Disciplines · Decisions (ADRs)

ADR-0039: OSHUN Studio Resilience and Error UX

Studio operators manage high-risk, long-running, and cross-domain workflows where errors and degraded states are expected.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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.
  • 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