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.mddocs/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#
- Active context must always be explicit and user-verifiable.
- Context switches must be validated before committing target scope.
- Unauthorized switches must fail safely without mutating active context.
- 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:
- Select target program/project/workspace.
- Run preflight context validation.
- Evaluate role-policy authorization for target scope.
- Commit context switch if policy allows.
- 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:
- Trigger context switch from active workflow.
- Capture pending-flow and back-stack continuity metadata.
- Execute target-context switch transaction.
- Surface resumable workflow hints in target context.
- 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:
- Request target context switch.
- Run entitlement and policy checks.
- Deny switch with explicit reason.
- Keep active context unchanged.
- 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:
- Attempt context switch commit.
- Detect commit-stage failure.
- Roll back to last confirmed context.
- Surface recovery diagnostics and retry options.
- 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:
- Review validation evidence for switch contracts.
- Approve and promote release candidate.
- Monitor switch success/deny/rollback telemetry.
- Roll back to certified contract if regressions appear.
- 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, orworkspaceId. - 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.startedworkspace_context_switch.journey.step.completedworkspace_context_switch.journey.blockedworkspace_context_switch.journey.recoveredworkspace_context_switch.journey.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,targetProgramId,targetProjectId,targetWorkspaceIdactorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00083)#
OST-00083 is complete only when:
- At least five workspace context-switching journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.