Live mode and its limits

Live mode and its limits

The simulator is one implementation of the engine’s venue interface, not part of the strategy. The IBKR implementation sits behind the same interface and maps canonical orders to Client Portal API requests, then maps broker order, fill, position and account reports back into the engine’s vocabulary. This is why OnBar, OnFill, ctx.Position, and ctx.Account have the same shape in a backtest and at a broker.

The command-line switch is --mode live; --mode backtest is the default. A live invocation adds the venue endpoint and its durable reconciliation ledger:

bin/algo run ... \
  --mode live \
  --venue-url http://127.0.0.1:5000 \
  --venue-emulated \
  --ledger var/orders.json \
  --on-orphan exit

--venue-account can pin an IBKR account; when omitted the adapter asks the venue for the selected account. The ledger gives orders durable canonical references under a persisted deployment identity (The order ledger; --deployment names the label, --ledger-migration admits a ledger written before identity existed) and lets startup fold the venue’s executions into it and compare expected orders and positions with the venue (The execution fold). The only current orphan policy is exit: an unexplained broker order refuses startup rather than being adopted or ignored.

This build’s live mode is an integration and reconciliation harness, not yet a general real-time runner. It requires --venue-emulated, one series per traded symbol or contract, bar resolution, no replication, no intra-bar path, and a --limit-fill other than through (a deployed member on its desk’s SIM clock carries all three; see Fill settings on a desk). The supplied bin/ibkr-emulator makes that path deterministic for testing. A non-emulated real-time feed and several live corporate-action cases remain deferred; the engine rejects them explicitly. Live market data comes from Databento only, and only through marketfeed’s gateways (The live source); IBKR is the order venue, not a live data source.

A live run can hold several series (GLE-1385 8a). The loop steps the emulator once for each bar and names the bar’s symbol: POST /admin/tick with {"symbol": "MSFT", "through": "2026-01-02T14:32:00Z"} advances that symbol’s bars that close at or before through, and answers with the close of the symbol’s last observed bar. If that close is not the bar’s, the run stops, so a fixture that does not hold the run’s bars fails at the first step instead of filling orders at other prices. The same check refuses a run on an emulator that an earlier run has already played; POST /admin/reset rewinds it. At start the emulator observes only the first bars that close earliest; a series that starts later is advanced from its first bar when the run reaches it. A tick without symbol still moves every symbol one bar. Two series on one traded symbol, such as ES 5m beside ES 1d, are refused: a backtest fills the symbol’s orders on both series’ bars, and the emulator holds one bar series per symbol. A series the strategy declares for reference only is data. Its bars reach the strategy, it steps nothing at the venue, and the venue is never asked for its symbol.

A live venue applies its own GTC rule, so --gtc-expiry configures the fill simulator alone (GTC quarter-end cancellation): a live run given a non-default value prints one operator note, algo: --gtc-expiry ibkr-quarter configures the fill simulator; the live venue applies its own GTC rule and the ledger records each GTC order's deadline regardless, and its report’s simulator: line is unchanged (no simulator ran; the summary records never). What the live loop does instead (I13a, GLE-374): the ledger line of every GTC order it emits records the venue’s deadline, gtc_deadline, the last calendar day of the quarter after the submission bar’s trade date (absent on a non-GTC order and on lines written before the field existed), so a restart keeps it; and a cancel the adapter observes at the venue, which it reports as Explicit when the run asked for it and as Venue otherwise (Tickets and cancels at the IBKR venue), is delivered to the strategy as GTC_EXPIRED when the order’s ledger line carries a deadline, the loop is on a bar whose trade date is on or after it, and the loop did not itself ask the venue to cancel that order. “On or after” because IBKR cancels at the close of the deadline’s final trading day, so a daily-bar run observes the cancel on the deadline’s own trade date, while the emulator produces it before the next bar; a strategy’s own cancel on the deadline date stays Explicit, and an unrequested one before the deadline stays Venue. The end-of-run sweep is the loop’s own: its cancels carry Shutdown and are marked as requested, so a run whose last bar is the deadline date ends with a Shutdown cancel, not a GTC_EXPIRED one, in both loops. Without a ledger nothing is recorded and an observed cancel keeps the adapter’s reason. The emulator takes the same setting in its JSON config, "gtcExpiry": "never" or "ibkr-quarter" (empty is never; another value refuses startup naming it), mapped onto its embedded simulator; it is part of the backtest/emulator cross-check contract like capital, commission and slippage, and must equal the backtest’s --gtc-expiry for the two to agree. An order seeded through /admin/seed anchors at the seed clock’s trade date; a prior lifecycle’s true deadline lives in the engine’s ledger, not in the double.

The emulator serves the numeric account summary a live trade director reads (GET /iserver/account/{accountId}/summary, The live account), laid out as IBKR’s documented example, from its embedded simulator: net liquidation is the cash plus the positions at their last close times their point value, and initial and maintenance margin are 0, as for a cash account. An account other than its own is refused with HTTP 400. POST /admin/account-summary with {"status": 503, "body": {...}} makes it answer with that status and body instead, verbatim, until {"clear": true} or a reset: a test affordance, not an IBKR endpoint.

The emulator’s brokerage session is live unless POST /admin/session says otherwise (GLE-1380). {"state": "down"} ends it, as a timeout or IBKR’s nightly reset does; {"state": "competing", "message": "TWS logged in"} has another login take it over. While it is not live:

  • /iserver/auth/status and the keep-alive’s iserver.authStatus answer authenticated and established false, connected true, competing true for a competing session, and the message given, if any.
  • Every other /iserver endpoint answers HTTP 401 with {"error": "not authenticated: <message>"}, the message given or else brokerage session ended or competing session. An order sent then is not taken.
  • The /portfolio and /portfolio2 endpoints, the keep-alive and the admin endpoints still answer, and /admin/tick still moves the clock.

{"state": "live"} or a reset brings the session back. The 401 body and the portfolio endpoints’ answers are the emulator’s choices, not checked against IBKR. It is a test affordance, not an IBKR endpoint, meant for AlgoDesk’s SIM session faults on the emulator (GLE-1493).

POST /admin/liquidate has IBKR liquidate a position itself (GLE-1500): {"symbol": "AAPL", "quantity": 25} sells 25 of a long or buys 25 of a short, at once, at the symbol’s last price, or at "price" when given. A quantity of 0, or none, closes the whole position out. The fill pays the configured commission and is on no order of the client’s: the trades list it with no order_ref and liquidation_trade "1", and the live orders never list its order. Every other trade says "0", as IBKR sends it. An unknown symbol, a flat position or a quantity over the position is refused with HTTP 400, changing nothing. The answer gives the execution id, the side, size and price, and the position after it. It is a test affordance, not an IBKR endpoint, for AlgoDesk’s split of a liquidation across its members (D17).

A symbol may take its bars from the emulator’s client rather than from a file (GLE-1493): "feed": true in its JSON config, with no "barsPath". Its series starts empty, and POST /admin/bar with {"symbol": "AAPL", "bars": [{"tsOpen": "2026-01-02T14:30:00Z", "tsClose": "2026-01-02T14:31:00Z", "open": 100, "high": 100.5, "low": 99.5, "close": 100.2, "volume": 1000}]} appends bars to it. Each bar must close after the one before it and after the symbol’s last; a bar whose high is below its low, or with a price that is not a number, is refused, and a refused post adds none of its bars. The answer gives the bars the series holds and how many the clock has passed. /admin/tick then moves the clock through them as through a file’s, so an order resting at the emulator fills on the bar that reaches it. A reset empties the series for the client to feed again from its start. A fed symbol declares no corporate actions: those due by the first bar are passed over at start, which needs that bar before any client posts it. AlgoDesk’s SIM clock uses this to run the emulator, since it learns each bar only as its members reach it.

Each symbol in the emulator’s JSON config may set "pointValue", the contract’s multiplier as the data adapter reports it to a backtest, for example 50 for ES (GLE-1448). Absent, it is 1, a stock’s. The embedded simulator books a fill as price × quantity × point value, as a backtest’s does, and the ledger, the positions and the account summary value a position the same way. A future configured without it moves cash by points, so its account and the live summary disagree with the backtest by the multiplier; fills and positions are right either way. A negative value refuses startup.

A live run’s summary (the report’s equity and the BENCH line’s) is read back from the venue: its cash, and its positions at the last close of the run’s bars, times the point values the adapter reported for the run. A continuous series’ bars carry its logical symbol, so the contract it holds is marked at that contract’s own last bar (GLE-1448). Realized P&L is replayed from the venue’s fills with the same point values. On the emulator with the right point values, a live run ends with its backtest’s equity and realized P&L. A desk member shares its account with the deployment’s other members, so its summary does not read the account’s cash (The member’s summary, GLE-1467).

Two settings in its JSON config shape the account (GLE-1390). "baseCurrency" (default "USD", three capital letters) is the currency GET /portfolio/accounts names for the account. The ledger and the summary’s cash rows use it too. It is only a label: the emulator holds its cash in one currency and converts nothing. "summaryShape" lays out the summary’s cash balances. "documented" (the default) gives the currency row and a "Total (in XXX)" row, as IBKR’s example does. "single-currency" gives the currency row alone, as a single-currency paper account answers. Any other value of either setting refuses startup.

"baseCurrency": "AUD",
"summaryShape": "single-currency"

A market-on-close order never goes to IBKR as an MOC ticket. The engine holds it until its send time and sends a Day market order (Market-on-close orders, GLE-1375); the IBKR adapter refuses an MOC that reaches it. The emulator, like IBKR, refuses an MOC ticket for a future (HTTP 200, {"error":"MOC orders are not supported for futures"}; the emulator’s own wording, not checked against IBKR’s). POST /admin/arrival with {"at": "2026-03-11T19:58:04.012Z"} stamps the arrival instant of the market orders placed before the next /admin/tick: each such order waits until that instant and fills at the first price at or after it, as a backtest fills a held MOC, rather than at the next bar’s open. The stamp lasts until the next tick or reset; it is a test affordance, not an IBKR endpoint. MOO, LOC and StopTouch have no live mapping: the venue rejects each such order at submission and the strategy receives a rejection cancel.

The emulator takes and refuses an order ticket as the paper account did on 7 Nov 2026 (Tickets and cancels at the IBKR venue): the same order type spellings, the same price fields, and the same refusals with the same HTTP status and error text, on /orders and on /admin/seed alike (since GLE-1366 and GLE-1376). It also serves GET /iserver/contract/{conid}/info-and-rules, the contract’s type and its orderTypesOutside, and an order’s status carries outside_rth. Each symbol in its JSON config may set "secType", "STK" (the default) or "FUT"; "orderTypesOutside", IBKR’s rule names (default for a future the paper account’s futures list, for a stock AAPL’s); and "regularHours", for example {"timeZone": "America/Chicago", "open": "08:30", "close": "15:00"}. A future’s stop, stop-limit or trailing-stop order sent without outsideRTH then sits out every bar outside those hours, as IBKR would hold it: it neither triggers nor, for a trailing stop, moves its trail. With the flag, or on a stock, or with no regularHours, it is evaluated on every bar. A bar is inside regular hours when it opens and closes on the same local day within them. The embedded simulator holds an order through its Hold hook, which no backtest sets.

A symbol may also set IBKR’s names for it (GLE-1464), so the emulator answers a contract search as a real gateway does (Finding contracts at the IBKR venue):

  • "ibkrSymbol": IBKR’s search symbol, for example "ES", or "SI" for Micro Silver.
  • "tradingClass": the trading class. It defaults to the IBKR symbol; Micro Silver’s is "SIL".
  • "contractMonth" (yyyymm) and "maturityDate" (YYYYMMDD): required for a future.
  • "underlyingConid": optional, the conid IBKR’s search answers for the root. Without it the emulator assigns one from 900000000.
{"symbol": "fut:XCME:ES:Z26", "conid": 495512563, "exchange": "CME", "secType": "FUT",
 "tick": 0.25, "barsPath": "es.csv",
 "ibkrSymbol": "ES", "contractMonth": "202612", "maturityDate": "20261218"}

A search with secType=FUT then answers the root, with a FUT section listing its contract months (DEC26;MAR27). GET /iserver/secdef/info lists one month’s contracts on the request’s exchange, each with its maturity date and trading class. As at IBKR, a request without an exchange, or for a month or exchange with no contract, is answered HTTP 500 {"error":"No Contracts retrieved "}. "engineNamed": true at the top of the config lists every symbol that sets no IBKR names under names of its own engine symbol (Finding contracts at the IBKR venue). A search with secType=STK finds a stock by its IBKR symbol, or by its engine symbol when it sets none. A search with a secType knows IBKR’s names only and answers anything else with {"error":"No symbol found"}; a search without one still finds a symbol by its engine name.

The IBKR emulator’s day lists

The emulator’s orders list and trades list cover one trade date (GLE-1494). IBKR’s reference, read on 12 Nov 2026, says the orders list “Returns open orders and filled or cancelled orders submitted during the current brokerage session”. Of the trades list’s days it says: “If omitted, only the current day’s executions will be returned.” The emulator’s trade date is that of the last bar its clock advanced, sim.BarTradeDate: the bar’s session trade date when it has one, otherwise the UTC date of the instant just before its close. The emulator’s bars carry no session, so it is the UTC date.

  • GET /iserver/account/orders lists the working orders and the orders that ended (filled, cancelled or rejected) on the current trade date, in the order they were placed. An order that ended on an earlier date has left the list, but GET /iserver/account/order/status/{orderId} still answers for it.
  • GET /iserver/account/trades lists the current trade date’s fills. With days=N it adds the fills of up to N earlier trade dates, at most 7, as IBKR does. The earlier trade dates are the dates the clock has stood on, so a weekend counts as none. A days that is not a whole number is refused with HTTP 400.
  • A fill counts as read once a trades answer has included it. A tick that would move the clock to a later trade date while a fill is unread is refused with HTTP 409, and moves nothing: {"error": "tick: 1 fill of 2026-01-05 is unread: read GET /iserver/account/trades before the clock moves to 2026-01-06", "cursor": 3, "advanced": 0, "done": false, "close": "..."}. The fill is not left for the reconciliation to find. A tick of several bars stops before the first bar of the later date. Its answer is the same 409, and advanced counts the bars it moved before it stopped. Read the trades, then send the tick again. A trades request the brokerage session refuses reads nothing.
  • A session drop does not change either list: only the trade date scopes them. Whether IBKR’s orders list loses the orders that ended before a re-authentication is a paper-account check on GLE-1391.

The live loop polls the venue after every step, which reads the trades. So only a step that moves a symbol several bars can meet the refusal: a series that starts later catching up, or a roll stepping a contract to its cut. The loop then polls and sends the step again. The poll’s events reach the strategy with the step’s other events. AlgoDesk’s SIM clock steps the emulator one bar at a time and polls after each.

The refusal guards fills only. An order cancelled on one trade date leaves the orders list when the clock moves to the next, read or not, and the venue adapter sees a cancel only on that list. So a client polls after it cancels and before it steps. The live loop polls after a bar’s cancels, and a roll that cancelled orders polls before it steps a contract to its cut.

A reader that asks for every execution asks for the current trade date and the 7 before it (days=7). On the emulator, as at IBKR, that answer leaves out a fill made more than 7 trade dates earlier. The venue adapter remembers every execution a trades answer gave it while it runs, and its fill reports add those the answer leaves out, oldest first. So the live summary of a run longer than 8 trade dates still counts every fill. A restarted run’s adapter knows only what it has read since it started: its reconciliation folds the days=7 answer, and the ledger holds the earlier fills.

Before GLE-1494 the emulator listed every order and fill it had taken since it started, so each poll cost more as a run went on. On 12 Nov 2026 an AlgoDesk SIM session of smacross on a month of AAPL minute bars took 68 s on the emulator.

The account in a live run

A live run pushes the strategy its own account before each bar’s decision, as a backtest pushes its simulator’s (GLE-1516). So ctx.Account(), kit.Equity and kit.BuyingPower read the same figures live as in the backtest of the same bars, and a strategy that sizes from its equity trades the same quantity. The account is the run’s own mark, on every live venue, the desk included:

  • cash: the run’s capital (--initial-capital), less what each of its fills cost and their commission, plus the cash of the corporate actions it fired, booked in time order with the simulator’s own expressions;
  • net liquidation: the cash plus each open position at its symbol’s last close times its point value (a continuous series’ held contract at its own close; a contract a roll’s legs just opened, until its first bar, at their fill price). It is the account’s one balance, in the base currency, and NetLiquidation;
  • Reported is false, and the account carries no margin, so kit.BuyingPower is the net liquidation.

