# OSHUN Studio Resilience and Error UX Dependency and Data Contract Map

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.md`
- `docs/adr/ADR-0039-oshun-studio-resilience-and-error-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

- **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:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contracts for error envelope, severity routing, recovery action, degraded
   mode, incident closure, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
