Repository navigation
Closed
Milestone
Description
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
OnBarsinput, 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
- 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. - Extend the worker's
OnBarsinput to include the completedbarsand an orderedeventslist (empty is allowed). Keep the existing length-prefixed JSON framing, loopback-only transport, timeouts and strict field validation. - 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.
- 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.
- 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
OnBarscall 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 ./...andmake checkpass. PR documents any deliberately deferred feedback fields.
Explicitly deferred
- Immediate/asynchronous push notifications and a separate event stream.
- Authoritative position snapshots or account/portfolio snapshots (evaluate separately after this increment).
- Registration/RunID negotiation, Trader service listener, durable journal (Trader: journal every run with durable RunID results (first increment) #702), REST run management (Strategy Protocol: read/control completed and active runs via REST #700), remote authorization/TLS, registry and alternative binary transport.
- Stop amendment/trailing implementation and generalized study/indicator results.
Development cadence
Build → test → review → decide. Do not attempt all the unresolved protocol questions or broader #690 scope in this issue.
Metadata
Metadata
Assignees
Labels
No labels
Activity
[-]Strategy Protocol: return broker feedback and position context to strategies[/-][+]Strategy Protocol: deliver execution feedback with the next OnBars[/+]rustyeddy commentedon Nov 21, 2026
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), thenstrategy.onBars. Returned orders are handled after that, inhandleOrder.order.history(orderEvent{state, time, reason});order.recordis the only writer.trader.rejectedand never get an id. Orders the broker fills, rejects at the fill or cancels joinbroker.completed(append-only). The broker's own protective stop, take profit and closeout orders are incompletedwithreason != reasonStrategy.Timing (this is what gives no look-ahead and no leak)
Events are collected inside
onFrameafterbroker.onFrame(f)and beforeonBars. A request therefore carries:It never carries anything caused by the orders returned by this same callback: they are handled after
onBarsreturns 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 towarmer:feedbacker { feedback(events []feedbackEvent) }.onFramecalls it just beforeonBars, 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 nextOnBars.Collector (new
feedback.go, root). The trader getswatched []*order(appended inhandleOrderbefore submit, so a sizing rejection is seen),sent map[*order]intandexitsSeen int(a cursor intobroker.completed). It emits: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):timekindaccepted,filled,rejected,cancelledidrefOrder.Ref, echoed; empty for the broker's own exitsinstrument,action,directionunitspricecausestrategy,stop loss,take profit,margin closeout: tells a protective-stop exit apartreasonExcluded: account, balance, positions, margin and any other stateful snapshot (deferred in the issue).
{"bars":[...],"events":[...]}with the same strict decoding, framing, deadline and size cap.eventsis required and may be[](missing ornullis an error, like the orders list).Client.OnBars(ctx, bars, events); theServe/ListenAndServecallback becomesfunc(bars, events) ([]Order, error).Ordergains an optionalrefstring that is echoed on its events. The adapter keeps amap[*order]string; the domainordergets no new field.Changes
strategy/strategy.go,client.go,server.go:Event,Order.Ref, events in the request, new signatures, the required-list check.strategy.go(feedbacker),trader.go(onFramecall,handleOrderappends towatched), newfeedback.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.Tests
stop loss(theb1-stop-wick/b2-stop-crossfixtures); take-profit and closeout causes; broker exits' submitted/cancelled not delivered; a cancelled strategy order is delivered.Eventandrefround trip; null/missingeventsis an error; strict decoding of the request.feedbackertoo) 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 md5195e457a21def1223e7181c86cb824a4unchanged.Process
Branch from the issue (
gh issue develop 698), one PR withCloses #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
feedbackerinterface (mirrorswarmer) rather than adding events to theonBarssignature, which would touch about 20 implementers mechanically.Order.Refechoed on events, rather than the worker matching a rejection by instrument/action/time.accepted,filled,rejected,cancelled; the broker's own exits report only the fill.Deliver execution feedback with the next OnBars (#698)
Deliver execution feedback with the next OnBars (#698) (#713)