The run counts the fills it books: its own, the desk’s operator and flatten fills, a roll’s legs, and those the reconciliation finds. Each counts once. A run that starts again counts the fills of its earlier sessions too, from the venue’s fill list at its start: at the desk the member’s own, elsewhere those its ledger owns (every fill without a ledger; the IBKR venue lists 7 trade dates of them). The run asks the broker for nothing more per bar, so IBKR’s paced account endpoints are not touched. A desk member’s account is its own book, never the account it shares with the other members, as its summary is (GLE-1467). A corrected execution at the desk replaces the fill it corrects in the account as in the ledger (GLE-1515; A corrected execution). The account keeps the earlier fill’s commission.

On a one-currency, one-symbol run the account is the backtest’s to the bit. Across several symbols the marks add in symbol order, as the simulator’s do, and fills booked at one instant may add in another order and differ in the last bit. A position in another currency is marked in its own currency, with no conversion. A live account is the run’s own, so it does not see the broker’s other activity: the live summary of a run on IBKR direct reads the broker’s cash, which can differ. A strategy on a CSV wire receives no account, live or in a backtest.

Continuous futures in live mode

A live run can trade a continuous futures series on the emulated venue (GLE-1385 8b; the owner allowed continuous live runs on 9 Nov 2026) or as a member of a deployment against the desk (GLE-1447). It runs under order lifetime v1, and since GLE-1446 under v2 and with a trade director too (Under order lifetime v2), on a real-time feed as well since GLE-1503. The symbol can be spelled as a bare root such as fut:XCME:ES or as a marketfeed composite such as fut:XCME:ES:cont. The run follows the composite it fetched at start, as a backtest does. The strategy sees the same bars, roll notices, fills and cancels as a backtest of the same data. For a strategy author’s walk through a live roll, see Contract rolls in a live strategy.

Each bar steps the held contract. The emulator steps on the dated contract the series holds at each bar, at that contract’s raw prices. So the emulator’s config lists every contract the series holds during the run ("secType": "FUT" and its tick), each with its own bars. On a bar of ES’s H26 stretch, the loop sends POST /admin/tick with {"symbol": "ESH26", ...}, not the series’ symbol. The strategy’s orders go to the held contract, translated from the series’ adjusted prices.

The roll at a cut is a market roll (GLE-1447). Every live mode, SIM, PAPER and LIVE, makes it the same way, at the venue, in the backtest’s order, before the venue steps to the first bar after the cut:

  1. The roll cancels the strategy’s working orders on the outgoing contract. These cancels are the engine’s own, and the strategy is not told of them. It then waits until the venue confirms each cancel (below).
  2. It sends the roll as two DAY market orders, the outgoing contract’s close first, then the incoming contract’s open. They are labelled roll/<symbol>/<cut>/close and roll/<symbol>/<cut>/open, and flagged as roll legs: to the desk with DeskSubmit.roll_leg, to the emulator with POST /admin/roll-legs.
  3. It waits until the venue reports both legs filled. The engine makes no bar and supplies no price: the venue fills each leg at its own price for the contract at the cut. On PAPER and LIVE that is the exchange’s. A SIM venue fills it from its own data. The desk’s SIM clock has none of its own, so there the member sends it (below).
  4. It places the strategy’s orders again on the incoming contract, at their translated levels, decided at the cut.

The strategy is told of the roll and of its orders’ new contract, and never of the legs, exactly as in a backtest. Each leg’s fill goes to stderr against the served seam, the price the backtest’s leg fills at:

algo: roll leg sell 1 ESH26 filled at 6712 against the served seam 6712.25: slip -0.25

The legs on the emulator: marks. Each contract in the emulator’s config may carry "marks", its prices at given instants. A fixture made from a backtest sets them to the served seam: the outgoing and incoming contracts’ prices at the cut. Then the live run rolls with the backtest’s trades, to the cent.

{"symbol": "ESH26", "conid": 495512551, "secType": "FUT", "tick": 0.25, "barsPath": "ESH26.csv",
 "marks": [{"at": "2026-03-15T22:00:00Z", "price": 6712.25}]}

POST /admin/roll-legs with {"orderIds": ["1000004", "1000005"]} flags working market orders as roll legs. A step that reaches a contract’s mark at or after the instant a leg was flagged fills the leg there, at the mark less or plus the configured slippage. The contract’s other working orders are evaluated at that mark too, as the backtest’s synthetic cut bar evaluates them. A mark that fills no leg is passed over. A roll leg is exempt from the cross-symbol rule. The endpoint refuses, with HTTP 400, an order that is unknown or not a working market order, and then flags none. It is a test affordance, not an IBKR one. POST /admin/roll-bar is retired.

Cancels the emulator holds pending. The emulator’s config may carry "cancelRaces", to test a roll’s wait for its cancels. Each names an order by its order_ref, the first order with that ref the emulator takes. Its cancel is answered as submitted, the order still works, and the orders list shows it PendingCancel for the next reads reads. At the read after those the cancel takes effect, or, with a fillPrice, the order fills there at that price instead: the cancel lost a race to the market. With no reads and a fillPrice, the order fills as the cancel arrives, and the cancel is refused as one for a filled order.

"cancelRaces": [{"orderRef": "tp", "reads": 3}, {"orderRef": "stop", "fillPrice": 6650}]

The cancels are confirmed before the legs go (owner ruling of 12 Nov 2026). A live venue answers a cancel as pending, and the order’s end arrives with a later poll. Until then a desk’s gate counts the order as working: a close leg with the same terms as a cancelled exit would be refused as a duplicate, or checked as an opening. So the roll polls the venue until none of the orders it cancelled is working or pending cancel, and only then sends the close leg. This applies at every live venue: the emulator, and the desk on any clock.

  • An order that filled before its cancel took effect is not placed again. The roll sizes its legs from the position after the fill, and a flat position needs no legs. The fill reaches the strategy as any fill does. An entry that filled may have put its attached orders to work on the outgoing contract: the roll cancels them too, and carries them as the position’s children. A line on stderr says what happened:

    algo: roll ESH26->ESM26: tp filled before the roll's cancel took effect; the legs move the position after the fill: 1
    
  • The wait counts inside roll_deadline, which runs from the roll’s start. A cancel still unconfirmed at the deadline fails the roll as a leg that does not fill fails it: the run stops with a roll partial failure at its cancel_from step, no leg sent, and a restart’s catch-up roll finishes the roll.

    engine: the roll's cancels were not confirmed within 2m0s of the roll, so no leg was sent: ESH26 1000002 (pending_cancel) still works; a restart's catch-up roll finishes the roll
    

The owner turned down the other way: a gate that ignores pending cancels for a roll leg. If the cancelled order filled after all, the position would be closed twice.

How the roll waits.

  • On an engine-stepped venue (the emulator, or the desk on its emulator broker port in SIM), the roll steps each contract to its instant at the cut, the outgoing first. A leg that has not filled then fails the roll: the venue had no price for the contract at the cut.
  • On a desk on the wall clock (PAPER and LIVE), the loop steps nothing. The roll polls the desk until both legs have ended, up to the deployment’s roll_deadline (default two minutes) from the roll’s start, the wait for its cancels included. It fires at the later of the cut and the incoming contract’s ETH open, so that contract’s market is open when the wait begins (Running live on a real-time feed). A member on the wall clock needs a real-time feed ("feed": "stream"), and a continuous series on it needs the roll rebase, which is on unless the deployment sets "roll_rebase": false. One on history is refused.
  • On the desk’s SIM clock (GLE-1380), which fills against the bars its members send, the roll awaits each contract’s cut instant, the outgoing first, with one flat bar of the contract at its served price at the cut: the bar the backtest’s simulator fills the leg on (owner ruling of 11 Nov 2026). The desk fills the leg there, as the backtest does. Only then does the run await the bar the roll fired on. The run’s other awaits carry a continuous series’ contract bars, which the backtest’s simulator advances on, not its adjusted bars.

A leg that does not fill (owner ruling Q4). The roll cancels every leg still working, and the run stops with a roll partial failure at its advance step. The error names each leg’s end:

engine: the roll's leg on ESM26 (venue order 1000005) did not fill at the cut 2026-03-15T22:00:00Z: within 2m0s of the roll; the roll's legs: ESH26 1000004 filled, ESM26 1000005 cancelled now

When the close leg did not fill, the position is still on the outgoing contract, and a restart’s catch-up roll (below) finishes the roll. When only the open leg failed, the member is flat at the venue, and the operator restores the position. The desk’s alarm on a failed roll comes with GLE-1379.

What stays refused. A run under order lifetime v2, or with a trade director, which needs v2, is refused before any adapter or strategy spawn without a ledger. A v2 roll addresses each order by its attempt, and a live run’s events carry their attempts from its ledger. algo run --mode live always has one (--ledger, or a deployment’s desk journal). The message names the symbol, says live continuous futures runs are refused, gives the reason, and suggests a dated contract such as fut:XCME:ES:Z26 instead. On a real-time feed (--feed stream) a continuous series needs the roll rebase, on by default since GLE-1502, which runs under either order lifetime since GLE-1503.

Live mode also refuses:

  • A contract that feeds two series. For example, a continuous series beside one of its own dated contracts, or two ranks of one root that share a contract. A backtest fills a contract’s orders on every series’ bars, while the emulator holds one bar series per contract. This is the rule for two series on one traded symbol.
  • A restart’s catch-up roll on the desk’s SIM clock (below). Its close leg fills on a bar of the outgoing contract after the cut, which the member’s series does not hold to send the desk. The run stops before its first bar; restart the replay from before the cut.

A restart (GLE-1385 8c). A live run with a ledger starts from the position and working orders it finds at the venue (Equities and live reconciliation). What it finds on a continuous series’ contracts becomes the series’ own:

  • On the contract the series holds at its first bar. The strategy adopts the position and the orders on the series’ symbol, at adjusted prices. The average cost and each order’s levels move by that contract’s adjustment, as a fill’s price does. The series tracks the orders, so a later roll carries them onto the next contract.

  • On a contract the series rolled out of during its warm-up. The engine was down across a cut. The strategy adopts the book in the same way, at that contract’s adjustment. Then, before the first bar reaches the strategy, the engine makes one catch-up roll onto the contract the series holds, however many cuts it missed:

    • the strategy gets one roll notice, from the contract it held to the one it holds now;
    • the orders on the outgoing contract are cancelled, the strategy is not told of those cancels, and the orders are placed again on the incoming contract at their translated levels, as at any roll;
    • the two DAY market legs fill at market on the next bar of each contract, not at the cut. The difference from the seam is roll slip.

    On an engine-stepped venue the loop steps the outgoing contract through the series’ next bar (POST /admin/tick with that contract’s symbol, or a DeskStep through the desk), then checks that both legs filled. So the emulator’s config must hold the outgoing contract’s bars past the cut, or the run stops and names the contract. On the wall clock the venue moves itself. The outgoing contract is outside the run’s universe, so the venue looks it up before reconciliation.

A restart refuses to start when it finds a position or working order:

  • on a contract the series has not reached yet, for example after the operator rolled early by hand. This is reconciliation invariant 5, and the message names the contract held and the one expected;
  • on a contract the series rolled out of before its warm-up, because the restart has no cut to roll it at. Roll it by hand, or warm the run up over the cut;
  • on two contracts the series rolled out of;
  • on a contract two order-taking ranks of one root share, because the venue’s net position does not say whose it is.

Give the emulator each contract’s "pointValue": its account then books the series’ fills in dollars, and a live run ends with its backtest’s equity (GLE-1448). An @ES alias, the retired registry’s symbol, is no continuous form since ER5 and takes the plain path. Before GLE-1385 8b, every live continuous run was refused (owner decision 2026-10-04, GLE-228 Decision 7).

A live continuous roll under order lifetime v2

Since GLE-1446 a live run under order lifetime v2 rolls a continuous series as its backtest does, with or without a trade director. It runs on a venue fed from history: the emulator, and the desk on its engine-stepped and SIM clocks. Since GLE-1503 it runs on a real-time feed too (--feed stream, and so the desk’s wall clock), where the series needs the roll rebase (on by default since GLE-1502). At each roll the engine then restates the strategy’s working view, its race guard’s attempts and its trade director’s levels onto the incoming basis before it places anything again, as the backtest does (Re-adjusting at each roll).

The roll is the market roll above. Under v2 the strategy’s orders go through it as they do in a backtest (Order lifetime v2 across a roll):

  • A series order is placed again as a new attempt. Each order on the series’ symbol goes to the incoming contract under its label, at an attempt past every one the label has used. The strategy gets one OrderUpdate per order naming the attempt it replaces. It is never told of the roll’s own cancel of the old attempt.
  • An order pinned to the outgoing contract is cancelled, with CANCEL_REASON_ROLL.
  • Which orders go at the cut follows the simulator’s own rule (FillsFlatBar), so the live plan is the backtest’s. An order that would fill at the cut’s price is placed after the cut, so its first chance is the first real bar of the incoming contract (GLE-627).
  • An order the venue ended itself (a Day order at the session close) is read from the venue before the roll reads its book, and is not carried. The engine models no calendar of its own live.
  • The roll’s traffic is not paced by the engine’s transport queue, so the legs are not delayed. The desk paces at its end.
  • A moved order is moved on the held contract. A strategy that moves a working order (cancel and a same-label successor in one reply) has it modified in place where the venue can (GLE-1419). On a continuous series the modification is priced on the held contract, as a submission is. A later roll places the moved order’s terms again, not the ones it replaced.
  • A timer fires as in a backtest: every roll due before its instant fires first, so a timer past a cut sees the incoming contract.
  • A restart adopts the orders the venue still works under the labels and attempts the ledger holds for them, so a later cancel, move or roll addresses them.

Two failures stop the run with a roll partial failure:

  • A roll the schedule made late. When the outgoing contract expired before the cut, the roll trades nothing:

    continuous: roll LEJ26->LEM26 partial failure at step order_status (completed: none): continuous: roll LEJ26->LEM26: LEJ26 expired at 2026-03-16T18:00:00Z, before the roll's cut at 2026-03-17T13:30:00Z (the schedule rolled late); a live roll does not trade an expired contract: settle the position at the venue, then restart
    
  • A placement the venue does not answer. The roll’s book keys each order it carries by its venue id, and an unanswered submission has none. The run stops, and a restart reconciles the order with the venue:

    continuous: roll LEJ26->LEM26 partial failure at step resubmit_at_cut (completed: order_status, position, cancel_from, open_legs; unreplaced: tp, stop): continuous: roll LEJ26->LEM26: resubmit "tp" (LEM26): the venue's answer to the re-placement of "tp" on LEM26 is unknown (broker port timed out); a restart reconciles it with the venue
    

With a trade director, the roll’s legs and placements are decided by the director as in a backtest. A live run has no marks yet (GLE-548), so a rule that reads one fails closed there, continuous or not.

A live strategy receives its own account before each bar, as in a backtest (The account in a live run), so a strategy that sizes from equity sizes as its backtest does across a roll.

A demo for a roll at a real venue: rollhold

The demo rollhold (strategies/demo/go/rollhold, GLE-1447) holds a position through every roll of its series with a protective stop working. So each roll has an order to cancel, and to wait for the venue to confirm, before it sends its legs, and an order to place again on the incoming contract after them. It is the strategy for the PAPER acceptance of a live roll: MCL Z26→F27, whose cut is 23:00 UTC on 17 Nov 2026 (owner’s rulings of 12 Nov 2026).

  • On the first bar of the run’s primary symbol it buys Lots (1) at the market. If the entry is refused, it buys again on the next bar, under a numbered client id (entry-2026-11-17-2). A live run on a real-time feed refuses openings while it catches up from the archive’s last bar, which its first bar always is, and a desk refuses an opening while its quote is older than quote_age.
  • Once long, it keeps one sell stop for the whole position working, GTC, StopPct (20) percent below the close of the bar it placed the stop on. The level is rounded down to a whole tick: Tick, or the instrument’s tick size when Tick is 0. A run with neither stops at that bar.
  • It never moves the stop and never trades again. If the stop fills, or the position is closed another way, it stays flat. If the venue cancels the stop while the position is held, it places a new one on the next bar. A short position stops the run.
  • It finds its entry and its stop by side and type, not by label, so it recognises the stop a roll places again and the one a restart adopts.
  • A stop working while it is flat protects nothing, so it cancels it. A restart can find one, for example after the operator closed the position by hand.
  • What it has sent lives in the process. A restart after the stop has filled starts flat and buys again.

