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.mddocs/adr/ADR-0036-oshun-studio-file-and-media-ingestion.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for ingestion envelope, validation, lifecycle, recovery, and audit events are documented.
- Ownership boundaries and validation rules are explicit.