Task: Write up the wire-format architecture analysis and design decision

handler_helpers.hpp's reply()=/=decode() are the single choke point almost every service handler in the codebase goes through (mirrors why the compression task only needed to touch ores.nats's two choke points), but they are not the whole story: the heartbeat publisher and the workflow-engine's step-request/event-publish path both bypass handler_helpers.hpp entirely and hard-code rfl::json directly against the NATS client. All four of these extra call sites need to move onto the injected wire_codec too – the migration task must not assume handler_helpers.hpp alone closes out ores.service.

Every process_authenticated_request overload independently calls rfl::json::write(request) then, after the NATS round trip, rfl::json::read<ResponseType>(raw). exportPortfolio=/ =trade_instrument are deliberately concrete (non-template) wrappers – per their own doc comments, to keep template instantiation out of callers with heavy accumulated context (avoiding an MSVC C1202 limit) – so the migration must preserve that property, not templatise them away.

ClientManager is not the only ores.qt consumer, though. Two more call sites bypass it entirely:

Both need to route through the injected wire_codec as well.

One near-miss investigated and excluded: trading/OreImportWizard.cpp:862 (req.import_choices_json = rfl::json::write(choices)) encodes a domain field – an embedded JSON string carried inside ore_import_request – not the NATS wire-format serialization itself. The req object as a whole still goes through cm->process_authenticated_request(req, ...), which the ClientManager audit above already covers, so this is not an additional call site.

do_request=/=do_auth_request is not a shared helper – it is independently copy-pasted, in full, into the anonymous namespace of each command .cpp file (confirmed via projects/ores.shell/src/app/commands/currencies_commands.cpp:40-59 as a representative sample; the same two ~15-line templates recur verbatim). The actual breakdown, verified by grep rather than estimated:

• 13 files define their own copy of do_request=/=do_auth_request (account_parties_commands.cpp, accounts_commands.cpp, countries_commands.cpp, currencies_commands.cpp, change_reason_categories_commands.cpp, change_reasons_commands.cpp, variability_commands.cpp, tenants_commands.cpp, rbac_commands.cpp, plus bundles_commands.cpp, crm_commands.cpp, marketdata_commands.cpp, which each independently copy-paste their own do_auth_request), 18 definitions total (some files define both templates). provision_commands.cpp has a third, differently-shaped do_request – it takes a Request object plus a default timeout and authenticated bool and does its own internal rfl::json::write(req) – so the eventual shared helper needs an overload covering that shape too, not just a drop-in replacement for the other 12 files' identical pattern.
• 60 actual call sites invoke these templates (do_request<...>=/ =do_auth_request<...>) across the files above.

This duplication – 18 copies of essentially the same ~15-line template pattern (plus one differently-shaped variant) across 13 files – is a pre-existing debt, independent of this story, that the migration should fix as a side effect (one shared helper, with an overload for provision_commands.cpp's shape, instead of 13 copies) rather than propagate.

That is not the full picture, though: 7 more command files have rfl::json call sites that don't go through do_request=/ =do_auth_request at all, using some other/direct pattern against nats_client::request()=/=authenticated_request() not yet characterised in this doc – reports_commands.cpp, lei_commands.cpp, parties_commands.cpp, connection_commands.cpp, history_diff_renderer.cpp, synthetic_commands.cpp, workflow_commands.cpp (15 occurrences between them), plus the previously-known stragglers below:

Honest grand total (excluding config/options.cpp and config/login_options.cpp, which write a JSON options value to a stream with no nats_client=/=session.request reference nearby – config-file I/O, not NATS wire format, same exclusion rationale as ores.cli below): 101 rfl::json occurrences across 22 files. The migration task needs to consolidate all of it, not just the 13 files that already use the named template pattern.

ores.cli's rfl::json hits (config/import_options.cpp, config/delete_options.cpp, config/list_options.cpp, config/export_options.cpp, config/options.cpp, config/ore_roundtrip_options.cpp) are all config-file/CLI-option I/O – reading/writing a JSON options file, not building or parsing a NATS message body. Confirmed by inspecting the surrounding code: none of these call sites reference nats_client=/=client::request_sync=/=publish. Dropped from this story's scope entirely; no follow-up needed.

A concrete, non-polymorphic value type in ores.nats (new module, architecturally parallel to the already-shipped ores.nats::compression):

namespace ores::nats {

enum class wire_format { json, msgpack };

class wire_codec {
public:
    explicit wire_codec(wire_format format) : format_(format) {}

    // Illustrative: the real implementation needs a default/unreachable
    // arm (or equivalent exhaustiveness guard) so this doesn't trip
    // -Wreturn-type; omitted here for brevity.
    template <typename T>
    std::vector<std::byte> encode(const T& obj) const {
        switch (format_) {
            case wire_format::json:    return to_bytes(rfl::json::write(obj));
            case wire_format::msgpack: return to_bytes(rfl::msgpack::write(obj));
        }
        std::unreachable();
    }

    template <typename T>
    rfl::Result<T> decode(std::span<const std::byte> data) const {
        switch (format_) {
            case wire_format::json:    return rfl::json::read<T>(as_string_view(data));
            case wire_format::msgpack: return rfl::msgpack::read<T>(as_char_span(data));
        }
        std::unreachable();
    }

private:
    wire_format format_;
};

}

Deliberately not polymorphic (no virtual functions): the format is decided once, at construction, and never changes for the instance's lifetime – there is nothing here that benefits from indirection. wire_format is a plain 1-byte enum and wire_codec holds nothing else, so it is trivially copyable and cheap to pass by value, reference, or hold as a member wherever a consumer needs it. The switch inside encode=/=decode is not "runtime format switching" in the sense this story rejects (see below) – it is a single branch on a value fixed at process startup, not a per-message inspection of incoming data; the branch predictor sees the same outcome on every call for the process's entire lifetime.

Confirmed viable: reflect-cpp's rfl::msgpack::Writer already special-cases any MutableContiguousByteContainer (which std::vector<std::uint8_t> satisfies) via msgpack_pack_bin=/ =msgpack_pack_bin_body – native MessagePack binary framing, not an array of small integers and not base64. No custom serialization code is needed for any existing reflectable type; swapping wire_format is sufficient on its own.

One new .env value, e.g. ORES_NATS_WIRE_FORMAT=json|msgpack (default json, preserving today's behaviour for any process that doesn't set it), read once at process startup alongside existing NATS connection config (nats_options=/=nats_configuration). A single wire_codec instance is constructed from the resolved value and threaded to every consumer via dependency injection:

• Server (ores.service::messaging): reply()=/=decode() take (or close over) the codec; since these are free template functions already parameterised on the message type, the natural shape is an extra const wire_codec& parameter, or a codec held on the ores::nats::service::client instance already passed to every handler (avoiding a signature change to every handler).
• Qt client (ClientManager): one wire_codec member, constructed once when the client is constructed/connects, used by the consolidated request helpers (see the ClientManager migration task).
• Shell client: one wire_codec, constructed once at ores.shell's application startup, passed into the consolidated do_request=/=do_auth_request helper (see the shell migration task).