Wire protocols

The protobuf schema (proto/algolang/v1/algolang.proto) is the field-number reference. make proto regenerates gen/ using buf generate. Preserve wire compatibility: add fields, never renumber or repurpose existing fields. OrderbookAction values use the ORDERBOOK_ACTION_ prefix to avoid proto3 enum-name collisions. DBN payloads use Envelope.DbnRecordBatch (field 60) inside the protobuf control framing.

Strategy CSV carries one response per bar, cannot represent attached-order trees, and has narrower identifier/field support than protobuf. Use protobuf for multi-order decisions, brackets and richer data declarations. The exact grammars and validation live in internal/wire/csv_strategy.go and internal/wire/csv_data.go; changing them also requires checking the raw clients in strategies/demo. The stdio-csv-v2 grammar (its codec is internal/wire/csv2_strategy.go) answers each decision with a batch of cancels and orders and still refuses attached-order trees; the engine speaks it on a run under lifetime v2 (engine/stdiohost_csv2.go), and the Go SDK runs a strategy over it (sdk/strategy/run_csv2.go) (The stdio-csv-v2 grammar).

The current adjusted strategy CSV records are abar and afill, with roll for notices. Earlier implementation briefs called them cbar and cfill; those names did not ship. Protobuf bars carry raw OHLC, additive offset, multiplicative ratio, is_adjusted, and optional session metadata. Fills carry raw_price and adjusted_price, not a price_adjustment field. For additive adjustment, adjusted = raw + cumulative_adjustment. For ratio adjustment, adjusted = raw * cumulative_price_ratio.

InitAck.data_requirements (8) carries a declared bar series’ own construction (GLE-390). DataRequirement.bar_spec (4) carries every BarSpec field the declaration sets, and DataRequirement.session (5) carries its session; a declaration that sets neither marshals byte for byte as before. The CSV declaring record keeps its fixed eight fields and refuses a session or a construction field beyond kind, interval and threshold. sdk/barspec holds the shared Construction type. Its zero value is the run’s construction; its Validate, Normalise, Key, BarSpec and FromBarSpec are what the SDK, the run config and the engine all apply.

InitAck.aligned_series (field 12, message AlignedSeries: series_id 1, source 2, grid 3) carries the strategy’s aligned-series declarations (GLE-353). The engine reads them to validate each view and fetch its reach-back; the samples themselves never cross a wire. An InitAck without them marshals byte for byte as before. The CSV strategy wire has no grammar for them: the SDK’s CSV encoder refuses an InitAck that carries one (a raw CSV replay drops them, having no engine to read them). Bar carries no new wire field: SourceOpenTime, SourceCloseTime and Updates exist only on the SDK’s Bar.

Bar.tick_count (11), vwap (12), notional (13), buy_volume (14), sell_volume (15) and close_threshold (16) are the construction statistics of a trade-built bar. Since GLE-386 they cross the strategy wire as well as the data wire: internal/pbconv and the SDK’s mirrored converter map them to and from Bar.Stats, a block that exists exactly when tick_count > 0. A bar without the block marshals byte for byte as before. The CSV bar and abar lines have no slots for them, so a CSV strategy sees Stats == nil; the equity adjuster adjusts vwap with the bar’s prices.

Statistic.price (4) and Statistic.quantity (5) are proto3 optional since GLE-396, so a settlement carries a price and no quantity and an open interest a quantity and no price; Statistic.symbol names the dated contract. InstrumentDef.symbol (17) is the canonical dated symbol and maturity_year (18), maturity_month (19) and maturity_day (20) the calendar maturity the venue symbol encodes (0 where the publisher gives no such granularity). GetDataRequest.stat_types (16) names the statistic kinds a STATISTICS request wants; empty asks for every kind. The data SDK serves both schemas through data.StatisticSource and data.DefinitionSource on the pb data wire only and refuses them on DBN and CSV; the engine reads them with DataClient.FetchStatistics and FetchDefinitions (Statistics and instrument definitions).

BarSpec.lead_in (13, a google.protobuf.Duration) asks an event-bar request for a constructor lead-in (GLE-397). SupportedBarKind.serves_lead_in (6) advertises one per kind, and the data SDK refuses a lead-in the adapter did not advertise, a negative one, and one on time bars. GetDataResponse.lead_in (5, message LeadInReport: start 1, clamped 2, warmup_bars_discarded 3) rides the request’s final envelope, and DataClient.FetchBars returns it as FetchStats.LeadIn. Both travel on the pb data wire only, and the engine refuses a lead-in on the CSV wire. The bar cache key carries the lead-in as lead_in (a Go duration string, omitted when there is none, so earlier entries keep their hashes). GetDataRequest.session may name a custom:HHMM-HHMM window when the adapter’s SupportedSessions lists custom (Custom session windows).

GetDataResponse.chart_query (6; GLE-670) is the mf-chart query that reproduces the served series, as the adapter names it. Like snapshot_token, it rides the request’s FINAL envelope only, on every schema, and is empty on every other envelope and when the adapter supplies none. Its value is a JSON object (UTF-8 text) whose keys are mf-chart /api/v1/bars query parameter names and whose values are strings, such as {"symbol":"fut:XCME:ES:cont","interval":"1d-rth","from":"2018-01-02T00:00:00Z","to":"2026-08-31T00:00:00Z","adjust_anchor":"2026-08-31T00:00:00Z","snapshot_token":"s2:..."}. The data SDK sets it from DataContext.SetChartQuery, per request, and drops a value that is not a JSON object with a warning, so a feed can never put malformed JSON into a run’s artefacts. The engine treats it as opaque: DataClient.FetchBars returns it as FetchStats.ChartQuery, the bar cache stores it with the entry (a warm run reports what the cold run did), and the result header records each series’ main fetch’s as Series[].Chart (Artefact formats), which the .algorun export carries as chart_query_json. pb data wire only; the CSV and DBN wires have no field for it.

