Add a TWS API feature

Target: $ARGUMENTS. The worked example with code is Extending the API (steps 1–9); this skill is the order of work and the checks around it. Ship with /ship.

C# reference: tws-api/source/csharpclient/client/ in the IBKR TWS API distribution (the maintainer's checkout: /Users/wboayue/projects/tws-api/). Protos: tws-api/source/proto/. It is authoritative for encoding and version gates. It is not authoritative for semantics (units, defaults, which values TWS accepts): for those, /live-probe.

1. Read the reference

Write these down before touching code:

For algo parameters, the Testbed sample (samples/CSharp/Testbed/AvailableAlgoParams.cs) is the wire spec; the docs page has conflated algos. For List<TagValue> options, protobuf encodes a map<string,string>.

2. Gate and proto

• Gate ≤ 213 (server_versions::PROTOBUF_REST_MESSAGES_3, the handshake floor): no check.
• Gate > 213 on a request: add the constant to src/server_versions.rs, a ProtocolFeature on Features (src/protocol.rs), and check_version(self.server_version(), Features::FOO)? before sending.
• Gate > 213 on a field: check only when the caller sets it, beside its siblings. Order fields: a local ProtocolFeature in orders/common/verify.rs (if order.conditions_include_overnight { check_version(..)? }).
• Either way, tests derive the boundary from the constant (derive from constants).
• Gate > advertised max (max_version in src/connection/common.rs): raise it. TWS then starts sending every field gated between the old and new max, so check each against our decoders in the same PR (#1045 raised it to 226).
• Proto missing from src/proto/protobuf.rs: just proto regenerates it from IBKR's latest protos, so it can carry unrelated upstream changes. Read the regenerated diff: a changed or removed field elsewhere is its own change. Commit the regeneration on its own so the feature diff stays reviewable.

3. Classify the shape

Rules for each: one-shot narrowing, proto-only decoding. A stream's End marker comes after the initial dump only, not after every push (wire facts).

4. Implement

Order: types → message ids → registration → encoder → decoder → sync → async.

• Layout: the domain owns it: types in <domain>/mod.rs (ungated), codecs in <domain>/common/{encoders,decoders}.rs, impl Client in <domain>/{sync,async}.rs (domain module layout). Shared logic lives once in common/, never copied across sync and async.
• Registration: miss any of these and the stubbed tests stay green while a live gateway hangs or drops frames:
  • IncomingMessages / OutgoingMessages variants in src/messages.rs
  • text_request_id_field in src/messages.rs for every inbound type that carries a request id. It is the routing allow-list; without it the frame never reaches the subscription (proto-aware accessors)
  • one-shot: the payload in impl_proto_payload! (src/proto/payload.rs)
  • stream: every handled type in RESPONSE_MESSAGE_IDS, plus the decoder in the roster checked by decoder_roster_is_complete
  • request ids come from mint_request_id(), never a caller (id partition)
• Encoder helpers: reuse ToField (src/lib.rs) and some_str & co. (src/proto/encoders.rs); add missing ones there, not locally. Mirror EClientUtils's "set only when" conditions exactly.
• Field typing (wire enum typing):
  • Required (Error::Parse when absent) only if C# drops the frame, or a default would fabricate a plausible wrong value. Otherwise tolerate: Option, or an open enum's Unknown/Other(""). A decode error ends a long-lived stream.
  • Enum only after the fixtures or C# show a fixed vocabulary; on a streaming path, open (fallback Unknown).
• Public API shape: three parameters or fewer, else a builder (param budget); one named setter per enum variant (builder enum coverage). Parameters every caller must pass go in the entry point, not a setter.

5. Test

• Fixtures in src/testdata/builders/<domain>.rs, field-minimal, free-function entry points (fixture builders); tests in sibling *_tests.rs files (sibling test files).
• Both sides: a sync and an async test through the real impl Client method, asserting the encoded request and the decoded result (exercise production code).
• Version gate: one test below the constant (error) and one at it.
• An absent-field case per field: Error::Parse for required ones, None / unset for the rest.

6. Document

• Rustdoc # Examples on each new pub fn and builder entry point, sync and async, each async example mirroring its sync sibling (public API examples). Check what a user copying it would see: an example that subscribes and then drops shows nothing.
• Gate in the rustdoc ("Requires server version N"), and units where they apply.
• Runnable example in examples/sync/ and examples/async/, each with an [[example]] entry in Cargo.toml (required-features). Run it against the paper gateway once: stubbed tests can't catch a missing routing entry.
• CHANGELOG.md under ## [Unreleased] (changelog entry).

7. Verify live

An integration test in integration/{sync,async}/tests/<domain>.rs when the API has observable behavior on a paper account (integration tests). For anything C# didn't settle (units, accepted values, absent-field defaults), /live-probe, and record the result in docs/wire-facts/.

Then /ship: wire changes also need the integration crate builds.