types.h

// Portable NeoGraph projections and full typed SDK outcome consumer helpers.
#pragma once
 
#include <algorithm>
#include <limits>
#include <map>
#include <unordered_set>
#include <mutex>
#include <optional>
#include <stdexcept>
#include <string>
#include <vector>
#include <neograph/json.h>
#include <core/value.h>
#include <neograph/provider_outcome_codec.h>
#include <json/json.h>
 
namespace neograph {
 
struct ToolCall {
    std::string id;         
    std::string name;       
    std::string arguments;  
};
 
struct ChatMessage {
    std::string role;                    
    std::string content;                 
    std::vector<ToolCall> tool_calls;    
    std::string tool_call_id;            
    std::string tool_name;               
    std::string tool_status;
    bool tool_retryable = false;
    bool tool_effect_uncertain = false;
    std::vector<std::string> image_urls; 
    std::string reasoning;
    json reasoning_details = json::array();
};
 
struct ChatTool {
    std::string name;         
    std::string description;  
    json parameters;          
    std::optional<bool> strict;
};
 
struct GeneratedArtifact {
    std::string kind;         
    std::string mime_type;
    std::string base64_data;  
    std::string url;
    std::string file_id;
    json metadata = json::object();
};
 
 
// Provider reports and conservative budget authority are intentionally separate.
class NEOGRAPH_API UsageAccumulator {
public:
    struct AuthoritySnapshot {
        std::uint64_t charged = 0, reserved = 0;
        std::vector<std::string> provider_effects;
        sp::Usage reports;
        bool has_report = false;
    };
    AuthoritySnapshot authority_snapshot() const {
        std::lock_guard lock(mutex_);
        AuthoritySnapshot result;
        result.charged = charged_;
        result.reserved = reserved_;
        result.provider_effects.assign(provider_effects_.begin(), provider_effects_.end());
        std::sort(result.provider_effects.begin(), result.provider_effects.end());
        result.reports = reports_;
        result.has_report = has_report_;
        return result;
    }
    // Recorded playback may observe authenticated custody, never spend/refund it.
    void seal_observation() {
        std::lock_guard lock(mutex_);
        observation_only_ = true;
    }
    // Caller must authenticate custody and original scope/ceiling first.
    // Restoration is one-shot into a pristine bank, never replacement/reset.
    void restore_authority(AuthoritySnapshot snapshot) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        if (authority_restored_ || charged_ != 0 || reserved_ != 0 || has_report_ || !provider_effects_.empty())
            throw std::logic_error("Spending authority may only restore into a pristine bank");
        std::unordered_set<std::string> effects;
        effects.reserve(snapshot.provider_effects.size());
        for (auto& key : snapshot.provider_effects)
            if (!effects.insert(std::move(key)).second)
                throw std::invalid_argument("Spending authority snapshot has duplicate effect identities");
        charged_ = snapshot.charged;
        reserved_ = snapshot.reserved;
        reports_ = std::move(snapshot.reports);
        has_report_ = snapshot.has_report;
        provider_effects_ = std::move(effects);
        authority_restored_ = true;
    }
    bool remember_provider_effect(std::string key) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        return provider_effects_.insert(std::move(key)).second;
    }
    void observe(const sp::Usage& usage) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        add_report(usage);
    }
    void add(const sp::Usage& usage) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        add_report(usage);
        if (const auto charge = final_charge(usage)) charged_ = sum(charged_, *charge);
    }
    bool try_reserve(std::uint64_t tokens, std::uint64_t ceiling) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        if (tokens == 0 || ceiling == 0) return false;
        const auto committed = sum(charged_, reserved_);
        if (committed > ceiling || tokens > ceiling - committed) return false;
        reserved_ = sum(reserved_, tokens);
        return true;
    }
    // Only for operations proven not dispatched. Unknown delivery retains authority.
    void release_reservation(std::uint64_t tokens) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        reserved_ -= std::min(reserved_, tokens);
    }
    void settle_reservation(std::uint64_t reserved, const sp::Usage& usage) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        add_report(usage);
        const auto charge = final_charge(usage);
        if (!charge) return;
        const auto held = std::min(reserved_, reserved);
        reserved_ -= held;
        charged_ = sum(charged_, *charge);
    }
    sp::Usage snapshot() const {
        std::lock_guard lock(mutex_);
        return reports_;
    }
    std::uint64_t total_tokens_wide() const noexcept {
        std::lock_guard lock(mutex_);
        return sum(charged_, reserved_);
    }
    // Only trusted durable journals restore conservative spending authority.
    // This neither invents a provider report nor releases a reservation.
    void restore_charge(std::uint64_t amount) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        charged_ = sum(charged_, amount);
    }
    void restore_reservation(std::uint64_t amount) {
        std::lock_guard lock(mutex_);
        require_live_authority_locked();
        reserved_ = sum(reserved_, amount);
    }
    static std::optional<std::uint64_t> conservative_final_charge(const sp::Usage& usage) {
        return final_charge(usage);
    }