Envelope.market_events (field 62, message MarketEvents: repeated MarketEvent, each a series_id (1) and a oneof event holding a Trade (2), a Statistic (3), an InstrumentDef (4), an Observation (5) or a ContractListing (6)) carries declared trades (GLE-389), statistics and definitions (GLE-406), observations (GLE-408) and contract listings (GLE-410) to the strategy between bars. An observation is delivered at its available_at; a listing record at the instant in its meta.ts_recv, which is its known_at on its first delivery and a daily listing’s instant on a later one. An older SDK skips an unknown member. The strategy SDK sets InitAck.needs_market_events (15) when it declares a TRADES, STATISTICS, INSTRUMENT_DEFINITION, OBSERVATIONS or CONTRACT_LISTING series or implements MarketTradeHandler, StatisticHandler, DefinitionHandler, ObservationHandler or ListingHandler. The push is pb-only and gets no reply; a declaring strategy speaks pb already. A trade’s RecordMeta.flags carries the Databento flags byte (last, top_of_book, snapshot, aggregated for F_MBP, bad_ts_recv, maybe_bad_book; the two publisher-specific low bits are not carried), so MarketTrade.BadTsRecv reaches strategy code.

GetDataRequest.grid_revision (field 11) carries the calendar revision of an intraday grid request; the CSV get line carries it as an optional trailing grid_revision=HEX token, emitted only when set.

DataInitAck.bar_membership (8, enum BarMembership) says which bars an adapter puts in a window [start, end] (GLE-1344). BAR_MEMBERSHIP_UNSPECIFIED (0) is what an adapter that says nothing sends, and means the old rule, start <= ts_close < end, which the engine refuses (The date range). BAR_MEMBERSHIP_CLOSE_INCLUSIVE (1) is start < ts_close <= end: a bar owns its close. An adapter built on the Go data SDK declares its rule by implementing data.BarMembershipDeclarer (BarMembership() algolangpb.BarMembership). The SDK sends it on every data wire and adds it to the --algolang-describe-data output as bar_membership. The CSV data_init_ack line carries it as an optional fifth field, bar_membership=BAR_MEMBERSHIP_CLOSE_INCLUSIVE, written only when the adapter declares a rule; the sessions field before it is then written even when empty, as []. The engine does not act on the declaration yet. GLE-1342 will refuse an adapter that does not declare BAR_MEMBERSHIP_CLOSE_INCLUSIVE, because an adapter on the old rule paired with an engine on the new one would shift every run by one bar.

Error.request_scoped (3) and Error.request_id (4) carry a request-scoped refusal on the data wire (GLE-324 W10). Without the flag, which is every producer that predates the fields, an Error is fatal in either direction and ends the run. With it, the error answers the one request request_id names: the adapter keeps serving, and the engine fails that request alone. The data client returns it as an engine.RequestRefusal carrying the feed’s code and text; test for it with errors.As. The data SDK’s rule is that every error on a request’s path is request-scoped: a handler’s returned error (source_error), the SDK’s own request validation (bad_request, unsupported_schema) and a failed coverage lookup (coverage_failed). The fatal errors are the ones no request owns: a failed DataInit (init_failed), a protocol violation (protocol_error: a request before DataInit, an envelope or line the data wire has no meaning for), an engine-sent Error, and a broken stream, on which the SDK exits because nothing can be answered. On the CSV data wire the request-scoped form is its own line, refused,REQUEST_ID,CODE,MESSAGE; the error,CODE,MESSAGE line stays fatal. A refusal is the request’s own only on an exact, non-empty request_id: requests are served one at a time, so a refusal naming another request, or none, is a protocol error on the engine side, never a RequestRefusal, and the data client then refuses every later request on that connection before writing it, naming the earlier cause — as it does after an unscoped Error, a failed read or write, or a response its decoder rejected mid-stream (whose remaining envelopes are still on the stream). Every request kind — data, coverage, instrument info — sent before DataInit is a fatal protocol_error that never reaches the adapter’s handler. Compatibility in both directions: an engine that predates the fields reads a request-scoped Error as fatal and fails the fetch as it always has (the adapter is still up, so a later fetch on the same connection succeeds), and an engine with them reads an older adapter’s unscoped Error as fatal, exactly as before. Benchmark sleeves are the first consumer (see Report benchmark findings); a series fetch the feed refuses still fails the run, with the feed’s text rather than a dead connection’s.

ROLL_SCHEDULE is data schema 14. Its protobuf records contain the root, recipe hash, generation, election time, half-open held spans, paired seam prices and typed degradation flags. Three fields added for the calendar schedule (GLE-270, populated by marketfeed’s schedule v2, GLE-274) say what the pair and the chain are:

  • RollSchedule.seam_policy (12) names the measurement contract every seam’s pair conforms to; schedule v2 sends r1-settlement@trade-date-boundary/v1 (the R−1 settlement pair at the trade-date-boundary cut). Empty means a producer that predates the field, whose pair is the feed’s 1 m contemporaneous measurement at the cut.
  • RollSeam.degraded_reason (10) names the fallback rung that supplied the pair when degraded is true. Schedule v2 uses settle_window (the 1 m pair in the settlement window), last_common (the last common 1 m pair before the cut) and temporal.
  • RollSchedule.held_rank (7, optional) is the contract rank the rule holds: 0 is the front, 1 to 3 are B1 to B3. A rule may hold a deferred month on purpose, and the engine follows it (GLE-387). With no presence the rank is undisclosed, which does not mean the front; the engine refuses that.

