TenantAtlas/specs/279-workspace-managed-environment-core/research.md

# Research: Workspace-first Managed Environment Core Cutover

**Date**: 2026-05-06  
**Branch**: `279-workspace-managed-environment-core`

## Decision 1: Use one breaking in-place cutover with no `Tenant` compatibility layer

- **Decision**: Replace `Tenant` as the active managed-target core directly instead of introducing alias models, dual-read paths, or dual-write migrations.
- **Rationale**: The repo is still pre-production, the constitution explicitly rejects speculative compatibility paths, and the current coupling spans too many seams for an adapter layer to stay honest.
- **Alternatives considered**:
  - `Tenant` wrapper over `ManagedEnvironment`: rejected because it would preserve the wrong core truth and spread mixed nouns.
  - dual columns (`tenant_id` plus `managed_environment_id`): rejected because it would violate the pre-production lean doctrine and make later specs harder, not easier.

## Decision 2: Keep the current `/admin/t/{environment}` path temporarily as the only bounded exception

- **Decision**: Allow the existing public `/admin/t/{environment}` path family to remain temporarily while rebinding it to `ManagedEnvironment`.
- **Rationale**: The current cutover already replaces the core entity, memberships, query helpers, and panel binding. Folding the full workspace-first public route rewrite into the same slice would collapse Spec `280` into `279` and make the first cutover package too broad.
- **Alternatives considered**:
  - immediate public route-family rewrite: rejected because it belongs to Spec `280` and would widen review scope too far.
  - second compatibility route family: rejected because the cutover must not carry two public path families at once.

## Decision 3: Replace current tenant-context helpers in place instead of layering new adapters

- **Decision**: Retarget or rename the existing tenant-context seams (`WorkspaceContext`, Filament panel binding, resource query helpers, global-search helpers, route builders) in place.
- **Rationale**: The current helper seams are the correct ownership points. A new parallel `ManagedEnvironmentContext` layer wrapped around tenant helpers would create drift immediately.
- **Alternatives considered**:
  - keep tenant helpers and add environment adapters: rejected because it creates a second context vocabulary.
  - local page-by-page context replacement: rejected because the problem is cross-cutting and shared.

## Decision 4: Keep `ManagedEnvironment` provider-neutral and defer provider extraction to Spec `281`

- **Decision**: `ManagedEnvironment` owns neutral managed-target identity only. Provider-specific fields such as Entra tenant IDs, Graph configuration, domains, or consent details stay outside the new root entity.
- **Rationale**: The whole point of the cutover is to stop provider-specific semantics from defining the platform core. The repo already has provider-owned seams that can carry this data until Spec `281` normalizes them.
- **Alternatives considered**:
  - copy current `Tenant` provider fields to `ManagedEnvironment`: rejected because it would deepen Microsoft coupling.
  - extract provider profiles in the same slice: rejected because Spec `281` already owns that follow-up.

## Decision 5: Retarget membership semantics without broad RBAC redesign

- **Decision**: Replace current tenant-membership truth with managed-environment membership truth while preserving current workspace and capability semantics.
- **Rationale**: The cutover needs environment-scoped access control to keep current pages safe, but a broader RBAC scope redesign is already reserved for Spec `285`.
- **Alternatives considered**:
  - leave memberships tenant-shaped temporarily: rejected because the active root model would still leak tenant-core assumptions.
  - widen capabilities or role families now: rejected because that would collapse Spec `285` into the core cutover.

## Decision 6: Use unit + feature + browser + guard checks as the narrowest honest proof

- **Decision**: Plan one managed-environment unit family, one feature family, one browser smoke, and one legacy-core guard family.
- **Rationale**: The cutover changes both internal identity rules and end-to-end context selection. Feature tests alone are not enough to prove the shell/chooser still works, and browser coverage alone would hide legacy-core drift.
- **Alternatives considered**:
  - feature tests only: rejected because the cutover changes end-to-end context entry.
  - heavy-governance or multi-browser rollout: rejected because the slice is core infrastructure, not new multi-surface behavior.

## Final Research Outcome

- `279` should remain the breaking core entity cutover only.
- The only allowed public-path deviation is temporary `/admin/t/{environment}` retention while it binds `ManagedEnvironment`.
- Existing tenant-context seams should be replaced in place, not wrapped.
- `ManagedEnvironment` must stay provider-neutral.
- Membership semantics move with the core entity, but broader RBAC redesign remains deferred.
- Unit, feature, browser, and guard coverage together are the narrowest honest proof.