ProjectDB.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
// Point-cloud aliases (Cloud/CloudN/CloudL and pcl::PointCloud<pcl::PointXYZ>)
// are part of the public signatures below, so the point-type header stays.
// The heavier OpenCV and PCL mesh headers are only needed by the .cpp: they
// are forward-declared here (cv::Mat by value/reference, mesh types via
// std::shared_ptr) to keep DB clients from transitively compiling them.
#include "reusex/core/component_record.hpp"
#include "reusex/core/survey.hpp"
#include "reusex/types/point_types.hpp"
 
#include <array>
#include <cstdint>
#include <filesystem>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <utility>
#include <vector>
 
// Forward declarations for heavy third-party types used only by-value or via
// shared_ptr in the public API (definitions pulled in by ProjectDB.cpp).
namespace cv {
class Mat;
} // namespace cv
namespace pcl {
struct PolygonMesh;
struct TextureMesh;
} // namespace pcl
 
namespace reusex {
 
// Forward declarations
namespace core {
struct MaterialPassport;
struct MaterialPassportMetadata;
struct SensorIntrinsics;
} // namespace core
 
class ProjectDB {
    public:
  explicit ProjectDB(std::filesystem::path dbPath, bool readOnly = false);

  struct OpenOptions {
    bool read_only = false;
    bool hardened = false;
  };
  ProjectDB(std::filesystem::path dbPath, OpenOptions options);

  static void set_hardened_by_default(bool on) noexcept;
  static bool hardened_by_default() noexcept;

  struct IntegrityReport {
    enum class Kind {
      ok,
      unreadable,        
      corrupt,           
      executable_schema, 
    };
    Kind kind = Kind::ok;
    std::string detail; 
    bool ok() const noexcept { return kind == Kind::ok; }
  };

  static IntegrityReport check_integrity(const std::filesystem::path &file);
 
  bool is_read_only() const noexcept;
  ~ProjectDB();
 
  // Non-copyable (RAII resource management)
  ProjectDB(const ProjectDB &) = delete;
  ProjectDB &operator=(const ProjectDB &) = delete;
 
  // Movable
  ProjectDB(ProjectDB &&) noexcept;
  ProjectDB &operator=(ProjectDB &&) noexcept;
 
  // --- Core Database Operations ---
 
  bool is_open() const noexcept;
  const std::filesystem::path &path() const noexcept;
  int schema_version() const;
  static int latest_schema_version() noexcept;

  struct ProbeResult {
    bool is_project = false; 
    int schema_version = -1; 
    std::string error;       
  };

  static ProbeResult probe(const std::filesystem::path &path) noexcept;

  class Transaction {
      public:
    explicit Transaction(ProjectDB &db); 
    ~Transaction();
    void commit();
    Transaction(const Transaction &) = delete;
    Transaction &operator=(const Transaction &) = delete;
 
      private:
    ProjectDB *db_;
    bool open_ = true;
  };
  void validate_schema() const;
 
  // --- Sensor Frame Operations ---
 
  void save_sensor_frame(int nodeId, const cv::Mat &colorImage);
 
  void save_sensor_frame(int nodeId, const cv::Mat &color, const cv::Mat &depth,
                         const cv::Mat &confidence,
                         const std::array<double, 16> &worldPose,
                         const core::SensorIntrinsics &intrinsics,
                         double timestamp = -1.0, int scan_id = -1);

  void update_sensor_frame_pose(int nodeId,
                                const std::array<double, 16> &worldPose);
 
  std::vector<int> sensor_frame_ids() const;

  std::vector<std::pair<int, int>> sensor_frame_ids_with_scan() const;
  cv::Mat sensor_frame_image(int nodeId) const;
  cv::Mat sensor_frame_depth(int nodeId) const;
  cv::Mat sensor_frame_confidence(int nodeId) const;
  std::array<double, 16> sensor_frame_pose(int nodeId) const;

  bool has_sensor_frame_pose(int nodeId) const;
 
  core::SensorIntrinsics sensor_frame_intrinsics(int nodeId) const;
  bool has_sensor_frame(int nodeId) const;

  double sensor_frame_timestamp(int nodeId) const;

