Eve library

OSHUN Studio Background Jobs and Progress UX Dependency and Data Contract Map

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

Purpose#

Define dependencies and canonical contracts for Studio background jobs and progress UX capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00202.

Sources Used#

  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0038-oshun-studio-background-jobs-and-progress-ux.md
  • libs/oshun/analytics/src/types.ts
  • libs/oshun/domain-registry/src/index.ts
  • docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md
  • 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

1. Dependency Overview#

1.1 Control Surfaces#

  • Jobs/progress UI surfaces: Studio background-jobs modules in apps/oshun/web/src/components/studio.
  • Job admission/orchestration services: BFF job queue APIs, ownership services, and lifecycle policy checks.
  • Domain execution adapters: worker runtimes for ingest/render/build/export operations.
  • Progress aggregation and heartbeat services: stage-level progress snapshots, ETA models, and stuck-job detection.
  • Escalation and governance evidence pipelines: notification routing, analytics, and compliance retention/export systems.

1.2 Domain Dependency Graph#

  • Background Jobs -> Yemaya: release-bundle generation and pipeline publish tasks.
  • Background Jobs -> Isis: model training/evaluation and dataset processing jobs.
  • Background Jobs -> Hathor: narrative synthesis and world-state generation jobs.
  • Background Jobs -> Aja: timeline rendering, reconciliation, and export jobs.
  • Background Jobs -> Bellona: runtime validation, incident replay, and recovery jobs.
  • Project Obsidian -> all: cross-domain orchestration, escalation, and governance controls.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Canonical job envelope BFF + Domain Integrators Operators + execution workers Job payload StudioBackgroundJobEnvelope
Lifecycle state orchestration Platform SRE + BFF Studio surfaces + services Lifecycle payload StudioBackgroundJobLifecycle
Progress and heartbeat model Domain Workers + BFF Operators + escalation routes Progress payload StudioJobProgressSnapshot
Control actions and policies Security + Program Ops Operators + SRE Control-action record StudioJobControlAction
Escalation and routing Program Ops + SRE Notification center + on-call Escalation payload StudioJobEscalationSignal
Audit and governance evidence Data Platform + Security Compliance + governance Telemetry/audit event StudioJobAuditEvent

3. Canonical Contracts#

3.1 StudioBackgroundJobEnvelope#

ts
export interface StudioBackgroundJobEnvelope {
  jobId: string;
  workflowId: string;
  correlationId: string;
  domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  workspaceId: string;
  jobType: string;
  priority: 'low' | 'normal' | 'high' | 'critical';
  requestedBy: string;
  requestedAt: string;
}

3.2 StudioBackgroundJobLifecycle#

ts
export interface StudioBackgroundJobLifecycle {
  lifecycleId: string;
  jobId: string;
  state:
    | 'queued'
    | 'running'
    | 'blocked'
    | 'retrying'
    | 'completed'
    | 'failed'
    | 'canceled';
  queueWaitMs?: number;
  runLatencyMs?: number;
  updatedAt: string;
}

3.3 StudioJobProgressSnapshot#

ts
export interface StudioJobProgressSnapshot {
  progressId: string;
  jobId: string;
  stageKey: string;
  stageLabel: string;
  stagePercent: number;
  totalPercent: number;
  heartbeatAt: string;
  etaMs?: number;
  throughputPerMinute?: number;
}

3.4 StudioJobControlAction#

ts
export interface StudioJobControlAction {
  actionId: string;
  jobId: string;
  action: 'pause' | 'resume' | 'cancel' | 'retry' | 'reassign';
  actorId: string;
  actorRole: string;
  policyId: string;
  reason: string;
  occurredAt: string;
}

3.5 StudioJobEscalationSignal#

ts
export interface StudioJobEscalationSignal {
  escalationId: string;
  jobId: string;
  severity: 'low' | 'medium' | 'high' | 'critical';
  trigger: 'stuck' | 'retry_exhausted' | 'policy_denied' | 'latency_breach';
  routedTo: string;
  acknowledged: boolean;
  escalatedAt: string;
}

3.6 StudioJobAuditEvent#

ts
export interface StudioJobAuditEvent {
  eventId: string;
  action:
    | 'job.submitted'
    | 'job.started'
    | 'job.progressed'
    | 'job.controlled'
    | 'job.escalated'
    | 'job.policy_denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  jobId?: string;
  lifecycleId?: string;
  actorId?: string;
  actorRole?: string;
  traceId?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Job envelopes missing identity, domain, or ownership metadata must be rejected.
  • Lifecycle transitions must remain deterministic and enforce state guards.
  • Progress snapshots must include heartbeat freshness and bounded percentages.
  • Control actions must be idempotent, policy-gated, and auditable.
  • Escalation signals must trigger on stuck/retry/latency thresholds.
  • Audit events must capture submit/start/progress/control/escalation outcomes end to end.

5. Acceptance Criteria (OST-00202)#

OST-00202 is complete only when:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for job envelope, lifecycle, progress snapshot, control actions, escalation, and audit events are documented.
  4. Ownership boundaries and validation rules are explicit.