Order lifecycle trace
--lifecycle-json PATH writes a second machine-readable artefact beside the fill blotter: the order lifecycle trace, schema algolang.lifecycle/1. --fills-json shows what filled. The trace shows everything the venue was asked and everything it answered, in the order the bar loop saw it:
- every submission, in the strategy’s frame and in the venue’s (on a continuous run the logical symbol with adjusted levels against the dated contract with raw levels; on an adjusted equity series the adjusted levels against the raw ones), with the venue’s answer:
acceptedunder a broker id,deniedwith the simulator’s reason, orrejectedby the engine before the venue saw it; - every cancel request the strategy made, and whether the venue honoured it;
- every fill and every cancel the venue produced, with the cancel’s reason (
explicit,tif_expired,gtc_expired,oco_triggered,parent_cancelled,corporate_action,contract_expired,roll,moc_send_missed,rejected,shutdown), the basis of the exchange-calendar instant a Day or GTC order was ended at (since GLE-468), and whether the strategy was shown it — a continuous roll’s own legs and the cancels it hides on the outgoing contract are suppressed from the strategy but present in the trace; - under lifetime v2, each dated futures contract’s expiry at the venue (since GLE-479): the contract, the continuous series holding it when one does, the position the venue settled and at what price, where that price came from, the orders it cancelled, and whether the expiry came late (Contract expiry (lifetime v2));
- each continuous roll: the net position rolled, the standalone orders re-translated onto the incoming contract, the bracket children re-established on the open leg, and the contract-addressed orders cancelled; and, once the roll has executed, its account (since GLE-459): the roll’s trade date, the orders the venue’s GTC deadline ended at the roll, and every order it found with its fate, re-placed, cancelled, dropped or lost with the simulator’s reason;
- under lifetime v2, every arm, disarm, fire and refusal of a strategy timer (Scheduled decision points), with its instants, its anchor, the refusal’s code and reason, and the decision it belongs to (since GLE-458);
- one snapshot of the working set, taken after the last bar’s submissions and before the end-of-data cancellation sweeps it;
- a summary of 25 counts (bars, signals, submissions by outcome, first eligible evaluations, unfilled resting orders, fills, cancels by class, rolls, the working set at the end), with the orders the rolls re-placed, lost and expired, the contract expiries and the timer counts beside them on a run that has them, then the same
capital,equity,realizedandfillsthe fill blotter carries.
Use it when the question is an order’s lifetime rather than its P&L: why an order rested unfilled, and whether the simulator evaluated it at all (first_eligible_evaluations against unfilled_resting); what the shutdown cancellation swept away (working_at_end and the snapshot, each entry of which is followed by a shutdown cancel); whether a cancel request reached the book, and which attempt it addressed; which level and which contract a roll re-translated a resting order to, and under which new broker id; which order a roll lost, and why the venue denied its replacement; which orders the venue denied and why; when a timer fired, what its decision did, and why a timer was refused. It is the evidence base of the order-lifetime programme (GLE-366 is the increment that added it): the trace observes and decides nothing.
Trace on or off, a run’s fill blotter, printed report and BENCH line are byte-identical (timings aside), and the trace’s capital, equity, realized and fills decode equal to the --fills-json file of the same run. Two runs of the same input write the same trace.
It is a command-line option only, like --fills-json: no run-config key sets it (a config’s report.fills writes the blotter alone). It covers backtest strategy runs, plain and continuous: since GLE-421 both run through the one bar loop, a continuous series’ bars through its frame. Two cases refuse it before any adapter or strategy is spawned, so the run fails at once:
algo: engine: --lifecycle-json is a backtest-only export (live orders belong to the venue ledger)
algo: engine: --lifecycle-json needs a strategy run (schema BARS, not TRADES)
A write failure (a missing directory, say) fails the run, as the blotter’s does. The file’s layout is in The lifecycle trace schema.
A plain-loop example. The e9equity demo strategy buys 100 shares at market on its first bar and rests a GTC sell-stop at half that bar’s close. Run it over eight flat daily bars of a file-csv fixture (flat at 100, so the stop at 50 cannot trigger):
bin/algo run \
--adapter bin/file-csv-adapter --adapter-inputs Path=aapl-1d.csv,Interval=1d \
--strategy bin/e9equity --symbols AAPL --bar-interval 1d \
--date-from 2026-03-10T00:00:00Z --date-to 2026-03-20T00:00:00Z \
--simulation-resolution bar --run-id lc-demo \
--fills-json fills.json --lifecycle-json trace.jsontrace.json holds five records. The file writes one key per line; it is re-flowed here, and the blotter section is elided:
{
"schema": "algolang.lifecycle/1",
"run": {"run_id": "lc-demo", "mode": "plain", "symbols": ["AAPL"],
"lifetime": "v2", "lifetime_source": "default"},
"summary": {
"bars": 8, "signals": 1, "submitted": 2, "accepted": 2, "denied": 0, "rejected": 0,
"attached_children": 0, "replacements": 0,
"first_eligible_evaluations": 2, "unfilled_resting": 1,
"fills": 1, "suppressed_fills": 0,
"cancel_requests": 0, "cancels_accepted": 0, "cancel_rejects": 0,
"explicit_cancels": 0, "unsolicited_cancels": 0, "shutdown_cancels": 1,
"rejection_cancels": 0, "suppressed_cancels": 0,
"rolls": 0, "roll_resubmits": 0, "roll_legs": 0, "pinned_cancelled": 0,
"working_at_end": 1
},
"records": [
{"seq": 1, "kind": "submit", "bar": 0, "at": "2026-03-10T00:00:00Z",
"source": "strategy", "client_id": "e9_entry_20260310T000000",
"symbol": "AAPL", "side": "buy", "type": "market", "quantity": 100,
"price": 0, "stop_price": 0, "trail_amount": 0, "tif": "day", "oco_group": "",
"venue_symbol": "AAPL", "venue_price": 0, "venue_stop_price": 0, "venue_trail_amount": 0,
"status": "accepted", "broker_id": "sim-1", "reason": ""},
{"seq": 2, "kind": "submit", "bar": 0, "at": "2026-03-10T00:00:00Z",
"source": "strategy", "client_id": "e9_stop_20260310T000000",
"symbol": "AAPL", "side": "sell", "type": "stop", "quantity": 100,
"price": 0, "stop_price": 50, "trail_amount": 0, "tif": "gtc", "oco_group": "",
"venue_symbol": "AAPL", "venue_price": 0, "venue_stop_price": 50, "venue_trail_amount": 0,
"status": "accepted", "broker_id": "sim-2", "reason": ""},
{"seq": 3, "kind": "fill", "bar": 1, "at": "2026-03-11T00:00:00Z",
"delivered": true, "origin": "sim-1", "client_id": "e9_entry_20260310T000000",
"parent_client_id": "", "symbol": "AAPL", "venue_symbol": "AAPL",
"side": "buy", "quantity": 100, "price": 100, "venue_price": 100, "commission": 0},
{"seq": 4, "kind": "snapshot", "bar": 7, "at": "2026-03-19T00:00:00Z",
"working": [
{"broker_id": "sim-2", "client_id": "e9_stop_20260310T000000", "venue_symbol": "AAPL",
"kind": "top", "source": "strategy", "parent_client_id": "",
"symbol": "AAPL", "side": "sell", "type": "stop", "quantity": 100,
"price": 0, "stop_price": 50, "trail_amount": 0, "tif": "gtc",
"venue_price": 0, "venue_stop_price": 50, "venue_trail_amount": 0,
"submitted_seq": 2}]},
{"seq": 5, "kind": "cancel", "bar": 7, "at": "2026-03-19T00:00:00Z",
"delivered": true, "origin": "sim-2", "client_id": "e9_stop_20260310T000000",
"reason": "shutdown", "triggered_by": ""}
],
"capital": 100000, "equity": 100000, "realized": 0,
"fills": [ ... ]
}Reading it:
- The
runobject names the run and, since order lifetime v2 became the backtest default (GLE-470), its profile and how it was chosen: the command names none, so the run is lifetime v2 by default, and each fill of the elided blotter section carries itsAttempt(1). Under--lifetime v1, the legacy profile, the two keys and theAttemptfields are absent and the rest of the file is the same. - Records 1 and 2 are the two orders bar 0 returned, stamped at that bar’s close (
aton a submission is the simulator’s clock) and accepted as attemptssim-1andsim-2. On this unadjusted series the two frames coincide (symbolandvenue_symbol,stop_priceandvenue_stop_price); on an adjusted equity series or a continuous run they differ. - Record 3: the market buy filled on bar 1, the next bar of its symbol (an order decided on bar N first evaluates on bar N+1).
originnames the attempt the fill descends from, anddeliveredsays the strategy received it. - Record 4: the snapshot after the last bar (bar 7) lists the stop, still working, joined (
kind: top) to the record that submitted it (submitted_seq: 2). - Record 5: the shutdown cancel that swept it, after the snapshot, so
working_at_end: 1andshutdown_cancels: 1describe the same order. - The summary:
first_eligible_evaluations: 2— both attempts reached a bar on which the simulator evaluated them;unfilled_resting: 1— the stop’s own terminal was a cancel, not a fill;signals: 1— one bar carried strategy activity.
Since the order-lifetime programme’s I21 (GLE-467, PR5) the three e9 demos (e9equity, e9rename, e9reuse) declare optional lifetime-v2 support, and a cf21_conform_test.go beside each runs it under both profiles over its end-to-end fixture, the split, the rename and the ticker reuse served with their corporate actions through the file-csv adapter. The rename re-keys the resting stop under both profiles; the split rewrites it under the legacy profile, as above, and cancels it under v2, the venue’s rule (Corporate actions and working orders (lifetime v2)), after which e9equity re-places it on the ex-date bar under its label, for the rewritten lot at the split-adjusted level (GLE-498); and e9_adoption_test.go beside e9equity and e9rename pins their stops across adoption (Conformance under both lifetimes).
A timer, from the closetimer demo. Under lifetime v2 the trace also records the strategy’s timers. The closetimer demo (Scheduled decision points) rests a GTC limit buy at its first bar inside the RTH window and arms the session timer close for the RTH close; the timer’s decision cancels the order. Over the fixtures of TestLt458ClosetimerTrace (minute bars of fut:XCME:ES:M26 on 2026-03-12 closing from 14:31Z to 14:35Z, then one closing at 21:06Z), the trace holds six records (re-flowed, the submit abridged):
"records": [
{"seq": 1, "kind": "submit", "bar": 0, "at": "2026-03-12T14:31:00Z", "source": "strategy",
"client_id": "entry-2026-03-12", "side": "buy", "type": "limit", "price": 98, "tif": "gtc",
"status": "accepted", "broker_id": "sim-1", ...},
{"seq": 2, "kind": "timer", "bar": 0, "at": "2026-03-12T14:31:00Z", "event": "arm",
"timer_id": "close", "timer_at": "2026-03-12T21:00:00Z", "anchor": "fut:XCME:ES:M26",
"fired_at": "", "code": "", "reason": "", "decision": "bar", "decision_seq": 0, "turn": 0},
{"seq": 3, "kind": "timer", "bar": 4, "at": "2026-03-12T21:00:00Z", "event": "fire",
"timer_id": "close", "timer_at": "2026-03-12T21:00:00Z", "anchor": "fut:XCME:ES:M26",
"fired_at": "2026-03-12T21:00:00Z", "code": "", "reason": "",
"decision": "timer", "decision_seq": 3, "turn": 0},
{"seq": 4, "kind": "cancel_request", "bar": 4, "at": "2026-03-12T21:00:00Z", "source": "strategy",
"client_id": "entry-2026-03-12", "broker_id": "sim-1", "status": "accepted", "reason": ""},
{"seq": 5, "kind": "cancel", "bar": 5, "at": "2026-03-12T21:00:00Z", "delivered": true,
"origin": "sim-1", "client_id": "entry-2026-03-12", "reason": "explicit", "triggered_by": ""},
{"seq": 6, "kind": "snapshot", "bar": 5, "at": "2026-03-12T21:06:00Z", "working": []}
],Reading it:
- Record 2: bar 0’s reply carried the arm.
decision: barwithturn: 0says it came in the bar’s own reply, not a lifecycle turn’s.timer_atis the instant the strategy computed from the calendar, andanchorthe symbol whose calendar it used. - Record 3: the timer fired at 21:00, between bar 4 (closing 14:35) and bar 5 (closing 21:06), so it carries bar 4’s index and the timer’s instant. A fire opens the timer’s decision and names it by its own seq,
decision_seq: 3. - Record 4 is that decision’s cancel request, stamped at the timer’s instant. A timer record of the same decision, a re-arm say, would carry
decision: timeranddecision_seq: 3. - Record 5: the venue’s cancel is delivered at the top of bar 5, stamped 21:00, so nothing on the 21:06 bar, which trades down to 90, is matched against the order.
The summary adds "timers": {"arms": 1, "cancels": 0, "fires": 1, "refusals": 0} after working_at_end. With Withdraw=false the demo arms no timer, and its trace has neither timer records nor the timers key.