  int nearest_sensor_frame_by_timestamp(double timestamp) const;
 
  // --- Panoramic Image Operations ---
 
  struct PanoramicImage {
    int id;
    std::string filename;
    double timestamp; // -1.0 if unknown
    int node_id;      // -1 if unmatched
    // Refined 6-DoF pose from content-based alignment (`rux align 360`). When
    // has_pose is false the panorama has only its timestamp-matched frame pose.
    bool has_pose = false;
    std::array<double, 16> pose = {1, 0, 0, 0, 0, 1, 0, 0,
                                   0, 0, 1, 0, 0, 0, 0, 1}; // row-major world
    std::string pose_source = "timestamp"; // "timestamp" | "aligned"
    int align_inliers = -1;                // RANSAC inliers, -1 if not aligned
    // Angular RMS of the inlier bearings after resection, in degrees
    // (PanoramaAlignmentResult::rms_deg). -1 if not aligned.
    double align_rms = -1.0;
  };
 
  void save_panoramic_image(const std::string &filename,
                            const std::vector<uint8_t> &jpeg_data,
                            double timestamp = -1.0, int nodeId = -1);
 
  cv::Mat panoramic_image(int id) const;
  cv::Mat panoramic_image(std::string_view filename) const;
  bool has_panoramic_image(std::string_view filename) const;
  void delete_panoramic_image(int id);
  void delete_panoramic_image(std::string_view filename);
  std::vector<PanoramicImage> list_panoramic_images() const;
  int panoramic_image_count() const;

  void save_panorama_pose(int id, const std::array<double, 16> &pose,
                          int inliers, double rms);
 
  // --- Panorama Segmentation Operations ---
 
  bool has_panorama_segmentation(int panoId) const;
  cv::Mat panorama_segmentation(int panoId) const;
  void save_panorama_segmentation(int panoId, const cv::Mat &labels);
 
  // --- Segmentation Image Operations ---
 
  bool has_segmentation_image(int nodeId) const;
  cv::Mat segmentation_image(int nodeId) const;
  std::vector<int> segmentation_image_ids() const;
  void save_segmentation_image(int nodeId, const cv::Mat &labels);
  void save_segmentation_images(const std::vector<int> &nodeIds,
                                const std::vector<cv::Mat> &labels);
 
  // --- Glass Confidence Image Operations ---
  //
  // Per-frame binary depth-suppress map produced by `rux create annotate
  // --glass-filter`.  Stored as CV_8U PNG: 0 = suppress (glass/mirror), 255 =
  // trust depth.  Consumed by reconstruct_point_clouds when glass_filter is
  // enabled.
 
  bool has_glass_confidence_image(int nodeId) const;
  cv::Mat glass_confidence_image(int nodeId) const;
  std::vector<int> glass_confidence_image_ids() const;
  void save_glass_confidence_image(int nodeId, const cv::Mat &confidence);
 
  // --- Point Cloud Operations ---
 
