arachne::penelope::store Class Reference

#include <include/penelope/store.hpp>

Public Member Functions
	store (std::filesystem::path root)
snapshot_result	replace_candidate_snapshot (const candidate_snapshot_request &request)
std::optional< snapshot_result >	active_snapshot (graph_domain domain) const
integrity_report	integrity_check (graph_domain domain, const std::filesystem::path &database_path) const
void	checkpoint_staging (graph_domain domain, const std::filesystem::path &database_path) const
std::string	export_jsonl (graph_domain domain, const std::filesystem::path &database_path, const std::filesystem::path &destination) const
const std::filesystem::path &	root () const noexcept

Private Attributes
std::filesystem::path	root_

Detailed Description

Penelope's isolated SQLite persistence boundary.

Candidate builds always start from an empty database and therefore cannot carry grey/group/greedy state from an older build. Product data is maintained directly by the dedicated inbox importer; it is deliberately outside this immutable candidate-snapshot store.

Canonical SQLite files contain research data only. Run IDs, payload paths, and artifact hashes are written exclusively to metadata.json beside the database.

Definition at line 71 of file store.hpp.

Constructor & Destructor Documentation

store()

arachne::penelope::store::store ( std::filesystem::path root )

explicit

Definition at line 1283 of file store.cpp.

                        {
    if (root.empty()) {
        fail("Penelope store root must not be empty");
    }
    root_ = fs::absolute(std::move(root)).lexically_normal();
    if (root_ == root_.root_path()) {
        fail("Penelope store root must not be a filesystem root");
    }
    for (const auto& component : root_) {
        if (component == "inbox") {
            fail(
                "Penelope store root must never be inside the immutable inbox"
            );
        }
    }
    fs::create_directories(
        domain_path(root_, graph_domain::candidate) / "snapshots"
    );
    fs::create_directories(
        domain_path(root_, graph_domain::candidate) / ".staging"
    );
}

Member Function Documentation

active_snapshot()

std::optional< snapshot_result > arachne::penelope::store::active_snapshot ( graph_domain domain ) const

nodiscard

Return the currently active immutable snapshot, if one exists.

Definition at line 1307 of file store.cpp.

                                                      {
    const std::string id = read_active_id(root_, domain);
    if (id.empty()) {
        return std::nullopt;
    }
    return snapshot_from_directory(root_, domain, id, true);
}

checkpoint_staging()

void arachne::penelope::store::checkpoint_staging	(	graph_domain	domain,
		const std::filesystem::path &	database_path ) const

Checkpoint a staging database and require a clean integrity report. This must not be used to modify a database referenced by ACTIVE.

Definition at line 1323 of file store.cpp.

        {
    if (const auto active = active_snapshot(domain)) {
        std::error_code error;
        if (fs::equivalent(active->database_path, database_path, error)
            && !error) {
            fail("refusing to checkpoint an active immutable snapshot");
        }
    }
    seal_and_validate_database(domain, database_path);
    remove_staging_sqlite_sidecars(database_path, database_path.parent_path());
}

References arachne::penelope::anonymous_namespace{store.cpp}::remove_staging_sqlite_sidecars(), and arachne::penelope::anonymous_namespace{store.cpp}::seal_and_validate_database().

Referenced by replace_candidate_snapshot().

Here is the call graph for this function:

Here is the caller graph for this function:

export_jsonl()

std::string arachne::penelope::store::export_jsonl ( graph_domain domain, const std::filesystem::path & database_path, const std::filesystem::path & destination ) const

nodiscard

Write the stable, table-ordered JSONL representation of a snapshot.

Definition at line 1337 of file store.cpp.

        {
    database db(
        database_path, SQLITE_OPEN_READONLY, database_access::immutable_readonly
    );
    db.exec("PRAGMA foreign_keys = ON");
    if (!destination.parent_path().empty()) {
        fs::create_directories(destination.parent_path());
    }
    std::ofstream output(destination, std::ios::binary | std::ios::trunc);
    if (!output) {
        fail("cannot create deterministic export: " + destination.string());
    }
    for (const auto& table : export_tables(domain)) {
        statement rows(
            db.get(),
            "SELECT * FROM " + std::string(table.name) + " ORDER BY "
                + std::string(table.order)
        );
        while (rows.row()) {
            json values = json::object();
            const int columns = sqlite3_column_count(rows.get());
            for (int column = 0; column < columns; ++column) {
                values[sqlite3_column_name(rows.get(), column)]
                    = sqlite_value(rows.get(), column);
            }
            json line { { "table", table.name }, { "row", std::move(values) } };
            output << canonical_json(line) << '\n';
            if (!output) {
                fail("failed while writing deterministic export");
            }
        }
    }
    output.flush();
    if (!output) {
        fail("failed while flushing deterministic export");
    }
    output.close();
    return crypto::sha256_file(destination);
}

References arachne::penelope::anonymous_namespace{store.cpp}::database::database(), arachne::penelope::anonymous_namespace{store.cpp}::immutable_readonly, and arachne::crypto::sha256_file().

Referenced by replace_candidate_snapshot().

Here is the call graph for this function:

Here is the caller graph for this function:

integrity_check()

integrity_report arachne::penelope::store::integrity_check ( graph_domain domain, const std::filesystem::path & database_path ) const

nodiscard

Run SQLite integrity, FK, and domain-specific structural checks.

Definition at line 1315 of file store.cpp.

        {
    return inspect_database(
        domain, database_path, database_access::immutable_readonly
    );
}

References arachne::penelope::anonymous_namespace{store.cpp}::immutable_readonly, and arachne::penelope::anonymous_namespace{store.cpp}::inspect_database().

Here is the call graph for this function:

replace_candidate_snapshot()

