Eve library

OSHUN Studio Asset Preview Pipeline Dependency and Data Contract Map

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

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.