It runs under either order lifetime. On a live run on a real-time feed, a continuous series needs the roll rebase, under either order lifetime (GLE-1503); it is on unless the run turns it off (GLE-1502). There the SDK restates the stop at each roll. The engine cancels the stop on the outgoing contract, waits for the cancel to be confirmed, sends the legs, and places the stop again on the incoming contract at the restated level. Over 2018 on the archive:

bin/algo run --strategy bin/rollhold --symbol fut:XCME:ES --bar-interval 1d \
  --date-from 2018-01-01 --date-to 2018-12-31 --lifetime v1
[rollhold] INFO: rollhold: 2018-01-02 buy 1 fut:XCME:ES at the market
[rollhold] INFO: rollhold: bought 1 fut:XCME:ES at 2693.75 (entry-2018-01-02)
[rollhold] INFO: rollhold: 2018-01-03 long 1 fut:XCME:ES, sell stop GTC at 2167.25 (close 2709.25)
[rollhold] INFO: rollhold: fut:XCME:ES rolled ESH18 -> ESM18 at 2018-03-11T22:00:00Z, gap 4.75; the stop is now at 2172
[rollhold] INFO: rollhold: fut:XCME:ES rolled ESM18 -> ESU18 at 2018-06-10T22:00:00Z, gap 3.75; the stop is now at 2175.75
[rollhold] INFO: rollhold: fut:XCME:ES rolled ESU18 -> ESZ18 at 2018-09-16T22:00:00Z, gap 5.25; the stop is now at 2181
[rollhold] INFO: rollhold: fut:XCME:ES rolled ESZ18 -> ESH19 at 2018-12-16T23:00:00Z, gap 3.5; the stop is now at 2184.5
[rollhold] INFO: rollhold: stop-2018-01-03 cancelled (reason 5)

The run makes nine fills: the entry and the eight roll legs. With --roll-rebase=false, and under v2, it makes the same nine. The last line is the stop cancelled at the end of the data (reason 5, shutdown). With the rebase off, the roll is logged at the next bar, with no stop level, because the stop the strategy sees stays on the series’ adjusted basis.

Crude can move 20% in two weeks: between 2 and 18 June 2026, MCL fell from 93 to below 73, and the default stop filled. For the PAPER test, start the member a few bars before the cut, so its entry fills and its stop is placed in time.

As a member of a PAPER deployment, the portfolio names bin/rollhold on fut:XNYM:MCL, and the deployment file carries what follows. Start it with --date-from at the current minute: a continuous series on the stream with an open --date-from is refused, its adjustment anchored at 1970 (ADJUST_ANCHOR_UNHELD). The run then catches up from the archive’s last bar, refusing the entry, and buys once it is within a bar of the clock. The desk’s price_collar_away (5% on PAPER) also bounds the stop, so StopPct must be below it: the PAPER test runs "inputs": {"StopPct": 3}. A lake slice for the adapter needs, besides the registry, the root’s manifest and its contracts’ bars, the root’s continuous schedule (continuous/XNYM/MCL) and the last 120 days of the dataset’s definitions (events/GLBX.MDP3/definition), from which the stream’s forward roll calendar lists the contracts.

{
  "portfolio": "rollhold.json",
  "mode": "paper",
  "desk": "http://localhost:7443",
  "feed": "stream",
  "roll_rebase": true,
  "members": {"rollhold-mcl": {}}
}

The desk’s config lists both contracts of the roll as the member names a series’ dated contracts, MCLZ26 and MCLF27, each with marketfeed’s name for its quotes as its feed_symbol (fut:XNYM:MCL:Z26; algodesk GLE-1447). The member’s limits allow one close leg and one open leg of the position’s size.

Finding contracts at the IBKR venue

A real gateway knows a contract only by IBKR’s names, never by the engine’s symbol: it finds no contract for fut:XCME:ES:Z26. So since GLE-1464 a live run asks the data adapter for each instrument’s IBKR contract terms before it shuts the data adapter down. It asks for every symbol the venue trades, and for every contract a continuous series’ warm-up rolled out of, which a restart may find the account still holding (Continuous futures in live mode). The IBKR adapter finds each contract by its terms when it starts:

  • A future. The adapter searches GET /iserver/secdef/search?symbol=ES&secType=FUT. The answer’s FUT section lists the root’s contract months, for example DEC26;MAR27. Then it asks GET /iserver/secdef/info?conid=<root>&sectype=FUT&month=DEC26&exchange=CME for the contracts of the terms’ contract month on the terms’ exchange (else the first exchange the FUT section names). It keeps the one with the terms’ trading class: Micro Silver is searched as SI and kept as SIL. If two remain, it refuses. The contract’s maturity date must be the date of the data adapter’s expiration on the exchange’s clock (exchange_timezone, else UTC). The adapter never picks by maturity month, since CL’s December contract matures in November.
  • A stock. The adapter searches with secType=STK and keeps the hit listed on the terms’ exchange. The contract’s currency at IBKR must be the terms’ currency.

Any of these stops the start-up, naming the symbol:

  • The data adapter gave a reason. venueibkr: "<symbol>" has no IBKR contract terms: <reason>.
  • It served no IBKR message. venueibkr: "<symbol>": the data adapter served no IBKR contract terms for it, so its contract cannot be found at IBKR; the adapter failed to describe it, or predates the terms (GLE-1466).
  • IBKR lists no such contract. venueibkr: IBKR has no contract for symbol "<symbol>" (<why>), for example (IBKR lists no JUN27 contract of ES; it lists DEC26, MAR27), or a trading class or stock listing IBKR doesn’t have.
  • Two contracts match. For example IBKR lists more than one DEC26 contract of SI with trading class SI (conids 22 and 23).
  • The maturity differs. For example `IBKR’s DEC26 contract of ES (conid 11) matures on 20261218, but the data adapter’s expiration is 20261217, so it is not the same contract`.
  • No expiration was served, so the maturity can’t be checked.
  • The currency differs. For example IBKR's contract (conid 41) trades in USD, but the data adapter's terms name CAD, so it is not the same contract.
  • The terms are incomplete. They name a futures root (no contract month), no search symbol, a security type other than FUT or STK, or a stock without its exchange.

When a restart learns the contracts a warm-up rolled out of, it skips a contract IBKR no longer lists, such as an expired month, since the account can’t hold it. Every other refusal stops the restart.

IBKR can say it has no contract in three ways: an empty array, HTTP 200 with an error object, or, from secdef info, HTTP 500 with an error object. The paper account answered a search {"error":"No symbol found"} on 10 Nov 2026. On 11 Nov it answered secdef info {"error":"No Contracts retrieved "} with HTTP 500 for a month it doesn’t list and for a request without the exchange, which it requires. The adapter reads each as no contract, not as a decoding failure.

On the emulator (--venue-emulated) the rules are the same (owner ruling, 11 Nov 2026): a gateway knows no engine names, so neither does the adapter. A symbol whose data adapter served no IBKR message is refused, a run over an adapter that serves none included. file-csv serves terms through its IBKR inputs. The emulator config lists each symbol by IBKR’s names, or sets "engineNamed": true to list every symbol that sets none by its engine symbol. Then a stock is found by a STK search for its own symbol on its exchange, and a future by a FUT search for its own symbol, in contract month 209912, maturing on 20991218. Its data adapter serves those terms: for a future, IBKRContractMonth=209912 and an Expiration on 18 Dec 2099. The far date keeps the expiry out of every run’s window.

Tickets and cancels at the IBKR venue

Since increment I4 unit 4b of the order-lifetime programme (GLE-378, 2026-10-07) the IBKR adapter (engine/venueibkr over internal/ibkrclient) follows IBKR’s Client Portal Web API reference for the order ticket and the cancel, and since I6 unit 3b (GLE-436, 2026-10-08) for the order reply messages IBKR asks it to confirm (Order reply messages, below). The rules hold on both lifetime profiles; a v2 run also passes each cancel answer through to the strategy (Lifecycle turns).

The ticket. Every order ticket carries "manualIndicator": false. IBKR’s ticket schema: “Required for US Futures; indicates if order was originated manually (True) or automatically (False)”. The engine is an automated system and the adapter has no product classification, so it sends the flag on every ticket whatever the product. The ticket’s tif takes IBKR’s documented list, “Time in force of the order ticket (DAY, IOC, GTC, OPG, PAX)”, which has no FOK (nor GTD, which the SDK does not define): the adapter denies an FOK order locally, with a reason naming those five values, before any ticket is sent. The live loop admits only Day and GTC and stops the run on any other time in force before the adapter is called, so the adapter’s denial guards its direct use.

Order types and price fields. Since GLE-1366 and GLE-1376 (2026-11-07) the ticket’s order type and price fields are the ones a paper account accepted. A stop-limit order is STP LMT, as in IBKR’s Web API Stop Limit example, with its limit in price and its trigger in auxPrice. A plain stop is STP with its trigger in price, and a trailing stop is TRAIL with its distance in trailingAmt. Before, the adapter sent STP_LIMIT and put a plain stop’s trigger in auxPrice, and IBKR refuses both, so no live stop or stop-limit order could have been placed. The paper account (DU8898890, 7 Nov 2026, one MES contract far from the market, each order cancelled) answered:

TicketIBKR’s answer
STP LMT, STOP_LIMIT or STPLMT with price and auxPriceplaced; the order status says STOP_LIMIT
STP_LIMIT or TRAILINGHTTP 400 {"error":"Unknown order type"}
STP or STOP with the trigger in priceplaced as STP
STP with the trigger in auxPrice only; STP LMT without auxPrice; TRAIL without trailingAmtHTTP 200 {"error":"Invalid order price fields"}
TRAIL with trailingAmt, with or without trailingTypeplaced as TRAILING_STOP
outsideRTH: true on a future’s STP, STP LMT or TRAILplaced; the order status says outside_rth: true
outsideRTH: true on a future’s LMTHTTP 200 {"error":"invalid order attribute : Outside Regular Trading Hours"}

The ledger keeps its own type token for a stop-limit order, STP_LIMIT, so ledgers written before stay readable; it is not the ticket’s token.

Outside regular trading hours. IBKR’s US futures order handling rules say that “simulated stop orders in U.S. futures contracts other than single stock futures will only be triggered during regular trading hours unless you specify otherwise”. The ticket’s outsideRTH is how a Web API order specifies otherwise: “Instructs IB to permit the order to execute outside of regular trading hours”. There is no automatic overnight stop protection (owner, 7 Nov 2026): a strategy sends a stop only when it wants one, and that stop works whenever the market trades. A strategy that wants a stop working only in regular hours cancels it and sends it again itself. So since GLE-1366 the adapter reads each contract’s rules when it starts (GET /iserver/contract/{conid}/info-and-rules), and a stop, stop-limit or trailing-stop order on a future goes out with "outsideRTH": true when the rules’ orderTypesOutside lists its type. When they do not, the adapter denies the order before sending a ticket. The reason names the symbol, the type and the list, for example venueibkr: IBKR's rules for ESZ6 do not allow a stop order outside regular trading hours (they allow stop_limit), so IBKR would trigger it in regular hours only; refused rather than sent that way (GLE-1366). It never sends a stop as a stop-limit instead, since a stop-limit can fail to fill on a gap. A future’s limit and market orders go without the flag: IBKR refuses it on a future’s limit order, and a future’s rules do not list either type, which reads as IBKR not holding them to regular hours; an overnight fill of one has not been observed yet. Equity tickets never carry the flag, since extended-hours equity trading is a separate decision. A contract whose rules cannot be read stops the adapter’s start-up with venueibkr: contract rules of "<symbol>" (conid <n>): <error>.

A symbol whose contract the adapter cannot find stops the start-up too (Finding contracts at the IBKR venue).

The paper account’s rules, on 7 Nov 2026, for buy and sell alike:

ContractorderTypesOutside
ES, NQ, CL, GC, ZN, 6E (EUR at IBKR) and MES, front monthsstop, stop_limit, mit, lit, trailing_stop, trailing_stop_limit
AAPLlimit, stop_limit, lit, trailing_stop_limit, relative

So every stop type a strategy can send works outside regular hours on those futures, and no futures stop is denied for its hours. Nothing changes in a backtest, whose fill simulator has triggered exits outside a strategy’s session since GLE-91. IBKR’s paper accounts simulate every stop, so a stop triggering overnight on paper does not prove that a live account does: confirm it with one small live order before relying on it.

The cancel request. A cancel is DELETE /iserver/account/{accountId}/order/{orderId}?manualIndicator=false, IBKR’s documented path and parameter: “For all orders for US Futures products, clients must submit this flag to indicate whether the order was originated manually (by a natural person) or automatically (by an automated trading system transmitting orders without human intervention). […] Orders for USFUT products that do not include this field will be rejected.” The path is the singular order. The client sent the plural /orders/{orderId} before unit 4b, a path the emulator served and IBKR does not document, so a cancel against a real gateway would have failed; the client now uses the singular path and the emulator serves both.

The cancel classes. IBKR’s success reply acknowledges the request, not the cancellation: orderCancelSuccess “Acknowledges IB’s acceptance of the request to cancel the order. Does not report whether the cancellation can or will ultimately be enacted.” So the adapter does not answer Confirmed; the confirmation is the order’s status on a later poll. CancelOrder (engine/venueibkr/cancel.go) classifies each reply, in this order:

ReplyOutcomeReason
HTTP 4xxRefusedthe error’s message, else its body, else the error text (ibkr: http 403:)
HTTP 5xx, a transport or decoding failureUnknownthe error text
HTTP 200 with an error body, such as {"error":"OrderID 123456 doesn't exist"}Refusedthe error text; an error outranks a msg
HTTP 200 with {"msg":"Request was submitted", ...}Pending, status PendingCancelRequest was submitted
any other HTTP 200 body, an empty one includedUnknownunrecognised cancel reply for order <id> (msg "<msg>")

A 4xx is the venue answering this request and saying no (an unknown id, a pacing refusal, a session that is not authenticated); a 5xx or a lost connection leaves the request’s fate open. Every Refused and Unknown answer has a reason: an error with empty text reads ibkr: cancel failed with an empty error, and a nil API error ibkr: nil API error. Every answer carries the IBKR order id and no attempt or remaining quantity, which the adapter does not know (the live loop fills in the attempt). CancelOrder also returns the error of a failure that got no HTTP answer, beside its Unknown result, so a caller that checks the error alone, as the teardown does, still sees it.

Modifying in place. Since GLE-1434 (2026-11-10) ModifyOrder modifies a working order in place, so a live IBKR run moves a stop without the race guard’s gap (Replacing in place, GLE-1419). The request is IBKR’s “Modify an existing, unfilled order”, POST /iserver/account/{accountId}/order/{orderId}, and its body is the order’s whole ticket as the adapter sent it (conid, orderType, side, cOID, ticker, "manualIndicator": false, outsideRTH) with the new terms: the total quantity, never the remainder; the levels in the fields IBKR reads for the type (a limit’s in price, a stop’s trigger in price, a stop-limit’s limit in price and trigger in auxPrice); and the time in force. A second modification repeats the first’s terms. The adapter modifies only a limit, stop or stop-limit order it submitted itself and was told IBKR accepted. Any other order (a market, trailing-stop or market-on-close order, one learnt from IBKR’s reports or adopted at a restart) is answered with an error wrapping sim.ErrModifyNotSupported, and the engine cancels and resubmits. The answer is classified as follows:

IBKR’s answerOutcomeEvidence and reason
an order element with the order’s id and a working status (PreSubmitted, Submitted, or any status that does not end the order)Appliedstatus Working
an order element whose status is Filled, Cancelled, PendingCancel, Rejected or InactiveRefusedthe order’s status, read once, and the answer’s
HTTP 200 with an error body, or any 4xx (a 429 included)Refusedthe order’s status, read once (Filled when a fill won the race), and IBKR’s text
reply messagesthe submission’s reply conversation (Order reply messages): a declined reply is Refused (the modification was not transmitted), an open one Unknown, and an order element after a confirmation is classified as above
a 5xx, a lost connection, an answer that cannot be read, an empty one, or an order element naming another orderUnknownthe failure’s text