private:
    void require_live_authority_locked() const {
        if (observation_only_)
            throw std::logic_error("Recorded replay bank is observation-only");
    }
    static std::uint64_t sum(std::uint64_t a, std::uint64_t b) noexcept {
        return b > std::numeric_limits<std::uint64_t>::max() - a
            ? std::numeric_limits<std::uint64_t>::max() : a + b;
    }
    static std::optional<std::uint64_t> final_charge(const sp::Usage& usage) {
        if (usage.stage != sp::UsageStage::Final || usage.quality != sp::UsageQuality::Consistent ||
            !usage.input_total || !usage.output_total) return {};
        const auto input = usage.input_total->value, output = usage.output_total->value;
        if (output > std::numeric_limits<std::uint64_t>::max() - input) return {};
        const auto total = input + output;
        if ((usage.total && usage.total->value < total) ||
            (usage.provider_reported_total && usage.provider_reported_total->value < total)) return {};
        return std::max({total, usage.total ? usage.total->value : total,
            usage.provider_reported_total ? usage.provider_reported_total->value : total});
    }
    void add_report(const sp::Usage& usage) {
        if (!has_report_) { reports_ = usage; has_report_ = true; return; }
        // This bank aggregates tokens, not monetary reports. On a second report,
        // the first call's cost is no longer a valid snapshot of the aggregate.
        // Exact money evidence remains in each retained provider outcome.
        if (!provider_codec::provider_cost_absent(reports_.provider_cost))
            reports_.provider_cost = {};
        auto fold = [&](std::string_view counter, std::optional<sp::Count>& target,
                        const std::optional<sp::Count>& value) {
            if (!target || !value) { target.reset(); return; }
            if (value->value > std::numeric_limits<std::uint64_t>::max() - target->value) {
                target.reset();
                reports_.quality = sp::UsageQuality::Inconsistent;
                reports_.conflicts.push_back({std::string(counter), "aggregate counter overflow"});
                return;
            }
            target->value += value->value;
            target->evidence = sp::Evidence::Derived;
        };
        fold("input_total", reports_.input_total, usage.input_total);
        fold("output_total", reports_.output_total, usage.output_total);
        fold("total", reports_.total, usage.total);
        fold("provider_reported_total", reports_.provider_reported_total, usage.provider_reported_total);
        fold("input_uncached", reports_.input_uncached, usage.input_uncached);
        fold("cache_read", reports_.cache_read, usage.cache_read);
        fold("cache_write", reports_.cache_write, usage.cache_write);
        fold("reasoning", reports_.reasoning, usage.reasoning);
        for (auto entry = reports_.extra.begin(); entry != reports_.extra.end();) {
            const auto value = usage.extra.find(entry->first);
            if (value == usage.extra.end()) { entry = reports_.extra.erase(entry); continue; }
            if (value->second.value > std::numeric_limits<std::uint64_t>::max() - entry->second.value) {
                reports_.quality = sp::UsageQuality::Inconsistent;
                reports_.conflicts.push_back({entry->first, "aggregate counter overflow"});
                entry = reports_.extra.erase(entry);
                continue;
            }
            entry->second.value += value->second.value;
            entry->second.evidence = sp::Evidence::Derived;
            ++entry;
        }
        if (reports_.stage == sp::UsageStage::Missing && usage.stage == sp::UsageStage::Missing)
            reports_.stage = sp::UsageStage::Missing;
        else if (reports_.stage != sp::UsageStage::Final || usage.stage != sp::UsageStage::Final)
            reports_.stage = sp::UsageStage::Partial;
        if (usage.quality == sp::UsageQuality::Inconsistent) reports_.quality = usage.quality;
        reports_.conflicts.insert(reports_.conflicts.end(), usage.conflicts.begin(), usage.conflicts.end());
    }
    mutable std::mutex mutex_;
    sp::Usage reports_;
    bool has_report_ = false;
    bool authority_restored_ = false;
    bool observation_only_ = false;
    std::uint64_t charged_ = 0, reserved_ = 0;
    std::unordered_set<std::string> provider_effects_;
};
 
