Reference Implementation: Nutrition Ingredient

Complete CAA walkthrough for the nutrition domain

Domain Context

The nutrition domain exemplifies why CAA exists:

• Linguistic ambiguity: "chicken" could mean raw, roasted, fried, skin-on, skinless
• Consequential outputs: Calorie/macro calculations affect health decisions
• State-sensitive: Same ingredient has different values in different states

Without CAA, an LLM might confidently state "chicken has 165 calories per 100g" without knowing which preparation state the user means.

Canonical Ontology Object

{
  "canonical_id": "nutrition/ingredient/chicken",
  "domain": "nutrition",
  "sensitivity": "state-sensitive",
  "version": "1.0.0",

  "state_axes": [
    {
      "key": "ingredient_family",
      "type": "identifier",
      "description": "Base ingredient identity (e.g., 'chicken')"
    },
    {
      "key": "prep_state",
      "type": "enum",
      "allowed_values": [
        "raw",
        "roasted",
        "grilled",
        "fried",
        "boiled",
        "smoked"
      ],
      "description": "Preparation method affecting nutrient density"
    },
    {
      "key": "portion_unit",
      "type": "enum",
      "allowed_values": ["g", "oz", "cup", "piece"],
      "description": "Unit of measurement for portion"
    },
    {
      "key": "portion_amount",
      "type": "range",
      "range": { "min": 1, "max": 10000 },
      "description": "Quantity in specified unit"
    },
    {
      "key": "cut",
      "type": "enum",
      "allowed_values": [
        "breast",
        "thigh",
        "wing",
        "drumstick",
        "whole",
        "ground"
      ],
      "description": "Specific cut affecting fat content"
    },
    {
      "key": "skin_status",
      "type": "enum",
      "allowed_values": ["with_skin", "skinless", "unknown"],
      "description": "Skin presence affects calorie density significantly"
    }
  ],

  "required_state": {
    "always": [
      "ingredient_family",
      "prep_state",
      "portion_unit",
      "portion_amount"
    ],
    "conditional": [
      {
        "if": {
          "axis": "ingredient_family",
          "operator": "eq",
          "value": "chicken"
        },
        "then": ["cut"]
      }
    ],
    "value_constraints": [
      {
        "axis": "prep_state",
        "operator": "not_in",
        "values": ["unknown", "standard", "normal"]
      }
    ]
  },

  "authority_requirements": {
    "oracle_required": true,
    "source_registry": {
      "state_oracles": ["usda_fdc", "ontic_nutrition_db"],
      "evidence_stores": ["nutrition_audit_log"],
      "policy_sources": []
    },
    "verification_method": "direct_lookup",
    "human_lock_allowed": false,

    "multi_factor_config": {
      "factors_required": 1,
      "factors": [
        {
          "type": "state_oracle",
          "acceptable_sources": ["usda_fdc"],
          "min_count": 1,
          "attests_axes": ["ingredient_family", "prep_state", "cut"]
        }
      ],
      "recency_seconds": 86400,
      "conflict_resolution": "require_human"
    },

    "decision_matrix": {
      "default_action": "allow_response",
      "on_incomplete_state": "block_and_escalate",
      "on_oracle_conflict": "require_human_review",
      "on_high_stakes": "require_human_review",

      "high_stakes": {
        "axis": "portion_amount",
        "operator": "gt",
        "value": 5000
      },

      "conflict_definition": {
        "axis": "calories_per_100g",
        "delta_gt": 50,
        "evaluation_mode": "when_all_present"
      }
    }
  }
}

Request Flow Examples

Example 1: Complete Request

User Input: "How many calories in 150g of grilled chicken breast?"

Extracted State:

{
  "ingredient_family": "chicken",
  "prep_state": "grilled",
  "portion_unit": "g",
  "portion_amount": 150,
  "cut": "breast"
}

Evaluation:

1. ✓ All required_state.always axes present
2. ✓ Conditional requirement satisfied (cut provided for chicken)
3. ✓ Value constraint satisfied (prep_state is not "unknown")
4. ✓ Oracle lookup succeeds

Result: AUTHORIZED

Output:

