# supply-shed-change-brazil — NATIONAL profile of supply-shed-change (ADR-0080, docs/spec/SUPPLY_SHED.md).
#
# Same layer DAG as registry/recipes/supply-shed-change, with the parameter DEFAULTS set to the
# all-Brazil cane profile: 319 mills (mills_brazil.geojson, ANP capacity), the national cane
# transition table (transitions_national.parquet, post==cane rolled to res-7, built by
# supply-shed-brazil/inputs/build_national_transitions.py), and the national bbox at h3:6.
# This is the "profile = parameter set, not new code" test of ADR-0080 — it exists because the
# CLI has no parameter-override flag yet (ENGINE_READINESS "still open"), so national is a
# sibling recipe, not a run flag.
#
# Run it per method (edit `method` default between runs, the supply-shed-brazil pattern):
#   products/sdk/target/debug/folia run registry/recipes/supply-shed-change-brazil --no-cache
# then serialize + cane-mask for the map:
#   cd demos/sugarcane-sourcing-luc && /tmp/gpq/bin/python scripts/engine_export.py \
#       --run-dir ../../registry/recipes/supply-shed-change-brazil \
#       --facilities ../../registry/recipes/supply-shed-change-brazil/inputs/mills_brazil.geojson \
#       --out outputs/national_engine

spec_version: folia/0.1
name: supply-shed-change-brazil
version: "0.1.0"
description: >
  National (all-Brazil) profile of supply-shed-change: 319 sugar mills -> capacity-weighted
  sourcing sheds -> cane land-use-change per shed, cane-masked to real MapBiomas cane. Straight-
  line; a drive-time profile adds the OSRM distances table.

parameters:
  facilities_uri:
    type: string
    description: Facility points (GeoJSON) with an optional capacity column.
    default: "local://inputs/mills_brazil.geojson"
  transitions_uri:
    type: string
    description: >
      National per-H3 cane transitions (GeoParquet: h3, prior, post, area_ha; post==cane only).
    default: "local://inputs/transitions_national.parquet"
  distances_uri:
    type: string
    description: >
      Drive-time cost table (facility, h3, minutes) for distance=drivetime. Straightline loads
      but ignores it; this default is a one-row placeholder.
    default: "local://inputs/drivetime_stub.parquet"
  bbox:
    type: array
    items: number
    description: National allocation-universe 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
  method:
    type: string
    description: Allocation rule — huff (capacity-weighted gravity) or voronoi (nearest).
    default: huff
  distance:
    type: string
    description: Distance metric — straightline (in-engine haversine km) or drivetime (OSRM table).
    default: straightline
  unit:
    type: string
    description: Allocation unit (h3:N). Res-6 (~36 km2) is the national overview default.
    default: "h3:6"
  haul_km:
    type: number
    description: Haul bound (km) for distance=straightline.
    default: 60.0
    minimum: 1
  haul_min:
    type: number
    description: Haul bound (drive-time MINUTES) for distance=drivetime.
    default: 90.0
    minimum: 1
  beta:
    type: number
    description: Huff distance-decay exponent (assign to argmax capacity/dist^beta).
    default: 2.0
    minimum: 0
  capacity_field:
    type: string
    description: Per-facility capacity column (tonnes cane/season).
    default: capacity_tc
  target_class:
    type: number
    description: The commodity class transitions are screened INTO (MapBiomas 20 = sugar cane).
    default: 20
  native_forest:
    type: array
    items: number
    description: Native-forest prior classes (MapBiomas Collection 10).
    default: [1, 3, 5, 6, 49]
  native_veg:
    type: array
    items: number
    description: Native non-forest vegetation prior classes (savanna, wetland, grassland...).
    default: [4, 10, 11, 12, 13, 50]

layers:

  # The three sources use the sanctioned spelling (ADR-0074 D3): a pointer + the read that
  # consumes it. `mechanism:` names the read because each pointer is a PARAMETER, so there is no
  # suffix to infer from. Desugars to the same ops (geojson_vector / geoparquet_vector) with the
  # same effective params, so the committed `folia.lock.json` keys unchanged.
  facilities:
    type: vector
    description: Facility points with capacity; row order is the facility index.
    uri: { param: facilities_uri }
    mechanism: local-file

  transitions:
    type: table
    description: Per-H3-cell prior->post cane transition areas (post==cane).
    uri: { param: transitions_uri }
    mechanism: table-query

  distances:
    type: table
    description: Per-(facility, cell) road drive-time minutes (used when distance=drivetime).
    uri: { param: distances_uri }
    mechanism: table-query

  shed:
    type: table
    description: >
      Per-cell facility assignment: h3, facility (-1 = unreachable), score, distance_km,
      n_within_haul (the fixed-radius double-count).
    compute:
      op: supply_shed_allocate
      inputs:
        facilities: { layer: facilities }
        distances: { layer: distances }
      params:
        method: { param: method }
        distance: { param: distance }
        unit: { param: unit }
        haul_km: { param: haul_km }
        haul_min: { param: haul_min }
        beta: { param: beta }
        bbox: { param: bbox }
        capacity_field: { param: capacity_field }

  transitions_matrix:
    type: table
    description: From-class -> to-class area (ha) per shed.
    compute:
      op: raster_transition_matrix
      inputs:
        transitions: { layer: transitions }
        assignment: { layer: shed }
      params:
        mode: prebinned
        output: matrix

  shed_summary:
    type: table
    description: Per shed target-class area, new conversion, native-forest / native-veg slices.
    compute:
      op: raster_transition_matrix
      inputs:
        transitions: { layer: transitions }
        assignment: { layer: shed }
      params:
        mode: prebinned
        output: summary
        class_scheme:
          target: { param: target_class }
          native_forest: { param: native_forest }
          native_veg: { param: native_veg }

outputs:
  shed:
    layer: shed
    value_kind: table
    description: Per-cell facility assignment.
  transitions_matrix:
    layer: transitions_matrix
    value_kind: table
    description: From-class -> to-class area (ha) per shed.
  shed_summary:
    layer: shed_summary
    value_kind: table
    description: Per-shed target area, new conversion, native slices.

# 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: compliance-reporting
  folia/themes: [agriculture, land-cover]
  folia/family: sourcing-shed-land-use-history