runtime_context.h

#pragma once
 
#include <neograph/api.h>
#include <neograph/json.h>
#include <neograph/types.h>
#include <core/native_archive.h>
 
#include <cstdint>
#include <map>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>
#include <vector>
 
namespace neograph {
 
enum class RuntimeTrustClass : std::uint8_t {
    UntrustedInput,
    ModelOutput,
    ToolOutput,
    Developer,
    HostPolicy,
};
 
enum class ContextArtifactKind : std::uint8_t {
    RawHistory,
    DerivedContext,
    RequiredSkill,
    HookOutput,
    HardConstraint,
    UntrustedSupplemental,
};
 
enum class ContextPlacement : std::uint8_t {
    BeforeLatestUser,
    AfterLatestUser,
    AfterHistory,
    BeforeHistory,
};
 
enum class RuntimeGuaranteeProfile : std::uint8_t {
    Legacy,
    Recorded,
    Strict,
};
 
enum class StabilityClass : std::uint8_t {
    Stable,
    Slow,
    Volatile,
};
 
enum class AnchorMode : std::uint8_t {
    Replace,
    KeepInPlace,
};
 
enum class ContextBreakReason : std::uint8_t {
    Compaction,
    StableChange,
    LayoutChange,
    AnchorDrop,
    OrderChange,
    Explicit,
};
 
enum class AssemblyLayout : std::uint8_t {
    Legacy,
    StableFirst,
};
 
enum class ClassSource : std::uint8_t {
    Declared,
    Derived,
};
 
enum class ContextPrefixClaim : std::uint8_t {
    Extends,
    Breaks,
};
 
NEOGRAPH_API std::string_view to_string(RuntimeTrustClass value) noexcept;
NEOGRAPH_API std::string_view to_string(ContextArtifactKind value) noexcept;
NEOGRAPH_API std::string_view to_string(ContextPlacement value) noexcept;
NEOGRAPH_API std::string_view to_string(RuntimeGuaranteeProfile value) noexcept;
NEOGRAPH_API std::string_view to_string(StabilityClass value) noexcept;
NEOGRAPH_API std::string_view to_string(AnchorMode value) noexcept;
NEOGRAPH_API std::string_view to_string(ContextBreakReason value) noexcept;
NEOGRAPH_API std::string_view to_string(ContextPrefixClaim value) noexcept;
NEOGRAPH_API std::string_view to_string(AssemblyLayout value) noexcept;
NEOGRAPH_API std::string_view to_string(ClassSource value) noexcept;
NEOGRAPH_API RuntimeTrustClass runtime_trust_class_from_string(std::string_view value);
NEOGRAPH_API ContextArtifactKind context_artifact_kind_from_string(std::string_view value);
NEOGRAPH_API ContextPlacement context_placement_from_string(std::string_view value);
NEOGRAPH_API RuntimeGuaranteeProfile runtime_guarantee_profile_from_string(
    std::string_view value);
NEOGRAPH_API StabilityClass stability_class_from_string(std::string_view value);
NEOGRAPH_API AnchorMode anchor_mode_from_string(std::string_view value);
NEOGRAPH_API ContextBreakReason context_break_reason_from_string(std::string_view value);
NEOGRAPH_API ContextPrefixClaim context_prefix_claim_from_string(std::string_view value);
NEOGRAPH_API AssemblyLayout assembly_layout_from_string(std::string_view value);
NEOGRAPH_API ClassSource class_source_from_string(std::string_view value);
 
inline constexpr std::string_view COMPACTION_PRODUCER_ID = "neograph-compaction.v1";
 
NEOGRAPH_API bool context_artifact_kind_renders_as_system(ContextArtifactKind kind) noexcept;
 
inline constexpr std::uint32_t STABILITY_DERIVATION_RULE_VERSION = 1;
 
NEOGRAPH_API StabilityClass derive_stability_class(
    ContextArtifactKind kind, std::string_view producer_id) noexcept;
 
enum class ContextStabilityRefusal : std::uint8_t {
    VolatileSystemArtifact,
    PredecessorUnavailable,
    PredecessorOrderUnknown,
    ArtifactsMismatch,
    RawWindowMoved,
    RawWindowNotGrown,
    StablePrefixChanged,
    AnchorDropped,
    AnchorOutOfRange,
    LayoutChangeUndeclared,
    StableOutsideHistoryHead,
    VolatileOutsideTail,
    TierOrderViolated,
    VolatileSystemText,
    PrefixBoundaryUnavailable,
    AmbiguousOrder,
};
 
NEOGRAPH_API std::string_view to_string(ContextStabilityRefusal value) noexcept;
 
class NEOGRAPH_API ContextStabilityError final : public std::invalid_argument {
public:
    ContextStabilityError(ContextStabilityRefusal code, const std::string& message);
    ContextStabilityRefusal code() const noexcept;
 
private:
    ContextStabilityRefusal code_;
};
 
struct RuntimeHistoryRecordData {
    std::string                 feed_id;
    std::uint64_t               sequence = 0;
    std::string                 message_id;
    RuntimeTrustClass           trust = RuntimeTrustClass::UntrustedInput;
    sp::Message                 message;
    std::optional<json>         source_payload;
    std::optional<std::string>  source_media_type;
    std::optional<std::string>  predecessor_id;
};
 
class NEOGRAPH_API RuntimeHistoryRecord final {
public:
    // 3 since SchemaProvider interface 7 (provider-message/v3). A version 2 record is read
    // with its bytes and id as stored, so a feed's predecessor chain stays intact.
    static constexpr std::uint32_t STORAGE_SCHEMA_VERSION = 3;
    static constexpr std::uint32_t LEGACY_STORAGE_SCHEMA_VERSION = 2;
 