The feed-owned continuous product’s wire additions landed in GLE-314 P0 (additive; no adapter or engine behaviour changed with them). On RollSchedule, the GLE-214 E0 lineage fields took their reserved numbers: superseded_by (8; 0 when the served generation is current, else the current generation number), derived_at (9; when the deriver last examined the lineage), last_bar_at (10; the end of the newest stored bar of the open front) and chain_checksum (11; sha256 hex over the canonical chain), plus snapshot_token (13), the identity of the served state. RollScheduleSpan gained optional cumulative_adjustment (6) and cumulative_price_ratio (7), the span’s constants at the request’s adjustment anchor (absent means undisclosed). GetDataRequest gained the pins snapshot_token (12), generation (13), as_of (14) and adjust_anchor (15), which apply to composite BARS and ROLL_SCHEDULE requests (and since GLE-398 as_of and snapshot_token to OBSERVATIONS, since GLE-399 to CONTRACT_LISTING), and adjust_anchor also to the BARS request of an adjusted equity (eq:V:T:adj=split|splitdiv; GLE-328 sets it to the run end on the warm-up and main fetches alike, so they share one basis), and which an adapter that predates them ignores; GetDataResponse.snapshot_token (4) echoes the served token on the final envelope only, and the data SDK sets it from DataContext.SetSnapshotToken. Bar gained seam_prior_contract (28) and seam_partial (29), the straddled-seam facts of a composite bar built across a roll cut, and CorporateActionType gained CA_SPINOFF (11) and CA_SUSPENSION (12) (CSV tokens spinoff and suspension). None of these travel on the CSV or DBN wires.

RollSchedule.next_roll (14, message NextRoll: from 1, to 2, cut 3) is the schedule’s next roll (GLE-1460, for GLE-1458): the open front’s contract, the contract the rule rolls into, and the cut. A live run on a real-time feed reads it to wake at the cut before the roll’s seam is served. It is unset when the producer does not know it, when the chain has no open front, and from a producer that predates it. It is a fact about the calendar, not the served chain, so it is in neither snapshot_token nor chain_checksum. A schedule without it marshals byte for byte as before.

Live bars (GLE-1440; owner ruling 10 Nov 2026) use the subscription messages the wire already defined, which nothing used before: SubscribeDataRequest (envelope 34), CancelSubscription (35), StreamData (36) and SubscriptionEvent (37). The ruling added three fields and changed nothing else. SubscribeDataRequest.start (9) is where the stream resumes: the adapter serves the bars that close after it. SubscribeDataRequest.adjust_anchor (10) is the adjustment anchor, as on GetDataRequest. Bar.provisional (30) marks a bar the source may still restate, which is every bar of a live tail (GLE-1118). A request or bar without them marshals byte for byte as before. Unlike a history request, a subscription is answered by pushes: the adapter sends a StreamData per batch of closed bars and a SubscriptionEvent per change of feed state, under the subscription’s request_id, interleaved with the answers to other requests. The adapter’s half is in Live bars from an adapter.

SubscriptionEvent.endpoints (4, message LiveEndpoint) is the live endpoints a bar or quote subscription’s source may read from, in the order it tries them, with their health (GLE-1740; owner ruling 18 Nov 2026, add only): marketfeed’s Databento gateways, named as the server list names them (db1, db2). One other name is possible. databento is Databento direct, only from a process run with MF_DATABENTO_DIRECT=1: a databento entry in the server list is refused, and no ordinary run reports it (The live source, GLE-1790, GLE-1793). Each has its name (1), whether the source reads from it now (current, 2), whether its status page answered the last poll (reachable, 3; for Databento direct, its dataset-condition API), when it last answered (polled, 4), the last poll’s error (poll_error, 5), how old its newest record was per dataset (streaming_age_ms, 6), and how long the source has failed to reach it (failing_ms, 7). The adapter sends them with each change of state, and again while CONNECTED in an event that repeats the state and reason, which is a refresh and not a change: an engine from before the field takes a repeated CONNECTED as nothing new. An event without them marshals byte for byte as before. The SDK’s half is BarStream.Endpoints and QuoteStream.Endpoints; the engine’s is StreamItem.Endpoints.

The same messages stream a futures root’s roll schedule and an equity’s corporate actions (GLE-1460), with no new field. A corporate-action subscription is a SubscribeDataRequest of schema CORPORATE_ACTIONS, and each push is a StreamData.corporate_actions (19) batch holding the whole state: every action of the symbol from start on, the empty batch when there is none.

Top-of-book quotes stream on the same messages too (GLE-1620). A quote subscription is a SubscribeDataRequest of schema QUOTES_L1 (2), QUOTES_L1_ON_TRADE (3) or QUOTES_L1_SAMPLED (4), the last with its sampling interval (7). Each push is a StreamData.quotes (12) batch of one or more Quote records, on stdio-pb-v1 only. GLE-1620 added one field: RecordMeta.ts_local (8), when the adapter received the record from its provider, on the adapter’s clock. It is set on live records only. For a quiet book the adapter sends again, it is when the adapter last saw the feed live. ts_event and ts_recv stay the provider’s. A record without it marshals byte for byte as before. The adapter’s half is in Quote subscriptions.

EXCHANGE_CALENDAR is data schema 15 (GLE-380, increment I11 unit A1 of the order-lifetime programme): versioned exchange-calendar facts, one record per exchange trade date of a futures root under a root-level header. The messages, the record rule, the adapter contract and the validator are in Exchange calendar facts; this paragraph is the wire. It is a GetData schema only: GetDataResponse.exchange_calendar (22, message ExchangeCalendarBatch: header 1, days 2) is its one response member, and StreamData and AppendDataRequest carry no counterpart, because a calendar is neither streamed nor appended. The framing is header first: the first envelope of a request carries the header and the first days, every later envelope carries days only, and total_count counts days (not envelopes, and not the header). The data SDK batches a calendar as it batches every schema: full envelopes of batch_size days go out with complete = false, and the final envelope carries the remaining days, possibly none, with complete = true and the total; so five days at batch_size 2 travel as three envelopes of 2, 2 and 1 days, four days as 2, 2 and 0, and no days as one envelope (the header, no days, complete, total 0). Of the request, symbol (a bare root, a dated contract or a :cont composite; the three share one calendar and the adapter resolves the root), start, end and batch_size (0 = 4096) reach the adapter; session, bar_spec, grid_revision and the composite pins (snapshot_token, generation, as_of, adjust_anchor) are ignored on this schema. GetDataResponse.snapshot_token rides the final envelope when the adapter set one, as on every schema; the SDK does not fill it from the calendar’s revision. pb wire only: DBN has no record type for it and the CSV grammar no encoding, and both refuse it (the refusal table in Exchange calendar facts).