A refusal’s evidence is the order’s status from GET /iserver/account/order/status/{orderId}, with its remaining quantity (total_size less cum_fill). A status that cannot be read leaves both empty. Like a placement’s order element, an Applied answer is IBKR’s acceptance of the new terms, not the exchange’s: an execution that beats the modification at the exchange still arrives as the order’s execution, once, and the order’s attempt is then the successor’s. IBKR’s order reports carry no attempt, so a restart with a modification intent outstanding (an Unknown answer) is still refused (The execution fold). The operator settles it at the broker. The emulator modifies a working order in place: it keeps the order’s order_id and cOID, raises its reply fixture’s warnings as it does for a placement, and answers an ended order with an error body.

The paper account (DU8898890, 10 Nov 2026, one MES December 2026 contract) answered as follows:

RequestIBKR’s answer
a GTC sell stop at 7000, modified to two lots at 7001, its ticket repeated with the same cOIDHTTP 200 [{"order_id":"1241466224","local_order_id":"<cOID>","order_status":"PreSubmitted","encrypt_message":"1"}], with no reply message (the placement had asked o10331 and o354); the order status read at once says Sell 2 Stop 7001.00, GTC under the same order id
two more modifications 0.6 seconds apart (two lots at 7002, then one at 7003)the same order element to each; the order then carried the second’s terms, Sell 1 Stop 7003.00, GTC
a modification of a buy limit that had filledHTTP 200 {"error":"Cannot be modified"}; the order status says Filled

IBKR’s reference leaves four questions open (GLE-1419). They are checked on the paper account by make conformance-ibkr-paper (Paper-account conformance), and on LIVE:

  1. What a modification that loses the race to a fill returns. A modification of an order that has filled is refused with Cannot be modified, and the adapter reads the order’s status, Filled, as the evidence (TestPaperModifyAfterFill). A true race cannot be arranged on demand, and the Web API’s polled status and trades do not show the order in which IBKR’s messages arrive.
  2. A modification after a partial fill: whether the new quantity is the order’s total, and what a total below the filled quantity does. The adapter sends the total, as IBKR’s ticket quantity is the order’s. Paper fills a one-lot order whole, so this is still open.
  3. A second modification sent while the first is pending. Both are answered with the order element, and the order ends on the second’s terms: the latest wins, as the engine assumes (TestPaperModifyStopInPlace). The engine itself sends one at a time.
  4. Whether IBKR sends CME a native modify, which keeps the order’s queue priority when its size goes down, or cancels and replaces it. Paper simulates every stop, so this waits for LIVE at small size (GLE-1382).

HTTP 429. Since I6 unit 3a (GLE-435) an HTTP 429 Too Many Requests on the place or the cancel endpoint is a pacing refusal, marked Paced: a submission is Denied with the error text (ibkr: http 429: Too many requests), where any other failed place call is still Unknown, and a cancel request is Refused, as every 4xx is. The adapter reads a 429 as IBKR’s rate limiter refusing the request before it was processed, an assumption IBKR’s reference does not settle, and a v2 live run’s transport scheduler sends the request again (The transport scheduler). Since I6 unit 3b a 429 answering the confirmation of an order reply message is a pacing refusal too, a Denied submission marked Paced (Order reply messages).

PendingCancel is live. IBKR’s PendingCancel status maps to a venue status of its own, sim.OrderPendingCancel, no longer to Cancelled: the venue has accepted the cancellation and not enacted it, and the order can still execute. The poll emits no cancel for it; the cancel is emitted when the live-orders report says Cancelled, with the quantity still working there (remainingQuantity). Reconciliation (engine/recon) counts it as live too: startup matches it as it matches a working order, and the in-flight check and the open-orders poll read it as at the broker, not terminated. A v2 strategy sees the wire’s PendingCancel.

Whose cancel. An observed cancel carries Explicit when this adapter asked for it and Venue (reason 8) otherwise: an expiry, a cancel made at the broker, anything the venue did of its own accord. The adapter claims a cancel before the DELETE leaves. The claims are counted per IBKR order id under a lock of their own, not the poll’s, so a cancel does not wait behind a poll’s HTTP calls; a refused request withdraws its own claim and no other, so an earlier unrefused request’s claim stands; and an order’s claims are dropped once its cancel is emitted. A poll that observes the cancel before the reply is back, as a background poller can, therefore still attributes it to the strategy. The cancel de-duplication keys on the IBKR order id rather than the order reference: two attempts of one label share a cOID without a ledger, and each emits its own cancel, once.

Fills before cancels. PollOnce reads the live orders before the trades and emits the fills before the cancels. Every execution that preceded an order’s cancel is then among the trades read, so a cancel does not reach the strategy ahead of a fill of its order, and its remaining quantity agrees with the fills delivered. Partial executions arrive as one fill per IBKR trade record, each with its own execution_id as ExecID: 4 then 6 of 10 are two fills, and with a ledger each carries the attempt and the quantity still working after it (RemainingQuantity 6, then 0), stamped from the ledger’s record. Without a ledger the adapter leaves those two fields zero; live mode requires a ledger, so only tests run without one.

The emulator’s answers. The emulator answers the cancel with IBKR’s documented bodies, all HTTP 200. A working order is cancelled at once and acknowledged with {"msg":"Request was submitted","order_id":<id>,"conid":<conid>,"account":"<account>"}, which the adapter classifies Pending and confirms from the Cancelled status on its next poll, the path a real gateway takes. An unknown id gets IBKR’s documented example, {"error":"OrderID <id> doesn't exist"}. An order already terminal gets {"error":"OrderID <id> is already <status> and cannot be cancelled"}, the emulator’s own text: IBKR documents no body for that case and may acknowledge the request instead, which the adapter handles as Pending followed by the order’s own terminal status. The manualIndicator parameter is accepted and ignored.

On the v1 profile. Two things change on purpose: a Pending answer is an accepted request, so the strategy gets no CancelReject and the loop marks the order requested, as it does a confirmed one; and an observed cancel the run did not ask for is Venue rather than Explicit (the ledger’s GTC classification accepts both). The v1 loop records no cancel intent in the ledger.

Teardown. After the last bar the live loop, on either profile, reads the order reports (a failure is fatal, engine: live teardown: order status: <error>) and sweeps them in report order. A swept order gets one Shutdown cancel stamped at the last bar’s close, as the simulator’s end-of-data sweep stamps it:

  • a Working order gets one cancel request; an error from it is fatal (engine: live teardown: cancel <id>: <error>), and a Confirmed or Pending answer gets the Shutdown cancel;
  • an order already PendingCancel is treated as requested: no second request, and the Shutdown cancel;
  • a cancel answered Refused or Unknown is not a shutdown. After the sweep the loop reads the order reports again: an order now PendingCancel gets the Shutdown cancel; one terminal, or no longer reported, gets none, since the venue ended it some other way; one still Working is a leak, and fatal, engine: live teardown: order <id> still working after its cancel was <outcome>: <reason> with <outcome> refused or unknown, and the run does not record the order terminated in the ledger;
  • every other status is skipped.

The loop marks each swept order requested and records its Shutdown cancel through the ledger, so a restart does not resurrect it. The sweep covers every working order the account reports (see the known limits under Lifecycle turns).

Executions and positions

Since GLE-1433 (2026-11-09) the adapter reads executions and positions as a real gateway sends them. Before, it could read neither: on the paper account DU8898890 a one-lot MES sell stop triggered and filled, and a market buy closed it, but every poll failed on the trades request (HTTP 404) and the position read failed to decode, so the adapter reported no fill and no position. The emulator served the shapes the client expected, so no test saw it.

  • Trades. The adapter asks for GET /iserver/account/trades, with no account in the path; IBKR answers the old /iserver/account/{accountId}/trades with 404. IBKR’s reference, read on 9 Nov 2026, says of days: “The number of prior days to include in response, up to a maximum of 7. If omitted, only the current day’s executions will be returned.” PollOnce reads the current day’s. GenerateFillReports, which the reconciliation and the run’s summary read, asks for all seven prior days (days=7) and filters by since. Since GLE-1494 it also reports every execution an earlier trades answer gave the adapter that this answer leaves out, so a run longer than 8 trade dates keeps its early fills. A trade record carries conid, order_id and size as numbers, price and commission as strings, and its side as B or S. A size that is not a whole number of units is refused, since a fill’s quantity is an integer. A poll stops at that record every time it reads it.
  • An empty first reply. A few minutes after the two fills, the paper account answered the trades request with [], and four seconds later with all three executions. The poll repeats, so the fills arrive on a later poll. GenerateFillReports reads once, so Config.TradesSettle makes it read an empty reply again, once a second, until that long has passed. Zero, the default, accepts the first reply, as the emulator answers at once. This build’s live mode runs only against the emulator, so only the paper check sets it (10 s).
  • Positions. GET /portfolio2/{accountId}/positions sends conid as a string, as its own schema says and the paper account did. IBKR’s shared position object says integer, and the client reads either. The contract’s label is description, for example MES DEC2026; contractDesc belongs to the older /portfolio/{accountId}/positions/{pageId}. A position closed in the session stays listed with position 0. The adapter leaves it out, as the simulator reports only open positions.
  • Symbols. IBKR names a contract its own way: a trade or an order status of the MES December 2026 future says MES, and its position says MES DEC2026. In fills, fill reports, positions and order reports the adapter names a contract by the symbol it resolved for the conid at start-up, the one the engine trades it under. A contract it did not resolve keeps IBKR’s label. A live order’s ticker no longer replaces a resolved conid’s symbol in the adapter’s contract cache.
  • A filled order’s status has no order_ref and no outside_rth. IBKR documents neither, and the paper account sent both for working orders only. GetOrderStatus then reports the client id the adapter recorded when it submitted the order. Order status is current-session only: IBKR answers 503 for an order of an earlier session.
  • The emulator serves these shapes. It serves trades only at the documented path. Since GLE-1494 it lists one trade date’s, and days adds up to 7 earlier ones (see The IBKR emulator’s day lists). It sends numbers where IBKR sends numbers, sides as B and S, portfolio2’s string conid and description, and a filled order’s status without order_ref and outside_rth. It still lists only open positions. Tests read the paper account’s replies, byte for byte, from internal/ibkrclient/testdata/paper-20261109.

The paper check confirms all of this on an account (Paper-account conformance): TestPaperTradesAndPositions reads, and TestPaperFutureStopTriggers fills a stop and reads its fill. Both passed on DU8898890 on 9 Nov 2026. A one-lot MES December 2026 sell stop at 7415.00, placed at 18:32:58 AEDT, filled at 7411.50. Its fill reached the adapter through PollOnce nine seconds after the stop was placed, under the order’s id, its order_ref and the engine’s symbol. The fill reports and the position (short one contract) followed, and a market buy closed the short at 7411.50.

Order reply messages

Since I6 unit 3b of the order-lifetime programme (GLE-436, 2026-10-08) the adapter confirms an IBKR order reply message only when the deployment allows every message id it carries, and declines any other (engine/venueibkr/reply.go). Until then it confirmed every reply (confirmed: true), waiving each of IBKR’s order precautions on the engine’s behalf. The policy is the adapter’s, so it holds on both lifetime profiles.

IBKR’s reply flow. The place call (POST /iserver/account/{accountId}/orders) can answer HTTP 200 with order reply messages instead of the order: “An array containing objects that each deliver the order reply messages emitted against one order ticket in the submission request’s array.” Each carries an id, “The replyId UUID of the order ticket’s emitted order reply messages, used to confirm them and proceed”, a message array of texts, messageIds, “identifiers that categorize the types of order reply messages that have been emitted”, and isSuppressed, “Internal use”. IBKR’s example:

[{"id": "07a13a5a-4a48-44a5-bb25-5ab37b79186c",
  "message": ["The following order \"BUY 5 AAPL NASDAQ.NMS @ 150.0\" price exceeds \nthe Percentage constraint of 3%.\nAre you sure you want to submit this order?"],
  "isSuppressed": false,
  "messageIds": ["o163"]}]

The client answers POST /iserver/reply/{replyId} with {"confirmed": <bool>}: “true will agree to the message transmit the order. false will decline the message and discard the order.” A confirmation can draw another reply: “These confirmation messages must also be responded to before the order will submit.” And the answer must come at once: “Submitting other orders or other requests will cancel the order and attempts to acknowledge the reply will result in a 503 error.”

The rule. A reply is confirmed only when it carries at least one message id and every one of its ids is on the allow-list, matched exactly, case included, on the id as IBKR sent it. Any other reply is declined (confirmed: false), and its order is not transmitted.

  • One id off the list declines the whole reply: IBKR answers one reply id for all the messages of a ticket, and confirming it would waive that precaution too.
  • A reply with no message id, or only empty or blank ones, is declined whatever the list holds.
  • The isSuppressed flag is ignored: IBKR documents it as “Internal use” and “Always returns false”, and a reply that reaches the adapter was not auto-accepted, so it is judged like any other.
  • The adapter neither suppresses messages nor resets their suppression. /iserver/questions/suppress makes IBKR auto-accept a message id for the whole brokerage session, outside the run’s control and shared with every client of the session, and a suppressed message does not reach the adapter, so suppression would bypass the policy. Do not suppress a precaution id at the gateway either.

Only the first element of a reply array is answered: IBKR ties the elements to the request’s tickets by index, and the adapter sends one ticket. A first element without a reply id cannot be answered: the submission is Unknown and nothing is sent.

The default list. venueibkr.DefaultReplyAllow is IBKR’s five general risk disclosures: o10151, o10152, o10153, o10331 and p12. A disclosure is raised whatever the order’s size, value or price, so confirming it waives nothing about the order. A precaution is IBKR checking the order against one of its limits (price percentage, size, total value, tick size) or warning of a condition of the order itself (no market data, an immediate fill); confirming it waives that check on the engine’s behalf, the risk the plan records as R23, so every precaution is declined unless the deployment lists it. IBKR publishes its message ids only in its list of suppressible ones (the Client Portal Web API page, “Suppressible MessageIds”). The table gives each listed id, IBKR’s meaning as the reference summarises it, and what the default does:

Message idIBKR’s meaningDefault
o163the order exceeds the price percentage limitdeclined
o354an order without market datadeclined
o382a value exceeds the tick size limitdeclined
o383the order size exceeds the size limitdeclined
o403the order will most likely fill immediatelydeclined
o451the order’s value estimate exceeds the total value limitdeclined
o10151the risks of market ordersconfirmed
o10152the risks of active stop ordersconfirmed
o10153IB may set a cap price on the order, which may keep it from tradingconfirmed
o10331the stop order types and their risksconfirmed
p12an order not immediately executable may be rejected if its limit price is too far from the reference priceconfirmed
o10138a size modification exceeds the size modification limitdeclined
o2136a mixed allocation orderdeclined
o2137a cross-side orderdeclined
o2165no fractional trading outside regular hoursdeclined
o10082a called bonddeclined
o10164, o10223cash-quantity ordersdeclined
o10288crypto market ordersdeclined
o10332OSL crypto ordersdeclined
o10333an option exercise at the moneydeclined
o10334an order placed in the omnibus accountdeclined
o10335an internal Rapid Entry windowdeclined
o10336illiquid securitiesdeclined
p6an order distributed over several accountsdeclined
any other idnot in IBKR’s list: o0 carries the stop-order text in one of IBKR’s examples, and o102 appears only as an example of the suppress requestdeclined

Chains. Each reply of a chain is judged on its own, in turn, and a decline at any hop ends the order with that reply’s ids and texts in its reason. The adapter confirms at most 10 replies of one submission: a reply that would be the eleventh confirmation is declined instead, with the cause more than 10 replies (the allow-list is judged first). Only a confirmation transmits, so a malfunctioning venue’s chain ends with positive evidence rather than an Unknown.

The answer to a confirmation. Every hop’s answer is read by one table, the first row that applies:

AnswerSubmission
HTTP 4xxDenied with the error text, such as ibkr: http 400: reply id not found: 'r1'; Paced too for HTTP 429 (ibkr: http 429: Too many requests)
any other failure: an HTTP 5xx, 503 included, or a lost connectionUnknown
IBKR’s error envelope, {"error": ...}, in an HTTP 200Denied with the envelope’s text, such as Order not confirmed
a body the adapter cannot readUnknown
another replythe next hop judges its first element
an order elementread as a direct place answer: Rejected is Denied (venue rejected order), no order id Unknown, otherwise Accepted
no order element: an empty array, null or an empty bodyUnknown

