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
Purpose#
Define dependencies and canonical contracts for Studio asset preview pipeline capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00194.
Sources Used#
docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0037-oshun-studio-asset-preview-pipeline.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.md
1. Dependency Overview#
1.1 Control Surfaces#
- Preview UI surfaces: Studio preview modules in
apps/oshun/web/src/components/studio. - Preview orchestration services: BFF preview request + lifecycle APIs.
- Rendering/transform services: media conversion, model thumbnailing, timeline frame extraction.
- Caching/invalidation services: preview cache keys, revision invalidation, and freshness controls.
- Telemetry/governance pipelines: analytics and compliance evidence exports.
1.2 Domain Dependency Graph#
Asset Preview -> Yemaya: release bundle preview and scene validation media.Asset Preview -> Isis: model artifact and dataset preview rendering.Asset Preview -> Hathor: narrative/world asset preview and review context.Asset Preview -> Aja: timeline/sequence/frame preview generation.Asset Preview -> Bellona: runtime artifact and incident evidence preview.Project Obsidian -> all: cross-domain preview governance and quality gates.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Canonical preview request | BFF + Domain Integrators | Studio operators + reviewers | Preview payload | StudioPreviewRequest |
| Rendering lifecycle orchestration | BFF + Platform SRE | Studio surfaces + pipelines | Lifecycle payload | StudioPreviewLifecycle |
| Fidelity and fallback decisions | Studio Architecture | Reviewers + operators | Fidelity payload | StudioPreviewFidelity |
| Cache and invalidation controls | Platform SRE + BFF | Studio surfaces + APIs | Cache payload | StudioPreviewCacheRecord |
| Audit and governance evidence | Data Platform + Security | Compliance + governance | Telemetry/audit event | StudioPreviewAuditEvent |
3. Canonical Contracts#
3.1 StudioPreviewRequest#
ts
export interface StudioPreviewRequest {
previewId: string;
assetRef: string;
sourceDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
requestorId: string;
profile: 'thumbnail' | 'timeline_frame' | 'interactive' | 'high_fidelity';
classification: 'public' | 'internal' | 'restricted' | 'confidential';
requestedAt: string;
}
3.2 StudioPreviewLifecycle#
ts
export interface StudioPreviewLifecycle {
lifecycleId: string;
previewId: string;
state: 'queued' | 'rendering' | 'ready' | 'failed';
progressPercent: number;
previewUrl?: string;
updatedAt: string;
}
3.3 StudioPreviewFidelity#
ts
export interface StudioPreviewFidelity {
fidelityId: string;
previewId: string;
requestedProfile: string;
deliveredProfile: string;
fallbackUsed: boolean;
fallbackReason?: string;
evaluatedAt: string;
}
3.4 StudioPreviewCacheRecord#
ts
export interface StudioPreviewCacheRecord {
cacheId: string;
previewId: string;
assetRevision: string;
cacheKey: string;
state: 'warm' | 'invalidated' | 'refreshing';
invalidationReason?: string;
updatedAt: string;
}
3.5 StudioPreviewAuditEvent#
ts
export interface StudioPreviewAuditEvent {
eventId: string;
action:
| 'preview.requested'
| 'preview.rendered'
| 'preview.fallback_used'
| 'preview.cache_invalidated'
| 'preview.policy_denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
previewId?: string;
lifecycleId?: string;
actorId?: string;
actorRole?: string;
traceId?: string;
occurredAt: string;
}
4. Validation Rules#
- Preview requests missing asset/profile/classification context must be rejected.
- Rendering lifecycle transitions must remain deterministic and auditable.
- Fallback decisions must include reason metadata and delivered profile.
- Cache invalidation must reference revision and invalidation rationale.
- Audit events must capture request/render/fallback/cache outcomes end to end.
5. Acceptance Criteria (OST-00194)#
OST-00194 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for preview request, lifecycle, fidelity/fallback, cache record, and audit events are documented.
- Ownership boundaries and validation rules are explicit.