# ADR-0037: OSHUN Studio Asset Preview Pipeline

**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 deterministic asset preview generation and delivery for files,
media, models, and timeline artifacts before promotion. Current preview behavior
is fragmented and inconsistent, reducing trust in review decisions.

Without a canonical preview pipeline, OSHUN risks:

- inconsistent preview fidelity across domains
- delayed review/approval cycles from missing or stale previews
- security/compliance gaps in preview handling for sensitive assets
- duplicated preview tooling and weak operational visibility

## Decision Drivers

- **Fidelity**: previews must represent source assets accurately.
- **Determinism**: preview generation states and outputs must be predictable.
- **Security**: preview rendering must enforce classification and policy bounds.
- **Interoperability**: one preview model across Yemaya/Isis/Hathor/Aja/Bellona.
- **Operability**: failures and fallback paths must be explicit and recoverable.

## Considered Options

### Option 1: Domain-Specific Preview Implementations

Allow each domain to own custom preview generation behavior.

**Pros**:

- Fast local optimization for asset-specific scenarios.

**Cons**:

- Inconsistent UX and governance behavior.
- Expensive cross-domain maintenance overhead.

### Option 2: Third-Party Preview Services Only

Rely exclusively on external rendering/preview providers.

**Pros**:

- Lower direct implementation burden in Studio.

**Cons**:

- Reduced control over deterministic lifecycle and policy requirements.
- Limited integration with Studio audit/governance contracts.

### Option 3: Canonical Studio Preview Pipeline Contracts (Chosen)

Adopt a shared preview pipeline with typed preview requests, rendering lifecycle
contracts, fallback semantics, and audit/governance evidence contracts.

**Pros**:

- Consistent preview behavior and operator trust.
- Strong policy/compliance controls with deterministic observability.
- Better cross-domain decision velocity and quality.

**Cons**:

- Requires coordinated schema and preview capability governance.

## Decision Outcome

**Chosen option**: Option 3.

Preview pipeline requirements:

1. **Canonical preview request envelope** with asset, viewer, and policy
   context.
2. **Rendering lifecycle contract** for queued/rendering/ready/failed states.
3. **Fidelity and fallback contract** for deterministic degradation behavior.
4. **Cache and invalidation contract** to prevent stale preview delivery.
5. **Audit and governance contract** for retention and policy evidence.

## Normative Rules

### Canonical Preview Request Contract

- Every request must include `previewId`, `assetRef`, `requestorId`,
  `requestedAt`, and `classification`.
- Viewer context and target preview profile must be explicit.
- Invalid requests must be rejected before rendering.

### Rendering Lifecycle Contract

- Lifecycle states are constrained to `queued`, `rendering`, `ready`, and
  `failed`.
- State transitions must remain deterministic and auditable.
- Render failures must preserve diagnostics and recovery actions.

### Fidelity and Fallback Contract

- Preview fidelity profiles must be explicit and versioned.
- Fallback rendering must be deterministic and policy-compliant.
- Fallback use must emit explicit degraded-fidelity telemetry.

### Cache and Invalidation Contract

- Preview cache keys must include asset revision and profile context.
- Invalidation must trigger on upstream asset/version changes.
- Stale preview delivery is prohibited for production release gates.

### Audit and Governance Contract

- Preview lifecycle, fallback, and policy decisions must emit audit events.
- Governance exports must include preview lineage and fidelity metadata.
- Missing audit events must trigger degraded-observability warnings.

### Release Validity Contract

An asset preview pipeline release is valid only when all are true:

- preview request schema validation passes
- rendering lifecycle tests pass
- fidelity/fallback determinism tests pass
- cache invalidation tests pass
- telemetry/audit integrity checks pass
- rollback and ownership handoff are documented

## Architecture Implications

- Studio surfaces share one preview request and lifecycle model.
- BFF orchestrates preview rendering with policy guardrails.
- Domain adapters provide asset-type specific preview transformations.
- Analytics pipelines measure preview latency, fallback rate, and failures.

## Acceptance Criteria (OST-00193)

`OST-00193` is complete only when:

1. ADR exists at `docs/adr/ADR-0043-oshun-studio-asset-preview-pipeline.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines request envelope, rendering lifecycle, fidelity/fallback,
   cache/invalidation, audit/governance, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0036`, especially `ADR-0012`,
   `ADR-0036`, 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

- More reliable, consistent, and policy-compliant asset preview experience.
- Faster review cycles with higher decision confidence.
- Improved operational visibility for preview health and drift.

### Negative

- Increased complexity in preview rendering orchestration.
- Requires sustained governance around profile/version compatibility.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0042-oshun-studio-file-and-media-ingestion.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`