# OSHUN Studio Asset Preview Pipeline Dependency and Data Contract Map

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.md`
- `docs/adr/ADR-0037-oshun-studio-asset-preview-pipeline.md`
- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md`
- `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`

## 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:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for preview request, lifecycle, fidelity/fallback, cache record,
   and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