A refused confirmation leaves the ticket untransmitted, so a 4xx and the error envelope, IBKR’s answer to an unknown reply id, are denials. A 429 is read, as on the place endpoint, as IBKR’s rate limiter refusing the request before it was processed: a v2 live run’s transport scheduler sends the order again, with a new place call and a new conversation (The transport scheduler), and a v1 run hears it as a denial. A 503 is Unknown, although IBKR documents it as its answer to acknowledging a reply whose ticket was cancelled: any gateway or proxy may send one, so it is not positive evidence, and a wrong denial would let the engine forget a live order where a wrong Unknown only waits for reconciliation. Until unit 3b every failure on a reply hop was Unknown.

The decline. A decline is sent once, and nothing is sent after it. Only a confirmation transmits a parked ticket, so the answer to a decline does not matter: IBKR documents none (the emulator answers an empty array), and whatever comes back, an error, any HTTP status or a lost connection included, the submission is Denied with the declined reason, and not Paced, since sending the order again would draw the same message. The one exception is an answer whose first element reports a live order, an order id with a status other than Rejected: it contradicts the decline, so the submission is Unknown with that order id, for reconciliation, rather than a denial that would let the engine forget a working order.

The reason. A declined order’s reason is reply_declined: <cause>: <text> (algolang.ReplyDeclined, sdk/strategy/reply.go). The cause is the reply’s ids that are off the list, in the reply’s order with duplicates kept, joined by commas; or no message id; or more than 10 replies. The text is every text of the reply joined by |, since IBKR does not say which text belongs to which id, or no message text when it has none. Every run of white space, IBKR’s line breaks included, becomes one space, so the reason is one line. A ticket of 150 that draws IBKR’s size precaution is denied with

reply_declined: o383: The following order "BUY 150 AAPL NASDAQ.NMS" size exceeds the Size Limit of 100. Are you sure you want to submit this order?

and a reply carrying o451, o10151 and o383 with three texts has the cause o451,o383 and carries all three. As with the engine’s other tokens, the text after the token is for people, not for parsing.

What the engine does with a decline. A decline is a venue denial, and final.

  • A lifetime-v2 strategy sees an OrderUpdate with status Denied and the reason reply_declined: ..., which grants a turn, then the OrderCancel{Rejected} that follows every venue denial; a v1 strategy sees the OrderCancel{Rejected} alone. The operator hears the denial line on stderr, algo: order "big" (AAPL) from instance AAPL denied: reply_declined: o383: The following order ....
  • The race guard ends the attempt, so the label’s successor, and any order held behind it, is admitted, and neither the exposure oracle nor the admission policy counts it (The engine race guard).
  • The ledger closes the order’s reference as a reject with the denial’s reason, IBKR’s text. Every live venue denial now records its venue’s reason: venue rejected order when it has none, and a pacing refusal keeps venue refused the submission for pacing.
  • The desired-order controller blocks the key for that frame, with the reason as State(key).Blocked, so it does not submit the declined order again until the intent changes (The desired-order controller).

Configuration. --venue-reply-allow sets the list for a single run, comma-separated (--venue-reply-allow o10151,o10152,o10153,o10331,p12,o383 adds the size precaution to the default); none is the empty list, which confirms no reply, and blank, the default, selects the five disclosures. It is refused with --config, like the other single-run flags. In a run-config file it is the data key venue-reply-allow, a list of strings set at any level, a more specific level’s list replacing an outer one; [] confirms no reply, and null is refused:

"data": {
  "adapter": "bin/file-csv-adapter",
  "venue-reply-allow": ["o10151", "o10152", "o10153", "o10331", "p12", "o383"]
}

Every run checks the list before any spawn, a backtest included, which ignores it, and a run-config file’s list is checked as the plan is built: each id is 1 to 32 ASCII letters and digits, none is listed twice, and none stands alone. The refusal names the key, as in engine: venue-reply-allow: message id p12 listed twice. The adapter matches the ids as given, so O383 allows nothing IBKR sends as o383.

The emulator’s fixture. The emulator raises order reply messages from its JSON config’s replyWarnings, a list of warnings with the fields messageId, message, minQuantity, minValue and hop. A ticket draws a warning when its quantity is at least minQuantity and its value at least minValue: the quantity times its limit price, else its stop price, else, for an order with neither, the last close the emulator observed for its contract (0 when none); with both thresholds zero every ticket draws it. The warnings a ticket draws are grouped by hop: each group, in ascending order, is one reply carrying the group’s ids and texts in configuration order, so warnings that share a hop make one reply with several ids and distinct hops make a chain, the next group answering the confirmation of the one before. The ticket is placed once every reply is confirmed; a decline drops it and is answered [] (HTTP 200), and an unknown reply id is answered HTTP 400. IBKR’s size precaution on tickets of 100 or more:

"replyWarnings": [
  {"messageId": "o383", "minQuantity": 100,
   "message": "The following order \"BUY 150 AAPL NASDAQ.NMS\" size exceeds \nthe Size Limit of 100.\nAre you sure you want to submit this order?"}
]

The emulator refuses to start when the fixture is combined with requireReply, or holds a warning with no messageId, a negative or non-finite threshold or a negative hop, and under the fixture a place request carries one ticket (HTTP 400 otherwise). The generic reply flow, requireReply with replyChainLength, is unchanged: it raises o163 and, on a chain, o451, IBKR’s price and value precautions, so the default list declines it.

Recorded assumptions. The policy rests on these, stated here as assumptions until a paper-account probe checks them:

  • Real replies carry messageIds. IBKR’s Client Portal page calls the field “Internal use only”; a reply without ids is always declined, and no allow-list can admit it.
  • A stop order draws o10331, IBKR’s listed stop-order disclosure, which the default confirms. One of IBKR’s examples shows that text under o0, which the default declines.
  • An HTTP 429 on a confirmation was refused before IBKR processed it, as unit 3a reads a 429 on the place call.
  • The ticket a declined reply leaves parked does not transmit. IBKR says a decline will “discard the order”; the probe checks that it does.
  • IBKR’s reference gives no HTTP status for its error envelope on an unknown reply id and no answer body for a decline: the adapter reads the envelope as a refusal whatever the status, and a decline’s answer as nothing but a possible live order.
  • IBKR does not tie a reply’s texts to its ids, so the reason carries every text. Its own texts for o383 and o451 are not in the reference; the emulator’s follow the documented o163 wording.

Known limits and follow-ups. These must close before the adapter trades live (GLE-445):

  • A reply conversation is not serialized against the adapter’s other gateway requests. IBKR cancels a parked ticket when another request reaches the session first, and today another submission, a cancel, the poll and the reconciler’s queries can all reach the gateway while a reply is pending. The engine fails safe (the confirmation draws a 503 or an error, read as Unknown, and reconciliation resolves it), but an allow-listed order can be lost. Each place call and its whole reply chain should be serialized against every request on the brokerage session, polls included, and the emulator should drop a parked ticket when requests interleave; today’s concurrency test proves race-freedom only.
  • The paper-account probe checks the assumptions above.
  • The declined reason carries the venue’s free text uncapped; a cap on its length is a follow-up.
  • An opt-in /iserver/questions/suppress/reset in the live pre-flight would undo a suppression made at the gateway.
  • An error envelope or an advanced-order reject answering the place call itself is still Unknown, where one answering a confirmation is Denied; the asymmetry is deliberate until it is revisited.
  • The declined ids do not reach OrderUpdate.BrokerCode.
  • A strategy that sends the declined order again at every decision (a v1 strategy, or one that does not forward OnOrderUpdate to the controller) draws the same decline each time; detecting the repeated order is a follow-up.

Tests. engine/venueibkr/aa_reply_tournament_spec_test.go (24 tests) drives the conversation over a fake gateway that scripts every answer and logs every request (each default id, each precaution, mixed replies, chains, the bound, every answer to a confirmation and to a decline, the first element only) and over the emulator’s fixture (a size and a value warning, a chain, the generic flow, sixteen concurrent submissions under -race); engine/venueibkr/reply_review_test.go holds the review panel’s gap tests (the answer table at later hops, concurrent conversations’ order ids and fills, nothing after a decline, no suppression request on any path, wrapped and typed-nil errors); engine/aa_reply_tournament_spec_test.go (10 tests) runs the live loop over the adapter and the emulator (a decline reaching a v2 and a v1 strategy, a declined replacement, the ledger’s reason, a confirmation refused with a 429 and sent again by the transport scheduler) and the configuration through engine.Run; and a tournament_reply_spec_test.go in each of cmd/tools/ibkr-emulator/emu, engine/runconfig, cmd/algo and sdk/strategy pins, in turn, the fixture, the key, the flag and the token.

The order ledger

--ledger PATH names the live loop’s order ledger (engine/ledger): an append-only JSONL log at PATH, one object per line, fsync’d before each broker call, with a counter sidecar PATH.ctr and a lock sidecar PATH.lock. It is the engine’s own record of what it expects to find at the broker and the basis of startup reconciliation (engine/recon), and since increment I7 of the order-lifetime programme (GLE-373) it owns its identity. A member of a deployment keeps the same ledger, the same entries and counter, in the desk journal instead of a file (The member’s ledger, GLE-1385 item 4).

