Status: Active
Owner: OSHUN Studio Architecture + OSHUN Data Platform + OSHUN Security and
Compliance + OSHUN Web + OSHUN BFF + Platform SRE
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0050-oshun-studio-data-retention-and-lifecycle-controls.mddocs/releases/v1/specs/studio-data-retention-and-lifecycle-controls-dependency-and-data-contract-map.md
Purpose#
Define primary journeys and deterministic edge-case behavior for Studio data retention and lifecycle controls.
This document is the execution artifact for OST-00299.
Personas#
- Data Retention Operator
- Compliance Auditor
- Security Reviewer
- Platform SRE Incident Commander
- Domain Integration Engineer
Journey Principles#
- Retention policy binding must be explicit, versioned, and auditable.
- Lifecycle transitions must be deterministic and reason-coded.
- Legal-hold and exception controls must preserve compliance integrity.
- Purge execution must be safe, verifiable, and operationally observable.
1. Primary Journeys#
J1. Define and Publish Retention Policy Baseline#
Goal: Establish policy definitions for retention class, windows, archival tiers, and approval requirements.
Entry: Retention/lifecycle workspace
Steps:
- Select data class and source-domain coverage.
- Define retention window, archival tier, and legal-hold capability.
- Define purge approval tier and owner metadata.
- Validate policy schema and compatibility constraints.
- Publish policy version and emit governance audit event.
Success State:
- Policy baseline is versioned, valid, and available for lifecycle operations.
J2. Bind Dataset to Policy and Manage Lifecycle State#
Goal: Assign governed datasets to retention policy and advance lifecycle state through approved transitions.
Entry: Policy baseline published
Steps:
- Select dataset/artifact with domain lineage metadata.
- Bind dataset to active retention policy version.
- Validate transition preconditions (
active -> archived -> purge_pending). - Apply transition with actor/tier reason code.
- Emit lifecycle transition telemetry and audit event.
Success State:
- Dataset lifecycle state is policy-compliant and traceable.
J3. Apply and Release Legal Hold#
Goal: Preserve governed data while investigations, legal requests, or compliance reviews are active.
Entry: Legal/compliance hold request
Steps:
- Validate hold request context (case, approver, scope).
- Apply legal hold and suspend purge progression.
- Persist hold evidence with approver identity and timestamp.
- Revalidate release conditions for hold removal.
- Release hold and resume lifecycle orchestration when approved.
Success State:
- Hold lifecycle is enforced without violating retention/purge controls.
J4. Execute Purge Plan and Verify Completion#
Goal: Purge datasets whose retention windows are complete while preserving evidence and safety controls.
Entry: Datasets in purge_pending
Steps:
- Run dry-run purge scope validation and impact preview.
- Validate role/tier/approval prerequisites for destructive action.
- Execute purge job and monitor progress/residual metrics.
- Verify deletion evidence and unresolved residue.
- Emit purge completion telemetry/audit and update lifecycle state to
purged.
Success State:
- Purge executes deterministically with complete verification evidence.
J5. Recover Retention Incident and Close#
Goal: Restore retention/lifecycle integrity after policy drift, hold-state errors, or purge failures.
Entry: Open retention incident
Steps:
- Correlate policy, lifecycle, hold, and purge failure signals.
- Apply mitigation (policy rollback, hold repair, purge retry, dataset restoration).
- Re-run retention and purge verification suite.
- Confirm telemetry/audit continuity restoration.
- Close incident with post-recovery evidence package.
Success State:
- Retention governance integrity is restored with validated evidence.
2. Critical Edge Cases#
E1. Policy Publish Without Retention Window#
- Trigger: policy update omits
retentionDaysor sets non-positive value. - Required behavior: reject publish with policy-schema reason code.
E2. Unsupported Data Class Binding#
- Trigger: dataset attempts to bind to unknown data class.
- Required behavior: deny binding and emit classification error.
E3. Illegal Lifecycle Transition#
- Trigger: transition attempts
active -> purge_pendingwithout archival policy allowance. - Required behavior: block transition and return deterministic lifecycle transition reason.
E4. Missing Dataset Ownership Metadata#
- Trigger: lifecycle action submitted without owner/domain lineage fields.
- Required behavior: reject transition and require ownership metadata.
E5. Legal Hold Apply Without Case Reference#
- Trigger: hold request has no investigation/legal case id.
- Required behavior: deny hold apply and emit hold-context error.
E6. Legal Hold Release Without Approval#
- Trigger: hold release requested without authorized reviewer.
- Required behavior: deny release and preserve active hold state.
E7. Purge Execution While Legal Hold Active#
- Trigger: dataset in
legal_holdenters purge execution. - Required behavior: hard deny purge and emit hold-protection reason code.
E8. Purge Request Without Required Tier/Approval#
- Trigger: operator lacks required permission tier or production approval evidence.
- Required behavior: deny purge and emit policy-denial audit event.
E9. Purge Completes with Residual Records#
- Trigger: purge run reports non-zero residual count.
- Required behavior: mark partial-failure state and open retention incident.
E10. Telemetry or Audit Sink Degradation#
- Trigger: lifecycle/purge action executes but telemetry/audit write fails.
- Required behavior: enter degraded-observability mode and block production lifecycle promotions.
3. Journey-to-Surface Mapping#
| Journey | Primary Surface | Supporting Surfaces |
|---|---|---|
| J1 Define Retention Policy Baseline | Policy definition panel | Policy registry + schema validation services |
| J2 Bind Dataset and Manage Lifecycle | Lifecycle state orchestration | BFF lifecycle APIs + domain lineage services |
| J3 Apply/Release Legal Hold | Legal hold governance panel | Compliance workflows + approval controls |
| J4 Execute Purge and Verify | Purge execution and status pane | Data platform purge workers + residue verification |
| J5 Recover Retention Incident | Retention incident panel | On-call dashboards + runbook orchestration and retry |
4. Instrumentation Requirements#
Required events:
retention_lifecycle.journey.startedretention_lifecycle.journey.step.completedretention_lifecycle.journey.blockedretention_lifecycle.journey.purge.executedretention_lifecycle.journey.recoveredretention_lifecycle.journey.completed
Required dimensions:
policyId,policyVersion,dataClass,retentionDays,archivalTierdatasetId,sourceDomain,lifecycleState,legalHoldStatus,purgeModeexecutionId,deletedCount,residualCount,verificationStateactorId,actorRole,permissionTier,releaseChannel,approvalTicketjourneyId,stepId,outcome,reasonCode,latencyMs,traceId
5. Acceptance Criteria (OST-00299)#
OST-00299 is complete only when:
- At least five retention/lifecycle journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.