Story: Make NATS wire format configurable: JSON/MessagePack, decided once at startup

Decided in the write-up task. A self-describing, per-message header (mirroring the compression feature's X-Content-Encoding) was considered and explicitly rejected in favour of a wire_codec value type holding a wire_format fixed at construction from a .env value, read once at process startup and threaded to every consumer via dependency injection. Rationale: wire format is a binary, environment-wide choice with no natural per-message trigger, unlike compression's genuinely per-message, size-dependent decision – the header approach's flexibility (safe mixed-fleet rollout) isn't a requirement here, and .env is explicitly the intended control surface. Full blast-radius audit (6 call sites in ores.service, ~10 plus stragglers in ores.qt, 101 across 22 files in ores.shell; ores.cli confirmed out of scope) and the wire_codec type's shape are recorded in that task's * Plan.

Decided in the wire_codec build task. The --nats-wire-format option (env ORES_NATS_WIRE_FORMAT, same per-service prefix convention as the existing nats-tls-* options) defaulted to json while every layer was being migrated, preserving pre-existing behaviour for any process that didn't set it. With the end-to-end verification task confirming every layer round-trips correctly under msgpack (server-to-server, Qt client, and shell client, including image-carrying flows), the default was flipped to msgpack at this story's close – the whole point of making the format configurable was to stop paying json's base64 tax on binary payloads by default, not just to make it possible to opt in per environment. An unrecognised value throws std::invalid_argument at startup rather than silently falling back – misconfiguration is a fail-fast error, not a silent default. ores.nats.lib links reflectcpp::reflectcpp publicly (previously only transitively/privately via ores.utility.lib) since wire_codec.hpp is a public, header-only template type every consumer needs rfl/json.hpp=/=rfl/msgpack.hpp for.

Decided in the handler_helpers migration task. decode<Req>(msg) is called from ~250+ handler call sites across every service, none of which have a wire_codec or client reference in scope – threading one through would mean editing every call site, defeating this task's "single change, no per-handler edits" goal. Resolved with ores::nats::default_wire_codec()=/=set_default_wire_codec(): a process-wide default set automatically by nats::service::client's constructor (every server process constructs exactly one client, from its resolved nats_options), so handler_helpers.hpp's reply()=/=decode() (and the heartbeat_publisher=/=workflow_helpers stragglers) read it with zero edits anywhere else. This is a deliberate, narrow exception to per-instance dependency injection – justified because wire format is a single process-wide, decided-once-at-startup value, not a per-instance or per-message choice, matching this story's core architectural decision above.

Discovered live during the ClientManager task's msgpack smoke test, not by the write-up task's static audit: ores.iam.client::service_token_provider – every service's self-authentication call at startup – hard-coded rfl::json, entirely outside any completed task's file scope. This is as universal a blocker as a bug can be: a msgpack-configured process couldn't authenticate itself, let alone serve a single request, until fixed. Fixed in the same commit, same shape as every other fix in this story (ores::nats::default_wire_codec()). Take-away for the remaining tasks: the write-up's static grep-based audit, however careful, could not find every service-to-service NATS call site – prefer a live msgpack smoke test (see the test scenario that caught this) over trusting the audit alone before declaring the story done. A repo-wide sweep at the same time found several more such call sites (party_cache.hpp, tenant_handler.hpp, crm_client.cpp, currency_pair_convention_cache.hpp, report_definition_template_handler.hpp, trade_handler.hpp), tracked as * Notes on the end-to-end-verify task rather than fixed here, to keep this task's diff scoped to =ores.qt=/its one universal blocker.

Decided in the ores.shell migration task, on explicit request mid-task: ores.qt::ClientManager and ores.shell each originally grew their own thin encode/transport/decode wrapper around wire_codec independently. Rather than leave two parallel copies, the actual primitive (request_and_decode=/=authenticated_request_and_decode, templated on Response=/=Request, returning rfl::Result<Response>) moved down into ores.nats/service/request_helpers.hpp, callable by any NATS consumer regardless of its error-reporting convention. ores.shell's do_request=/=do_auth_request (std::optional plus an ostream failure message) and ClientManager's unauthenticated process_request()=/=testConnection()=/=signup() (std::expected) both now call it directly; ClientManager's three header-scoped authenticated overloads keep their own thinner encode_request=/=decode_response wrappers, documented as deliberate rather than accidental duplication, since send_authenticated_request* must return raw bytes (not a decoded value) to preserve the MSVC-C1202-avoiding TU isolation ClientManagerExportPortfolio.cpp=/=ClientManagerTradeInstrument.cpp already relied on.

Decided in the migrate-remaining-call-sites task. A whole category of rfl::json::write=/=read call sites are not wire-payload encoding at all: workflow command_json=/=result_json (persisted DB columns, published raw by workflow_engine::publish_command regardless of wire_format), scheduler job_definition::action_payload, nested request_json fields carrying an inner request as opaque text inside an outer wire message, and the JWKS public-key bootstrap exchange (deliberately JSON-only since it may run before a client's own wire_codec is established). These are left as rfl::json by design, not migrated – doing so would either be a category error (the field's value happens to be JSON text, it isn't the transport encoding) or require an unrelated DB schema change. Documented in doc/knowledge/architecture/nats_wire_format.org as the standing reference for this distinction, since it recurs on every future audit. Also found and fixed one genuine producer/consumer mismatch along the way: workflow_engine.cpp's on_step_completed=/=on_start_workflow still hard-coded JSON decode while their publishers (workflow_helpers.hpp, workflow_handler.cpp) already used wire_codec – a latent bug under any msgpack configuration, now fixed.