[M2] add SQLite overlay + add_manual

src/linkdb/linkdb.cppm

@@ -1,3 +1,7 @@
+module;
+
+#include <sqlite3.h>
+
 export module cargoxx.linkdb;
 
 import std;
@@ -26,13 +30,60 @@ struct CuratedRecipe {
     bool components_supported = false;
 };
 
+struct OverlayRow {
+    std::string version_range;
+    std::string nixpkgs_attr;
+    std::string find_package;
+    std::vector<std::string> targets;
+    std::string source;
+    std::int64_t verified_at = 0;
+};
+
+// RAII wrapper for an open sqlite3 connection used by the overlay database.
+// Move-only would be redundant — the holder (Database::overlay_) is a
+// std::unique_ptr<OverlayState>, so we delete copy and move outright.
+class OverlayState {
+  public:
+    OverlayState() = default;
+    explicit OverlayState(sqlite3* handle) noexcept : db_(handle) {}
+    ~OverlayState() {
+        if (db_) {
+            sqlite3_close(db_);
+        }
+    }
+
+    OverlayState(const OverlayState&) = delete;
+    OverlayState& operator=(const OverlayState&) = delete;
+    OverlayState(OverlayState&&) = delete;
+    OverlayState& operator=(OverlayState&&) = delete;
+
+    [[nodiscard]] auto handle() const noexcept -> sqlite3* { return db_; }
+
+  private:
+    sqlite3* db_ = nullptr;
+};
+
+auto overlay_open(const std::filesystem::path& path)
+    -> cargoxx::util::Result<std::unique_ptr<OverlayState>>;
+
+auto overlay_insert_manual(OverlayState& state, const std::string& package,
+                           const std::string& version_range,
+                           const cargoxx::linkdb::Recipe& r)
+    -> cargoxx::util::Result<void>;
+
+auto overlay_query(OverlayState& state, const std::string& package)
+    -> cargoxx::util::Result<std::vector<OverlayRow>>;
+
+auto overlay_is_fresh(const OverlayRow& row, std::int64_t now_epoch_seconds) -> bool;
+
 } // namespace cargoxx::linkdb::detail
 
 export namespace cargoxx::linkdb {
 
 class Database {
   public:
-    static auto open() -> util::Result<Database>;
+    static auto open(std::optional<std::filesystem::path> overlay_path = std::nullopt)
+        -> util::Result<Database>;
 
     auto resolve(const std::string& package, const std::string& version,
                  const std::vector<std::string>& components = {})
@@ -44,6 +95,7 @@ class Database {
   private:
     Database() = default;
     std::map<std::string, std::vector<detail::CuratedRecipe>> curated_;
+    std::unique_ptr<detail::OverlayState> overlay_;
 };
 
 // Pure helpers exported for unit testing.