// --- ADL serialization: ChatMessage/ToolCall <-> json ---
// These live in the same namespace as the types for ADL lookup.
 
inline void to_json(json& j, const ToolCall& tc) {
    j = json{{"id", tc.id}, {"name", tc.name}, {"arguments", tc.arguments}};
}
 
inline void from_json(const json& j, ToolCall& tc) {
    tc.id = j.value("id", "");
    tc.name = j.value("name", "");
    tc.arguments = j.value("arguments", "");
}
 
inline void to_json(json& j, const ChatMessage& msg) {
    j["role"] = msg.role;
    j["content"] = msg.content;
    if (!msg.tool_calls.empty()) {
        j["tool_calls"] = json::array();
        for (const auto& tc : msg.tool_calls) {
            json tc_j;
            to_json(tc_j, tc);
            j["tool_calls"].push_back(tc_j);
        }
    }
    if (!msg.tool_call_id.empty()) j["tool_call_id"] = msg.tool_call_id;
    if (!msg.tool_name.empty())    j["tool_name"] = msg.tool_name;
    if (!msg.tool_status.empty())  j["tool_status"] = msg.tool_status;
    if (msg.tool_retryable)        j["tool_retryable"] = true;
    if (msg.tool_effect_uncertain) j["tool_effect_uncertain"] = true;
    if (!msg.image_urls.empty())   j["image_urls"] = msg.image_urls;
    if (!msg.reasoning.empty())    j["reasoning"] = msg.reasoning;
    if (!msg.reasoning_details.empty()) j["reasoning_details"] = msg.reasoning_details;
}
 
inline void from_json(const json& j, ChatMessage& msg) {
    msg.role    = j.value("role", "");
    msg.content = j.value("content", "");
    if (j.contains("tool_calls") && j["tool_calls"].is_array()) {
        for (const auto& tc_j : j["tool_calls"]) {
            ToolCall tc;
            from_json(tc_j, tc);
            msg.tool_calls.push_back(tc);
        }
    }
    msg.tool_call_id = j.value("tool_call_id", "");
    msg.tool_name    = j.value("tool_name", "");
    msg.tool_status  = j.value("tool_status", "");
    msg.tool_retryable = j.value("tool_retryable", false);
    msg.tool_effect_uncertain = j.value("tool_effect_uncertain", false);
    if (j.contains("image_urls") && j["image_urls"].is_array()) {
        msg.image_urls = j["image_urls"].get<std::vector<std::string>>();
    }
    msg.reasoning = j.value("reasoning", "");
    if (j.contains("reasoning_details") && !j["reasoning_details"].is_array()) {
        throw std::invalid_argument("ChatMessage reasoning_details must be an array");
    }
    msg.reasoning_details = j.contains("reasoning_details")
        ? j["reasoning_details"]
        : json::array();
}
 
 
class NEOGRAPH_API ProviderFailure final : public std::runtime_error {
public:
    explicit ProviderFailure(std::shared_ptr<const sp::Outcome> outcome)
        : std::runtime_error(std::get<sp::Failure>(*outcome).error.safe_message),
          outcome_(std::move(outcome)) {}
    const std::shared_ptr<const sp::Outcome>& outcome() const noexcept { return outcome_; }
private:
    std::shared_ptr<const sp::Outcome> outcome_;
};
 
inline std::shared_ptr<const sp::Outcome> outcome_or_throw(std::shared_ptr<const sp::Outcome> result) {
    if (!result) throw std::invalid_argument("Provider returned no owned outcome");
    if (std::holds_alternative<sp::Failure>(*result)) throw ProviderFailure(result);
    return result;
}
inline const std::vector<sp::Message>& outcome_messages(const sp::Outcome& outcome) noexcept {
    if (const auto* completion = std::get_if<sp::Completion>(&outcome)) return completion->messages;
    return std::get<sp::Failure>(outcome).partial.messages;
}
inline const sp::Usage& outcome_usage(const sp::Outcome& outcome) noexcept {
    if (const auto* completion = std::get_if<sp::Completion>(&outcome)) return completion->usage;
    return std::get<sp::Failure>(outcome).partial.usage;
}
namespace detail {
// A usage record that holds nothing at all: no stage, no counter, no cost. The
// provider reported nothing, which is not the same as reporting zero.
inline bool usage_holds_nothing(const sp::Usage& usage) noexcept {
    return usage.stage == sp::UsageStage::Missing &&
        usage.quality == sp::UsageQuality::Consistent &&
        !usage.input_total && !usage.output_total && !usage.total && !usage.provider_reported_total &&
        !usage.input_uncached && !usage.cache_read && !usage.cache_write && !usage.reasoning &&
        usage.extra.empty() && usage.conflicts.empty() &&
        provider_codec::provider_cost_absent(usage.provider_cost);
}
// The statuses SchemaProvider 0.3.1 labels `RejectedBeforeOutput`: the server
// completed an answer that declines the request. 408 and 425 ask the client to
// try again and 429 can follow started work, so they stay possibly accepted.
inline bool http_status_declines_request(int status) noexcept {
    return status >= 400 && status < 500 && status != 408 && status != 425 && status != 429;
}
}  // namespace detail
 
