Home /Modules/advantage/advantage_store.hpp

advantage_store.hpp

advantage/advantage_store.hpp · 96 line(s) · c

// advantage_store.hpp - In-memory model + loader for advantages.xml.
//
// Loads the source advantages (assumptions and strings of knowledge) from
// the XML document into C++ structures so they can be analyzed. The parser
// is a small, dependency-free reader scoped to the advantages.xml schema
// produced by this module; it is not a general-purpose XML engine.
#ifndef ADVANTAGE_STORE_HPP
#define ADVANTAGE_STORE_HPP

#include <string>
#include <vector>

namespace advantage {

// Finite bounds on what the loader will accept. Beyond these the load fails
// with a clear error instead of consuming unbounded memory or time. They are
// generous for a hand-authored knowledge store.
constexpr std::size_t kMaxDocumentBytes = 16u * 1024u * 1024u;  // 16 MiB
constexpr std::size_t kMaxSources = 10000;
constexpr std::size_t kMaxObservationsPerSource = 100000;

// A declared remote origin for additional knowledge strings. Parsed from an
// optional <knowledgeSource url="..." sha256="..."/> element. Declaring one
// does NOT fetch anything: base parsing is pure and offline. Fetching is an
// explicit, opt-in step handled by enrich.hpp with strict safety gates.
struct KnowledgeSource {
    std::string url;      // e.g. "https://host/path" or "file:///path"
    std::string sha256;   // optional content pin (lowercase hex), may be empty
};

// One recorded outcome: what was gained (reward) against what would have
// been gained anyway (baseline). Parsed from <observation reward baseline/>.
struct Observation {
    double reward = 0.0;
    double baseline = 0.0;
};

// One source of leverage loaded from <sourceAdvantage> in the XML.
struct SourceAdvantage {
    std::string id;
    std::string kind;
    std::string name;
    std::string description;
    std::vector<std::string> assumptions;  // <assumptions><assumption>...

    // Parallel to `assumptions` (always the same size): true when the
    // assumption is currently held, false when marked status="doubted".
    // Unmarked assumptions default to held.
    std::vector<bool> assumptionHeld;

    // Recorded outcomes for this source, from <evidence><observation/>.
    // These feed the C advantage math (see counsel.hpp). Empty means the
    // source has no track record yet -- which is not the same as zero.
    std::vector<Observation> evidence;
    double evidenceWeight = 1.0;  // <evidence weight="..."> scales the advantage

    std::vector<std::string> knowledge;     // <knowledge><string>...

    // Knowledge strings pulled in from a remote source during enrichment.
    // Kept separate from the authored `knowledge` so provenance is never
    // confused: local/authored vs. fetched/untrusted.
    std::vector<std::string> remoteKnowledge;

    // Optional declared remote origin(s) for knowledge. Not fetched by the
    // base loader.
    std::vector<KnowledgeSource> knowledgeSources;
};

// The whole document: a version string and the set of source advantages.
struct AdvantageStore {
    std::string version;
    std::vector<SourceAdvantage> sources;

    // Lookup by id; returns nullptr if absent.
    const SourceAdvantage* find(const std::string& id) const;

    // Total counts across all sources, useful for analysis.
    std::size_t assumptionCount() const;
    std::size_t knowledgeCount() const;
    std::size_t evidenceCount() const;
};

// Load from a file path. On failure returns false and fills `error`.
bool loadFromFile(const std::string& path,
                  AdvantageStore& out,
                  std::string& error);

// Load directly from an in-memory XML string.
bool loadFromString(const std::string& xml,
                    AdvantageStore& out,
                    std::string& error);

}  // namespace advantage

#endif  // ADVANTAGE_STORE_HPP