# supply-shed-brazil — national sourcing-shed METHODS map (ADR-0080, docs/spec/SUPPLY_SHED.md).
#
# The allocation half of supply-shed-change, run over ALL 319 Brazil sugarcane mills, to
# compare allocation METHODS on one national map (straight-line Voronoi vs capacity-weighted
# Huff). No land-use layer here — this recipe is just facilities -> shed, so it needs only the
# mills (no national MapBiomas read). The from->to land-use change is the separate
# supply-shed-change recipe / a national transitions input.
#
# Run it per method (the map switches between them):
#   folia run registry/recipes/supply-shed-brazil                    # method default (huff)
#   (flip `method` default to voronoi for the nearest-mill partition)
#
# res-6 (~36 km2 cells) is the national default — a smooth country-wide overview; res-7 fits
# under the engine's grid-sample cap for the cane belt if finer detail is wanted.

spec_version: folia/0.1
name: supply-shed-brazil
version: "0.1.0"
description: >
  National sourcing sheds for all 319 Brazil sugarcane mills: partition Brazil's land cells to
  each mill by allocation method (straight-line nearest = voronoi, or capacity-weighted gravity
  = huff), for a methods-comparison map. Capacity weighting is the axis where this exceeds the
  open incumbents (PalmWatch is unweighted).

parameters:
  facilities_uri:
    type: string
    description: All-Brazil mill points + ANP capacity (row order = facility index).
    default: "local://inputs/mills_brazil.geojson"
  method:
    type: string
    description: huff (capacity-weighted gravity) or voronoi (straight-line nearest).
    default: huff
  unit:
    type: string
    description: Allocation unit. res-6 (~36 km2) is the national default.
    default: "h3:6"
  haul_km:
    type: number
    description: Straight-line haul bound (km).
    default: 60.0
    minimum: 1
  beta:
    type: number
    description: Huff distance-decay exponent.
    default: 2.0
    minimum: 0
  capacity_field:
    type: string
    description: Per-facility capacity column (tonnes cane/season).
    default: capacity_tc
  bbox:
    type: array
    items: number
    description: National allocation bbox [w, s, e, n] (mill extent + a haul margin).
    default: [-60.6, -24.5, -34.4, -1.5]
    min_items: 4
    max_items: 4

layers:

  # The sanctioned source spelling (ADR-0074 D3): a pointer + the read that consumes it.
  # `mechanism:` names the read because the pointer is a PARAMETER, so there is no suffix to
  # infer from.
  facilities:
    type: vector
    description: All-Brazil mill points with capacity.
    uri: { param: facilities_uri }
    mechanism: local-file

  shed:
    type: table
    description: >
      Per-cell mill assignment: h3, facility (int; -1 = beyond every mill's haul), score,
      distance_km, n_within_haul (the fixed-radius double-count).
    compute:
      op: supply_shed_allocate
      inputs:
        facilities: { layer: facilities }
      params:
        method: { param: method }
        distance: straightline
        unit: { param: unit }
        haul_km: { param: haul_km }
        beta: { param: beta }
        bbox: { param: bbox }
        capacity_field: { param: capacity_field }

outputs:
  shed:
    layer: shed
    value_kind: table
    description: National per-cell mill assignment under the chosen method.

# Shelf facets. A governed recipe carries these under `extensions:`, never at the
# top level: AuthorRecipe is deny_unknown_fields, so a top-level `category:` stops
# the recipe binding at all.
extensions:
  folia/category: risk-suitability
  folia/themes: [agriculture, boundaries]
  folia/family: supply-shed-delineation