Disciplines · Decisions (ADRs)

ADR-0038: OSHUN Studio Background Jobs and Progress UX

Studio operators run long-lived operations continuously: media ingest, preview rendering, publish workflows, governance exports, and cross-domain processing.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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