# OSHUN Studio Background Jobs and Progress UX Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0038-oshun-studio-background-jobs-and-progress-ux.md`

## Purpose

Define dependencies and canonical contracts for Studio background jobs and
progress UX capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

This document is the execution artifact for `OST-00202`.

## Sources Used

- `docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0038-oshun-studio-background-jobs-and-progress-ux.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

- **Jobs/progress UI surfaces**: Studio background-jobs modules in
  `apps/oshun/web/src/components/studio`.
- **Job admission/orchestration services**: BFF job queue APIs, ownership
  services, and lifecycle policy checks.
- **Domain execution adapters**: worker runtimes for ingest/render/build/export
  operations.
- **Progress aggregation and heartbeat services**: stage-level progress
  snapshots, ETA models, and stuck-job detection.
- **Escalation and governance evidence pipelines**: notification routing,
  analytics, and compliance retention/export systems.

### 1.2 Domain Dependency Graph

- `Background Jobs -> Yemaya`: release-bundle generation and pipeline publish
  tasks.
- `Background Jobs -> Isis`: model training/evaluation and dataset processing
  jobs.
- `Background Jobs -> Hathor`: narrative synthesis and world-state generation
  jobs.
- `Background Jobs -> Aja`: timeline rendering, reconciliation, and export jobs.
- `Background Jobs -> Bellona`: runtime validation, incident replay, and
  recovery jobs.
- `Project Obsidian -> all`: cross-domain orchestration, escalation, and
  governance controls.

## 2. Ownership and Contract Matrix

| Area                          | Owner                    | Consumers                     | Artifact              | Contract                       |
| ----------------------------- | ------------------------ | ----------------------------- | --------------------- | ------------------------------ |
| Canonical job envelope        | BFF + Domain Integrators | Operators + execution workers | Job payload           | `StudioBackgroundJobEnvelope`  |
| Lifecycle state orchestration | Platform SRE + BFF       | Studio surfaces + services    | Lifecycle payload     | `StudioBackgroundJobLifecycle` |
| Progress and heartbeat model  | Domain Workers + BFF     | Operators + escalation routes | Progress payload      | `StudioJobProgressSnapshot`    |
| Control actions and policies  | Security + Program Ops   | Operators + SRE               | Control-action record | `StudioJobControlAction`       |
| Escalation and routing        | Program Ops + SRE        | Notification center + on-call | Escalation payload    | `StudioJobEscalationSignal`    |
| Audit and governance evidence | Data Platform + Security | Compliance + governance       | Telemetry/audit event | `StudioJobAuditEvent`          |

## 3. Canonical Contracts

### 3.1 StudioBackgroundJobEnvelope

```ts
export interface StudioBackgroundJobEnvelope {
  jobId: string;
  workflowId: string;
  correlationId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workspaceId: string;
  jobType: string;
  priority: 'low' | 'normal' | 'high' | 'critical';
  requestedBy: string;
  requestedAt: string;
}
```

### 3.2 StudioBackgroundJobLifecycle

```ts
export interface StudioBackgroundJobLifecycle {
  lifecycleId: string;
  jobId: string;
  state:
    | 'queued'
    | 'running'
    | 'blocked'
    | 'retrying'
    | 'completed'
    | 'failed'
    | 'canceled';
  queueWaitMs?: number;
  runLatencyMs?: number;
  updatedAt: string;
}
```

### 3.3 StudioJobProgressSnapshot

```ts
export interface StudioJobProgressSnapshot {
  progressId: string;
  jobId: string;
  stageKey: string;
  stageLabel: string;
  stagePercent: number;
  totalPercent: number;
  heartbeatAt: string;
  etaMs?: number;
  throughputPerMinute?: number;
}
```

### 3.4 StudioJobControlAction

```ts
export interface StudioJobControlAction {
  actionId: string;
  jobId: string;
  action: 'pause' | 'resume' | 'cancel' | 'retry' | 'reassign';
  actorId: string;
  actorRole: string;
  policyId: string;
  reason: string;
  occurredAt: string;
}
```

### 3.5 StudioJobEscalationSignal

```ts
export interface StudioJobEscalationSignal {
  escalationId: string;
  jobId: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  trigger: 'stuck' | 'retry_exhausted' | 'policy_denied' | 'latency_breach';
  routedTo: string;
  acknowledged: boolean;
  escalatedAt: string;
}
```

### 3.6 StudioJobAuditEvent

```ts
export interface StudioJobAuditEvent {
  eventId: string;
  action:
    | 'job.submitted'
    | 'job.started'
    | 'job.progressed'
    | 'job.controlled'
    | 'job.escalated'
    | 'job.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  jobId?: string;
  lifecycleId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}
```

## 4. Validation Rules

- Job envelopes missing identity, domain, or ownership metadata must be
  rejected.
- Lifecycle transitions must remain deterministic and enforce state guards.
- Progress snapshots must include heartbeat freshness and bounded percentages.
- Control actions must be idempotent, policy-gated, and auditable.
- Escalation signals must trigger on stuck/retry/latency thresholds.
- Audit events must capture submit/start/progress/control/escalation outcomes
  end to end.

## 5. Acceptance Criteria (OST-00202)

`OST-00202` 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 job envelope, lifecycle, progress snapshot, control actions,
   escalation, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
