TenantAtlas/specs/334-nested-filament-context-contract-hardening/plan.md

Implementation Plan: Spec 334 - Nested Filament / Livewire Context Contract Hardening

• Branch: 334-nested-filament-context-contract-hardening
• Date: 2026-05-24
• Spec: specs/334-nested-filament-context-contract-hardening/spec.md
• Input: User-provided Spec 334 draft + repo inspection for path truth.

Summary

Define and enforce a nested Filament/Livewire context contract so operator-critical nested surfaces do not depend on ambient Filament::getTenant() during modal, wizard, relation manager, widget, and Livewire update lifecycles.

Implement a narrow hardening slice across four confirmed surfaces, plus guard tests:

• apps/platform/app/Livewire/BackupSetPolicyPickerTable.php
• apps/platform/app/Filament/Resources/RestoreRunResource.php (+ apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php seam)
• apps/platform/app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleOperationRunsRelationManager.php
• apps/platform/app/Filament/Widgets/ManagedEnvironment/ManagedEnvironmentTriageArrivalContinuity.php
• new architecture guard: apps/platform/tests/Architecture/FilamentTenantContextContractTest.php

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 + Livewire component tests + one architecture guard; browser smoke only for the two user-visible regression scenarios.
• Validation Lanes: confidence + browser (scoped).
• Target Platform: Laravel Sail locally; Dokploy/container deployment posture unchanged.
• Project Type: Laravel monolith under apps/platform.
• Performance Goals: DB-only context recovery; no Graph calls during UI render; no broad unscoped queries in nested surfaces.
• Constraints: No new persisted truth, migrations, packages, env vars, queue/scheduler changes, or routing architecture changes. Scale/Scope: Four confirmed nested surfaces + shared seam hardening + guard tests.

UI / Surface Guardrail Plan

• Guardrail scope: changed existing operator-facing nested surfaces (modal, wizard, relation manager, widget).
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • Backup Set “Add policies” modal table (Livewire component).
  • Restore Run Create wizard (resource create page).
  • Backup Schedule Operation Runs relation manager table (nested resource detail).
  • Environment dashboard triage widget (nested widget).
• No-impact class: N/A.
• Native vs custom classification summary: native Filament + Livewire surfaces; no custom UI framework.
• Shared-family relevance: environment context resolution, authorization/visibility gating, table selection semantics, wizard option closures, remembered context validation.
• State layers in scope: route-owned workspace/environment, Livewire component state (captured at mount), remembered environment context (validated only), ambient Filament tenant (fallback convenience only).
• Audience modes in scope: operator-MSP / platform operators. No customer/read-only surface changes expected.
• Decision/diagnostic/raw hierarchy plan: fail-closed states must be honest; do not show “no records” when context is invalid; no raw debug “framework state” troubleshooting exposed to operators.
• Handling modes: review-mandatory. This is a correctness hardening slice affecting authorization and scope.
• Special surface test profiles: exception-coded-surface (context recovery) + shared-detail-family (nested relation manager) + browser smoke for two user-visible regressions.
• Required tests or manual smoke:
  • Feature/Livewire tests for each confirmed surface and its fail-closed behavior.
  • Architecture guard preventing unsafe Filament::setTenant(...) usage in nested surfaces.
  • Browser smoke for:
    • Backup Set “Add policies” checkbox visibility + selection.
    • Restore Run Create wizard no-crash on Livewire update transitions.
• Exception path and spread control: no broad fallback that sets tenant from arbitrary model IDs. Any referer-based recovery must validate workspace membership and environment entitlement.
• UI/Productization coverage decision: no new routes/pages; cover via tests + browser smoke + PR close-out note.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes (multiple nested surfaces).
• Systems touched:
  • Filament tenant resolution seam: apps/platform/app/Filament/Concerns/ResolvesPanelTenantContext.php
  • Route/shell context: apps/platform/app/Support/OperateHub/OperateHubShell.php
  • Workspace/environment context + remembered context: apps/platform/app/Support/Workspaces/WorkspaceContext.php
  • UI gating: apps/platform/app/Support/Rbac/UiEnforcement.php
