# Contract: Managed Environment Canonical Route Cutover

**Status**: Logical route/link contract  
**Runtime persistence**: none  
**Compatibility**: no broad compatibility surface

## Canonical Route Families

| Product case | Canonical route family | Notes |
|---|---|---|
| Environment index | `/admin/workspaces/{workspace}/environments` | Workspace context required |
| Environment detail | `/admin/workspaces/{workspace}/environments/{environment}` | Environment must belong to workspace |
| Required permissions / readiness | `/admin/workspaces/{workspace}/environments/{environment}/required-permissions` | Existing repo-real route preferred |
| Diagnostics / provider health | `/admin/workspaces/{workspace}/environments/{environment}/diagnostics` or repo-real equivalent | If no route exists, implementation must document canonical equivalent |
| Access scopes / memberships | `/admin/workspaces/{workspace}/environments/{environment}/access-scopes` or repo-real equivalent | If no route exists, implementation must document canonical equivalent |
| Provider connections | `/admin/provider-connections...` | Tenantless admin resource with neutral scope context |
| Operations index | `/admin/workspaces/{workspace}/operations` | Workspace context required |
| Operation detail | `/admin/workspaces/{workspace}/operations/{run}` | Run entitlement required |

## Retired Route Families

| Route family | Contract |
|---|---|
| `/admin/t` | Absent or 404 |
| `/admin/t/*` | Absent or 404 |
| `/admin/tenants` | Not active product surface; 404 or documented safe canonical resolution only |
| `/admin/tenants/{environment}` | Not active product surface; 404 or documented safe canonical resolution only |
| `/admin/tenants/{environment}/edit` | 404 |
| `/admin/tenants/{environment}/memberships` | 404 or documented safe canonical access-scope resolution only |
| `/admin/tenants/{environment}/required-permissions` | 404 or documented safe canonical required-permissions resolution only |
| `/admin/tenants/{environment}/provider-connections...` | 404 |
| `/admin/operations` | Not final intended URL; normalize to workspace operations if workspace known |

## Link Helper Contract

If `ManagedEnvironmentLinks` is introduced or extended, it must provide or delegate these behaviors:

```php
ManagedEnvironmentLinks::indexUrl($workspace)
ManagedEnvironmentLinks::viewUrl($environment)
ManagedEnvironmentLinks::requiredPermissionsUrl($environment)
ManagedEnvironmentLinks::diagnosticsUrl($environment)
ManagedEnvironmentLinks::accessScopesUrl($environment)
ManagedEnvironmentLinks::operationsUrl($workspace, ?ManagedEnvironment $environment = null)
```

The exact method names may differ if the repo already has a canonical helper. The behavior must remain equivalent.

## Authorization Contract

- Link generation does not grant authorization.
- Page/action owners still enforce workspace membership and managed-environment entitlement.
- Non-member/out-of-scope access returns 404.
- Established member missing capability returns 403.
- Managed-environment scope cannot grant role/capability authority.

## Intended URL Contract

Rejected as final destination:

```text
/admin/t
/admin/t/*
/admin/tenants
/admin/tenants/*
/admin/tenants/*/required-permissions
/admin/tenants/*/provider-connections
external URLs
```

Normalized when safe:

```text
/admin/operations -> /admin/workspaces/{workspace}/operations
```

Fallback when unsafe:

```text
/admin/workspaces/{workspace}/overview
```

or:

```text
/admin/workspaces/{workspace}/environments
```