snapshot_result arachne::penelope::store::replace_candidate_snapshot ( const candidate_snapshot_request & request )

nodiscard

Definition at line 1523 of file store.cpp.

                                                                           {
    if (request.run_id.empty()) {
        fail("candidate snapshot request requires a run_id");
    }
    const auto& descriptor = request.plan;
    if (!fs::is_regular_file(descriptor.control_contract_path)
        || !fs::is_regular_file(descriptor.resolved_plan_payload_path)) {
        fail("candidate control contract and resolved payload must both exist");
    }
    const json control = read_json(descriptor.control_contract_path);
    require_valid_contract(
        arachnespace::contracts::contract_name::research_candidate_graph_plan,
        control, "candidate plan"
    );
    const auto& plan_artifact = control.at("plan_artifact");
    const std::string payload_hash = lowercase(
        require_string(plan_artifact, "sha256", "control.plan_artifact")
    );
    require_sha256(payload_hash, "control.plan_artifact.sha256");
    if (crypto::sha256_file(descriptor.resolved_plan_payload_path)
        != payload_hash) {
        fail(
            "resolved candidate plan payload hash does not match control "
            "contract"
        );
    }
    const auto expected_bytes
        = plan_artifact.at("byte_length").get<std::uint64_t>();
    if (fs::file_size(descriptor.resolved_plan_payload_path)
        != expected_bytes) {
        fail(
            "resolved candidate plan payload length does not match control "
            "contract"
        );
    }
    const json payload
        = read_candidate_payload(descriptor.resolved_plan_payload_path);
    const std::string seed = request.run_id + "\n"
        + require_string(control, "plan_id", "candidate control") + "\n"
        + payload_hash;
    staging_guard staging {
        .path = make_staging_directory(root_, graph_domain::candidate, seed)
    };
    const fs::path database_path = staging.path / "graph.sqlite";
    {
        database db(database_path, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE);
        configure_connection(db);
        create_candidate_schema(db);
        transaction build(db);
        import_candidate_plan(db.get(), control, payload);
        build.commit();
    }
    checkpoint_staging(graph_domain::candidate, database_path);
    const fs::path export_path = staging.path / "graph.jsonl";
    const std::string export_hash
        = export_jsonl(graph_domain::candidate, database_path, export_path);
    const std::string database_hash = crypto::sha256_file(database_path);
    remove_staging_sqlite_sidecars(database_path, staging.path);
    const std::string snapshot_id = "candidate_" + export_hash.substr(0, 32);
    const json validation_artifact = write_validation_report(
        staging.path, graph_domain::candidate, snapshot_id
    );
    const std::string database_ref
        = "candidate/snapshots/" + snapshot_id + "/graph.sqlite";
    const std::string export_ref
        = "candidate/snapshots/" + snapshot_id + "/graph.jsonl";
    const json metadata {
        { "contract", candidate_contract },
        { "format_version", 1 },
        { "snapshot_id", snapshot_id },
        { "run_id", request.run_id },
        { "graph_version", "candidate-schema-v1" },
        { "content_sha256", database_hash },
        { "database",
          artifact(
              database_ref, database_hash, fs::file_size(database_path),
              "application/vnd.sqlite3"
          ) },
        { "exports",
          json::array(
              { { { "kind", "candidate-jsonl" },
                  { "artifact",
                    artifact(
                        export_ref, export_hash, fs::file_size(export_path),
                        "application/x-ndjson"
                    ) } } }
          ) },
        { "plan_id", control.at("plan_id") },
        { "source_snapshot_id",
          control.at("source_snapshot").at("snapshot_id") },
        { "activated_at", utc_now() },
        { "structural_validation",
          { { "passed", true }, { "report", validation_artifact } } },
        { "extensions",
          { { "org.ninjaro.penelope",
              { { "control_contract_ref",
                  descriptor.control_contract_path.generic_string() },
                { "control_contract_sha256",
                  crypto::sha256_file(descriptor.control_contract_path) },
                { "plan_artifact", plan_artifact } } } } },
    };
    require_valid_contract(
        arachnespace::contracts::contract_name::
            research_candidate_graph_snapshot,
        metadata, "candidate snapshot metadata"
    );
    write_bytes(
        staging.path / "metadata.json", canonical_json(metadata) + "\n"
    );
    return finalize_snapshot(
        root_, graph_domain::candidate, staging, snapshot_id, database_hash,
        export_hash, 1, 0
    );
}

References arachne::penelope::candidate, checkpoint_staging(), arachne::penelope::anonymous_namespace{store.cpp}::transaction::commit(), arachne::penelope::anonymous_namespace{store.cpp}::configure_connection(), arachne::penelope::anonymous_namespace{store.cpp}::create_candidate_schema(), arachne::penelope::anonymous_namespace{store.cpp}::database::database(), export_jsonl(), arachne::penelope::anonymous_namespace{store.cpp}::database::get(), arachne::penelope::anonymous_namespace{store.cpp}::require_sha256(), arachnespace::contracts::research_candidate_graph_plan, arachnespace::contracts::research_candidate_graph_snapshot, arachne::penelope::candidate_snapshot_request::run_id, arachne::crypto::sha256_file(), and arachne::penelope::anonymous_namespace{store.cpp}::transaction::transaction().

Referenced by anonymous_namespace{main.cpp}::command_candidate_rebuild().

Here is the call graph for this function:

Here is the caller graph for this function:

root()

const std::filesystem::path & arachne::penelope::store::root ( ) const

inlinenodiscardnoexcept

Definition at line 101 of file store.hpp.

                                                                 {
        return root_;
    }

Member Data Documentation

root_

std::filesystem::path arachne::penelope::store::root_

private

Definition at line 106 of file store.hpp.

---

The documentation for this class was generated from the following files:

• store.hpp
• store.cpp