# OSHUN Studio Data Retention and Lifecycle Controls Journeys and Edge Cases

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.md`
- `docs/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

1. Retention policy binding must be explicit, versioned, and auditable.
2. Lifecycle transitions must be deterministic and reason-coded.
3. Legal-hold and exception controls must preserve compliance integrity.
4. 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**:

1. Select data class and source-domain coverage.
2. Define retention window, archival tier, and legal-hold capability.
3. Define purge approval tier and owner metadata.
4. Validate policy schema and compatibility constraints.
5. 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**:

1. Select dataset/artifact with domain lineage metadata.
2. Bind dataset to active retention policy version.
3. Validate transition preconditions (`active -> archived -> purge_pending`).
4. Apply transition with actor/tier reason code.
5. 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**:

1. Validate hold request context (case, approver, scope).
2. Apply legal hold and suspend purge progression.
3. Persist hold evidence with approver identity and timestamp.
4. Revalidate release conditions for hold removal.
5. 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**:

1. Run dry-run purge scope validation and impact preview.
2. Validate role/tier/approval prerequisites for destructive action.
3. Execute purge job and monitor progress/residual metrics.
4. Verify deletion evidence and unresolved residue.
5. 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**:

1. Correlate policy, lifecycle, hold, and purge failure signals.
2. Apply mitigation (policy rollback, hold repair, purge retry, dataset
   restoration).
3. Re-run retention and purge verification suite.
4. Confirm telemetry/audit continuity restoration.
5. 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 `retentionDays` or 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_pending` without 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_hold` enters 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.started`
- `retention_lifecycle.journey.step.completed`
- `retention_lifecycle.journey.blocked`
- `retention_lifecycle.journey.purge.executed`
- `retention_lifecycle.journey.recovered`
- `retention_lifecycle.journey.completed`

Required dimensions:

- `policyId`, `policyVersion`, `dataClass`, `retentionDays`, `archivalTier`
- `datasetId`, `sourceDomain`, `lifecycleState`, `legalHoldStatus`, `purgeMode`
- `executionId`, `deletedCount`, `residualCount`, `verificationState`
- `actorId`, `actorRole`, `permissionTier`, `releaseChannel`, `approvalTicket`
- `journeyId`, `stepId`, `outcome`, `reasonCode`, `latencyMs`, `traceId`

## 5. Acceptance Criteria (OST-00299)

`OST-00299` is complete only when:

1. At least five retention/lifecycle journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
