# ADR-0028: OSHUN Studio Enterprise Tenant Isolation

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

## Context and Problem Statement

Studio is expanding into enterprise operating models where multiple tenant
organizations run isolated governance workflows on shared platform
infrastructure. Current Studio patterns assume shared program context and need
explicit tenant-boundary contracts for policy, data, and action safety.

Without first-class tenant isolation architecture, OSHUN risks:

- cross-tenant data visibility or mutation leaks
- inconsistent policy enforcement at tenant boundaries
- weak auditability of tenant-scoped actions and decisions
- operational incidents with broad blast radius across organizations

## Decision Drivers

- **Security boundaries**: strict tenant-level data and action isolation.
- **Operational safety**: deterministic tenant-scoped policy outcomes.
- **Compliance readiness**: auditable tenant lineage and access evidence.
- **Scalability**: support enterprise tenancy without workflow regression.
- **Interoperability**: preserve consistent behavior across all Studio domains.

## Considered Options

### Option 1: Logical Segmentation Only in UI

Represent tenants in UI but rely on shared backend data access paths.

**Pros**:

- Lower immediate implementation effort.

**Cons**:

- Insufficient isolation guarantees.
- Higher risk of cross-tenant leakage.

### Option 2: Per-Domain Tenant Isolation Implementations

Each Studio domain owns separate tenant isolation logic.

**Pros**:

- Domain-level flexibility.

**Cons**:

- Policy drift and inconsistent enforcement.
- Harder centralized governance and auditing.

### Option 3: Unified Enterprise Tenant Isolation Contract Model (Chosen)

Adopt one tenant-boundary contract model across Studio surfaces and services,
with explicit tenant-scoped identity, policy, data, and observability controls.

**Pros**:

- Consistent and strong tenant isolation semantics.
- Better governance, incident containment, and compliance evidence.
- Reduced cross-domain policy drift.

**Cons**:

- Higher contract-management complexity and migration overhead.

## Decision Outcome

**Chosen option**: Option 3.

Enterprise tenant isolation requirements:

1. **Tenant context contract** with immutable tenant identity and scope.
2. **Tenant policy contract** for allow/deny behavior on tenant-scoped actions.
3. **Tenant data-boundary contract** for read/write partition enforcement.
4. **Compatibility contract** for tenant schema/policy version evolution.
5. **Release governance** with validation, approval, telemetry/audit, and
   rollback controls.

## Normative Rules

### Tenant Context Contract

- Every governed Studio request must include tenant identity and scope metadata.
- Tenant context must remain immutable during single action execution.
- Missing or invalid tenant context defaults to deny for privileged actions.

### Tenant Policy Contract

- Tenant-scoped actions must evaluate role + entitlement + tenant policy.
- Denied outcomes must not mutate tenant or shared governance state.
- Cross-tenant requests must be blocked unless explicitly authorized.

### Tenant Data-Boundary Contract

- Read/write paths must resolve within tenant partitions only.
- Cross-tenant joins are prohibited unless explicitly approved and audited.
- Tenant boundary violations must trigger hard fail and incident signal.

### Compatibility Contract

- Tenant schema and policy changes require compatibility checks.
- Breaking changes require migration guidance and rollback references.
- Tenant identifiers and lineage fields must remain backward compatible.

### Release Validity Contract

A tenant-isolation release is valid only when all are true:

- tenant context validation checks pass
- tenant policy allow/deny checks pass
- tenant data-boundary enforcement checks pass
- telemetry/audit records are complete
- rollback strategy is documented

## Architecture Implications

- Studio web surfaces expose explicit tenant context and boundary diagnostics.
- BFF and downstream services enforce authoritative tenant partition controls.
- Shared identity/policy services become tenant-scoped dependencies.
- Analytics and audit pipelines track tenant-scoped policy and boundary events.

## Acceptance Criteria (OST-00121)

`OST-00121` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0034-oshun-studio-enterprise-tenant-isolation.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines tenant context, tenant policy, tenant data-boundary,
   compatibility, and release-validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0027`, especially `ADR-0010`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `libs/oshun/auth`, and `libs/oshun/domain-registry`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Stronger tenant isolation and reduced cross-tenant blast radius.
- Better policy consistency and operational clarity for enterprise workflows.
- Improved compliance/audit readiness for tenant-governed operations.

### Negative

- Increased tenancy contract complexity and migration overhead.
- Requires stricter enforcement and validation discipline across services.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0032-oshun-studio-session-and-device-management.md`
- `docs/adr/ADR-0033-oshun-studio-rbac-and-permission-policy-ux.md`

## References

- `libs/oshun/auth/src/index.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`