inline bool provider_failure_proves_not_sent(const sp::Failure& failure) noexcept {
    const auto& attempt = failure.error.attempt;
    const auto& partial = failure.partial;
    return failure.error.retry_safety == sp::RetrySafety::NotSent &&
        !attempt.request_may_have_left && attempt.request_body_bytes == 0 &&
        !attempt.response_head_seen && attempt.transport_internal_resends == 0 && !attempt.prior_usage_unknown &&
        partial.messages.empty() && !partial.stop && !partial.wire_envelope &&
        partial.raw_events.empty() && detail::usage_holds_nothing(partial.usage);
}
 
inline bool provider_failure_proves_rejected_before_output(const sp::Failure& failure) noexcept {
    const auto& attempt = failure.error.attempt;
    const auto& partial = failure.partial;
    return failure.error.retry_safety == sp::RetrySafety::RejectedBeforeOutput &&
        detail::http_status_declines_request(failure.error.http_status) &&
        attempt.request_may_have_left && attempt.response_head_seen &&
        attempt.transport_internal_resends == 0 && !attempt.prior_usage_unknown &&
        partial.messages.empty() && !partial.stop && !partial.wire_envelope &&
        std::all_of(partial.raw_events.begin(), partial.raw_events.end(),
                    [](const sp::RawWire& event) { return event.type == "http.error"; }) &&
        detail::usage_holds_nothing(partial.usage);
}
 
