Eve library

OSHUN Studio Complex Interaction Patterns Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Product Design + OSHUN Web
Last Updated: 2026-02-23
Related: docs/adr/ADR-0019-oshun-studio-complex-interaction-patterns-and-state-orchestration.md

Purpose#

Define dependencies and canonical contracts required to govern complex interaction patterns across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00050.

Sources Used#

  • 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
  • docs/domains/yemaya/service-catalog.md
  • docs/domains/isis/service-catalog.md
  • docs/domains/hathor/service-catalog.md
  • docs/domains/aja/service-catalog.md
  • docs/domains/bellona/service-catalog.md
  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/ergonomics-requirements.md
  • libs/oshun/ui
  • libs/oshun/analytics
  • apps/oshun/web/src/design-system/tokens.ts

1. Dependency Overview#

1.1 Control Surfaces#

  • Interaction primitives and shells: libs/oshun/ui
  • Web composition layer: apps/oshun/web/src/components and apps/oshun/web/src/design-system
  • Studio governance UX: apps/oshun/web/src/components/studio
  • Telemetry and audit contracts: libs/oshun/analytics + Studio sinks

1.2 Domain Dependency Graph#

  • Complex Interaction Governance -> Yemaya: project orchestration boards and collaboration workflows require deterministic multi-step interactions.
  • Complex Interaction Governance -> Isis: pipeline generation and review workflows require robust async-state handling and recovery.
  • Complex Interaction Governance -> Hathor: narrative composition/review flows require stable long-running orchestration behavior.
  • Complex Interaction Governance -> Aja: motion/timeline authoring requires deterministic sequencing and rollback-safe edits.
  • Complex Interaction Governance -> Bellona: runtime/build orchestration needs resilient command batching and diagnostics.
  • Project Obsidian -> all: release governance and compliance for advanced interaction semantics.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Workflow orchestration schema Product Design + Web Platform Domain teams Workflow bundle InteractionWorkflowBundle
State transition validation QA + Accessibility Release managers Validation report InteractionStateValidationReport
Concurrency and timeout behavior Web Platform SRE + Product Execution report InteractionConcurrencyReport
Domain interaction parity Domain adapters + QA Program ops Parity report DomainInteractionParityReport
Audit/telemetry stream Data Platform Governance + SRE Event stream InteractionAuditEvent

3. Canonical Contracts#

3.1 InteractionWorkflowBundle#

ts
export interface InteractionWorkflowBundle {
  bundleId: string;
  version: string;
  scope: 'studio-complex-interactions';
  generatedAt: string;
  generatedBy: string;
  workflows: Array<{
    workflowId: string;
    surface: string;
    steps: string[];
    supportedActions: Array<'run' | 'retry' | 'cancel' | 'reset' | 'rollback'>;
    timeoutMs: number;
  }>;
}

3.2 InteractionStateValidationReport#

ts
export interface InteractionStateValidationReport {
  reportId: string;
  bundleVersion: string;
  checkedAt: string;
  checkedBy: string;
  checks: {
    transitionDeterminismPass: boolean;
    recoveryPathPass: boolean;
    accessibilityFocusContinuityPass: boolean;
    timeoutAndCancelPass: boolean;
    partialCompletionMessagingPass: boolean;
  };
  violations: Array<{
    workflowId: string;
    issue: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
  }>;
  status: 'pass' | 'fail';
}

3.3 InteractionConcurrencyReport#

ts
export interface InteractionConcurrencyReport {
  reportId: string;
  bundleVersion: string;
  generatedAt: string;
  workflows: Array<{
    workflowId: string;
    parallelTaskCount: number;
    aggregateOutcome: 'success' | 'error' | 'partial';
    timeoutTriggered: boolean;
    cancellationTriggered: boolean;
  }>;
  status: 'pass' | 'fail';
}

3.4 DomainInteractionParityReport#

ts
export interface DomainInteractionParityReport {
  reportId: string;
  bundleVersion: string;
  domains: Array<'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona'>;
  generatedAt: string;
  driftFindings: Array<{
    domain: string;
    surface: string;
    workflowId: string;
    expectedVersion: string;
    actualVersion: string;
  }>;
  parityStatus: 'pass' | 'fail';
}

3.5 InteractionAuditEvent#

ts
export interface InteractionAuditEvent {
  eventId: string;
  action:
    | 'interaction.bundle.publish.requested'
    | 'interaction.bundle.publish.completed'
    | 'interaction.validation.requested'
    | 'interaction.validation.completed'
    | 'interaction.parity.sync.requested'
    | 'interaction.parity.sync.completed'
    | 'interaction.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}

4. Validation Rules#

  • Production promotion is blocked unless InteractionStateValidationReport.status = 'pass'.
  • Production promotion is blocked unless DomainInteractionParityReport.parityStatus = 'pass'.
  • All publish/validate/sync actions require complete context and policy authorization.
  • All allow/deny outcomes must emit InteractionAuditEvent records.

5. Acceptance Criteria (OST-00050)#

OST-00050 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 orchestration bundle, state validation, concurrency, parity, and audit streams are documented.
  4. Ownership boundaries and validation rules are explicit.