ADR 10: Ambient Multi-Tenant SaaS Isolation Model
Amended by ADR-0113 (Consequences). Amended by ADR-0114 (Consequences).
Summary
ContextVar tenant propagation, hard reset safety, and storage query pushdown.
Context
Multi-tenant SaaS architectures require absolute data isolation. Manual passing of tenant IDs is error-prone, while poorly isolated async contexts can leak tenant state across coroutines.
Decision
- Ambient tenant context is propagated across async tasks and threads via
tenant_scope(tenant_id). - Hard-clear reset semantics:
clear_tenant_context()invalidates active context; attempting to restore a cleared token raisesTenantContextResetErrorto prevent zombie context revival. - Precondition enforcement on aggregate load: repositories verify active tenant context before touching disk.
- Storage-level tenant filtering: push
tenant_idinto adapter queries (FeedReadOptions(tenant_id=...)) preventing cross-tenant memory leakage.
Consequences
- Write-side tenant validation on
TenantAwareRepository. Under an active scope, the repository also refuses to load, probe, or append to a stream that another tenant owns (ADR-0113). This is a repository-level control. It does not cover direct store access, unscoped repositories, or the global uniqueness of event ids. Under an active scope, read models throughTenantScopedReadModelRepositoryand DLQ reads and state changes through the DLQ repository match only rows of the active tenant (ADR-0114). Checkpoints are not tenant-scoped. Each per-tenant projection instance uses its own name. This is an application-level control. It does not cover direct adapter access or the global feed. - Clean application code without polluting domain signatures with tenant parameters.
- Storage pushdown maximizes database index efficiency.