Namespace and references. Every ledger belongs to one namespace, <label>-<nonce>: the configured deployment label and a ten-character nonce (lower-case base32, a–z and 2–7) drawn once from crypto/rand when the ledger is created and written as the log’s first line, {"kind":"identity","deployment":"demo","nonce":"k7x2q3mz4a"}, before any reference is allocated. Every canonical reference the ledger hands out is <label>-<nonce>-<n>, n a monotonic 64-bit ordinal from one, and goes to IBKR verbatim as the order’s cOID, which the venue echoes as order_ref. IBKR’s cOID is at most 64 characters: a reference that would be longer is refused by the ledger before it is allocated, the counter and the sidecar untouched (ledger: canonical reference "..." is 65 characters, over IBKR's 64-character cOID limit), and the live loop turns that into a fatal error of the run before any submission; a 40-character label reaches the limit at ordinal 10¹². A restart reopens the same namespace and continues the counter, and an ordinal handed out but not recorded (a crash between allocation and the order line) is not reissued.

The deployment label. --deployment (config key data.deployment) is 1 to 40 characters from [A-Za-z0-9_], no dash (the dash separates a reference’s parts); empty means algo. A ledger keeps the identity it recorded when it was created and refuses to open under another label (ledger: "var/orders.json" was created under deployment "demo", but "algo" is configured (a ledger keeps the identity it recorded when it was created)), so a ledger created under a label must keep being run under it. The label is the operator’s name for a deployment; the nonce is what keeps two deployments apart: two started from one copied configuration draw different nonces, allocate under different namespaces, and each delivers only its own executions and cancels to its strategy (below).

Legacy ledgers. A ledger written before identity existed holds order records whose references are c-<n> and no identity line. It refuses to open, writing nothing, unless --ledger-migration exclusive-owner (config key data.ledger-migration) is set: the operator’s assertion that no other deployment on the account allocated references under that prefix. The refusal counts the order records, how many of them are open and the prefixes found, and names the migration. With the migration the ledger appends an identity line carrying legacy_prefix ("c"), owns every c-<n> from then on, continues the counter from the legacy high-water mark, and the flag is unnecessary afterwards. The migration is refused when the legacy references carry more than one prefix (c-* and x-*: ambiguous) or one that does not parse as <prefix>-<n>; an identity line with an empty label or nonce is a corrupt log and refuses to open; a log holding only corporate-action lines, or only a sidecar, is fresh, not legacy. Another value of --ledger-migration is refused.

The order frame and attempts. The order line carries the complete supported frame: the label, symbol, side, quantity, type, prices, time in force, parent label and GTC deadline it carried before, plus the attempt under the label, the trailing distance, the standalone OCO tag and the allocation instant (attempt, trail_amount, oco_group, submitted_at; absent on a line written before the fields existed). The allocation instant is the close of the bar the loop was on when it assigned the reference. The attempt is the strategy’s stamp when it made one (the v2 working view stamps attempts 1-based per label) and otherwise the ledger’s, one above the highest attempt recorded under the label, so an attempt number is restart-stable and is not reused after a restart. Lookup and ExpectedOpen return copies carrying OwnerID, the namespace: every record the ledger holds is owned, migrated legacy ones included. Adoption restores the frame whole: each adopted order carries its trailing distance, OCO tag, attempt, reference (OrderRef), the executed and remaining quantities with the status they imply (Working, or PartiallyFilled once anything executed), its allocation instant and its owner, and AdoptedState.OwnerID is the namespace. Delivered fills and cancels carry the reference, the attempt and the quantity still working (OrderRef, Attempt, RemainingQuantity); a fill carries the venue’s execution id (ExecID, IBKR’s execution_id), which the adapter reads from every trade record.

Executions. IBKR’s trade feed is account-wide, so every execution report the adapter emits, on the real-time channel, the reconciliation poll and the startup alike, goes through one gate, RecordExecution (the poll and the startup reach it through the execution fold, below), which checks in this order and stops at the first that applies:

  1. a report without an execution id is an error (the de-duplication key is required; nothing is written);
  2. a reference outside the namespace is foreign (reference "other-zzzzzzzzzz-1" is not in namespace "demo-k7x2q3mz4a"): another deployment’s execution on the account;
  3. an owned reference with no order record is unexplained;
  4. an execution id already applied is a duplicate when it was applied to this order (nothing written, the record returned) and invalid when it was applied to another, since an execution id is the venue’s identity of one execution and names one order, globally; an id already quarantined is invalid too, with nothing written;
  5. the frame: a non-positive quantity, a symbol or side other than the order’s, a cumulative executed quantity over the order’s, or a time before the allocation instant (compared at millisecond resolution, IBKR’s trade_time_r; a zero time on either side skips the check) makes the report invalid;
  6. otherwise it is applied: a fill line is appended and folded, the cumulative executed quantity and the symbol’s expected position move, and the order terminates once its quantity is reached. Partial executions accumulate, and a fill after a recorded cancel still applies (the cancel-and-fill race moved the position at the venue).

Foreign, unexplained and invalid reports are quarantined: a quarantine line carrying the report, its outcome and the reason is written once per execution id (a re-report is classified again and writes nothing), and the report touches no record, position, de-duplication set or expected-open set. Quarantined() lists them in log order. The live loop drops a foreign execution, and a cancel of a reference it does not own, with one stderr line each and a count, and fails loud on an unexplained or invalid one, naming the execution and the outcome: an owned order the ledger cannot explain is a contradiction, not noise. A duplicate is dropped without a line (the other channel delivered it). So two deployments started from one configuration deliver neither’s executions to the other, and a restart replays the fold, the de-duplication set and the quarantine list from the log. A cancel or reject of a reference the ledger holds no record for writes nothing and is not delivered.

Durable cancel intent. RecordCancelRequest writes a cancel_request line before a cancel is sent, ClearCancelRequest a cancel_refused line when the venue refused it and the order still works, and CancelRequested reads the intent back after a restart; intent on a terminated order clears silently. The API is I7’s. The v2 live cancel (I4 unit 4b) records the intent before each request leaves and keeps it on a Pending or Unknown answer; a Refused answer clears only the intent this request recorded, and not when the venue reports the order already pending cancellation, so an earlier request’s intent stands. A failure to record or clear it is fatal to the run. The v1 loop records none. Recovering a recorded intent at restart (adopting the order as pending cancellation, re-issuing or awaiting the cancel) is the recovery state machine’s, I8 unit 2 (The execution fold).

Durable modification intent (GLE-1435). An in-place modification (Replacing in place) changes the frame an execution must agree with, so it is recorded in three kinds of line, which reuse the order line’s fields:

{"kind":"modify_request","canonical_id":"demo-k7x2q3mz4a-7","quantity":13,"stop_price":100,"tif":"GTC","gtc_deadline":"2026-06-30","attempt":2}
{"kind":"revision","canonical_id":"demo-k7x2q3mz4a-7","quantity":13,"stop_price":100,"tif":"GTC","gtc_deadline":"2026-06-30","attempt":2}
{"kind":"modify_refused","canonical_id":"demo-k7x2q3mz4a-7"}

RecordModifyRequest writes the intent before the request leaves, as the cancel intent is written, and refuses a second while one is outstanding. RecordRevision applies a verdict of applied: the record takes the line’s attempt, total quantity, prices, time in force and GTC deadline, and its earlier attempt still counts as recorded under the label. ClearModifyRequest writes modify_refused. ModifyRequested reads an outstanding intent back after a restart. While an intent is outstanding, the frame check and the order’s end use the larger of the recorded and requested totals. A build older than these kinds skips them, so reopening a ledger that recorded a modification with an older build is unsafe: it would hold the order to its old frame.

Desk fills (GLE-1500). At the desk, a member’s share of a broker liquidation comes on an order the desk made, not one of the member’s (owner ruling Q4d-1, 12 Nov 2026), and so, from desk protocol version 5 (GLE-1491), do the operator’s close on its behalf, a flatten’s close and a position the operator assigns it. RecordDeskFill books each on a line of its own kind, with no order record and no canonical id. Its reason is liquidation, operator, flatten or assigned:

{"kind":"desk_fill","symbol":"AAPL","side":"SELL","exec_id":"DU1234567.4","fill_qty":25,"fill_px":103.5,"exec_time":"2026-01-02T14:34:00Z","reason":"liquidation","desk_order_id":"D-41"}

The line moves the symbol’s expected position by its signed quantity. It is applied once per exec id (the desk’s, or the broker’s for the operator’s and a flatten’s closes), which no order’s execution may share: a second RecordDeskFill with the same exec id writes nothing, and an order’s execution under it is invalid. The real-time event and the restart’s fold go through it alike. A build older than the kind skips the line, so its position no longer agrees with the desk’s: reopening such a ledger with an older build is unsafe.

Corrections at the desk (GLE-1515). A ledger opened with Options.Corrections (a member’s at the desk) takes a corrected execution in place of the one it corrects, as the desk does. Two exec ids on one order (or one desk order) with the same base, everything before the last period, are versions of one execution. The later version replaces the earlier: its fill or desk_fill line is written as any other, and folding the lines takes the earlier version’s quantity off the position and the order’s filled quantity. Replay folds the same lines in the same order, so it gives the same position. RecordExecution checks a correction against the order without the version it replaces and returns that version’s exec id in ExecResult.Replaced. A base that arrives after its correction is a duplicate. CorrectionOf reads what a correction replaced, and OnCorrection hears each one as it is booked. Without the option a suffixed exec id is an execution of its own, as before. No new line kind: a build older than the rule books both versions, so reopening a desk member’s ledger with one is unsafe.

One handle, bounded lines. Open takes an exclusive, non-blocking flock on PATH.lock and holds it until Close, so a second process, or a second open on the same path in one process, is refused (ledger: "var/orders.json" is already open (another process or handle holds "var/orders.json.lock")) rather than replaying the same counter and reissuing a reference. A log line is at most 4 MiB: the writer refuses a longer entry and replay reads up to that limit, so every accepted line survives a restart. Every line round-trips through the Entry struct, the on-disk schema, whose fields are append-only.

Backtests are unaffected: the simulator allocates no ledger reference, and the KBD masters are byte-identical.

The execution fold

Since increment I8 unit 1 of the order-lifetime programme (2026-10-08) the startup reconciliation, and the continuous reconciliation’s resolution of a filled order, fold the broker’s execution reports into the order ledger (FoldExecutions, engine/recon/fold.go) before anything reads the ledger’s position. The owned position is the ledger’s net position per symbol after the fold: the owned executions and the ledgered position events (applied executions and recorded splits), in log order. The broker’s position snapshot is compared with it, not copied into it. Before this unit an order that executed while the engine was down refused the start as a ledger order missing at the broker, an execution the ledger had not recorded refused it as a position mismatch, and the open-orders poll stopped the run when one order had two execution reports; each is now folded. Reconciliation runs only on a live run with a ledger, on either lifetime profile, so backtests and the KBD masters are unchanged.

What IBKR documents. The fold rests on these facts, quoted from IBKR’s Web API v3 reference as retrieved on 2026-10-08:

  • GET /iserver/account/trades: “Retrieve a list of trades, up to a maximum of 7 days prior.” Its optional days parameter: “The number of prior days to include in response, up to a maximum of 7.” The reference read on 9 Nov 2026 adds: “If omitted, only the current day’s executions will be returned.” IBKR’s example record carries "execution_id": "0000e0d5.6576fd38.01.01", "order_ref": "Order123" (the cOID), "order_id": 17437897932 (IBKR’s order id) and its own size, price and commission: each record is one execution.
  • GET /iserver/account/order/status/{orderId}: “Note that orders executed on a previous day or session will return a 503 error.”
  • GET /portfolio2/{accountId}/positions: “This endpoint provides near-real time updates and removes caching otherwise found in the /portfolio/{accountId}/positions/{pageId} endpoint.” Each position carries position, the account’s net quantity, with avgCost, avgPrice, conid (a string) and description.
  • The reference documents no correction or cancellation (bust) of an execution, and no separate commission report: commission is a field of each execution record.
  • Each record also carries liquidation_trade, which “Indicates whether the trade is the result of a liquidation by IB” ("0" or "1", read on 12 Nov 2026).

So the venue’s execution_id identifies one execution, a partially filled order has one record per execution, the history the venue can replay is bounded at seven days, and the position snapshot is account-wide, which is why it is compared with the owned position rather than adopted.

A liquidation’s share at the desk (GLE-1500). A desk member’s fill reports include its share of a broker liquidation, flagged Liquidation, on an order the desk made, and from desk protocol version 5 (GLE-1491) the operator’s fills on its book, each with its Fill.Origin (sim.DeskMadeReason names the kind). With FoldInput.DeskFills, which the run sets at the desk, the fold books such a report on a desk fill line, keyed on its exec id, and lists it as applied or a duplicate with DeskFill set; one with no exec id is unkeyed. It is about no order, so a fold of one order leaves it out. Off the desk it is attributed as any other report, and is foreign.

At startup. recon.Recover (with MatchLedger its wrapper, without splits) reads the broker’s working orders and indexes the broker order id of every order the ledger records, reads every execution the venue reports and folds them, then computes the expected-open set from the ledger after the fold and applies the existing refusals in their order (a ledger order missing at the broker, an orphan, a terminal-status contradiction) before it reads the positions, compares and adopts. An order the fold completed is terminated, so it no longer reaches the “missing at the broker” refusal. A contradicting execution (below) refuses the start first. The fold’s writes stay in the ledger when the start is then refused: they are facts.

Before the fold, an outstanding modification intent (GLE-1435) is settled by the broker’s report of the order. A report carrying the intent’s attempt is recorded as the revision, and one carrying another attempt clears the intent. An order with no report, or one whose report carries no attempt (IBKR’s do not), refuses the start with a DeferredError naming the order: the operator settles it at the broker first. The operator reads one line for the executions folded, one per corporate action recorded, a count of foreign reports quarantined, and one per suspected correction:

recon: folded 2 execution(s) the ledger had not recorded (executed while the engine was down)
recon: recorded the AAPL split 4/1 effective 2026-06-09T13:30:00Z (it took effect while the engine was down)
recon: recorded the AAPL dividend effective 2026-06-09T13:30:00Z (it took effect while the engine was down)

The fold records corporate actions of every kind (GLE-1385 8d): a split scales the owned position, a dividend moves none, a rename moves it to the new symbol, a cash merger or delisting closes it, and a stock or mixed merger converts it to the acquirer’s shares. Within one ex-date they are taken in the backtest’s firing order (renames, splits and dividends, cash mergers and delistings, then mergers), so a split of a renamed symbol’s new name scales the moved position.

Execution identity. An execution is identified by IBKR’s execution_id, verbatim (the report’s ExecID). A report without one is keyed exec:<broker order id>:<reference>, the key the real-time channel derives for the same report, and is accepted only as its order’s single, whole execution: an owned report without an id whose quantity is not its order’s quantity is refused as unkeyed, with nothing written, because its sibling executions would share the key and collapse into one. A report without a reference is keyed under the order it is attributed to (below), so the same execution reported later with its reference has the same key. IBKR’s example record carries an id, and the emulator and the scripted venue stamp one on every execution, so the rule is a guard.

De-duplication. An execution seen any number of times is applied once. The seen-set is the ledger itself: the fill lines of applied executions and the quarantine lines of refused ones, one per execution id, rebuilt on every open (The order ledger). A re-report is classified again and writes nothing, so an execution is applied once however often it is reported: by the startup fold, which reads everything the venue still holds, by a second poll of the same order or after a restart; one the real-time channel already delivered is a duplicate on the poll. The set grows with distinct executions, not with polls or restarts, and the venue re-reports at most seven days; pruning it and rotating the log are a ledger-compaction follow-up.

Attribution. Each report is attributed before anything is written, by the first rule that applies:

  1. A report naming an owned reference (order_ref, the cOID the ledger allocated) belongs to that order. It is refused as invalid, with nothing written, when it also carries a broker order id that is not the order’s, or that is another owned order’s.
  2. A report without a reference belongs to the owned order its broker order id names in the fold’s index.
  3. A report naming a reference that is not this deployment’s under an owned order’s broker order id is refused as invalid.
  4. Anything else is foreign: another deployment’s or manual activity on the account. The ledger quarantines it (one quarantine line per execution id), the startup counts and logs it, and it is not applied, not delivered to the strategy and not part of the adopted state.

The index maps an owned order to its broker order id. At startup it holds every broker order report naming an order the ledger records, whatever its status, so a filled order’s id still attributes its executions; on the poll it is the reconciler’s map, which the startup seeds with the adopted working orders’ ids (Recovery.BrokerIDs, Reconciler.AdoptBrokerIDs), so an order adopted from a prior lifecycle can be addressed before any bulk poll lists it. A broker order id that two orders claim attributes nothing. Every report not refused here then goes through the ledger’s gate, RecordExecution: applied, duplicate, foreign, unexplained (an owned reference with no order record) or invalid (a frame contradiction, an execution id applied to another order or already quarantined). At IBKR the reference-less rule is dormant: the adapter does not read a trade’s order_id but looks a fill’s broker id up from its order_ref, and leaves it empty when this process has seen no order with that reference (one filled in an earlier session), in which case the broker-id checks of rules 1 and 3 do not apply.

Contradictions. An unexplained, invalid or unkeyed report is a contradiction: an owned order the ledger cannot explain. It does not stop the fold; every other report and split is folded first, and the start is then refused, naming the first, whether the ledger quarantined it or the fold refused it with nothing written:

recon: 1 execution report(s) contradict this deployment's records (refusing to continue); first: exec "0000e0d5.6576fd38.01.01" of order_ref "demo-k7x2q3mz4a-3" quarantined as invalid: execution quantity 8 takes the cumulative executed quantity to 12, over the order's quantity 10

A ledger write failure, or a split that would overflow the position, stops the fold with that error; what was written before it stays.

The fold order and splits. The reports are folded by time (a report without one first), then key, broker order id, reference and position in the venue’s answer, so any order of the same reports writes the same ledger lines in the same order, and a restart replays the same position. A split is folded before the first execution at or after its ex-date: an execution at the ex-date is post-split. The splits come from the run’s corporate-action manifests: every split and reverse split whose ex-date precedes the run start, the ones the live corporate-action pass does not fire. The fold records one in the ledger, as the live pass records the splits it observes, when

  • the ledger does not already record it;
  • the ledger’s latest position event for its symbol (an applied execution’s time or a recorded split’s ex-date, LastPositionEvent) precedes its ex-date, or the ledger holds none; and
  • the owned position at that point, after the executions folded before it, is not flat;

and skips it otherwise. A split inside the ledger’s own history cannot be appended without folding it out of order; if it should have applied, the snapshot comparison reports it. A split during downtime is therefore applied from its ledger record, interleaved by time with the offline executions, and not taken from the broker’s post-split snapshot: 100 shares held, a 4:1 split while the engine was down and an offline buy of 20 after the ex-date fold to 420. A manifest ratio that is not an exact terminating rational refuses the start, and so does a split with no symbol, no ex-date, a ratio that is not positive, or the symbol and ex-date of another, before anything is written.

Corrections. IBKR’s TWS API marks a correction by an execution id that differs from the corrected one only after its final period (0000e0d5.6576fd38.01.01 corrected by 0000e0d5.6576fd38.01.02); the Web API reference documents none, and the convention is unverified for it. The fold applies each distinct id as its own execution, and when an id differs from another of the same order’s in the same answer only after its final period, it lists the report (FoldResult.Corrections) and the startup and the poll log it:

recon: suspected correction: execution "0000e0d5.6576fd38.01.02" of order_ref "demo-k7x2q3mz4a-3" differs from another of the order's execution ids only after its final period; applied as its own execution

A correction that moved quantity would then be counted twice where the broker counts it once. Two backstops stop the run: the ledger’s over-fill check (a cumulative quantity over the order’s is invalid) and the snapshot comparison, at startup and at every bar. On the real-time channel the strategy would already have received the extra fill, which is why the paper-account probe of the convention comes before real-money trading.

At the desk the ledger follows the desk instead: it books a correction in place of the execution it corrects, and the fold lists it in FoldResult.Corrected rather than as a suspect (A corrected execution, GLE-1515).

Fold versus snapshot. ComparePositions compares the owned position with the broker’s snapshot (the sum of its reports per symbol) and returns one PositionDiscrepancy{Symbol, Fold, Snapshot} per symbol that differs, sorted by symbol; Difference() is snapshot minus fold. When none differs, the adopted positions take their quantity from the fold and their average price and opening time from the symbol’s first non-zero snapshot report (AdoptedPositions); the quantities agree there, so a start that succeeded before this unit adopts the same state. When one differs, the fold is the adopted quantity and the difference is the record, but unit 1 does not block risk: the start is refused, as before, by the invariant-1 InvariantError, which now carries every record in Discrepancies (json:",omitempty"), the input unit 2’s quarantine reads. A broker reporting +5 where the fold holds +2:

recon: invariant 1 violated (refusing to start): position quantity mismatch for AAPL: ledger-expected 2, broker-reported 5

with the record {Symbol: "AAPL", Fold: 2, Snapshot: 5}, a difference of 3; each further symbol that differs is counted (; 1 more symbol(s) differ). The mid-session check at every bar stops a live run the same way, its error carrying its one record. Adopting the fold and trading on with only a log line was rejected: it would trade on a known discrepancy until unit 2 lands.

On the poll. When the open-orders poll or the in-flight check finds an order the ledger expects open now filled at the broker, the reconciler reads the venue’s execution reports and folds the ones about that order, with its broker-id map. Each execution newly applied reaches the strategy as one fill, in fold order, partial executions included. The order is resolved once the ledger records it complete; until then (an execution report lagging the order’s status) it is held and resolved again on the next poll, and what did arrive is delivered at once. A contradiction about the order stops the run.

Recorded assumptions.

  • One IBKR trade record is one execution, and its execution_id is unique per execution. IBKR’s example implies it (an id, a size and a commission per record) without stating that a partial fill yields several records.
  • Each distinct execution id is one execution; corrections are listed and logged, not interpreted (above).
  • The place answer’s order_id, which the adapter keeps as a string, is the decimal form of the live orders’ numeric orderId, which it renders in decimal. The adapter holds whichever form it recorded last for an order, and the startup index is built from the live orders, so if the two forms differed (leading zeros, say) every start with offline executions would be refused and the poll would stop. IBKR’s examples show the same id in both places.
  • The account belongs to this deployment alone (sharing one is a later account coordinator’s), so when the quantities agree the snapshot’s average price is the owned basis.
  • The manifests’ corporate actions are right. A downtime action is written to the ledger before the snapshot comparison, so a wrong ratio or target becomes a permanent ledger line that refuses every later start until it is repaired by hand. A working order the broker adjusts across a downtime split yields executions over its ledgered quantity, which the fold refuses as invalid: fail-closed.

Paper-probe preconditions. Before any run against a real gateway, a paper-account probe must confirm that the place answer’s order_id and the live orders’ orderId are the same id in the same form. The trades and positions requests were confirmed on the paper account by GLE-1433 (Executions and positions). Before real-money trading it must also settle IBKR’s correction convention on the Web API, and check that a partially filled order yields one trade record, with its own execution_id, per execution.

Known limits and blockers.

  • GLE-450 carries the two broker-id forms above (normalise them in one place) and the "0" placeholder: a live order without orderId comes out as broker id "0", which the fold treats as ambiguous when several orders share it but which breaks cancel and event routing outside the fold, so a missing id must read as absent. The trades path, days and the trade, position and order-status field types it also listed were fixed by GLE-1432 and GLE-1433 against the paper account’s replies (Executions and positions).
  • The fold sees what the venue still reports: at most seven days, which the reconciliation asks for (days=7). An execution the ledger did not record and the venue no longer reports cannot be folded; its effect reaches the snapshot comparison, which refuses the start.
  • An order cancelled at the broker while the engine was down still refuses the start (in-ledger-not-at-broker very-late Fill/OrderCancel replay is deferred past task 3b-2): IBKR’s single-order status answers 503 for an earlier session, so the evidence has to come from elsewhere.
  • The real-time channel keys a report without an execution id under the derived key without the unkeyed rule, so it can take an id-less sibling execution for a duplicate, which only the next position check catches.
  • The poll rebuilds the reverse of its broker-id map, which keeps every order the run has registered, each time it resolves a filled order: a cost linear in the orders registered.
  • Two folds running at once on one ledger could both record the same split. Unit 1 cannot reach it: the startup fold runs once, before the loop, downtime actions are folded only there, and the poll folds on the live loop’s goroutine.

Unit 2, the recovery state machine, is next. It adds:

  • quarantine of a discrepancy and blocking of new risk, instead of the refusal;
  • restart while an owned order is PendingCancel, the order reserved and cancellable, from the ledger’s recorded cancel intent;
  • cancelling adopted orders: their broker ids in the strategy’s cancel path, by label on v1 and by attempt on v2, and adopted predecessors in the race guard;
  • offline cancels, from order-status evidence;
  • the seven-day window: days=7 on every trades request, the gap past it, and operator reconciliation from a statement;
  • the owned average price, computed from owned executions through splits, for an adoption despite a discrepancy;
  • atomic split recording in the ledger (check recorded, check position, record under one lock), or folds serialized per ledger, before folds can run at once on one ledger;
  • a lazy reverse broker-id lookup.

Tests. engine/recon/aa_fold_tournament_spec_test.go (36 tests) drives FoldExecutions directly (partial executions; duplicates within a batch, across calls and across a restart; foreign activity; attribution through the broker order id, its three contradictions and an ambiguous id; reports without an execution id; determinism under every order of the reports; Order; the split rules, refusals and overflows; a failed write; suspected corrections), ComparePositions, AdoptedPositions and the startup and poll paths through them; engine/ledger/aa_fold_tournament_spec_test.go pins LastPositionEvent; engine/aa_fold_tournament_spec_test.go (4 tests) runs the live startup over a scripted venue and the manifests’ downtime splits; and fold_review_test.go in engine/recon and engine holds the review panel’s gap tests (a full tie decided by input order, a failed split write, reports returned as given, the first non-zero snapshot report, a zero-time execution as the earliest, unchanged inputs, and one execution raced between the real-time gate and the poll, applied and delivered once).

The scripted venue

engine/venuetest (I4 unit 4b) is a deterministic, in-process venue for the live loop’s tests, with the asynchronous cancellation a real venue has and the emulator cannot produce: the emulator embeds the simulator, which cancels synchronously. venuetest.New(cfg) returns a *Scripted that implements the live loop’s venue (the venue adapter interface plus PollOnce), and its Step is the loop’s clock stepper, so runLiveLoop drives it exactly as it drives the IBKR adapter over the emulator. It starts no goroutine, guards its state with one mutex and imports engine/sim and sdk/strategy only, so any package’s tests can use it. It ships with the module, as the emulator does, with no production caller.

The script. Config.Orders maps the cOID the engine submits (the ledger’s canonical reference when a ledger is active, else the label) to an OrderScript; an order without one is accepted and cancelled on request.

  • Submission. Deny denies it with that text; Unknown answers SubmitUnknown with no id, and with Booked the venue books the order anyway (the answer was lost). Booked orders take the ids sv-1, sv-2, … in booking order; a denial, a pacing refusal or an unbooked Unknown takes none.
  • Cancel. Cancel.Outcome decides every cancel request: Confirmed, or none, cancels at once; Pending makes the order PendingCancel until the step ResolveAt (0: not during the run), so a cancel can be deferred, and a second request answers Pending again; Refused refuses with Reason (by default venuetest: cancel refused by script); Unknown answers without evidence, as a transport failure would, and with Applied the cancel took effect anyway. The Confirmed, Pending and Refused answers carry the order’s status, attempt and remaining quantity as evidence. A cancel of an unknown id is Refused without evidence, and one of an order already filled or cancelled is Refused with it.
  • Fills. Fills execute at the steps they name, capped at the quantity remaining, while the order is Working or PendingCancel, so an order can fill, or fill in part, during a pending cancel. Each execution carries its own id (sv-1-e1, sv-1-e2, …), the attempt and the quantity still working after it; the order is Filled when nothing remains, which makes a pending cancel moot. At one step the executions come before a cancel that resolves there, which then carries the post-fill remaining quantity. A fill at a step already passed when the order was booked does not fire.
  • Modify. Modify.Outcome decides a modification request (GLE-1419); with none, ModifyOrder answers an error wrapping sim.ErrModifyNotSupported, as it does for an unknown id, and the engine replaces by cancel and new. Applied gives a Working order the request’s total quantity, prices, time in force and attempt, which its later events carry, and refuses a total not above the quantity already filled; Refused leaves the order as it was, with Reason (by default venuetest: modify refused by script); Unknown answers without a verdict, and with Applied the change took effect anyway. FillFirst makes the request lose a race: the order’s remainder executes at FillPrice just before the request lands, and the answer is Refused with the status Filled. A request for an order pending cancellation or ended is Refused with its status, whatever the script. Pending (GLE-1436) answers later: the order keeps its terms until the step ResolveAt (by default the next), which resolves the request as Resolve after the step’s fills and queues the verdict as a VenueEvent carrying a sim.ModifyEvent under the broker id. A fill that ends the order first makes it Refused with Filled, and a second request while one is pending is Refused. Modifies scripts successive requests in turn, the last repeating, in place of Modify.
  • Pacing. Pacing{SubmitsPerStep, CancelsPerStep} refuses each request past the limit within one step with venuetest.PacingRefusal (venuetest: pacing refusal): a denial for a submission, a Refused answer for a cancel. The counters reset at every Step. Since I6 unit 3a each refusal is marked Paced, a pacing refusal that a v2 live run’s transport scheduler sends again (The transport scheduler).

Events queue until PollOnce moves them onto the Events channel without blocking (venuetest: events buffer full when the channel is full, venuetest: poll after shutdown after Shutdown). The order, fill, position and account reports answer from the script’s state; the account state has no cash book.

The clock. Step 0’s clock is Config.Start, which defaults to 2026-01-02T14:31:00Z, the close of bar 0 in the engine’s oracle fixture, so step k’s clock is bar k’s close and an event on a bar is stamped at that bar’s close, not before the ledger’s allocation instant of an order submitted on it. Each Step advances the clock by Interval (a minute by default). EventBuffer is the channel’s depth (1024 when not positive).

The call log. Calls() lists the venue calls in order, one entry each: init, submit <cOID>, cancel <id>, modify <id> (a scripted modification only), step <n>, poll, status <id>, orders, fills, positions, account and shutdown. Name, Clock, Calls, Events and an unscripted ModifyOrder log nothing, nor does a Step or PollOnce that returns early on a cancelled context. A test reads in it what reached the venue: one cancel request for an order already pending, none for a label with no order id, no second request at teardown.

Reuse. The admission race guard’s tests (The engine race guard) reuse the fixture: a Pending cancel resolving at step k with fills inside the window gives fill-before-cancel, cancel-before-fill and a partial fill; Pending with ResolveAt 0 is a cancel the venue does not confirm; and Calls() shows which orders reached the venue. The transport scheduler’s tests (The transport scheduler) use Pacing for the venue’s pacing refusals.

No reply messages. The scripted venue has no reply conversation and needed none for I6 unit 3b: to the engine a declined IBKR order reply is a venue denial with a text, which Deny already scripts. The reply policy’s engine tests drive the IBKR adapter over the emulator’s replyWarnings fixture instead (Order reply messages).

Running a deployment against the desk

AlgoDesk runs a portfolio’s strategies as members of a deployment: the desk owns the broker connection, each member’s book and the limits, and a member’s engine sends it intents rather than broker orders (GLE-1439). algo run --deploy FILE starts every member the file names, together, each in an algo process of its own (GLE-1385). The file is a deployment file: one per mode, beside the portfolio file the backtests run.

{
  // portfolios/core-sim.json: the SIM deployment of core.json
  "portfolio": "core.json",
  "mode": "sim",                       // sim, paper or live
  "desk": "http://localhost:7443",     // https for TLS, http for HTTP/2 without TLS
  // "desk_pin": "sha256//…",          // an https desk's certificate pin (GLE-1521), below
  "feed": "stream",                    // history (the default) or stream
  "roll_deadline": "2m",               // a continuous roll's wait for its legs (default 2m) and its seam (default 10m)
  "roll_rebase": true,                 // re-adjust continuous series at each roll (GLE-1458); on when absent (GLE-1502)
  "reconnect_wait": "2m",              // how long a member whose stream drops tries to resume (GLE-1479); "0s" is off
  "members": {
    "smacross-es": {"start": "adopt"},
    "smacross-nq": {}                  // start defaults to adopt
  }
}
bin/algo run --deploy portfolios/core-sim.json                         # every member
bin/algo run --deploy portfolios/core-sim.json --member smacross-es    # one member, in this process

Each member is named by its run’s id in the portfolio file, and every run of a deployed portfolio needs one. The run is the portfolio’s run exactly as a backtest expands it, run live. Paths resolve against the deployment file’s directory. The engine refuses:

  • a member that is not a run of the portfolio, naming the runs that are;
  • a portfolio with an entry that sweeps its inputs or fans out over a template (runs[0]: sweeps Fast; a deployed portfolio holds fixed runs only), or a run without an id;
  • a member that names a ledger (the desk journal keeps every member’s ledger, below), and a start other than adopt;
  • an unknown field, a mode other than sim, paper or live, a desk that is not an http or https URL, a desk_pin that is malformed or given with an http desk, a feed other than history or stream, a roll_deadline that is not a positive Go duration, a roll_rebase that is not true or false, and a reconnect_wait that is not a Go duration of zero or more;
  • a replay or speed outside a sim deployment, a replay with feed stream, a replay with neither end or with its ends in the wrong order, and a speed that is neither a positive number nor max;
  • a --member the file does not name, naming the members it does.

The desk’s certificate. An https desk’s certificate is checked against the system’s roots, unless the file gives desk_pin. The desk host serves a self-signed certificate, which no root signs, so a member trusts it by the pin of its public key, as AlgoDesk’s own clients do (GLE-1521). The pin is sha256// and the base64 SHA-256 of the certificate’s public key, the form curl’s --pinnedpubkey takes. algodesk-local status prints it on the desk host:

pin=$(host/local/algodesk-local status | awk '$1 == "pin" && $2 == "paper" {print $3}')
echo "$pin"    # sha256//9KdojAhrMQRpBhZRQLW2TMRGeYuiVMOofpF91p7xnGU=
{
  "portfolio": "core.json",
  "mode": "paper",
  "desk": "https://127.0.0.1:8442",
  "desk_pin": "sha256//9KdojAhrMQRpBhZRQLW2TMRGeYuiVMOofpF91p7xnGU=",
  "members": {"rollhold-mcl": {}}
}

With a pin, the member trusts only a certificate whose key has it. The certificate’s chain, its host names and its dates are not checked: the pin is the trust. Every connection is checked, a resumed session’s included (GLE-1479). A desk whose key is not the pin is refused at the handshake, before the member says anything, and the error shows only the start of each pin:

algo: engine: live venue init: venuedesk: session ended: venuedesk: receive: unavailable: the desk's certificate key is not the pin given (desk_pin "sha256//47DEQpj8…", the desk's key "sha256//9KdojAhr…"): check the pin with algodesk-local status on the desk host, which a renewed certificate changes

