Eve library

OSHUN Studio Workspace Context Switching Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF
Last Updated: 2026-02-23
Related: docs/adr/ADR-0023-oshun-studio-workspace-context-switching.md

Purpose#

Define dependencies and canonical contracts for workspace context switching across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00082.

Sources Used#

  • apps/oshun/web/src/components/DomainSwitcherEntryPanel.tsx
  • apps/oshun/web/src/navigation/routes.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#

  • Context-switch entry surfaces: DomainSwitcherEntryPanel + Studio routes.
  • Route and back-stack context contracts: apps/oshun/web/src/navigation/routes.ts.
  • Domain metadata authority: libs/oshun/domain-registry.
  • Permission/identity boundaries: session payloads + role policy checks.
  • Telemetry and audit: libs/oshun/analytics + web/BFF pipelines.

1.2 Domain Dependency Graph#

  • Context Switching -> Yemaya: project context determines asset/workspace routing and collaboration scope.
  • Context Switching -> Isis: model/workflow actions require deterministic program/project scope continuity.
  • Context Switching -> Hathor: world/lore editing requires safe workspace boundary transitions.
  • Context Switching -> Aja: timeline/media review requires preserved origin, playback, and annotation context.
  • Context Switching -> Bellona: build/runtime operations require explicit scope to prevent wrong-environment actions.
  • Project Obsidian -> all: governance and release controls for context-switch safety, permissions, and observability.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Context envelope schema Studio Architecture Web + BFF + domain adapters Context schema WorkspaceContextEnvelope
Switch transaction preflight/commit OSHUN BFF + Web Studio surfaces Transaction API WorkspaceContextSwitchRequest
Continuity and return-path state Navigation Platform Studio + domain routes Route context payload WorkspaceContextContinuityState
Policy and permission outcomes Security + Platform Identity Ops + Studio governance Decision payload WorkspaceContextSwitchDecision
Audit and telemetry evidence Data Platform Governance + SRE Event stream WorkspaceContextSwitchAuditEvent

3. Canonical Contracts#

3.1 WorkspaceContextEnvelope#

ts
export interface WorkspaceContextEnvelope {
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  switchIntent: 'navigation' | 'execution' | 'review' | 'recovery';
  contextVersion: string;
  requestedAt: string;
}

3.2 WorkspaceContextSwitchRequest#

ts
export interface WorkspaceContextSwitchRequest {
  requestId: string;
  actorId: string;
  source: WorkspaceContextEnvelope;
  target: WorkspaceContextEnvelope;
  preserveContinuity: boolean;
  reason?: string;
}

3.3 WorkspaceContextSwitchDecision#

ts
export interface WorkspaceContextSwitchDecision {
  requestId: string;
  outcome: 'allowed' | 'denied' | 'rollback';
  policyChecks: Array<{
    policyId: string;
    status: 'pass' | 'fail';
    reason?: string;
  }>;
  committedContext?: WorkspaceContextEnvelope;
  rollbackContext?: WorkspaceContextEnvelope;
  decisionAt: string;
}

3.4 WorkspaceContextContinuityState#

ts
export interface WorkspaceContextContinuityState {
  originRoute: string;
  backStack: string[];
  pendingFlowHints: Array<{
    flowId: string;
    label: string;
    resumable: boolean;
  }>;
  preservedQuery?: string;
}

3.5 WorkspaceContextSwitchAuditEvent#

ts
export interface WorkspaceContextSwitchAuditEvent {
  eventId: string;
  action:
    | 'context.switch.requested'
    | 'context.switch.allowed'
    | 'context.switch.denied'
    | 'context.switch.committed'
    | 'context.switch.rolled_back';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  targetProgramId: string;
  targetProjectId: string;
  targetWorkspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}

4. Validation Rules#

  • Production promotion is blocked unless source/target context envelopes are validated for required fields and compatibility.
  • Context switch commit is blocked unless policy checks pass for the target workspace scope.
  • Failed commits must restore last confirmed context without partial mutation.
  • All allow/deny/rollback outcomes must emit WorkspaceContextSwitchAuditEvent records.

5. Acceptance Criteria (OST-00082)#

OST-00082 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 context envelope, switch request/decision, continuity state, and audit events are documented.
  4. Ownership boundaries and validation rules are explicit.