# ADR-0023: OSHUN Studio Workspace Context Switching

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN BFF  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio operators routinely switch between program, project, and workspace scopes
while working across Yemaya, Isis, Hathor, Aja, and Bellona. Context switching
must preserve intent, permissions, and execution continuity without introducing
stale or ambiguous state.

Without a governed context-switch model, Studio risks:

- accidental execution in the wrong program/project/workspace scope
- context loss between discovery, navigation, and execution surfaces
- inconsistent permission evaluation during switch transitions
- weak auditability for context-switch decisions and failures

## Decision Drivers

- **Context integrity**: context must remain explicit, validated, and stable.
- **Safety**: context switching must prevent unsafe mutations and stale writes.
- **Continuity**: users should resume workflows without losing intent.
- **Governance**: context switches must be observable and auditable.
- **Interoperability**: one switching contract across web, BFF, and domains.

## Considered Options

### Option 1: Route-Local Context State Only

Each route maintains independent context-switch behavior.

**Pros**:

- Simple local implementation.

**Cons**:

- High drift risk across surfaces.
- Inconsistent permission and audit behavior.

### Option 2: Client-Only Global Context Store

Maintain one browser-side context store without server-validated switching
contracts.

**Pros**:

- Faster local transitions.

**Cons**:

- Weak trust boundary for permission-sensitive changes.
- Risk of stale context under multi-tab or token refresh scenarios.

### Option 3: Governed Context-Switch Transaction Model (Chosen)

Adopt a canonical context envelope plus explicit switch transaction contracts
validated by BFF and consumed by Studio surfaces.

**Pros**:

- Deterministic, auditable switching behavior.
- Consistent permission checks and policy enforcement.
- Safer handoff across domains and workflows.

**Cons**:

- Higher upfront contract/governance complexity.

## Decision Outcome

**Chosen option**: Option 3.

Workspace context switching requirements:

1. **Canonical context envelope** containing `programId`, `projectId`,
   `workspaceId`, actor role, and switch intent metadata.
2. **Switch transaction contract** with preflight validation, policy check,
   commit/rollback outcomes, and reason codes.
3. **Workflow continuity contract** preserving return-path and pending-task
   hints through switch completion.
4. **Versioned compatibility rules** for context schema and permission payloads.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback controls.

## Normative Rules

### Context Envelope Contract

- Every switch operation must include `programId`, `projectId`, and
  `workspaceId`.
- Context envelope must include `role`, `switchIntent`, and `requestedAt`.
- Empty or partially specified context envelopes are invalid.

### Switch Transaction Contract

- Switch must execute as: `preflight -> policy check -> commit/rollback`.
- Policy-denied switches must not mutate active context.
- Failed commits must roll back to last confirmed context atomically.

### Continuity Contract

- Switch completion must preserve origin and back-path metadata.
- Pending workflow hints must be surfaced for user confirmation.
- Cross-domain route handoff must remain deterministic.

### Compatibility Contract

- Context schema changes require compatibility checks and explicit versioning.
- Breaking changes require migration guidance and rollback references.

### Release Validity Contract

A context-switch release is valid only when all are true:

- context envelope validation checks pass
- policy and entitlement checks pass
- commit/rollback semantics pass integration validation
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Web shell and Studio surfaces consume one context-switch contract for route
  and workflow continuity.
- BFF performs authoritative validation and policy checks for switch
  transactions.
- Navigation/deep-link layers preserve origin/back-stack metadata.
- Analytics pipelines capture switch request, commit, rollback, and denial
  outcomes.

## Acceptance Criteria (OST-00081)

`OST-00081` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0029-oshun-studio-workspace-context-switching.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines context envelope, switch transaction, continuity, compatibility,
   and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0022`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `apps/oshun/web/src/navigation/routes.ts`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Safer and more predictable workspace-context transitions.
- Stronger auditability and operational diagnostics for context changes.
- Better continuity across cross-domain workflows.

### Negative

- Additional coordination for contract and policy evolution.
- Requires strict discipline around context-schema migrations.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0017-offline-caching-and-sync-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0026-oshun-studio-navigation-and-command-surfaces.md`
- `docs/adr/ADR-0027-oshun-studio-search-and-global-discovery.md`
- `docs/adr/ADR-0028-oshun-studio-cross-domain-entity-model.md`

## References

- `apps/oshun/web/src/components/DomainSwitcherEntryPanel.tsx`
- `apps/oshun/web/src/navigation/routes.ts`
- `libs/oshun/domain-registry/src/index.ts`
- `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`