    static RuntimeHistoryRecord create(RuntimeHistoryRecordData data);
    static RuntimeHistoryRecord parse(
        std::string_view stored_bytes,
        const std::shared_ptr<sp::NativeArchive>& archive = {},
        std::string_view owner_id = {});
 
    const std::string& feed_id() const noexcept;
    std::uint64_t sequence() const noexcept;
    const std::string& message_id() const noexcept;
    RuntimeTrustClass trust() const noexcept;
    const sp::Message& message() const noexcept;
    std::optional<json> source_payload() const;
    const std::optional<std::string>& source_media_type() const noexcept;
    const std::optional<std::string>& predecessor_id() const noexcept;
    const std::string& id() const noexcept;
    std::string serialize_canonical() const;
    std::string serialize_canonical(
        const std::shared_ptr<sp::NativeArchive>& archive,
        std::string_view owner_id) const;
 
private:
    struct Impl;
    explicit RuntimeHistoryRecord(std::shared_ptr<const Impl> impl);
    std::shared_ptr<const Impl> impl_;
};
 
struct ContextArtifactData {
    ContextArtifactKind kind = ContextArtifactKind::DerivedContext;
    std::string          producer_id;
    std::string          source_digest;
    std::string          source_feed_id;
    std::uint64_t        covers_from_sequence = 0;
    std::uint64_t        covers_through_sequence = 0;
    std::string          media_type;
    ContextPlacement     placement = ContextPlacement::BeforeLatestUser;
    std::int32_t         priority = 0;
    bool                 required = false;
    json                 content;
    std::optional<StabilityClass> stability_class;
    std::optional<AnchorMode>     anchor_mode;
};
 
class NEOGRAPH_API ContextArtifact final {
public:
    // 2 only for an artifact that sets stability_class or anchor_mode; every other
    // artifact keeps version 1 and the identity it always had.
    static constexpr std::uint32_t STORAGE_SCHEMA_VERSION = 2;
    static constexpr std::uint32_t LEGACY_STORAGE_SCHEMA_VERSION = 1;
 
    static ContextArtifact create(ContextArtifactData data);
    static ContextArtifact parse(std::string_view stored_bytes);
 
