native_order.hpp

Go to the documentation of this file.

#pragma once
 
#include "execution.hpp"
#include "execution_reverse_to.hpp"
#include "execution_close_scope.hpp"
#include "market_driver.hpp"
#include "native_order_identity.hpp"
#include "detail/scratch_readback.hpp"
#include "payload_readback.hpp"
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
#include <exception>
#include <functional>
#include <iterator>
#include <limits>
#include <map>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <type_traits>
#include <utility>
#include <variant>
#include <vector>
 
namespace pineforge::detail {
class ScratchSlab;
class NativeHistoryOwner;
struct ReadThroughCacheStats;
}
// The matcher (src/native_execution_consumer.hpp) is declared in the engine
// epoch, as run_failure.hpp and execution_consumer.hpp declare epoch classes,
// so the friends below name that one class and no other.
namespace pineforge {
struct CacheCapacity;
inline namespace engine_script_run_v20 {
class NativeExecutionConsumer;
}
}
 
namespace pineforge::native_order {
inline namespace native_order_v8 {
 
// Isolated working-request/value core: current LIVE requests and immutable
// command history. It does not own positions, cash, paid fees, matching,
// calendar, host phase, or a second physical book.
//
// Identity types remain native_order_v1. Request/core/event values are v8.
// Physical execution::Action is unchanged; native Reduce uses a typed size
// source instead of a dummy units field. ExecutionPlan is a transient widening
// used at the core/consumer boundary.
 
using Flatten = execution::Flatten;
/// A signed book transaction: finite nonzero units on the side their sign names.
/// It opens, and it closes against a live opposite book on the way, so a
/// transaction larger than an opposite position still opens the remainder. An
/// opening denial rejects the ENTIRE transaction, including that remainder.
using Transact = order_action::Transact;
using HandleVisitor = void (*)(void*, const RequestHandle&);
 
/// A host-maintained, run-scoped roster identity.  Zero is invalid and is
/// never allocated by WorkingRequestCore.
struct CohortHandle {
    std::uint64_t value = 0;
};
inline bool operator==(CohortHandle left, CohortHandle right) noexcept {
    return left.value == right.value;
}
inline bool operator!=(CohortHandle left, CohortHandle right) noexcept {
    return !(left == right);
}
inline bool operator<(CohortHandle left, CohortHandle right) noexcept {
    return left.value < right.value;
}
 
/// Exact target exposure for an explicit reversal request. This is distinct
/// from execution::ReverseTo, which is the transient resolved execution plan.
struct ReverseTo {
    double signed_units = 0.0;
};
 
enum class HostSizedKind : std::uint8_t { Open = 0, Close = 1 };
enum class Side : std::uint8_t { Long = 0, Short = 1 };
/// An opening or a closing whose quantity the HOST resolves, in
/// NativeStrategyHost::resolve_execution_terms. `side` is required for an
/// opening, which must declare where it trades. A host-sized request that reaches
/// a candidate with no units answered is MatchRejectReason::TermsUnresolved. It is
/// the adapter's sizing seam; a bare host that wants the kernel to resolve a cash
/// or equity basis uses Sized instead. The C surface admits HostSized as a cohort
/// close or a Book-scoped WaitForApplied close only (the 1.0 C boundary table).
struct HostSized {
    HostSizedKind kind = HostSizedKind::Open;
    std::optional<Side> side;
};
 
/// Resolved host sizing normally remains subject to the run's quantity grid.
/// A host may instead authenticate literal units for a pure reduction; the
/// consumer still proves that the positive quantity is representable within
/// the selected exposure before it can reach settlement.
enum class ExecutionGridPolicy : std::uint8_t {
    SnapToGrid = 0,
    ExplicitUnits = 1,
};
 
/// Native sizing bases (L3).  The kernel resolves them into units at the
/// sizing point.  A source adapter lowers its own declaration-level default
/// quantity onto them and keeps only its rounding and admission quirks
/// (R5 R2); a host that owns its whole quantity still emits HostSized.
struct CashValue {
    double cash = 0.0;                 // account currency
};
/// A fraction in (0, 1] of MARKED equity at the sizing point. The other SizeBasis
/// alternative, CashValue, is an absolute account-currency amount; both resolve as
/// units = cash / (price * point_value * fx).
struct EquityFraction {
    double fraction = 0.0;             // of marked equity at the sizing point (0.10 = 10 %)
};
/// The two bases a Sized intent may name. Extended only by appending, so an
/// existing aggregate initializer keeps its meaning.
using SizeBasis = std::variant<CashValue, EquityFraction>;
 
/// AtMatch resolves the basis at the matching candidate; AtAcceptance freezes
/// the resolved units when the request is accepted.
enum class SizeTime : std::uint8_t { AtMatch = 0, AtAcceptance = 1 };
 
/// WHICH price the basis is converted at. This is the generic "size against the
/// expected fill price" rule; it names no source language.
///
/// Resolved (today's behaviour) uses the price the kernel would otherwise
/// settle at: the candidate's default resolved price for AtMatch, the raw
/// acceptance-point price for AtAcceptance.
///
/// Signal is the decision-point price at placement -- the current bar's close,
/// or the last print, at submit -- carried to the expected market fill: it is
/// adjusted by the run's slippage for the request's own side
/// (price +/- slippage_ticks * price_tick) and then rounded onto the run's
/// price grid when NativeRunSpec::price_grid is on (HalfUp is the nearest
/// tick; NativePriceGrid::None leaves it unrounded). It is frozen when the
/// request is accepted, so it composes with SizeTime::AtAcceptance and, with
/// SizeTime::AtMatch, the basis still converts at that frozen signal price at
/// every later candidate. A Signal request accepted outside a decision point
/// has no price to freeze and stays unresolvable.
///
/// SignalOnTick is the same decision-point rule measured on the INSTRUMENT's
/// own tick ladder (NativeRunSpec::price_tick) instead of the run's fill grid:
/// the decision price is rounded onto the ladder (nearest tick, ties away from
/// zero), carried to the expected fill by the side's tick slippage, and rounded
/// onto the ladder again. Two rulings are folded into it, both generic:
///
///   * price_tick is the instrument's own resolution and the run already
///     declares it as the slippage multiplier, so a price the market PRINTS
///     lives on that ladder whether or not the run also quantizes the prices it
///     BOOKS. NativeRunSpec::price_grid governs fills; it does not govern what
///     a signal was worth. A run that books unquantized fills can therefore
///     still size against the printed price, which Signal cannot express.
///   * the ladder is applied BEFORE the slippage, not only after. Slippage is
///     a whole number of ticks, so it carries a ladder price to another ladder
///     price: pre-rounding makes `round(p) +/- n*tick` exact and leaves the
///     second rounding a pure binary64 re-normalization, where rounding only
///     after composes two different quantizations of the same print.
///
/// Resolved and Signal are unchanged by this alternative, so every established
/// Sized resolution keeps its value.
enum class SizePrice : std::uint8_t { Resolved = 0, Signal = 1, SignalOnTick = 2 };
 
/// A kernel-sized opening.  units = cash / (price * point_value * fx), where
/// cash is the basis value or fraction * marked equity, and price is the
/// sizing-point price SizePrice names.  A host override of
/// resolve_execution_terms still has the last word: it sees the kernel-resolved
/// units as the facts' RemainingUnits and may return its own.
///
/// SizeTime chooses WHEN the basis is resolved, SizePrice chooses WHICH price
/// it converts at, and the two compose.  Either way the request reaches the
/// candidate with a deferred quantity and exactly one terms pass: the kernel
/// resolves (or republishes the acceptance-frozen) units, publishes them as the
/// facts' RemainingUnits before resolve_execution_terms and
/// validate_execution_precommit run, and uses the host's units when the host
/// returns any.  An acceptance-time quantity is additionally an admission input
/// at placement, so an opening the run cannot admit is
/// RequestRejectReason::PlacementAdmission at submit rather than a rejected
/// candidate later.
struct Sized {
    Side side = Side::Long;
    SizeBasis basis{};
    SizeTime time = SizeTime::AtMatch;
    /// Which price the basis converts at; see SizePrice. Appended after `time`
    /// because Sized has no positional aggregate initializer outside tests that
    /// stop at the basis.
    SizePrice price = SizePrice::Resolved;
    /// SnapToGrid floors the resolved units onto the run's quantity grid.
    /// ExplicitUnits keeps the literal quotient, which the ordinary on-grid
    /// terms gate then refuses when a grid is configured and the quotient is
    /// off it; the two are identical on an ungridded run.
    ExecutionGridPolicy grid_policy = ExecutionGridPolicy::SnapToGrid;
    /// Divide the sizing cash by (1 + fee) when the run's fee kind is
    /// NativeFeeKind::Percent.  Every other fee kind is an exact no-op.
    bool reserve_percent_fee = false;
};
 
/// A reduction of exactly these units, finite and positive. Capped by the live
/// exposure of the scope the reduce is bound to, and floored onto the run's
/// quantity_grid like every other engine quantity.
struct ExplicitUnits {
    double units = 0.0;
};
/// A reduction of exactly what the owner's fill opened, bound at the arm and
/// reported by a QuantityBoundEvent. It is the arm-time size, which is why no
/// SizeTime::AtArm exists.
struct OwnerOpenedUnits {};
/// Gross claims the whole bound scope; NetOfSiblings first subtracts the units
/// already claimed by the live sibling reduces bound to that same scope.  The
/// keys are opaque request/owner handles, never source identifiers.
enum class ScopeClaim : std::uint8_t { Gross = 0, NetOfSiblings = 1 };
/// Which measurement of the bound scope the fraction is taken of. AtMatch (the
/// default) reads the scope as it stands at the matching candidate.
/// AtAcceptance freezes the scope SIZE when the request is accepted -- the
/// placement-time live basis -- so two 50 % siblings on one 10-unit lot both
/// claim 5 under Gross even after the first has already executed. NetOfSiblings
/// then subtracts the live sibling claims from that frozen basis.
enum class ScopeBasis : std::uint8_t { AtMatch = 0, AtAcceptance = 1 };
/// A fraction in (0, 1] of the bound scope, resolved at the matching candidate.
/// The resolution is units = scope * fraction, one binary64 multiplication: a
/// caller that spells its size as a percent converts percent -> fraction
/// itself, so no second rounding step is introduced here.
struct ScopeFraction {
    double fraction = 1.0;
    ScopeClaim claim = ScopeClaim::Gross;
    /// Appended last so every existing aggregate initializer keeps its meaning.
    ScopeBasis basis = ScopeBasis::AtMatch;
};
/// How much a Reduce takes: literal units, the owner's own opening, or a fraction
/// of the bound scope.
using ReductionSize = std::variant<ExplicitUnits, OwnerOpenedUnits, ScopeFraction>;
/// A closing-only intent. It never opens, so it stays legal while the run's
/// opening limits are already exceeded, and it uses CURRENT exposure rather than
/// the acceptance-cycle book. On a flat book it terminalizes a NoEffectEvent: no
/// execution identity, no fill, no fee, no physical action.
struct Reduce {
    ReductionSize size;
};
/// What a request does. Six alternatives: Flatten (quantity-free whole-book
/// close), Reduce (closing only), Transact (a signed book transaction), ReverseTo
/// (an exact signed target exposure), HostSized (the host resolves the quantity)
/// and Sized (the kernel resolves it from a cash or equity basis). The variant's
/// size is pinned by the frozen C++ ABI fixtures, so appending an alternative is
/// an epoch decision.
using OrderIntent = std::variant<Flatten, Reduce, Transact, ReverseTo, HostSized, Sized>;
 
/// Match at the next eligible matching point, with no level to reach. A market
/// request accepted on bar N cannot fill on that bar's already delivered opening.
struct Market {};
/// `fill_through` makes the limit a touch trigger (market-if-touched): the
/// level still gates when the request becomes executable, but its fill is not
/// bounded by the level, so slippage may carry it past the level.
struct Limit {
    double price = 0.0;
    bool fill_through = false;
};
/// A stop trigger: the modeled path has to reach `price` from the adverse side. A
/// crossing books the level itself; a point already past it (a gapped open) books
/// that print. Under a quantizing trigger grid the core re-validates the
/// activation on the same ladder the matcher used, so a hit the matcher reports is
/// never refused.
struct Stop {
    double price = 0.0;
};
/// A stop that, once reached, becomes a limit at `limit`. The stop gates and the
/// limit bounds; an anchored FromOwnerFill level is refused for this trigger,
/// because the anchor materializes one level and this trigger has two.
struct StopLimit {
    double stop = 0.0;
    double limit = 0.0;
};
/// Trail offset spelled in price ticks instead of a price distance. The
/// acceptance path resolves it against the run's price tick, writes the
/// product into Trail::offset and clears the spelling, so a stored definition
/// always carries a plain price distance and can never resolve twice.
struct TrailTicks {
    double ticks = 0.0;
};
/// offset is a price distance: the stop rides `offset` behind the running
/// best. Zero is legal and means "ride the best": the exit is the first
/// adverse move past it. Negative and nonfinite offsets are rejected.
/// arm_price absent means the trail is already armed and starts riding at the
/// first print. Under a FromOwnerFill anchor it means the owner's fill
/// supplies the threshold, which is that anchor's whole point: absent is the
/// anchored spelling, 0.0 is the equivalent placeholder kept legal for hosts
/// that already write it, and any other written level is refused because the
/// arm would overwrite it.
///
/// best_seed is where the running best STARTS, appended last so every existing
/// {offset}, {offset, arm_price} and {offset, arm_price, ticks} initializer
/// keeps its meaning. Absent (the default) is the established behaviour: the
/// best is the arm's own print -- the arm threshold's own ladder point when a
/// crossing armed it, the first print the trail sees when it was submitted
/// already armed. A present seed is a floor on that start: at the arm the best
/// becomes the favourable one of the seed and the arm print (the higher for a
/// sell trail, the lower for a buy trail), so a host whose position already
/// reached a level before this request existed does not restart the ride at a
/// worse print. It is a generic broker shape -- a trail that rides from its
/// activation rather than from the next print -- and the level is the host's
/// own number: the kernel neither derives it nor knows what named it. It is
/// absolute (an anchor moves the arm threshold, never the seed), it must be
/// finite and positive, and under a price grid it is put on the ladder exactly
/// like an observed print. It is folded into the request digest only when
/// present, so every trail without one keeps the digest it had before the
/// field existed.
struct Trail {
    double offset = 0.0;
    std::optional<double> arm_price;
    std::optional<TrailTicks> ticks = std::nullopt;
    std::optional<double> best_seed = std::nullopt;
};
using Trigger = std::variant<Market, Limit, Stop, StopLimit, Trail>;
 
/// How a materialized anchored level is snapped onto the run's price tick
/// ladder (NativeRunSpec::price_tick). Raw keeps `fill + offset` exactly,
/// which is the established behaviour. HalfUp is the nearest tick with ties
/// away from zero. Directional rounds toward the price region the resting leg
/// needs, relative to the leg's trigger kind and side exactly as
/// NativeGridRounding documents it: a buy limit down and a sell limit up, a
/// stop the other way; a trail arm threshold is reached from the favourable
/// side like a limit and rounds like one. Either rounding needs a positive
/// price tick, checked at acceptance exactly like a tick-spelled offset. This
/// is a generic instrument grid: a source language's own trigger projection
/// is not spelled here (a host restates the level through its arm hook).
enum class NativeAnchorRounding : std::uint8_t {
    Raw = 0,
    HalfUp = 1,
    Directional = 2,
};
 
/// Where a request's trigger level comes from. Absolute is the level written
/// in the trigger itself. FromOwnerFill defers it to the owner's fill: the
/// level becomes fill + offset when the owner arms the request, so a bracket
/// leg can be placed before its parent has a price. offset is signed (adverse
/// is negative) and is spelled in price ticks when `ticks` is set; acceptance
/// resolves a tick spelling exactly like TrailTicks, in place, once. The
/// materialized level is then snapped per `rounding`, which is appended last
/// so every existing aggregate initializer keeps its meaning.
struct Absolute {};
/// Defer a level to the owner's fill: at the arm the level becomes fill + offset,
/// with `offset` signed (adverse is negative) and spelled in price ticks when
/// `ticks` is set, then rounded by `rounding`. Legal on Limit and Stop prices and
/// on a Trail arm threshold, and only under a WaitForApplied owner, which is the
/// one relation that arms. Until then the anchored field is left unwritten (0.0
/// for a Limit or Stop price, an absent or 0.0 Trail::arm_price), and the ArmedEvent
/// carries the materialized definition: from then on the request reads as that level.
struct FromOwnerFill {
    double offset = 0.0;
    bool ticks = false;
    NativeAnchorRounding rounding = NativeAnchorRounding::Raw;
};
using TriggerAnchor = std::variant<Absolute, FromOwnerFill>;
 
/// Replacement behaviour that is not expressible in the successor request.
/// retain_trigger_state carries the predecessor's live trigger state (a
/// tracking trail's best, an already active stop) into the successor instead
/// of restarting it; predecessor and successor must hold the same trigger
/// alternative.
///
/// keep_handle re-prices the request in place: the new definition keeps the
/// target's handle, and with it the request's lineage (its predecessor link
/// and chain root) and its dependents -- a child waiting on it keeps waiting,
/// a roster that names it keeps it -- where a plain replace retires the handle
/// and issues a successor. Everything else is the replace: the same checks and
/// refusals, a new immutable definition and birth, a fresh live row (remaining,
/// allowance and trigger state restart unless retain_trigger_state keeps the
/// last), and one ReplacedEvent, whose two definitions share the handle. The
/// re-price takes the number of the run's request sequence a successor's
/// incarnation would have taken, as the definition's priority
/// (RequestDefinition::priority): matching ranks it the newest request, where a
/// successor stands, and the requests after it are numbered as if the replace
/// had issued a handle. No handle is issued under that number.
///
/// keep_binding carries a close's book binding across the replace. A successor
/// that starts unbound (an Independent close) and whose predecessor was bound
/// to the book, or carried such a binding itself, records the binding's cycle
/// and side (RequestDefinition::kept_binding). Where the successor would bind,
/// at its first evaluation, a book that still has that cycle and side binds it
/// with no CloseBoundEvent; any other book binds it, or ends it, exactly as it
/// does a successor that carried nothing. So the option changes the events a
/// run records, never what it matches. Anywhere else it carries nothing.
/// Either option may be given alone.
struct ReplaceOptions {
    bool retain_trigger_state = false;
    bool keep_handle = false;
    bool keep_binding = false;
};
 
/// Take whatever the point allows, with no per-point cap. The default capacity,
/// and the only one the Pine adapter emits.
struct ImmediateRemaining {};
/// Cap what this request may execute at ONE matching point at `units`. Fixed at
/// submit and metered per point — including after an arm — so a request cannot be
/// drained faster than its owner's schedule allows.
struct PointBudget {
    double units = 0.0;
};
using Capacity = std::variant<ImmediateRemaining, PointBudget>;
 
/// Whether an owner-related request that arms is a working order before its
/// arm. Working (the default) is the established book: the request is listed
/// by native_working_requests() from acceptance on. PendingUntilArmed keeps
/// it out of that enumeration until its ArmedEvent; it is still a live
/// request the whole time -- accepted, addressable by handle (replace,
/// cancel, trail_state), counted by cancel_all / cancel_where, and folded
/// into the continuation identity -- and it never matches before the arm
/// under either value. Visibility governs enumeration, not addressing.
enum class NativeArmVisibility : std::uint8_t {
    Working = 0,
    PendingUntilArmed = 1,
};
 
/// When an armed request may first match. The arm happens inside its owner's
/// fill settlement, at the owner's fill print. AtArmPrint (the default) is the
/// established book: the armed request is a candidate at that very cursor, so
/// a level the fill print already satisfies matches at the print. AfterArmPrint
/// gives the armed request the birth rule of a request submitted from the
/// owner's fill callback: on the driver point that armed it, it sees only the
/// path after the print -- a level the print already satisfies does not match
/// there, a later crossing on that point still does -- and from the next
/// driver point on it is an ordinary working request. It governs the level
/// test of a priced trigger (limit, stop, stop-limit, trail arm); a market
/// trigger has no level and is unaffected. Both are broker models: a
/// contingent child that enters the book after its parent's trade cannot
/// trade on that print, a simulated bracket commonly may.
enum class NativeArmFirstMatch : std::uint8_t {
    AtArmPrint = 0,
    AfterArmPrint = 1,
};
 
/// What an armed CLOSING request (Reduce, Flatten, a HostSized close) closes.
/// OwnerLot (the default) is the established relation: the lot its owner's
/// fill opened, and nothing a later add brings. Book binds it, at the arm, to
/// the whole position that fill left -- the very book authority an
/// Independent close submitted from the owner's fill callback acquires -- so
/// a protective leg placed with its entry covers later adds and settles
/// through the book like any other close. A HostSized close may wait for its
/// owner only under Book: the owner-lot relation sizes from the units the
/// owner opened, whereas a book close is sized by the host at the match.
/// A waiting transaction closes nothing, so it must keep OwnerLot.
enum class NativeArmScope : std::uint8_t {
    OwnerLot = 0,
    Book = 1,
};
 
/// No owner: the request stands on its own book authority. Required for Sized, and
/// the default.
struct Independent {};
/// The one owner relation that arms (the ArmedEvent). `visibility`, then
/// `first_match`, then `scope` are appended last so every existing {parent},
/// {parent, visibility} initializer keeps its meaning.
struct WaitForApplied {
    RequestHandle parent;
    NativeArmVisibility visibility = NativeArmVisibility::Working;
    NativeArmFirstMatch first_match = NativeArmFirstMatch::AtArmPrint;
    NativeArmScope scope = NativeArmScope::OwnerLot;
};
/// Bind to ONE already-live opening, by its handle and the positive cycle it is
/// live in. A reduce bound this way closes that lot and nothing a later add
/// brings.
struct BindOpening {
    RequestHandle opening;
    int64_t cycle = 0;
};
/// Immutable membership, independent of a source scratch scope. A successful
/// read changes out; an error leaves it unchanged. No read allocates.
class OpeningReadback {
public:
    virtual ~OpeningReadback() noexcept = default;
    virtual std::uint64_t count() const noexcept = 0;
    virtual detail::ScratchStatus opening_at(
        std::uint64_t index, RequestHandle& out) const noexcept = 0;
};
 
/// Call-local input. Enrollment freezes it before retaining a definition;
/// neither this object nor its callback/context is retained.
class OpeningInputCursor final : public OpeningReadback {
public:
    using Reader = detail::ScratchStatus (*)(void*, std::uint64_t, RequestHandle&);
    OpeningInputCursor(std::uint64_t count, void* context, Reader reader) noexcept
        : count_(count), context_(context), reader_(reader) {}
    std::uint64_t count() const noexcept override { return count_; }
    detail::ScratchStatus opening_at(
        std::uint64_t index, RequestHandle& out) const noexcept override;
private:
    std::uint64_t count_;
    void* context_;
    Reader reader_;
};
 
/// Freeze and canonicalize a same-run, unique stream. Uses bounded workspace
/// and an exclusive unlinked file; failure leaves out unchanged (an allocation
/// failure throws typed out_of_memory). Only creation of the fixed-size owner allocates.
detail::ScratchStatus freeze_openings(
    const RunIdentity&, const OpeningReadback&,
    std::shared_ptr<const OpeningReadback>& out);
 
std::uint64_t opening_count(const std::vector<RequestHandle>&,
                           const OpeningReadback*) noexcept;
detail::ScratchStatus opening_at(const std::vector<RequestHandle>&,
    const OpeningReadback*, std::uint64_t, RequestHandle&) noexcept;
/// Bind to a fixed cohort of already-live openings. Every handle must be unique,
/// nonzero, of this run and physically live in `cycle`; enrollment rejects the
/// ENTIRE request if any member is invalid. The accepted definition keeps the
/// original cohort in canonical handle order even as later retirement narrows the
/// live subset, and execution still closes lots in physical FIFO order.
struct BindOpenings {
    std::vector<RequestHandle> openings;
    int64_t cycle = 0;
    std::shared_ptr<const OpeningReadback> external_openings;
};
/// Bind to a host-built roster (cohort_open / cohort_add / cohort_remove), read at
/// the match rather than frozen at submit. The C surface pairs it with exactly one
/// intent, a host-sized close, whose units the on_close_units hook answers.
struct BindCohort {
    CohortHandle cohort;
};
using Owner = std::variant<Independent, WaitForApplied, BindOpening, BindOpenings, BindCohort>;
 
enum class GroupEffect : std::uint8_t { Cancel = 0, Reduce = 1 };
struct NoGroup {};
struct Member {
    std::uint64_t group = 0;
    std::int64_t cohort = 0;
    GroupEffect effect = GroupEffect::Cancel;
};
using Group = std::variant<NoGroup, Member>;
 
/// Aggregate field order keeps market construction:
///   Request{Transact{1.0}, "buy", "comment"}
///   Request{Flatten{}, "flat", ""}
///   Request{Reduce{ExplicitUnits{3}}, "close", ""}
/// New fields default to Market / ImmediateRemaining / Independent / NoGroup.
/// market_request() converts a physical execution::Action (explicit Reduce
/// units only) into that same market Request. Host market-only methods must
/// reject nondefault extras; they must not drop them.
struct Request {
    OrderIntent intent{};
    std::string label{};
    std::string comment{};
    Trigger trigger = Market{};
    Capacity capacity = ImmediateRemaining{};
    Owner owner = Independent{};
    Group group = NoGroup{};
    TriggerAnchor anchor = Absolute{};
};
 
/// Complete request schema, including owner text and every opening handle.
/// intent/trigger/capacity/owner/group/anchor have an unsigned variant `tag`;
/// label/comment are top-level byte fields. See the production freeze codec.
class RequestReadback final : public detail::PayloadReadback {
public:
    RequestReadback() noexcept = default;
    RequestReadback(const detail::CommandScratchStore& store, detail::ScratchHandle version) noexcept
        : PayloadReadback(store, version, detail::PayloadSchema::request) {}
    explicit RequestReadback(detail::PayloadReadback view) noexcept : PayloadReadback(view) {}
    detail::ScratchStatus label(detail::PayloadField& out) const noexcept {
        return find("label", out);
    }
    detail::ScratchStatus comment(detail::PayloadField& out) const noexcept {
        return find("comment", out);
    }
};
 
inline OrderIntent intent_from_physical(const execution::Action& action) {
    if (std::holds_alternative<execution::Flatten>(action)) return Flatten{};
    if (const auto* transact = std::get_if<order_action::Transact>(&action)) {
        return Transact{transact->signed_units};
    }
    const auto& reduce = std::get<order_action::Reduce>(action);
    return Reduce{ExplicitUnits{reduce.units}};
}
 
inline Request market_request(execution::Action action,
                              std::string label = {},
                              std::string comment = {}) {
    return Request{intent_from_physical(action), std::move(label), std::move(comment)};
}
 
inline bool has_market_defaults(const Request& request) noexcept {
    return std::holds_alternative<Market>(request.trigger)
        && std::holds_alternative<ImmediateRemaining>(request.capacity)
        && std::holds_alternative<Independent>(request.owner)
        && std::holds_alternative<NoGroup>(request.group)
        && std::holds_alternative<Absolute>(request.anchor);
}
 
struct EventId {
    RunIdentity run;
    uint64_t ordinal = 0;
};
 
inline bool operator==(const EventId& a, const EventId& b) {
    return a.ordinal == b.ordinal && a.run == b.run;
}
inline bool operator!=(const EventId& a, const EventId& b) { return !(a == b); }
 
struct MatchCursor {
    NativeCoordinate point{};
    double t = 0.0;
};
 
inline bool operator==(const MatchCursor& a, const MatchCursor& b) noexcept {
    return a.point.ordinal == b.point.ordinal && a.t == b.t
        && a.point.interval_index == b.point.interval_index
        && a.point.effective_time_ms == b.point.effective_time_ms
        && a.point.provenance == b.point.provenance
        && a.point.path_phase == b.point.path_phase;
}
inline bool operator!=(const MatchCursor& a, const MatchCursor& b) noexcept { return !(a == b); }
 
inline std::uint8_t display_waypoint(const MatchCursor& cursor) noexcept {
    return static_cast<std::uint8_t>(cursor.point.path_phase);
}
 
struct RemainingUnbound {};
struct RemainingFlattenAll {};
/// A resolved remaining quantity, in units. The kernel publishes a Sized intent's
/// own resolution here, BEFORE the host's terms hook runs, so an override sees the
/// kernel's number and may answer with a different one.
struct RemainingUnits {
    double q = 0.0;
};
struct RemainingDeferred {};
/// A dynamic cohort has no currently live member.  This is a live deferral,
/// not a terminal receipt: the consumer retries it at the next candidate.
struct NoTarget {};
using Remaining = std::variant<RemainingUnbound, RemainingFlattenAll, RemainingUnits,
                               RemainingDeferred, NoTarget>;
 
struct RemainingProjectionUnbound {};
struct RemainingProjectionFlattenAll {};
struct RemainingProjectionUnits {
    double q = 0.0;
};
struct RemainingProjectionDeferred {};
struct RemainingProjectionNoTarget {};
using RemainingProjection =
        std::variant<RemainingProjectionUnbound, RemainingProjectionFlattenAll,
                     RemainingProjectionUnits, RemainingProjectionDeferred,
                     RemainingProjectionNoTarget>;
 
struct BookTransaction {};
/// The authority an unarmed WaitForApplied child holds: accepted and live, but
/// never a matching candidate until its owner's fill arms it — under either
/// visibility.
struct Wait {
    RequestHandle parent;
};
struct ArmedTransaction {
    RequestHandle parent;
    EventId cause;
    MatchCursor cause_cursor{};
};
struct UnboundBookClose {};
/// The authority an armed leg acquires under NativeArmScope::Book: the whole
/// position its owner's fill left, on this cycle and side, bound at the fill's
/// cursor. It is the same authority an Independent close has, which is what lets a
/// protective leg placed with its entry also cover later adds.
struct BookClose {
    int64_t cycle = 0;
    Side side = Side::Long;
    EventId binding_event;
    MatchCursor binding_cursor{};
};
struct EnrollmentFromCommand {
    EventId accepted;
};
struct EnrollmentFromApplied {
    EventId cause;
    MatchCursor cursor{};
};
using Enrollment = std::variant<EnrollmentFromCommand, EnrollmentFromApplied>;
struct OpeningClose {
    RequestHandle opening;
    int64_t cycle = 0;
    Side side = Side::Long;
    Enrollment enrollment;
};
/// Immutable fixed cohort. Current physical liveness is observed, never stored
/// here; later fragments of an enrolled provenance remain authorized.
struct OpeningsClose {
    std::vector<RequestHandle> openings;
    int64_t cycle = 0;
    Side side = Side::Long;
    Enrollment enrollment;
    std::shared_ptr<const OpeningReadback> external_openings;
};
struct CohortClose {
    CohortHandle cohort;
};
using Authority = std::variant<BookTransaction, Wait, ArmedTransaction, UnboundBookClose, BookClose,
                               OpeningClose, OpeningsClose, CohortClose>;
 
/// Native authorization receipt, converted to a call-local financial
/// SelectedOpeningSet only at the consumer's settlement boundary.
struct SelectedExposure {
    int64_t cycle = 0;
    std::vector<uint64_t> incarnations;
};
/// What one execution acted on: the whole book, one opening's exposure, or a bound
/// selection. Reported on ExecutionAppliedEvent::scope. The financial
/// execution::CloseScope remains the original two-alternative type; this is the
/// native view, and a selected close's committed row range identifies the actual
/// contributors.
using ExecutionScope = std::variant<execution::Book, execution::OpeningExposure, SelectedExposure>;
 
struct MarketReady {};
struct LimitReady {};
struct StopIdle {};
struct StopActive {};
struct StopLimitPending {};
struct StopLimitLive {};
struct TrailWaitArm {};
/// A trail riding its running best. `activation_ordinal` is the ordinal of
/// this request's own TrailArm ActivatedEvent -- NativeTrailState's
/// activation_ordinal, kept in state so it outlives the journal window -- and
/// 0 for a successor that retained its predecessor's tracking
/// (ReplaceOptions::retain_trigger_state), which never armed itself. A
/// re-price that kept the handle (ReplaceOptions::keep_handle) keeps it: that
/// same request armed.
struct TrailTrack {
    double best = 0.0;
    uint64_t activation_ordinal = 0;
};
/// A triggered trail; `activation_ordinal` carries TrailTrack's.
struct TrailActive {
    double best_at_trigger = 0.0;
    uint64_t activation_ordinal = 0;
};
using TriggerState = std::variant<MarketReady, LimitReady, StopIdle, StopActive, StopLimitPending,
                                  StopLimitLive, TrailWaitArm, TrailTrack, TrailActive>;
 
struct AllowanceUnset {};
struct AllowanceUnits {
    uint64_t point_ordinal = 0;
    double initial = 0.0;
    double left = 0.0;
};
struct AllowanceAllScope {
    uint64_t point_ordinal = 0;
};
struct AllowanceDeferred {
    uint64_t point_ordinal = 0;
};
using Allowance = std::variant<AllowanceUnset, AllowanceUnits, AllowanceAllScope,
                               AllowanceDeferred>;
 
struct PendingNone {};
struct PendingDeferred {
    double total = 0.0;
    uint64_t count = 0;
    EventId tail_receipt;
};
using PendingAdjustments = std::variant<PendingNone, PendingDeferred>;
 
struct PositionFlat {};
struct PositionNonflat {
    int64_t cycle = 0;
    Side side = Side::Long;
};
using PositionIdentity = std::variant<PositionFlat, PositionNonflat>;
 
struct OpeningObservation {
    RequestHandle queried_opening;
    int64_t queried_cycle = 0;
    PositionIdentity current_position;
    bool has_live_matching_lot = false;
};
 
/// Borrowed through the enclosing command/evaluation and any prepare/install
/// pair that copies its TargetObservation, including nested reads.
class OpeningObservationReadback {
public:
    virtual ~OpeningObservationReadback() noexcept = default;
    virtual std::uint64_t count() const noexcept = 0;
    virtual detail::ScratchStatus observation_at(
        std::uint64_t index, OpeningObservation& out) const noexcept = 0;
};
 
struct TargetObservation {
    PositionIdentity current_position;
    std::optional<OpeningObservation> opening;
    std::vector<OpeningObservation> openings;
    const OpeningObservationReadback* external_openings = nullptr;
};
 
std::uint64_t opening_observation_count(const TargetObservation&) noexcept;
detail::ScratchStatus opening_observation_at(
    const TargetObservation&, std::uint64_t, OpeningObservation&) noexcept;
 
/// Who authored a request. Host is every request a host submits, replaces or
/// cancels, and it is the whole existing population: it folds nothing into the
/// continuation digest, so no established hash moves. KernelLiquidation marks
/// the margin model's own Reduce or Flatten; KernelRisk marks the Flatten a
/// NativeRiskAction::FlattenAndBlock breach issues at its breach point
/// (native_execution_consumer.cpp, pinned by tests/test_native_risk_limits.cpp).
enum class RequestOrigin : std::uint8_t {
    Host = 0,
    KernelLiquidation = 1,
    KernelRisk = 2,
};
 
/// The immutable accepted form of one request: its handle, the request value as
/// accepted, its birth (acceptance ordinal and decision floor), its origin
/// (RequestOrigin::Host, or the kernel's own for a liquidation or a risk flatten)
/// and its authority. Every event carries a shared pointer to it, so a reader
/// holds the definition the kernel matched against and not a later re-read.
struct RequestDefinition {
    RequestHandle handle;
    Request request;
    Birth birth;
    std::optional<RequestHandle> predecessor;
    /// Appended last so every existing aggregate initializer keeps its meaning.
    RequestOrigin origin = RequestOrigin::Host;
    /// The first handle of this request's replace chain -- the request the
    /// chain began with, which is how a cohort roster names every request of
    /// the chain (cohort_add, cohort_contains). Empty for a request that
    /// replaced nothing: its chain begins with itself. Set by the core at the
    /// replace that creates the definition, from the predecessor's own root,
    /// so it never needs the predecessor's journal events. Appended after
    /// `origin` for the same reason `origin` was.
    std::optional<RequestHandle> root;
    /// Where the definition stands in the run's queue: the number of the
    /// run's request sequence the command that placed it took. Matching
    /// breaks a tie at one cursor oldest number first, and the working book
    /// is held in this order (WorkingRequestCore::live). 0, as every accepted
    /// request and replace successor has it, means the handle's incarnation,
    /// the number its command took; a re-price that kept the handle
    /// (ReplaceOptions::keep_handle) sets the number it took instead. Read it
    /// through LiveRequest::priority. Appended after `root`, like it.
    uint64_t priority = 0;
    /// The book binding a replace carried forward (ReplaceOptions::
    /// keep_binding): the cycle and side of the book its predecessor was bound
    /// to. The request starts unbound, and at its first evaluation a live book
    /// with this cycle and side binds it with no CloseBoundEvent. Empty for
    /// every other definition.
    std::optional<PositionNonflat> kept_binding;
};
using DefinitionRef = std::shared_ptr<const RequestDefinition>;
 
struct LiveRequest {
    DefinitionRef definition;
    Remaining remaining = RemainingUnbound{};
    Authority authority = UnboundBookClose{};
    TriggerState trigger_state = MarketReady{};
    Allowance allowance = AllowanceUnset{};
    PendingAdjustments pending = PendingNone{};
    /// Placement-time sizing measurements frozen from the accepting command
    /// context. Both stay empty for every request that did not ask to freeze
    /// one, and an empty optional folds nothing into the continuation digest.
    std::optional<double> sizing_units;   // SizeTime::AtAcceptance
    std::optional<double> sizing_scope;   // ScopeBasis::AtAcceptance
    std::optional<double> sizing_price;   // SizePrice::Signal / SignalOnTick
 
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
    const std::optional<RequestHandle>& predecessor() const noexcept {
        return definition->predecessor;
    }
    /// Its place in the queue (RequestDefinition::priority): the handle's
    /// incarnation, unless a re-price kept the handle and took a later number.
    uint64_t priority() const noexcept {
        return definition->priority != 0 ? definition->priority : definition->handle.incarnation;
    }
};
 
/// Whether a request may be considered at this driver point: the point's ordinal
/// must be strictly past the birth acceptance ordinal AND its effective time at or
/// past the birth's decision-time lower bound. This is the birth gate — it is why
/// a request accepted on bar N cannot fill on that bar's already delivered
/// opening — and a request born mid-path in on_native_applied is admitted at the
/// current cursor instead, on the unconsumed suffix of that segment.
inline bool point_eligible(const LiveRequest& live,
                           uint64_t point_ordinal,
                           int64_t effective_time_ms) noexcept {
    return point_eligible(live.birth(), point_ordinal, effective_time_ms);
}
 
/// v2 exact binary64 grid: r=abs(q)/s, n=round(r) half away from zero, g=n*s.
/// Intermediates finite, 1<=n<=2^53, abs(abs(q)-g) <= 4*ulp(max(abs(q),abs(g)))
/// and < s/2. ulp is nextafter toward +inf. Does not rewrite q.
inline bool quantity_on_grid(double q, double step) noexcept {
    if (!std::isfinite(q) || !std::isfinite(step) || step <= 0.0) return false;
    const double abs_q = std::abs(q);
    const double r = abs_q / step;
    if (!std::isfinite(r)) return false;
    const double n = std::round(r);
    if (!std::isfinite(n) || n < 1.0 || n > 0x1p53) return false;
    const double g = n * step;
    if (!std::isfinite(g)) return false;
    const double err = std::abs(abs_q - g);
    const double span = std::max(abs_q, std::abs(g));
    const double ulp = std::nextafter(span, std::numeric_limits<double>::infinity()) - span;
    const double ulp_bound = 4.0 * ulp;
    const double half_step = step / 2.0;
    if (!std::isfinite(err) || !std::isfinite(ulp_bound) || !std::isfinite(half_step))
        return false;
    return err <= ulp_bound && err < half_step;
}
 
/// Why an acceptance was refused, on a Rejected SubmitResult. These are decided at
/// submit, before any request record exists: an invalid quantity or basis, an
/// off-grid quantity, an owner the intent may not take, a trigger spelling the run
/// cannot resolve, or a frozen quantity the run's own opening admission refuses
/// (PlacementAdmission).
enum class RequestRejectReason : std::uint8_t {
    InvalidQuantity = 0,
    OffGrid = 1,
    InvalidTrigger = 2,
    InvalidCapacity = 3,
    InvalidOwner = 4,
    InvalidQuantityBasis = 5,
    InvalidGroup = 6,
    /// A Sized{SizeTime::AtAcceptance} whose acceptance-resolved quantity does
    /// not pass the run's opening admission (allowed directions, max_abs_units,
    /// max_open_lots, initial margin) at the sizing price.
    PlacementAdmission = 7,
};
 
enum class SubmitStatus { Accepted, Rejected };
enum class ReplaceStatus { Replaced, ReplaceRejected, NotWorking, InvalidHandle };
enum class CancelStatus { Cancelled, NotWorking, InvalidHandle };
 
/// What submit answers. Accepted carries a timeline ordinal and a RequestHandle
/// (session, run, incarnation); Rejected carries a rejection ordinal, no handle
/// and a reason. Acceptance is not a fill: no lot, no cash and no fee moves here,
/// and the ordinary fill appears later as an ExecutionAppliedEvent on the same
/// command history.
struct SubmitResult {
    SubmitStatus status = SubmitStatus::Rejected;
    uint64_t event_ordinal = 0;
    std::optional<RequestHandle> handle;
    std::optional<RequestRejectReason> reason;
};
 
struct ReplaceResult {
    ReplaceStatus status = ReplaceStatus::InvalidHandle;
    uint64_t event_ordinal = 0;
    std::optional<RequestHandle> successor;
    std::optional<RequestRejectReason> reason;
};
 
struct CancelResult {
    CancelStatus status = CancelStatus::InvalidHandle;
    uint64_t event_ordinal = 0;
};
 
/// Why a CANDIDATE was refused at a matching point. Every refusal is terminal:
/// the MatchRejectedEvent ends the request, and a host that still wants it
/// submits again. OpeningDirection, MaxAbsUnits, MaxOpenLots, InitialMargin and
/// RiskLimit are the run's admission gates; TermsUnresolved is a host-sized or
/// basis-sized quantity that could not be resolved; NoOppositeExposure and
/// InvalidTerms are shapes the answered terms cannot take;
/// UnrepresentableQuantity is a quantity the settlement cannot book exactly on
/// the book it met.
enum class MatchRejectReason : std::uint8_t {
    NonpositivePrice = 0,
    OpeningDirection = 1,
    MaxAbsUnits = 2,
    MaxOpenLots = 3,
    InitialMargin = 4,
    TermsUnresolved = 5,
    InvalidTerms = 6,
    NoOppositeExposure = 7,
    HostPrecommit = 8,
    /// An opening refused while the run spec's generic risk limits are
    /// blocking (L9). Reduces never reach this gate.
    RiskLimit = 9,
    /// The settlement's inspection answered execution::Status::
    /// UnrepresentableQuantity: a close split binary64 cannot hold (a rest
    /// below half an ulp of the lot it ends in, a whole lot that cannot
    /// decrement the rest or move the running sum), a reduction or transaction
    /// the position absorbs, or an opening the surviving book absorbs; or the
    /// request core cannot take the fill off the request's own units
    /// (CoreFailure::NonrepresentableQuantity: a scope of dust closed by a far
    /// larger request, a point budget too small to move its remaining units);
    /// or what an off-grid Reduce the grid admitted as a FIFO boundary of its
    /// scope settles no longer closes whole lots of the book it meets
    /// (CommandContext::units_are_scope_boundary). The request ends here,
    /// nothing moves, and the run goes on; the settlement's and the core's
    /// cases stopped the whole run before the representable-quantity refusal change.
    UnrepresentableQuantity = 10,
};
 
/// Which price a candidate is being offered at: the point's own price, or the
/// request's trigger level (a crossing that books the level itself). A host reads
/// it off the terms facts, and the trail suites read it back off the applied event
/// to tell a level fill from a path fill.
enum class NativeCandidatePriceKind : std::uint8_t {
    PointPrice = 0,
    TriggerLevel = 1,
    CurrentQuote = 2,
};
 
enum class OpeningShape : std::uint8_t {
    Transact = 0,
    ReverseTo = 1,
    CloseOpposite = 2,
};
 
struct ExecutionTerms {
    double resolved_price = 0.0;
    std::optional<double> units;
    OpeningShape shape = OpeningShape::Transact;
    ExecutionGridPolicy grid_policy = ExecutionGridPolicy::SnapToGrid;
};
 
/// The settlement shape one execution takes. Derived by the kernel from the intent
/// and the answered terms; a host never constructs it.
using ExecutionPlan = std::variant<execution::Flatten, order_action::Reduce,
                                   order_action::Transact, execution::ReverseTo>;
 
inline ExecutionPlan to_execution_plan(const execution::Action& action) {
    return std::visit([](const auto& alternative) -> ExecutionPlan {
        return alternative;
    }, action);
}
 
struct TermsResolvedInput {
    NativeCandidatePriceKind price_kind = NativeCandidatePriceKind::PointPrice;
    bool shared_cursor_collision = false;
    double raw_price = 0.0;
    double default_resolved_price = 0.0;
    ExecutionTerms terms;
};
 
/// Why a request left the book. Host is an explicit cancel; Group an OCA sibling's
/// effect; OwnerGone a parent that was rejected, replaced or cancelled, which ends
/// its waiting children; Superseded the kernel withdrawing its own liquidation
/// before re-pricing it. Every reason is carried on a CancelledEvent.
enum class CancelReason : std::uint8_t {
    User = 0,
    Group = 1,
    OwnerGone = 2,
    UnsupportedRelation = 3,
    /// A kernel-originated request the kernel itself withdrew: the liquidation
    /// level or its units moved, or the requirement is no longer breached.
    Superseded = 4,
};
 
enum class AppliedTerminalReason : std::uint8_t {
    WorkingUnitsSatisfied = 0,
    Flattened = 1,
    TargetExhausted = 2,
};
 
enum class ActivationKind : std::uint8_t {
    Stop = 0,
    StopLimit = 1,
    TrailArm = 2,
    TrailTrigger = 3,
};
 
enum class CoreFailure : std::uint8_t {
    Invariant = 0,
    InvalidCause = 1,
    NonrepresentableQuantity = 2,
    MissingObservation = 3,
    StaleHandle = 4,
    UnsupportedTransition = 5,
    ConflictingReceipt = 6,
    /// A group deduction's pending total that overflows binary64 (or a
    /// non-finite reservation, which a valid run does not reach). A deduction
    /// binary64 cannot take off its recipient is absorbed instead (the
    /// absorbed-deduction rule); it failed the run with this discriminator before.
    UnrepresentableReservation = 7,
    InvalidScope = 8,
    InvalidProposal = 9,
    ObservationMismatch = 10,
};
 
enum class DriverEligibilityClass : std::uint8_t {
    ObservedPrint = 0,
    CarriedOpen = 1,
    TickAfterCalculation = 2,
    ConfirmedOpen = 3,
    ConfirmedExcursion = 4,
    ConfirmedAfterCalculationClose = 5,
    CurrentExecution = 6,
};
 
enum class CommandSurface : std::uint8_t { General = 0, MarketOnly = 1 };
 
/// One request was accepted: the definition, and the timeline ordinal it was
/// accepted at. The first event of every request's history.
struct AcceptedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    CommandSurface surface = CommandSurface::General;
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
};
 
struct RejectedEvent {
    uint64_t ordinal = 0;
    Request request;
    RequestRejectReason reason = RequestRejectReason::InvalidQuantity;
    CommandSurface surface = CommandSurface::General;
};
 
struct ReplacedEvent {
    uint64_t ordinal = 0;
    DefinitionRef predecessor_definition;
    DefinitionRef successor_definition;
    CommandSurface surface = CommandSurface::General;
    const RequestHandle& predecessor() const noexcept { return predecessor_definition->handle; }
    const Request& predecessor_request() const noexcept { return predecessor_definition->request; }
    const RequestHandle& successor() const noexcept { return successor_definition->handle; }
    const Request& successor_request() const noexcept { return successor_definition->request; }
    const Birth& successor_birth() const noexcept { return successor_definition->birth; }
    /// Whether the replace kept the handle (ReplaceOptions::keep_handle): the
    /// successor definition is the same request re-priced, and only such a
    /// definition carries a priority of its own.
    bool kept_handle() const noexcept { return successor_definition->priority != 0; }
};
 
struct ReplaceRejectedEvent {
    uint64_t ordinal = 0;
    DefinitionRef live_definition;
    Request attempted;
    RequestRejectReason reason = RequestRejectReason::InvalidQuantity;
    CommandSurface surface = CommandSurface::General;
    const RequestHandle& target() const noexcept { return live_definition->handle; }
    const Request& live_request() const noexcept { return live_definition->request; }
};
 
struct CancelledEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    CancelReason reason = CancelReason::User;
    std::optional<EventId> cause;
    Authority prior_authority = UnboundBookClose{};
    RemainingProjection unexecuted = RemainingProjectionUnbound{};
    PendingAdjustments pending = PendingNone{};
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
};
 
