Skip to content

Strategy Protocol: deliver execution feedback with the next OnBars #698

Closed

Description

@rustyeddy

Goal — next small Strategy Protocol increment

After merged #710 (bars over TCP/JSON) and #712 (requested orders), let an external strategy learn what Trader actually did with its orders. Deliver read-only execution feedback alongside the next OnBars callback, not through a separate asynchronous message channel.

Implement only this increment; open a PR for review before extending the protocol. This is one step toward milestone #27 v1, not the full v1 definition. Part of #690 and consistent with ADR-093 (Trader owns the single Order/OrderState lifecycle).

Agreed decision

  • Trader remains the only authority for Account risk/admission, position sizing, Broker execution and OrderState.
  • Feedback is delivered with the next completed-bars group; it reports events already known by the host when that callback begins. Do not leak events caused by the current callback's returned orders into that same request.
  • Maintain a single synchronous request/response exchange: Trader sends OnBars input, worker returns requested orders.
  • Reuse existing broker/order event structures and timing semantics where practical; introduce the smallest public read-only representation needed to cross the package/protocol boundary.

Scope

  1. Inspect existing order history/events and the trader.onFrame / Account / Broker lifecycle. Briefly describe the proposed event mapping and delivery timing in the PR before broad refactoring.
  2. Extend the worker's OnBars input to include the completed bars and an ordered events list (empty is allowed). Keep the existing length-prefixed JSON framing, loopback-only transport, timeouts and strict field validation.
  3. Include the minimum information for an external strategy to distinguish:
    • An order requested but rejected (with reason).
    • An order accepted/filled (including host-assigned identity and authoritative execution details as available).
    • An exit caused by a protective stop.
  4. Ensure each event is delivered at most once, in deterministic order, and not before its true availability. Preserve existing in-process behavior and no-look-ahead guarantees.
  5. Update the Go worker SDK and reference example to consume feedback without adding a second order/state machine or an asynchronous listener.

Acceptance

  • A deterministic external backtest requests an opening order; on a subsequent OnBars call the worker can observe whether it was rejected or filled and can recognize a protective-stop exit.
  • Tests verify no future leakage, stable ordering, no duplicate delivery, empty events, rejection reason, fills and stop-outs, and continued in-process/remote parity for the same fixture.
  • The host retains full control of order sizing, admission, state and fills; the worker only receives read-only facts.
  • go test -race ./... and make check pass. PR documents any deliberately deferred feedback fields.

Explicitly deferred

Development cadence

Build → test → review → decide. Do not attempt all the unresolved protocol questions or broader #690 scope in this issue.

