NATS Idiomatic Architecture: Drop Binary Protocol, Adopt MessagePack + JetStream

The 2026-03-13 NATS migration plan replaced the TCP/SSL transport with NATS but preserved the custom binary frame format (magic bytes + uint16 message type + JWT + payload). NATS was therefore used as a dumb pipe — its routing, pub/sub, and persistence capabilities were completely ignored.

This plan supersedes the original plan's remaining phases with a fully idiomatic NATS architecture:

• NATS subjects replace the uint16 message type field for routing
• MessagePack (rfl::msgpack) replaces the custom binary frame as the payload format
• Authorization: Bearer <token> in NATS message headers replaces JWT-in-frame
• JetStream replaces PGMQ (ores.mq) for durable queuing from day one
• Queue groups provide horizontal scaling at zero cost
• ores.comms is deleted entirely — NATS is the bus, not a thin wrapper over it

No backwards compatibility is required. The system may be non-functional between phases.

• Phases 1–3 of the original plan are complete: NNG removed, cnats added, ores.comms.service uses NATS transport via nats_server
• 10 domain service scaffolds exist (ores.mq.service deleted today)
• Qt client and shell still use binary frames via the old nats_client
• ores.comms still exists and is depended on by multiple projects

PR: [nats] Replace nats_server/nats_client with clean client interface

Remove all ores.comms dependencies from ores.nats. Implement the new interface with full Pimpl.

Client interface:

class client {
public:
    explicit client(config::nats_options opts);
    ~client();
    client(const client&) = delete;
    client& operator=(const client&) = delete;

    // Lifecycle
    void connect();       // synchronous, throws on failure
    void disconnect();
    [[nodiscard]] bool is_connected() const noexcept;

    // Request/reply
    [[nodiscard]] message request_sync(
        std::string_view subject,
        std::span<const std::byte> data,
        std::unordered_map<std::string, std::string> headers = {},
        std::chrono::milliseconds timeout = std::chrono::seconds(30));

    [[nodiscard]] boost::asio::awaitable<message> request(
        std::string_view subject,
        std::span<const std::byte> data,
        std::unordered_map<std::string, std::string> headers = {},
        std::chrono::milliseconds timeout = std::chrono::seconds(30));

    // Core pub/sub
    void publish(std::string_view subject,
        std::span<const std::byte> data,
        std::unordered_map<std::string, std::string> headers = {});

    [[nodiscard]] subscription subscribe(std::string_view subject,
        message_handler handler);

    [[nodiscard]] subscription queue_subscribe(std::string_view subject,
        std::string_view queue_group,
        message_handler handler);

    // JetStream
    void js_publish(std::string_view subject,
        std::span<const std::byte> data,
        std::unordered_map<std::string, std::string> headers = {});

    [[nodiscard]] subscription js_subscribe(
        std::string_view subject,
        std::string_view durable_name,
        message_handler handler);

    [[nodiscard]] subscription js_queue_subscribe(
        std::string_view subject,
        std::string_view durable_name,
        std::string_view queue_group,
        message_handler handler);

    void drain();

private:
    struct impl;
    std::unique_ptr<impl> impl_;
};

Working state: ores.nats compiles with no ores.comms dependency. Existing users of nats_server (ores.comms.service) and old nats_client (ores.qt, ores.comms.shell) do not yet compile — fix in subsequent phases.

PR: [nats] Wire up domain services with idiomatic subjects and MessagePack

Each of the 10 domain services registers subject-based handlers using client::queue_subscribe. The domain registrar interfaces change: instead of taking a message_server&, they take a nats::client& and register their own subject handlers directly.

Pattern for each service application.cpp:

// 1. Create DB context
auto ctx = make_context(cfg.database);

// 2. Create NATS client
nats::client nats(cfg.nats);
nats.connect();

// 3. Register domain handlers (queue group = service name)
ores::iam::messaging::registrar::register_handlers(
    nats, "ores.iam.service", ctx, ...);

// 4. Run (block until SIGINT/SIGTERM)
nats.drain();

Registrar subject convention:

Each domain registrar implementation replaces binary-frame dispatch with per-subject queue_subscribe calls. Payload is deserialised with rfl::msgpack. JWT is extracted from the Authorization header.

ores.comms.service is deleted once all 10 services are wired.

Working state: All 10 services start, connect to NATS, and handle domain requests. Shell and Qt clients are still broken (next phase).

PR: [cleanup] Delete ores.comms and ores.comms.service

Working state: Clean build with no ores.comms or ores.mq in the tree.

PR: [nats] Rewrite ores.comms.shell using ores.nats::client

ores.comms.shell currently builds binary frames and sends them via the old nats_client. Replace with direct nats::client usage:

• Each shell command calls client.request_sync() to the appropriate subject
• Payload serialised with rfl::msgpack
• JWT placed in the Authorization header

Working state: Shell commands work against the new domain services.

PR: [nats] Rewrite ores.qt ClientManager using ores.nats::client

ClientManager currently wraps the old nats_client (which wrapped client_base). Replace with nats::client:

• connect() / disconnect() map directly
• Each request from a Qt dialog calls request_sync() or the async request()
• Notifications: Qt dialogs subscribe to ores.{domain}.v1.events.> via client.subscribe(); callbacks are posted to the Qt event loop via QMetaObject::invokeMethod(..., Qt::QueuedConnection)

Working state: Full Qt application functional. Login, all dialogs, live updates all work via NATS.

PR: [nats] Bridge ores.eventing to JetStream pub/sub

The existing ores.eventing Postgres NOTIFY → event bus pipeline is extended: instead of notifying a subscription_manager, each domain service publishes to its JetStream event stream when entities change.

• Each service creates its event stream at startup (e.g. ORES_IAM_EVENTS consuming ores.iam.v1.events.*)
• Qt dialogs subscribe to relevant event subjects for live refresh
• Replaces the old subscription_manager / subscription_handler mechanism

Working state: Live entity updates delivered via NATS JetStream pub/sub. Charts can use DeliverByStartTime consumer for history + live in one consumer.