Two existing messages gained a field each. InstrumentInfo.exchange_timezone (8) is the IANA name of the venue’s exchange-local clock (America/Chicago); empty from an adapter that predates the field or does not know it, and absent from the CSV init line, which is byte-identical with it set. The SDK mirrors it as InstrumentInfo.ExchangeTimezone (omitempty, so every artefact that embeds an InstrumentInfo is unchanged when it is empty), and it reaches a strategy through InitConfig.Instruments and ctx.Instrument(sym). InitAck.needs_calendar (14) mirrors needs_rolls: the strategy SDK sets it when the strategy consumes calendar facts (unit A3; Strategy SDK lookups), gating the engine’s push, and leaves it false otherwise, so the InitAck of a strategy that consumes none is byte-identical; the CSV init_ack line does not carry it. The contract’s draft numbered it 13, which I2’s capabilities had taken by the time the unit froze, so 14 is its number; the draft’s 15, 22 and 8 stand. The push is Envelope.exchange_calendar (61, message ExchangeCalendarBatch): one batch per root with the header and every served day, engine to strategy, after InstrumentsResolved and before the first warm-up bar, only to a strategy that set needs_calendar. 61 is the lowest tag above every allocated and reserved one (the strategy-side tags 1–29 are exhausted, 30–60 belong to the data-adapter, timer and DBN blocks, 53–54 are reserved), and the engine sends it since unit A2a (Engine side). Old readers see identical bytes when the new fields are unset; a reader built from the proto with every I11 addition stripped decodes every earlier field of an Init, an InitAck, a GetDataResponse and an Envelope that carry the new ones, keeps the new bytes as unknown fields, and a current reader recovers them intact.

OBSERVATIONS is data schema 16 (GLE-398): revision-aware observations of a release-stamped series, one Observation record per published value of a reference period. The record carries meta (1: ts_recv equals available_at, and so does ts_event when set), symbol (2), ref_date (3, YYYY-MM-DD), available_at (4), value (5, proto3 optional, absent exactly when withdrawn), withdrawn (6), revision (7, 0 = first release) and vintage_date (8, YYYY-MM-DD). GetDataResponse.observations (23, message ObservationBatch) is its one response member. It is a GetData schema only, like EXCHANGE_CALENDAR, so StreamData and AppendDataRequest carry no counterpart. Of the pins, as_of (14) asks for the series as known at that instant and snapshot_token (12) pins the adapter’s store; generation, adjust_anchor, session, bar_spec and grid_revision are ignored on this schema. The records of a response ascend strictly by (available_at, ref_date, revision). pb wire only: the SDK refuses it on DBN and CSV (Revisions: the OBSERVATIONS schema).

CONTRACT_LISTING is data schema 17 (GLE-399): the contracts of a futures root listed at an instant, one ContractListing record each. The record carries meta (1: ts_recv equals known_at, and so does ts_event when set), symbol (2, the canonical dated symbol), contract (3, the code), activation (4), expiration (5), maturity_year (6), maturity_month (7) and maturity_day (8; 0 = no such granularity), first_bar (9), last_bar (10, clamped to the instant), tick_size (11) and known_at (12). GetDataResponse.contract_listing (24, message ContractListingBatch) is its one response member; like OBSERVATIONS it is a GetData schema only. The request’s symbol is the root and as_of (14) the instant, which is required; snapshot_token (12) pins the adapter’s store, and start, end and the other pins are ignored. The records of a response ascend strictly by (expiration, symbol). pb wire only (Contract listings).

GLE-400 extends instrument metadata and the roll schedule.

  • InstrumentInfo gains three fields:
    • margin (9, message MarginRequirement, with presence). Its fields are initial (1), maintenance (2), currency (3), source (4, MarginSource: REGISTRY_SEED = 1, IBKR_WHATIF = 2), captured_at (5), account_dependent (6) and contract (7).
    • tick_size_source (10, TickSizeSource: REGISTRY = 1, DEFINITIONS = 2, UNSPECIFIED from an older adapter).
    • as_of (11). It is set exactly when the request carried as_of, and to the same instant.
  • InstrumentInfoRequest gains as_of (3). Unset asks for the latest facts, and an adapter that predates it ignores it.
  • RollScheduleSpan gains front (8). It is the code of the front contract while a deferred contract was held (held_rank > 0), and empty when the schedule holds the front or does not disclose it. The engine refuses a front on a front holding (FRONT_ON_FRONT_HOLD), a malformed code (FRONT_INVALID), the held contract itself (FRONT_IS_HELD), and a front that does not mature before the held contract (FRONT_NOT_AHEAD).

Every new field is additive, and an unset field marshals as before (Instrument metadata).

GLE-1358 adds InstrumentInfo.description (12): the instrument’s name for people, e.g. E-Mini S&P 500 for fut:XCME:ES. The engine copies it into ctx.Instrument(sym).Description and into each series of result.json’s header. An adapter that predates the field, or has no name, leaves it empty. It is unset when empty, so an instrument without one marshals as before. pb wire only: the CSV init line does not carry it.