inline bool provider_failure_proves_not_accepted(const sp::Failure& failure) noexcept {
    return provider_failure_proves_not_sent(failure) ||
           provider_failure_proves_rejected_before_output(failure);
}
inline std::string outcome_text(const sp::Outcome& outcome) {
    std::string text;
    for (const auto& message : outcome_messages(outcome))
        for (const auto& part : message.parts)
            if (const auto* value = std::get_if<sp::Text>(&part)) text += value->value;
    return text;
}
inline std::vector<ToolCall> client_tool_calls(const sp::Message& message) {
    std::vector<ToolCall> result;
    for (const auto& part : message.parts) if (const auto* call = std::get_if<sp::ToolCall>(&part);
        call && call->kind == sp::ToolCallKind::ClientExecuted && call->input && call->input->root().is_object())
        result.push_back({call->id, call->name, call->input->root().dump()});
    return result;
}
// A completed turn the vendor paused (`sp::StopKind::PauseTurn`). The documented
// continuation resends the history, including that assistant turn, unchanged.
inline bool paused_turn(const sp::Outcome& outcome) noexcept {
    const auto* completion = std::get_if<sp::Completion>(&outcome);
    return completion && completion->stop.kind == sp::StopKind::PauseTurn;
}
inline std::vector<ToolCall> pending_client_tool_calls(const std::vector<sp::Message>& history) {
    std::map<std::string_view, const sp::ToolCall*> pending;
    std::vector<const sp::ToolCall*> order;
    for (const auto& message : history) for (const auto& part : message.parts) {
        if (const auto* call = std::get_if<sp::ToolCall>(&part);
            call && call->kind == sp::ToolCallKind::ClientExecuted && call->input &&
            call->input->root().is_object()) {
            if (!pending.emplace(call->id, call).second)
                throw std::invalid_argument("Client tool call history has duplicate unresolved identities");
            order.push_back(call);
        } else if (const auto* result = std::get_if<sp::ToolResult>(&part)) {
            pending.erase(result->tool_use_id);
        }
    }
    std::vector<ToolCall> result;
    result.reserve(pending.size());
    for (const auto* call : order) {
        const auto found = pending.find(call->id);
        if (found != pending.end() && found->second == call)
            result.push_back({call->id, call->name, call->input->root().dump()});
    }
    return result;
}
inline sp::Role portable_role(std::string_view role) {
    if (role == "system") return sp::Role::System;
    if (role == "developer") return sp::Role::Developer;
    if (role == "user") return sp::Role::User;
    if (role == "assistant") return sp::Role::Assistant;
    if (role == "tool") return sp::Role::Tool;
    throw std::invalid_argument("Invalid portable message role");
}
inline std::string_view portable_role_name(sp::Role role) {
    switch (role) {
        case sp::Role::System: return "system";
        case sp::Role::Developer: return "developer";
        case sp::Role::User: return "user";
        case sp::Role::Assistant: return "assistant";
        case sp::Role::Tool: return "tool";
    }
    throw std::invalid_argument("Invalid typed message role");
}
inline sp::Message portable_message(const ChatMessage& source) {
    if (!source.reasoning.empty() || !source.reasoning_details.empty())
        throw std::invalid_argument("Portable projection cannot import native reasoning authority");
    sp::Message message;
    message.role = portable_role(source.role);
    if (message.role == sp::Role::Tool) {
        if (!source.tool_calls.empty() || !source.image_urls.empty())
            throw std::invalid_argument("Portable tool result cannot contain calls or images");
        message.parts.emplace_back(sp::ToolResult{source.tool_call_id, source.content,
            source.tool_status != "succeeded" && !source.tool_status.empty(),
            sp::ToolResultHostMetadata{source.tool_name, source.tool_status,
                source.tool_retryable, source.tool_effect_uncertain}});
        return message;
    }
    if (!source.content.empty()) message.parts.emplace_back(sp::Text{source.content});
    for (const auto& url : source.image_urls) {
        // A data URL is inline base64; an https URL is a location the provider fetches.
        sp::Media image;
        if (url.starts_with("data:")) {
            const auto separator = url.find(";base64,");
            if (separator == std::string::npos)
                throw std::invalid_argument("Portable inline image requires a base64 data URL");
            image = sp::Media::image(url.substr(5, separator - 5),
                                     std::make_shared<const std::string>(url.substr(separator + 8)));
        } else {
            image = sp::Media::url(sp::MediaKind::Image, url);
        }
        if (sp::check_media(image, sp::config_defaults::codec_resources_image_decoded_bytes) != sp::MediaFault::None)
            throw std::invalid_argument("Invalid portable image");
        message.parts.emplace_back(std::move(image));
    }
    for (const auto& call : source.tool_calls) {
        auto parsed = sp::json::parse(call.arguments);
        auto* document = std::get_if<sp::json::Document>(&parsed);
        if (!document || !document->root().is_object())
            throw std::invalid_argument("Portable tool call requires admitted object arguments");
        sp::ToolCall typed;
        typed.id = call.id;
        typed.name = call.name;
        typed.input = std::make_shared<const sp::json::Document>(std::move(*document));
        message.parts.emplace_back(std::move(typed));
    }
    return message;
}
// Deliberately an observational projection, never used to replay provider history.
inline ChatMessage project_message(const sp::Message& message) {
    ChatMessage result;
    result.role = portable_role_name(message.role);
    result.tool_calls = client_tool_calls(message);
    for (const auto& part : message.parts) {
        if (const auto* text = std::get_if<sp::Text>(&part)) result.content += text->value;
        else if (const auto* thinking = std::get_if<sp::Thinking>(&part)) result.reasoning += thinking->text;
        else if (const auto* tool = std::get_if<sp::ToolResult>(&part)) {
            result.tool_call_id = tool->tool_use_id;
            result.content += tool->content;
            result.tool_status = tool->is_error ? "failed" : "succeeded";
            if (tool->host) {
                result.tool_name = tool->host->name;
                result.tool_status = tool->host->status;
                result.tool_retryable = tool->host->retryable;
                result.tool_effect_uncertain = tool->host->effect_uncertain;
            }
        } else if (const auto* media = std::get_if<sp::Media>(&part);
                   media && media->kind == sp::MediaKind::Image) {
            if (media->source == sp::MediaSource::Inline && media->data)
                result.image_urls.push_back("data:" + media->mime + ";base64," + *media->data);
            else if (media->source == sp::MediaSource::Url)
                result.image_urls.push_back(media->reference);
        }
    }
    return result;
}
inline json message_projection_json(const sp::Message& message) {
    return provider_codec::encode_message(message);
}
inline json usage_to_json(const sp::Usage& usage) { return provider_codec::encode_usage(usage); }
inline json outcome_projection_json(const sp::Outcome& outcome) {
    return provider_codec::observe_outcome(outcome);
}
NEOGRAPH_API std::string message_digest(const sp::Message& message);
 
} // namespace neograph