# OSHUN Studio File and Media Ingestion Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-file-and-media-ingestion-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio
file/media ingestion workflows.

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

## Personas

- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Compliance Auditor

## Journey Principles

1. Every ingestion must carry canonical asset/provenance metadata.
2. Validation and classification gates must be deterministic and policy-aware.
3. Processing lifecycle transitions must be explicit and auditable.
4. Recovery actions must preserve lineage and idempotency semantics.

## 1. Primary Journeys

### J1. Submit Ingestion Envelope

**Goal**: Register file/media asset with canonical metadata and provenance.

**Entry**: `Studio file/media ingestion workspace`

**Steps**:

1. Select file/media asset and provide domain context.
2. Attach owner, source, classification, and checksum metadata.
3. Submit ingestion envelope.
4. Persist envelope and enqueue validation tasks.
5. Emit ingestion submission audit event.

**Success State**:

- Ingestion envelope is persisted with complete metadata and provenance context.

### J2. Execute Validation Gate

**Goal**: Run deterministic validation checks before processing.

**Entry**: `Queued ingestion envelope`

**Steps**:

1. Execute type/size/checksum checks.
2. Evaluate policy and classification constraints.
3. Record validation outcomes.
4. Route pass/fail state to lifecycle orchestrator.
5. Emit validation lifecycle event.

**Success State**:

- Validation outcomes are deterministic and attributable.

### J3. Run Processing Lifecycle

**Goal**: Process validated asset into ready state.

**Entry**: `Validation passed ingestion`

**Steps**:

1. Transition state from queued to processing.
2. Execute transformation/transcode/indexing tasks.
3. Persist processing progress and artifact outputs.
4. Mark ingestion state as ready.
5. Emit processing completion event.

**Success State**:

- Asset is ready with deterministic lifecycle history.

### J4. Recover Failed Ingestion

**Goal**: Recover failed ingestion via retry/replay workflows.

**Entry**: `Failed ingestion lifecycle state`

**Steps**:

1. Select recovery action (`retry`, `replay`, `rollback`, `manual_override`).
2. Validate policy authorization for recovery action.
3. Execute deterministic recovery path.
4. Persist recovery evidence and state transition.
5. Emit recovery lifecycle event.

**Success State**:

- Recovery action completes with preserved ingestion lineage.

### J5. Export Governance Evidence

**Goal**: Produce governance-ready ingestion evidence package.

**Entry**: `Ready or recovered ingestion set`

**Steps**:

1. Collect envelope, validation, lifecycle, and recovery lineage.
2. Apply retention/classification tags.
3. Generate governance export package.
4. Store export reference in compliance system.
5. Emit governance export audit event.

**Success State**:

- Governance export is complete, attributable, and retention-ready.

## 2. Critical Edge Cases

### E1. Missing Asset Reference

- Trigger: submission payload missing `assetRef`.
- Required behavior: reject ingestion and emit validation error.

### E2. Invalid Classification Tag

- Trigger: unrecognized classification value submitted.
- Required behavior: reject envelope and require valid classification.

### E3. Unsupported MIME Type

- Trigger: file type outside allowed ingestion profile.
- Required behavior: block validation and emit policy-denied event.

### E4. Size Limit Exceeded

- Trigger: `sizeBytes` exceeds configured ingestion threshold.
- Required behavior: fail validation and provide deterministic error code.

### E5. Checksum Mismatch

- Trigger: reported checksum does not match computed checksum.
- Required behavior: fail validation and quarantine ingestion payload.

### E6. Non-Deterministic Lifecycle Transition

- Trigger: identical ingestion enters conflicting lifecycle states.
- Required behavior: block promotion and open lifecycle-integrity incident.

### E7. Retry Without Original Envelope Identity

- Trigger: retry action mutates `ingestionId` or provenance lineage.
- Required behavior: deny retry and flag idempotency integrity violation.

### E8. Unauthorized Manual Override

- Trigger: unprivileged actor triggers `manual_override`.
- Required behavior: deny action and emit policy-denied audit event.

### E9. Governance Export Missing Retention Tags

- Trigger: export package missing required retention/classification tags.
- Required behavior: block export and surface governance contract error.

### E10. Ingestion Audit Emission Failure

- Trigger: ingestion lifecycle events fail to emit.
- Required behavior: buffer/retry and surface degraded observability warning.

## 3. Journey-to-Surface Mapping

| Journey                       | Primary Surface      | Supporting Surfaces             |
| ----------------------------- | -------------------- | ------------------------------- |
| J1 Submit Ingestion Envelope  | File/media ingestion | Domain asset adapters           |
| J2 Execute Validation Gate    | File/media ingestion | Validation and policy services  |
| J3 Run Processing Lifecycle   | File/media ingestion | Processing/transformation stack |
| J4 Recover Failed Ingestion   | File/media ingestion | Recovery and reliability stack  |
| J5 Export Governance Evidence | File/media ingestion | Compliance and retention stack  |

## 4. Instrumentation Requirements

Required events:

- `file_media_ingestion.journey.started`
- `file_media_ingestion.journey.step.completed`
- `file_media_ingestion.journey.blocked`
- `file_media_ingestion.journey.recovered`
- `file_media_ingestion.journey.completed`

Required dimensions:

- `ingestionId`, `assetRef`, `sourceDomain`, `classification`, `mimeType`
- `actorId`, `actorRole`, `recoveryAction`, `policyId`, `lifecycleState`
- `journeyId`, `stepId`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00187)

`OST-00187` is complete only when:

1. At least five file/media ingestion 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.