The host makes a new certificate, with a new key, when it starts on a new data volume (the replace drill), so the pin changes: update desk_pin from algodesk-local status afterwards. A member follows no redirect from the desk, on http or https: the protocol’s calls never redirect, and a redirect could send the call to a server the pin does not cover.

feed is where the member’s bars come from: history, the default, or stream, the adapter’s real-time feed (Running live on a real-time feed).

roll_deadline bounds two waits of a continuous roll. A roll waits for its cancels to be confirmed and, on a desk on the wall clock, for its legs to fill, two minutes by default from the roll’s start (GLE-1447). On feed stream, a roll whose seam has not arrived is held, ten minutes by default (GLE-1508). Marketfeed checks for a new seam only every 30 s, and a held roll stops only openings, so the hold is the longer. One value sets both.

roll_rebase sets the roll rebase for every member, as --roll-rebase does: each adjusted continuous series is re-adjusted at every roll (Re-adjusting at each roll). Absent, each member takes the default, on where its strategy takes the capability (GLE-1502). false turns it off. A portfolio run that sets data.roll-rebase itself, at any level of the portfolio file, keeps its own setting either way (Turning the roll rebase off).

Replay. A sim deployment may say what the desk’s SIM clock replays and how fast (GLE-1380):

{
  "portfolio": "core.json",
  "mode": "sim",
  "desk": "http://localhost:7443",
  "replay": {"from": "2024-01-02", "to": "2024-03-28"},  // each end a date or an RFC 3339 timestamp
  "speed": 60,                                           // 60 times the market's pace; "max" (the default) is as fast as the members answer
  "members": {
    "smacross-es": {},
    "smacross-nq": {}
  }
}

The window replaces each end it gives of every member’s date range, so the members replay the same days; an end it leaves out stays each member’s own. A replay reads history, so it refuses feed stream.

Only --member, --date-from, --date-to, --results-dir, --plate, --color and --chart may accompany --deploy; a deployment with a replay refuses --date-from and --date-to, since the replay sets every member’s range.

Fill settings on a desk

A member’s fill settings are its run’s keys in the portfolio file, which the member and the desk both read (GLE-1603). --deploy takes none of the fill flags. What becomes of the settings depends on the clock the desk runs the member on.

On the desk’s SIM clock the desk fills the member’s orders itself, with the backtest’s fill model, so the settings are the desk’s to apply and the member accepts every one: simulation-resolution tick, an auto that resolves to tick, include-path, path-interval and limit-fill through. The desk resolves auto by the backtest’s own rule (The rule as a library), and reads what its fill model walks inside each bar, the bar’s path or its trades, itself. The member does not:

  • it reads whole bars. No request of its run asks for a path, the run’s or a series’ own, and it reads no trades;
  • its series keep the names its backtest gives them (eq:XNAS:AAPL@5m~time:path=1m), so the session’s plots and fills line up with the backtest’s;
  • the path it asks for is still checked as its backtest’s is: a path-interval no finer than the bar, or a path on activity bars, is refused before the member reaches its desk.

On any other clock (a desk that steps a broker port, or the wall clock of a paper or live desk) a broker fills the orders, and a setting that would make the run’s backtest fill differently is refused, as it is for every live run. A paper or live deployment is refused before the member reaches its desk; a sim deployment once its desk has said which clock it is on, before the member steps a bar:

engine: the desk fills this member's orders at its broker, not on its SIM clock, so the run's fill settings must be ones a broker's fills agree with: "simulation-resolution": "tick" replays each bar's trades, which only a SIM desk does; set it to "bar"
engine: the desk fills this member's orders at its broker, not on its SIM clock, so the run's fill settings must be ones a broker's fills agree with: the run's simulation-resolution, auto, resolved to tick, which replays each bar's trades as only a SIM desk does; set "simulation-resolution": "bar"
engine: the desk fills this member's orders at its broker, not on its SIM clock, so the run's fill settings must be ones a broker's fills agree with: an intra-bar path ("include-path" or "path-interval") is walked only by a SIM desk; drop it
engine: the desk fills this member's orders at its broker, not on its SIM clock, so the run's fill settings must be ones a broker's fills agree with: "limit-fill": "through" is a simulator's rule, and a broker decides its own limit fills (GLE-70); drop it

bracket-ambiguity and limit-fill optimistic are accepted on every clock, as they are for every live run. A deployed engine takes no bracket orders yet, so bracket-ambiguity has nothing to decide at a desk.

Members together. algo run --deploy FILE is the members’ supervisor (owner rulings Q15 and Q16, GLE-1385). It reads the file and builds every member’s run first, so a refusal stops the deployment before any member starts. It then starts each member as algo run --deploy FILE --member ID, with the flags it was given:

