name: forest-carbon-projects-aoi
version: "0.1"
status: draft
category: compliance-reporting   # mrv-compliance pattern; audit against a registry standard
themes: [vegetation, climate]
family: carbon-project-aoi-audit
description: >
  Every nature-based carbon offset project overlapping an area of interest,
  from Cecil's Forest Carbon Project Boundaries (~575 projects, 55 countries).
  Clips the project polygons to the AOI and returns each project with its
  registry (Verra, Gold Standard, ...), methodology, type, developer, and
  claimed area — the inspectable "who claims to be doing carbon work here, under
  what standard." Designed as an audit layer: pair it with an independent
  forest-change observation to check whether the claimed footprint holds up.
  No magic — the output rows are the raw project records that intersect the AOI.

# Example AOI: Acre / Rondonia arc, western Brazilian Amazon (REDD+ cluster).
settings:
  aoi_west: -70.0
  aoi_south: -11.0
  aoi_east: -66.0
  aoi_north: -8.0
  continent: south_america     # pick the partition covering the AOI (or UNION all six)

inputs:
  aoi:
    bbox: [-70.0, -11.0, -66.0, -8.0]
    notes: >
      Projects carry a `bbox` STRUCT column, so overlap filtering is plain
      DuckDB comparisons. Select the continent partition covering the AOI, or
      UNION all six continent parquet files for a global query.
  dataset:
    uri: "@cecil/forest-carbon-project-boundaries"

layers:

  # ── SOURCE ──────────────────────────────────────────────────────────────
  source/projects:
    type: vector
    uri: "@cecil/forest-carbon-project-boundaries"
    description: Forest-carbon project boundaries (GeoParquet), continent-partitioned, with a bbox struct.
    params:
      asset: "${settings.continent}.parquet"

  # ── COMPUTE ─────────────────────────────────────────────────────────────
  compute/in-aoi:
    type: table
    description: Projects whose bounding box overlaps the AOI rectangle.
    compute:
      op: tabular_filter
      inputs:
        table: { layer: source/projects }
      params:
        where: >
          bbox.xmin <= ${settings.aoi_east} AND bbox.xmax >= ${settings.aoi_west}
          AND bbox.ymin <= ${settings.aoi_north} AND bbox.ymax >= ${settings.aoi_south}

  # ── RESULT ──────────────────────────────────────────────────────────────
  result/by-registry-type:
    type: table
    description: >
      Project count and total claimed area (ha) grouped by registry and project
      type within the AOI. project_area is text upstream — cast before summing.
    compute:
      op: tabular_aggregate
      inputs:
        table: { layer: compute/in-aoi }
      params:
        group_by: [registry_name, project_type]
        aggregations:
          projects: "COUNT(*)"
          claimed_area_ha_total: "SUM(TRY_CAST(project_area AS DOUBLE))"
        order_by: ["projects DESC"]

outputs:
  primary:
    - result/by-registry-type    # Parquet — projects + claimed area by registry/type
  show_your_work:
    - compute/in-aoi             # the individual project records overlapping the AOI

license:
  recipe: Apache-2.0
  output_dataset: CC-BY-4.0
  upstream_data:
    - { source: "@cecil/forest-carbon-project-boundaries", license: CC-BY-4.0 }