Caloric Content / Macronutrient Calculator mechanism

Model scope

The core calorie formula is valid for an educational Atwater-style estimate. Before release, specify the exact percentage categories and denominator, define carbohydrate and fiber treatment, set validation and rounding rules, and label the result as an estimate rather than a regulatory nutrition-label calculation.

• The 4/4/9 Atwater factors, plus 7 kcal/g for alcohol, are standard estimates when protein, available carbohydrate, fat, and alcohol are supplied in grams.
• The specification does not define whether alcohol is included in the percentage denominator or reported separately, making the requested macro percentages ambiguous.
• The specification does not define treatment of dietary fiber, sugar alcohols, organic acids, or other components that can cause calculated calories to differ from regulated food-label calories.
• The specification does not define rounding rules for total kcal or percentages.

Units and conventions

• All inputs are grams, not ounces or other mass units.
• Protein and available carbohydrate contribute 4 kcal/g, fat contributes 9 kcal/g, and alcohol contributes 7 kcal/g.
• Test percentages use each component's calculated kcal divided by total calculated kcal, including alcohol when present.
• Percentages below are rounded to two decimal places; intermediate arithmetic uses unrounded values.

Inspectable vector

One of 4 source-bound review vectors:

{
  "inputs": {
    "protein_g": 20,
    "carb_g": 30,
    "fat_g": 10,
    "alcohol_g": 0
  },
  "expected_outputs": {
    "total_kcal": 290,
    "protein_percent": 27.59,
    "carb_percent": 41.38,
    "fat_percent": 31.03,
    "alcohol_percent": 0
  },
  "working": "Protein kcal = 4 × 20 = 80. Carb kcal = 4 × 30 = 120. Fat kcal = 9 × 10 = 90. Alcohol kcal = 7 × 0 = 0. Total = 80 + 120 + 90 + 0 = 290 kcal. Protein percentage = 80 ÷ 290 × 100 = 27.59%. Carb percentage = 120 ÷ 290 × 100 = 41.38%. Fat percentage = 90 ÷ 290 × 100 = 31.03%. Alcohol percentage = 0 ÷ 290 × 100 = 0.00%."
}

Failure boundary

BREAK_CLAIMED · SELF_FLAGGED

The all-zero input produces a valid total of 0 kcal but makes every percentage calculation 0/0 and therefore undefined. An implementation without an explicit zero-denominator guard will return invalid numeric results such as NaN or Infinity.

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche5/tranche5-results.json
• BOUNDARY_HAZARD_CATALOG.json