Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE + OSHUN
Security
Last Updated: 2026-02-23
Related: docs/adr/ADR-0039-oshun-studio-resilience-and-error-ux.md
Purpose#
Define dependencies and canonical contracts for Studio resilience and error UX capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00210.
Sources Used#
docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0039-oshun-studio-resilience-and-error-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#
- Resilience/error UI surfaces: Studio resilience modules in
apps/oshun/web/src/components/studio. - Error normalization services: BFF envelope normalization and workflow correlation services.
- Recovery orchestration adapters: retry/replay/rollback/degraded-mode handlers across domain workers.
- Incident routing services: severity-aware assignment and escalation systems.
- Governance evidence pipelines: telemetry ingestion and closure retention export systems.
1.2 Domain Dependency Graph#
Resilience/Error UX -> Yemaya: release pipeline fault handling and rollback.Resilience/Error UX -> Isis: training/inference failure handling and replay.Resilience/Error UX -> Hathor: narrative generation fault handling and fallback.Resilience/Error UX -> Aja: timeline/render failure handling and continuity recovery.Resilience/Error UX -> Bellona: runtime incident triage and escalation workflows.Project Obsidian -> all: cross-domain resilience governance and closure controls.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Canonical error envelope | BFF + Domain Integrators | Operators + reliability teams | Error payload | StudioErrorEnvelope |
| Severity and routing policy | Security + Program Ops | On-call + operators | Severity record | StudioSeverityRouting |
| Recovery-action orchestration | Platform SRE + BFF | Operators + domain workers | Recovery payload | StudioRecoveryAction |
| Degraded-mode continuity controls | Platform SRE | Operators + product surfaces | Degraded-state record | StudioDegradedModeState |
| Incident closure and governance | Data Platform + Security | Compliance + governance | Closure payload | StudioIncidentClosureRecord |
| Audit and telemetry evidence | Data Platform + Security | Compliance + operations | Telemetry/audit event | StudioResilienceAuditEvent |
3. Canonical Contracts#
3.1 StudioErrorEnvelope#
ts
export interface StudioErrorEnvelope {
errorId: string;
workflowId: string;
correlationId: string;
domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
surface: string;
errorCode: string;
severity: 'info' | 'warning' | 'high' | 'critical';
occurredAt: string;
}
3.2 StudioSeverityRouting#
ts
export interface StudioSeverityRouting {
routingId: string;
errorId: string;
severity: 'info' | 'warning' | 'high' | 'critical';
impactScope: 'single_flow' | 'workspace' | 'domain' | 'cross_domain';
assignedOwner: string;
escalated: boolean;
routedAt: string;
}
3.3 StudioRecoveryAction#
ts
export interface StudioRecoveryAction {
actionId: string;
errorId: string;
workflowId: string;
action: 'retry' | 'rollback' | 'replay' | 'manual_override';
actorId: string;
actorRole: string;
policyId: string;
reason: string;
occurredAt: string;
}
3.4 StudioDegradedModeState#
ts
export interface StudioDegradedModeState {
degradedStateId: string;
workflowId: string;
domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
active: boolean;
blockedCapabilities: string[];
fallbackCapabilities: string[];
enteredAt: string;
recoveredAt?: string;
}
3.5 StudioIncidentClosureRecord#
ts
export interface StudioIncidentClosureRecord {
closureId: string;
errorId: string;
severity: 'info' | 'warning' | 'high' | 'critical';
ownerId: string;
rootCause: string;
remediationId: string;
governanceTagged: boolean;
closedAt: string;
}
3.6 StudioResilienceAuditEvent#
ts
export interface StudioResilienceAuditEvent {
eventId: string;
action:
| 'resilience.error_detected'
| 'resilience.recovery_executed'
| 'resilience.degraded_mode_entered'
| 'resilience.escalated'
| 'resilience.incident_closed'
| 'resilience.policy_denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
errorId?: string;
workflowId?: string;
actorId?: string;
actorRole?: string;
traceId?: string;
occurredAt: string;
}
4. Validation Rules#
- Error envelopes missing identity, severity, or workflow metadata must be rejected.
- Severity routing must be deterministic and preserve owner assignment lineage.
- Recovery actions must remain idempotent and policy-gated.
- Degraded mode must expose blocked capabilities and explicit fallback behavior.
- Incident closure must include root-cause and remediation metadata.
- Audit events must capture detect/recover/degrade/escalate/close outcomes end to end.
5. Acceptance Criteria (OST-00210)#
OST-00210 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for error envelope, severity routing, recovery action, degraded mode, incident closure, and audit events are documented.
- Ownership boundaries and validation rules are explicit.