# ADR-0039: OSHUN Studio Resilience and Error UX

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web + BFF Engineering, Platform
SRE, OSHUN Security  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio operators manage high-risk, long-running, and cross-domain workflows
where errors and degraded states are expected. Existing error handling patterns
are inconsistent across surfaces, making recovery paths unpredictable and
reducing operator trust.

Without a canonical resilience and error UX model, OSHUN risks:

- inconsistent error messaging and remediation behavior across domains
- slow incident response from weak severity and escalation alignment
- duplicated recovery logic and fragile degraded-mode handling
- insufficient audit evidence for policy and compliance decisions

## Decision Drivers

- **Recoverability**: every critical error must provide deterministic recovery
  paths.
- **Clarity**: operator-facing error states must be explicit and actionable.
- **Determinism**: retries/rollbacks must preserve workflow identity and
  lineage.
- **Interoperability**: one resilience model across
  Yemaya/Isis/Hathor/Aja/Bellona.
- **Governance**: incident and recovery actions must be auditable.

## Considered Options

### Option 1: Per-Feature Error Handling Patterns

Allow each Studio feature team to define custom error models and UX.

**Pros**:

- Fast local iteration for individual teams.

**Cons**:

- Inconsistent user experience and incident response quality.
- Harder cross-domain governance and observability.

### Option 2: Infrastructure-Only Resilience with Thin UX

Focus resilience in backend systems and expose minimal UI error details.

**Pros**:

- Reduced frontend implementation surface area.

**Cons**:

- Limited operator agency and weak remediation guidance in Studio UX.
- Poor alignment with policy/compliance evidence needs.

### Option 3: Canonical Resilience and Error UX Contracts (Chosen)

Adopt shared error envelope, severity, recovery, degraded-mode, escalation, and
audit contracts with consistent Studio UX behavior.

**Pros**:

- Predictable operator experience and faster incident remediation.
- Stronger policy/compliance posture with attributable recovery actions.
- Better cross-domain reliability and incident coordination.

**Cons**:

- Requires coordinated schema and lifecycle governance across teams.

## Decision Outcome

**Chosen option**: Option 3.

Resilience and error UX requirements:

1. **Canonical error envelope contract** for identity, scope, and severity.
2. **Severity and impact contract** for incident triage and routing.
3. **Recovery action contract** for retry/rollback/replay/fail-safe flows.
4. **Degraded-mode contract** for safe continuity under partial failures.
5. **Escalation and closure contract** for incident ownership and evidence.
6. **Audit and telemetry contract** for traceability and SLO alignment.

## Normative Rules

### Canonical Error Envelope Contract

- Every error must include `errorId`, `errorCode`, `domain`, `surface`,
  `workflowId`, `severity`, and `occurredAt`.
- Error envelopes must preserve correlation IDs for cross-system traceability.
- Invalid error payloads must be rejected from operator-facing surfaces.

### Severity and Impact Contract

- Severity levels are constrained to `info`, `warning`, `high`, and `critical`.
- Incident routing must be deterministic by severity and domain ownership.
- Critical incidents must trigger immediate escalation and explicit owner
  assignment.

### Recovery Action Contract

- Recovery actions (`retry`, `rollback`, `replay`, `manual_override`) must be
  idempotent.
- Recovery actions must enforce policy and role constraints.
- Recovery state transitions must preserve workflow lineage identity.

### Degraded-Mode Contract

- Degraded mode must expose active capability limits and blocked actions.
- Safety-critical actions must fail closed when required dependencies are
  unavailable.
- Degraded state entry/exit must emit explicit lifecycle events.

### Escalation and Closure Contract

- Escalation artifacts must include severity, impact, owner, and timeline
  metadata.
- Incident closure requires root-cause summary and validated remediation.
- Production closure requires compliance-ready evidence packaging.

### Audit and Telemetry Contract

- Error, recovery, degraded-mode, and closure actions must emit audit events.
- Telemetry must include `success`, `latencyMs`, `severity`, and `errorCode`.
- Missing resilience telemetry must trigger degraded-observability warnings.

### Release Validity Contract

A resilience/error UX release is valid only when all are true:

- error-envelope schema validation passes
- severity routing and escalation tests pass
- recovery and degraded-mode behavior tests pass
- policy and role enforcement checks pass
- telemetry/audit integrity checks pass
- rollback, ownership, and runbook handoff are documented

## Architecture Implications

- Studio surfaces share one resilience and error-state model.
- BFF orchestrates error envelope normalization and policy-aware recovery.
- Domain adapters map local failures into canonical resilience contracts.
- Analytics pipelines track severity mix, retry success, and incident closure
  quality.

## Acceptance Criteria (OST-00209)

`OST-00209` is complete only when:

1. ADR exists at `docs/adr/ADR-0045-oshun-studio-resilience-and-error-ux.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines error envelope, severity, recovery, degraded mode, escalation,
   telemetry/audit, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0038`, especially `ADR-0012`,
   `ADR-0038`, and `ADR-0037`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/analytics`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Clearer and more consistent resilience behavior across Studio workflows.
- Faster, safer recovery with explicit operator guidance.
- Improved incident governance and compliance evidence quality.

### Negative

- Additional integration and migration work for existing surfaces.
- Requires ongoing governance of error-code and recovery-action taxonomies.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0044-oshun-studio-background-jobs-and-progress-ux.md`
- `docs/adr/ADR-0043-oshun-studio-asset-preview-pipeline.md`

## References

- `libs/oshun/analytics/src/types.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`