GLE-1464 adds InstrumentInfo.ibkr (13, message IBKRContract, with presence): how IBKR knows the instrument. Its answer is one of terms (1, message IBKRContractTerms) and reason (2, for people). The terms are search_symbol (1), trading_class (2), sec_type (3, FUT or STK), exchange (4), currency (5), multiplier (6), price_magnifier (7) and contract_month (8, yyyymm, e.g. 202612 for Z26; empty for a root or a stock). It is unset from an adapter that predates it. The engine clears it before an InstrumentsResolved reaches a strategy. pb wire only (IBKR contract terms).

GLE-412 adds RollNotice.front (7): the front contract the incoming contract is held behind on a deferred schedule, as an engine code like from and to (e.g. ZQH26 while ZQJ26 is held). It is empty on a front holding.

The CSV roll line carries it as an optional seventh field, roll,SYMBOL,FROM,TO,TS,RAW_GAP,PRICE_RATIO[,FRONT]. The field is written only when set, so a front holding’s line is byte-identical to before. The parser accepts five, six or seven fields.

GLE-411 adds AccountState.initial_margin (8) and maintenance_margin (9), both optional: the margin the open positions require, in base_currency. It also fills margins (5) with each position’s requirement in its own currency. A venue that models no margin leaves them unset and empty.

GLE-391 adds AccountState.net_liquidation (7, optional): the account’s value in base_currency, every balance converted at the rate in force and open positions marked. The backtest’s per-bar account push sets it, and the balances list one entry per currency, the base first. A cash account state, or a venue that reports no value, leaves it unset; a computed value may be zero or negative. In the SDK it is AccountState.NetLiquidation with HasNetLiquidation. The CSV strategy wires carry no account state.

GLE-1372 adds the portfolio view. Envelope.portfolio_view (64, message PortfolioView) is engine to strategy, pb only, with no reply: sent immediately before a decision, only to a strategy whose InitAck sets needs_portfolio (16), and gated like needs_calendar. InitAck.portfolio_detail (17, PortfolioDetail: members, the default, or totals) and portfolio_curve (18, PortfolioCurve: none, the default, portfolio or members) say what the strategy asks the view to carry; the SDK sets all three from PortfolioWatcher, so the InitAck of a strategy that does not ask is byte-identical. A view carries as_of, a per-reader sequence, portfolio_id, base_currency, the reader’s member id and the visibility the portfolio file grants it; members; positions (member, logical symbol, contract, signed quantity, average price, mark and its time, point value, currency, open and realised P&L, notional); working orders (member, symbol, contract, client id, attempt, side, remaining quantity, type, limit and stop prices, time in force, reducing, state, submitted time); totals per symbol; and summaries, stats (all, long, short columns) and performance, each per member and for the portfolio (member ""). Positions, orders and totals are complete in every view; summaries, stats and performance are sent when they changed since the reader’s previous view, and curve carries only the points added or revised since then (a point at the time of one the SDK holds replaces it). Nothing in a view is later than as_of, and no decision made at as_of is in it. Both CSV strategy wires refuse needs_portfolio (stdio-csv-v1’s init_ack writer and stdio-csv-v2’s, with ErrCSV2NotExpressible); a raw CSV replay drops it, as it drops aligned series. See Reading the portfolio.

GLE-1458 adds the roll rebase. Envelope.rebase_notice (65, message RebaseNotice) is engine to strategy, with no reply (stdio-csv-v2 carries the same notice as a rebase block, GLE-1505). It is sent only on a run that negotiated roll-rebase, at each roll of an adjusted continuous series, straight after the roll’s RollNotice. It carries symbol (1), series_id (2, set when the series’ id is not its symbol), from (3) and to (4), at_date (5, the cut), gap (6, under panama the incoming price less the outgoing one at the cut; 0 otherwise), ratio (7, under ratio the incoming price over the outgoing one; 1 otherwise) and bars (8): the series’ newest bars on the incoming basis, oldest first, at most its warm-up depth. The SDK reads an unset ratio as 1. On stdio-csv-v2 StdioHost.SendRebaseNotice writes the same notice as a rebase block (Rebase blocks, GLE-1505); stdio-csv-v1 has no grammar for it, and the method refuses it. A strategy that predates it never receives it: the engine refuses that strategy at the handshake (Capability negotiation). See Re-adjusting at each roll.

