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.tsxapps/oshun/web/src/navigation/routes.tslibs/oshun/domain-registry/src/index.tsdocs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.mddocs/releases/v1/design/ux-principles.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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
WorkspaceContextSwitchAuditEventrecords.
5. Acceptance Criteria (OST-00082)#
OST-00082 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for context envelope, switch request/decision, continuity state, and audit events are documented.
- Ownership boundaries and validation rules are explicit.