# OSHUN Studio File and Media Ingestion Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0036-oshun-studio-file-and-media-ingestion.md`

## Purpose

Define dependencies and canonical contracts for Studio file and media ingestion
capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0036-oshun-studio-file-and-media-ingestion.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `docs/releases/v1/design/ux-principles.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

- **Ingestion UI surfaces**: Studio file/media ingestion modules in
  `apps/oshun/web/src/components/studio`.
- **Ingestion persistence and processing services**: BFF ingestion APIs and
  processing orchestrators.
- **Asset classification and validation adapters**: type/size/checksum/policy
  validation services.
- **Storage and transformation pipelines**: media staging, transcoding, and
  metadata extraction.
- **Telemetry and governance evidence pipelines**: analytics + compliance
  retention/export systems.

### 1.2 Domain Dependency Graph

- `File/Media Ingestion -> Yemaya`: release assets and orchestration bundles.
- `File/Media Ingestion -> Isis`: model artifacts, datasets, and lineage packs.
- `File/Media Ingestion -> Hathor`: narrative assets and worldbuilding media.
- `File/Media Ingestion -> Aja`: timeline media, sequences, and cuts.
- `File/Media Ingestion -> Bellona`: runtime artifacts and incident evidence.
- `Project Obsidian -> all`: cross-domain franchise asset ingestion governance.

## 2. Ownership and Contract Matrix

| Area                               | Owner                    | Consumers                      | Artifact              | Contract                    |
| ---------------------------------- | ------------------------ | ------------------------------ | --------------------- | --------------------------- |
| Canonical ingestion envelope       | BFF + Domain Integrators | Studio operators and pipelines | Ingestion payload     | `StudioIngestionEnvelope`   |
| Validation gate and classification | Security + Compliance    | Ingestion services + operators | Validation payload    | `StudioIngestionValidation` |
| Processing lifecycle state         | BFF + Platform SRE       | Studio surfaces + pipelines    | Lifecycle payload     | `StudioIngestionLifecycle`  |
| Retry and recovery actions         | Platform SRE + Program   | Operators + reliability teams  | Recovery payload      | `StudioIngestionRecovery`   |
| Audit and governance evidence      | Data Platform + Security | Compliance + governance        | Telemetry/audit event | `StudioIngestionAuditEvent` |

## 3. Canonical Contracts

### 3.1 StudioIngestionEnvelope

```ts
export interface StudioIngestionEnvelope {
  ingestionId: string;
  assetRef: string;
  sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  ownerId: string;
  submittedBy: string;
  mimeType: string;
  sizeBytes: number;
  checksum: string;
  classification: 'public' | 'internal' | 'restricted' | 'confidential';
  submittedAt: string;
}
```

### 3.2 StudioIngestionValidation

```ts
export interface StudioIngestionValidation {
  validationId: string;
  ingestionId: string;
  checks: Array<'type' | 'size' | 'checksum' | 'policy' | 'classification'>;
  status: 'passed' | 'failed';
  failureCode?: string;
  validatedAt: string;
}
```

### 3.3 StudioIngestionLifecycle

```ts
export interface StudioIngestionLifecycle {
  lifecycleId: string;
  ingestionId: string;
  state: 'queued' | 'processing' | 'ready' | 'failed';
  progressPercent: number;
  artifactUrl?: string;
  updatedAt: string;
}
```

### 3.4 StudioIngestionRecovery

```ts
export interface StudioIngestionRecovery {
  recoveryId: string;
  ingestionId: string;
  action: 'retry' | 'replay' | 'rollback' | 'manual_override';
  actorId: string;
  policyId: string;
  reason: string;
  occurredAt: string;
}
```

### 3.5 StudioIngestionAuditEvent

```ts
export interface StudioIngestionAuditEvent {
  eventId: string;
  action:
    | 'ingestion.submitted'
    | 'ingestion.validated'
    | 'ingestion.state_transitioned'
    | 'ingestion.recovered'
    | 'ingestion.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  ingestionId?: string;
  lifecycleId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Ingestion envelopes missing identity, owner, or classification fields must be
  rejected.
- Validation checks must include type, size, checksum, and policy outcomes.
- Lifecycle transitions must remain deterministic and auditable.
- Recovery actions must be policy-gated and preserve ingestion lineage.
- Audit events must capture submit/validate/lifecycle/recovery outcomes end to
  end.

## 5. Acceptance Criteria (OST-00186)

`OST-00186` 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 ingestion envelope, validation, lifecycle, recovery, and audit
   events are documented.
4. Ownership boundaries and validation rules are explicit.