The order-lifetime v2 wire (GLE-367, increment I2 of the order-lifetime programme) is additive and in effect only on a run that negotiated the lifetime-v2 capability (next subsection). Every field and message below is lifetime-v2: a v1 run sets none of them, so each is zero or absent there, and a message with none of them set marshals byte for byte as before. The strategy-side Envelope gains order_update (27, message OrderUpdate: one attempt’s status transition) and cancel_response (28, message CancelResponse: the classified answer to one cancel request), and since GLE-377 lifecycle_turn (29, message LifecycleTurn: one lifecycle decision turn), all engine to strategy; a v1 run receives none of them. Init.capabilities (6) carries the tokens the engine puts in effect and InitAck.capabilities (13) the tokens the strategy accepts. On the order messages:

  • Order.attempt (13): the attempt number of this physical submission under client_id, 1-based and increasing per label within one strategy instance. client_id stays the strategy’s label; (client_id, attempt) names one attempt, and every engine-to-strategy event about the attempt echoes both. 0 on a v1 submission.
  • Fill 11–14: attempt; exec_id, the venue’s execution identifier and the de-duplication key of a partial execution; order_ref, the engine’s durable canonical reference for the attempt; remaining_quantity, the quantity still working after this execution (0 on a full fill).
  • Order.legs (14, repeated ComboLeg), since GLE-409: the legs of a combo order, set only on a run that also negotiated combo-orders (Combo orders); symbol is then the legs’ combo symbol, quantity the combo units and a limit’s price the net per unit. Empty on every other order; combos travel on the order, and Envelope tag 54 stays reserved. ComboLeg 1–3: symbol, a dated contract; side, the action the leg takes when the combo is bought (a sold combo reverses every leg); ratio, the leg’s contracts per combo unit (positive).
  • Fill.combo_leg (15), since GLE-409: the 1-based index, in the combo’s legs, of the leg the fill executes. client_id and attempt are then the combo’s, symbol and side the leg’s, and remaining_quantity the combo units still working (the combo’s quantity until its last leg, then 0). 0 on any other fill.
  • Order.name (15) and Fill.name (16), since GLE-666: the order’s display name and its echo on the order’s fills (Naming orders). client_id stays the label. Empty when the strategy names none, and on a fill of no order: a roll leg, an expiry settlement, a corporate action’s leg.
  • Order.cancel_at (16), since GLE-1362: the instant at which the engine requests the attempt’s cancellation on the strategy’s behalf, a google.protobuf.Timestamp, unset for none (Order.CancelAt). The answer is a CancelResponse and, when it succeeds, an OrderCancel (CANCEL_REASON_EXPLICIT), both with request_id <client_id>/<attempt>/cancel_at.
  • OrderCancel 5–8: attempt, order_ref, request_id (echoes the OrderCancelRequest the cancel answers, when the reason is CANCEL_REASON_EXPLICIT, or <client_id>/<attempt>/cancel_at for the cancellation an order’s cancel_at asked for, GLE-1362) and remaining_quantity, the quantity still working when the order was cancelled.
  • OrderCancelRequest 2–3: attempt, the attempt to cancel (0 = the label’s current attempt, the v1 meaning), and a strategy-chosen request_id that the CancelResponse and the resulting OrderCancel echo.
  • AdoptedState.owner_id (3): the deployment identity the state was recovered under; every working order’s owner_id equals it. AdoptedOrder 10–19, the complete order frame: trail_amount, oco_group, attached_orders (each child a complete AdoptedOrder; a child of an unfilled parent carries status INACTIVE), attempt, order_ref, status, filled_quantity, remaining_quantity, submitted_at and owner_id. A v1 snapshot carries the nine v1 fields alone.
  • OrderDenied 4–5 and OrderRejected 5–6: attempt and order_ref of the attempt denied or rejected.
  • OrderUpdate, fields 1–13: client_id, attempt, order_ref, symbol, status, quantity, filled_quantity, remaining_quantity (the attempt’s original, cumulative filled and still-working quantities), timestamp, reason and broker_code (the venue’s or the engine’s text for a terminal or held transition), parent_client_id and owner_id; and, since I15 unit 2a (GLE-453), replaces_attempt (14), set only when the engine itself re-placed the order: a continuous roll re-places a working order on the incoming contract as a new attempt under the same client_id, and the update names the new attempt, its order_ref and the attempt it replaces, which ends without an OrderCancel of its own (Order lifetime v2 across a roll); 0 on every other update.
  • CancelResponse, fields 1–9: client_id, attempt, request_id, outcome, reason, status and remaining_quantity (the attempt’s state as evidence), timestamp and order_ref.
  • LifecycleTurn, fields 1–3: at, the instant; turn, 1-based within the instant; budget, the turns the run grants per instant. The strategy answers it exactly as it answers a Bar: zero or more OrderCancelRequest envelopes (and, since I12, TimerArm and TimerCancel envelopes), then one OrderResponse whose for_bar echoes at. No bar travels with it, so a turn advances no series (Lifecycle turns).
  • Enums: OrderStatus 0–12 (UNSPECIFIED, SUBMITTING, SUBMISSION_UNKNOWN, WORKING, PARTIALLY_FILLED, PENDING_CANCEL, HELD, INACTIVE, then the terminal FILLED, CANCELLED, REJECTED, DENIED, EXPIRED); CancelOutcome 0–4 (UNSPECIFIED, CONFIRMED, PENDING, REFUSED, UNKNOWN); and CancelReason gains GTC_EXPIRED (7, a GTC order cancelled at the venue’s quarter-end deadline), VENUE (8, the venue cancelled and the cause was not determined) and, since I14 unit 1 (GLE-455), CORPORATE_ACTION (9, the venue cancelled the order for a corporate action on its instrument; token corporate_action on both CSV grammars and in the lifecycle trace; Corporate actions and working orders (lifetime v2)) and, since I15 unit 2a (GLE-453), ROLL (11, the engine cancelled the order at a continuous roll: an order pinned to the outgoing contract, or a flat roll’s bracket child; token roll on stdio-csv-v2 and in the lifecycle trace; Order lifetime v2 across a roll) and, since I14 unit 2a (GLE-479), CONTRACT_EXPIRED (10, the value I15 unit 2a had reserved: the venue ended the order at its dated futures contract’s expiration; token contract_expired on both CSV grammars and in the lifecycle trace; Contract expiry (lifetime v2)). The SDK mirrors each value for value (OrderStatus, CancelOutcome, CancelReasonGTCExpired, CancelReasonVenue, CancelReasonCorporateAction, CancelReasonContractExpired, CancelReasonRoll); its CancelReasonParentCancelled (6) was added at the same time as 7 and 8, the proto having carried the value since June. Only a lifetime-v2 backtest produces 9, 10 and 11, so v1, every golden and the KBD masters are byte-identical. GLE-1375 added MOC_SEND_MISSED (12, the SDK’s CancelReasonMOCSendMissed, token moc_send_missed): a live run’s held market-on-close order whose send time and session close passed while the engine was down (Market-on-close orders).

