# OSHUN Studio Workspace Context Switching Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-workspace-context-switching-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio
workspace context-switching governance.

This document is the execution artifact for `OST-00083`.

## Personas

- Program Operator
- Domain Integrator
- Security Reviewer
- Reliability Engineer
- Production Coordinator

## Journey Principles

1. Active context must always be explicit and user-verifiable.
2. Context switches must be validated before committing target scope.
3. Unauthorized switches must fail safely without mutating active context.
4. Failed commits must roll back atomically to last confirmed context.

## 1. Primary Journeys

### J1. Program/Project/Workspace Context Switch Commit

**Goal**: Switch active Studio scope to a new target context safely.

**Entry**: `Studio -> Workspace Context Switching -> Switch Console`

**Steps**:

1. Select target program/project/workspace.
2. Run preflight context validation.
3. Evaluate role-policy authorization for target scope.
4. Commit context switch if policy allows.
5. Confirm updated context banner and route continuity.

**Success State**:

- Active context is switched with deterministic commit evidence.

### J2. Context Switch with Workflow Continuity Preservation

**Goal**: Preserve route origin and resumable flow hints after context switch.

**Entry**: `Context switch action while workflow is in progress`

**Steps**:

1. Trigger context switch from active workflow.
2. Capture pending-flow and back-stack continuity metadata.
3. Execute target-context switch transaction.
4. Surface resumable workflow hints in target context.
5. Resume or dismiss preserved workflow hints.

**Success State**:

- Switch completes and users can continue work without losing intent.

### J3. Unauthorized Context Switch Denial

**Goal**: Block context switch attempts when target scope is not permitted.

**Entry**: `Switch request with insufficient role permissions`

**Steps**:

1. Request target context switch.
2. Run entitlement and policy checks.
3. Deny switch with explicit reason.
4. Keep active context unchanged.
5. Emit denial audit evidence.

**Success State**:

- Unauthorized switch is safely denied with no context mutation.

### J4. Failed Switch Rollback Recovery

**Goal**: Recover when commit fails after preflight/policy checks pass.

**Entry**: `Switch transaction commit-stage failure`

**Steps**:

1. Attempt context switch commit.
2. Detect commit-stage failure.
3. Roll back to last confirmed context.
4. Surface recovery diagnostics and retry options.
5. Record rollback evidence for operations review.

**Success State**:

- Last confirmed context is restored deterministically.

### J5. Context Switch Governance Promotion and Rollback

**Goal**: Promote context-switch contract changes safely.

**Entry**: `Review & Approvals` or `Observability alert`

**Steps**:

1. Review validation evidence for switch contracts.
2. Approve and promote release candidate.
3. Monitor switch success/deny/rollback telemetry.
4. Roll back to certified contract if regressions appear.
5. Publish mitigation actions and evidence chain.

**Success State**:

- Context-switch release is either stable or safely rolled back.

## 2. Critical Edge Cases

### E1. Missing Required Target Context Field

- Trigger: target context missing `programId`, `projectId`, or `workspaceId`.
- Required behavior: fail preflight and block switch commit.

### E2. Source Context Drift During Switch

- Trigger: source context changes while switch is in-flight.
- Required behavior: cancel commit and request user re-confirmation.

### E3. Unauthorized Target Scope

- Trigger: role lacks permission for target context.
- Required behavior: deny request and preserve active context.

### E4. Commit-Stage Transaction Failure

- Trigger: commit fails after passing validation.
- Required behavior: roll back atomically and emit rollback audit event.

### E5. Continuity Metadata Loss

- Trigger: route origin/back-stack metadata cannot be preserved.
- Required behavior: switch to safe fallback route and emit continuity error.

### E6. Pending Workflow Conflict

- Trigger: active workflow conflicts with target context constraints.
- Required behavior: require explicit user resolution before switch commit.

### E7. Multi-Tab Context Race

- Trigger: competing tab commits another context switch.
- Required behavior: detect stale context and force reconciliation.

### E8. Entitlement Payload Staleness

- Trigger: switch uses stale or expired policy payload.
- Required behavior: refresh identity payload and retry policy check.

### E9. Telemetry/Audit Emission Failure

- Trigger: switch events fail to emit to telemetry sinks.
- Required behavior: buffer and retry while surfacing degraded observability.

### E10. Missing Rollback Reference

- Trigger: release candidate lacks certified rollback contract version.
- Required behavior: block production promotion.

## 3. Journey-to-Surface Mapping

| Journey                                                 | Primary Surface             | Supporting Surfaces       |
| ------------------------------------------------------- | --------------------------- | ------------------------- |
| J1 Program/Project/Workspace Context Switch Commit      | Workspace Context Switching | Navigation/Commands       |
| J2 Context Switch with Workflow Continuity Preservation | Workspace Context Switching | Domain routes             |
| J3 Unauthorized Context Switch Denial                   | Workspace Context Switching | Security/Policy           |
| J4 Failed Switch Rollback Recovery                      | Workspace Context Switching | Observability             |
| J5 Context Switch Governance Promotion and Rollback     | Review & Approvals          | Observability, Governance |

## 4. Instrumentation Requirements

Required events:

- `workspace_context_switch.journey.started`
- `workspace_context_switch.journey.step.completed`
- `workspace_context_switch.journey.blocked`
- `workspace_context_switch.journey.recovered`
- `workspace_context_switch.journey.completed`

Required dimensions:

- `programId`, `projectId`, `workspaceId`
- `journeyId`, `stepId`, `targetProgramId`, `targetProjectId`,
  `targetWorkspaceId`
- `actorRole`, `outcome`, `latencyMs`, `errorCode`

## 5. Acceptance Criteria (OST-00083)

`OST-00083` is complete only when:

1. At least five workspace context-switching journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
