Eve library

OSHUN Studio Asset Preview Pipeline 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-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.