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

Research: Hard Filament Nativity Cleanup

Decision: Reuse the repo's existing native page-table pattern for EvidenceOverview and TenantRequiredPermissions

Rationale

The codebase already has two strong native examples for page-owned tables outside normal resource index pages: ReviewRegister and InventoryCoverage. Both use InteractsWithTable, HasTable, native Filament filters, Filament-managed filter state, native empty states, and one consistent inspect model. That makes them the narrowest repo-consistent replacement for the two current page-level bypasses.

EvidenceOverview is currently a hand-built Blade report table, and TenantRequiredPermissions is currently a custom page with pseudo-native filter controls. Both are better modeled as page-owned native tables than as bespoke Blade contracts.

Alternatives considered

• Keep the current Blade table and filter bars, but restyle them more convincingly: rejected because that preserves the separate contract instead of removing it.
• Move either surface into a Resource or RelationManager: rejected because both already have correct route and page ownership; only their internal interaction model is wrong.

Decision: Keep both page-level surfaces on derived data instead of adding new projections or schema

Rationale

EvidenceOverview rows are already derived from EvidenceSnapshot, TenantReview, and ArtifactTruthPresenter, while TenantRequiredPermissions rows and summaries are already derived through TenantRequiredPermissionsViewModelBuilder. The current product truth is sufficient. The problem is not missing data infrastructure, but the non-native way the data is exposed.

Using derived table records keeps the implementation proportional and avoids importing persistence or a second source of truth for UI state.

Alternatives considered

• Add dedicated read models or materialized projections for overview rows: rejected because the spec is cleanup, not reporting-architecture expansion.
• Convert the permission or evidence pages into query-first Eloquent resources: rejected because the current derived summaries and guidance would still need a second layer and would not simplify the domain.

Decision: Replace inventory dependency GET controls with an embedded Livewire TableComponent

Rationale

The dependency surface is not a standalone page and not a true Eloquent relationship that should become a RelationManager. It is a detail-context sub-surface inside inventory item view. The narrowest native replacement is therefore an embedded Livewire TableComponent that owns direction and relationship state, renders native filters, and stays inside the current inventory detail section.

The repo already uses Filament TableComponent in BackupSetPolicyPickerTable, which proves the pattern is acceptable and reusable here.

Alternatives considered

• Convert the dependency section into a RelationManager: rejected because dependency edges are query-driven, not a direct relationship manager surface.
• Move dependencies to a new standalone page: rejected because it would break the current inspect-one-record workflow and widen scope.
• Keep a custom Blade fragment with wire:model on raw inputs: rejected because that still leaves a pseudo-native control surface instead of a real native table contract.

Decision: Query parameters may seed initial state, but they do not remain the authoritative interaction contract

Rationale

Both TenantRequiredPermissions and EvidenceOverview have valid deeplink or workflow-continuity reasons to accept initial query values. The spec explicitly allows that. What needs to change is ongoing ownership of page-body state. After first mount, filter state must live in native page or component state rather than continuing to be reconstructed from request() on every interaction.

This preserves existing deeplink behavior without letting query values become a shadow state system.

Alternatives considered

• Remove all query seeding entirely: rejected because the current product does rely on deeplink and continuity behavior.
• Keep query parameters as the main contract forever: rejected because that is the bypass pattern the spec exists to remove.

Decision: Preserve custom read-only presentation where it carries domain value, but make control state native

Rationale

The spec is not a repo-wide custom Blade purge. Some read-only rendering still carries useful domain formatting, especially for dependency target badges, missing-target hints, permission guidance blocks, and evidence explanation text. The actual harm sits in fake controls, manual GET submission, and hand-built primary table contracts.

The narrowest implementation therefore replaces the primary control and table contracts while allowing domain-specific read-only cells or layout blocks to remain when they do not create a second state system.

Alternatives considered

• Force every touched surface into generic Filament markup only: rejected because it risks over-correction and would expand scope into broader micro-UI standardization.
• Leave custom presentation and custom control markup mixed together: rejected because it would keep the core nativity problem alive.

Decision: No additional same-class low-risk hit is confirmed during planning

Rationale

The planning audit found the three target surfaces clearly. It did not identify a fourth candidate that is both obviously the same problem class and clearly small enough to include without opening shared-family or shell questions. That means the safe default is to keep the implementation scope locked to the three named surfaces and only admit an extra hit if implementation discovers a truly trivial match.

Alternatives considered

• Expand planning scope now to include visually similar custom Blade surfaces elsewhere in monitoring or verification: rejected because those families carry broader architecture and product-semantics questions already marked out of scope.

Decision: Extend existing focused tests and guardrails rather than introducing a new browser-centric verification layer

Rationale

The repo already has meaningful coverage for all three areas: dependency rendering and tenant isolation, required-permissions trusted-state behavior and view-model derivation, and evidence overview authorization and DB-only rendering. The cleanup should lean on that existing coverage, then add only the missing surface-level native-table or component assertions.

This keeps the feature aligned with TEST-TRUTH-001 and avoids creating a heavier verification framework than the change requires.

Alternatives considered

• Add a new browser suite for all three surfaces as the primary proof: rejected because most required outcomes are already testable with feature and Livewire tests.
• Rely only on manual smoke checks: rejected because the repo rules require automated coverage for changed behavior.