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.mddocs/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#
- Every error state must map to a canonical envelope and severity.
- Recovery guidance must be deterministic, policy-aware, and idempotent.
- Degraded mode must preserve safe continuity with explicit capability limits.
- 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:
- Capture raw domain failure payload.
- Normalize into canonical error envelope.
- Assign severity and impact scope.
- Persist error record with workflow/correlation identifiers.
- 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:
- Present available recovery actions (
retry,rollback,replay,manual_override). - Validate role and policy authorization.
- Execute idempotent recovery transition.
- Persist recovery outcome and lineage metadata.
- 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:
- Detect degraded-mode trigger and affected capabilities.
- Enter degraded mode with explicit capability restrictions.
- Route eligible workflows through fallback paths.
- Surface blocked actions and fallback status to operators.
- 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:
- Create escalation record with severity and impact context.
- Route ownership to on-call and domain leads.
- Track acknowledgement and mitigation status.
- Update operator-visible incident timeline.
- 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:
- Capture root-cause and remediation summary.
- Validate closure requirements and policy checks.
- Package error, recovery, degraded, and escalation evidence.
- Persist closure record and retention tags.
- 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
workflowIdorcorrelationId. - 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.startedresilience_error_ux.journey.step.completedresilience_error_ux.journey.blockedresilience_error_ux.journey.recoveredresilience_error_ux.journey.completed
Required dimensions:
errorId,workflowId,correlationId,domain,severity,errorCodeactorId,actorRole,recoveryAction,degradedMode,escalationOwnerjourneyId,stepId,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00211)#
OST-00211 is complete only when:
- At least five resilience/error journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.