Record attributed source-use evidence for an inventoried terrain artifact

Saves one candidate, recorded-use account, or rejection in a new Study Area context. Source identity is explicitly namespaced; no catalog query, automatic matching, source download, terrain transformation or acceptance occurs.

record_study_terrain_source(
  dsn,
  output_file,
  association_id,
  artifact_id,
  source_catalog,
  source_record_id,
  source_snapshot,
  source_description,
  status,
  basis,
  evidence,
  analyst,
  source_version = NA_character_,
  report_file = NULL,
  report_purpose = "definition"
)

Arguments

dsn: Existing saved Study Area context with a terrain manifest.
output_file: New context .gpkg beside dsn. Retain earlier snapshots.
association_id: Caller-supplied local claim ID. Reusing it explicitly revises status/evidence/description/attribution, not its target or source key.
artifact_id: Exact GeoTIFF artifact ID in the linked manifest. Its saved SHA-256 pins the derivative; availability remains a separate report finding.
source_catalog: Nonempty source namespace, such as WESM, USIEI, or a documented local archive namespace. No public catalog membership is required.
source_record_id: Exact identifier in that namespace, not an FG event ID.
source_snapshot: Nonempty locator/reference for the metadata or archive record consulted. This is retained text, not fetched or checksum-verified.
source_description: Human-readable source/product description.
status: CANDIDATE, RECORDED_USE, or REJECTED. RECORDED_USE is an attributed account of use, not independently verified lineage or processing execution.
basis: PROJECT_RECORD or OWNER_RECOLLECTION; both require evidence.
evidence: Nonempty account of support, limitations and competing claims.
analyst: Nonempty recorder attribution, not an approval signature.
source_version: Optional source edition/version; NA means unresolved. Neither a catalog ID nor a version string establishes exact source bytes.
report_file: Optional new HTML report; no fresh reference inspection is required to show saved source-use evidence.
report_purpose: definition (default), terrain, or staging.

Value

List with context and report paths. Uses FLUVGEO_STUDY_CONTEXT_3; schema-1/2 contexts remain readable. Multiple sources per artifact and reuse across artifacts are supported without merging catalog identities or events. No in-file revision ledger is created. A later report failure retains the context for inspection/retry. Source products, recipes, source checksums, recoverability and cross-catalog reconciliation remain separate work.