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.