• Shared abstractions reused: prefer existing helpers/policies over new framework layers.
• New abstraction introduced?: none by default. A small helper class may be introduced only if at least two confirmed surfaces would otherwise duplicate validated context recovery logic (ABSTR-001).
• Bounded deviation / spread control: any new helper must be feature-local in scope and must not become a generic “ambient context fixer” without explicit follow-up spec approval.

OperationRun UX Impact

N/A. This feature does not introduce new queued operations. It must not create new OperationRun types or change OperationRun UX policy.

Provider Boundary / Platform Core Check

Platform-core hardening only. No Graph contract, provider registry, or provider vocabulary changes.

Implementation Approach

Phase 1 — Repo truth + reproduce

• Inspect current behavior and confirm the concrete failure path(s) for:
  • Add Policies modal selection checkbox hidden.
  • Restore Run Create wizard crash during Livewire update.
• Document the exact call path(s) and which closures/methods access context.

Phase 2 — Define nested context resolution order

Implement (or codify within existing seams) a deterministic resolution order for managed-environment context in nested surfaces:

1. Owner/domain record (owner record, component-bound record, backup set record, schedule record, widget record).
2. Validated component state captured at mount (e.g., environment ID saved in the Livewire component state).
3. Route-owned workspace/environment (when route params are available).
4. Remembered environment only if workspace membership and entitlement validate.
5. Ambient Filament tenant as fallback convenience only.
6. Fail closed with a clear, honest UI state.

Prohibited:

• blindly trusting referer as authority
• unguarded Filament::setTenant($model->...) derived from an arbitrary identifier
• broad “set tenant from model id” fallback in the shared seam

Phase 3 — Apply the contract to confirmed surfaces

• BackupSetPolicyPickerTable:
  • Resolve context from the BackupSet (validated) and scope policy query accordingly.
  • Ensure mutation-time recheck before attaching policy IDs.
  • Do not override a mismatched existing tenant; fail closed.
• RestoreRunResource:
  • Ensure option closures used in wizard lifecycles can resolve environment context without route params.
  • Implement validated Livewire update context recovery via the shared seam (apps/platform/app/Support/OperateHub/OperateHubShell.php) by treating the Referer path as a candidate (never authority) and re-validating workspace + membership + operability before using it.
• BackupScheduleOperationRunsRelationManager:
  • Use owner schedule context ($this->getOwnerRecord()) as primary context.
  • Avoid ambient ManagedEnvironment::currentOrFail()-style assumptions when owner exists.
• ManagedEnvironmentTriageArrivalContinuity:
  • Prefer widget record context; ambient tenant only fallback.
  • Use the same resolver for visibility and mutation-time checks.

Phase 4 — Guardrails

• Add apps/platform/tests/Architecture/FilamentTenantContextContractTest.php to:
  • detect unsafe Filament::setTenant(...) patterns in nested surfaces
  • keep an explicit allowlist for infrastructure-only locations
  • optionally classify (not fail) direct Filament::getTenant() usage in known high-risk directories first, to avoid noisy failures

Phase 5 — Tests and validation

Add focused tests (Feature/Livewire) for:

• tenantless Add Policies picker: authorized user still sees checkboxes and can select items
• restore create wizard: does not throw when route params are missing in Livewire update lifecycle
• owner-scoped relation manager: query does not broaden when ambient tenant is null/wrong
• widget context: record context is preferred; missing context fails closed

Validation commands (narrow first):

• cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament --filter='BackupSetPolicyPicker|RestoreRun|BackupScheduleOperationRuns|Triage' --compact
• cd apps/platform && ./vendor/bin/sail artisan test tests/Architecture --filter='FilamentTenantContextContract' --compact

Browser smoke (only when feature tests pass):

• cd apps/platform && php vendor/bin/pest tests/Browser/Spec334NestedFilamentContextContractSmokeTest.php --compact

Deployment / Ops Impact

• Migrations: none expected.
• Env vars: none expected.
• Queues/scheduler: none expected.
• Filament assets: no new registered assets expected; deployment posture unchanged.