Eve library

OSHUN Studio Resilience and Error UX Dependency and Data Contract Map

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

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.