TenantAtlas/specs/209-heavy-governance-cost/data-model.md

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.