evidence_ledger.h

Go to the documentation of this file.

 
#pragma once
 
#include <neograph/api.h>
#include <neograph/json.h>
 
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <memory>
#include <limits>
#include <vector>
#include <utility>
 
namespace neograph::research {
 
enum class ResearchTaskKind : std::uint8_t {
    PrimaryExtraction,
    IndependentReview,
    Reproduction,
    Rebuttal,
    Reconciliation,
};
 
NEOGRAPH_API std::string_view to_string(ResearchTaskKind kind) noexcept;
NEOGRAPH_API ResearchTaskKind research_task_kind_from_string(std::string_view value);
 
enum class ResearchTaskState : std::uint8_t {
    Ready,
    Leased,
    Published,
    Cancelled,
};
 
NEOGRAPH_API std::string_view to_string(ResearchTaskState state) noexcept;
NEOGRAPH_API ResearchTaskState research_task_state_from_string(std::string_view value);
 
enum class EvidencePolarity : std::uint8_t {
    Supports,
    Contradicts,
    Inconclusive,
    NoSupport,
};
 
NEOGRAPH_API std::string_view to_string(EvidencePolarity polarity) noexcept;
NEOGRAPH_API EvidencePolarity evidence_polarity_from_string(std::string_view value);
 
enum class SourceLifecycle : std::uint8_t {
    Unclaimed,
    Claimed,
    Extracted,
    Reviewed,
    Corroborated,
    Contradicted,
    Inconclusive,
};
 
NEOGRAPH_API std::string_view to_string(SourceLifecycle state) noexcept;
 
enum class ClaimResolutionKind : std::uint8_t {
    Unresolved,
    Corroborated,
    Contradicted,
    Inconclusive,
    ReconciliationRequired,
    HumanDecisionRequired,
};
 
NEOGRAPH_API std::string_view to_string(ClaimResolutionKind kind) noexcept;
 
enum class EvidencePublishResult : std::uint8_t {
    Published,
    Duplicate,
};
 
struct NEOGRAPH_API SourceIdentity {
    std::uint32_t schema_version = 1;
    std::string source_id;
    std::string canonical_locator;
    std::string version;
    std::string content_hash;
    std::vector<std::string> aliases;
    json metadata = json::object();
 
    bool operator==(const SourceIdentity&) const = default;
};
 
struct NEOGRAPH_API ResearchTaskSpec {
    std::uint32_t schema_version = 1;
    std::string task_id;
    std::string objective_id;
    std::string source_id;
    std::string claim_id;
    std::string owner_scope;
    std::string scope;
    ResearchTaskKind kind = ResearchTaskKind::PrimaryExtraction;
    std::string replication_of_task_id;
    bool intentional_replication = false;
    std::uint64_t lease_duration_ms = 60'000;
    json requirements = json::object();
 
    bool operator==(const ResearchTaskSpec&) const = default;
};
 
struct NEOGRAPH_API ResearchTask {
    ResearchTaskSpec spec;
    ResearchTaskState state = ResearchTaskState::Ready;
    std::uint64_t generation = 0;
    std::string lease_id;
    std::string leased_by;
    std::uint64_t lease_expires_at_unix_ms = 0;
    std::string board_id;
    std::string published_artifact_id;
 
    bool operator==(const ResearchTask&) const = default;
};
 
struct NEOGRAPH_API ResearchLeaseRequest {
    std::string task_id;
    std::string lease_id;
    std::string worker_id;
    std::string owner_scope;
    std::uint64_t now_unix_ms = 0;
    std::string board_id;
    std::uint32_t board_max_active_leases = 0;
    std::uint64_t board_max_cost_microunits = std::numeric_limits<std::uint64_t>::max();
    std::uint64_t cost_microunits = 0;
 
    bool operator==(const ResearchLeaseRequest&) const = default;
};
 
struct NEOGRAPH_API ResearchTaskLease {
    std::string task_id;
    std::string lease_id;
    std::string worker_id;
    std::string owner_scope;
    std::uint64_t generation = 0;
    std::uint64_t expires_at_unix_ms = 0;
    std::string board_id;
 
