# Data Model: Filament/Livewire Heavy Suite Segmentation

This feature does not introduce new runtime database tables. The data-model work formalizes repository-level governance objects that describe how heavy Filament, Livewire, surface, discovery, and browser families are classified, assigned to lanes, guarded against drift, and attributed in reporting. It builds directly on the existing Spec 206 lane manifest and Spec 207 fixture-cost outputs.

## 1. Heavy Test Classification

### Purpose

Represents a repository-defined cost and purpose class for a UI-related test family.

### Fields

- `classification_id`: stable identifier such as `ui-light`, `ui-workflow`, `surface-guard`, `discovery-heavy`, or `browser`
- `purpose`: contributor-facing description of what this class is meant to cover
- `dominant_cost_drivers`: list of characteristics such as `single-mount`, `multi-mount`, `relation-manager breadth`, `reflection`, `resource discovery`, `workflow fan-out`, or `real-browser interaction`
- `default_lane_id`: primary execution lane for this class
- `allowed_lane_ids`: lanes where the class may legitimately appear
- `forbidden_lane_ids`: lanes where the class must not appear
- `reviewer_signals`: short list of clues a reviewer should look for when classifying a new test
- `escalation_triggers`: conditions that force a test out of a lighter class, such as broad discovery, wide reflection, or repeated multi-surface mounts

### Validation rules

- `browser` must allow only the `browser` lane.
- `discovery-heavy` must forbid `fast-feedback` and `confidence`.
- `surface-guard` must forbid `fast-feedback` and `confidence` and default to `heavy-governance`.
- `ui-light` may appear in `fast-feedback` and `confidence` only when its dominant cost drivers remain localized.
- `ui-workflow` defaults to `confidence` and may escalate to `heavy-governance` if its breadth becomes governance-wide.

## 2. Heavy Test Family

### Purpose

Represents a named cluster of related tests that share a heavy behavior pattern, hotspot files, and intended lane placement.

### Fields

- `family_id`: stable identifier for the family
- `classification_id`: owning heavy class
- `purpose`: why the family exists and what safety it provides
- `current_lane_id`: the lane where the family currently runs
- `target_lane_id`: the intended lane after segmentation
- `selectors`: one or more selectors that identify the family in the manifest or guards
- `hotspot_files`: representative or dominant files in the family
- `cost_signals`: concrete evidence of heaviness such as reflection use, multi-page mounts, relation-manager breadth, concern-driven fixture graphs, or repeated action-surface assertions
- `confidence_rationale`: explanation of why the family should remain in Confidence or move to Heavy Governance
- `validation_status`: `seeded`, `reviewed`, `migrated`, or `guarded`

### Validation rules

- Every family must have at least one selector and one hotspot file.
- `target_lane_id` must be compatible with the owning `classification_id`.
- Families assigned to `fast-feedback` may not carry `discovery-heavy` or broad `surface-guard` signals.
- A family with `classification_id = browser` must target the `browser` lane only.
- Families assigned to `confidence` must include `confidence_rationale` explaining why the retained UI safety is worth the lane cost.

## 3. Heavy Family Selector

### Purpose

Represents the checked-in selector used to find a heavy family during lane execution and guard validation.

### Fields

- `selector_type`: `suite`, `path`, `group`, or `file`
- `selector_value`: exact selector value used by the manifest or guard
- `selector_role`: `include`, `exclude`, or `inventory-only`
- `rationale`: why this selector is needed
- `source_of_truth`: `manifest`, `pest-group`, `guard-test`, or `report-attribution`

### Validation rules

- Selectors used for execution must be representable in `TestLaneManifest`.
- Families with more than one hotspot should not rely on a single ad-hoc file selector alone unless the file is intentionally the whole family.

## 4. Lane Placement Rule

### Purpose

Describes the allowed relationship between a heavy class and an execution lane.

### Fields

- `rule_id`: stable identifier
- `classification_id`: heavy class under review
- `lane_id`: execution lane
- `allowance`: `required`, `allowed`, `discouraged`, or `forbidden`
- `reason`: concise explanation of the rule
- `exception_policy`: how rare justified exceptions are handled

### Validation rules

- Each heavy class must have exactly one `required` or `default` lane target.
- `browser` cannot be `allowed` in non-browser lanes.
- `discovery-heavy` and broad `surface-guard` classes must be `forbidden` in `fast-feedback`.
- `confidence` may contain only the classes explicitly marked `allowed` or `required` there.

## 5. Mixed File Resolution