    ContextArtifactKind kind() const noexcept;
    const std::string& producer_id() const noexcept;
    const std::string& source_digest() const noexcept;
    const std::string& source_feed_id() const noexcept;
    std::uint64_t covers_from_sequence() const noexcept;
    std::uint64_t covers_through_sequence() const noexcept;
    const std::string& media_type() const noexcept;
    ContextPlacement placement() const noexcept;
    std::int32_t priority() const noexcept;
    bool required() const noexcept;
    json content() const;
    const std::string& content_digest() const noexcept;
    StabilityClass stability_class() const noexcept;
    const std::optional<StabilityClass>& declared_stability_class() const noexcept;
    AnchorMode anchor_mode() const noexcept;
    const std::optional<AnchorMode>& declared_anchor_mode() const noexcept;
    const std::string& id() const noexcept;
    std::string serialize_canonical() const;
 
private:
    struct Impl;
    explicit ContextArtifact(std::shared_ptr<const Impl> impl);
    std::shared_ptr<const Impl> impl_;
};
 
struct ContextEpochData {
    std::string                run_id;
    std::uint64_t              sequence = 0;
    std::optional<std::string> predecessor_id;
    std::string                feed_id;
    std::uint64_t              raw_from_sequence = 0;
    std::uint64_t              raw_through_sequence = 0;
    std::string                raw_window_digest;
    std::vector<std::string>   artifact_ids;
    RuntimeGuaranteeProfile    guarantee_profile = RuntimeGuaranteeProfile::Recorded;
    std::optional<std::vector<std::string>> ordered_artifact_ids;
    std::optional<ContextPrefixClaim> prefix_claim;
    std::optional<ContextBreakReason> break_reason;
    AssemblyLayout assembly_layout = AssemblyLayout::Legacy;
};
 
class NEOGRAPH_API ContextEpoch final {
public:
    // 2 only for an epoch that sets ordered_artifact_ids, prefix_claim, break_reason
    // or the StableFirst layout; every other epoch keeps version 1 and the identity it had.
    static constexpr std::uint32_t STORAGE_SCHEMA_VERSION = 2;
    static constexpr std::uint32_t LEGACY_STORAGE_SCHEMA_VERSION = 1;
 
    static ContextEpoch create(ContextEpochData data);
    static ContextEpoch parse(std::string_view stored_bytes);
 
    const std::string& run_id() const noexcept;
    std::uint64_t sequence() const noexcept;
    const std::optional<std::string>& predecessor_id() const noexcept;
    const std::string& feed_id() const noexcept;
    std::uint64_t raw_from_sequence() const noexcept;
    std::uint64_t raw_through_sequence() const noexcept;
    const std::string& raw_window_digest() const noexcept;
    const std::vector<std::string>& artifact_ids() const noexcept;
    RuntimeGuaranteeProfile guarantee_profile() const noexcept;
    const std::optional<std::vector<std::string>>& ordered_artifact_ids() const noexcept;
    const std::optional<ContextPrefixClaim>& prefix_claim() const noexcept;
    const std::optional<ContextBreakReason>& break_reason() const noexcept;
    AssemblyLayout assembly_layout() const noexcept;
    const std::string& id() const noexcept;
    std::string serialize_canonical() const;
 
private:
    struct Impl;
    explicit ContextEpoch(std::shared_ptr<const Impl> impl);
    std::shared_ptr<const Impl> impl_;
};
 
struct ContextPrefixBoundary {
    std::uint64_t message_index = 0;
    std::uint64_t part_index = 0;
    auto operator<=>(const ContextPrefixBoundary&) const = default;
};
 
struct ContextAssemblyReceiptData {
    std::string              context_epoch_id;
    std::string              normalized_request_digest;
    std::string              message_window_digest;
    std::vector<std::string> artifact_ids;
    std::vector<std::string> required_skill_artifact_ids;
    std::uint64_t            raw_from_sequence = 0;
    std::uint64_t            raw_through_sequence = 0;
    std::uint64_t            estimated_input_tokens = 0;
    std::uint64_t            mandatory_input_tokens = 0;
 