Activity

  1. added this to the Strategy Protocol milestone on Nov 20, 2026
  2. changed the title [-]Strategy Protocol: return broker feedback and position context to strategies[/-] [+]Strategy Protocol: deliver execution feedback with the next OnBars[/+] on Nov 21, 2026
  3. rustyeddy commented on Nov 21, 2026

    @rustyeddy
    OwnerAuthor

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

    #710 and #712 are merged: the worker receives bars and requests orders, but never learns what Trader did with them. This slice adds read-only execution feedback in the same request as the next completed-bars group. There is no second channel, and Trader stays the authority for risk, sizing, execution and OrderState (ADR-093).

    Where events come from (existing code)

    • trader.onFrame: broker.onFrame(f) runs first (fills, stops and expiries for this frame), then strategy.onBars. Returned orders are handled after that, in handleOrder.
    • Every order carries its lifecycle in order.history (orderEvent{state, time, reason}); order.record is the only writer.
    • Strategy orders refused at sizing or submit sit in trader.rejected and never get an id. Orders the broker fills, rejects at the fill or cancels join broker.completed (append-only). The broker's own protective stop, take profit and closeout orders are in completed with reason != reasonStrategy.

    Timing (this is what gives no look-ahead and no leak)

    Events are collected inside onFrame after broker.onFrame(f) and before onBars. A request therefore carries:

    • what the broker did while processing this frame's bars (the bar is complete, and in-process strategies already see this), and
    • the outcome of the previous callback's orders.

    It never carries anything caused by the orders returned by this same callback: they are handled after onBars returns and appear in the next request. Each history entry is delivered once, through a per-order cursor.

    Design

    • Delivery without changing onBars. A small optional interface next to warmer: feedbacker { feedback(events []feedbackEvent) }. onFrame calls it just before onBars, only if the strategy implements it. In-process strategies and the EMAX md5 are untouched; the remote adapter keeps the events and sends them with the next OnBars.

    • Collector (new feedback.go, root). The trader gets watched []*order (appended in handleOrder before submit, so a sizing rejection is seen), sent map[*order]int and exitsSeen int (a cursor into broker.completed). It emits:

      • the submitted / filled / rejected / cancelled history entries of watched orders;
      • the filled broker exits of this account (stop loss, take profit, margin closeout), whose submitted and cancelled noise stays out.

      They are stable-sorted by event time; on a tie the strategy's own events come first, then the broker's exits (the causal order on one bar).

    • Public read-only strategy.Event (no domain types exposed):

    JSON field Meaning
    time when it happened (the step's bar time)
    kind accepted, filled, rejected, cancelled
    id host-assigned order id; empty for a rejection before submit (those orders never get one)
    ref the worker's own label from Order.Ref, echoed; empty for the broker's own exits
    instrument, action, direction what the order was
    units the size Trader chose (accepted, filled)
    price fill price (filled)
    cause strategy, stop loss, take profit, margin closeout: tells a protective-stop exit apart
    reason why, for a rejection

    Excluded: account, balance, positions, margin and any other stateful snapshot (deferred in the issue).

    • Wire. The request becomes {"bars":[...],"events":[...]} with the same strict decoding, framing, deadline and size cap. events is required and may be [] (missing or null is an error, like the orders list). Client.OnBars(ctx, bars, events); the Serve / ListenAndServe callback becomes func(bars, events) ([]Order, error).
    • Correlation. A worker must be able to tie a rejection to its request, and rejected orders have no id (ids are issued at submit; giving rejects ids would shift later ids and break parity). So Order gains an optional ref string that is echoed on its events. The adapter keeps a map[*order]string; the domain order gets no new field.

    Changes

    • strategy/strategy.go, client.go, server.go: Event, Order.Ref, events in the request, new signatures, the required-list check.
    • Root: strategy.go (feedbacker), trader.go (onFrame call, handleOrder appends to watched), new feedback.go, strategy_remote.go (feedback(), ref map, events passed through).
    • examples/remote-strategy: same rule, but it closes on the sixth group only if it saw its entry filled and not stopped out, and it prints each event to stderr.
    • Mechanical: existing callbacks and tests take the new argument.

    Tests

    • Collector: nothing before the first order; accepted then filled on the next callback; delivered once; stable order; the current callback's own orders absent from its request; a sizing rejection carries the reason and no id; a broker rejection at the fill; a stop-out arrives with cause stop loss (the b1-stop-wick / b2-stop-cross fixtures); take-profit and closeout causes; broker exits' submitted/cancelled not delivered; a cancelled strategy order is delivered.
    • Wire: Event and ref round trip; null/missing events is an error; strict decoding of the request.
    • Parity: the same feedback-aware rule in-process (it implements feedbacker too) and over TCP gives identical orders, fills, balance, trades and events seen; a stop-out fixture shows the worker skipping its close; a zero-balance account shows the rejection reason reaching the worker; the real example binary 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 698), one PR with Closes #698, the PR description repeating the event mapping and the deferred list. No merge until the owner says "merge".

    Deferred (the PR will say so)

    Position and account snapshots, push or async events, amend/trail events, richer per-fill fields (margin, P/L), registration/RunID, a Trader-side listener, journal (#702), REST (#700), auth/TLS, binary transport.

    Defaults I'll assume unless you say otherwise

    1. An optional feedbacker interface (mirrors warmer) rather than adding events to the onBars signature, which would touch about 20 implementers mechanically.
    2. Order.Ref echoed on events, rather than the worker matching a rejection by instrument/action/time.
    3. Event kinds accepted, filled, rejected, cancelled; the broker's own exits report only the fill.
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