# Implementation Plan: Hard Filament Nativity Cleanup

**Branch**: `196-hard-filament-nativity-cleanup` | **Date**: 2026-04-13 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/196-hard-filament-nativity-cleanup/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/196-hard-filament-nativity-cleanup/spec.md`

**Note**: This plan keeps the work inside the existing Filament v5 / Livewire v4 page layer, the current derived view-model services, the existing dependency query and target-resolution services, and the current focused RBAC and reporting tests. It explicitly avoids adding a new runtime UI framework, new persistence, or a broader shell or monitoring-state architecture.

## Summary

Remove the three hard nativity bypasses called out by Spec 196 by reusing repo-proven native Filament patterns. Convert `EvidenceOverview` and `TenantRequiredPermissions` into page-owned native table surfaces with native filter state and unchanged scope semantics. Replace the GET-form dependency micro-UI on inventory item detail with an embedded Livewire table component that owns direction and relationship state inside the current detail surface. Preserve existing domain truth, authorization, empty states, and drilldowns, and prove the cleanup through focused feature, Livewire, RBAC, and Filament guard coverage.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing `DependencyQueryService`, `DependencyTargetResolver`, `TenantRequiredPermissionsViewModelBuilder`, `ArtifactTruthPresenter`, `WorkspaceContext`, Filament `InteractsWithTable`, Filament `TableComponent`, and existing badge and action-surface helpers  
**Storage**: PostgreSQL through existing tenant-owned and workspace-context models (`InventoryItem`, `InventoryLink`, `TenantPermission`, `EvidenceSnapshot`, `TenantReview`); no schema change planned  
**Testing**: Pest feature, Livewire, unit, and existing guard tests run through Laravel Sail; browser smoke only if an implementation detail proves impossible to cover with existing feature or Livewire layers  
**Target Platform**: Laravel monolith web application under `apps/platform`, spanning tenant-context admin routes under `/admin/t/{tenant}/...`, tenant-specific admin routes under `/admin/tenants/{tenant:external_id}/...`, and workspace-context canonical admin routes under `/admin/...`  
**Project Type**: web application  
**Performance Goals**: Preserve DB-only render behavior, keep dependency and evidence rendering free of Graph calls, avoid request-reload control flows, preserve current row-count and summary derivation cost, and avoid introducing extra persistence or polling  
**Constraints**: No new persistence, no new enum or status family, no new wrapper microframework, no global shell or monitoring-state refactor, no provider or panel registration changes, no weakening of current 404 or 403 semantics, no destructive-action expansion, and no new asset pipeline work  
**Scale/Scope**: 3 core surfaces, 1 embedded tenant detail micro-surface, 1 tenant workflow page, 1 workspace report page, and a focused verification pack touching roughly 12 existing or new test files; optional extra hits are allowed only if no new architecture question opens

## Constitution Check

*GATE: Passed before Phase 0 research. Re-checked after Phase 1 design and still passing.*

| Principle | Pre-Research | Post-Design | Notes |
|-----------|--------------|-------------|-------|
| Inventory-first / snapshots-second | PASS | PASS | Inventory dependencies and evidence overview remain read-only views over existing inventory and evidence truth. |
| Read/write separation | PASS | PASS | The cleanup changes interaction contracts only. Existing follow-up writes remain on their current confirmed destinations. |
| Graph contract path | N/A | N/A | No new Graph calls or contract-registry changes are introduced. |
| Deterministic capabilities | PASS | PASS | Existing capability registries, tenant access checks, and page authorization remain authoritative. |
| Workspace + tenant isolation | PASS | PASS | Tenant required permissions keeps the route tenant authoritative; evidence overview keeps workspace-context entitlement filtering; inventory detail remains tenant-context scoped. |
| RBAC-UX authorization semantics | PASS | PASS | Non-members remain `404`, in-scope capability denial remains unchanged, and no new mutation path bypasses server-side authorization. |
| Run observability / Ops-UX | PASS | PASS | No new `OperationRun` flow is introduced. Existing run-linked destinations remain unchanged. |
| Data minimization | PASS | PASS | No new persisted UI-state mirror or helper artifact is added, and DB-only rendering remains required. |
| Proportionality / anti-bloat | PASS | PASS | The design reuses existing Filament patterns and adds no new persistence or generic UI layer. |
| UI semantics / few layers | PASS | PASS | The plan maps directly from current domain truth to native UI primitives without a new presenter framework. |
| Filament-native UI | PASS | PASS | All three target surfaces move toward native Filament tables, filters, or shared primitives and away from pseudo-native contracts. |
| Surface taxonomy / decision-first roles | PASS | PASS | Inventory dependencies remains a secondary context sub-surface; tenant required permissions and evidence overview remain primary decision surfaces. |
| Filament v5 / Livewire v4 compliance | PASS | PASS | All touched surfaces remain inside the current Filament v5 + Livewire v4 stack. |
| Provider registration location | PASS | PASS | No provider changes are required; Laravel 11+ provider registration remains in `apps/platform/bootstrap/providers.php`. |
| Global search hard rule | PASS | PASS | No searchable resource is added or modified. `TenantRequiredPermissions` and `EvidenceOverview` are pages, and inventory resource search behavior is unchanged. |
| Destructive action safety | PASS | PASS | No new destructive action is introduced. Existing destructive follow-up actions remain on their current confirmed surfaces. |
| Asset strategy | PASS | PASS | No new global or on-demand assets are required. Existing deployment handling of `cd apps/platform && php artisan filament:assets` remains unchanged. |

## Filament-Specific Compliance Notes

- **Livewire v4.0+ compliance**: The implementation remains entirely inside Filament v5 + Livewire v4 and does not introduce legacy Filament or Livewire APIs.
- **Provider registration location**: No provider changes are required; panel providers remain registered in `apps/platform/bootstrap/providers.php`.
- **Global search**: No resource search behavior changes. `InventoryItemResource` already has a view page, but this spec does not change its global-search status. `TenantRequiredPermissions` and `EvidenceOverview` remain pages, not searchable resources.
- **Destructive actions**: No new destructive actions are added. Existing linked destinations retain their current confirmation and authorization behavior.
- **Asset strategy**: No new assets are planned. Existing deployment handling of `cd apps/platform && php artisan filament:assets` remains sufficient and unchanged.
- **Testing plan**: Cover the cleanup through `InventoryItemDependenciesTest`, a new Livewire or table-component dependency test, `TenantRequiredPermissionsTrustedStateTest`, a new required-permissions page-table test, `EvidenceOverviewPageTest`, `EvidenceOverviewDerivedStateMemoizationTest`, and guard coverage such as `FilamentTableStandardsGuardTest` where native table adoption becomes guardable.

## Phase 0 Research

Research outcomes are captured in `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/196-hard-filament-nativity-cleanup/research.md`.

Key decisions:

- Reuse the repo's existing native page-table pattern from `ReviewRegister` and `InventoryCoverage` for `TenantRequiredPermissions` and `EvidenceOverview`.
- Keep `TenantRequiredPermissions` and `EvidenceOverview` on derived data and current services instead of adding new projections, tables, or materialized helper models.
- Replace inventory dependency GET-form controls with an embedded Livewire `TableComponent` because the surface is detail-context and not a true relation manager or a standalone page.
- Treat query parameters as one-time seed or deeplink inputs only; after mount, native page or component state owns filter interaction.
- No additional same-class extra hit is confirmed in planning; default implementation scope stays fixed at the three named core surfaces unless the setup audit records a candidate that passes every FR-196-015 admission check without widening architecture or adding new persistence, routes, or shared abstractions.
- Extend existing focused tests and the current Filament table guard where possible instead of introducing a new browser-only verification layer.

## Phase 1 Design

Design artifacts are created under `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/196-hard-filament-nativity-cleanup/`:

- `research.md`: implementation-shape decisions and rejected alternatives for each surface
- `data-model.md`: derived UI-state and row-projection models for dependency scope, required-permissions filtering, and evidence overview rows
- `contracts/filament-nativity-cleanup.logical.openapi.yaml`: internal logical contract for page state, derived rows, scope rules, and deeplink semantics
- `quickstart.md`: implementation and verification sequence for the feature

Design highlights:

- `EvidenceOverview` adopts `InteractsWithTable` + `HasTable` and keeps derived rows via a records callback similar to `InventoryCoverage`.
- `TenantRequiredPermissions` adopts a native table and native table-owned filter state while keeping summary, copy, and guidance sections above the table body.
- Inventory dependencies stays embedded on inventory detail but moves its interactive controls into a dedicated Livewire table component rather than a request-driven Blade fragment.
- Existing domain services stay authoritative: dependency rows still come from `DependencyQueryService` and `DependencyTargetResolver`; permission truth still comes from `TenantRequiredPermissionsViewModelBuilder` when an adapter is needed; evidence truth still comes from `ArtifactTruthPresenter` and current snapshot queries.
- No new schema, enum, or shared microframework is introduced.

## Project Structure

### Documentation (this feature)

```text
specs/196-hard-filament-nativity-cleanup/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── spec.md
├── contracts/
│   └── filament-nativity-cleanup.logical.openapi.yaml
└── checklists/
    └── requirements.md
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── TenantRequiredPermissions.php                     # MODIFY
│   │   │   └── Monitoring/
│   │   │       └── EvidenceOverview.php                          # MODIFY
│   │   └── Resources/
│   │       └── InventoryItemResource.php                         # MODIFY
│   ├── Livewire/
│   │   └── InventoryItemDependencyEdgesTable.php                 # NEW
│   └── Services/
│       └── Intune/
│           └── TenantRequiredPermissionsViewModelBuilder.php     # MODIFY or REVIEW FOR ADAPTERS
├── resources/
│   └── views/
│       └── filament/
│           ├── components/
│           │   └── dependency-edges.blade.php                    # MODIFY
│           └── pages/
│               ├── tenant-required-permissions.blade.php         # MODIFY
│               └── monitoring/
│                   └── evidence-overview.blade.php               # MODIFY
└── tests/
    ├── Feature/
    │   ├── InventoryItemDependenciesTest.php                     # MODIFY
    │   ├── Evidence/
    │   │   └── EvidenceOverviewPageTest.php                      # MODIFY
    │   ├── Filament/
    │   │   ├── EvidenceOverviewDerivedStateMemoizationTest.php   # MODIFY
    │   │   ├── InventoryItemDependencyEdgesTableTest.php         # NEW
    │   │   └── TenantRequiredPermissionsPageTest.php             # NEW
    │   ├── Guards/
    │   │   └── FilamentTableStandardsGuardTest.php               # MODIFY
    │   └── Rbac/
    │       └── TenantRequiredPermissionsTrustedStateTest.php     # MODIFY
    └── Unit/
        ├── TenantRequiredPermissionsFilteringTest.php            # REUSE
        ├── TenantRequiredPermissionsCopyPayloadTest.php          # REUSE
        ├── TenantRequiredPermissionsOverallStatusTest.php        # REUSE
        ├── TenantRequiredPermissionsFeatureImpactTest.php        # REUSE
        └── TenantRequiredPermissionsFreshnessTest.php            # REUSE
```

**Structure Decision**: Keep the work entirely inside the existing Laravel/Filament monolith under `apps/platform`. Add at most one new Livewire table component for the dependency sub-surface, then modify the three target page or resource files and focused tests. Do not add a new service layer, persistence shape, or cross-surface UI abstraction.

## Complexity Tracking

No constitution violation or BLOAT-triggered structural expansion is planned. The feature deliberately avoids new persistence, new enums, new UI taxonomies, or new cross-page infrastructure.

## Proportionality Review

Not triggered beyond the spec-level review already completed. The implementation plan adds no new enum, presenter framework, persisted entity, or registry. The narrowest correct implementation is to reuse native Filament tables and one embedded `TableComponent`.

## Implementation Strategy

Execution sequence for this plan is test-first at two levels: complete the shared test and guard scaffolding before story work starts, then land each story's focused tests before its implementation changes.

### Phase 0.5 - Establish shared test and guard scaffolding

Goal: create the blocking Spec 196 test entry points and shared guard coverage before surface refactors begin.

Changes:

- Create the new focused test entry points for the dependency table component and required-permissions page table.
- Record the pre-implementation scope gate: unless the setup audit documents an FR-196-015 pass, scope is frozen to the three named core surfaces and no optional extra hit may begin.
- Extend shared guard coverage for new native page-table expectations, faux-control regressions, and no-new-wrapper drift.
- Add shared regression coverage for mount-only query seeding versus authoritative scope on required permissions and evidence overview.

Tests:

- This phase establishes the focused test harness and is itself the blocking prerequisite for later story delivery.

### Phase A - Replace the inventory dependency GET form with an embedded Livewire table component

Goal: keep the dependencies surface on inventory item detail, but move direction and relationship controls into native component state instead of a request-driven Blade fragment.

Changes:

- Introduce `App\Livewire\InventoryItemDependencyEdgesTable` as a Filament `TableComponent` that owns direction and relationship filter state.
- Keep the surface embedded in the current `InventoryItemResource` detail section rather than moving it to a standalone route or relation manager.
- Move the current request-query dependency fetch into the component so the Blade fragment no longer parses `request()` or submits a GET form.
- Preserve existing target rendering, missing-target labels, and tenant-isolated dependency resolution through `DependencyQueryService` and `DependencyTargetResolver`.
- Keep render-time behavior DB-only and preserve the no-Graph-call guard.

Tests:

- Extend the listed story tests before landing implementation changes.
- Modify `tests/Feature/InventoryItemDependenciesTest.php` to assert the preserved result logic while removing dependence on manual query-string filter submission.
- Add `tests/Feature/Filament/InventoryItemDependencyEdgesTableTest.php` to cover direction changes, relationship narrowing, missing-target rendering, and tenant isolation through the native component.
- Reuse existing unit and feature tests around `DependencyQueryService`, `DependencyTargetResolver`, and tenant isolation as domain and safety regression coverage.

### Phase B - Convert `TenantRequiredPermissions` into a native page-owned table and filter contract

Goal: remove pseudo-native filter controls while preserving the page's summary, guidance, copy payloads, and tenant-authoritative routing semantics.

Changes:

- Add `HasTable` and `InteractsWithTable` to `App\Filament\Pages\TenantRequiredPermissions`.
- Replace the manual public filter properties and `updated*()` handlers with native table filters and native table search, using a derived-records callback because permission rows are view-model based rather than Eloquent-backed.
- Keep the route tenant authoritative and allow query parameters only to seed initial filter state when the page first mounts.
- Keep the summary, copy, and guidance blocks, but derive their values from the same normalized filter state that drives the native table rows.
- Preserve the current behavior where copy payloads remain driven by the intended filter dimensions and do not silently widen tenant scope.

Tests:

- Extend the listed story tests before landing implementation changes.
- Modify `tests/Feature/Rbac/TenantRequiredPermissionsTrustedStateTest.php` to keep route-tenant authority and safe deeplink behavior after native filter adoption.
- Add `tests/Feature/Filament/TenantRequiredPermissionsPageTest.php` to cover native filter behavior, summary consistency, and no-results states.
- Reuse current unit tests for filtering, freshness, feature impacts, overall status, and copy payload derivation as unchanged domain-truth guards.
- Extend `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` if the page becomes subject to shared page-table standards.

### Phase C - Convert `EvidenceOverview` into a native workspace table

Goal: remove the hand-built report table and make filtering, empty state, and row inspection native without changing workspace-safe scope behavior.

Changes:

- Add `HasTable` and `InteractsWithTable` to `App\Filament\Pages\Monitoring\EvidenceOverview`.
- Move row generation out of the Blade table contract and into a native table records callback, following the derived-row pattern already used by `InventoryCoverage`.
- Convert the current `tenantFilter` query handling into native filter state seeded from an entitled tenant prefilter only.
- Add native table search across tenant-facing row labels.
- Keep the existing row inspect destination to tenant evidence detail through a single native inspect model.
- Replace the Blade table markup with a page wrapper that renders the native table and keeps any lightweight surrounding layout only if still needed.

Tests:

- Extend the listed story tests before landing implementation changes.
- Modify `tests/Feature/Evidence/EvidenceOverviewPageTest.php` to assert native table output, native search behavior, workspace safety, entitled-tenant filtering, and current drilldowns.
- Modify `tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php` to keep DB-only derived-state guarantees after table conversion.
- Extend `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` if the new page-owned table should now satisfy shared table standards.

### Phase D - Verification, guard alignment, and explicit scope stop

Goal: confirm the cleanup remains bounded to the three core surfaces and that the repo's existing guard layer reflects newly native table surfaces where appropriate.

Changes:

- Extend guard coverage only where native table adoption now makes a page eligible for existing table standards.
- Run focused Sail verification for the modified feature, RBAC, and guard tests.
- Record the release close-out in `specs/196-hard-filament-nativity-cleanup/quickstart.md`, including cleaned surfaces, deferred themes, optional extra hits, and touched follow-up specs.
- Document any optional additional same-class hit only if it was truly included; otherwise record that no extra candidate was confirmed.
- Verify the final implementation still satisfies the non-functional constraints: DB-only rendering, no new remote calls, no new persistence, and no asset or provider drift.
- Stop immediately if implementation reaches shared micro-UI family, monitoring-state, or shell-context architecture.

Tests:

- Focused feature and Livewire test pack for the three surfaces.
- Existing RBAC and derived-state regression tests retained.
- Pint run after touched files are complete.

## Risk Assessment

### Risk 1 - Scope creep into shared monitoring or detail-micro-UI architecture

Mitigation:

- Keep `EvidenceOverview` limited to native table conversion, not broader monitoring-shell cleanup.
- Keep inventory dependencies embedded on the existing detail page and do not generalize a new micro-UI framework.
- Reject any additional surface that opens shared-family or shell questions.

### Risk 2 - Deeplink or initial-state regressions on required permissions and evidence overview

Mitigation:

- Treat query values strictly as initial seed state.
- Keep route tenant and entitled tenant scope authoritative.
- Preserve and extend current trusted-state tests.

### Risk 3 - Derived-data performance or DB-only regressions after native table adoption

Mitigation:

- Reuse the repo's existing derived-records page pattern from `InventoryCoverage`.
- Preserve current eager-loading and memoization behavior.
- Keep the current no-Graph and DB-only tests in the verification pack.

### Risk 4 - Over-correcting custom read-only rendering into an unnecessary generic surface

Mitigation:

- Keep only the controls and state contract native.
- Allow custom read-only cell or row presentation to remain where it carries real domain value.
- Avoid relation-manager or standalone-page moves for the dependency section.

## Implementation Order Recommendation

1. Establish the shared test and guard scaffolding first so story work starts from the same blocking regression baseline captured in the task plan.
2. Replace inventory dependencies second, with the focused story tests landing before the implementation changes.
3. Convert `TenantRequiredPermissions` third, again extending the story tests before code changes.
4. Convert `EvidenceOverview` fourth, with its focused page and derived-state tests updated before the refactor lands.
5. Run the final focused verification pack, formatting, and release close-out last, and record whether the setup audit admitted any optional same-class extra hit. No new optional extra hit may enter scope after implementation has started.