    // Version 2. Each field is part of the identity only when set, and a receipt
    // that sets none is a version 1 receipt. A version 1 receipt knows none of
    // them: its prefix is unknown, not empty.
    std::optional<std::vector<std::string>>        assembled_artifact_ids;
    std::optional<std::map<std::string, StabilityClass>> artifact_classes;
    std::optional<std::map<std::string, ClassSource>> class_sources;
    std::optional<std::uint32_t> class_rule_version;
    std::optional<std::string>                     encoder_family;
    std::optional<ContextPrefixBoundary>           stable_boundary;
    std::optional<ContextPrefixBoundary>           prefix_boundary;
    std::optional<std::string>                     prefix_digest;
    std::optional<std::string>                     tools_digest;
    std::optional<ContextBreakReason>              break_reason;
};
 
class NEOGRAPH_API ContextAssemblyReceipt final {
public:
    static constexpr std::uint32_t STORAGE_SCHEMA_VERSION = 2;
    static constexpr std::uint32_t LEGACY_STORAGE_SCHEMA_VERSION = 1;
 
    static ContextAssemblyReceipt create(
        ContextAssemblyReceiptData data,
        const ContextEpoch& epoch,
        const std::vector<ContextArtifact>& artifacts);
    static ContextAssemblyReceipt parse(
        std::string_view stored_bytes,
        const ContextEpoch& epoch,
        const std::vector<ContextArtifact>& artifacts);
 
    const std::string& context_epoch_id() const noexcept;
    const std::string& normalized_request_digest() const noexcept;
    const std::string& message_window_digest() const noexcept;
    const std::vector<std::string>& artifact_ids() const noexcept;
    const std::vector<std::string>& required_skill_artifact_ids() const noexcept;
    std::uint64_t raw_from_sequence() const noexcept;
    std::uint64_t raw_through_sequence() const noexcept;
    std::uint64_t estimated_input_tokens() const noexcept;
    std::uint64_t mandatory_input_tokens() const noexcept;
    const std::optional<std::vector<std::string>>& assembled_artifact_ids() const noexcept;
    const std::optional<std::map<std::string, StabilityClass>>& artifact_classes() const noexcept;
    const std::optional<std::map<std::string, ClassSource>>& class_sources() const noexcept;
    const std::optional<std::uint32_t>& class_rule_version() const noexcept;
    const std::optional<std::string>& encoder_family() const noexcept;
    const std::optional<ContextPrefixBoundary>& stable_boundary() const noexcept;
    const std::optional<ContextPrefixBoundary>& prefix_boundary() const noexcept;
    const std::optional<std::string>& prefix_digest() const noexcept;
    const std::optional<std::string>& tools_digest() const noexcept;
    const std::optional<ContextBreakReason>& break_reason() const noexcept;
    const std::string& id() const noexcept;
    std::string serialize_canonical() const;
 
private:
    struct Impl;
    explicit ContextAssemblyReceipt(std::shared_ptr<const Impl> impl);
    static ContextAssemblyReceipt create_structural(ContextAssemblyReceiptData data);
    std::shared_ptr<const Impl> impl_;
};
 
NEOGRAPH_API void validate_context_assembly_receipt(
    const ContextAssemblyReceipt& receipt,
    const ContextEpoch& epoch,
    const std::vector<ContextArtifact>& artifacts);
 
struct ContextArtifactOrderEntry {
    ContextArtifact artifact;
    std::string     order_key;
};
 
NEOGRAPH_API std::vector<std::string> order_context_artifacts(
    const std::vector<ContextArtifactOrderEntry>& entries);
 
NEOGRAPH_API void validate_context_layout(
    const ContextEpoch& epoch, const std::vector<ContextArtifact>& artifacts);
 
NEOGRAPH_API void verify_context_epoch_claim(
    const ContextEpoch& epoch,
    const std::vector<ContextArtifact>& artifacts,
    const ContextEpoch* predecessor,
    const std::vector<ContextArtifact>& predecessor_artifacts);
 
}  // namespace neograph