Eve library

OSHUN Studio Background Jobs and Progress UX Journeys and Edge Cases

Spec

Revision 1

On this page

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.