Module records and aliases

Installation records what a module reports about itself. dpm_install_module
opens a module once, writes its version and description to a .meta file in
/var/lib/dpm/metadata/, and records the alternate names it declared in
modules.aliases beside it. dpm_uninstall_module removes both, leaving the
module file in place.

dpm_list_modules reads those records and opens no module. A module with no
record lists with a version of <uninstalled> and still loads when a caller
names it. An unreadable or absent metadata directory costs the listing its
detail and costs nothing else.

Aliases give a module alternate names, declared through the new
dpm_module_aliases contract symbol or added with dpm_add_module_alias. A
name is recorded once: one already serving as an alias, or belonging to an
installed module, is refused rather than repointed. dpm_require matches a
name against the installed modules, then the alias table, then the module
path.

The metadata directory is a fifth override field and the -M flag, and
[modules] metadata in core.conf.

The test suite is four binaries covering context, modules, records, and
aliases, each a ctest case of its own, alongside the CLI cases.

include/internal/metadata.hpp

@@ -0,0 +1,128 @@
+/**
+ * @file metadata.hpp
+ * @brief Module records: what libdpm-core.so knows without loading a module
+ *
+ * @copyright Copyright (c) 2026 SILO GROUP LLC
+ * @author Chris Punches <chris.punches@silogroup.org>
+ *
+ * Part of the Dark Horse Linux Package Manager (DPM)
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as
+ * published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include <map>
+#include <string>
+
+struct dpm_ctx;
+
+/**
+ * @brief The records one module's .meta file carries
+ *
+ * Written when a module is installed, from what the module itself
+ * reported at that moment. A listing reports these values, so a listing
+ * needs to open no module.
+ */
+struct dpm_module_meta_records {
+    /** Basename of the module file these records describe. */
+    std::string module_file;
+
+    /** Version the module reported when it was installed. */
+    std::string version;
+
+    /** Description the module reported when it was installed. */
+    std::string description;
+};
+
+namespace dpm_core {
+    /**
+     * @brief Reads a flat key/value file from the metadata directory
+     *
+     * The format every file in that directory uses: one `key = value`
+     * per line, '#' and ';' opening a comment, and every key and value
+     * trimmed. A line carrying no '=' is skipped, so a malformed line
+     * costs that line and no more.
+     *
+     * @param path The file to read
+     * @param out Receives the pairs the file carried
+     * @return true when the file was opened; false when it was not
+     */
+    bool md_read_key_value_file(const std::string& path,
+                                std::map<std::string, std::string>& out);
+
+    /**
+     * @brief Writes a flat key/value file into the metadata directory
+     *
+     * Creates the directory when it is absent, and replaces the file's
+     * whole contents.
+     *
+     * @param path The file to write
+     * @param values The pairs to write, one per line
+     * @param reason Receives the failure reason when the write fails
+     * @return true on success
+     */
+    bool md_write_key_value_file(
+        const std::string& path,
+        const std::map<std::string, std::string>& values,
+        std::string& reason);
+
+    /**
+     * @brief Reads every module record in a context's metadata directory
+     *
+     * Each .meta file becomes one set of records named after the file
+     * without its extension. A missing or unreadable directory leaves
+     * the context holding no records, which costs a listing its detail
+     * and costs nothing else.
+     *
+     * @param ctx The libdpm-core.so context
+     */
+    void md_load_records_dir(dpm_ctx* ctx);
+
+    /**
+     * @brief Finds the records for a module name
+     *
+     * @param ctx The libdpm-core.so context
+     * @param module_name The module name to look up
+     * @return The records, or nullptr when no module of that name is recorded
+     */
+    const dpm_module_meta_records* md_find_module_record(
+        dpm_ctx* ctx, const std::string& module_name);
+
+    /**
+     * @brief Writes one module's records into the metadata directory
+     *
+     * Replaces the records of the same module name, and updates the
+     * context's own copy so the change is visible without reopening.
+     *
+     * @param ctx The libdpm-core.so context
+     * @param module_name The module name the records belong to
+     * @param records The records to write
+     * @param reason Receives the failure reason when the write fails
+     * @return true on success
+     */
+    bool md_write_module_record(dpm_ctx* ctx, const std::string& module_name,
+                                const dpm_module_meta_records& records,
+                                std::string& reason);
+
+    /**
+     * @brief Removes one module's records from the metadata directory
+     *
+     * @param ctx The libdpm-core.so context
+     * @param module_name The module name whose records are removed
+     * @param reason Receives the failure reason when the removal fails
+     * @return true on success
+     */
+    bool md_remove_module_record(dpm_ctx* ctx, const std::string& module_name,
+                                 std::string& reason);
+} // namespace dpm_core