ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a2fdca43fd
TenantAtlas/specs/208-heavy-suite-segmentation/data-model.md
ahmido 0d5d1fc9f4 Spec 208: finalize heavy suite segmentation (#241) 
## Summary
- add the checked-in Spec 208 heavy-suite classification and family manifest with config-driven lane generation, attribution, and budget reporting
- update Pest grouping, guard coverage, wrapper/report contracts, and spec artifacts for the segmented lane model
- complete the targeted follow-up pass that re-homes the remaining in-scope confidence hotspots into explicit heavy-governance families

## Acceptance
- confidence is repaired and now measures 389.613832s, down from 587.446894s and below the 450s lane budget
- confidence is also slightly below the post-Spec-207 baseline of 394.383441s (delta -4.769609s)
- this closes the central Spec 208 acceptance issue that had kept the spec open

## Intentionally Re-homed Families
- finding-bulk-actions-workflow
- drift-bulk-triage-all-matching
- baseline-profile-start-surfaces
- workspace-settings-slice-management
- findings-workflow-surfaces
- workspace-only-admin-surface-independence

## Explicit Residual Risk
- heavy-governance now measures 318.296962s, above its documented 300s threshold
- the cost was not removed; it was moved into the correct lane and made visible on clearly named heavy families
- this is documented residual debt, not an open Spec 208 failure

## Validation
- focused guard/support validation: 206 passed (3607 assertions)
- lane wrapper/report validation completed for confidence and heavy-governance
- no full-suite run was performed in this pass by request

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #241
2026-04-17 09:53:55 +00:00

207 lines
9.5 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink