# ADR-0038: OSHUN Studio Background Jobs and Progress UX

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, Platform
SRE  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio operators run long-lived operations continuously: media ingest, preview
rendering, publish workflows, governance exports, and cross-domain processing.
Today, background work state is fragmented across local domain implementations
with inconsistent progress, retries, and ownership signaling.

Without a canonical background-jobs model and progress UX, OSHUN risks:

- low operator trust in long-running execution state
- duplicated queue/control logic across Studio domains
- hidden failures and delayed escalation for critical pipelines
- weak governance evidence for retries, cancellation, and ownership transfer

## Decision Drivers

- **Determinism**: job lifecycle transitions must be strict and auditable.
- **Ergonomics**: operators need one coherent progress UX surface.
- **Resilience**: retries, pause/resume, and cancel controls must be reliable.
- **Interoperability**: one contract model across
  Yemaya/Isis/Hathor/Aja/Bellona.
- **Operability**: failures and stuck jobs must trigger explicit escalation
  paths.

## Considered Options

### Option 1: Domain-Specific Job + Progress Implementations

Let each domain own custom background queues and progress UI behavior.

**Pros**:

- Rapid local delivery for domain-specific workflows.

**Cons**:

- Inconsistent operator UX and policy semantics.
- Higher long-term maintenance and governance costs.

### Option 2: External Scheduler with Thin Studio Wrappers

Use third-party scheduling/progress capabilities directly from Studio surfaces.

**Pros**:

- Faster initial rollout with reduced direct implementation burden.

**Cons**:

- Limited control over progress semantics and ownership contracts.
- Weaker alignment with Studio policy, audit, and domain context requirements.

### Option 3: Canonical Studio Background-Job Contracts + Progress UX (Chosen)

Adopt shared job envelope, lifecycle, progress, control-plane, and audit
contracts with one Studio progress UX model.

**Pros**:

- Consistent operator experience and decision confidence.
- Stronger governance and auditability for long-running execution.
- Better cross-domain reliability and ownership clarity.

**Cons**:

- Requires coordinated schema governance and queue adapter integration.

## Decision Outcome

**Chosen option**: Option 3.

Background jobs and progress UX requirements:

1. **Canonical job envelope contract** for identity, ownership, and routing.
2. **Lifecycle contract** for deterministic state transitions.
3. **Progress contract** for stage-level and aggregate progress reporting.
4. **Control-plane contract** for pause/resume/cancel/retry operations.
5. **Escalation and notification contract** for stuck/failing jobs.
6. **Audit and telemetry contract** for job lineage and SLO observability.

## Normative Rules

### Canonical Job Envelope Contract

- Every job must include `jobId`, `jobType`, `domain`, `workspaceId`,
  `requestedBy`, `requestedAt`, and `priority`.
- Jobs must carry correlation keys (`correlationId`, `workflowId`) for
  cross-surface traceability.
- Invalid or incomplete envelopes must be rejected before queue admission.

### Lifecycle Contract

- Lifecycle states are constrained to `queued`, `running`, `blocked`,
  `retrying`, `completed`, `failed`, and `canceled`.
- Transitions must be deterministic and validated against policy constraints.
- Stuck-state detection must trigger escalation when heartbeat SLO is violated.

### Progress Contract

- Progress must expose stage-level status plus aggregate percentage.
- Every running job must include heartbeat metadata and freshness timestamp.
- ETA and throughput fields are optional but, when present, must be typed and
  unit-explicit.

### Control-Plane Contract

- Pause, resume, cancel, and retry actions must be idempotent.
- Control actions must enforce role/policy checks before execution.
- Every control action must emit explicit audit and telemetry events.

### Escalation and Notification Contract

- Failing or blocked jobs exceeding threshold must trigger escalation routes.
- Operator assignment transitions must be explicit and auditable.
- Critical-path job incidents must integrate with Studio notification surfaces.

### Audit and Telemetry Contract

- Job lifecycle, control actions, and escalation decisions must emit audit
  events.
- Telemetry must include `success`, `latencyMs`, `queueWaitMs`, and failure
  reason when applicable.
- Missing telemetry or audit evidence must trigger degraded-observability
  warnings.

### Release Validity Contract

A background-jobs/progress UX release is valid only when all are true:

- job envelope schema validation passes
- lifecycle transition tests pass
- progress freshness and stuck-detection checks pass
- control-plane idempotency and policy checks pass
- telemetry/audit integrity checks pass
- rollback, ownership, and escalation handoff are documented

## Architecture Implications

- Studio surfaces share one background-jobs and progress model.
- BFF orchestrates job admission, lifecycle transitions, and ownership metadata.
- Domain adapters integrate workload-specific execution workers.
- Analytics pipelines track queue health, latency, retries, and escalation rate.

## Acceptance Criteria (OST-00201)

`OST-00201` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0044-oshun-studio-background-jobs-and-progress-ux.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines envelope, lifecycle, progress, control-plane, escalation,
   telemetry/audit, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0037`, especially `ADR-0012`,
   `ADR-0037`, and `ADR-0036`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Higher operator confidence in long-running work execution and ownership.
- Faster incident detection and response for stuck or failing jobs.
- Stronger policy/compliance evidence for background job control actions.

### Negative

- Additional upfront integration work for existing domain job pipelines.
- Ongoing governance required for job-type and policy compatibility.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0042-oshun-studio-file-and-media-ingestion.md`
- `docs/adr/ADR-0043-oshun-studio-asset-preview-pipeline.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`