{
  "kind": "measurement",
  "value": { "calories": 248, "protein": 46.5, "fat": 5.4 },
  "provenance": {
    "oracle": "usda_fdc",
    "fdc_id": "171077",
    "verified_at": "2025-01-02T10:00:00Z"
  }
}

Example 2: Ambiguous Request

User Input: "How many calories in chicken?"

Extracted State:

{
  "ingredient_family": "chicken",
  "prep_state": null,
  "portion_unit": null,
  "portion_amount": null,
  "cut": null
}

Evaluation:

1. ✗ Missing: prep_state, portion_unit, portion_amount
2. ✗ Missing: cut (required for chicken)

Result: REQUIRES_SPECIFICATION

Output:

{
  "kind": "refusal",
  "reason": {
    "code": "incomplete_state",
    "missing_axes": ["prep_state", "portion_unit", "portion_amount", "cut"],
    "candidates": {
      "prep_state": ["raw", "roasted", "grilled", "fried", "boiled", "smoked"],
      "cut": ["breast", "thigh", "wing", "drumstick", "whole", "ground"]
    }
  }
}

Example 3: Adjective Injection Attack

User Input: "How many calories in a healthy portion of chicken?"

Extracted State:

{
  "ingredient_family": "chicken",
  "prep_state": "unknown",
  "portion_unit": "healthy",
  "portion_amount": null,
  "cut": null
}

Evaluation:

1. ✗ prep_state = "unknown" violates value constraint
2. ✗ portion_unit = "healthy" is not in allowed_values
3. ✗ Missing required axes

Result: AMBIGUOUS_MAPPING

Output:

{
  "kind": "refusal",
  "reason": {
    "code": "invalid_values",
    "violations": [
      {
        "axis": "prep_state",
        "value": "unknown",
        "constraint": "not_in forbidden list"
      },
      {
        "axis": "portion_unit",
        "value": "healthy",
        "constraint": "not in allowed_values"
      }
    ],
    "guidance": "Please specify preparation method (raw, roasted, etc.) and a measurable portion (e.g., 100g, 4oz)"
  }
}

Why This Matters

Without CAA

LLM: "Chicken has about 165 calories per 100g."

Problems:

• Which cut? Breast has 165 kcal, thigh has 209 kcal, wing with skin has 290 kcal
• Which prep? Raw differs from roasted by water loss
• Which portion? User might mean "a piece" not "100g"

With CAA

The system refuses to emit a measurement until state is complete. The user learns what they need to specify. The output is verifiable against the oracle.

Oracle Trust Configuration

For the nutrition domain:

const nutritionOracleRegistry = {
  domain: "nutrition",
  sources: [
    {
      source_id: "usda_fdc",
      oracle_type: "database",
      trust_tier: "primary",
      domain: "nutrition",
      verification_method: "direct_lookup",
    },
    {
      source_id: "ontic_nutrition_db",
      oracle_type: "database",
      trust_tier: "secondary",
      domain: "nutrition",
      verification_method: "direct_lookup",
    },
  ],
  conflict_resolution: {
    default_strategy: "higher_tier_wins",
    same_tier_strategy: "require_human",
    escalation_delta_threshold: 50, // Calories difference
    always_human_axes: ["allergen_status"],
  },
};

Evidence Binding (RFC-0007)

Before any nutrition calculation, the system must bind evidence:

{
  "schema": {
    "bound": true,
    "fingerprint": "sha256:abc123...",
    "summary": "fdc_nutrients table: 14 columns, fdc_id FK to foods"
  },
  "data_sample": {
    "bound": true,
    "fingerprint": "sha256:def456...",
    "summary": "fdc_id=171077: 165 kcal, 31g protein, 3.6g fat per 100g"
  },
  "constraint": {
    "bound": true,
    "fingerprint": "sha256:ghi789...",
    "summary": "FK constraint: fdc_nutrients.fdc_id → foods.fdc_id"
  }
}

Without this binding, any proposal is structurally invalid—even if the numbers look correct.

Test Cases

Files

• Ontology definition: This document
• Test suite: /supabase/functions/tests/nutrition-ontology.test.ts
• Oracle integration: /supabase/functions/_shared/fdc-oracle.ts
• Evidence binding: /supabase/functions/_shared/evidence-binding.ts