The three new instants, OrderUpdate.timestamp, CancelResponse.timestamp and AdoptedOrder.submitted_at, are emitted only when set and decode as the zero time when absent; the v1 instants (Fill.timestamp, OrderCancel.timestamp, AdoptedPosition.opened_at) keep their v1 encoding, always emitted and the Unix epoch when absent, so the v1 bytes are unchanged. CancelReject is unchanged: it stays the v1 answer to a cancel the engine could not honour, and a run that negotiated lifetime-v2 answers every cancel request with a CancelResponse instead and sends no CancelReject. I2 defined the protocol and the conversions on both sides of the wire (internal/pbconv for the engine, sdk/strategy/run_pb.go and lifetime.go for the SDK; ToPBOrder also carries oco_group now, a correction with no production caller). The behaviour behind each field is its own increment: the attempt-indexed working view (I3, landed under GLE-372: on a run that negotiated lifetime-v2 the SDK stamps Order.attempt on its submissions, sends attempt and request_id on its cancel requests and keeps the view the events move; see The working view under lifetime v2); the lifecycle turns and the cancel classification on the simulated path (I4 unit 4a, landed under GLE-377: a backtest under lifetime v2 sends OrderUpdate, CancelResponse and LifecycleTurn, stamps attempt on every Fill and OrderCancel, echoes request_id and carries the simulator’s sim-N reference as order_ref; see Lifecycle turns); the live path’s turns and cancel classes (unit 4b); admission limits (I6); persisted ownership (I7: the live order_ref, exec_id and the extended adoption frame); recovery (I8; unit 1, the execution fold, landed: The execution fold) and CSV v2 (I10, landed: the grammar and its codec, the engine host and the Go SDK’s runner; The stdio-csv-v2 grammar).

The scheduled decisions (GLE-448, increment I12 unit 1; Scheduled decision points) put the timer messages the proto has carried since June 2026 into effect, on a run that negotiated lifetime-v2 and on stdio-pb-v1 only:

  • Envelope.timer_arm (50, strategy to engine, message TimerArm: timer_id 1, at 2, and since I12 anchor 3, the symbol whose exchange calendar at was computed from, empty for an absolute timer) and timer_cancel (51, TimerCancel: timer_id 1) travel in the strategy’s reply to a Bar, a LifecycleTurn or a TimerFired, before its OrderResponse and among its OrderCancelRequest envelopes. Anywhere else they are protocol errors.
  • Envelope.timer_fired (52, engine to strategy, TimerFired: timer_id 1, at 2, the instant armed, and fired_at 3, the decision’s instant, equal to at on today’s stepped loops) is a decision, answered exactly as a Bar is, with for_bar echoing fired_at.
  • Envelope.timer_refused (63, engine to strategy, no reply; the lowest free strategy-side tag above market_events’ 62) is the new message TimerRefused: timer_id 1 and at 2 as the strategy asked, code 3 (timer_invalid, timer_not_future, timer_after_end, calendar_incomplete, timer_limit or timer_coarse), reason 4, the engine’s text, starting with the code, and timestamp 5, the arming decision’s instant or, for timer_coarse, the timer’s own.

An instant the engine sends is unset when it is the zero time, so the refusal of an arm without an instant carries no at. An absolute TimerArm encodes as it did before anchor existed, and a run that arms no timer sends and receives none of these messages, so v1, every golden and the KBD masters are byte-identical. The CSV wires carry none of them: stdio-csv-v2 has no timer lines, and the host refuses to send a TimerFired or a TimerRefused on a CSV wire, naming stdio-csv-v2 when it is that wire. The Go SDK writes TimerArm and TimerCancel and dispatches TimerFired and TimerRefused since I12 unit 2 (GLE-451, sdk/strategy/timers.go).

Capability negotiation

A capability is a named token the engine puts in effect for a run; the vocabulary has three, lifetime-v2 (wire.CapabilityLifetimeV2, mirrored as algolang.CapabilityLifetimeV2), since GLE-409 combo-orders (wire.CapabilityComboOrders, mirrored as algolang.CapabilityComboOrders; Combo orders) and, since GLE-532, order-conviction-v1 (wire.CapabilityOrderConviction, mirrored as algolang.CapabilityOrderConviction; Order conviction). The handshake rides the Init / InitAck pair and both sides check it (internal/wire/capability.go).