struct NotWorkingEvent {
    uint64_t ordinal = 0;
    RequestHandle target;
    std::optional<Request> attempted;
    CommandSurface surface = CommandSurface::General;
};
 
struct InvalidHandleEvent {
    uint64_t ordinal = 0;
    RequestHandle target;
    std::optional<Request> attempted;
    CommandSurface surface = CommandSurface::General;
};
 
/// A reduction or a flatten that had nothing to close: terminal, with no execution
/// identity, no fill, no fee and no physical action. It is an outcome, not a
/// failure.
struct NoEffectEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    RemainingProjection remaining = RemainingProjectionUnbound{};
    Authority authority = UnboundBookClose{};
    MatchCursor cursor{};
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
};
 
/// One candidate's execution terms, recorded. For a request whose units were
/// deferred it also binds them: it spends the pending group chain
/// (`prior_adjustment_ids`, `pending_total`), takes `effective_deduction` off the
/// resolved units and leaves `remaining_after`. That deduction is 0 with a
/// positive `pending_total` and positive resolved units when binary64 cannot
/// take the total off them -- absorbed, and the units stand (the absorbed-deduction rule).
struct TermsResolvedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    MatchCursor cursor{};
    TermsResolvedInput input;
    std::vector<EventId> prior_adjustment_ids;
    double pending_total = 0.0;
    double effective_deduction = 0.0;
    RemainingProjection remaining_before = RemainingProjectionDeferred{};
    RemainingProjection remaining_after = RemainingProjectionUnits{};
    Allowance allowance_after = AllowanceUnset{};
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
};
 
