Disciplines · Decisions (ADRs)

ADR-0023: OSHUN Studio Workspace Context Switching

Studio operators routinely switch between program, project, and workspace scopes while working across Yemaya, Isis, Hathor, Aja, and Bellona.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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