Disciplines · Decisions (ADRs)

ADR-0036: OSHUN Studio File and Media Ingestion

Studio teams need a deterministic ingestion system for files and media assets used across narrative, model, timeline, and runtime workflows.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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