Eve library

OSHUN Studio Resilience and Error UX Journeys and Edge Cases

Spec

Revision 1

On this page

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
  • docs/releases/v1/specs/studio-resilience-and-error-ux-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and deterministic edge-case behavior for Studio resilience and error UX workflows.

This document is the execution artifact for OST-00211.

Personas#

  • Collaboration Lead
  • Program Operator
  • Domain Integrator
  • Security Reviewer
  • Compliance Auditor

Journey Principles#

  1. Every error state must map to a canonical envelope and severity.
  2. Recovery guidance must be deterministic, policy-aware, and idempotent.
  3. Degraded mode must preserve safe continuity with explicit capability limits.
  4. Escalation and closure workflows must preserve governance evidence lineage.

1. Primary Journeys#

J1. Detect and Classify Error#

Goal: Normalize and classify workflow failures into canonical error model.

Entry: Workflow failure or policy denial

Steps:

  1. Capture raw domain failure payload.
  2. Normalize into canonical error envelope.
  3. Assign severity and impact scope.
  4. Persist error record with workflow/correlation identifiers.
  5. Emit error-detected audit event.

Success State:

  • Error is persisted with deterministic identity and severity metadata.

J2. Execute Guided Recovery#

Goal: Recover failed workflow through policy-approved remediation path.

Entry: Classified high/critical or blocking error

Steps:

  1. Present available recovery actions (retry, rollback, replay, manual_override).
  2. Validate role and policy authorization.
  3. Execute idempotent recovery transition.
  4. Persist recovery outcome and lineage metadata.
  5. Emit recovery-completed event.

Success State:

  • Recovery action completes with preserved workflow identity and traceability.

J3. Enter and Operate Degraded Mode#

Goal: Maintain safe continuity when dependencies are partially unavailable.

Entry: Dependency outage or systemic reliability breach

Steps:

  1. Detect degraded-mode trigger and affected capabilities.
  2. Enter degraded mode with explicit capability restrictions.
  3. Route eligible workflows through fallback paths.
  4. Surface blocked actions and fallback status to operators.
  5. Emit degraded-mode lifecycle events.

Success State:

  • Degraded mode preserves safe operation with explicit limits and observability.

J4. Escalate Incident and Route Ownership#

Goal: Route critical incidents to accountable responders quickly.

Entry: Critical severity or exhausted recovery attempts

Steps:

  1. Create escalation record with severity and impact context.
  2. Route ownership to on-call and domain leads.
  3. Track acknowledgement and mitigation status.
  4. Update operator-visible incident timeline.
  5. Emit escalation-routing event.

Success State:

  • Incident ownership and mitigation status are explicit and attributable.

J5. Close Incident and Export Governance Evidence#

Goal: Complete incident with validated remediation and compliance evidence.

Entry: Mitigation validated and stability restored

Steps:

  1. Capture root-cause and remediation summary.
  2. Validate closure requirements and policy checks.
  3. Package error, recovery, degraded, and escalation evidence.
  4. Persist closure record and retention tags.
  5. Emit closure-completed governance event.

Success State:

  • Incident is closed with complete, audit-ready evidence package.

2. Critical Edge Cases#

E1. Error Envelope Missing Workflow Identity#

  • Trigger: envelope lacks workflowId or correlationId.
  • Required behavior: reject envelope and require complete identity context.

E2. Unknown Severity Value#

  • Trigger: severity outside approved taxonomy.
  • Required behavior: reject classification and require valid severity mapping.

E3. Recovery Action Without Policy Authorization#

  • Trigger: unprivileged actor initiates restricted recovery.
  • Required behavior: deny action and emit policy-denied audit event.

E4. Duplicate Recovery Action Replay#

  • Trigger: same recovery action submitted concurrently.
  • Required behavior: enforce idempotent outcome and avoid duplicate side effects.

E5. Degraded Mode Without Capability Metadata#

  • Trigger: degraded mode entered with missing blocked/fallback capability set.
  • Required behavior: reject degraded transition and surface configuration error.

E6. Safety-Critical Action Executed During Degraded Mode#

  • Trigger: blocked action attempts execution while degraded mode is active.
  • Required behavior: fail closed and present explicit blocked-action guidance.

E7. Escalation Routing Failure#

  • Trigger: critical escalation cannot route to owning team.
  • Required behavior: trigger fallback routing and incident-system alert.

E8. Incident Closure Without Root Cause#

  • Trigger: closure attempted without remediation summary/root-cause metadata.
  • Required behavior: block closure and require mandatory closure fields.

E9. Governance Package Missing Recovery History#

  • Trigger: closure export omits recovery/degraded/escalation lineage.
  • Required behavior: reject export and flag governance evidence mismatch.

E10. Resilience Telemetry Emission Failure#

  • Trigger: error/recovery/degraded/closure events fail emission.
  • Required behavior: buffer/retry and surface degraded observability warning.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Detect and Classify Error Resilience/error UX Error normalization services
J2 Execute Guided Recovery Resilience/error UX Recovery orchestration and policy
J3 Enter and Operate Degraded Mode Resilience/error UX Dependency health and fallback stack
J4 Escalate Incident Resilience/error UX Notification/on-call routing
J5 Close Incident and Export Resilience/error UX Governance and retention services

4. Instrumentation Requirements#

Required events:

  • resilience_error_ux.journey.started
  • resilience_error_ux.journey.step.completed
  • resilience_error_ux.journey.blocked
  • resilience_error_ux.journey.recovered
  • resilience_error_ux.journey.completed

Required dimensions:

  • errorId, workflowId, correlationId, domain, severity, errorCode
  • actorId, actorRole, recoveryAction, degradedMode, escalationOwner
  • journeyId, stepId, outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00211)#

OST-00211 is complete only when:

  1. At least five resilience/error journeys are documented.
  2. At least ten deterministic edge cases are documented.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements and dimensions are documented.