A fourth token, roll-rebase (wire.CapabilityRollRebase, mirrored as algolang.CapabilityRollRebase; GLE-1458), is not the strategy’s to require or support. The engine offers it on stdio-pb-v1 and stdio-csv-v2 unless the rebase is turned off (on by default since GLE-1502), and the Go SDK accepts it by itself on stdio-pb-v1 and stdio-csv-v2 (GLE-1505), because the SDK restates the strategy’s prices at each roll. A strategy written without the SDK lists it in its v2 init_ack when it is offered (The v2 init and init_ack lines) (Re-adjusting at each roll). It is outside the vocabulary above, so a strategy that names it in RequiredCapabilities or SupportedCapabilities fails initialisation with the unknown-token error. The steps:

  1. The offer. The engine puts the tokens it selects in Init.capabilities (InitConfig.Capabilities in the SDK). An engine that predates the field offers none, and so does every run under the legacy profile (--lifetime v1, a live run’s default and a TRADES run’s). The v2 profile selects lifetime-v2: a plain backtest and, since I15 unit 2a (GLE-453), a continuous one offer it by default since I22 (GLE-470), and an emulated-live run under --lifetime v2 (Lifecycle turns); its config key is data.lifetime. The same profile adds combo-orders to the offer when the strategy runs on the pb wire and the run holds no continuous series (comboOffered); an emulated-live run offers it too, but its venue refuses every combo. It also adds order-conviction-v1 when the strategy runs on the pb or csv2 wire (convictionOffered), the two wires that carry a conviction; a strategy that leaves it unaccepted keeps its InitAck. The engine’s own tests set InitConfig.Capabilities and drive the run through StdioHost.Init.
  2. The acceptance. A strategy declares what it requires by implementing CapabilityRequirer (Reacting to fills and cancels). After the input values are applied and before OnInit, the SDK applies the strategy-side law, wire.AcceptCapabilities(offered, required), walking the required tokens in order. A token this build does not define is an initialisation error, Error code init_failed with the text wire: the strategy requires unknown capability "lifetime-v1" (this build knows: lifetime-v2, combo-orders, order-conviction-v1). A known token the engine did not offer refuses the run with Error code capability_unsupported and the text wire: capability not offered by the engine: the strategy requires "lifetime-v2" but the engine offered none; run it under an engine and execution profile that offer lifetime-v2 (GLE-200 I2) (none becomes the offered list, as [other], when the engine offered something else; the error wraps the sentinel wire.ErrCapabilityUnsupported, and algolang.Run returns it). Otherwise the required tokens go out in InitAck.capabilities, duplicates collapsed. On a refusal OnInit is not called. A strategy that serves both profiles declares what it supports instead, by implementing CapabilitySupporter (I16; Supporting lifetime v2 optionally): the SDK walks the supported tokens after the required ones, each through the same law on its own, so an unknown token is the same init_failed, an offered one is accepted (once, a token already required included) and one the engine did not offer is left out, the run proceeding. A strategy that requires nothing and supports nothing accepts nothing, and its InitAck is byte-identical whatever the engine offered.
  3. The check. The engine’s strategy host applies the engine-side law, wire.CheckCapabilities(offered, accepted), to the InitAck and refuses the run, prefixing the text with engine: <strategy name>:, when a token was accepted twice (wire: the strategy accepted capability "lifetime-v2" twice), when a token was accepted that was not offered (wire: the strategy accepted capability "lifetime-v2" that was not offered (offered: none), the list again rendered [a b] when non-empty), or when lifetime-v2 was offered and not accepted (wire: the run selected lifetime-v2 but the strategy did not accept it; a strategy that does not implement the v2 order lifetime must run under the legacy execution profile (GLE-200 I2), an error that wraps the sentinel wire.ErrLifetimeNotAccepted; on a backtest that names no profile the engine appends ; lifetime v2 is the default for a backtest: run <name> with --lifetime v1 (in a run-config file, "data": {"lifetime": "v1"}) for the legacy profile (GLE-470), <name> the strategy binary’s base name, Lifecycle turns), so no strategy runs under a lifetime it does not implement. Only lifetime-v2 is mandatory when offered: another offered token the strategy leaves unaccepted is tolerated, as is a token offered twice. That includes roll-rebase, which the run offers unless the rebase is turned off (GLE-1502). Whether a strategy that leaves it unaccepted may run is the engine’s decision, made once the run knows its adjusted continuous series (When the default gives way): an explicit --roll-rebase refuses it with engine: wire: the run re-adjusts continuous futures at each roll (--roll-rebase) but the strategy did not accept roll-rebase; a strategy on stdio-pb-v1 or stdio-csv-v2 must accept it when offered, and restate its own prices at each rebase (GLE-1458, GLE-1505); the run's adjusted continuous series: <labels> (turn roll rebase off with --roll-rebase=false), an error that wraps the sentinel wire.ErrRollRebaseNotAccepted, so no strategy keeps stale prices after a roll; left at its default, the run goes on without the rebase and says so.

The outcomes, with O = the engine offers lifetime-v2, R = the strategy requires it and S = the strategy supports it:

ORSOutcome
nononov1, byte-identical on both wires
nonoyesv1: the token is left out, the InitAck carries no capability and ctx.LifetimeV2() is false
noyesanythe SDK refuses before OnInit: Error{code: "capability_unsupported"} on protobuf, an error,capability_unsupported,... line on CSV, a non-nil Run error
yesnonothe host refuses the InitAck with the offered-and-not-accepted text, the default’s hint after it on a backtest that names no profile
yesyesanyInitAck.capabilities = ["lifetime-v2"]; the run proceeds and the SDK keeps the attempt-indexed working view (I3; The working view under lifetime v2)
yesnoyesthe same: the token is accepted once and ctx.LifetimeV2() is true

stdio-csv-v1 has no grammar for capabilities; stdio-csv-v2 (increment I10) carries them on its init and init_ack lines (The stdio-csv-v2 grammar), and a run under lifetime v2 offers it ahead of v1. The v1 CSV formatters refuse an Init that offers any and an InitAck that accepts any with one text, wire: capabilities [lifetime-v2] are not expressible in stdio-csv-v1; run the strategy on stdio-pb-v1 (GLE-200 I2), and the CSV parsers yield none. So the host cannot offer lifetime-v2 over CSV v1 (its Init fails before any line is written, with that text behind the engine: <strategy name>: prefix and, on a backtest that names no profile, the default’s hint after it), and a strategy that requires it on the v1 CSV wire, where no offer reaches it, is refused by the SDK with the same capability_unsupported code, as the line error,capability_unsupported,<message, commas replaced by ';'>. The code is not request-scoped on either wire; init_failed covers an unknown token and every other initialisation failure.

Compatibility runs in both directions. A reader built from the pre-I2 schema decodes every v1 field of a v2 message, keeps the v2 fields as unknown bytes and re-encodes them unchanged; CancelReason values 7, 8, 9 and 11 reach it as their numbers (proto3 enums are open); a v2-only envelope decodes on it with no message set, which the v1 SDK reports as the unexpected <nil> on the strategy wire protocol error — the reason a host sends OrderUpdate and CancelResponse only to a strategy that accepted lifetime-v2. In the other direction a v1 run is byte-identical on both wires: an Order with attempt 0, a Fill and an OrderCancel with their four new fields zero, an AdoptedState with no owner and v1 frames, an Init and an InitAck with no capabilities each marshal as the v1 message built from the v1 fields alone. That identity reaches the run’s artefacts too: sim.FillReport embeds algolang.Fill, so the new fields on the existing SDK structs (Order, Fill, OrderCancel, InitConfig, InitAck, AdoptedState, AdoptedOrder) carry json:",omitempty" and a v1 run’s --fills-json blotter is unchanged; the three KBD masters and the engine/sim FillReport JSON golden pin it.