# OSHUN Studio Data Retention and Lifecycle Controls Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Data Platform + OSHUN Security and
Compliance + OSHUN Web + OSHUN BFF  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0050-oshun-studio-data-retention-and-lifecycle-controls.md`

## Purpose

Define dependencies and canonical contracts for Studio data retention and
lifecycle controls across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

This document is the execution artifact for `OST-00298`.

## Sources Used

- `docs/adr/ADR-0050-oshun-studio-data-retention-and-lifecycle-controls.md`
- `docs/adr/ADR-0029-oshun-studio-audit-and-compliance-surfaces.md`
- `docs/releases/v1/specs/studio-audit-and-compliance-surfaces-dependency-and-data-contract-map.md`
- `apps/oshun/web/src/components/studio/StudioAuditComplianceSurfacesWorkspace.tsx`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `docs/releases/v1/runbooks/on-call-runbook.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Retention/lifecycle UX surfaces**: Studio retention policy, legal-hold, and
  purge workspaces in `apps/oshun/web/src/components/studio`.
- **Retention policy authority**: BFF policy APIs and data platform policy
  registry.
- **Lifecycle state orchestrator**: workflow services for archival, hold,
  restore, and purge transitions.
- **Compliance and legal governance**: approval flows for legal hold and purge
  exceptions.
- **Telemetry and audit continuity**: analytics/event sinks with retention
  evidence export.

### 1.2 Domain Dependency Graph

- `Retention/Lifecycle Controls -> Yemaya`: asset and content lineage retention
  with policy-tagged archival tiers.
- `Retention/Lifecycle Controls -> Isis`: generation artifacts and workflow
  traces with purge-safe dependency handling.
- `Retention/Lifecycle Controls -> Hathor`: narrative/research evidence windows
  and legal-hold overrides.
- `Retention/Lifecycle Controls -> Aja`: timeline/media session records with
  lifecycle evidence continuity.
- `Retention/Lifecycle Controls -> Bellona`: runtime and release governance
  records requiring deterministic retention and purge auditability.
- `Project Obsidian -> all`: policy baselines, exception governance, and
  cross-domain retention harmonization.

## 2. Ownership and Contract Matrix

| Area                                       | Owner                         | Consumers                      | Artifact                 | Contract                             |
| ------------------------------------------ | ----------------------------- | ------------------------------ | ------------------------ | ------------------------------------ |
| Retention policy definition and versioning | Data Platform + Compliance    | Web + BFF + Security           | Retention policy payload | `StudioRetentionPolicyDefinition`    |
| Dataset/artifact lifecycle registry        | BFF + Data Platform           | Domain surfaces + operations   | Lifecycle state payload  | `StudioRetentionLifecycleRecord`     |
| Legal hold and release workflow            | Compliance + Legal + Security | Operators + incident command   | Legal-hold payload       | `StudioLegalHoldRecord`              |
| Purge planning and execution evidence      | Data Platform + SRE           | Governance + compliance review | Purge execution payload  | `StudioRetentionPurgeExecution`      |
| Retention telemetry and audit export       | Data Platform + Security      | Governance + reporting         | Audit/telemetry payload  | `StudioRetentionLifecycleAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioRetentionPolicyDefinition

```ts
export interface StudioRetentionPolicyDefinition {
  policyId: string;
  policyVersion: string;
  dataClass:
    | 'audit_evidence'
    | 'workflow_event'
    | 'artifact_manifest'
    | 'incident_record'
    | 'runtime_signal';
  retentionDays: number;
  archivalTier: 'hot' | 'warm' | 'cold';
  legalHoldSupported: boolean;
  purgeApprovalTier: 'baseline' | 'sensitive' | 'restricted';
  ownerTeam: string;
}
```

### 3.2 StudioRetentionLifecycleRecord

```ts
export interface StudioRetentionLifecycleRecord {
  lifecycleId: string;
  datasetId: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  policyId: string;
  lifecycleState:
    | 'active'
    | 'archived'
    | 'legal_hold'
    | 'purge_pending'
    | 'purged';
  nextActionAt: string;
  updatedAt: string;
}
```

### 3.3 StudioLegalHoldRecord

```ts
export interface StudioLegalHoldRecord {
  holdId: string;
  datasetId: string;
  policyId: string;
  status: 'active' | 'released' | 'expired';
  requestedBy: string;
  approvedBy: string;
  reason: string;
  expiresAt?: string;
  updatedAt: string;
}
```

### 3.4 StudioRetentionPurgeExecution

```ts
export interface StudioRetentionPurgeExecution {
  executionId: string;
  policyId: string;
  datasetCount: number;
  mode: 'dry_run' | 'execute';
  status: 'pending' | 'running' | 'success' | 'failed';
  deletedCount: number;
  residualCount: number;
  startedAt: string;
  completedAt?: string;
}
```

### 3.5 StudioRetentionLifecycleAuditEvent

```ts
export interface StudioRetentionLifecycleAuditEvent {
  eventId: string;
  action:
    | 'retention.policy.upsert'
    | 'retention.lifecycle.transition'
    | 'retention.legal_hold.apply'
    | 'retention.legal_hold.release'
    | 'retention.purge.execute';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  actorId: string;
  actorRole: string;
  datasetId?: string;
  policyId: string;
  reasonCode?: string;
  traceId: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Retention policy writes must reject non-positive retention windows and invalid
  archival tiers.
- Lifecycle transitions must be validated against allowed state transitions and
  policy-tier requirements.
- Legal hold release must be denied while linked investigations are unresolved.
- Purge execution must always emit scope and residue metrics for verification.
- Telemetry/audit payloads must include actor, policy, trace, and outcome
  fields.

## 5. Acceptance Criteria (OST-00298)

`OST-00298` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for retention policy definition, lifecycle record, legal hold,
   purge execution, and retention lifecycle audit events are documented.
4. Ownership boundaries and validation rules are explicit.