### Purpose

Represents how a file that exhibits more than one heavy behavior is resolved for lane placement.

### Fields

- `file_path`: relative test file path
- `primary_classification_id`: the classification that drives lane placement
- `secondary_classification_ids`: additional observed behaviors
- `resolution_strategy`: `split-file` or `broadest-cost-wins`
- `rationale`: why the chosen resolution is acceptable
- `follow_up_required`: boolean

### Validation rules

- Files with `resolution_strategy = broadest-cost-wins` must have an explicit rationale.
- Files whose primary classification is `discovery-heavy` or `surface-guard` may not remain in `fast-feedback` or `confidence`.

## 6. Drift Guard

### Purpose

Represents a checked-in validation that prevents wrong-lane placement for heavy classes or families.

### Fields

- `guard_id`: stable identifier
- `scope`: `classification`, `family`, `lane`, or `report`
- `assertion_type`: `forbidden-membership`, `required-membership`, `required-attribution`, `required-selector`, or `browser-isolation`
- `target_refs`: classes, families, files, or lanes covered by the guard
- `failure_contract`: the minimum actionable failure output expected from the guard
- `owning_test_paths`: tests that enforce the guard

### Validation rules

- Every forbidden lane relationship for `browser`, `discovery-heavy`, and broad `surface-guard` must have at least one drift guard.
- Drift guards must fail with actionable output that identifies the violating file or family.

## 7. Heavy Budget Threshold

### Purpose

Represents the runtime budget target for a heavy lane, heavy class, or heavy family.

### Fields

- `budget_id`: stable identifier
- `target_type`: `lane`, `classification`, or `family`
- `target_id`: referenced lane, classification, or family
- `threshold_seconds`: allowed wall-clock target
- `baseline_source`: `measured-current-suite`, `measured-lane`, or `measured-post-spec-207`
- `enforcement_level`: `report-only`, `warn`, or `hard-fail`
- `lifecycle_state`: `draft`, `measured`, `documented`, or `enforced`
- `review_cadence`: how often the budget should be revisited

### Validation rules

- Heavy Governance must retain a lane-level budget.
- At least one heavy family budget must exist beyond the lane total.
- New family budgets should stay report-oriented until lane baselines stabilize.

## 8. Heavy Attribution Report

### Purpose

Represents the reporting view that explains heavy-lane cost by class and family.

### Fields

- `lane_id`: lane being reported
- `wall_clock_seconds`: total lane duration
- `slowest_entries`: canonical top 10 runtime hotspot entries ordered by slowest wall-clock time
- `classification_attribution`: totals grouped by heavy class
- `family_attribution`: totals grouped by heavy family
- `budget_evaluations`: lane, classification, and family budget evaluations
- `artifact_paths`: generated report artifacts

### Validation rules

- Heavy reports must retain the canonical top 10 runtime hotspot view ordered by slowest wall-clock time.
- If a heavy family is cataloged, its cost should be attributable either directly or through its classification.
- Report artifact paths must remain under the app-root contract path `storage/logs/test-lanes`.

## 9. First-Slice Governance Inventory

### Existing lane infrastructure

- Operational lanes already present: `fast-feedback`, `confidence`, `browser`, and `heavy-governance`
- Support-lane entries already present: `profiling` and `junit`
- Existing family budgets currently cover `ops-ux-governance` and `browser-smoke`

### Initial heavy family clusters

- `tests/Feature/Filament/`: broadest mixed UI cluster; currently contains UI-Light, UI-Workflow, Surface-Guard, and Discovery-Heavy candidates
- `tests/Feature/Rbac/`: relation-manager and role-matrix heavy families with repeated Livewire mounts and capability transitions
- `tests/Feature/Baselines/` plus related Filament baseline pages: dense workflow and matrix-style coverage with expensive fixture construction
- `tests/Feature/Concerns/`: heavy builder traits such as baseline compare and portfolio triage fixtures that amplify test cost across families
- `tests/Feature/Guards/ActionSurfaceContractTest.php` and related governance guards: canonical Surface-Guard seeds already treated as heavy
- `tests/Browser/`: isolated Browser class, already a separate lane and cost domain

### Initial heavy signals

- Reflection-based discovery such as `ReflectionProperty` and global-search parity checks
- Multi-mount Livewire tests across pages, relation managers, and actions
- Broad action-surface and navigation-discipline validation
- Concern-driven fixture construction that creates dense comparison or triage graphs
- Browser interaction and end-to-end smoke coverage
