Skip to content

Strategy Protocol: return requested orders over TCP/JSON #711

Closed

Description

@rustyeddy

Goal

Second small vertical slice after merged #710 / completed #703: let an external strategy receive completed bars over the existing loopback TCP/JSON connection and return requested orders that Trader evaluates using its existing Account → Broker machinery.

Implement only this increment. Open a PR for review before extending the protocol. Part of milestone #27 (Strategy Protocol), design issue #690, and ADR-093. This is an implementation increment toward a useful v1, not the definition of v1 itself.

Scope

  • Inspect the existing root order / OrderState lifecycle, strategy callback onBars(ctx, bars) ([]*order, error), Account risk/admission/sizing and Broker execution. Reuse the current domain semantics; do not create a parallel intent/order lifecycle.
  • Resolve the narrow public-type boundary between root trader and public strategy without an import cycle. Propose the smallest wire representation or domain-type exposure needed for requested orders in the PR description before broad refactoring. A transport DTO is acceptable where necessary, but must map into the existing authoritative Order.
  • Extend existing strategy.Serve / ListenAndServe worker callback and JSON response to return zero or more requested orders, in order. Preserve OnBars grouping, framing, limits, deadlines and error handling.
  • At the root adapter, strictly validate/decode requested order fields and forward valid requests through the same Trader order-processing path as in-process strategies; never bypass Account risk, position sizing or Broker.
  • Enforce the agreed boundary: a worker may request an order but may not dictate authoritative quantity/sizing, admission, fill, OrderState, account/broker state or other forbidden fields. Reject malformed/forbidden inputs explicitly and fail the run rather than silently ignoring them.
  • Preserve mandatory protective stop for opening orders, consistent with current domain validation. Do not build stop amendment/trailing behavior in this increment.
  • Keep worker-side Go API simple; update the example worker to demonstrate a tiny deterministic order-producing strategy.

Acceptance

  • Real historical backtest via external worker produces an opening requested order and a closing requested order (or deterministic stop exit), processed through the existing Account/Broker path.
  • Same simple strategy run in-process and externally yields equivalent accepted/rejected orders, fills and final outcome for a fixed fixture (subject to identical configuration).
  • Valid zero-order response still works; malformed JSON, forbidden fields, missing stop, unsupported order action and worker disconnect fail clearly; no orders are processed when the callback fails.
  • Unit/integration tests, race tests and make check pass. PR explains public-type mapping and any narrowly deferred decisions.

Explicitly deferred

Registration / RunID negotiation, Trader-side listener and service lifecycle, broker feedback/position snapshots (#698), durable results (#702), REST management (#700), registry, non-loopback auth/TLS, binary transport, generalized studies/indicators, stop amendments/trailing, and protocol version expansion.

Development cadence

Build → test → review → decide. Do not implement future issues opportunistically.

Activity

  1. added this to the Strategy Protocol milestone on Nov 21, 2026
  2. rustyeddy commented on Nov 21, 2026

    @rustyeddy
    OwnerAuthor

    Implementation plan for #711 (proposal for review; nothing is implemented yet)

    #710 lets a loopback worker answer each availability group with no orders. This slice lets it return requested orders, run through the existing path (trader.onFrame → handleOrder → order.validate → account sizing → broker). There is no second order lifecycle (ADR-093).

    Public type boundary

    strategy cannot import root trader (import cycle, and order is unexported). I propose one transport DTO in the public strategy package, strategy.Order. It is a request, not a lifecycle model, and no domain types are exposed.

    JSON field Meaning
    instrument string; must be one of the instruments in the delivered group
    action open, close, add, reduce (no amend)
    direction long / short; only for open (the domain already rejects it on close/add/reduce)
    type market (default), limit, stop
    price decimal string (num.Price): reference or trigger price, as EMAX sets the bar close today
    stop_loss decimal string; required on open by the existing validate
    take_profit decimal string, optional

    Deliberately left out: trail, expires, amend, ref, and anything stateful. A worker cannot send units, id, account, state, fill_price, reason or decidedAt. Replies are decoded strictly (DisallowUnknownFields), so any such field fails the run with an explicit error instead of being ignored.

    Authority stays in Trader

    The root adapter (strategy_remote.go) maps each DTO to *order:

    • It parses action, direction and type with small inverse-of-String() helpers; an unknown string is an error.
    • Time comes from the delivered bar of that instrument; an instrument not in the group is an error.
    • accountID, decidedAt, id, units and state are left to the existing onFrame / handleOrder / broker code.
    • It calls o.validate() on every order before returning any, so one bad order means the callback fails and none are processed.

    Missing stop, unsupported action and malformed JSON all fail the run. The existing onBars error path already stops onFrame before any order is used.

    Changes

    • strategy/strategy.go: Order; ordersMessage.Orders []Order.
    • strategy/frame.go: strict decoding in readMessage, keeping the 16 MiB cap.
    • strategy/client.go: Client.OnBars(ctx, bars) ([]Order, error); the "orders not supported" error goes away. Deadline, cancel and loopback behaviour are unchanged.
    • strategy/server.go: the Serve / ListenAndServe callback becomes func(bars []marketdata.Bar) ([]Order, error); the reply always holds a non-nil list.
    • strategy_remote.go: the mapping and parse helpers.
    • examples/remote-strategy: a tiny deterministic rule (open long on the Nth group with a stop a fixed distance below the close, close on the Mth).
    • Existing callbacks and tests get the mechanical signature change.

    Reused: order.validate, trader.onFrame / handleOrder, the recorder / startWorker / newRemoteTrader helpers in trader_test.go, orderResults / orderHistories in emax_backtest_test.go, the a-reversal-exit fixture.

    Tests

    • strategy: Order JSON round trip with decimal strings; strict decode rejects units, id, state and unknown fields; orders carried in order, including a zero-order reply ([], not null); malformed JSON reply fails.
    • Adapter tables: valid open/close mapping (Time from the bar); unknown action, direction or type; amend; instrument not in the group; open without a stop; a later invalid order means none are processed.
    • Integration: the same simple strategy in-process (a test twin of the example rule) and over TCP on the same fixture and config. Equal order histories, fills, final balance and trades; both an opening and a closing order occur. Zero orders, disconnect and timeout still pass.
    • The real example binary built and run as a separate process.

    Verification

    go test -race -count=1 ./..., make check, and the EMAX md5 195e457a21def1223e7181c86cb824a4 unchanged.

    Process

    Branch from the issue (gh issue develop 711), one PR with Closes #711, whose description repeats the mapping and the deferred list. No merge until the owner says "merge".

    Deferred (not in this increment)

    trail / expires / amend, registration and RunID, Trader-side listener, broker feedback (#698), journal (#702), REST (#700), auth/TLS, binary transport.

    Defaults I'll assume unless you say otherwise

    1. price is required on open (and on limit/stop orders), as validate demands today; the other actions may omit it.
    2. The DTO lives in public strategy; no domain types are exposed.
    3. Strict unknown-field rejection applies to both directions of the wire.
  3. rustyeddy commented on Nov 21, 2026

    @rustyeddy
    OwnerAuthor

    Owner clarification for #711: drop the adapter's instrument-membership check altogether. Do not require a requested order's instrument to appear in the current OnBars group, and do not add a separate run-universe membership check in this increment. Multi-instrument strategies may request an order for a different instrument than those represented in the current completed-bar group.

    Keep the existing Order/Account/Broker validation and risk authority intact (including strict decoding and forbidden-field rejection); this decision removes only the proposed instrument membership gate. Do not expand the protocol or invent additional instrument-selection machinery. Please update the plan/tests accordingly, then proceed with the small implementation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions