@callback artifacts(manifest :: GeoGenius.Manifest.t()) :: [
  GeoGenius.Manifest.Artifact.t()
]

The artifacts, across a manifest's sources, this provider will stage.

The pipeline asks this once per source, with the manifest narrowed to that one source, so a provider delegating to all_artifacts/1 answers with its own source's artifacts. A release may name a different provider per source, and each logical name is staged by the provider of the source that declared it.

@callback asserted_relations(
  manifest :: GeoGenius.Manifest.t(),
  row :: GeoGenius.Staging.Row.t()
) :: [
  {parent_area_key :: String.t(), child_area_key :: String.t(),
   relation_type :: String.t()}
]

Relation edges this row asserts, which geometry cannot measure.

A source that carries its hierarchy in columns -- a county FIPS on every city row, an admin parent code on every place -- knows edges no overlap test can derive, and a source with no geometry at all has no other way to express one. Each edge is {parent_area_key, child_area_key, relation_type}, where relation_type is "contains", "mostly_contains", or "overlaps".

Both keys are the strings GeoGenius.Provider.Area.key/1 composes. Build the %GeoGenius.Provider.Area{} an edge names and take its key from there, rather than joining the three parts by hand: an edge composed a second way can name a key normalize/2 never produced, and GeoGenius.Catalog.put_relation/4 refuses an area the release does not carry.

Composes with relations/1 rather than replacing it: a provider whose areas nest spatially may both rebuild measured relations and assert edges the geometry does not carry. Edges are written after every area exists, so an edge may reference an area any row emitted, not only its own.

Asserting an edge for a pair relations/1 also rebuilds from geometry overwrites that measurement: GeoGenius.Catalog.put_relation/4 upserts on the same (parent_area_id, child_area_id) pair, nulling intersection_area_m2, parent_coverage, and child_coverage and replacing the geometry-classified relation_type with the asserted one, with no warning that a measurement was discarded. A provider returning :rebuild should assert only pairs geometry cannot derive, keeping the two sets of edges disjoint.

@callback normalize(manifest :: GeoGenius.Manifest.t(), row :: GeoGenius.Staging.Row.t()) ::
  {:ok, GeoGenius.Provider.Area.t()}
  | {:ok, [GeoGenius.Provider.Area.t()]}
  | :skip
  | {:error, reason()}

Describes one staged row as an area, or as several.

Returns :skip for a row that carries no area -- a header, a summary record, a feature with no usable code -- rather than an error, since that is an expected shape for some rows rather than a failure.

A list is for a source that denormalises a hierarchy into every row: a city row that also carries its county and state describes all three, and returning them together is cheaper and truer than staging the same row once per level. Areas repeated across rows converge on area_key, so a provider emits an implied parent from every row that implies it rather than tracking which it has already emitted.

@callback relations(manifest :: GeoGenius.Manifest.t()) :: :rebuild | :none

Whether the areas this provider stages need parent_area_id relations rebuilt after normalization.

:rebuild for a provider whose areas nest spatially or by code; :none for a provider whose collection carries no hierarchy.

@callback required_options() :: [String.t()]

The manifest options keys this provider requires.

Manifest validation checks that every key named here is present in a manifest's options map before the manifest is accepted.

@callback stage(
  manifest :: GeoGenius.Manifest.t(),
  artifact :: GeoGenius.Manifest.Artifact.t(),
  path :: Path.t(),
  emit :: ([GeoGenius.Staging.Row.t()] -> :ok),
  opts :: stage_opts()
) :: :ok | {:error, reason()}

Parses path -- the downloaded or operator-supplied copy of artifact -- and hands each resulting batch of rows to emit.

opts carries the adapters described above. Returns {:error, reason} for a file this provider cannot parse; never raises for a malformed file, only for a defect in the provider itself.

@callback validate_manifest(manifest :: GeoGenius.Manifest.t()) ::
  :ok | {:error, reason()}

Validates relationships between fields of a fully decoded manifest.

Optional. GeoGenius.Manifest calls this after its own structural checks and validate_options/1, so a provider can enforce a policy spanning options, area types, authorities, or sources without putting source-specific rules in the manifest parser. Every provider named by the release or one of its sources receives the same complete manifest.

@callback validate_options(options :: map()) :: :ok | {:error, reason()}

Validates the manifest options map as a whole, beyond the presence of the keys required_options/0 names.

Optional. A provider that exports it is called at manifest load, once every required key is known to be present, and an error it returns becomes a GeoGenius.ManifestError naming the field. That is what makes a malformed option fail before a release row exists, rather than partway through normalizing an artifact already downloaded and staged.

This is where a provider checks the options only it understands. The option vocabulary is per-provider, so the same document can be valid under one provider and invalid under another: GeoGenius.Providers.GeoJSON reads an implied_areas entry's code key as "code_property" and GeoGenius.Providers.CSV reads it as "code_column", and neither accepts the other's.

A provider still validates what it reads at the point it reads it. A %GeoGenius.Manifest{} built in Elixir never passes through GeoGenius.Manifest.from_map/2, so this is a gate on loaded documents, not a guarantee normalize/2 may rely on.