9.9 KiB
Lifecycle Governance Standard
Canonical taxonomy for lifecycle-sensitive TenantPilot work. This standard governs naming, source ownership, transition safeguards, and follow-up boundaries before runtime lifecycle flows are implemented.
Last reviewed: 2026-05-01
Governing Principle
Lifecycle meanings stay orthogonal.
Do not reuse one lifecycle field, label, badge, or status as a proxy for another lifecycle dimension.
The machine-readable source for Spec 262 is specs/262-lifecycle-governance-taxonomy/contracts/lifecycle-governance-taxonomy.yaml; this document is the reviewer-facing standard that future lifecycle specs must cite.
This v1 standard introduces no application behavior, migration, lifecycle service, provider rollout, panel surface, or purge/delete/export runtime flow.
Canonical Dimensions
Every lifecycle concern must map to exactly one primary dimension.
| Dimension | Answers | Current repo-real authorities | Current repo-real values | Reserved follow-up values | Must not proxy |
|---|---|---|---|---|---|
| Local record lifecycle | Is a TenantPilot-owned record active, onboarding, archived, removed, or purged locally? | specs/143-tenant-lifecycle-operability-context-semantics/spec.md, specs/091-backupschedule-retention-lifecycle/spec.md, apps/platform/app/Models/Tenant.php |
tenant.draft, tenant.onboarding, tenant.active, tenant.archived, backup_schedule.active, backup_schedule.archived, backup_schedule.force_deleted |
locally_removed, local_purge_scheduled, locally_purged |
Provider presence, commercial state, retention expiry |
| Provider presence lifecycle | Is a managed object observed in the supported provider-backed result set? | specs/261-provider-missing-policy-visibility/spec.md, apps/platform/app/Models/Policy.php |
present, provider_missing |
provider_deleted, provider_reappeared |
Local deletion, local suppression, restoreability |
| Operator suppression lifecycle | Did an operator intentionally hide or restore local visibility? | specs/261-provider-missing-policy-visibility/spec.md, apps/platform/app/Models/Policy.php |
visible, ignored, restored_to_visibility |
scoped_suppression_reason_families |
Provider missing, retention, commercial state |
| Commercial/workspace lifecycle | What commercial posture controls workspace expansion and read-only behavior? | specs/251-commercial-entitlements-billing-state/spec.md |
trial, active_paid, grace, suspended_read_only |
closed |
Tenant archive, provider missing, purge due |
| Retention/compliance lifecycle | What must be retained, exported, held, deleted, or purged? | apps/platform/app/Models/ReviewPack.php, apps/platform/app/Console/Commands/PruneReviewPacksCommand.php, apps/platform/config/tenantpilot.php |
review_pack.expired, configured_retention_days |
retained, export_requested, deletion_requested, deletion_scheduled, legal_hold, purge_due, purged |
Workspace suspension, local archive, provider missing |
| Restoreability lifecycle | Is historical backup or evidence truth still restorable? | specs/261-provider-missing-policy-visibility/spec.md, apps/platform/app/Models/BackupSet.php, apps/platform/app/Models/RestoreRun.php |
historical_restore_continuity_available |
metadata_only, blocked_by_dependency, not_restorable, expired_by_retention |
Provider presence, commercial state, local suppression |
Rules:
- Use current repo-real values only when the repo already owns that meaning.
- Use reserved follow-up values only to name later specs; do not render, persist, or enforce them in this slice.
- If a concern seems to belong to multiple dimensions, choose the dimension that owns the operator consequence and document the secondary relationship as context only.
Mandatory Meaning Answers
Deleted
Deleted is not a shared lifecycle state.
Local removal, provider hard deletion, retention purge, and reduced restoreability are separate lifecycle meanings.
- Local deletion belongs to local record lifecycle and requires an explicit runtime follow-up before it can exist beyond current archive/force-delete patterns.
- Provider hard deletion belongs to provider presence lifecycle and remains provider-owned evidence.
- Purge belongs to retention/compliance lifecycle.
- Not restorable belongs to restoreability lifecycle.
Missing From Provider
Provider missing means the managed object is not observed in the supported provider-backed result set.
It does not mean the local record was deleted, ignored, purged, or no longer historically restorable.
Ignored
Ignored means intentional local operator suppression.
It does not mean the provider object disappeared, the workspace is suspended, or the record is retention-expired.
Workspace Suspension Or Closure
Suspended read-only is commercial/workspace lifecycle.
It does not delete tenants, purge data, expire evidence, or eliminate restoreability.
Closed is reserved for Workspace & Tenant Closure Lifecycle v1; this standard only names the boundary.
Export Before Deletion
export_requested is a reserved retention/compliance lifecycle value.
The actual export workflow, export contents, customer ownership, and completion proof belong to Data Export Before Deletion v1.
Retained Versus Purgeable
Retained, legal hold, purge due, and purged are retention/compliance lifecycle meanings. They must not be inferred from workspace suspension, local archive, provider missing, or restoreability status.
Restore Eligibility
Restoreability is about whether historical backup or evidence truth remains restorable. It remains distinct from current provider presence: a live provider object can be missing while a historical backup remains restorable, and a present provider object does not prove historical restoreability.
Transition Governance
Future runtime specs must use this matrix before implementing a lifecycle transition.
| Dimension | Example transition | Transition owner | Execution path | Confirmation | Audit evidence | OperationRun | Export / retention preconditions |
|---|---|---|---|---|---|---|---|
| Local record lifecycle | Archive a local record or force-delete a backup schedule | TenantPilot local domain owner | Direct local mutation for bounded DB-only archive; shared OperationRun when long-running, cross-resource, or externally mediated |
Always | Required | Sometimes | Required before irreversible deletion |
| Provider presence lifecycle | Mark provider missing or reappeared | Provider observation / sync process | Observation-derived update; no operator confirmation | Never | Required | Never unless part of broader reconciliation run | Not required |
| Operator suppression lifecycle | Ignore or restore local visibility | TenantPilot local domain owner | Direct local mutation | Always | Required | Never | Not required |
| Commercial/workspace lifecycle | Suspend read-only or close workspace | Platform workspace/commercial owner | Direct local mutation for bounded state change; shared OperationRun for closure-class or multi-artifact flows |
Always | Required | Sometimes | Required for closure-class flows |
| Retention/compliance lifecycle | Mark export requested, deletion requested, hold, purge due, or purge | Compliance/retention owner | Shared OperationRun for purge-class automation and any long-running/export-coupled flow |
Always | Required | Always for purge-class automation | Required |
| Restoreability lifecycle | Mark metadata-only or expired by retention | Backup/restore/evidence owner | Derived status when passive; shared OperationRun or guarded mutation when an operator reduces restoreability |
Sometimes | Required | Sometimes | Required when retention or irreversible reduction is involved |
Audit-only is insufficient when the transition is destructive, long-running, externally mediated, cross-resource, export-coupled, purge-class, or materially reduces restoreability. Those slices must reuse the shared OperationRun start and completion UX path instead of composing local queued toast, link, event, or terminal-notification behavior.
Follow-Up Boundaries
Spec 262 deliberately does not implement these runtime slices:
| Follow-up slice | Boundary |
|---|---|
Provider-Missing Managed Object Truth v1 |
Broader provider-presence rollout beyond policy records |
Workspace & Tenant Closure Lifecycle v1 |
Workspace or tenant close/remove behavior, including closure-specific UX and authorization |
Data Export Before Deletion v1 |
Customer-owned export workflow that fulfills export_requested before irreversible deletion |
Retention & Purge Governance v1 |
Retention periods, holds, purge eligibility, irreversible deletion, and purge proof |
Restoreability Expiry & Evidence Retention v1 |
Distinction between retained evidence and restorable payloads |
If a future spec needs one of these behaviors, it must cite this standard and implement the dedicated follow-up slice instead of expanding Spec 262 retroactively.
Review Checklist
Lifecycle-bearing specs and PRs must answer these questions:
- Which one lifecycle dimension owns the changed meaning?
- What current repo-real source owns that meaning today?
- Is the value current repo-real or reserved follow-up?
- Which dimensions are explicitly forbidden as proxies?
- Does the transition require confirmation, audit evidence, shared
OperationRunexecution, export-before-delete, or retention review? - Does lifecycle state remain separate from RBAC, workspace entitlement, tenant entitlement, and deny-as-not-found behavior?
- Does provider-specific evidence stay at a provider-owned seam instead of becoming platform-core truth?
- Is any adjacent lifecycle runtime work split into a named follow-up slice?
A change fails review if it uses lifecycle language as an authorization substitute, collapses provider absence into local deletion, treats suppression as provider truth, infers retention from commercial state, or claims restoreability from current provider presence alone.