# OrchardSnacks Complete Technical Reference & Dataset Specification
URI: https://orchardsnacks.com/llms-full.txt
Version: 2.0.0
Author: OrchardSnacks Data Architecture Team
License: Open Data Commons Attribution License (ODC-By)

## 1. Probabilistic Traceback Architecture
Traditional food traceability relies on closed enterprise barcodes (GS1-128, IBM Food Trust, FoodLogiQ, SAP). Because consumers only have access to item-level stickers and shelf placards, OrchardSnacks introduces a deterministic-probabilistic graph traversal engine:

Inputs:
1. Commodity & PLU (Price Look-Up code, 4-digit conventional or 5-digit organic starting with 9).
2. Country or Region of Origin (Mandated by Country of Origin Labeling - COOL laws in US/EU).
3. Purchase Store & Destination ZIP (Resolving to retail supermarket regional distribution centers).

Supply Chain Graph Topology:
Stage 1: Harvest Orchard (centroid coordinates of producing agricultural sub-basin).
Stage 2: Regional Cold Storage & Forced-Air Precooling Packhouse.
Stage 3: Port of Lading (Maritime departure terminal or overland export consolidation depot).
Stage 4: Port of Entry & Inspection (Customs and Border Protection + USDA APHIS quarantine clearance).
Stage 5: Regional Distribution Center (RDC) with ripening conditioning if applicable.
Stage 6: Retail Store Shelf (Local grocery store in consumer's zip code).

## 2. Emission & Carbon Calculation Methodology
Emissions are modeled per 1 kilogram of fresh produce arriving at retail shelf using the Global Logistics Emissions Council (GLEC) Framework:

Carbon Intensity Factors (grams CO2e per short ton-mile):
- Maritime Reefer Vessel: 24 g CO2e / ton-mile (high thermal efficiency per unit mass across bulk voyages).
- Overland Refrigerated Class 8 Diesel Tractor-Trailer: 175 g CO2e / ton-mile (including diesel auxiliary refrigeration power unit).
- Refrigerated Rail Intermodal: 45 g CO2e / ton-mile.
- Air Cargo (Widebody belly or freighter): 780 g CO2e / ton-mile.

Formulas:
- Nautical Miles: Haversine great-circle distance multiplied by 1.35 maritime routing circumnavigation factor (accounting for chokepoints like the Panama Canal).
- Overland Miles: Interstate highway corridor routing between border crossing/port and RDC/store.
- Total Carbon = sum(leg_distance_miles * cargo_weight_tons * mode_emission_factor)

## 3. Post-Harvest Physiology Across the 6 Perennial Orchard Classes
Fruit age at retail is dictated by post-harvest respiratory biology and specialized handling across the 6 perennial orchard classes:

### Class 1: Pome Fruits (Apples, Pears)
- Apples (Honeycrisp, Gala, Fuji): Climacteric fruit treated with 1-MCP (1-Methylcyclopropene) to block ethylene receptors, then held in Ultra-Low Oxygen (ULO) vaults (1.0%–1.5% O2, 1% CO2, 33–34°F). This slows cellular respiration by 95% and extends commercial viability up to 330 days (11 months).
- Pears (Bartlett, Bosc, Anjou): Non-tree ripening fruit. Must be picked firm-mature and subjected to a 30-day "cold shock" at 31°F (-0.5°C) to break physiological dormancy before commercial ethylene conditioning activates uniform buttery ripening.

### Class 2: Stone Fruits / Drupes (Peaches, Cherries, Plums, Nectarines)
- Peaches & Nectarines: Extremely sensitive to chilling injury between 36°F and 46°F (the "Kill Zone"), where internal pectin degrades improperly into mealy, woolly flesh. Must be kept strictly at 31°F–32°F or ripened immediately at 68°F.
- Sweet Cherries (Bing, Rainier): Non-climacteric and highly perishable. Must undergo immediate forced hydrocooling within minutes of picking to reduce core temperature from 85°F to 34°F. Shipped under high CO2 (10–15%) modified atmosphere box liners to preserve emerald-green stems.

### Class 3: Citrus Orchards (Navel Oranges, Lemons, Limes)
- Navel & Valencia Oranges: Non-climacteric. Early-season fruit with sweet pulp frequently retains green chlorophyll rinds; commercial packhouses utilize warm degreening rooms (70°F with 1–5 ppm ethylene) for 48 hours to unveil orange pigmentation.
- Lemons (Eureka, Lisbon): Stored in warm curing vaults at 52°F (11.1°C) and 85% relative humidity to prevent peel pitting and chilling lesions. Curing thins the rind and increases juice volume by 20%.
- Persian Limes: Picked at peak chlorophyll maturity in Martínez de la Torre, Veracruz. Rushed across the border at 48°F–50°F within 48 hours to prevent oleocellosis skin lesions.

### Class 4: Tree Nut Crops (California Almonds, Pecans)
- California Nonpareil Almonds: Perennial drupe seeds mechanically shaken onto orchard floors for solar drying to <6% moisture content. Governed by USDA-mandated pasteurization protocols (propylene oxide or high-temperature steam) to eradicate Salmonella before ambient or 40°F warehouse storage.

### Class 5: Berries & Vine Fruits (Blueberries, Table Grapes, Kiwifruit, Tomatoes)
- Table Grapes: Maintained at 31.5°F (-0.3°C) with dual-release sodium metabisulfite (SO2) pads placed inside each carton to release fungistatic sulfur dioxide gas, inhibiting Botrytis cinerea gray mold over 30-day ocean transits.
- Blueberries: Coated in natural epicuticular bloom wax. Shipped in modified atmosphere sea reefers with 10–15% CO2 to avoid chemical fungicide application.
- SunGold & Hayward Kiwifruit: Hyper-sensitive to ethylene gas (>10 ppb causes rapid softening). Shipped from New Zealand across 6,000 miles in specialized sea reefers equipped with continuous catalytic ethylene scrubbers and ultra-low oxygen.
- Roma & Vine Tomatoes: Must never be chilled below 50°F (10°C) to prevent irreversible aroma gene shutdown (cis-3-hexenal) and chilling injury.

### Class 6: Subtropical & Tropical Fruits (Avocados, Mangoes, Bananas, Pineapple)
- Cavendish & Organic Bananas: Transported in profound metabolic stasis at precisely 56.5°F (13.6°C) inside controlled-atmosphere sea reefers (2–3% O2, 5% CO2) from Ecuador and Costa Rica. Ripened in pressurized regional distribution center vaults using catalytic ethylene before store shelf stocking.
- Hass Avocados: Cannot ripen while attached to the tree due to an endogenous inhibitor. Commercial size grades (#4046 Small/Medium, #4225 Large, #4770 Extra Large) transported at 42°F in 2–3% O2 and 4–10% CO2.
- Mangoes (Tommy Atkins, Ataulfo): Subject to mandatory USDA-APHIS Hot Water Dip quarantine treatment (submersion at 115°F / 46.1°C for 65–90 minutes) in Mexican and Peruvian packhouses to eradicate Tephritidae fruit fly larvae prior to entering US cold chains at 54°F.
- Golden Ripe Pineapple (MD2): Non-climacteric composite fruit harvested at physiological sugar maturity in Costa Rica; transported at 45°F–50°F to prevent chilling breakdown.

## 4. Origin Watershed Water Stress Ratings
Sourced from World Resources Institute (WRI) Aqueduct 4.0:
- Chavimochic / Olmos (Peru): Score 4.8 / 5.0 (Extremely High). Irrigated coastal hyper-desert relying on trans-Andean river diversions.
- Petorca / Aconcagua (Chile): Score 4.7 / 5.0 (Extremely High). Historic multi-decade drought; groundwater overdraft for avocados and grapes.
- San Joaquin / Central Valley (California): Score 4.6 / 5.0 (Extremely High). Governed by California SGMA groundwater restriction mandates.
- Michoacán Highlands (Mexico): Score 4.1 / 5.0 (High). Intensive volcanic aquifer extraction.
- Culiacán / Sinaloa Coast (Mexico): Score 4.0 / 5.0 (High). Dam reservoir irrigation for export mango and winter vegetable crops.
- Central Florida Citrus Ridge: Score 3.1 / 5.0 (Medium-High). Floridan aquifer stress and citrus greening pressures.
- Yakima Valley (Washington State): Score 3.2 / 5.0 (Medium-High). Snowpack-dependent reservoir system for pome and cherry orchards.
- Hood River Valley (Oregon): Score 2.2 / 5.0 (Low-Medium). Glacial runoff from Mt. Hood supplying gravity-fed pear orchards.
- Fort Valley Peach Ridge (Georgia): Score 2.1 / 5.0 (Low-Medium). Cretaceous sand aquifer with subtropical rainfall surplus.
- Alto Valle of Río Negro (Argentina): Score 2.4 / 5.0 (Low-Medium). Andean snowmelt feeding Patagonian pear and apple canals.
- Bay of Plenty (New Zealand): Score 2.2 / 5.0 (Low-Medium). Volcanic aquifers and abundant maritime rainfall.
- San Carlos & Upala (Costa Rica): Score 1.4 / 5.0 (Low). High tropical rainfall basin supplying sustainable pineapple production.

## 5. API Endpoints
- GET /api/trace?plu={plu}&origin={origin}&zip={zip}&chain={chain}
  Returns full TraceResult object with waypoints, distances, transit days, carbon metrics, and quarantine phytosanitary protocols.
- GET /api/commodities
  Returns list of all 17 commodities across the 6 orchard categories, PLU variants, and seasonal calendars.
- POST /api/scan-sticker
  Multimodal AI vision & barcode decoding endpoint for produce stickers. Extracts 4-digit PLUs, 5-digit organic indicators, and COOL origin country.