algo: starting the 2 members of core-sim.json: smacross-es, smacross-nq
smacross-es | algo[fut:XCME:ES]: recon: match_ledger complete: adopted 0 position(s) and 0 working order(s)
smacross-nq | algo[fut:XCME:NQ]: recon: match_ledger complete: adopted 0 position(s) and 0 working order(s)
  • Every line a member writes comes out behind its id, padded to the longest, on the stream the member wrote it to. A member prints what it would print on the supervisor’s terminal: the same plates and colour, and the terminal’s width less the prefix.

  • A member that exits with an error has crashed. The supervisor starts it again after a pause that doubles from one second to a minute, and says so:

    algo: member smacross-es exited (exit status 1); starting it again in 2s (crash 2 of 5 within 10m0s)

    After five crashes within ten minutes, the supervisor gives the member up and the other members run on. A member that starts again reads its ledger back from the desk and adopts its book, as any start does.

  • A SIM desk that rewinds its clock (algodesk sim rewind) ends every member’s session with the code rewind. Each member’s algo run exits with status 75, and the supervisor starts it again at once, with no pause; the exit is not a crash. The desk has cleared the member’s ledger, so it starts with a fresh SIM ledger and an empty book, and the desk’s clock runs the session again from its start:

    smacross-es | algo: desk ended member smacross-es's session: rewind: rewinding to seq 4120
    algo: member smacross-es was ended by its desk for a rewind; starting it again

    A member that exits for a rewind ten times within ten seconds is counted a crash on the tenth, so a desk that keeps refusing it cannot keep the supervisor starting it.

  • A member that ends cleanly has finished, and is not started again. The supervisor exits once every member has ended: with status 0 if every member finished, otherwise 1, naming each member that did not and why.

  • Ctrl-C and SIGTERM reach the supervisor alone, since each member runs in a process group of its own. The supervisor passes each signal on to every member: the first stops each member’s run and a second kills it, as for a single run (Stopping a run). Nothing starts again after the first.

  • A member watches its stdin, a pipe the supervisor holds open. If the supervisor dies, even by SIGKILL, the pipe closes and the member stops its run rather than trade unsupervised:

    smacross-es | algo: the deployment's supervisor has gone; stopping the member

--member ID runs that member alone, in this process: nothing starts it again if it fails. It exits with status 75 when its desk rewinds, and 1 for any other failure.

With --results-dir, the members share one results dir and one index.json. Each member merges its run’s row into the index under a lock (index.json.lock beside it), so no member overwrites another’s row, and a row replaces the row of the same run id from an earlier start. The supervisor adds a failed row for a member it gives up on:

{"Name": "smacross-es", "RunID": "smacross-es", "Status": "failed",
 "Error": "given up after 5 crashes within 10m0s: engine: desk refused member smacross-es: ..."}

The handshake. The run’s venue is the desk venue (engine/venuedesk), which speaks the strategy-to-desk protocol (docs/desk-protocol.md (docs/desk-protocol.md)) over one HTTP/2 stream. Its hello carries the member id, the engine build’s VCS revision (with -dirty for a modified tree), the SHA-256 of the portfolio file’s bytes, the mode and the symbols the member trades. The desk accepts it with the member’s owner book and working orders, or refuses it, and a refusal stops the run with the desk’s reason:

algo: desk refused member smacross-es: unknown_member: no member smacross-es in core.json

A desk that ends a running session stops the run the same way (desk ended member smacross-es's session: stopped: ...). Each warning in the acceptance (the portfolio-hash warning in SIM and PAPER, say) is printed on stderr as algo: desk: <warning>.

No trade director of its own. A deployed member runs no trade director: the desk’s judges its orders, against the whole account (GLE-1629). The hello says so (desk protocol version 7, director_off), and a LIVE desk refuses a member that does not. A director the portfolio file gives the run, at any level, is set aside with a note:

algo: member smacross-es: the trade director its portfolio file gives it is set aside: the desk's trade director judges its orders (algodesk director import takes a director file)

The desk’s director comes from a director file of its own, the file --director reads (One file for the desk and the command line).

A roll’s reopen at the desk. The desk’s trade director judges a continuous roll’s reopen as the run’s own director would (Continuous rolls): the close passes, and the open leg is judged alone, as a transfer, whole or not at all (GLE-1691, desk protocol version 8). A reopen it refuses is refused in the desk’s answer to the open leg, coded desk_ and the director’s token (desk_director_reducing). The member takes that as a refused reopen, not as the roll’s failure: the position closes on the outgoing contract, the strategy gets a Denied update under the open leg’s label whose reason leads with the director’s token, the bracket children that were to ride the reopen are lost, and the run goes on. The decision is in the desk’s journal, not in a decision log of the member’s. A run under order lifetime v1 has no loop to tell its strategy, so it stops with the position closed and says why.

The member’s ledger. A deployed member keeps no ledger file: its order ledger is kept in the desk journal (desk protocol version 2, GLE-1385 item 4). The acceptance returns the member’s ledger, its entries in order and its counter, and the engine opens the ledger on them. From then on the engine sends each entry to the desk, which journals it before it answers, so an order is in the desk journal before it is submitted. A restart reads the ledger back from the desk: it keeps the member’s namespace and never reissues an order reference the desk has seen. Each member’s references have a namespace of their own. A desk that answers a record with other entries or another counter than the engine expects stops the run (venuedesk: the desk holds 3 ledger entries and counter 1 for member smacross-es, the engine expects 4 and 1), since the next start would read another ledger.

A broker liquidation. IBKR can liquidate or close out the account’s net position itself, on no order of the desk’s: a margin liquidation, or a close-out before delivery. Its trades list such a fill with liquidation_trade "1", and the IBKR venue flags it Liquidation on its fill event and fill report (GLE-1500). The desk splits it across the members whose positions it reduces (design §8.7, D17), and sends each member its share as a fill on an order the desk made (DeskOrderEvent.desk_made, desk protocol (docs/desk-protocol.md)). The member’s engine books the share on a desk fill line of its ledger (The order ledger), so its position agrees with the desk’s owner book at every later position check and after a restart. The strategy gets the share as a fill with no client id, as it gets an expiry settlement, and the member’s stderr notes it:

algo: the desk booked this member's share of a broker liquidation: SELL 25 AAPL @ 103.5 (exec DU1234567.4, desk order D-41)

A share the desk made while the member was down is booked by the restart’s fold. Off the desk, a run on the IBKR venue books nothing it did not order: a liquidation is dropped as another deployment’s execution, and the next position check stops the run, as before.

The operator’s fills (desk protocol version 5, GLE-1491). Every fill in a member’s book reaches the member, the operator’s too (design §8.6, §8.9, §11):

  • a close the operator makes on the member’s behalf (after the desk has paused the member’s openings on the contract and cancelled its working orders there);
  • a close made by the stop control’s flatten (level 4);
  • a position the operator assigns the member from quarantine or a standing outside holding, which no broker execution made, at the prices it was opened at.

Each comes as a fill on an order the desk made, as a liquidation’s share does. The engine books it on a desk fill line of the ledger, with the reason operator, flatten or assigned. The strategy gets it as a fill with no client id, flagged with its origin: Fill.Origin is FillOriginOperator, FillOriginFlatten or FillOriginAssigned (FillOriginLiquidation for a liquidation’s share, FillOriginOrder for every other fill). A strategy in Go, in-process or over the protobuf wire (Fill.origin), reads the flag; the csv and csv2 wires carry no origin, so a strategy on them sees a fill with no client id. The stderr note says which:

algo: the desk booked the operator's close on this member's behalf: SELL 30 AAPL @ 103.49 (exec DU1234567.4, desk order 1000004)

The pause or the stop level still holds the member’s openings until the operator resumes them. A fill the desk made while the member was down is booked by the restart’s fold.

A corrected execution (GLE-1515). IBKR corrects an execution by sending it again under the same base id with a new suffix (0000e0d5.6576fd38.01.02 corrects 0000e0d5.6576fd38.01.01), and the desk books the correction in place of the version it corrects (design §8.1). So does the member’s ledger at the desk. On one order, or one desk order, an execution whose exec id has the same base (everything before its last period) as one the ledger booked replaces that one. The position, the order’s filled quantity and the over-fill check follow it, so the next position check still matches. A base that arrives after its correction is a duplicate and moves nothing. That happens when the restart’s fold books the correction from the desk’s fill list before the base’s event arrives. The strategy keeps the fill it was sent and is not sent the correction. The member’s stderr notes it:

algo: a corrected execution on order demo-k7x2q3mz4a-3: 0000e0d5.6576fd38.01.02 corrects 0000e0d5.6576fd38.01.01: SELL ES 2 @ 6050.25 -> 1 @ 6050.5; the ledger books it in place of the fill it corrects, which the strategy keeps

The reconciliation logs a correction its fold books (FoldResult.Corrected, not Applied, so nothing delivers it). Off the desk the rule is off: a suffixed exec id is an execution of its own, as The execution fold describes under Corrections.

The position check (desk protocol version 5, GLE-1491; design §8.3 invariant 5). At every bar the member tells the desk what its ledger holds, per contract, once it has booked every event the desk has sent it. The desk answers with the member’s owner book as of the same event, and compares the two. The engine’s per-bar position reconciliation then compares its ledger with that book, as it compared it with the desk’s positions before. A fill still on its way therefore never counts. When the two differ, the desk holds the member’s openings on the contract and raises an alarm, and the member’s stderr names the difference before its run stops on invariant 1:

algo: the desk's position check at 2026-01-02T14:33:00Z found this member and its owner book apart (AAPL: member 130, desk 120); the desk holds its openings there

The restart is then refused until the books agree (D37). The desk does not book corporate actions on a member’s book yet, so a split on a member’s stock makes the check find the two apart at once.

What the strategy says

A deployed strategy’s plots, annotations and log lines go to the desk (desk protocol version 6, GLE-1601), so the desk can journal them beside the member’s orders and fills. The strategy changes nothing: it calls ctx.Plot, ctx.Annotate and ctx.Log as it does in a backtest (Plotting from a strategy).

  • No extra traffic. What the strategy said rides the member’s next frame to the desk, whatever that frame asks. The engine takes it each time the strategy has answered a decision (a bar, a timer or a lifecycle turn), before it sends the answer’s orders. So a log line reaches the desk ahead of the order it explains.
  • Plots and annotations go bar by bar, each named by its series and its bar’s open, as a backtest’s report names them. The desk gets them as the strategy sent them: a plot’s style comes with its first point.
  • Log lines go in the order written, with their level. They are still printed on the member’s stderr, whole, as [smacross] INFO: ....
  • A long line is cut. A line over 4,096 bytes is cut to its first 4,096, at a character’s edge, and marked as truncated at the desk.
  • A flood is counted. One frame carries at most 200 lines: the first 200 the strategy wrote since the last frame that carried any. The desk is told how many more there were, and does not get them. The limits count lines and bytes, never time, so a replay of the same run cuts and drops the same lines.
  • The CSV wires carry log lines and no plots. Plots and annotations travel on stdio-pb-v1 only, so a strategy on stdio-csv-v1 or stdio-csv-v2 sends the desk its log lines alone.
  • A dropped stream loses nothing. The member numbers what it sends, and after a resume sends again whatever the desk may not have read. The desk journals each piece once.
  • What the desk does not get. Lines written after the member’s last frame to the desk, or as its run fails, are on its stderr only. So is anything the strategy writes to its own stderr.

The two limits are the engine’s (venuedesk.MaxLogLineBytes, venuedesk.MaxLogLines); the deployment file has no setting for them. The strategy’s output (docs/desk-protocol.md) has the wire’s detail.

A dropped stream. If the stream to the desk drops, the member carries on in the same process (GLE-1479). The strategy keeps its state and does not warm up again. The member dials the desk again and resumes its session on a new stream, for up to the deployment’s reconnect_wait (two minutes by default). The desk holds the member’s place for as long.

  • The run waits at its next call to the desk. On the engine-stepped and SIM clocks the desk’s clock waits too. On the wall clock, bars that close meanwhile are stepped once the session resumes. With feed stream, openings stay stopped while the run catches up (see Running live on a real-time feed).
  • Requests the drop left unanswered are sent again. The desk places a repeated submit once, and a late one is refused when its intent has expired. A modify in flight is Unknown.
  • After the resume, the run’s next reconciliation pass runs both of its loops at once.
  • A connection that dies silently is caught by HTTP/2 pings, and by a request left unanswered for the answer timeout.

The member’s stderr notes the drop, each failed attempt and the resume:

algo: desk: the stream to the desk dropped (venuedesk: receive: unavailable: ...); resuming session smacross-es-12 for up to 2m0s
algo: desk: resumed session smacross-es-12 after 1.27s (attempt 2)

A desk that ends the session with shutdown, to restart, is resumed the same way. Any other refusal ends the run, as before. If the session does not resume within the wait, the run stops with an error naming the drop, and the supervisor starts the member again (owner ruling Q20). Set "reconnect_wait": "0s" to stop the run at the drop instead.

A trade director’s decision log goes to the run’s results directory (<results-dir>/<run>/director-decisions.jsonl), or to --director-log.

The member’s summary. Each member’s summary shows its own figures, however many members the deployment has (GLE-1467). The members share one broker account, so the engine never reads the account’s cash for it. The member’s cash starts at its capital. Each of its fills, from the desk’s fill query, moves it as a backtest’s fill moves the simulator’s cash. Each corporate action the run fired adds the cash the simulator books for it: a dividend, a cash merger’s or a delisting’s consideration, a mixed merger’s cash, or the cash in lieu of a fractional share. The amounts are counted on the ledger’s position entering the action. Equity is that cash plus the member’s positions at the last close of its bars, and the return is measured on its capital. A one-member run on the emulator ends with its backtest’s cash, equity and return, to the bit. With several symbols, amounts booked at one instant can add in another order and differ in the last bit. The account’s own figures are the desk’s: its account strip, and the pane of GLE-1381.

The member’s summary has three limits. It counts USD only, as a live summary always has. A futures contract settled at expiry without a fill moves no cash in it. And a corporate action a run before a restart fired is not counted again: the cash is kept in the process, not in the ledger.

Start-up. After the acceptance the engine runs its usual start-up reconciliation against the desk, through the desk’s order, fill and position queries (The execution fold). It then compares the desk’s owner book with the ledger’s recovery and refuses to start if any symbol’s quantity differs, naming each symbol with both quantities. An order the desk journal holds that the broker never saw (the engine stopped between the record and the submission) refuses the start, naming it, as a ledger file’s does.

The clock. The protocol runs against a desk whose broker port is the emulator: the engine steps the desk’s clock bar by bar, as it steps the emulator in an emulated live run, and the desk’s answer to each step must be the bar’s close. A desk on the wall clock is refused until real-time bars arrive (GLE-1440). Each intent carries the bar close it was decided at and is valid for one bar interval after it (clamped to between 5 seconds and 24 hours; 60 seconds on activity bars); the desk refuses one that arrives later with intent_expired. The members of a deployment step one clock, the broker port’s, so the desk runs their steps in bar order (docs/desk-protocol.md (docs/desk-protocol.md)).

The SIM clock. A desk in SIM may run its own clock instead (GLE-1380, docs/desk-protocol.md (docs/desk-protocol.md)). The member still reads its bars from history, as its backtest does, but before it steps an instant’s bars, or makes a timer’s decision, it awaits the instant at the desk with those bars. The desk moves its clock to the earliest instant once every member has said what it is due at next, fills the members’ resting orders against the instant’s bars, and answers with the events each bar made, tagged with the bar. The engine lets each event through once it has stepped its bar, so a fill reaches the strategy with the bar that made it, as in a backtest. The await has no timeout, since it waits on the other members and the operator. When the desk’s replay ends first, the run ends there as at the end of its data. A member on the SIM clock cannot take feed stream. A continuous series sends its contract bars, and its roll sends each contract’s price at the cut as a bar (Continuous futures in live mode).

The fake desk. engine/venuedesk/fakedesk serves the protocol over any live venue, in process or over HTTP/2, for tests: a smacross member run through it over the IBKR venue on the emulator fills exactly as the emulated live run and the backtest do. It serves several members at once. It keeps each member’s orders, fills and positions apart by symbol, so it refuses a second member on a symbol another member trades (symbol_shared). Config.Quorum holds every acceptance until that many members have said hello, so a test can tell members started together from members run in turn. It runs the members’ steps in bar order: a step waits until every other member in session has a later step waiting or has already stepped through the bar. Without that order, a member whose bars ran ahead would move the emulator’s clock past the bar another member’s order was decided at, and the emulator would hold that order out of its next bar (the simulator’s cross-symbol rule). With Config.Sim, a fill model such as fakedesk.SimPort over the backtest’s simulator, it runs on the SIM clock instead: a member run through it fills, and hears of each fill and cancel at the same bar, exactly as its backtest does, and two members step each instant together. Config.SimEnd ends its replay.