# OSHUN Studio Background Jobs and Progress UX Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-background-jobs-and-progress-ux-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio
background jobs and progress UX workflows.

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

## Personas

- Collaboration Lead
- Program Operator
- Domain Integrator
- Security Reviewer
- Compliance Auditor

## Journey Principles

1. Every background job must preserve canonical identity and ownership context.
2. Lifecycle transitions and progress updates must be deterministic and
   heartbeat-driven.
3. Control actions must be policy-gated, idempotent, and auditable.
4. Escalation and closure workflows must preserve cross-domain governance
   evidence.

## 1. Primary Journeys

### J1. Submit Background Job

**Goal**: Admit long-running work into canonical background-job pipeline.

**Entry**: `Studio background jobs workspace`

**Steps**:

1. Select domain workload and job type.
2. Attach workspace, ownership, priority, and correlation metadata.
3. Submit canonical job envelope.
4. Persist job and enqueue lifecycle execution.
5. Emit job-submitted audit event.

**Success State**:

- Job is persisted with deterministic queue admission context.

### J2. Track Progress and Heartbeats

**Goal**: Provide trustworthy progress state while job executes.

**Entry**: `Queued/running job`

**Steps**:

1. Transition lifecycle state from queued to running.
2. Stream stage-level progress snapshots and heartbeat timestamps.
3. Compute aggregate progress and ETA in workspace.
4. Persist progress snapshots and freshness metadata.
5. Emit progress lifecycle events.

**Success State**:

- Operators see deterministic, fresh, and attributable progress state.

### J3. Execute Control Actions

**Goal**: Apply pause/resume/cancel/retry actions safely.

**Entry**: `Running/blocked/failed job`

**Steps**:

1. Select control action (`pause`, `resume`, `cancel`, `retry`, `reassign`).
2. Evaluate role/policy authorization.
3. Execute idempotent control transition.
4. Persist action record and resulting lifecycle state.
5. Emit control-action audit event.

**Success State**:

- Control action completes with policy-compliant and auditable state transition.

### J4. Recover Blocked or Failed Jobs

**Goal**: Restore failed/stalled jobs without lineage drift.

**Entry**: `Blocked or failed lifecycle state`

**Steps**:

1. Detect stuck/failure reason and retry eligibility.
2. Select deterministic recovery strategy and assignment.
3. Resume/retry job with preserved workflow identity.
4. Persist recovery metadata and transition history.
5. Emit recovery lifecycle event.

**Success State**:

- Job recovery completes while maintaining deterministic lineage.

### J5. Escalate and Close Governance Evidence

**Goal**: Escalate critical failures and produce compliance-ready evidence.

**Entry**: `Critical stuck/failure condition or policy denial`

**Steps**:

1. Trigger escalation signal with severity and route target.
2. Notify on-call/compliance stakeholders.
3. Collect job envelope, lifecycle, progress, and control history.
4. Generate governance closure package.
5. Emit escalation/closure completion audit event.

**Success State**:

- Escalation and governance closure are complete and attributable.

## 2. Critical Edge Cases

### E1. Missing Job Identity

- Trigger: submission payload omits `jobId` or `workflowId`.
- Required behavior: reject admission and emit validation error.

### E2. Invalid Domain Routing

- Trigger: job references domain outside approved registry values.
- Required behavior: deny admission and require valid domain context.

### E3. Priority Drift During Retry

- Trigger: retry mutates priority outside policy constraints.
- Required behavior: block retry and emit policy-denied audit event.

### E4. Progress Percent Regression

- Trigger: total progress decreases without corresponding lifecycle rollback.
- Required behavior: reject update and flag progress-integrity incident.

### E5. Heartbeat Timeout

- Trigger: running job heartbeat exceeds freshness SLO threshold.
- Required behavior: mark job as blocked, trigger escalation signal.

### E6. Duplicate Control Action Replay

- Trigger: same pause/cancel/retry action replayed concurrently.
- Required behavior: enforce idempotent outcome and avoid duplicate effects.

### E7. Unauthorized Cancel Request

- Trigger: unprivileged actor requests job cancellation.
- Required behavior: deny action and emit role-policy denial event.

### E8. Retry Without Correlation Preservation

- Trigger: retry path rewrites `correlationId` unexpectedly.
- Required behavior: reject retry and preserve original lineage identity.

### E9. Escalation Routing Failure

- Trigger: critical escalation cannot route to on-call target.
- Required behavior: trigger fallback routing and create incident marker.

### E10. Governance Package Missing Control History

- Trigger: closure package omits control actions/reassignment lineage.
- Required behavior: block closure export and surface governance error.

## 3. Journey-to-Surface Mapping

| Journey                           | Primary Surface          | Supporting Surfaces                |
| --------------------------------- | ------------------------ | ---------------------------------- |
| J1 Submit Background Job          | Background jobs/progress | Domain job adapters                |
| J2 Track Progress and Heartbeats  | Background jobs/progress | Progress stream + heartbeat system |
| J3 Execute Control Actions        | Background jobs/progress | Policy and RBAC services           |
| J4 Recover Blocked or Failed Jobs | Background jobs/progress | Reliability and queue services     |
| J5 Escalate and Close Governance  | Background jobs/progress | Notification/compliance systems    |

## 4. Instrumentation Requirements

Required events:

- `background_jobs_progress.journey.started`
- `background_jobs_progress.journey.step.completed`
- `background_jobs_progress.journey.blocked`
- `background_jobs_progress.journey.recovered`
- `background_jobs_progress.journey.completed`

Required dimensions:

- `jobId`, `workflowId`, `correlationId`, `jobType`, `domain`, `priority`
- `actorId`, `actorRole`, `lifecycleState`, `progressPercent`, `heartbeatAt`
- `journeyId`, `stepId`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00203)

`OST-00203` is complete only when:

1. At least five background-job/progress journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
