Eve library

OSHUN Studio Workspace Context Switching Journeys and Edge Cases

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
  • 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.