Eve library

OSHUN Studio Data Retention and Lifecycle Controls Journeys and Edge Cases

Spec

Revision 1

On this page

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.

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.
  • Trigger: hold request has no investigation/legal case id.
  • Required behavior: deny hold apply and emit hold-context error.
  • Trigger: hold release requested without authorized reviewer.
  • Required behavior: deny release and preserve active hold state.
  • 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.