# OSHUN Studio Asset Preview Pipeline Journeys and Edge Cases

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + OSHUN Security  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0037-oshun-studio-asset-preview-pipeline.md`
- `docs/releases/v1/specs/studio-asset-preview-pipeline-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio asset
preview pipeline workflows.

This document is the execution artifact for `OST-00195`.

## Personas

- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Compliance Auditor

## Journey Principles

1. Every preview request must bind to explicit asset revision and profile.
2. Rendering lifecycle transitions must be deterministic and auditable.
3. Fallback and cache invalidation behavior must be explicit and policy-aware.
4. Governance exports must preserve preview fidelity lineage.

## 1. Primary Journeys

### J1. Submit Preview Request

**Goal**: Request deterministic preview for target asset and profile.

**Entry**: `Studio asset preview workspace`

**Steps**:

1. Select asset reference and preview profile.
2. Attach revision, classification, and requestor context.
3. Submit canonical preview request envelope.
4. Persist request and enqueue rendering lifecycle.
5. Emit preview-request lifecycle event.

**Success State**:

- Preview request persists with complete context and deterministic queue state.

### J2. Render Preview Lifecycle

**Goal**: Execute preview rendering pipeline from queued to ready state.

**Entry**: `Queued preview request`

**Steps**:

1. Transition preview to rendering state.
2. Execute transform/render pipeline for requested profile.
3. Persist rendering progress and output metadata.
4. Mark preview state ready with output URL.
5. Emit rendering completion event.

**Success State**:

- Preview renders successfully with deterministic lifecycle trace.

### J3. Apply Fidelity Fallback

**Goal**: Provide deterministic fallback preview when requested profile fails.

**Entry**: `Render failure or unsupported profile condition`

**Steps**:

1. Detect unsupported/failed render profile.
2. Select deterministic fallback profile.
3. Render fallback output with policy checks.
4. Persist fallback reason and delivered profile metadata.
5. Emit fallback lifecycle and degraded-fidelity event.

**Success State**:

- Fallback preview is delivered with explicit fidelity lineage.

### J4. Invalidate and Refresh Preview Cache

**Goal**: Prevent stale preview delivery after asset changes.

**Entry**: `Asset revision change or policy invalidation signal`

**Steps**:

1. Detect asset revision drift against preview cache key.
2. Invalidate stale cache record.
3. Trigger refresh rendering for current revision.
4. Persist refreshed cache state and linkage metadata.
5. Emit cache invalidation and refresh events.

**Success State**:

- Preview cache reflects latest asset revision deterministically.

### J5. Export Preview Governance Evidence

**Goal**: Export preview lifecycle/fidelity evidence for compliance review.

**Entry**: `Ready preview set with lifecycle history`

**Steps**:

1. Collect request, lifecycle, fidelity, and cache events.
2. Attach classification/retention metadata.
3. Produce governance export package.
4. Persist export reference and audit markers.
5. Emit governance-export completion event.

**Success State**:

- Governance package is complete, attributable, and retention-ready.

## 2. Critical Edge Cases

### E1. Missing Asset Reference

- Trigger: preview request submitted without `assetRef`.
- Required behavior: reject request and emit validation error.

### E2. Unsupported Preview Profile

- Trigger: request includes profile not supported for asset type.
- Required behavior: fail initial profile render and route to deterministic
  fallback.

### E3. Classification Policy Violation

- Trigger: confidential asset preview requested by unauthorized role.
- Required behavior: deny request and emit policy-denied audit event.

### E4. Rendering Worker Timeout

- Trigger: rendering state exceeds timeout SLO threshold.
- Required behavior: fail lifecycle with deterministic timeout code.

### E5. Non-Deterministic Fallback Selection

- Trigger: repeated failures select different fallback profile for same input.
- Required behavior: block release and open fidelity determinism incident.

### E6. Stale Cache Delivery

- Trigger: preview cache serves outdated asset revision.
- Required behavior: invalidate cache and force refresh before delivery.

### E7. Cache Invalidation Without Reason

- Trigger: cache record invalidated without `invalidationReason`.
- Required behavior: reject invalidation write and require reason metadata.

### E8. Ready State Without Output URL

- Trigger: lifecycle enters ready state without preview output reference.
- Required behavior: reject transition and flag lifecycle integrity issue.

### E9. Governance Export Missing Fidelity Metadata

- Trigger: export package omits fallback/delivered profile lineage.
- Required behavior: block export and surface governance contract error.

### E10. Preview Audit Emission Failure

- Trigger: request/render/fallback/cache events fail emission.
- Required behavior: buffer/retry and surface degraded observability warning.

## 3. Journey-to-Surface Mapping

| Journey                         | Primary Surface        | Supporting Surfaces         |
| ------------------------------- | ---------------------- | --------------------------- |
| J1 Submit Preview Request       | Asset preview pipeline | Domain asset adapters       |
| J2 Render Preview Lifecycle     | Asset preview pipeline | Render/transform services   |
| J3 Apply Fidelity Fallback      | Asset preview pipeline | Fidelity policy controls    |
| J4 Invalidate and Refresh Cache | Asset preview pipeline | Cache/invalidation services |
| J5 Export Preview Governance    | Asset preview pipeline | Compliance/export services  |

## 4. Instrumentation Requirements

Required events:

- `asset_preview.journey.started`
- `asset_preview.journey.step.completed`
- `asset_preview.journey.blocked`
- `asset_preview.journey.recovered`
- `asset_preview.journey.completed`

Required dimensions:

- `previewId`, `assetRef`, `profileRequested`, `profileDelivered`, `cacheKey`
- `actorId`, `actorRole`, `classification`, `lifecycleState`, `fallbackUsed`
- `journeyId`, `stepId`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00195)

`OST-00195` is complete only when:

1. At least five asset preview 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.
