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.mddocs/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#
- Every ingestion must carry canonical asset/provenance metadata.
- Validation and classification gates must be deterministic and policy-aware.
- Processing lifecycle transitions must be explicit and auditable.
- 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:
- Select file/media asset and provide domain context.
- Attach owner, source, classification, and checksum metadata.
- Submit ingestion envelope.
- Persist envelope and enqueue validation tasks.
- 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:
- Execute type/size/checksum checks.
- Evaluate policy and classification constraints.
- Record validation outcomes.
- Route pass/fail state to lifecycle orchestrator.
- 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:
- Transition state from queued to processing.
- Execute transformation/transcode/indexing tasks.
- Persist processing progress and artifact outputs.
- Mark ingestion state as ready.
- 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:
- Select recovery action (
retry,replay,rollback,manual_override). - Validate policy authorization for recovery action.
- Execute deterministic recovery path.
- Persist recovery evidence and state transition.
- 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:
- Collect envelope, validation, lifecycle, and recovery lineage.
- Apply retention/classification tags.
- Generate governance export package.
- Store export reference in compliance system.
- 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:
sizeBytesexceeds 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
ingestionIdor 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.startedfile_media_ingestion.journey.step.completedfile_media_ingestion.journey.blockedfile_media_ingestion.journey.recoveredfile_media_ingestion.journey.completed
Required dimensions:
ingestionId,assetRef,sourceDomain,classification,mimeTypeactorId,actorRole,recoveryAction,policyId,lifecycleStatejourneyId,stepId,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00187)#
OST-00187 is complete only when:
- At least five file/media ingestion journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.