/// A candidate the run refused, with its MatchRejectReason and the cursor it was
/// refused at. It carries an event ordinal but no execution identity, and it is
/// the request's last event: every match refusal erases the live request.
struct MatchRejectedEvent {
    uint64_t ordinal = 0;
    MatchRejectReason reason = MatchRejectReason::OpeningDirection;
    DefinitionRef definition;
    RemainingProjection remaining = RemainingProjectionUnbound{};
    Authority authority = UnboundBookClose{};
    MatchCursor cursor{};
    std::optional<ExecutionTerms> attempted_terms;
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
};
 
struct CloseBoundEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    int64_t cycle = 0;
    Side side = Side::Long;
    MatchCursor cursor{};
    Authority before = UnboundBookClose{};
    Authority after = UnboundBookClose{};
};
 
struct ActivatedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    ActivationKind kind = ActivationKind::Stop;
    TriggerState before = StopIdle{};
    TriggerState after = StopActive{};
    double reached_price = 0.0;
    MatchCursor cursor{};
};
 
/// One committed execution: the definition, the cursor, the resolved price and
/// units, the scope it acted on, the committed closed-row range, the cycle on
/// either side, and the ticket it booked under. Delivered to on_native_applied and
/// recorded in native_events(); the account observation that follows it shares its
/// ordinal.
struct ExecutionAppliedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    double raw_price = 0.0;
    double resolved_price = 0.0;
    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;
    double closed_units = 0.0;
    double opened_units = 0.0;
    double filled_working = 0.0;
    RemainingProjection remaining_before = RemainingProjectionUnbound{};
    RemainingProjection remaining_after = RemainingProjectionUnbound{};
    Allowance allowance_before = AllowanceUnset{};
    Allowance allowance_after = AllowanceUnset{};
    bool terminal = true;
    std::optional<AppliedTerminalReason> terminal_reason;
    int64_t cycle_before = 0;
    int64_t cycle_after = 0;
    ExecutionScope scope = execution::Book{};
    MatchCursor cursor{};
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
    const Birth& birth() const noexcept { return definition->birth; }
    int64_t effective_time_ms() const noexcept { return cursor.point.effective_time_ms; }
    int64_t interval_open_ms() const noexcept { return cursor.point.open_ms; }
    int64_t interval_last_traded_close_ms() const noexcept {
        return cursor.point.last_traded_close_ms;
    }
    int interval_index() const noexcept { return cursor.point.interval_index; }
    std::uint8_t provenance() const noexcept {
        return static_cast<std::uint8_t>(cursor.point.provenance);
    }
};
 
