# Data Model: Managed Environment Canonical Route Cutover & Legacy Tenant Surface Retirement

**Date**: 2026-05-12  
**Runtime persistence changes**: none planned.

## Existing Domain Truth

| Concept | Current role in this spec | Persistence change |
|---|---|---|
| Workspace | Primary SaaS/admin context and route scope | None |
| ManagedEnvironment | Secondary managed target context under a workspace | None |
| Tenant / internal tenant model | Existing technical implementation detail where repo-real | None |
| WorkspaceMembership | Role/capability authority | None |
| ManagedEnvironmentMembership | Access-scope / narrowing-only overlay | None |
| ProviderConnection | Tenantless admin resource with neutral scope context | None |
| OperationRun | Existing execution truth linked through workspace operations routes | None |

## Route Truth

| Old route family | New truth | Data implication |
|---|---|---|
| `/admin/t...` | Retired / 404 | None |
| `/admin/tenants...` | Retired as active product surface | None |
| `/admin/tenants/{environment}/required-permissions` | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` or repo-real equivalent | None |
| `/admin/tenants/{environment}/provider-connections...` | `/admin/provider-connections...` with neutral scope context or canonical environment context | None |
| `/admin/operations` | `/admin/workspaces/{workspace}/operations` when workspace known | None |

## New Structures

No new persisted tables, columns, enum/status families, lifecycle states, or source-of-truth records are introduced.

One bounded runtime helper may be introduced if needed:

```text
App\Support\ManagedEnvironmentLinks
```

Allowed helper responsibility:

- Generate canonical URLs for existing workspace/environment routes.
- Require enough workspace/environment context to avoid ambiguous routing.
- Delegate operations URLs to existing OperationRun link helpers.

Forbidden helper responsibility:

- Acting as a generic route registry.
- Creating compatibility redirects.
- Inferring authorization from route generation.
- Introducing a new persistent route mapping.

## RBAC Semantics

- Workspace membership carries role/capability authority.
- Managed-environment membership narrows access only.
- Non-member or out-of-scope workspace/environment access returns 404.
- Established member missing capability returns 403.
- Legacy `role` data on managed-environment membership, if present, is not authority.

## Compatibility

No compatibility data model exists for this cutover. Historical rows, old route aliases, and old helper aliases are not preserved.