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.mddocs/adr/ADR-0038-oshun-studio-background-jobs-and-progress-ux.mdlibs/oshun/analytics/src/types.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for job envelope, lifecycle, progress snapshot, control actions, escalation, and audit events are documented.
- Ownership boundaries and validation rules are explicit.