    bool operator==(const ResearchTaskLease&) const = default;
};
 
 
struct NEOGRAPH_API EvidenceArtifact {
    std::uint32_t schema_version = 1;
    std::string artifact_id;
    std::string task_id;
    std::string source_id;
    std::string claim_id;
    std::string owner_scope;
    std::string source_version;
    std::string source_content_hash;
    EvidencePolarity polarity = EvidencePolarity::Inconclusive;
    std::string evidence_locator;
    std::string observation;
    std::string searched_scope;
    json conditions = json::object();
    json applicability = json::object();
    json uncertainty = json::object();
    std::vector<std::string> limitations;
    std::vector<std::string> contradictions;
    std::string recommended_next_task;
    double confidence = 0.0;
    std::string worker_id;
    std::string model_id;
    std::string tool_id;
    std::string program_version_id;
    std::string program_run_id;
    std::string a2a_message_id;
    json provenance = json::object();
 
    bool operator==(const EvidenceArtifact&) const = default;
};
 
struct NEOGRAPH_API ClaimResolution {
    std::string claim_id;
    ClaimResolutionKind kind = ClaimResolutionKind::Unresolved;
    std::vector<std::string> supporting_artifact_ids;
    std::vector<std::string> contradicting_artifact_ids;
    std::vector<std::string> inconclusive_artifact_ids;
    std::optional<ResearchTaskKind> recommended_next_task;
 
    bool operator==(const ClaimResolution&) const = default;
};
 
class NEOGRAPH_API EvidenceLedger {
public:
    virtual ~EvidenceLedger() = default;
 
    virtual void register_source(SourceIdentity source) = 0;
    [[nodiscard]] virtual std::optional<SourceIdentity>
    source(std::string_view source_id) const = 0;
 
    virtual void create_task(ResearchTaskSpec task) = 0;
    [[nodiscard]] virtual std::optional<ResearchTask>
    task(std::string_view owner_scope, std::string_view task_id) const = 0;
 
    [[nodiscard]] virtual std::vector<ResearchTask>
    tasks(std::string_view owner_scope, bool include_terminal) const = 0;
    [[nodiscard]] virtual std::optional<ResearchTaskLease>
    acquire_lease(ResearchLeaseRequest request) = 0;
 
    [[nodiscard]] virtual bool renew_lease(const ResearchTaskLease& lease,
                                           std::uint64_t now_unix_ms) = 0;
 
    [[nodiscard]] virtual std::vector<std::string>
    expire_leases(std::string_view owner_scope, std::uint64_t now_unix_ms) = 0;
 
    [[nodiscard]] virtual EvidencePublishResult
    publish(const ResearchTaskLease& lease, EvidenceArtifact artifact,
            std::uint64_t now_unix_ms) = 0;
 
    [[nodiscard]] virtual std::vector<EvidenceArtifact>
    artifacts_for_claim(std::string_view owner_scope, std::string_view claim_id) const = 0;
    [[nodiscard]] virtual SourceLifecycle source_lifecycle(std::string_view owner_scope,
                                                            std::string_view source_id,
                                                            std::uint64_t now_unix_ms) const = 0;
    [[nodiscard]] virtual ClaimResolution
    resolve_claim(std::string_view owner_scope, std::string_view claim_id) const = 0;
};
 
struct NEOGRAPH_API ResearchTaskBoardBudget {
    std::uint32_t max_active_leases = 1;
    std::uint64_t max_cost_microunits = std::numeric_limits<std::uint64_t>::max();
};
 
class NEOGRAPH_API ResearchTaskBoard final {
public:
    explicit ResearchTaskBoard(EvidenceLedger& ledger) noexcept : ledger_(ledger) {}
 
    ResearchTaskBoard(const ResearchTaskBoard&) = delete;
    ResearchTaskBoard& operator=(const ResearchTaskBoard&) = delete;
 
    void submit(ResearchTaskSpec task) { ledger_.create_task(std::move(task)); }
 
    [[nodiscard]] std::optional<ResearchTaskLease> acquire_next(
        std::string_view owner_scope, std::string_view worker_id,
        std::string_view board_id, std::uint64_t now_unix_ms,
        ResearchTaskBoardBudget budget = {}) const;
 
    [[nodiscard]] EvidencePublishResult publish(
        const ResearchTaskLease& lease, EvidenceArtifact artifact,
        std::uint64_t now_unix_ms) const {
        return ledger_.publish(lease, std::move(artifact), now_unix_ms);
    }
 
    [[nodiscard]] std::vector<ResearchTask>
    snapshot(std::string_view owner_scope) const {
        return ledger_.tasks(owner_scope, true);
    }
 
private:
    EvidenceLedger& ledger_;
};
 
} // namespace neograph::research