Record a Study Area analysis-reference choice in a new context — record_study_analysis

Records or explicitly revises one project-wide analysis choice, not a source declaration, executed transformation, or approval. Values are descriptive text, not validated CRS definitions or unit-conversion instructions. Prior context files, other components, terrain and manifest assertions are preserved.

record_study_analysis_reference(
  dsn,
  output_file,
  component,
  value,
  basis,
  evidence,
  analyst,
  report_file = NULL,
  report_purpose = "definition"
)

Arguments

dsn: Existing saved Study Area context GeoPackage.
output_file: New context .gpkg beside dsn.
component: One of horizontal, vertical, elevation_unit.
value: Nonempty description of the choice. State exceptions/limitations in evidence; a project-wide record does not certify every event or DEM.
basis: PROJECT_RECORD, OWNER_RECOLLECTION, or PROPOSED. A proposal is not an established choice; corroboration is not inferred from saving.
evidence: Nonempty source, rationale and qualifications for this choice.
analyst: Nonempty recorder attribution, not an approval signature.
report_file: Optional new HTML report. Saved choices are visible without opting in to fresh terrain-file inspection.
report_purpose: definition (default), terrain, or staging.

Value

List with context and report paths. Schema-1 inputs remain readable; contexts containing choices use FLUVGEO_STUDY_CONTEXT_2. New-file publication preserves the source. A later report failure retains the new context for inspection and retry. No in-file revision ledger or cryptographic signature is created; retain prior snapshots. No missing choice is inferred.