TenantAtlas/specs/208-heavy-suite-segmentation/data-model.md

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