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.mddocs/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#
- Every background job must preserve canonical identity and ownership context.
- Lifecycle transitions and progress updates must be deterministic and heartbeat-driven.
- Control actions must be policy-gated, idempotent, and auditable.
- 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:
- Select domain workload and job type.
- Attach workspace, ownership, priority, and correlation metadata.
- Submit canonical job envelope.
- Persist job and enqueue lifecycle execution.
- 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:
- Transition lifecycle state from queued to running.
- Stream stage-level progress snapshots and heartbeat timestamps.
- Compute aggregate progress and ETA in workspace.
- Persist progress snapshots and freshness metadata.
- 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:
- Select control action (
pause,resume,cancel,retry,reassign). - Evaluate role/policy authorization.
- Execute idempotent control transition.
- Persist action record and resulting lifecycle state.
- 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:
- Detect stuck/failure reason and retry eligibility.
- Select deterministic recovery strategy and assignment.
- Resume/retry job with preserved workflow identity.
- Persist recovery metadata and transition history.
- 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:
- Trigger escalation signal with severity and route target.
- Notify on-call/compliance stakeholders.
- Collect job envelope, lifecycle, progress, and control history.
- Generate governance closure package.
- 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
jobIdorworkflowId. - 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
correlationIdunexpectedly. - 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.startedbackground_jobs_progress.journey.step.completedbackground_jobs_progress.journey.blockedbackground_jobs_progress.journey.recoveredbackground_jobs_progress.journey.completed
Required dimensions:
jobId,workflowId,correlationId,jobType,domain,priorityactorId,actorRole,lifecycleState,progressPercent,heartbeatAtjourneyId,stepId,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00203)#
OST-00203 is complete only when:
- At least five background-job/progress journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.