  void save_point_cloud(std::string_view name, const Cloud &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name, const CloudN &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name, const CloudL &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name,
                        const pcl::PointCloud<pcl::PointXYZ> &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  CloudPtr point_cloud_xyzrgb(std::string_view name) const;
  CloudNPtr point_cloud_normal(std::string_view name) const;
  CloudLPtr point_cloud_label(std::string_view name) const;
  pcl::PointCloud<pcl::PointXYZ>::Ptr
  point_cloud_xyz(std::string_view name) const;
 
  bool has_point_cloud(std::string_view name) const;
  void delete_point_cloud(std::string_view name);
  std::vector<std::string> list_point_clouds() const;
  std::string point_cloud_type(std::string_view name) const;

  std::string point_cloud_storage_order(std::string_view name) const;

  std::pair<std::string, std::string>
  point_cloud_provenance(std::string_view name) const;

  void save_tile_index(std::string_view name, const std::vector<uint8_t> &blob);

  std::vector<uint8_t> tile_index(std::string_view name) const;

  struct CloudPage {
    std::string point_type;
    uint32_t point_step = 0; 
    uint64_t offset = 0;     
    uint64_t count = 0;      
    uint64_t total = 0;      
    std::vector<uint8_t> data;
  };

  CloudPage point_cloud_page(std::string_view name, uint64_t offset,
                             uint64_t limit) const;
 
  // --- Label Definitions ---
 
  void save_label_definitions(std::string_view cloudName,
                              const std::map<int, std::string> &labelMap);
 
  std::map<int, std::string>
  label_definitions(std::string_view cloudName) const;
 
  // --- Instances (stable identity) ---

  struct InstanceRecord {
    uint32_t instance_id = 0; 
    std::string guid;         
    int semantic_class = -1;  
    int point_count = 0;      
  };

  void save_instances(const std::string &cloud_name,
                      const std::vector<InstanceRecord> &records);

  std::vector<InstanceRecord> instances(const std::string &cloud_name) const;

  void add_instance(const std::string &cloud_name,
                    const InstanceRecord &record);

  void set_instance_point_count(const std::string &cloud_name,
                                uint32_t instance_id, int point_count);

  std::string instance_guid(const std::string &cloud_name,
                            uint32_t instance_id) const;
 
  // --- Instance ↔ Material Links ---

  void set_instance_material(std::string_view cloudName, int instanceId,
                             std::string_view materialGuid);

  std::optional<std::string> instance_material_guid(std::string_view cloudName,
                                                    int instanceId) const;

  std::map<int, std::string>
  instance_materials(std::string_view cloudName) const;
 
  // --- Material Annotations (VLM-derived) ---

  struct MaterialAnnotation {
    std::string description; 
    std::vector<std::pair<std::string, std::string>>
        attributes; 
    std::string provider_model; 
    std::string raw_json;       
  };

  void save_material_annotation(std::string_view materialGuid,
                                const MaterialAnnotation &annotation);

  std::optional<MaterialAnnotation>
  material_annotation(std::string_view materialGuid) const;
 
  // --- Mesh Operations ---
 
  void save_mesh(std::string_view name, const pcl::PolygonMesh &mesh,
                 std::string_view stage = "", std::string_view paramsJson = "");
 
  void save_mesh(std::string_view name, const pcl::TextureMesh &mesh,
                 std::string_view stage = "", std::string_view paramsJson = "");
 
  std::shared_ptr<pcl::PolygonMesh> mesh(std::string_view name) const;
  std::shared_ptr<pcl::TextureMesh> texture_mesh(std::string_view name) const;
  bool has_mesh(std::string_view name) const;
  std::vector<std::string> list_meshes() const;
  std::string mesh_format(std::string_view name) const;
 
  struct MeshMetadata {
    std::string name, format, stage, parameters, created_at;
    int vertex_count = 0, face_count = 0;
  };
  MeshMetadata mesh_metadata(std::string_view name) const;
 
  std::vector<uint8_t> mesh_data_blob(std::string_view name) const;
 
  struct MeshTextureInfo {
    std::string tex_name, format;
    std::vector<uint8_t> image_data;
    int width, height;
  };
  std::vector<MeshTextureInfo> mesh_texture_blobs(std::string_view name) const;
 
  struct MeshTextureMetadata {
    std::string tex_name, format;
    int width, height;
  };
  std::vector<MeshTextureMetadata>
  mesh_texture_metadata(std::string_view name) const;
 
  // --- Gaussian Splat Operations ---
  //
  // A trained splat is stored verbatim, as the INRIA `.ply` bytes, chunked
  // across `gaussian_splat_data` rows the same way point clouds are: a splat
  // is routinely hundreds of MB and SQLite materializes a whole blob column
  // on read, so a single-row layout would cost peak memory proportional to
  // the entire file even to answer "how many Gaussians".
  //
  // The bytes are opaque to core — nothing here inflates a splat into a
  // geometry type. What core *does* own is the guarantee that the bytes are a
  // splat at all: `save_gaussian_splat()` parses the PLY header
  // (core/gaussian_splat.hpp) and refuses anything else, so the point-cloud
  // PLY that `rux export ply` writes is rejected at the door instead of
  // reaching a renderer that would draw nothing and say nothing.

  struct GaussianSplatMetadata {
    std::string name;
    std::string format; 
    std::uint64_t gaussian_count = 0;
    int sh_degree = 0;           
    std::uint64_t byte_size = 0; 
    std::string created_at;
    std::string stage;      
    std::string parameters; 
  };

  void save_gaussian_splat(std::string_view name,
                           const std::vector<uint8_t> &ply,
                           std::string_view stage = "",
                           std::string_view parameters = "");

  bool has_gaussian_splat(std::string_view name) const;

  std::vector<std::string> list_gaussian_splats() const;

  GaussianSplatMetadata gaussian_splat_metadata(std::string_view name) const;

  std::vector<uint8_t> gaussian_splat_blob(std::string_view name) const;

  bool delete_gaussian_splat(std::string_view name);
 
  // --- Pose Graph ---
  //
  // Written by `rux optimize` after convergence; replaced atomically on each
  // run.  The table always reflects the most-recent optimize invocation.
  // A project that has never been optimized has an empty table.
  //
  // Node positions are read from `sensor_frames` (their current world poses),
  // so there is no separate nodes table.

  struct PoseGraphEdge {
    int from_node_id = 0;
    int to_node_id = 0;
    std::string edge_type;
    double residual = 0.0;
    double weight = 1.0;
  };

  void save_pose_graph_edges(const std::vector<PoseGraphEdge> &edges);

  std::vector<PoseGraphEdge> list_pose_graph_edges() const;

  bool has_pose_graph() const;

  int add_pose_graph_edge(const PoseGraphEdge &edge);

  int delete_pose_graph_edges(int from_node_id, int to_node_id,
                              std::string_view edge_type = "");
 
  // --- Scans (multi-session import, #129) ---

  struct ScanRecord {
    int id = 0;
    std::string source_path;
    std::string imported_at;
    int id_offset = 0;
    std::string provenance_json;
  };

  ScanRecord create_scan(const std::string &source_path,
                         const std::string &provenance_json = "{}");

  std::vector<ScanRecord> scans() const;
 
  // --- Building Component Operations ---
  //
  // Persistence speaks only core::ComponentRecord (see
  // reusex/core/component_record.hpp), so core stays free of geometry types
  // (#227). To store/load a geometry::BuildingComponent, use the mapping and
  // convenience free functions in reusex/geometry/component_persistence.hpp.

  void save_component_record(const core::ComponentRecord &record);
  void update_component_record_by_guid(const core::ComponentRecord &record);
  core::ComponentRecord component_record(std::string_view name) const;
  bool has_building_component(std::string_view name) const;
  void delete_building_component(std::string_view name);
  std::vector<std::string> list_building_components() const;
  std::vector<std::string>
  list_building_components(std::string_view type) const;
  int building_component_count() const;
 
  // --- Pipeline Log ---
 
  int log_pipeline_start(std::string_view stage,
                         std::string_view paramsJson = "");

  enum class PipelineOutcome { success, failed, cancelled };
 
  void log_pipeline_end(int logId, PipelineOutcome outcome,
                        std::string_view errorMsg = "");

  void log_pipeline_end(int logId, bool success,
                        std::string_view errorMsg = "");
 
  struct PipelineLogEntry {
    int id;
    std::string stage;
    std::string started_at;
    std::string finished_at; // Empty if still running
    std::string parameters;  // JSON string
    std::string status;      // "running", "success", "failed", "cancelled"
    std::string error_msg;   // Empty if no error
  };
 
  std::vector<PipelineLogEntry> pipeline_log(int limit = 0) const;
 
  // --- Raw table browsing (read-only) ---
  //
  // A generic, read-only window onto every table of the file, for a database
  // viewer (the Qt client's table view, `rux get`-style tooling). Typed
  // accessors above remain the way to *use* the data; these exist to *show*
  // what the file contains, including tables no accessor covers.
  //
  // Blob cells never carry their bytes: only their size and the first few
  // bytes (enough to sniff PNG / JPEG / PLY), read by incremental blob I/O,
  // which touches one page — so paging through `sensor_frames` costs
  // kilobytes, not the images. (A table WITHOUT ROWID has no blob I/O; its
  // blob heads come from substr(), which does read the whole value.) Long text
  // is truncated to `text_limit` bytes with its full size reported.

  struct TableInfo {
    std::string name;
    std::int64_t row_count = 0;
  };

  struct TableColumn {
    std::string name;
    std::string declared_type; 
    bool primary_key = false;
    bool not_null = false;
  };

  struct TableCell {
    enum class Kind { null, integer, real, text, blob };
    Kind kind = Kind::null;
    std::int64_t integer = 0;
    double real = 0.0;
    std::string text;       
    std::uint64_t size = 0; 
    bool truncated = false; 
  };

  std::vector<TableInfo> list_tables() const;

  std::int64_t table_row_count(std::string_view table) const;

  std::vector<TableColumn> table_columns(std::string_view table) const;

  std::vector<std::vector<TableCell>>
  table_rows(std::string_view table, std::int64_t offset, std::int64_t limit,
             std::size_t text_limit = 256) const;
 
  // --- Project Summary ---
 
  struct ProjectSummary {
    struct CloudInfo {
      std::string name;
      std::string type; // "PointXYZRGB", "Normal", "Label", "PointXYZ"
      size_t point_count;
      size_t width;
      size_t height;
      bool organized;                    // height > 1
      std::map<int, std::string> labels; // Only for Label clouds

      std::string storage_order;
    };
 
    struct MeshInfo {
      std::string name;
      int vertex_count;
      int face_count;
    };
 
    struct SensorFrameInfo {
      struct ScanInfo {
        int scan_id = 0;
        std::string source_path;
        std::string imported_at;
        int frame_count = 0;
      };
 
      int total_count;
      int width;                   // 0 if no frames
      int height;                  // 0 if no frames
      int segmented_count;         // frames with segmentation
      std::vector<ScanInfo> scans; // per-scan breakdown; empty if scans table
                                   // absent
    };
 
    struct PanoramicInfo {
      int total_count = 0;
      int matched_count = 0; // images linked to a sensor frame
    };
 
    struct ComponentInfo {
      int total_count = 0;
      std::map<std::string, int> count_by_type;
    };
 
    struct MaterialInfo {
      std::string id;
      std::string guid;
      int property_count = 0;
      std::string created_at;     // ISO 8601 timestamp
      std::string version_number; // Semver (e.g., "0.1.1")
    };
 
    struct ProjectInfo {
      std::string id;
      std::string name;
      std::string building_address;
      int year_of_construction = 0; // 0 = not set
      std::string survey_date;
      std::string survey_organisation;
      std::string notes;
    };
 
    std::filesystem::path path;
    int schema_version;
    std::vector<ProjectInfo> projects;
    std::vector<CloudInfo> clouds;
    std::vector<MeshInfo> meshes;
    std::vector<GaussianSplatMetadata> gaussian_splats;
    SensorFrameInfo sensor_frames;
    PanoramicInfo panoramic_images;
    ComponentInfo components;
    std::vector<MaterialInfo> materials;
  };
 
  ProjectSummary project_summary() const;

  struct PropertyDefinition {
    std::string id;
    std::string type; // "text" | "number" | "date" | "boolean" | "select" |
                      // "multiselect"
    std::string name;
    std::vector<std::string> options; // populated for "select"/"multiselect"
    int sort_order = 0;
    int width = 200; // display column width in pixels (schema v19)
  };
 
  // --- Material Property Definition Operations (schema v18) ---

  [[nodiscard]] std::vector<PropertyDefinition>
  list_property_definitions() const;

  std::string add_property_definition(const std::string &name,
                                      const std::string &type,
                                      const std::vector<std::string> &options,
                                      int sort_order, int width = 200);

  void update_property_definition(const std::string &id,
                                  const std::string &name,
                                  const std::string &type,
                                  const std::vector<std::string> &options,
                                  int sort_order, int width);

  void delete_property_definition(const std::string &id);

  [[nodiscard]] std::optional<std::pair<std::vector<std::uint8_t>, std::string>>
  material_thumbnail(const std::string &guid) const;

  void set_material_thumbnail(const std::string &guid,
                              const std::vector<std::uint8_t> &blob,
                              const std::string &mime_type);

  void delete_material_thumbnail(const std::string &guid);
 
  // --- Material Passport Operations ---
 
  core::MaterialPassport material_passport(std::string_view documentGuid) const;
  std::vector<core::MaterialPassport> all_material_passports() const;
 
  void add_material_passport(const core::MaterialPassport &passport,
                             std::string_view projectId);

  void add_material_passport(const core::MaterialPassport &passport,
                             std::string_view projectId, std::string_view id);

  void delete_material_passport(std::string_view documentGuid);

  std::vector<std::string> list_passport_guids() const;

  std::map<std::string, std::string>
  passport_stored_properties(std::string_view documentGuid) const;

  std::string passport_property_value(std::string_view documentGuid,
                                      std::string_view fieldName) const;

  std::optional<int>
  passport_linked_node_id(std::string_view documentGuid) const;

  core::MaterialPassportMetadata
  passport_metadata(std::string_view documentGuid) const;

  void set_passport_metadata_field(std::string_view documentGuid,
                                   std::string_view column,
                                   std::string_view value);

  void set_passport_property(std::string_view documentGuid,
                             std::string_view fieldName,
                             std::string_view value);

  void delete_passport_property(std::string_view documentGuid,
                                std::string_view fieldName);
 
  // --- Report PDF Storage (schema v20) ---

  struct ReportPdfRecord {
    int64_t id = 0;
    std::string created_at;
    std::string label; // human-readable tag (e.g. "Ressourcekortlægning")
    std::size_t size_bytes = 0;
    int version = 0;
    std::optional<int> blocking_types;
  };

  ReportPdfRecord
  add_report_pdf(const std::vector<std::uint8_t> &pdf,
                 const std::string &label = "",
                 std::optional<int> blocking_types = std::nullopt);

  [[nodiscard]] std::vector<ReportPdfRecord> list_report_pdfs() const;

  [[nodiscard]] std::optional<std::vector<std::uint8_t>>
  report_pdf(int64_t id) const;
 
  // --- Resource templates (schema v25) ---
  struct ResourceTemplateRecord {
    int64_t id = 0;
    std::string name;
    std::string members_json = "[]";
    std::string csv_json = "{}";
    std::optional<std::string> seed; // "materialepas" | "screening"
    std::string created_at;          // ISO 8601 UTC
    std::string updated_at;
  };
  struct ResourceTemplatePatch {
    std::optional<std::string> name, members_json, csv_json;
  };

  [[nodiscard]] std::vector<ResourceTemplateRecord> resource_templates() const;
  [[nodiscard]] std::optional<ResourceTemplateRecord>
  resource_template(int64_t id) const;
  ResourceTemplateRecord
  add_resource_template(const ResourceTemplateRecord &rec);
  ResourceTemplateRecord
  update_resource_template(int64_t id, const ResourceTemplatePatch &patch);
  bool delete_resource_template(int64_t id); // false when absent
 
  // --- Survey (Ressourcekortlægning, schema v22) ---
  struct SurveyTypeRecord {
    int64_t id = 0;
    std::string name;
    std::string eak_code;
    std::string bim7aa_code;
    std::string unit = "stk";
    core::Treatment treatment = core::Treatment::genanvendelse;
    core::ReviewStatus review_status = core::ReviewStatus::queue;
    std::optional<double> confidence; // 0..1, AI detection confidence
    std::optional<double> mass_t;     // tonnes
    std::string note;
    bool starred = false;
    int semantic_class = -1; // the class sync_survey seeded it from
    std::string created_at;  // ISO 8601 UTC
    std::string updated_at;
  };

  struct SurveyTypePatch {
    std::optional<std::string> name, eak_code, bim7aa_code, unit, note;
    std::optional<core::Treatment> treatment;
    // Unchecked storage write — set approval through core::set_review_status,
    // which enforces the sample gate.
    std::optional<core::ReviewStatus> review_status;
    std::optional<std::optional<double>> confidence, mass_t;
    std::optional<bool> starred;
  };
  struct SurveyPartRecord {
    std::string code; // "RX-001"
    int64_t type_id = 0;
    std::optional<std::string>
        cloud_name; // read-only, derived from instance_guid
    std::optional<std::uint32_t>
        instance_id; // read-only, derived from instance_guid
    std::optional<std::uint32_t> room_id;
    std::string room_name;
    double quantity = 1.0;
    bool starred = false;
    std::string note;
    std::optional<std::string>
        material_guid; // read-only: the part's passport (survey_parts.
                       // passport_guid, schema v25), else its instance's
                       // instance_materials link — unless another part
                       // owns that passport, then empty
    std::optional<std::string> instance_guid{};
  };
  struct SurveyPartPatch {
    std::optional<int64_t> type_id;
    std::optional<double> quantity;
    std::optional<bool> starred;
    std::optional<std::string> note, room_name;
  };
 
  SurveyTypeRecord
  add_survey_type(const SurveyTypeRecord &rec); // id/timestamps ignored
  [[nodiscard]] std::vector<SurveyTypeRecord> survey_types() const; // by id
  [[nodiscard]] std::optional<SurveyTypeRecord> survey_type(int64_t id) const;
  SurveyTypeRecord update_survey_type(int64_t id, const SurveyTypePatch &patch);
  void add_survey_part(const SurveyPartRecord &rec);
  [[nodiscard]] std::vector<SurveyPartRecord> survey_parts() const; // by code
  [[nodiscard]] std::optional<SurveyPartRecord>
  survey_part(std::string_view code) const;
  SurveyPartRecord update_survey_part(std::string_view code,
                                      const SurveyPartPatch &patch);
  void set_survey_part_quantities(
      const std::vector<std::pair<std::string, double>> &code_quantities);
  [[nodiscard]] bool has_survey_part_for(std::string_view cloud_name,
                                         std::uint32_t instance_id) const;
  [[nodiscard]] int max_survey_part_number() const; // 0 when there are none

  std::string ensure_resource_passport(std::string_view code);
  void delete_survey_part(std::string_view code);
  void delete_survey_type(int64_t id);

  void dismiss_instance(std::string_view instance_guid);
  [[nodiscard]] bool
  is_instance_dismissed(std::string_view instance_guid) const;
  [[nodiscard]] std::vector<std::string> dismissed_instances() const;
  bool unlink_instance_material(std::string_view cloud_name, int instance_id);
  void rename_passport_field(std::string_view old_name,
                             std::string_view new_name);
  [[nodiscard]] bool has_passport_field_values(std::string_view name) const;
  std::size_t delete_passport_field_values(std::string_view name);
  [[nodiscard]] bool is_passport_linked(std::string_view guid) const;
 
  struct SampleRecord {
    int64_t id = 0;
    std::string code;  // "P-01"
    std::string title; // "PCB i fugemasse"
    std::string what;  // what was sampled, where
    core::SampleStage stage = core::SampleStage::planlagt;
    core::SampleResult result = core::SampleResult::none;
    std::vector<int64_t> type_ids; // linked survey types, ascending
    std::string created_at;
    std::string updated_at;
  };
  struct SamplePatch {
    std::optional<std::string> title, what;
    std::optional<core::SampleStage> stage;
    std::optional<core::SampleResult> result;
  };

  SampleRecord
  add_sample(std::string_view title, std::string_view what,
             const std::vector<int64_t> &type_ids = {},
             core::SampleStage stage = core::SampleStage::planlagt);
  [[nodiscard]] std::vector<SampleRecord> samples() const; // by id
  [[nodiscard]] std::optional<SampleRecord> sample(int64_t id) const;
  SampleRecord
  update_sample(int64_t id,
                const SamplePatch &patch); // storage only; no stage rules
  bool delete_sample(int64_t id);          // false when absent
  void
  set_sample_links(int64_t id,
                   const std::vector<int64_t> &type_ids); // replaces the set
  [[nodiscard]] std::vector<SampleRecord>
  samples_for_type(int64_t type_id) const;
 
  // --- Project Metadata Operations ---
 
  struct ProjectMetadata {
    std::string id;
    std::string name;
    std::string building_address;
    int year_of_construction = 0; // 0 = not set
    std::string survey_date;
    std::string survey_organisation;
    std::string notes;
  };

  ProjectMetadata get_project_metadata(std::string_view projectId) const;

  void update_project_metadata(const ProjectMetadata &metadata);

  std::vector<std::string> list_project_ids() const;
 
    private:
  class Impl;
  std::unique_ptr<Impl> impl_;
};
} // namespace reusex