/// A group effect's deduction from a live sibling whose remaining units are
/// known (GroupEffect::Reduce): `requested_delta` is the member fill's
/// `filled_working`, `actual_deduction` the part taken -- capped at `before`,
/// which then cancels the sibling -- and `after` is fl(before -
/// actual_deduction). A deduction binary64 cannot take off `before` (at most
/// half an ulp of it: fl(before - d) is `before`) is absorbed (the absorbed-deduction rule):
/// `actual_deduction` is 0 and `after` equals `before`, the exact binary64
/// result, and the member's fill stands. A deduction that is taken is positive,
/// so an `actual_deduction` of 0 names an absorbed one.
struct ReservationReducedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    EventId cause;
    RequestHandle recipient;
    GroupEffect effect = GroupEffect::Reduce;
    double requested_delta = 0.0;
    double actual_deduction = 0.0;
    RemainingUnits before{};
    RemainingProjection after = RemainingProjectionUnits{};
};
 
/// A group effect's deduction deferred into a sibling whose units are not known
/// yet: its pending total grows by `deferred_delta`, in commit order, and the
/// receipts chain back through `previous_pending_receipt` until the terms or
/// the owner fill that binds the sibling's units takes the total off them. A
/// fill the total cannot move (fl(total + fill) is the total) is absorbed (R5
/// lane K-ULP5): `deferred_delta` is 0, `pending_after` is `pending_before` and
/// the event joins no chain. A total below half an ulp of a later fill rounds
/// into it, as binary64 addition does.
struct DeferredGroupAdjustmentEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    EventId cause;
    RequestHandle recipient;
    GroupEffect effect = GroupEffect::Reduce;
    double deferred_delta = 0.0;
    PendingAdjustments pending_before = PendingNone{};
    PendingDeferred pending_after{};
    std::optional<EventId> previous_pending_receipt;
};
 
/// A Reduce{OwnerOpenedUnits} was bound, at its owner's fill, to what that fill
/// opened. It is how a bracket child's size becomes a number, and it precedes the
/// ArmedEvent of the same drain. `effective_deduction` is the part of the child's
/// pending group total taken off `source_units`; it is 0 with a positive
/// `pending_total` when binary64 cannot take that total off them -- absorbed, and
/// the recipient's units stand (the absorbed-deduction rule).
struct QuantityBoundEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    EventId source;
    double source_units = 0.0;
    std::vector<EventId> prior_adjustment_ids;
    double pending_total = 0.0;
    double effective_deduction = 0.0;
    RemainingProjection remaining = RemainingProjectionUnits{};
};
 
/// An anchored leg was materialized, exactly once: fill + offset, then the
/// rounding, then resolve_anchored_level, then the representability check, and the
/// resulting level written into the leg's trigger with its anchor becoming
/// Absolute. Every later reader — the live book, the C working rows, matching —
/// sees that level. Under NativeArmScope::Book it also carries the BookClose the
/// leg acquired.
struct ArmedEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    Authority before = Wait{};
    Authority after = ArmedTransaction{};
    Enrollment enrollment = EnrollmentFromApplied{};
    std::optional<EventId> quantity_resolution;
};
 
/// A kernel-issued liquidation that actually filled. It carries the margin
/// facts of that fill, so a host reconstructs the outcome without recomputing
/// the account: `mark` is the booked resolved price, `equity` and `required`
/// are the marked equity and the maintenance requirement of the SURVIVING book
/// at that price, `liquidation_price` is the level re-solved for what is left,
/// and `position_before` / `position_after` are the signed book on either side
/// of the reduction. `applied` names the ExecutionAppliedEvent that booked it.
struct MarginCallEvent {
    uint64_t ordinal = 0;
    DefinitionRef definition;
    EventId applied;
    MatchCursor cursor{};
    Side side = Side::Long;
    double mark = 0.0;
    double equity = 0.0;
    double required = 0.0;
    double liquidation_price = 0.0;
    double units = 0.0;
    double position_before = 0.0;
    double position_after = 0.0;
    const RequestHandle& handle() const noexcept { return definition->handle; }
    const Request& request() const noexcept { return definition->request; }
};
 
/// Which generic risk limit of NativeRunSpec::risk a NativeRiskEvent reports.
enum class RiskLimitKind : std::uint8_t {
    MaxDrawdown = 0,
    MaxIntradayLoss = 1,
    MaxConsecutiveLossDays = 2,
    MaxFillsPerDay = 3,
};
 
/// One generic risk limit breaching (L9). It is not bound to a request: the
/// block it opens is an account fact, so this event carries no definition.
/// `limit` is the threshold in the unit the breach was measured in — account
/// currency for the two loss limits (a percent limit is already resolved
/// against its basis equity here), days or fills for the two counts — and
/// `observed` is the measured value that reached it. `day_ordinal` is the
/// risk day the breach happened on, on the spec's own day basis, and `cursor`
/// is the point it was measured at.
struct NativeRiskEvent {
    uint64_t ordinal = 0;
    RiskLimitKind kind = RiskLimitKind::MaxDrawdown;
    double limit = 0.0;
    double observed = 0.0;
    std::int64_t day_ordinal = 0;
    MatchCursor cursor{};
};
 
/// Every alternative of one request's history, as one value. native_events()
/// returns them as the NativeEventKind::Command rows, and
/// strategy_native_events_v1 flattens the same set into one tagged POD. The
/// variant's size is pinned by the frozen C++ ABI fixtures.
using CommandEvent = std::variant<AcceptedEvent,
                                  RejectedEvent,
                                  ReplacedEvent,
                                  ReplaceRejectedEvent,
                                  CancelledEvent,
                                  NotWorkingEvent,
                                  InvalidHandleEvent,
                                  NoEffectEvent,
                                  MatchRejectedEvent,
                                  ExecutionAppliedEvent,
                                  CloseBoundEvent,
                                  ActivatedEvent,
                                  ReservationReducedEvent,
                                  DeferredGroupAdjustmentEvent,
                                  QuantityBoundEvent,
                                  ArmedEvent,
                                  TermsResolvedEvent,
                                  MarginCallEvent,
                                  NativeRiskEvent>;
 
class JournalRecordSource final : public detail::ScratchByteSource {
public:
    explicit JournalRecordSource(const CommandEvent&) noexcept;
    std::uint64_t size() const noexcept override { return length_; }
    detail::ScratchStatus read(std::uint64_t, detail::ScratchBuffer) const noexcept override;
private:
    const CommandEvent* event_;
    std::uint64_t length_ = 0;
    detail::ScratchStatus status_ = detail::ScratchStatus::ok;
};
JournalRecordSource encode_journal_record(const CommandEvent&) noexcept;
// Owning decode is an explicit diagnostic surface; an allocation failure throws typed out_of_memory.
detail::ScratchStatus decode_journal_record(const detail::ScratchByteSource&,
    detail::ScratchBuffer, CommandEvent&);
class WorkingRequestCore;
void bind_journal_codec(WorkingRequestCore&, detail::CommandScratchStore&);
detail::ScratchStatus append_journal_record(WorkingRequestCore&,
    const detail::ScratchByteSource&) noexcept;
const detail::ScratchReadback& journal_readback(const WorkingRequestCore&);
 
/// Almost every prepared command yields one history event. Keep that ordinary
/// transactional payload inline; the overflow vector preserves the existing
/// arbitrary-length behavior for group/lifecycle plans that emit more events.
class InlineCommandEvents {
public:
    InlineCommandEvents() = default;
    InlineCommandEvents(InlineCommandEvents&& other) noexcept : size_(other.size_) {
        for (std::size_t i = 0; i < size_ && i < inline_.size(); ++i) {
            inline_[i] = std::move(other.inline_[i]);
        }
        overflow_ = std::move(other.overflow_);
        other.size_ = 0;
    }
    InlineCommandEvents& operator=(InlineCommandEvents&& other) noexcept {
        if (this != &other) {
            clear();
            size_ = other.size_;
            for (std::size_t i = 0; i < size_ && i < inline_.size(); ++i) {
                inline_[i] = std::move(other.inline_[i]);
            }
            overflow_ = std::move(other.overflow_);
            other.size_ = 0;
        }
        return *this;
    }
    InlineCommandEvents(const InlineCommandEvents& other) : size_(other.size_) {
        for (std::size_t i = 0; i < size_ && i < inline_.size(); ++i) {
            inline_[i] = other.inline_[i];
        }
        overflow_ = other.overflow_;
    }
    InlineCommandEvents& operator=(const InlineCommandEvents& other) {
        if (this != &other) {
            clear();
            size_ = other.size_;
            for (std::size_t i = 0; i < size_ && i < inline_.size(); ++i) {
                inline_[i] = other.inline_[i];
            }
            overflow_ = other.overflow_;
        }
        return *this;
    }
 
    std::size_t size() const noexcept { return size_; }
    bool empty() const noexcept { return size_ == 0; }
 
    template<class Event>
    void emplace_back(Event&& event) {
        push_back(CommandEvent(std::forward<Event>(event)));
    }
 
    void push_back(CommandEvent event) {
        if (overflow_.empty() && size_ < inline_.size()) {
            inline_[size_++].emplace(std::move(event));
            return;
        }
        if (overflow_.empty()) {
            overflow_.reserve(inline_.size() * 2U);
            for (std::size_t i = 0; i < size_; ++i) {
                overflow_.push_back(std::move(*inline_[i]));
                inline_[i].reset();
            }
        }
        overflow_.push_back(std::move(event));
        ++size_;
    }
 
    void clear() noexcept {
        for (std::size_t i = 0; i < size_ && i < inline_.size(); ++i) {
            inline_[i].reset();
        }
        overflow_.clear();
        size_ = 0;
    }
 
    CommandEvent& front() noexcept { return (*this)[0]; }
    const CommandEvent& front() const noexcept { return (*this)[0]; }
    CommandEvent& operator[](std::size_t index) noexcept {
        return overflow_.empty() ? *inline_[index] : overflow_[index];
    }
    const CommandEvent& operator[](std::size_t index) const noexcept {
        return overflow_.empty() ? *inline_[index] : overflow_[index];
    }
 
private:
    std::array<std::optional<CommandEvent>, 2> inline_{};
    std::vector<CommandEvent> overflow_{};
    std::size_t size_ = 0;
};
 
/// What acceptance needs from the run to judge a command: the point's ordinal and
/// coordinate, the price tick the tick spellings resolve against, the quantity
/// grid, and the live book. Built by the consumer; a host never constructs one.
struct CommandContext {
    int64_t decision_time_ms = 0;
    std::optional<double> quantity_grid;
    std::optional<OpeningObservation> opening;
    CommandSurface surface = CommandSurface::General;
    std::vector<OpeningObservation> openings;
    /// Kernel-resolved acceptance-time units for a Sized{AtAcceptance} request.
    /// The execution consumer owns the account facts, so it supplies them here;
    /// a producer that leaves it unset accepts the request with a size the
    /// matching path then reports as TermsUnresolved.  The accepted request
    /// carries the value in LiveRequest::sizing_units and still reaches the
    /// candidate with a deferred remaining, so the host keeps its one override
    /// pass.  Appended last so the existing positional aggregate initializers
    /// keep their meaning.
    std::optional<double> sizing_units;
    /// The run's price tick, needed only to resolve a tick-spelled trail
    /// offset or trigger anchor. A tick spelling without a usable tick here is
    /// rejected rather than silently read as a price distance.
    std::optional<double> price_tick;
    /// Placement-time sizing measurements the execution consumer owns, supplied
    /// only for the intent that asks for them. Appended last, exactly like
    /// sizing_units, so the existing positional aggregate initializers keep
    /// their meaning.
    ///
    /// sizing_scope: the bound scope's exposure at acceptance, for a
    ///   Reduce{ScopeFraction{ScopeBasis::AtAcceptance}}.
    /// sizing_price: the frozen signal price, for a Sized whose SizePrice is
    ///   Signal or SignalOnTick.
    /// sizing_admissible: false when the acceptance-resolved quantity of a
    ///   Sized{SizeTime::AtAcceptance} fails the run's placement admission.
    std::optional<double> sizing_scope;
    std::optional<double> sizing_price;
    bool sizing_admissible = true;
    /// A Reduce's ExplicitUnits are a FIFO boundary of its scope: the binary64
    /// sum, in book order, of the scope's lots through one of them -- the head
    /// lot's own size, a prefix, the whole scope. Such a quantity is on the
    /// quantity grid whatever the grid predicate answers: these are the book's
    /// own quantities, which settlement arithmetic can move off any decimal
    /// grid; closing them takes whole lots and splits none (the representable-quantity refusal change).
    /// The execution consumer measures it at submit, for a request of
    /// ImmediateRemaining capacity; its candidate settles what then remains
    /// only on the grid, at a boundary of the scope as it stands or at least at
    /// its held total, and refuses anything else (MatchRejectReason::
    /// UnrepresentableQuantity). Appended last, like the members above.
    bool units_are_scope_boundary = false;
    const OpeningObservationReadback* external_openings = nullptr;
};
 
struct EvaluationContext {
    MatchCursor cursor{};
    DriverEligibilityClass driver_class = DriverEligibilityClass::ObservedPrint;
    bool existing_matching_bit = false;
    /// Generic current-point delivery. At Open, the consumer sets this only for
    /// a market/immediate request born by the pre-open provider. On a continuous
    /// OHLC segment, it also admits a request born by an applied callback onto
    /// the unconsumed suffix. It is transient and never retained in a request.
    bool pre_open_birth_eligible = false;
    /// Set only while resolving a CohortClose candidate.  It carries the
    /// physical side of the currently live selected roster and is not retained
    /// in a request definition.
    std::optional<Side> cohort_side;
};
 
/// The one policy point of an anchored materialization. The core knows it
/// only as a callable over its own values: the leg's live row, the owner's
/// fill, the leg's side, the resolved offset (price units) and the kernel
/// level after the anchor rounding. It is consulted exactly once per
/// materialization, before the ArmedEvent is built, so the ArmedEvent and
/// every later reader see the installed level. A returned value is the level
/// to install (the kernel's representability check still applies and a
/// failure is the existing PreparationError path); nullopt keeps the kernel
/// level. An empty callable is exactly the pre-hook behaviour.
using AnchoredLevelResolver = std::function<std::optional<double>(
        const LiveRequest& leg, const ExecutionAppliedEvent& owner_fill, Side leg_side,
        double offset, double kernel_level)>;
 
/// What the consumer hands to prepare_owner_applied for an anchored leg's
/// materialization, the way acceptance receives CommandContext::price_tick.
/// price_tick is the ladder a rounded anchor snaps to; an anchor whose
/// rounding is Raw never reads it. resolve_level is the host's restatement,
/// carried as a value so the core stays host-free.
struct ArmContext {
    std::optional<double> price_tick;
    AnchoredLevelResolver resolve_level;
};
 
