Eve library

OSHUN Studio File and Media Ingestion Dependency and Data Contract Map

Spec

Revision 1

On this page

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.