# OSHUN Studio Workspace Context Switching Dependency and Data Contract Map

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.
