TenantAtlas/specs/338-workspace-environment-resource-scope-contract/plan.md

# Implementation Plan: Spec 338 - Workspace / Environment Resource Scope Contract

- Branch: `338-workspace-environment-resource-scope-contract`
- Date: 2026-05-30
- Spec: `specs/338-workspace-environment-resource-scope-contract/spec.md`
- Input: User-provided Spec 338 draft + repo inspection for link/query seams.

## Summary

Harden TenantPilot’s resource scope contract by tightening the canonical deep-link and query contract for workspace hubs and by eliminating first-party helper outputs that encode Filament internals (`tableFilters[...]`) as a product-level URL contract.

This is contract-first and targeted:

- `OperationRunLinks::index(..., operationType: ...)` must stop emitting `tableFilters[type][value]`.
- Evidence scope special casing under `/admin/evidence/*` must be either proven real and contractual, or removed as stale ambiguity.
- Environment-owned sidebar navigation must keep environment-owned entries primary and move workspace-wide/admin links into explicitly labeled cross-scope groups.
- Baseline ownership/navigation is regression-only (Spec 320 already completed; do not reopen).

## Technical Context

- Language/Version: PHP 8.4.15, Laravel 12.52.x.
- Primary Dependencies: Filament 5.2.x, Livewire 4.1.x, Pest 4.x, Tailwind CSS 4.x.
- Storage: PostgreSQL; no schema change expected.
- Testing: Pest Feature tests + minimal browser smoke only if navigation presentation is materially affected.
- Validation Lanes: fast-feedback (Feature) + browser (smoke, scoped).
- Target Platform: Sail locally; Dokploy/container deployment posture unchanged.
- Project Type: Laravel monolith under `apps/platform`.
- Constraints: No new persisted truth, migrations, packages, env vars, queue/scheduler changes, or route architecture rewrite.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed existing operator-facing scope/link behavior (navigation + deep links).
- **Affected surfaces**:
  - Workspace hub links to Operations (`OperationRunLinks` and any `CanonicalNavigationContext` filter payload usage).
  - Evidence Overview hub + “clear environment context” redirect behavior.
  - Environment → workspace hub “filtered” links (`environment_id` must remain canonical).
  - Environment sidebar grouping for workspace-wide/admin links.
- **Native vs custom**: native Filament + existing project navigation helpers; no custom UI framework.
- **Shared-family relevance**: navigation entry points, scope presentation, deep links, hub filtering, OperationRun “view in collection” links.
- **State layers in scope**: shell scope (route-owned), URL query contract, local table filter state (internal translation only).
- **Handling modes**: review-mandatory.
- **Required tests / smoke**:
  - Feature tests for URL contract + helper output.
  - Optional minimal browser smoke when sidebar/scope presentation changes are user-visible.
- **UI/Productization coverage**: no new routes/pages expected; capture screenshots only when needed to prove a scope regression fix.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched (expected)**:
  - `apps/platform/app/Support/OperationRunLinks.php`
  - `apps/platform/app/Support/Navigation/CanonicalNavigationContext.php`
  - `apps/platform/app/Support/Navigation/AdminSurfaceScope.php`
  - `apps/platform/app/Support/Navigation/WorkspaceHubNavigation.php`
  - `apps/platform/app/Http/Controllers/ClearEnvironmentContextController.php`
  - `apps/platform/app/Support/Navigation/WorkspaceHubRegistry.php`
  - `apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php`
- **New abstraction introduced?**: `WorkspaceHubNavigation`, a narrow helper for environment-surface hub grouping and explicit `environment_id` URL carry.
- **Shared abstractions reused**: existing `AdminSurfaceScope` + hub registry + navigation context; do not create a second taxonomy framework.
- **Bounded deviation**: if Filament requires `tableFilters` internally, keep it internal (page-level translation) and keep first-party helper output contract stable.

## OperationRun UX Impact

Link semantics only (no new OperationRun types, no lifecycle changes):

- Stop emitting Filament internals as deep-link contract for operation type filtering.
- Decide between:
  1) `operation_type=<canonical-code>` accepted by Operations page and mapped to internal table state, or
  2) removing operation-type deep-linking entirely if safe mapping is not feasible without bloat.

## Implementation Approach

### Phase 1 — Repo truth + failing tests first

- Inventory current first-party helper outputs and navigation contexts that emit:
  - `tableFilters[...]` (confirmed in `OperationRunLinks`; re-check `CanonicalNavigationContext` usage and call sites)
  - legacy `/admin/evidence/*` special casing branches (`AdminSurfaceScope`, `ClearEnvironmentContextController`)
- Add failing tests that lock the desired contract:
  - `OperationRunLinks::index(..., operationType: ...)` must not contain `tableFilters`.
  - Evidence Overview is workspace hub; any `/admin/evidence/*` environment-scope handling is either intentional + tested or removed.

### Phase 2 — OperationRunLinks query contract

- Change `OperationRunLinks::index`:
  - replace `tableFilters[type][value]` emission with a stable query key (`operation_type`) or remove operation-type deep linking.
- Update the Operations page boundary to translate `operation_type` into internal table state where needed (keep `environment_id` canonical).

### Phase 3 — Navigation context payload hygiene

- Re-check `CanonicalNavigationContext::toQuery()` usage:
  - prefer keeping navigation metadata under `nav[...]` only,
  - avoid emitting additional top-level filter payload that encodes `tableFilters` for hub filtering when `environment_id` is sufficient.
- Adjust the specific call sites (e.g. RelatedNavigationResolver contexts) that currently inject `tableFilters[managed_environment_id]` into query strings when linking to Operations.

### Phase 4 — Evidence scope special casing

- Verify actual route inventory for `/admin/evidence/*` beyond overview.
- Remove stale classification or redirect rules only when route inventory proves they are not real, or explicitly document + test the remaining route family if it is still reachable.

### Phase 5 — Validation and regression posture

- Split Environment sidebar IA:
  - keep environment-owned resources in their domain groups,
  - move workspace hub entries into “Workspace-wide” on environment pages,
  - move workspace configuration/admin entries into “Workspace admin” on environment pages,
  - preserve explicit `environment_id` only for workspace hubs that already accept that filter.

Run narrow tests first:

- `cd apps/platform && ./vendor/bin/sail artisan test --compact <new/updated Spec 338 tests>`
- `cd apps/platform && ./vendor/bin/sail pint --dirty --format agent`
- `git diff --check`

Run minimal browser smoke only if link/scope changes are user-visible in navigation:

- `cd apps/platform && php vendor/bin/pest tests/Browser --filter=Spec338 --compact`

## Deployment / Ops Impact

- Migrations: none expected.
- Env vars: none expected.
- Queues/scheduler: none expected.
- Filament assets: no new registered assets expected; `filament:assets` posture unchanged.