execution.hpp

Go to the documentation of this file.

#pragma once
 
#include "exit_leg_lifecycle.hpp"
#include "order_action.hpp"
#include <cstddef>
#include <cstdint>
#include <optional>
#include <string>
#include <variant>
#include <vector>
 
namespace pineforge::execution {
 
// Whole-book reduction is explicit: it never relies on a rounded aggregate
// quantity being exactly equal to the sum of individual physical lots.
struct Flatten {};
using Action = std::variant<Flatten, order_action::Reduce, order_action::Transact>;
 
// Why a closed row exited, as a value the closer records rather than a string
// a reader decodes. The numbers ARE the public C contract
// (strategy_closed_trade_close_cause, pineforge.h), so they are append-only:
// 0 is the documented "no cause recorded" value, never an error.
//
// Unspecified leaves the classification to the generic facts already on the
// row (open_at_end -> RangeEnd, exit_from_bracket -> Bracket, otherwise
// Script). Liquidation and RiskLimit are what a kernel-originated request
// carries (native_order::RequestOrigin::KernelLiquidation / KernelRisk), and
// Bracket is what a host request its owner's fill armed carries when it only
// closes (a native_order::WaitForApplied owner with a Reduce, Flatten or
// host-sized close intent, the relation native_toolkit::submit_bracket
// builds); a host that runs its own forced-close policy — the Pine adapter's
// margin call, its strategy.risk.max_intraday_loss close and its filled-order
// cap close — records its own cause on the row it produced.
enum class CloseCause : std::uint8_t {
    Unspecified = 0,
    Script = 1,
    Bracket = 2,
    Liquidation = 3,
    RiskLimit = 4,
    FillCap = 5,
    RangeEnd = 6,
};
 
// The caller has already matched/admitted the action and resolved its price.
// Settlement does not apply another lot step, price grid, slippage or entry cap.
struct Fill {
    double price;
    std::string id;
    std::string comment;
    uint64_t incarnation = 0;
    // An observed execution charge in account currency, including rebates.
    // Otherwise the engine's configured schedule quotes the current fill.
    std::optional<double> commission_account = std::nullopt;
    // Appended last so every existing aggregate initializer keeps its meaning.
    CloseCause close_cause = CloseCause::Unspecified;
};
 
enum class Status {
    Applied, NoEffect, InvalidPrice, InvalidQuantity, InvalidBook,
    UnrepresentableQuantity, InvalidAccounting,
    // Caller-supplied lifecycle targets/revisions/operations that cannot be
    // applied to the current pending book. Not durable engine state.
    InvalidLifecycle,
    // Invalid or unavailable run-local opening exposure on a scoped close.
    // Existing whole-book entry points do not return this status.
    InvalidCloseTarget = 8
};
 
struct Result {
    Status status = Status::NoEffect;
    // Aggregate projections of the physical effects; the lot/trade roster is
    // authoritative. Opening units are signed; closing units are nonnegative.
    double closed_units = 0.0;
    double opened_units = 0.0;
    // This execution's current ticket and committed-row references. Zero when
    // the result is not Applied. Native terminal events copy these facts.
    double current_ticket = 0.0;
    std::size_t first_trade_index = 0;
    std::size_t closed_trade_count = 0;
    uint64_t opened_lot_incarnation = 0;
};
 
// Stack-bound physical coordinates for one settlement. Native supplies time
// and index from the matching point and leaves the trail carry empty; the
// settling path fills it in for a trail exit. `account_fx` is the
// account-currency rate the execution's rows convert at; empty, they convert
// at the engine's rate at its presented clock (active_account_currency_fx()).
struct PhysicalExecutionContext {
    int64_t effective_time_ms = 0;
    int interval_index = 0;
    std::optional<double> preceding_exit_trail_peak;
    std::optional<double> account_fx;
};
 
// Stack-local inspect facts. Destroyed at the end of one matching step.
struct SettlementInspection {
    Status status = Status::NoEffect;
    double closed_units = 0.0;
    double opened_units = 0.0;
    double resulting_abs_units = 0.0;
    std::size_t resulting_lot_count = 0;
    double resulting_abs_notional = 0.0;
    double current_ticket = 0.0;
    bool would_open = false;
    bool incoming_short = false;
};
 
// One pre-close operation on an exact pending identity. created_seq 0 and
// Target{0,0} are actual expected values, not wildcards. The coordinator
// allocates the batch cause and does not rewrite operation payloads.
struct LifecycleIntent {
    uint64_t order_incarnation = 0;
    int64_t created_seq = 0;
    exit_legs::Target target{};
    uint64_t expected_revision = 0;
    exit_legs::Operation operation{};
};
 
// Engaging this batch allocates one observation frame on a successful
// commit even when operations is empty. Empty optional means no allocation.
// Phase must be a valid exit_legs::Phase even for an empty operations list.
struct LifecycleBatch {
    exit_legs::Phase phase = exit_legs::Phase::Observation;
    std::vector<LifecycleIntent> operations;
};
 
// Exact pending EXIT to remove after old-cycle unbind and before any
// quoted opening bind. Fields are the initial snapshot before this
// execution's own effects; incarnation 0 is refused.
struct PendingRemoval {
    uint64_t incarnation = 0;
    int64_t created_seq = 0;
    exit_legs::Target target{};
    uint64_t expected_revision = 0;
};
 
// Transient, stack-local effects for one native settlement preparation. Not
// stored, hashed, replayed, or reusable execution authority.
struct LifecycleEffects {
    std::optional<LifecycleBatch> pre_close;
    std::vector<PendingRemoval> removals;
};
 
} // namespace pineforge::execution