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.mddocs/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#
- Every preview request must bind to explicit asset revision and profile.
- Rendering lifecycle transitions must be deterministic and auditable.
- Fallback and cache invalidation behavior must be explicit and policy-aware.
- 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:
- Select asset reference and preview profile.
- Attach revision, classification, and requestor context.
- Submit canonical preview request envelope.
- Persist request and enqueue rendering lifecycle.
- 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:
- Transition preview to rendering state.
- Execute transform/render pipeline for requested profile.
- Persist rendering progress and output metadata.
- Mark preview state ready with output URL.
- 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:
- Detect unsupported/failed render profile.
- Select deterministic fallback profile.
- Render fallback output with policy checks.
- Persist fallback reason and delivered profile metadata.
- 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:
- Detect asset revision drift against preview cache key.
- Invalidate stale cache record.
- Trigger refresh rendering for current revision.
- Persist refreshed cache state and linkage metadata.
- 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:
- Collect request, lifecycle, fidelity, and cache events.
- Attach classification/retention metadata.
- Produce governance export package.
- Persist export reference and audit markers.
- 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.startedasset_preview.journey.step.completedasset_preview.journey.blockedasset_preview.journey.recoveredasset_preview.journey.completed
Required dimensions:
previewId,assetRef,profileRequested,profileDelivered,cacheKeyactorId,actorRole,classification,lifecycleState,fallbackUsedjourneyId,stepId,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00195)#
OST-00195 is complete only when:
- At least five asset preview journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.