struct BeginTrailTracking {
    MatchCursor cursor{};
    double reached_price = 0.0;
};
struct ObserveTrailExtremum {
    MatchCursor cursor{};
    double reached_price = 0.0;
};
struct ActivateStop {
    MatchCursor cursor{};
    double reached_price = 0.0;
};
struct ActivateStopLimit {
    MatchCursor cursor{};
    double reached_price = 0.0;
};
struct ActivateTrail {
    MatchCursor cursor{};
    double reached_price = 0.0;
};
using TriggerTransition = std::variant<BeginTrailTracking, ObserveTrailExtremum, ActivateStop,
                                       ActivateStopLimit, ActivateTrail>;
 
/// What the consumer hands to prepare_trigger under an opted-in price grid
/// (NativeRunSpec::price_grid == QuantizeFillsAndTriggers), the way acceptance
/// receives CommandContext::price_tick: the tick ladder and the rounding the
/// matcher tested the activation on. The core then re-validates the reached
/// print with the same grid arithmetic (L8b ruling: under that grid the
/// tick-quantized print IS the reached price, so a hit the matcher reports is
/// never refused), records the quantized print as the activation's reached
/// price, and keeps a trail's running best on the ladder. A default-constructed
/// value (no ladder) is exactly the raw compare and the raw print every
/// activation used before. Host-free: values only.
///
/// ladder_tick is a different question, appended last so every existing
/// aggregate initializer keeps its meaning: the run's DECLARED price tick
/// (NativeRunSpec::price_tick), whatever the quantization mode. Nothing is
/// tested or rounded on it; it is the ladder a level spelled in ticks names,
/// so a trailing stop a whole number of ticks from a best on that ladder is
/// the ladder point it names rather than the subtraction's ULP-off neighbour
/// (native_matching::ladder_trail_stop, the integer-tick trailing stop). Zero leaves the raw
/// arithmetic, which is what a run with no declared tick has.
struct ActivationGrid {
    double price_tick = 0.0;  // finite and positive when a ladder is in force
    bool half_up = true;      // nearest tick, ties away from zero; else directional
    double ladder_tick = 0.0; // the run's own price tick, quantized or not
};
 
struct ExecutionProposal {
    MatchCursor cursor{};
    /// Carries the generic pre-open delivery authorization from the matching
    /// evaluation through the synchronous execution preparation.
    bool pre_open_birth_eligible = false;
    double raw_price = 0.0;
    double resolved_price = 0.0;
    ExecutionPlan physical_action{};
    ExecutionScope scope = execution::Book{};
    PositionIdentity pre_fill = PositionFlat{};
    double inspected_closed_units = 0.0;
    double inspected_opened_units = 0.0;
    double inspected_current_ticket = 0.0;
    TargetObservation pre_target{};
};
 
struct CommittedExecutionFacts {
    execution::Result result{};
    int64_t cycle_before = 0;
    int64_t cycle_after = 0;
    TargetObservation post_target{};
    ExecutionPlan committed_action{};
};
 
/// Where an install put its events: `first_index` is an ABSOLUTE journal
/// position -- the count of events the run committed before them -- so it
/// stays valid when the front of the journal is retired
/// (WorkingRequestCore::history_at reads it back).
struct EventRange {
    std::size_t first_index = 0;
    std::size_t count = 0;
};
 
struct Installed {
    EventRange events{};
};
 
enum class InstallError : std::uint8_t {
    StalePreparation = 0,
    WrongCoreOrRun = 1,
    AlreadyConsumed = 2,
};
 
using InstallResult = std::variant<Installed, InstallError>;
 
enum class NoChangeReason : std::uint8_t {
    NoTransition = 0,
    StillWaiting = 1,
    NotEligible = 2,
    NotWorking = 3,
    AlreadyApplied = 4,
};
 
struct NoChange {
    NoChangeReason reason = NoChangeReason::NoTransition;
};
 
/// A working-request preparation that could not produce a representable
/// instruction — a nonrepresentable quantity, most often. Reported as a settlement
/// failure, which fails the run: it is a contract breach, not a refused candidate.
struct PreparationError {
    CoreFailure code = CoreFailure::Invariant;
    EventId cause;
    RequestHandle target;
};
 
template <class T>
using Preparation = std::variant<T, NoChange, PreparationError>;
 
template <class R>
struct CommandInstalled {
    R result{};
    EventRange events{};
};
 
template <class R>
using InstalledCommand = std::variant<CommandInstalled<R>, InstallError>;
 
class PreparedSubmit;
class PreparedReplace;
class PreparedCancel;
class PreparedMutation;
class PreparedExecution;
 
struct EligibilityFacts {
    bool birth_ok = false;
    bool waiting = false;
    bool driver_ok = false;
    bool needs_close_bind = false;
    bool ready_to_match = false;
    Side position_side = Side::Long;
    bool is_buy = false;
    const Trigger* trigger = nullptr;
    const TriggerState* trigger_state = nullptr;
    const Remaining* remaining = nullptr;
    const Allowance* allowance = nullptr;
    const Authority* authority = nullptr;
};
 
struct CohortRoster {
    CohortHandle handle{};
    /// Canonical origin handles, ordered by origin incarnation rather than by
    /// host insertion order.  A successor is normalized to its predecessor
    /// root before entering this table.
    std::vector<RequestHandle> origins;
};
 
enum class CohortReceiptOperation : std::uint8_t { Add = 0, Remove = 1 };
enum class CohortReceiptStatus : std::uint8_t {
    Applied = 0,
    InvalidHandle = 1,
    UnknownOrigin = 2,
    TerminalOrigin = 3,
};
struct CohortReceipt {
    CohortReceiptOperation operation = CohortReceiptOperation::Add;
    CohortReceiptStatus status = CohortReceiptStatus::InvalidHandle;
    CohortHandle cohort{};
    RequestHandle origin{};
};
 
/// One group-effect receipt: the applied event that caused it, the request it
/// acted on, the effect, and the ordinal of the event that recorded the
/// outcome. A drain that meets the same cause, recipient and effect again finds
/// it and applies nothing (WorkingRequestCore::group_effect_receipt).
struct GroupEffectReceipt {
    EventId cause{};
    RequestHandle recipient{};
    GroupEffect effect = GroupEffect::Reduce;
    uint64_t outcome_ordinal = 0;
};
 
/// Payload row policy for pending batches and committed-row read caches.
/// Shared line metadata is additional; retained history/backing admission are
/// independent. Zero disables optional residency. One fixed pending record
/// per store remains so prepared installation cannot allocate or do I/O.
struct TailWindowConfig {
    std::size_t successor_root_rows = 64;
    std::size_t receipt_rows = 64;
    std::size_t chain_segment_rows = 16;
};
 
/// Storage observations only, excluded from continuation state.
struct TailWindowStats {
    std::size_t successor_root_capacity_rows = 0;
    std::size_t receipt_capacity_rows = 0;
    std::size_t chain_index_capacity_rows = 0;
    std::uint64_t successor_root_reads = 0;
    std::uint64_t receipt_reads = 0;
    std::uint64_t chain_index_reads = 0;
    std::uint64_t chain_id_reads = 0;
    std::uint64_t successor_root_read_bytes = 0;
    std::uint64_t receipt_read_bytes = 0;
    std::uint64_t chain_index_read_bytes = 0;
    std::size_t successor_root_pending_bytes = 0;
    std::size_t receipt_pending_bytes = 0;
    std::size_t chain_index_pending_bytes = 0;
    std::size_t successor_root_control_bytes = 0;
    std::size_t receipt_control_bytes = 0;
    std::size_t chain_index_control_bytes = 0;
};
 
enum class TailWindowKind { successor_roots, receipts, chain_segments };
 
class WorkingRequestCore {
public:
    class CohortView;
    class JournalView;
    class LiveView;
    explicit WorkingRequestCore(RunIdentity identity);
    WorkingRequestCore(RunIdentity identity, TailWindowConfig windows);
    /// Inclusive committed-row read-cache allowances. Pending write batches
    /// keep their internal defaults, independently of these optional caches.
    WorkingRequestCore(RunIdentity identity, CacheCapacity successor_roots,
                       CacheCapacity receipts, CacheCapacity chain_segments);
    TailWindowConfig tail_window_config() const noexcept;
    TailWindowStats tail_window_stats() const noexcept;
    detail::ReadThroughCacheStats tail_read_cache_stats(TailWindowKind kind) const noexcept;
    WorkingRequestCore(const WorkingRequestCore&) = delete;
    WorkingRequestCore& operator=(const WorkingRequestCore&) = delete;
    /// Move transfers the complete run. The source becomes empty/unbound;
    /// commands throw invalid_argument without mutation until reset rebinds it.
    /// Self move-assignment preserves the current run.
    WorkingRequestCore(WorkingRequestCore&& other) noexcept;
    WorkingRequestCore& operator=(WorkingRequestCore&& other) noexcept;
    void set_successor_roots_directory(const std::string& directory); // After reset, before the first spill; empty uses TMPDIR or /tmp.
    void bind_scratch_slab(const std::shared_ptr<::pineforge::detail::ScratchSlab>& slab);
    void reset(RunIdentity identity);
 
    const RunIdentity& identity() const noexcept { return identity_; }
    /// The working book, in queue order: ascending LiveRequest::priority,
    /// which is incarnation order until a re-price keeps a handle
    /// (ReplaceOptions::keep_handle) and takes its request to the back.
    /// The book is a read view (LiveView). Up to a fixed bound its rows are
    /// resident; a larger book keeps its newest rows outside the heap, in an
    /// external ordered table, and the view reads them back in queue order.
    /// A row the view hands out stays valid until the next few spilled rows it
    /// reads or the next command; a command that targets a row outside the
    /// heap brings that row back first.
    LiveView live() const noexcept;
    /// How many requests are live, resident or not, in O(1); and the request
    /// at queue rank `rank` (std::out_of_range when none).
    std::size_t live_size() const noexcept;
    const LiveRequest& live_at(std::size_t rank) const;
    /// Whether some live rows are outside the heap: live_at and live_back
    /// then walk the book in queue order instead of indexing it.
    bool book_spilled() const noexcept { return spilled_count() != 0; }
    /// The command journal's retained window, oldest first. Commits append at
    /// the back and retire_history drops a prefix, so the window holds the
    /// absolute journal positions [history_base(), history_end()). A core
    /// nothing retires -- every core its consumer runs under a retaining
    /// policy -- keeps the whole journal and history_base() stays 0.
    /// The window is a read view (JournalView): its newest events are resident
    /// and its older ones, past a fixed resident bound, live in external
    /// pages that the view reads back through a fixed page cache. A reference
    /// it hands out stays valid until the next few page loads or the next
    /// command; copy an event that must outlive them.
    JournalView history() const noexcept;
    /// How many events have been retired from the front of the journal.
    std::size_t history_base() const noexcept { return history_base_; }
    /// The absolute journal length: every event this run has committed,
    /// retained or not. EventRange::first_index counts in this space.
    std::size_t history_end() const noexcept;
    /// The event at an absolute journal position; std::out_of_range when it
    /// is not retained.
    const CommandEvent& history_at(std::size_t absolute) const;
    /// Retire the journal prefix whose ordinals are <= through_ordinal. It
    /// stops ahead of the first event a live request still reads -- the head
    /// of a deferred group-adjustment chain (collect_pending_chain) -- and
    /// drops group-effect keys whose causes are <= retired_through(). The
    /// consumer must fold those keys first; queued applied notifications pin
    /// their causes. Live rows, logical counters and cohort rosters do not
    /// move. Answers the number of journal events retired.
    std::size_t retire_history(uint64_t through_ordinal);
    /// The ordinal of the newest retired event, 0 while none is.
    uint64_t retired_through() const noexcept { return retired_through_; }
    /// Logical roster sequence in allocation order, including empty rosters
    /// whose members have been removed. Walking allocates nothing and does
    /// no I/O; empty rows are synthesized from the dense handle sequence.
    CohortView cohorts() const noexcept;
    /// The retained cohort-receipt window, in command order. Its absolute
    /// positions are [cohort_receipt_base(), cohort_receipt_count()). A
    /// standalone core retains all rows until its reader retires them; the
    /// Window consumer retires each row after folding it into its digest.
    const std::vector<CohortReceipt>& cohort_receipts() const noexcept {
        return cohort_receipts_;
    }
    std::size_t cohort_receipt_base() const noexcept { return cohort_receipts_base_; }
    /// Every cohort receipt this run committed, retained or not.
    std::size_t cohort_receipt_count() const noexcept {
        return cohort_receipts_base_ + cohort_receipts_.size();
    }
    /// Drop the prefix strictly below the absolute position through, clamped
    /// to the window. The reader must have folded these rows first. Does not
    /// change rosters, command counters, prepared-command validity or totals.
    std::size_t retire_cohort_receipts(std::size_t through) noexcept;
    /// The core's two durable counters: the ordinal of the last committed
    /// event and the last incarnation a command consumed. A later command must
    /// exceed both.
    uint64_t last_ordinal() const noexcept { return last_ordinal_; }
    uint64_t last_incarnation() const noexcept { return last_incarnation_; }
    /// Group-effect keys in cause/commit order, retaining [base, count).
    /// Count is the total ever committed; base advances with retire_history.
    /// A cause's recipients stay in drain/queue order, even after keep_handle
    /// re-pricing. Older-than-newest causes are InvalidCause unless replayed.
    /// A retired index asserts in Debug and throws out_of_range otherwise.
    /// Only the newest few keys are resident: the rest of the retained window
    /// is read back from an external fixed-record log, so a pinned journal
    /// (a live deferred chain) no longer grows the heap with its receipts.
    std::size_t group_effect_receipt_base() const noexcept;
    std::size_t group_effect_receipt_count() const noexcept;
    GroupEffectReceipt group_effect_receipt(std::size_t index) const;
    /// The prior adjustment ids a TermsResolvedEvent or QuantityBoundEvent
    /// spent, in chain order, as a paged contract: `visit` is called once per
    /// id until it answers false. A chain of up to kInlineAdjustmentIds links
    /// is in the event's own prior_adjustment_ids exactly as before; a longer
    /// one is not copied into the event (a vector of every id would be O(chain
    /// length) in the event and in its prepared token) but kept in an external
    /// list this call reads back in fixed pages. Answers false when
    /// `resolution` names no such event in the retained window.
    bool visit_prior_adjustments(const EventId& resolution,
                                 const std::function<bool(const EventId&)>& visit) const;
    /// How many prior adjustment ids that event spent (0 when none or unknown).
    std::size_t prior_adjustment_count(const EventId& resolution) const;
    /// The longest chain whose ids an event still carries inline.
    static constexpr std::size_t kInlineAdjustmentIds = 256;
    /// The incarnations this run issued -- every accepted request and every
    /// replace successor -- as disjoint ascending [first, last] ranges: the
    /// half of the chain index that tells a request that ended from one that
    /// never existed. Read-only; a consumer issues one dense range.
    const std::vector<std::pair<uint64_t, uint64_t>>& issued_incarnations() const noexcept {
        return issued_;
    }
    const LiveRequest* find_live(const RequestHandle& handle) const;
    /// find_live for a reader that keeps the row across further reads of the
    /// book. A spilled row's copy lives as long as the answer does, whatever
    /// the book reads next; a resident row's answer owns nothing and, like
    /// find_live's, stays valid until the next command. Null when no live
    /// request has the handle.
    std::shared_ptr<const LiveRequest> hold_live(const RequestHandle& handle) const;
    /// A read of the book's spilled rows that failed where its reader cannot
    /// throw (a noexcept fold of the book): the reader hands the failure here
    /// and answers true, and from then on every read of the spilled rows and
    /// every command that moves one throws it again -- an I/O failure as the
    /// typed scratch failure (scratch_io_failed) -- until reset. False, with
    /// nothing kept, when the book has never spilled: it then has no such read.
    bool carry_book_read_failure(std::exception_ptr failure) const noexcept;
    /// Throws the failure carry_book_read_failure kept, if any.
    void rethrow_book_read_failure() const;
    /// How many spilled rows the book has read back to answer a lookup -- by
    /// handle (find_live, hold_live), by rank (live_at, live_back) -- and how
    /// many table steps those lookups walked, since this core was built or
    /// reset. A walk of live() in queue order is not counted, nor is a read of
    /// a row at the table entry such a walk found it at (the matcher reusing a
    /// row it scanned): neither searches the book. Diagnostics only: nothing
    /// folds them and no decision reads them.
    struct BookLookupReads {
        std::uint64_t rows = 0;
        std::uint64_t steps = 0;
    };
    BookLookupReads book_lookup_reads() const noexcept;
    const CommandEvent* event_at(const EventId& id) const;
 
    /// Command-boundary roster maintenance.  A rejected add/remove records a
    /// durable generic receipt but never emits a market event.
    CohortHandle cohort_open();
    void cohort_add(CohortHandle cohort, RequestHandle origin);
    void cohort_remove(CohortHandle cohort, RequestHandle origin);
    bool cohort_contains(CohortHandle cohort, const RequestHandle& opening) const;
 
