Associate a local terrain file with a recorded Survey Event — associate_study

Adds an explicit event grid selection using the existing terrain inventory. Original files, context, manifest records and associations are preserved. Selection enables metadata review, not scientific acceptance or FGDB loading.

associate_study_terrain(
  dsn,
  output_file,
  survey_event_id,
  terrain_file,
  evidence,
  analyst,
  manifest_file,
  report_file = NULL,
  report_purpose = "definition"
)

Arguments

dsn: Existing Study Area context GeoPackage.
output_file: New context .gpkg beside dsn.
survey_event_id: Exact saved Survey Event UUID.
terrain_file: Existing single-band GeoTIFF within the manifest folder or its descendants. No copying, export or reprojection is performed.
evidence: Nonempty basis for the file-to-event association.
analyst: Nonempty supplied attribution, not an approval signature.
manifest_file: New JSON path within the context folder tree. When an inventory already exists, save beside that manifest to preserve asset paths.
report_file: Optional new HTML report path.
report_purpose: Report view: definition (default), terrain or staging.

Value

List of context, report and manifest paths. Missing vertical metadata remains unknown. Existing file snapshots are never refreshed. A previously inventoried file can serve another event if its integrity checks pass. Existing event selections and duplicate associations are refused, not replaced. Outputs are not one transaction: failure after manifest publication retains it, and report failure can also retain context. Inspect retained outputs; use read-only reporting if the context was saved. Never mutate assets during this operation. No hierarchy, acquisition date or file equivalence is inferred.