Eve library

OSHUN Studio File and Media Ingestion Journeys and Edge Cases

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