    /// R1 producer convenience: prepare then install one command. Bound opening
    /// enrollment requires CommandContext observations via prepare_submit.
    SubmitResult submit(const Request& request,
                        int64_t decision_time_ms,
                        uint64_t& next_order_incarnation,
                        uint64_t& next_timeline_ordinal,
                        std::optional<double> quantity_grid = std::nullopt);
 
    ReplaceResult replace(const RequestHandle& target,
                          const Request& request,
                          int64_t decision_time_ms,
                          uint64_t& next_order_incarnation,
                          uint64_t& next_timeline_ordinal,
                          std::optional<double> quantity_grid = std::nullopt,
                          ReplaceOptions options = {});
 
    CancelResult cancel(const RequestHandle& target, uint64_t& next_timeline_ordinal);
 
    /// Consumer-only typed prepare/install. Prepare may reserve storage and
    /// invalidate live/history references; it does not change logical state.
    /// Tokens are move-only, bound to this instance/run/epoch, and do not
    /// survive another prepare/install, reset, or move.
    PreparedSubmit prepare_submit(const Request& request,
                                  const CommandContext& context,
                                  uint64_t& next_order_incarnation,
                                  uint64_t& next_timeline_ordinal,
                                  RequestOrigin origin = RequestOrigin::Host);
    PreparedReplace prepare_replace(const RequestHandle& target,
                                    const Request& request,
                                    const CommandContext& context,
                                    uint64_t& next_order_incarnation,
                                    uint64_t& next_timeline_ordinal,
                                    ReplaceOptions options = {});
    /// `reason` lets the kernel withdraw its own request under the durable
    /// Superseded receipt. Host cancels keep the default User reason.
    PreparedCancel prepare_cancel(const RequestHandle& target, uint64_t& next_timeline_ordinal,
                                  CancelReason reason = CancelReason::User);
 
    InstalledCommand<SubmitResult> install_submit(PreparedSubmit&& prepared) noexcept;
    InstalledCommand<ReplaceResult> install_replace(PreparedReplace&& prepared) noexcept;
    InstalledCommand<CancelResult> install_cancel(PreparedCancel&& prepared) noexcept;
 
    Preparation<PreparedMutation> prepare_evaluation(const RequestHandle& target,
                                                     const EvaluationContext& context,
                                                     const TargetObservation& observation,
                                                     uint64_t& next_timeline_ordinal);
    /// The same preparation under an explicit open activation grant: the caller
    /// vouches, for this handle alone, that the request is to be read as born
    /// before this point. The grant satisfies only the strict ordinal half of
    /// the birth gate, and only at an Open cursor whose effective time is not
    /// before the request's decision-time lower bound. It relaxes no time floor
    /// and no trigger, driver, quantity, margin or price check, it leaves the
    /// other birth exceptions as they stand, and it gives
    /// EvaluationContext::pre_open_birth_eligible no new meaning (that bool stays
    /// market/immediate only). Nothing retains it -- no request, plan or prepared
    /// token -- so every call that tests the gate takes it afresh; the check and
    /// the apply of an execution each do. The form above is this one with the
    /// grant false.
    Preparation<PreparedMutation> prepare_evaluation(const RequestHandle& target,
                                                     const EvaluationContext& context,
                                                     const TargetObservation& observation,
                                                     uint64_t& next_timeline_ordinal,
                                                     bool open_activation_grant);
    /// `grid` carries the run's activation grid (ActivationGrid); the default
    /// is the raw rule, so every existing caller keeps its meaning.
    Preparation<PreparedMutation> prepare_trigger(const RequestHandle& target,
                                                  const TriggerTransition& transition,
                                                  DriverEligibilityClass driver_class,
                                                  uint64_t& next_timeline_ordinal,
                                                  std::optional<Side> cohort_side = std::nullopt,
                                                  const ActivationGrid& grid = {});
    /// prepare_trigger under the open activation grant of prepare_evaluation: the
    /// cursor test every trigger transition makes (Stop, StopLimit and Trail
    /// activation among them) takes the grant too. Every parameter is explicit,
    /// so no earlier call can resolve to this form.
    Preparation<PreparedMutation> prepare_trigger(const RequestHandle& target,
                                                  const TriggerTransition& transition,
                                                  DriverEligibilityClass driver_class,
                                                  uint64_t& next_timeline_ordinal,
                                                  std::optional<Side> cohort_side,
                                                  const ActivationGrid& grid,
                                                  bool open_activation_grant);
    InstallResult install_mutation(PreparedMutation&& prepared) noexcept;
 
    Preparation<PreparedExecution> prepare_execution(const RequestHandle& target,
                                                     const ExecutionProposal& proposal,
                                                     uint64_t& next_timeline_ordinal);
    /// prepare_execution under the open activation grant of prepare_evaluation.
    /// The token holds no grant: install_execution does not read the birth gate.
    Preparation<PreparedExecution> prepare_execution(const RequestHandle& target,
                                                     const ExecutionProposal& proposal,
                                                     uint64_t& next_timeline_ordinal,
                                                     bool open_activation_grant);
    InstallResult install_execution(PreparedExecution&& prepared,
                                    const CommittedExecutionFacts& facts) noexcept;
    Preparation<PreparedMutation> prepare_no_effect(const RequestHandle& target,
                                                    const EvaluationContext& context,
                                                    uint64_t& next_timeline_ordinal);
    Preparation<PreparedMutation> prepare_match_rejected(const RequestHandle& target,
                                                         const EvaluationContext& context,
                                                         MatchRejectReason reason,
                                                         uint64_t& next_timeline_ordinal);
    Preparation<PreparedMutation> prepare_match_rejected(
            const RequestHandle& target,
            const EvaluationContext& context,
            MatchRejectReason reason,
            std::optional<ExecutionTerms> attempted_terms,
            uint64_t& next_timeline_ordinal);
    Preparation<PreparedMutation> prepare_terms(const RequestHandle& target,
                                                 const EvaluationContext& context,
                                                 const TermsResolvedInput& input,
                                                 uint64_t& next_timeline_ordinal);
 
    /// Append one MarginCallEvent to the immutable history. The target is the
    /// kernel-originated request that filled, which is already terminal by the
    /// time its margin facts are recorded, so no live row moves.
    Preparation<PreparedMutation> prepare_margin_call(const MarginCallEvent& event,
                                                      uint64_t& next_timeline_ordinal);
 
    /// Append one NativeRiskEvent to the immutable history. It names an
    /// account-level breach rather than a request, so it moves no live row and
    /// carries no definition; the kernel's own response (an opening block, and
    /// with FlattenAndBlock a KernelRisk Flatten) is separate from the record.
    Preparation<PreparedMutation> prepare_risk_event(const NativeRiskEvent& event,
                                                     uint64_t& next_timeline_ordinal);
 
    /// The allowance that prepare_evaluation would install for this point.
    static Allowance evaluated_allowance(const LiveRequest& live, uint64_t point) noexcept;
    /// Consumer-only no-event form of the ordinary allowance
    /// refresh. It preserves prepare_evaluation's eligibility and liveness
    /// checks while avoiding a transient mutation envelope per driver point.
    void refresh_point_allowances(uint64_t point, const PositionIdentity& position);
    bool refresh_allowance(const RequestHandle& target,
                           const EvaluationContext& context,
                           const TargetObservation& observation);
    /// refresh_allowance under the open activation grant of prepare_evaluation.
    bool refresh_allowance(const RequestHandle& target,
                           const EvaluationContext& context,
                           const TargetObservation& observation,
                           bool open_activation_grant);
    /// The same refresh, handed the run's timeline: an unbound close that
    /// carried a binding the book still has (ReplaceOptions::keep_binding) is
    /// bound here too, to the BookClose its CloseBoundEvent would install, and
    /// takes that event's ordinal without recording it. The form above leaves
    /// every unbound close to the evaluation.
    bool refresh_allowance(const RequestHandle& target,
                           const EvaluationContext& context,
                           const TargetObservation& observation,
                           uint64_t& next_timeline_ordinal);
    /// The timeline-handed refresh under the open activation grant.
    bool refresh_allowance(const RequestHandle& target,
                           const EvaluationContext& context,
                           const TargetObservation& observation,
                           uint64_t& next_timeline_ordinal,
                           bool open_activation_grant);
    bool refresh_cohort_allowance(const RequestHandle& target,
                                  const EvaluationContext& context,
                                  const TargetObservation& observation);
    /// Pure arithmetic over the cached pending total. Outputs are assigned only
    /// after every validation and subtraction succeeds. A total binary64 cannot
    /// take off the resolved units is absorbed: the deduction is 0 and the
    /// units stand (the absorbed-deduction rule).
    static bool effective_host_units(const PendingAdjustments& pending,
                                     double resolved_units,
                                     double* deduction,
                                     double* after,
                                     bool* exhausted) noexcept;
 
    void reserve(std::size_t expected_events);
    /// The live siblings an applied member's fill reaches -- its group, another
    /// cohort, born before the fill; none for a fill with no effect, such as a
    /// Cancel member's nonterminal one -- in queue order (live()): a request
    /// re-priced with its handle kept stands behind every sibling accepted or
    /// re-priced before it, where a plain replace's successor stands (the
    /// stable group-recipient ordering).
    std::vector<RequestHandle> group_recipients(const EventId& applied) const;
    std::vector<RequestHandle> waiting_children(const RequestHandle& parent) const;
    bool has_waiting_children(const RequestHandle& parent) const;
    std::vector<RequestHandle> bound_close_handles() const;
    /// The same three lists written over `out`, whose capacity a caller that
    /// keeps it reuses (the direct request-core forms): the same handles in the same order.
    void group_recipients(const EventId& applied, std::vector<RequestHandle>& out) const;
    void waiting_children(const RequestHandle& parent, std::vector<RequestHandle>& out) const;
    void bound_close_handles(std::vector<RequestHandle>& out) const;
    /// Synchronous queue-order reads. Callbacks may read the core or write a
    /// separate scratch store; they must not mutate this core.
    void visit_group_recipients(const EventId&, void*, HandleVisitor) const;
    void visit_waiting_children(const RequestHandle&, void*, HandleVisitor) const;
    void visit_bound_close_handles(void*, HandleVisitor) const;
 
    Preparation<PreparedMutation> prepare_group_effect(const EventId& applied,
                                                       const RequestHandle& recipient,
                                                       uint64_t& next_timeline_ordinal);
    /// `arm` carries the materialization facts of an anchored leg (the price
    /// tick a rounded anchor snaps to, the host's level restatement); a
    /// default-constructed value is exactly the pre-lane behaviour, so every
    /// existing caller keeps its meaning.
    Preparation<PreparedMutation> prepare_owner_applied(
            const EventId& applied,
            const RequestHandle& child,
            const std::optional<OpeningObservation>& observation,
            uint64_t& next_timeline_ordinal,
            const ArmContext& arm = {});
    Preparation<PreparedMutation> prepare_bound_expiry(const EventId& physical_cause,
                                                       const RequestHandle& child,
                                                       const TargetObservation& observation,
                                                       uint64_t& next_timeline_ordinal);
    Preparation<PreparedMutation> prepare_parent_terminal(const EventId& terminal_or_replaced,
                                                          const RequestHandle& child,
                                                          uint64_t& next_timeline_ordinal);
 
