stage_contract.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2025 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
// The single, machine-readable source of truth for what each pipeline stage
// consumes and produces in a `.rux` project (#246).
//
// This table used to exist three times: as a hand-written `switch` in
// `core::check_stage_inputs()`, as
// `rux::validation::validate_*_prerequisites()` in the CLI, and as prose in
// docs/CONTRACTS.md. The three could — and did — disagree, so `rux validate
// --stage mesh` could pass while `rux create mesh` refused. Everything now
// reads THIS table:
//
//   core::check_stage_inputs()   interprets it against a ProjectDB
//   pipeline::run_stage()        refuses through check_stage_inputs()
//   apps/rux                     gates every subcommand through it
//   docs/CONTRACTS.md            is a prose mirror, asserted by a unit test
//
// Layering (STANDARDS §1): the table is pure data — enums and names — with no
// PCL/CGAL/ProjectDB in it, so it sits at the lowest layer every consumer can
// reach. `pipeline` is Layer 4 and could not be read from `core`; `utils` would
// divorce it from the ProjectDB naming semantics it describes. Hence `core`.
 
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace reusex::core {

enum class PipelineStage {
  import,     
  optimize,   
  clouds,     
  annotate,   
  project,    
  planes,     
  rooms,      
  instances,  
  mesh,       
  texture,    
  windows,    
  materials,  
  survey,     
  attributes, 
  // `gsplat` consumes `cloud` + `sensor_frames`, so anywhere after `clouds`
  // would satisfy the ordering invariant. It sits last because it is a LEAF:
  // it produces a `splat` nothing else consumes, so putting it mid-table would
  // read as if the reconstruction spine ran through it. Leaves at the end also
  // keeps the numbering of the existing stages stable.
  gsplat, 
};

enum class ArtifactKind {
  point_cloud,    
  mesh,           
  gaussian_splat, 
  table,          
};

enum class Alignment {
  none,      
  per_point, 
  per_plane, 
};

struct Artifact {
  std::string_view name;
  ArtifactKind kind = ArtifactKind::point_cloud;
  Alignment alignment = Alignment::none;
  std::string_view description;
};

struct StageInput {
  std::vector<std::string_view> any_of;
  int min_rows = 1;
  int min_depth_frames = 0;
};

struct StageContract {
  PipelineStage stage;
  std::string_view name;
  std::vector<std::string_view> aliases;
  std::string_view command;
  std::string_view summary;
  std::vector<StageInput> inputs;
  std::vector<std::string_view> outputs;
  std::string_view external_outputs = {};
};

const std::vector<StageContract> &stage_contracts();

const StageContract &stage_contract(PipelineStage stage);

const std::vector<Artifact> &pipeline_artifacts();

const Artifact *find_artifact(std::string_view name);

std::optional<PipelineStage> producing_stage(std::string_view artifact);

std::optional<PipelineStage> parse_pipeline_stage(std::string_view name);

std::string_view to_string(PipelineStage stage);

std::vector<std::string> pipeline_stage_names();
 
} // namespace reusex::core