# ADR-0036: OSHUN Studio File and Media Ingestion

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, OSHUN
Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio teams need a deterministic ingestion system for files and media assets
used across narrative, model, timeline, and runtime workflows. Current upload
and ingestion behavior is fragmented, creating inconsistent metadata quality and
non-uniform processing outcomes.

Without canonical ingestion workflows, OSHUN risks:

- inconsistent asset metadata and provenance lineage
- delayed pipeline execution from failed or duplicated ingestion
- security/compliance exposure from weak validation and classification
- cross-domain workflow drift when ingestion semantics differ

## Decision Drivers

- **Determinism**: ingestion states must transition predictably.
- **Integrity**: assets must preserve provenance and content fidelity.
- **Security**: validation, classification, and policy checks are mandatory.
- **Interoperability**: one ingestion model across
  Yemaya/Isis/Hathor/Aja/Bellona.
- **Operability**: ingestion failures require clear recovery and observability.

## Considered Options

### Option 1: Domain-Local Upload Pipelines

Let each domain define its own ingestion behavior.

**Pros**:

- Fast local development autonomy.

**Cons**:

- Inconsistent validation and metadata semantics.
- High integration overhead for cross-domain workflows.

### Option 2: External Ingestion Toolchain Only

Perform ingestion outside Studio and import references.

**Pros**:

- Lower Studio implementation footprint.

**Cons**:

- Weak in-product traceability and lifecycle control.
- Delayed incident detection and poor operator ergonomics.

### Option 3: Canonical Studio Ingestion Contracts (Chosen)

Adopt one policy-aware ingestion model with typed file envelopes, validation
gates, processing lifecycle states, and governance audit contracts.

**Pros**:

- Consistent ingestion behavior and metadata quality.
- Strong security/compliance posture and evidence continuity.
- Better downstream reliability for domain workflows.

**Cons**:

- Requires coordinated schema and policy governance.

## Decision Outcome

**Chosen option**: Option 3.

Ingestion requirements:

1. **Canonical ingestion envelope** with source, owner, and classification
   metadata.
2. **Validation gate contract** for type, size, integrity, and policy checks.
3. **Processing lifecycle contract** for queued/processing/ready/failed states.
4. **Recovery and retry contract** for deterministic replay and error handling.
5. **Audit and governance contract** for retention and compliance evidence.

## Normative Rules

### Canonical Ingestion Envelope Contract

- Every ingestion payload must include `ingestionId`, `assetRef`, `ownerId`,
  `sourceDomain`, and `submittedAt`.
- Classification and sensitivity tags must be attached before processing start.
- Invalid envelopes must be rejected before persistence.

### Validation Gate Contract

- Type, size, checksum, and policy validation must complete before processing.
- Validation failures must be explicit and attributable.
- Validation bypass is prohibited for production ingestion paths.

### Processing Lifecycle Contract

- Lifecycle states are constrained to `queued`, `processing`, `ready`, and
  `failed`.
- State transitions must be deterministic and auditable.
- Failed states must preserve diagnostic evidence and recovery options.

### Recovery and Retry Contract

- Retry attempts must preserve original envelope identity and provenance.
- Replay actions must be idempotent for identical ingestion IDs.
- Manual recovery actions must be policy-gated and audited.

### Audit and Governance Contract

- Ingestion lifecycle and policy events must emit structured audit records.
- Governance exports must include validation, lifecycle, and retry lineage.
- Missing audit events must trigger degraded-observability warnings.

### Release Validity Contract

A file/media ingestion release is valid only when all are true:

- ingestion envelope schema validation passes
- validation gate tests pass
- lifecycle transition and retry tests pass
- security/classification policy tests pass
- telemetry/audit integrity checks pass
- rollback and ownership handoff are documented

## Architecture Implications

- Studio surfaces share one ingestion envelope and lifecycle model.
- BFF persists ingestion state with validation and policy guardrails.
- Domain adapters attach domain-specific asset context to canonical envelopes.
- Analytics pipelines measure ingestion throughput, failure rates, and latency.

## Acceptance Criteria (OST-00185)

`OST-00185` is complete only when:

1. ADR exists at `docs/adr/ADR-0042-oshun-studio-file-and-media-ingestion.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines ingestion envelope, validation gate, lifecycle/retry,
   security/policy, audit/governance, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0035`, especially `ADR-0012`,
   `ADR-0022`, and `ADR-0035`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Reliable and consistent ingestion behavior across Studio domains.
- Improved security/compliance posture for media handling.
- Better downstream pipeline stability and observability.

### Negative

- Higher governance complexity for ingestion schemas and policies.
- Requires sustained validation and policy maintenance.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0028-oshun-studio-cross-domain-entity-model.md`
- `docs/adr/ADR-0041-oshun-studio-review-and-approval-workflows.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`