# Data Model: Heavy Governance Lane Cost Reduction This feature does not introduce new runtime database tables. The data-model work formalizes repository-level governance objects that describe how the heavy-governance lane is inventoried, decomposed, slimmed, and evaluated against a single explicit budget contract. It builds directly on the existing Spec 206 to 208 lane manifest and report artifacts. ## 1. Heavy Governance Budget Contract ### Purpose Represents the deliberate budget rule for the heavy-governance lane, including the authoritative pre-normalization `300s` summary threshold, the legacy `200s` detailed budget-target evaluation, and the final reconciled threshold published by Spec 209. ### Fields - `laneId`: expected to be `heavy-governance` - `summaryThresholdSeconds`: current authoritative pre-normalization lane-level threshold used by the summary artifact - `evaluationThresholdSeconds`: legacy threshold currently used in detailed budget evaluations until normalization is complete - `normalizedThresholdSeconds`: the single threshold that will be treated as authoritative after Spec 209 - `baselineSource`: where the budget came from, such as `measured-lane` - `enforcementLevel`: `report-only`, `warn`, or `hard-fail` - `lifecycleState`: `draft`, `documented`, or `recalibrated` - `reconciliationRationale`: explanation of why the single threshold is correct for the post-Spec-209 lane - `decisionStatus`: `pending`, `recovered`, or `recalibrated` ### Validation rules - `laneId` must be `heavy-governance`. - `summaryThresholdSeconds` and `evaluationThresholdSeconds` must both be captured when they differ, and the authoritative pre-normalization contract must remain identifiable until normalization is complete. - `normalizedThresholdSeconds` must be present before the rollout is considered complete. - `decisionStatus = recovered` requires measured runtime less than or equal to `normalizedThresholdSeconds`. - `decisionStatus = recalibrated` requires a non-empty `reconciliationRationale`. ## 2. Heavy Governance Hotspot Inventory Record ### Purpose Represents one named heavy-governance family that materially contributes to the lane's runtime and needs explicit review. ### Fields - `familyId`: stable family identifier - `classificationId`: current owning class such as `ui-workflow`, `surface-guard`, or `discovery-heavy` - `purpose`: why the family exists and what trust it provides - `measuredSeconds`: current measured contribution from the latest heavy-governance report - `hotspotFiles`: dominant files tied to the family - `costDriverCategory`: primary cause such as `overbroad`, `redundant`, `discovery-heavy`, `workflow-heavy`, `surface-heavy`, `helper-driven`, `fixture-driven`, or `intentionally-heavy` - `priorityTier`: `primary`, `secondary`, or `residual` - `currentBudgetSeconds`: current family-level budget if one exists - `status`: `seeded`, `decomposed`, `slimmed`, `retained`, or `follow-up` ### Validation rules - `hotspotFiles` must contain at least one file. - `priorityTier = primary` is required for the families that explain most of the lane runtime. - The full hotspot inventory must cover the current top 5 families by runtime, or enough families to explain at least 80% of lane runtime, whichever set is larger. - `status = slimmed` or `status = retained` requires a corresponding decomposition record. - If `currentBudgetSeconds` exists, it must match the checked-in family budget contract. ## 3. Family Cost Decomposition Record ### Purpose Represents the internal analysis for a targeted hotspot family so reviewers can see what part of the family is necessary and what part is duplicated or accidental. ### Fields - `familyId`: referenced hotspot family - `trustType`: primary trust delivered, such as `workflow-trust`, `surface-trust`, `guard-trust`, or `discovery-trust` - `requiredBreadth`: what breadth is genuinely needed for product trust - `duplicateWorkSources`: repeated work sources such as `repeated-livewire-mounts`, `header-action-gating-matrix`, `filter-state-persistence`, `audit-fan-out`, `resource-discovery-pass`, or `helper-graph-build` - `duplicateWorkEstimateSeconds`: optional estimate of removable cost - `residualCostSource`: `family-breadth`, `helper-driven`, `fixture-driven`, `mixed`, or `intentional-depth` - `recommendedAction`: `split-family`, `centralize-work`, `narrow-assertions`, `retain-as-heavy`, or `route-follow-up` - `notes`: reviewer-readable explanation ### Validation rules - Every `primary` hotspot family must have one decomposition record. - `recommendedAction = route-follow-up` requires `residualCostSource` to be `helper-driven`, `fixture-driven`, or `mixed`. - `recommendedAction = retain-as-heavy` requires `residualCostSource = intentional-depth`. - `duplicateWorkEstimateSeconds` may be omitted when cost is truly intentional, but the reason must be explicit. ## 4. Heavy Family Slimming Decision ### Purpose Represents the implementation-facing decision taken for a hotspot family after decomposition. ### Fields - `familyId`: referenced hotspot family - `decisionType`: `split`, `centralize`, `trim-duplicate-work`, `retain`, or `follow-up` - `scope`: list of files, helpers, or manifest entries touched by the decision - `guardPreservationPlan`: how the original governance trust remains protected - `expectedDeltaSeconds`: estimated improvement if known - `owner`: responsible maintainer or team role - `validationPlan`: focused tests or lane reruns needed to validate the decision ### Validation rules - Every `decisionType` other than `retain` must include at least one item in `scope`. - `guardPreservationPlan` is mandatory for all decisions. - `follow-up` decisions must name the residual cause and target seam. - `retain` decisions must still reference a validation plan showing why the retained heaviness is acceptable. ## 5. Budget Recovery Snapshot ### Purpose Represents one snapshot in the before-and-after lane measurement pair used to prove recovery or justify recalibration. ### Fields - `snapshotId`: stable identifier such as `pre-slimming` or `post-slimming` - `capturedAt`: ISO timestamp - `wallClockSeconds`: measured heavy-governance wall-clock time - `classificationTotals`: totals by classification - `familyTotals`: totals by family - `slowestEntries`: top slowest test entries - `artifactPaths`: references to summary, report, and budget artifacts - `budgetStatus`: `within-budget`, `warning`, or `over-budget` ### Validation rules - At least two snapshots are expected for a complete rollout: baseline and post-change. - `artifactPaths` must stay under `storage/logs/test-lanes`. - `familyTotals` must include the targeted hotspot families. - Summary, budget, and report artifacts captured for the same snapshot must not disagree on the authoritative threshold or budget outcome classification. ## 6. Budget Outcome Record ### Purpose Represents the final explicit outcome required by Spec 209. ### Fields - `outcomeId`: stable identifier - `decisionStatus`: `recovered` or `recalibrated` - `finalThresholdSeconds`: authoritative heavy-governance threshold after the rollout - `finalMeasuredSeconds`: measured post-change runtime - `deltaSeconds`: change from the baseline snapshot - `deltaPercent`: percentage change from the baseline snapshot - `remainingOpenFamilies`: families still above expected cost or still awaiting follow-up - `justification`: human-readable explanation of the decision - `followUpDebt`: optional residual items that remain outside the current scope ### Validation rules - `decisionStatus = recovered` requires `finalMeasuredSeconds <= finalThresholdSeconds`. - `decisionStatus = recalibrated` requires a non-empty `justification` explaining why the new threshold is honest. - `remainingOpenFamilies` may be non-empty only when their residual status is explicit. ## 7. Heavy Author Guidance Rule ### Purpose Represents a short reviewer or author rule for future heavy-governance tests. ### Fields - `ruleId`: stable identifier - `whenToUse`: the situation the rule applies to - `requiredDecision`: what the author or reviewer must decide - `antiPattern`: what overbroad behavior the rule prevents - `preferredOutcome`: the intended family or separation behavior ### Validation rules - Guidance must cover at least: when to create a new heavy family, when to reuse an existing family, when a test is too broad, and when discovery, workflow, and surface trust must be separated. ## 8. Current Measured Inventory Snapshot ### Current dominant families - `baseline-profile-start-surfaces` — `98.112193s` — `ui-workflow` — currently the largest heavy-governance family - `action-surface-contract` — `40.841552s` — `surface-guard` - `ops-ux-governance` — `38.794861s` — `surface-guard` - `findings-workflow-surfaces` — `36.459493s` — `ui-workflow` - `finding-bulk-actions-workflow` — `26.491446s` — `ui-workflow` - `workspace-settings-slice-management` — `21.740839s` — `ui-workflow` ### Current classification totals - `ui-workflow` — `190.606431s` - `surface-guard` — `106.845887s` - `discovery-heavy` — `0.863003s` ### Current budget signals - Lane summary threshold: `300s` and currently the authoritative pre-normalization contract - Budget target evaluation threshold: `200s` and currently legacy drift evidence, not a second passing threshold - Current measured lane wall clock: `318.296962s` This dual-signal state is intentional input to Spec 209 and must be resolved by the final budget outcome.