TenantAtlas/specs/196-hard-filament-nativity-cleanup/plan.md

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 low-risk same-class hit is confirmed in planning; default implementation scope stays at the three named core surfaces unless implementation audit finds one trivial match that does not widen scope.
• 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)

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)

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.
• Extend shared guard coverage for new native page-table expectations and faux-control regressions.
• 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.
• 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 only then consider whether any optional same-class extra hit truly qualifies.