    /// The direct forms (the direct request-core forms). Each apply_* makes the checks of the
    /// prepare_* it is named after, in the same order, and answers what that
    /// prepare_* followed at once by its install answers: the same NoChange or
    /// PreparationError, the same exception at the same point with nothing
    /// changed, and otherwise the same events at the same absolute journal
    /// positions, the same live rows, receipts, chain index and counters, and a
    /// token prepared before it just as stale. What it does not do is stage:
    /// no token, plan or row copy stands between the checks and the write --
    /// the live row is updated where it stands and each event is appended
    /// once. A caller that installs what it prepares straight away uses these;
    /// the prepare/install pairs stay for a caller that holds a token across
    /// other work, or that may decide not to install (an anchored arm whose
    /// restatement hook failed). An execution's direct form comes in the two
    /// halves its caller needs around the settlement it proposes:
    /// check_execution makes prepare_execution's checks and its seal (the same
    /// NoChange, PreparationError or exception, the same reservation and
    /// epoch) and holds nothing; apply_execution, after the settlement, makes
    /// them again and then does what install_execution does with the token
    /// prepare_execution would have made. A caller changes nothing in the core
    /// between the two; if the checks no longer pass, apply_execution answers
    /// StalePreparation and writes nothing.
    CommandInstalled<SubmitResult> apply_submit(const Request& request,
                                                const CommandContext& context,
                                                uint64_t& next_order_incarnation,
                                                uint64_t& next_timeline_ordinal,
                                                RequestOrigin origin = RequestOrigin::Host);
    CommandInstalled<ReplaceResult> apply_replace(const RequestHandle& target,
                                                  const Request& request,
                                                  const CommandContext& context,
                                                  uint64_t& next_order_incarnation,
                                                  uint64_t& next_timeline_ordinal,
                                                  ReplaceOptions options = {});
    CommandInstalled<CancelResult> apply_cancel(const RequestHandle& target,
                                                uint64_t& next_timeline_ordinal,
                                                CancelReason reason = CancelReason::User);
    Preparation<Installed> apply_evaluation(const RequestHandle& target,
                                            const EvaluationContext& context,
                                            const TargetObservation& observation,
                                            uint64_t& next_timeline_ordinal);
    /// apply_evaluation under the open activation grant of prepare_evaluation.
    Preparation<Installed> apply_evaluation(const RequestHandle& target,
                                            const EvaluationContext& context,
                                            const TargetObservation& observation,
                                            uint64_t& next_timeline_ordinal,
                                            bool open_activation_grant);
    Preparation<Installed> apply_trigger(const RequestHandle& target,
                                         const TriggerTransition& transition,
                                         DriverEligibilityClass driver_class,
                                         uint64_t& next_timeline_ordinal,
                                         std::optional<Side> cohort_side = std::nullopt,
                                         const ActivationGrid& grid = {});
    /// apply_trigger under the open activation grant of prepare_evaluation; every
    /// parameter is explicit, like prepare_trigger's grant form.
    Preparation<Installed> apply_trigger(const RequestHandle& target,
                                         const TriggerTransition& transition,
                                         DriverEligibilityClass driver_class,
                                         uint64_t& next_timeline_ordinal,
                                         std::optional<Side> cohort_side,
                                         const ActivationGrid& grid,
                                         bool open_activation_grant);
    Preparation<Installed> apply_no_effect(const RequestHandle& target,
                                           const EvaluationContext& context,
                                           uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_match_rejected(const RequestHandle& target,
                                                const EvaluationContext& context,
                                                MatchRejectReason reason,
                                                std::optional<ExecutionTerms> attempted_terms,
                                                uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_terms(const RequestHandle& target,
                                       const EvaluationContext& context,
                                       const TermsResolvedInput& input,
                                       uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_margin_call(const MarginCallEvent& event,
                                             uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_risk_event(const NativeRiskEvent& event,
                                            uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_group_effect(const EventId& applied,
                                              const RequestHandle& recipient,
                                              uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_owner_applied(const EventId& applied,
                                               const RequestHandle& child,
                                               const std::optional<OpeningObservation>& observation,
                                               uint64_t& next_timeline_ordinal,
                                               const ArmContext& arm = {});
    Preparation<Installed> apply_bound_expiry(const EventId& physical_cause,
                                              const RequestHandle& child,
                                              const TargetObservation& observation,
                                              uint64_t& next_timeline_ordinal);
    Preparation<Installed> apply_parent_terminal(const EventId& terminal_or_replaced,
                                                 const RequestHandle& child,
                                                 uint64_t& next_timeline_ordinal);
    Preparation<std::monostate> check_execution(const RequestHandle& target,
                                                const ExecutionProposal& proposal,
                                                uint64_t& next_timeline_ordinal);
    /// check_execution and apply_execution under the open activation grant of
    /// prepare_evaluation. The two make the same birth test, so a caller hands
    /// both the grant its scope holds; an apply given a different one answers
    /// StalePreparation like any check that no longer passes.
    Preparation<std::monostate> check_execution(const RequestHandle& target,
                                                const ExecutionProposal& proposal,
                                                uint64_t& next_timeline_ordinal,
                                                bool open_activation_grant);
    InstallResult apply_execution(const RequestHandle& target,
                                  const ExecutionProposal& proposal,
                                  const CommittedExecutionFacts& facts,
                                  uint64_t& next_timeline_ordinal);
    InstallResult apply_execution(const RequestHandle& target,
                                  const ExecutionProposal& proposal,
                                  const CommittedExecutionFacts& facts,
                                  uint64_t& next_timeline_ordinal,
                                  bool open_activation_grant);
 
    EligibilityFacts eligibility_facts(const LiveRequest& live,
                                       const EvaluationContext& context) const noexcept;
    /// eligibility_facts and evaluation_eligible under the open activation grant
    /// of prepare_evaluation: the grant can only set birth_ok.
    EligibilityFacts eligibility_facts(const LiveRequest& live,
                                       const EvaluationContext& context,
                                       bool open_activation_grant) const noexcept;
    bool evaluation_eligible(const LiveRequest& live,
                             const EvaluationContext& context) const noexcept;
    bool evaluation_eligible(const LiveRequest& live,
                             const EvaluationContext& context,
                             bool open_activation_grant) const noexcept;
    bool trigger_permits_driver(const Trigger& trigger,
                                const TriggerState& state,
                                DriverEligibilityClass driver_class,
                                bool existing_matching_bit) const noexcept;
    bool working_is_buy(const LiveRequest& live,
                        std::optional<Side> cohort_side = std::nullopt) const noexcept;
    /// Borrow the rosters holding origins, in ascending cohort-handle order.
    /// No copies or allocation; use only until the next cohort mutation.
    const std::map<std::uint64_t, CohortRoster>& nonempty_cohorts() const noexcept {
        return cohorts_;
    }
 
private:
    enum class TargetKind { Live, NotWorking, InvalidHandle };
    // Native-private bridge. The existing opaque journal owns the resource;
    // this borrow ends at reset/move/destruction, like its other core reads.
    const detail::NativeHistoryOwner* managed_history_owner() const noexcept;
    friend void bind_journal_codec(WorkingRequestCore&, detail::CommandScratchStore&);
    friend detail::ScratchStatus append_journal_record(WorkingRequestCore&,
        const detail::ScratchByteSource&) noexcept;
    friend const detail::ScratchReadback& journal_readback(const WorkingRequestCore&);
    friend class PreparedSubmit;
    friend class PreparedReplace;
    friend class PreparedCancel;
    friend class PreparedMutation;
    friend class PreparedExecution;
    // The matcher reuses a row it scanned outside the heap through the place
    // its walk found the row at (book_generation, hold_scanned below).
    friend class ::pineforge::engine_script_run_v20::NativeExecutionConsumer;
 
    static void require_identity(const RunIdentity& identity);
    static void require_grid(std::optional<double> quantity_grid);
    static void require_distinct_counters(uint64_t& next_order_incarnation,
                                          uint64_t& next_timeline_ordinal);
    std::optional<RequestRejectReason> validate_request(
            const Request& request,
            const CommandContext& context,
            const std::optional<RequestHandle>& replace_target) const;
    /// Resolves tick-spelled trail offsets and trigger anchors in place
    /// against context.price_tick. Runs after validate_request, on the staged
    /// copy that becomes the stored definition.
    static std::optional<RequestRejectReason> resolve_tick_spellings(
            Request& request, const CommandContext& context);
    LiveRequest make_live(DefinitionRef definition,
                          const CommandContext& context,
                          EventId accepted) const;
    enum class ReceiptLookup : std::uint8_t { Absent = 0, Present = 1, Conflict = 2 };
    /// What a chain walk keeps of the chain's ids besides its total: the ids
    /// of a chain of up to kInlineAdjustmentIds links, in chain order, or --
    /// for a longer one -- where the walk wrote them (an external list of
    /// 8-byte ordinals), so no vector of every id is ever built.
    struct ChainIds {
        std::vector<EventId> inline_ids;
        uint64_t count = 0;
        bool external = false;
        uint64_t offset = 0;
    };
    /// Walks the live deferred chain `pending` back from its tail, checking
    /// every link, then replays it forward in commit order to reproduce the
    /// total's exact accumulation. False on any link that does not check.
    bool collect_pending_chain(const PendingAdjustments& pending,
                               const RequestHandle& recipient,
                               ChainIds* ids,
                               double* total);
    ReceiptLookup receipt_lookup(const EventId& cause, const RequestHandle& recipient,
                                 GroupEffect effect, uint64_t* outcome) const;
    bool authenticate_receipt_outcome(const CommandEvent& event, const EventId& cause,
                                      const RequestHandle& recipient, GroupEffect effect) const;
    /// The first retained group-effect key whose cause is above `retired`
    /// (the end of the keys when none): the base retire_history moves to. Reads
    /// the external log, so it may throw; apply_receipt_base cannot.
    std::size_t receipts_first_above(uint64_t retired) const;
    void apply_receipt_base(std::size_t base) noexcept;
    /// The external stores are created on first use, in the directory
    /// set_successor_roots_directory named.
    void ensure_receipt_store();
    CacheCapacity tail_cache_capacity(TailWindowKind kind) const noexcept;
    void prepare_codec_frames();
    void ensure_chain_segments();
    /// Appends one event to the journal (storage reserved by reserve_plan or
    /// seal_direct) and advances the absolute length. A bound codec reports I/O.
    void append_event(CommandEvent&& event);
    /// A first deferred link starts a chain whose head retire_history must
    /// keep; a row that held a chain and no longer does makes the cached
    /// floor a lower bound until it is recomputed.
    void note_chain_birth(const CommandEvent& event) noexcept;
    void note_chain_loss(const LiveRequest& row) noexcept;
    /// The working book's row erase: every erase goes through here so the
    /// chain floor hears of a chain that left with its row.
    void erase_live(std::size_t index) noexcept;
    /// A best and offset through native_matching::checked_trail_stop: finite,
    /// strictly past the best for a positive offset. `ladder_tick` is the run's
    /// price tick (ActivationGrid::ladder_tick); zero keeps the raw subtraction.
    bool trail_level_ok(double best, double offset, bool is_buy, double* stop,
                        double ladder_tick = 0.0) const noexcept;
    /// Whether this run's core accepted a request under `handle`, live or
    /// not: what a cohort command answers UnknownOrigin by.
    bool issued(const RequestHandle& handle) const noexcept;
    /// The first handle of `origin`'s replace chain (RequestDefinition::root),
    /// read from the live row or, for a request that is no longer working,
    /// from the chain index; nullopt for a handle this run never issued.
    std::optional<RequestHandle> canonical_cohort_origin(const RequestHandle& origin) const;
    bool cohort_exists(CohortHandle cohort) const noexcept;
    /// Records an accepted request's incarnation and, for a replace
    /// successor, its chain root, in the chain index. Storage is reserved by
    /// reserve_plan, so this cannot throw inside commit.
    void index_committed(const CommandEvent& event) noexcept;
    /// The head of every live deferred group-adjustment chain: the lowest
    /// ordinal retire_history must keep, or nullopt when no chain is live.
    std::optional<uint64_t> pending_chain_floor() const;
 
    uint64_t usable_ordinal(uint64_t next) const;
    uint64_t usable_incarnation(uint64_t next) const;
    /// The working book's position of the request under `incarnation`, or
    /// live_.size(), while repriced_ names a re-priced request: a search by
    /// queue order (the priority repriced_ names, or the handle's own number).
    std::size_t repriced_position(uint64_t incarnation) const noexcept;
    /// refresh_allowance's body, and its bind for an unbound close that
    /// carried a binding, under the open activation grant (false for every
    /// form that does not name one).
    bool refresh_allowance(const RequestHandle& target, const EvaluationContext& context,
                           const TargetObservation& observation,
                           uint64_t* next_timeline_ordinal, bool open_activation_grant);
    bool refresh_kept_binding(LiveRequest& live, const EvaluationContext& context,
                              const TargetObservation& observation,
                              uint64_t& next_timeline_ordinal);
    TargetKind classify_repriced(uint64_t incarnation, std::size_t* live_index) const noexcept;
    const LiveRequest* find_repriced(uint64_t incarnation) const noexcept;
    /// Records that the request under `incarnation` now stands at
    /// `priority` (a keep_handle re-price), dropping the entries of requests
    /// that have left the book once they outnumber its rows. The caller has
    /// reserved one entry.
    void note_repriced(uint64_t incarnation, uint64_t priority) noexcept;
    /// classify among the resident rows only.
    TargetKind classify_resident(const RequestHandle& handle, std::size_t* live_index) const;
    /// The index of the row a command targets in live_. A target outside the
    /// heap (a spilled row) is brought back into live_ first -- the one place
    /// the book changes without a command committing -- so every command
    /// reads and writes its row where the resident book keeps it.
    TargetKind classify(const RequestHandle& handle, std::size_t* live_index);
    bool bump_epoch() noexcept;
    void require_epoch_room() const;
    void clear_unbound() noexcept;
 
    struct InstanceBinding {
        uint64_t generation = 1;
        bool expired = false;
    };
    struct MutationPlan {
        std::weak_ptr<InstanceBinding> instance;
        uint64_t generation = 0;
        uint64_t epoch = 0;
        RunIdentity run;
        std::size_t history_size = 0;
        uint64_t last_ordinal = 0;
        bool consumed = false;
        InlineCommandEvents events;
        std::uint8_t live_change = 0;  // 0 none, 1 push, 2 erase, 3 update
        std::size_t live_index = 0;
        LiveRequest live_row{};
        bool consume_incarnation = false;
        uint64_t incarnation_used = 0;
        // An ordinal the mutation takes with no event: a kept binding's
        // (ReplaceOptions::keep_binding). 0: none.
        uint64_t skipped_ordinal = 0;
        bool add_receipt = false;
        EventId receipt_cause{};
        RequestHandle receipt_recipient{};
        GroupEffect receipt_effect = GroupEffect::Reduce;
        uint64_t receipt_outcome = 0;
        // A resolution event whose chain is longer than kInlineAdjustmentIds
        // keeps its ids in the external list the chain walk wrote: the event's
        // ordinal, where the list starts and how many ids it holds.
        bool chain_segment = false;
        uint64_t chain_event_ordinal = 0;
        uint64_t chain_offset = 0;
        uint64_t chain_count = 0;
    };
    std::optional<InstallError> validate_plan(const MutationPlan& plan) const noexcept;
    // prepare_replace / apply_replace past their checks, for a replace that
    // keeps the handle or carries a binding (ReplaceOptions::keep_handle /
    // keep_binding), and the successor row the two share.
    PreparedReplace prepare_replace_kept(std::size_t live_index, const RequestHandle& staged_target,
                                         Request&& staged, uint64_t ordinal, uint64_t incarnation,
                                         const CommandContext& context, ReplaceOptions options,
                                         MutationPlan&& plan);
    // apply_replace's two instantiations: <false> is a plain replace,
    // <true> (through apply_replace_kept, out of line) one with the options.
    template <bool Kept>
    CommandInstalled<ReplaceResult> apply_replace_as(const RequestHandle& target,
                                                     const Request& request,
                                                     const CommandContext& context,
                                                     uint64_t& next_order_incarnation,
                                                     uint64_t& next_timeline_ordinal,
                                                     ReplaceOptions options);
    CommandInstalled<ReplaceResult> apply_replace_kept(const RequestHandle& target,
                                                       const Request& request,
                                                       const CommandContext& context,
                                                       uint64_t& next_order_incarnation,
                                                       uint64_t& next_timeline_ordinal,
                                                       ReplaceOptions options);
    LiveRequest kept_successor(std::size_t live_index, const RequestHandle& staged_target,
                               Request&& staged, uint64_t ordinal, uint64_t incarnation,
                               const CommandContext& context, ReplaceOptions options) const;
    InstallResult commit(MutationPlan& plan) noexcept;
    MutationPlan begin_plan() const;
    void reserve_plan(const MutationPlan& plan);
    void bind_plan(MutationPlan& plan) const;
    void seal_plan(MutationPlan& plan);
    PreparedMutation finish_mutation(MutationPlan plan);
 
    // The direct forms' halves of a plan (the direct request-core forms). begin_direct makes
    // begin_plan's checks; seal_direct reserves what seal_plan would reserve
    // for `events` events and the live change and takes the seal's epoch;
    // append_direct appends one event exactly as commit does (the journal
    // append, the chain index for a command that consumes an incarnation,
    // the last ordinal); finish_direct takes commit's epoch and answers the
    // range. Nothing after seal_direct can throw. seal_direct also makes the
    // journal's room -- it may write the oldest resident events to an
    // external page first -- so a pointer into the journal taken before it is
    // read before it, as for prepare_*. `chain_segment` reserves the external
    // list index row of a resolution whose chain was written externally.
    void begin_direct() const;
    void seal_direct(std::size_t events, bool push_live, bool add_receipt,
                     bool consume_incarnation, bool chain_segment = false);
    /// Records the external id list of a resolution event just appended by
    /// append_direct (room made by seal_direct). Cannot throw.
    void note_chain_segment(uint64_t event_ordinal, uint64_t offset, uint64_t count) noexcept;
    template <class Event>
    void append_direct(Event&& event, bool consume_incarnation);
    EventRange finish_direct(std::size_t first) noexcept;
    template <class Event>
    Installed end_direct(std::size_t live_index, Event&& event);
    // What prepare_execution computes for its events and its retained row,
    // as values: check_execution and apply_execution make the same checks
    // through it (execution_values), so what apply_execution writes is what
    // the token would have held.
    struct ExecutionValues {
        std::size_t live_index = 0;
        uint64_t ordinal = 0;
        double filled = 0.0;
        bool flatten = false;
        bool units_exhausted = false;
        RemainingProjection remaining_after = RemainingProjectionUnits{};
        Allowance allowance_after = AllowanceUnset{};
        ExecutionScope scope = execution::Book{};
    };
    Preparation<ExecutionValues> execution_values(const RequestHandle& target,
                                                  const ExecutionProposal& proposal,
                                                  uint64_t& next_timeline_ordinal,
                                                  bool open_activation_grant);
 
    // The journal, the group-effect keys and the long
    // chains' id lists keep a fixed resident part and write the rest to
    // run-owned scratch files, created on the first spill. They are defined in
    // native_order.cpp and held by shared_ptr so this header stays complete.
    struct JournalStore;
    struct ReceiptStore;
    struct ChainSegments;
    // E02: the working book keeps at most a fixed number of rows in live_,
    // sorted by priority; its newest rows beyond that wait in BookSpill (an
    // external ordered table of serialized rows), spilled_count() of them.
    // The queue is the merge of the two in priority order. A row is in
    // exactly one of them; a command that targets a spilled row brings it
    // back into live_ (classify), and a row that would not fit pushes the
    // newest resident rows out first (make_book_room). repriced_ names only
    // resident rows.
    // The stores' state lives in the stores (the journal's length, the keys'
    // base and count, the spilled rows' count) and the directory they spill
    // into is the successor roots' (scratch_directory), so that the core
    // itself keeps the size it had before the stores existed.
    struct BookSpill;
    std::size_t spilled_count() const noexcept;
    const std::string& scratch_directory() const noexcept;
    // A position in the merged queue: the next resident row and the next
    // spilled one (a table offset, 0 when none) with its priority.
    struct BookCursor {
        std::size_t r = 0;
        uint64_t at = 0;
        uint64_t spilled_priority = 0;
    };
    void make_book_room();
    bool promote_book_row(uint64_t incarnation, std::size_t* index);
    const LiveRequest* spilled_row(uint64_t incarnation) const;
    std::shared_ptr<LiveRequest> spilled_held(uint64_t incarnation) const;
    const LiveRequest* find_resident(const RequestHandle& handle) const noexcept;
    // How many times the spilled table has been rebuilt (BookSpill::compact):
    // a table offset taken under one generation names nothing under the next.
    uint64_t book_generation() const noexcept;
    // hold_live for a row a walk of live() stood on outside the heap, at table
    // offset `at` (LiveView::const_iterator::spilled_at) under `generation`:
    // the row is read from that entry, with no search of the table, while the
    // entry still holds the request spilled. Otherwise -- the table rebuilt
    // since, the row back in the heap or ended -- it answers hold_live(handle).
    std::shared_ptr<const LiveRequest> hold_scanned(const RequestHandle& handle, uint64_t at,
                                                    uint64_t generation) const;
    void forget_repriced(uint64_t incarnation) noexcept;
    BookCursor book_begin() const;
    bool book_done(const BookCursor& cursor) const noexcept;
    bool book_next_spilled(const BookCursor& cursor) const noexcept;
    void book_step(BookCursor& cursor) const;
    const LiveRequest& live_back() const;
    /// Visits every live row in queue order until `visit` answers false. A
    /// spilled row is a copy that lives only for its visit.
    template <class Visit>
    void visit_book(Visit&& visit) const;
 
    RunIdentity identity_;
    std::shared_ptr<InstanceBinding> instance_;
    std::vector<LiveRequest> live_;
    std::shared_ptr<BookSpill> book_spill_;
    uint64_t last_ordinal_ = 0;
    uint64_t last_incarnation_ = 0;
    uint64_t epoch_ = 0;
    // The journal window: how many events were retired from its front and the
    // ordinal of the newest retired event. The events themselves -- resident
    // chunks plus external pages, the ordinal lookup over both, and the
    // absolute length (the position the next event takes) -- are the store's.
    std::shared_ptr<JournalStore> journal_;
    std::size_t history_base_ = 0;
    uint64_t retired_through_ = 0;
    // The head of the oldest live deferred chain (kNoChainFloor: none), a
    // lower bound unless chain_floor_exact_ (see note_chain_birth /
    // note_chain_loss).
    static constexpr uint64_t kNoChainFloor = std::numeric_limits<uint64_t>::max();
    mutable uint64_t chain_floor_ = kNoChainFloor;
    mutable bool chain_floor_exact_ = true;
    std::shared_ptr<ChainSegments> chain_segments_;
    // Issued ranges are dense for a consumer. Successor roots spill in order;
    // the consumer's event fold hashes their logical rows, once each.
    struct SuccessorRootIndex;
    void reserve_successor_root();
    void append_successor_root(uint64_t incarnation, uint64_t root) noexcept;
    std::optional<uint64_t> successor_root(uint64_t incarnation) const;
    std::vector<std::pair<uint64_t, uint64_t>> issued_;
    std::shared_ptr<SuccessorRootIndex> successor_roots_;
    // The requests a keep_handle re-price moved in the queue, ascending by
    // incarnation: (incarnation, priority). The book is held by priority, so
    // a handle lookup reads its priority here; a handle absent here is at its
    // own incarnation. Derived from the book (each row's definition carries
    // its priority), so nothing folds it; an entry outlives its request
    // until the next re-price prunes it, and a lookup through it finds no
    // row because no other request takes that priority.
    std::vector<std::pair<uint64_t, uint64_t>> repriced_;
    // Readback-only base; total/digest stay in the consumer. Keys are in
    // cause/drain order, retained at [group_effect_receipt_base(),
    // group_effect_receipt_count()) and held by the receipt store (a resident
    // tail over an external log), which also keeps the base and the count.
    std::shared_ptr<ReceiptStore> receipt_store_;
    std::uint64_t next_cohort_handle_ = 1;
    // Only rosters with members occupy nodes; erasing an empty roster frees
    // its member capacity as well. next_cohort_handle_ records the complete
    // dense sequence of allocated handles, including every empty roster.
    std::map<std::uint64_t, CohortRoster> cohorts_;
    std::vector<CohortReceipt> cohort_receipts_;
    // Storage cursor only: the consumer hashes the lifetime count and every
    // receipt, independently of how many of their rows have been retired.
    std::size_t cohort_receipts_base_ = 0;
};
 
// A non-owning read view. Iteration preserves CohortRoster references for
// existing typed predicates and iterator arrow reads. An empty row belongs
// to its input iterator and is valid until that iterator advances or dies.
// Indexed reads return a value, so a saved row from a temporary view remains
// valid. Callers that need no copies use the allocation-free iterator walk.
class WorkingRequestCore::CohortView {
public:
    class const_iterator {
    public:
        using iterator_category = std::input_iterator_tag;
        using value_type = CohortRoster;
        using difference_type = std::ptrdiff_t;
        using pointer = const CohortRoster*;
        using reference = const CohortRoster&;
 
        const_iterator() noexcept = default;
        reference operator*() const noexcept;
        pointer operator->() const noexcept { return &**this; }
        const_iterator& operator++() noexcept { ++index_; return *this; }
        const_iterator operator++(int) {
            auto previous = *this;
            ++*this;
            return previous;
        }
        friend bool operator==(const const_iterator& left, const const_iterator& right) noexcept {
            return left.core_ == right.core_ && left.index_ == right.index_;
        }
        friend bool operator!=(const const_iterator& left, const const_iterator& right) noexcept {
            return !(left == right);
        }
 
    private:
        friend class CohortView;
        const_iterator(const WorkingRequestCore* core, std::size_t index) noexcept
            : core_(core), index_(index) {}
        const WorkingRequestCore* core_ = nullptr;
        std::size_t index_ = 0;
        mutable CohortRoster empty_{};
    };
 
    std::size_t size() const noexcept {
        return static_cast<std::size_t>(core_->next_cohort_handle_ - 1);
    }
    bool empty() const noexcept { return size() == 0; }
    const_iterator begin() const noexcept { return const_iterator(core_, 0); }
    const_iterator end() const noexcept { return const_iterator(core_, size()); }
    CohortRoster operator[](std::size_t index) const { return *const_iterator(core_, index); }
 
private:
    friend class WorkingRequestCore;
    explicit CohortView(const WorkingRequestCore* core) noexcept : core_(core) {}
    const WorkingRequestCore* core_;
};
 
// A non-owning read view of the command journal's retained window
// (WorkingRequestCore::history), with the read interface the window had as a
// std::vector<CommandEvent>: size, empty, front, back, indexing relative to
// history_base(), random-access iteration, and a conversion to a vector for
// a reader that wants an owning copy. The newest events are resident; older
// ones sit in external pages that the view reads back through a fixed page
// cache, so a reference it returns stays valid until the next few page loads
// or the next command, and a read of an old event may do I/O (and so throw).
// capacity() and max_size() answer one huge bound: nothing is reserved for an
// external window. Positions are absolute inside the iterator, so an
// iterator survives a retirement that leaves its event in the window.
class WorkingRequestCore::JournalView {
public:
    class const_iterator {
    public:
        using iterator_category = std::random_access_iterator_tag;
        using value_type = CommandEvent;
        using difference_type = std::ptrdiff_t;
        using pointer = const CommandEvent*;
        using reference = const CommandEvent&;
 
        const_iterator() noexcept = default;
        reference operator*() const { return core_->history_at(position_); }
        pointer operator->() const { return &core_->history_at(position_); }
        reference operator[](difference_type offset) const { return *(*this + offset); }
        const_iterator& operator++() noexcept { ++position_; return *this; }
        const_iterator operator++(int) noexcept {
            const_iterator previous = *this;
            ++position_;
            return previous;
        }
        const_iterator& operator--() noexcept { --position_; return *this; }
        const_iterator operator--(int) noexcept {
            const_iterator previous = *this;
            --position_;
            return previous;
        }
        const_iterator& operator+=(difference_type offset) noexcept {
            position_ = static_cast<std::size_t>(static_cast<difference_type>(position_) + offset);
            return *this;
        }
        const_iterator& operator-=(difference_type offset) noexcept { return *this += -offset; }
        friend const_iterator operator+(const_iterator iterator, difference_type offset) noexcept {
            iterator += offset;
            return iterator;
        }
        friend const_iterator operator+(difference_type offset, const_iterator iterator) noexcept {
            iterator += offset;
            return iterator;
        }
        friend const_iterator operator-(const_iterator iterator, difference_type offset) noexcept {
            iterator -= offset;
            return iterator;
        }
        friend difference_type operator-(const const_iterator& left,
                                         const const_iterator& right) noexcept {
            return static_cast<difference_type>(left.position_)
                 - static_cast<difference_type>(right.position_);
        }
        friend bool operator==(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ == right.position_;
        }
        friend bool operator!=(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ != right.position_;
        }
        friend bool operator<(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ < right.position_;
        }
        friend bool operator>(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ > right.position_;
        }
        friend bool operator<=(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ <= right.position_;
        }
        friend bool operator>=(const const_iterator& left, const const_iterator& right) noexcept {
            return left.position_ >= right.position_;
        }
 
    private:
        friend class JournalView;
        const_iterator(const WorkingRequestCore* core, std::size_t position) noexcept
            : core_(core), position_(position) {}
        const WorkingRequestCore* core_ = nullptr;
        std::size_t position_ = 0;
    };
    using value_type = CommandEvent;
    using size_type = std::size_t;
    using reference = const CommandEvent&;
    using const_reference = const CommandEvent&;
    using iterator = const_iterator;
 
    std::size_t size() const noexcept { return core_->history_end() - core_->history_base(); }
    bool empty() const noexcept { return size() == 0; }
    std::size_t max_size() const noexcept {
        return static_cast<std::size_t>(std::numeric_limits<std::ptrdiff_t>::max()) / 4;
    }
    std::size_t capacity() const noexcept { return max_size(); }
    const CommandEvent& operator[](std::size_t index) const {
        return core_->history_at(core_->history_base() + index);
    }
    const CommandEvent& at(std::size_t index) const {
        if (index >= size()) throw std::out_of_range("native journal index is not retained");
        return (*this)[index];
    }
    const CommandEvent& front() const { return (*this)[0]; }
    const CommandEvent& back() const { return (*this)[size() - 1]; }
    const_iterator begin() const noexcept { return const_iterator(core_, core_->history_base()); }
    const_iterator end() const noexcept { return const_iterator(core_, core_->history_end()); }
    const_iterator cbegin() const noexcept { return begin(); }
    const_iterator cend() const noexcept { return end(); }
    operator std::vector<CommandEvent>() const { return std::vector<CommandEvent>(begin(), end()); }
 
private:
    friend class WorkingRequestCore;
    explicit JournalView(const WorkingRequestCore* core) noexcept : core_(core) {}
    const WorkingRequestCore* core_;
};
 
// A non-owning read view of the working book in queue order
// (WorkingRequestCore::live), with the read interface the book had as a
// std::vector<LiveRequest>: size, empty, front, back, indexing by queue rank,
// forward iteration, and a conversion to a vector for a reader that wants an
// owning copy. The resident rows are read in place; the rows outside the heap
// (a book past its resident bound) are read back one at a time, in queue
// order, so an iteration holds at most one of them. A reference to a spilled
// row stays valid until the next few spilled rows are read or the next
// command. Iterating costs one external read per spilled row; indexing by rank
// walks to it.
class WorkingRequestCore::LiveView {
public:
    class const_iterator {
    public:
        using iterator_category = std::forward_iterator_tag;
        using value_type = LiveRequest;
        using difference_type = std::ptrdiff_t;
        using pointer = const LiveRequest*;
        using reference = const LiveRequest&;
 
        const_iterator() noexcept = default;
        reference operator*() const;
        pointer operator->() const { return &**this; }
        /// The row the iterator stands on, held as hold_live holds it: a
        /// spilled row stays valid as long as the answer does, however far
        /// the iterator or any other reader of the book moves on.
        std::shared_ptr<const LiveRequest> hold() const;
        const_iterator& operator++();
        const_iterator operator++(int) {
            const_iterator previous = *this;
            ++*this;
            return previous;
        }
        friend bool operator==(const const_iterator& left, const const_iterator& right) noexcept {
            return left.core_ == right.core_ && left.cursor_.r == right.cursor_.r
                && left.cursor_.at == right.cursor_.at;
        }
        friend bool operator!=(const const_iterator& left, const const_iterator& right) noexcept {
            return !(left == right);
        }
 
    private:
        friend class LiveView;
        friend class ::pineforge::engine_script_run_v20::NativeExecutionConsumer;
        const_iterator(const WorkingRequestCore* core, BookCursor cursor) noexcept
            : core_(core), cursor_(cursor) {}
        // The spilled table's offset of the row the iterator stands on, 0
        // when that row is resident (WorkingRequestCore::hold_scanned).
        uint64_t spilled_at() const noexcept { return held_ ? cursor_.at : 0; }
        // Loads the spilled row the cursor stands on, if it does.
        void settle();
        const WorkingRequestCore* core_ = nullptr;
        BookCursor cursor_{};
        std::shared_ptr<LiveRequest> held_;
    };
    using value_type = LiveRequest;
    using size_type = std::size_t;
    using reference = const LiveRequest&;
    using const_reference = const LiveRequest&;
    using iterator = const_iterator;
 
    std::size_t size() const noexcept { return core_->live_size(); }
    bool empty() const noexcept { return size() == 0; }
    const LiveRequest& operator[](std::size_t rank) const { return core_->live_at(rank); }
    const LiveRequest& at(std::size_t rank) const { return core_->live_at(rank); }
    const LiveRequest& front() const { return core_->live_at(0); }
    const LiveRequest& back() const { return core_->live_back(); }
    const_iterator begin() const;
    const_iterator end() const;
    const_iterator cbegin() const { return begin(); }
    const_iterator cend() const { return end(); }
    operator std::vector<LiveRequest>() const;
 
private:
    friend class WorkingRequestCore;
    explicit LiveView(const WorkingRequestCore* core) noexcept : core_(core) {}
    const WorkingRequestCore* core_;
};
 
class PreparedSubmit {
public:
    PreparedSubmit() noexcept;
    PreparedSubmit(PreparedSubmit&&) noexcept;
    PreparedSubmit& operator=(PreparedSubmit&&) noexcept;
    ~PreparedSubmit();
    PreparedSubmit(const PreparedSubmit&) = delete;
    PreparedSubmit& operator=(const PreparedSubmit&) = delete;
    explicit operator bool() const noexcept;
    const SubmitResult& predicted() const;
    EventId predicted_event_id() const;
 
private:
    friend class WorkingRequestCore;
    struct Impl;
    std::unique_ptr<Impl> impl_;
    explicit PreparedSubmit(std::unique_ptr<Impl> impl) noexcept;
};
 
class PreparedReplace {
public:
    PreparedReplace() noexcept;
    PreparedReplace(PreparedReplace&&) noexcept;
    PreparedReplace& operator=(PreparedReplace&&) noexcept;
    ~PreparedReplace();
    PreparedReplace(const PreparedReplace&) = delete;
    PreparedReplace& operator=(const PreparedReplace&) = delete;
    explicit operator bool() const noexcept;
    const ReplaceResult& predicted() const;
    EventId predicted_event_id() const;
 
private:
    friend class WorkingRequestCore;
    struct Impl;
    std::unique_ptr<Impl> impl_;
    explicit PreparedReplace(std::unique_ptr<Impl> impl) noexcept;
};
 
class PreparedCancel {
public:
    PreparedCancel() noexcept;
    PreparedCancel(PreparedCancel&&) noexcept;
    PreparedCancel& operator=(PreparedCancel&&) noexcept;
    ~PreparedCancel();
    PreparedCancel(const PreparedCancel&) = delete;
    PreparedCancel& operator=(const PreparedCancel&) = delete;
    explicit operator bool() const noexcept;
    const CancelResult& predicted() const;
    EventId predicted_event_id() const;
 
private:
    friend class WorkingRequestCore;
    struct Impl;
    std::unique_ptr<Impl> impl_;
    explicit PreparedCancel(std::unique_ptr<Impl> impl) noexcept;
};
 
class PreparedMutation {
public:
    PreparedMutation() noexcept;
    PreparedMutation(PreparedMutation&&) noexcept;
    PreparedMutation& operator=(PreparedMutation&&) noexcept;
    ~PreparedMutation();
    PreparedMutation(const PreparedMutation&) = delete;
    PreparedMutation& operator=(const PreparedMutation&) = delete;
    explicit operator bool() const noexcept;
 
private:
    friend class WorkingRequestCore;
    struct Impl;
    std::unique_ptr<Impl> impl_;
    explicit PreparedMutation(std::unique_ptr<Impl> impl) noexcept;
};
 
class PreparedExecution {
public:
    PreparedExecution() noexcept;
    PreparedExecution(PreparedExecution&&) noexcept;
    PreparedExecution& operator=(PreparedExecution&&) noexcept;
    ~PreparedExecution();
    PreparedExecution(const PreparedExecution&) = delete;
    PreparedExecution& operator=(const PreparedExecution&) = delete;
    explicit operator bool() const noexcept;
 
private:
    friend class WorkingRequestCore;
    struct Impl;
    std::unique_ptr<Impl> impl_;
    explicit PreparedExecution(std::unique_ptr<Impl> impl) noexcept;
};
 
static_assert(std::is_nothrow_move_constructible_v<Request>);
static_assert(std::is_nothrow_move_assignable_v<Request>);
static_assert(std::is_nothrow_move_constructible_v<LiveRequest>);
static_assert(std::is_nothrow_move_assignable_v<LiveRequest>);
static_assert(std::is_nothrow_move_constructible_v<CommandEvent>);
static_assert(std::is_nothrow_move_assignable_v<CommandEvent>);
static_assert(std::is_nothrow_move_constructible_v<SubmitResult>);
static_assert(std::is_nothrow_move_constructible_v<ReplaceResult>);
static_assert(std::is_nothrow_move_constructible_v<CancelResult>);
static_assert(std::is_nothrow_move_constructible_v<NoEffectEvent>);
static_assert(std::is_nothrow_move_constructible_v<MatchRejectedEvent>);
static_assert(std::is_nothrow_move_constructible_v<ExecutionAppliedEvent>);
static_assert(std::is_nothrow_move_constructible_v<MatchCursor>);
static_assert(std::variant_size_v<OrderIntent> == 6);
static_assert(std::variant_size_v<ReductionSize> == 3);
static_assert(std::variant_size_v<SizeBasis> == 2);
static_assert(std::variant_size_v<Remaining> == 5);
static_assert(std::variant_size_v<RemainingProjection> == 5);
static_assert(std::variant_size_v<Allowance> == 4);
static_assert(std::variant_size_v<CommandEvent> == 19);
static_assert(std::variant_size_v<ExecutionPlan> == 4);
static_assert(std::variant_size_v<ExecutionScope> == 3);
static_assert(std::variant_size_v<TriggerState> == 9);
static_assert(std::variant_size_v<TriggerAnchor> == 2);
 
}  // inline namespace native_order_v8
}  // namespace pineforge::native_order
 
namespace std {
template <>
struct hash<pineforge::native_order::CohortHandle> {
    std::size_t operator()(pineforge::native_order::CohortHandle value) const noexcept {
        return static_cast<std::size_t>(value.value ^ (value.value >> 32));
    }
};
}  // namespace std