@homaiohq/napi-quickfix 0.1.0 → 0.3.0

package/cpp/message_wrap.cpp

@@ -2,52 +2,42 @@
 
 #include <algorithm>
 #include <string>
+#include <utility>
 
+#include "data_dictionary_wrap.h"
 #include "errors.h"
+#include "field_map_ops.h"
 #include "quickfix/FieldNumbers.h"
 
 namespace napi_quickfix {
 
 Napi::FunctionReference MessageWrap::constructor_;
 
-namespace {
-
-// Coerce a JS arg to a FIX field value string. Accepts string or number
-// (numbers are stringified without trailing ".0"). Throws TypeError otherwise.
-std::string CoerceValue(Napi::Env env, Napi::Value v) {
-  if (v.IsString()) {
-    return v.As<Napi::String>().Utf8Value();
-  }
-  if (v.IsNumber()) {
-    double d = v.As<Napi::Number>().DoubleValue();
-    // Integers -> plain integer string; otherwise a plain double string.
-    if (d == static_cast<double>(static_cast<long long>(d))) {
-      return std::to_string(static_cast<long long>(d));
-    }
-    return std::to_string(d);
-  }
-  throw Napi::TypeError::New(env, "field value must be a string or number");
-}
-
-int CoerceTag(Napi::Env env, Napi::Value v) {
-  if (!v.IsNumber()) {
-    throw Napi::TypeError::New(env, "field tag must be a number");
-  }
-  return v.As<Napi::Number>().Int32Value();
-}
-
-}  // namespace
-
 Napi::Object MessageWrap::Init(Napi::Env env, Napi::Object exports) {
   Napi::Function func = DefineClass(
       env, "Message",
       {
           InstanceMethod("getField", &MessageWrap::GetField),
           InstanceMethod("setField", &MessageWrap::SetField),
+          InstanceMethod("isSetField", &MessageWrap::IsSetField),
+          InstanceMethod("removeField", &MessageWrap::RemoveField),
+          InstanceMethod("getFieldIfSet", &MessageWrap::GetFieldIfSet),
           InstanceMethod("getHeaderField", &MessageWrap::GetHeaderField),
           InstanceMethod("setHeaderField", &MessageWrap::SetHeaderField),
           InstanceMethod("getTrailerField", &MessageWrap::GetTrailerField),
           InstanceMethod("setTrailerField", &MessageWrap::SetTrailerField),
+          InstanceMethod("isEmpty", &MessageWrap::IsEmpty),
+          InstanceMethod("totalFields", &MessageWrap::TotalFields),
+          InstanceMethod("clear", &MessageWrap::Clear),
+          InstanceMethod("fields", &MessageWrap::Fields),
+          InstanceMethod("headerFields", &MessageWrap::HeaderFields),
+          InstanceMethod("trailerFields", &MessageWrap::TrailerFields),
+          InstanceMethod("addGroup", &MessageWrap::AddGroup),
+          InstanceMethod("getGroup", &MessageWrap::GetGroup),
+          InstanceMethod("replaceGroup", &MessageWrap::ReplaceGroup),
+          InstanceMethod("removeGroup", &MessageWrap::RemoveGroup),
+          InstanceMethod("hasGroup", &MessageWrap::HasGroup),
+          InstanceMethod("groupCount", &MessageWrap::GroupCount),
           InstanceMethod("toString", &MessageWrap::ToString),
           InstanceMethod("toPretty", &MessageWrap::ToPretty),
           InstanceMethod("getMsgType", &MessageWrap::GetMsgType),
@@ -60,11 +50,23 @@ Napi::Object MessageWrap::Init(Napi::Env env, Napi::Object exports) {
   return exports;
 }
 
+// Both construct an empty MessageWrap then fill its (empty) FIX::Message. A
+// move keeps the nested entries typed by itself: FieldMap's move assignment
+// takes the entry pointers over.
 Napi::Object MessageWrap::NewInstance(Napi::Env env, const FIX::Message& msg) {
-  // Construct an empty MessageWrap then overwrite its FIX::Message with a copy.
   Napi::Object obj = constructor_.New({});
   MessageWrap* wrap = Napi::ObjectWrap<MessageWrap>::Unwrap(obj);
-  wrap->message_ = msg;
+  fieldmap::CloneMessage(wrap->message_, msg);
+  return obj;
+}
+
+Napi::Object MessageWrap::NewInstance(
+    Napi::Env env, FIX::Message&& msg,
+    std::shared_ptr<const FIX::DataDictionary> sessionDictionary) {
+  Napi::Object obj = constructor_.New({});
+  MessageWrap* wrap = Napi::ObjectWrap<MessageWrap>::Unwrap(obj);
+  wrap->message_ = std::move(msg);
+  wrap->sessionDictionary_ = std::move(sessionDictionary);
   return obj;
 }
 
@@ -87,87 +89,178 @@ MessageWrap::MessageWrap(const Napi::CallbackInfo& info)
   }
   if (!info[0].IsString()) {
     throw Napi::TypeError::New(
-        env, "new Message(raw: string, validate?: boolean)");
+        env,
+        "new Message(raw: string, validate?: boolean, "
+        "sessionDictionary?: DataDictionary, "
+        "applicationDictionary?: DataDictionary)");
   }
   const std::string raw = info[0].As<Napi::String>().Utf8Value();
   bool validate = false;
-  if (info.Length() >= 2 && !info[1].IsUndefined() && !info[1].IsNull()) {
+  if (info.Length() >= 2 && !fieldmap::IsNullish(info[1])) {
     validate = info[1].ToBoolean().Value();
   }
+  const FIX::DataDictionary* sessionDD = nullptr;
+  const FIX::DataDictionary* appDD = nullptr;
+  if (info.Length() >= 3 && !fieldmap::IsNullish(info[2])) {
+    sessionDictionary_ =
+        DataDictionaryWrap::UnwrapArg(env, info[2], "sessionDictionary")
+            ->Shared();
+    sessionDD = sessionDictionary_.get();
+  }
+  if (info.Length() >= 4 && !fieldmap::IsNullish(info[3])) {
+    appDD = &DataDictionaryWrap::UnwrapArg(env, info[3], "applicationDictionary")
+                 ->Dictionary();
+  }
   NQ_TRY(env) {
-    message_.setString(raw, validate);
+    if (sessionDD != nullptr || appDD != nullptr) {
+      // The dictionaries are read only during this call; the wrapper objects
+      // are kept alive by the caller's arguments for its duration.
+      message_.setString(raw, validate, sessionDD, appDD);
+    } else {
+      message_.setString(raw, validate);
+    }
   } NQ_CATCH(env)
 }
 
+namespace {
+
+bool Holds(const FIX::FieldMap& map, int tag) {
+  return map.isSetField(tag) || map.hasGroup(tag);
+}
+
+}  // namespace
+
+// Auto-route standard header/trailer fields (MsgType, SenderCompID, CheckSum,
+// NoHops, ...) and the ones the session dictionary declares to the right
+// section, as the parser does, so callers don't have to know which section a
+// tag belongs to, and a dictionary header field that is removed and set again
+// goes back to the header. Without a dictionary (a message built in JS or
+// parsed without one), any other tag is a body field unless the header or
+// trailer already holds it, so reads find such a field and setField /
+// removeField edit it in place rather than adding a body duplicate. A tag
+// held nowhere stays a body field.
+FIX::FieldMap& MessageWrap::SectionFor(int tag) {
+  const FIX::DataDictionary* dd = sessionDictionary_.get();
+  if (FIX::Message::isHeaderField(tag, dd)) {
+    return message_.getHeader();
+  }
+  if (FIX::Message::isTrailerField(tag, dd)) {
+    return message_.getTrailer();
+  }
+  if (Holds(message_, tag)) {
+    return message_;
+  }
+  if (Holds(message_.getHeader(), tag)) {
+    return message_.getHeader();
+  }
+  if (Holds(message_.getTrailer(), tag)) {
+    return message_.getTrailer();
+  }
+  return message_;
+}
+
+#define NQ_ROUTED [this](int tag) -> FIX::FieldMap& { return SectionFor(tag); }
+#define NQ_HEADER [this](int) -> FIX::FieldMap& { return message_.getHeader(); }
+#define NQ_TRAILER [this](int) -> FIX::FieldMap& { return message_.getTrailer(); }
+
 Napi::Value MessageWrap::GetField(const Napi::CallbackInfo& info) {
-  Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
-  NQ_TRY(env) {
-    // Auto-route standard header/trailer fields (MsgType, SenderCompID,
-    // CheckSum, ...) to the right section so callers don't have to know which
-    // section a well-known tag belongs to. Everything else is a body field.
-    const std::string& value =
-        FIX::Message::isHeaderField(tag)    ? message_.getHeader().getField(tag)
-        : FIX::Message::isTrailerField(tag) ? message_.getTrailer().getField(tag)
-                                            : message_.getField(tag);
-    return Napi::String::New(env, value);
-  } NQ_CATCH(env)
+  return fieldmap::GetField(info, NQ_ROUTED);
 }
 
 Napi::Value MessageWrap::SetField(const Napi::CallbackInfo& info) {
-  Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
-  std::string value = CoerceValue(env, info[1]);
-  NQ_TRY(env) {
-    if (FIX::Message::isHeaderField(tag)) {
-      message_.getHeader().setField(tag, value);
-    } else if (FIX::Message::isTrailerField(tag)) {
-      message_.getTrailer().setField(tag, value);
-    } else {
-      message_.setField(tag, value);
-    }
-  } NQ_CATCH(env)
-  return env.Undefined();
+  return fieldmap::SetField(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::IsSetField(const Napi::CallbackInfo& info) {
+  return fieldmap::IsSetField(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::RemoveField(const Napi::CallbackInfo& info) {
+  return fieldmap::RemoveField(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::GetFieldIfSet(const Napi::CallbackInfo& info) {
+  return fieldmap::GetFieldIfSet(info, NQ_ROUTED);
 }
 
 Napi::Value MessageWrap::GetHeaderField(const Napi::CallbackInfo& info) {
-  Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
-  NQ_TRY(env) {
-    const std::string& value = message_.getHeader().getField(tag);
-    return Napi::String::New(env, value);
-  } NQ_CATCH(env)
+  return fieldmap::GetField(info, NQ_HEADER);
 }
 
 Napi::Value MessageWrap::SetHeaderField(const Napi::CallbackInfo& info) {
-  Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
-  std::string value = CoerceValue(env, info[1]);
-  NQ_TRY(env) {
-    message_.getHeader().setField(tag, value);
-  } NQ_CATCH(env)
-  return env.Undefined();
+  return fieldmap::SetField(info, NQ_HEADER);
 }
 
 Napi::Value MessageWrap::GetTrailerField(const Napi::CallbackInfo& info) {
+  return fieldmap::GetField(info, NQ_TRAILER);
+}
+
+Napi::Value MessageWrap::SetTrailerField(const Napi::CallbackInfo& info) {
+  return fieldmap::SetField(info, NQ_TRAILER);
+}
+
+// Header, body and trailer (FIX::Message::isEmpty, not FieldMap's body-only
+// one), like clear().
+Napi::Value MessageWrap::IsEmpty(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
   NQ_TRY(env) {
-    const std::string& value = message_.getTrailer().getField(tag);
-    return Napi::String::New(env, value);
+    return Napi::Boolean::New(env, message_.isEmpty());
   } NQ_CATCH(env)
 }
 
-Napi::Value MessageWrap::SetTrailerField(const Napi::CallbackInfo& info) {
+Napi::Value MessageWrap::TotalFields(const Napi::CallbackInfo& info) {
+  return fieldmap::TotalFields(info.Env(), message_);
+}
+
+// Empties header, body and trailer.
+Napi::Value MessageWrap::Clear(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
-  int tag = CoerceTag(env, info[0]);
-  std::string value = CoerceValue(env, info[1]);
   NQ_TRY(env) {
-    message_.getTrailer().setField(tag, value);
+    message_.clear();
   } NQ_CATCH(env)
   return env.Undefined();
 }
 
+Napi::Value MessageWrap::Fields(const Napi::CallbackInfo& info) {
+  return fieldmap::Fields(info.Env(), message_);
+}
+
+Napi::Value MessageWrap::HeaderFields(const Napi::CallbackInfo& info) {
+  return fieldmap::Fields(info.Env(), message_.getHeader());
+}
+
+Napi::Value MessageWrap::TrailerFields(const Napi::CallbackInfo& info) {
+  return fieldmap::Fields(info.Env(), message_.getTrailer());
+}
+
+Napi::Value MessageWrap::AddGroup(const Napi::CallbackInfo& info) {
+  return fieldmap::AddGroup(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::GetGroup(const Napi::CallbackInfo& info) {
+  return fieldmap::GetGroup(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::ReplaceGroup(const Napi::CallbackInfo& info) {
+  return fieldmap::ReplaceGroup(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::RemoveGroup(const Napi::CallbackInfo& info) {
+  return fieldmap::RemoveGroup(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::HasGroup(const Napi::CallbackInfo& info) {
+  return fieldmap::HasGroup(info, NQ_ROUTED);
+}
+
+Napi::Value MessageWrap::GroupCount(const Napi::CallbackInfo& info) {
+  return fieldmap::GroupCount(info, NQ_ROUTED);
+}
+
+#undef NQ_ROUTED
+#undef NQ_HEADER
+#undef NQ_TRAILER
+
 Napi::Value MessageWrap::ToString(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   NQ_TRY(env) {

package/cpp/message_wrap.h

@@ -3,6 +3,9 @@
 
 #include <napi.h>
 
+#include <memory>
+
+#include "quickfix/DataDictionary.h"
 #include "quickfix/Message.h"
 
 namespace napi_quickfix {
@@ -10,17 +13,32 @@ namespace napi_quickfix {
 // Napi::ObjectWrap over FIX::Message.
 //
 //   new MessageWrap()
-//   new MessageWrap(raw: string, validate?: boolean = false)
+//   new MessageWrap(raw: string, validate?: boolean = false,
+//                   sessionDictionary?: DataDictionary,
+//                   applicationDictionary?: DataDictionary)
+//
+// With a dictionary the raw string is parsed structurally (repeating groups
+// become nested FieldMaps); without one it is parsed flat, as before.
 //
-// Methods: getField / setField / getHeaderField / setHeaderField /
-// getTrailerField / setTrailerField / toString / toPretty / getMsgType.
+// Field methods (getField / setField / isSetField / removeField /
+// getFieldIfSet) and group methods (addGroup / getGroup / replaceGroup /
+// removeGroup / hasGroup / groupCount) auto-route standard header/trailer
+// tags to the right section, as well as the header/trailer fields declared by
+// the session dictionary the message was parsed or delivered with. Any other
+// tag goes to the section that already holds it (body first). isEmpty and
+// clear() cover all three sections; totalFields / fields read the body.
 class MessageWrap : public Napi::ObjectWrap<MessageWrap> {
  public:
   static Napi::Object Init(Napi::Env env, Napi::Object exports);
 
-  // Build a JS MessageWrap wrapping a COPY of the given FIX::Message. Used by
-  // the ApplicationBridge trampoline to hand messages to JS handlers.
+  // Build a JS MessageWrap holding a copy of `msg` (typed down to the last
+  // nested group entry, see fieldmap::CloneMessage), or taking `msg` over.
+  // The ApplicationBridge trampoline moves its own copy in, with the session
+  // dictionary that routes its fields (null: none).
   static Napi::Object NewInstance(Napi::Env env, const FIX::Message& msg);
+  static Napi::Object NewInstance(
+      Napi::Env env, FIX::Message&& msg,
+      std::shared_ptr<const FIX::DataDictionary> sessionDictionary = nullptr);
 
   explicit MessageWrap(const Napi::CallbackInfo& info);
 
@@ -35,17 +53,41 @@ class MessageWrap : public Napi::ObjectWrap<MessageWrap> {
  private:
   static Napi::FunctionReference constructor_;
 
+  // The section (header / body / trailer) that owns `tag`.
+  FIX::FieldMap& SectionFor(int tag);
+
   Napi::Value GetField(const Napi::CallbackInfo& info);
   Napi::Value SetField(const Napi::CallbackInfo& info);
+  Napi::Value IsSetField(const Napi::CallbackInfo& info);
+  Napi::Value RemoveField(const Napi::CallbackInfo& info);
+  Napi::Value GetFieldIfSet(const Napi::CallbackInfo& info);
   Napi::Value GetHeaderField(const Napi::CallbackInfo& info);
   Napi::Value SetHeaderField(const Napi::CallbackInfo& info);
   Napi::Value GetTrailerField(const Napi::CallbackInfo& info);
   Napi::Value SetTrailerField(const Napi::CallbackInfo& info);
+  Napi::Value IsEmpty(const Napi::CallbackInfo& info);
+  Napi::Value TotalFields(const Napi::CallbackInfo& info);
+  Napi::Value Clear(const Napi::CallbackInfo& info);
+  Napi::Value Fields(const Napi::CallbackInfo& info);
+  Napi::Value HeaderFields(const Napi::CallbackInfo& info);
+  Napi::Value TrailerFields(const Napi::CallbackInfo& info);
+
+  Napi::Value AddGroup(const Napi::CallbackInfo& info);
+  Napi::Value GetGroup(const Napi::CallbackInfo& info);
+  Napi::Value ReplaceGroup(const Napi::CallbackInfo& info);
+  Napi::Value RemoveGroup(const Napi::CallbackInfo& info);
+  Napi::Value HasGroup(const Napi::CallbackInfo& info);
+  Napi::Value GroupCount(const Napi::CallbackInfo& info);
+
   Napi::Value ToString(const Napi::CallbackInfo& info);
   Napi::Value ToPretty(const Napi::CallbackInfo& info);
   Napi::Value GetMsgType(const Napi::CallbackInfo& info);
 
   FIX::Message message_;
+  // The session dictionary whose header/trailer fields SectionFor routes
+  // (null: none). Shared, since the message may outlive the session or the
+  // JS DataDictionary it came from.
+  std::shared_ptr<const FIX::DataDictionary> sessionDictionary_;
 };
 
 }  // namespace napi_quickfix

package/cpp/session_op_gate.h

@@ -0,0 +1,201 @@
+#ifndef NAPI_QUICKFIX_SESSION_OP_GATE_H
+#define NAPI_QUICKFIX_SESSION_OP_GATE_H
+
+#include <condition_variable>
+#include <map>
+#include <memory>
+#include <mutex>
+#include <set>
+#include <utility>
+
+#include "quickfix/SessionID.h"
+
+namespace napi_quickfix {
+
+// Per-engine gate between the libuv-thread session operations
+// (SendToTargetWorker, session_static.cpp) and the destruction of the engine
+// that owns the sessions they operate on.
+//
+// Why: FIX::Session::lookupSession() hands out a raw, non-owning pointer into
+// an engine-owned object, and nothing in QuickFIX keeps that session alive
+// while the caller uses it. The engine wraps destroy their FIX engine (which
+// deletes every FIX::Session) as soon as stop() settles, so without this gate
+// a `sendToTarget()` still running on one libuv thread while `engine.stop()`
+// completes would be a use-after-free.
+//
+// Why per engine (not process-wide): the gate must only ever couple an
+// operation with the engine that owns its session. A process-wide gate made
+// `A.stop()` wait for B's in-flight operations, and -- worse -- made the wrap
+// destructor, which runs on the JS thread at GC, wait for an operation of
+// ANOTHER engine that may itself be blocked in a BlockingCall that only the JS
+// thread can service: a hard deadlock. With one gate per engine, the
+// destructor only waits for operations on its own sessions, and Teardown()
+// has already deactivated this engine's bridge and joined its network threads
+// by then, so none of those can be waiting on the JS thread.
+//
+// Protocol:
+//   * Each engine wrap owns a `std::shared_ptr<SessionOpGate>` and registers
+//     it for its SessionIDs (Register) right after constructing the FIX engine,
+//     on the JS thread; it unregisters (Unregister) right before destroying it.
+//   * The JS-thread entry point of a session operation (SendToTarget) looks
+//     the gate of the engine owning `id` up (Lookup) BEFORE queuing its
+//     worker, so the operation is bound to the engine that owned the session
+//     when it was called: engines register and unregister on the JS thread
+//     only, so that lookup is exact, and an engine registered later for the
+//     same id can never be the one the operation runs on. No registered gate
+//     means no engine owns the session: SessionNotFound, without touching the
+//     registry QuickFIX keeps. The worker then calls Acquire(gate, id) on its
+//     libuv thread to hold an OpScope on that gate for its whole Execute()
+//     -- lookupSession AND the operation. Constructing the OpScope blocks
+//     while that engine is between Freeze() and Unfreeze(); a gate that is no
+//     longer the registered owner once the scope is held is SessionNotFound
+//     too (see below).
+//   * The engine's stop worker calls Freeze() on its libuv thread AFTER the FIX
+//     engine's own stop() has returned: it blocks new operations on this
+//     engine's sessions and waits for the in-flight ones to drain. The wrap
+//     then unregisters and destroys the engine on the JS thread (OnOK) and
+//     calls Unfreeze() -- or, if the engine survives (the stop threw, or the
+//     environment is torn down before a graceful stop's queued destruction
+//     runs), calls Unfreeze() alone so that operations parked meanwhile are
+//     woken rather than left pinning a libuv thread. Because Freeze() waits
+//     on a libuv thread while the JS loop is free, an in-flight operation
+//     blocked in a BlockingCall to JS (sendToTarget() -> toApp) can still
+//     complete.
+//   * The wrap destructor calls Freeze() on the JS thread, but only after
+//     Teardown() has deactivated the bridge (waking every pending BlockingCall
+//     and making later callbacks pass through) and joined the network threads,
+//     so no in-flight operation on THIS engine's sessions can be waiting on the
+//     (now blocked) JS thread. Operations on other engines are not involved.
+//
+// The gate outlives its engine: a worker whose gate was resolved just before
+// the engine was unregistered holds it by shared_ptr and passes the (now
+// lifted) freeze. By then a NEW engine may own the same id -- its sessions are what
+// lookupSession() would now return -- while the worker holds the OLD gate, on
+// which the new engine's stop() never waits. Acquire() closes that window by
+// re-reading the registry after the OpScope is held: the scope is kept only if
+// the gate is still the registered owner, and that owner cannot be destroyed
+// while the scope is in flight (Freeze() precedes Unregister() everywhere).
+// Otherwise the operation is reported as SessionNotFound, never retried
+// against the new owner: it was queued for the engine that is now gone, and a
+// message delivered through another engine's session -- not logged on, so
+// persisted in its store and sent on its first logon -- is exactly the
+// cross-over SessionWrap::Resolve() refuses for Session handles. Together
+// with the wraps rejecting a SessionID that is already live in the process,
+// this makes gate == registered owner == the engine whose session
+// lookupSession() returns.
+class SessionOpGate {
+ public:
+  class OpScope {
+   public:
+    explicit OpScope(std::shared_ptr<SessionOpGate> gate)
+        : gate_(std::move(gate)) {
+      std::unique_lock<std::mutex> lock(gate_->mtx_);
+      gate_->cv_.wait(lock, [this] { return gate_->frozen_ == 0; });
+      ++gate_->inflight_;
+    }
+    ~OpScope() {
+      {
+        std::lock_guard<std::mutex> lock(gate_->mtx_);
+        --gate_->inflight_;
+      }
+      gate_->cv_.notify_all();
+    }
+    OpScope(const OpScope&) = delete;
+    OpScope& operator=(const OpScope&) = delete;
+
+   private:
+    std::shared_ptr<SessionOpGate> gate_;
+  };
+
+  SessionOpGate() = default;
+  SessionOpGate(const SessionOpGate&) = delete;
+  SessionOpGate& operator=(const SessionOpGate&) = delete;
+
+  // Block new operations on this engine's sessions and wait for the in-flight
+  // ones to finish. Nests: the stop worker freezes on its thread and the wrap
+  // unfreezes later on the JS thread, and in between the destructor (if the
+  // wrap is finalized during environment teardown) freezes again around its
+  // own DestroyEngine().
+  void Freeze() {
+    std::unique_lock<std::mutex> lock(mtx_);
+    ++frozen_;
+    cv_.wait(lock, [this] { return inflight_ == 0; });
+  }
+
+  // Let operations run again. Pairs with Freeze().
+  void Unfreeze() {
+    {
+      std::lock_guard<std::mutex> lock(mtx_);
+      --frozen_;
+    }
+    cv_.notify_all();
+  }
+
+  // --- registry: SessionID -> owning engine's gate ---------------------------
+  // Each id maps to at most one gate at a time: the engine wraps refuse to
+  // construct an engine whose SessionID is already live in the process
+  // (ConfigError "Duplicate Session"). QuickFIX itself does NOT enforce that --
+  // its Session constructor ignores addSession()'s result, so a second engine
+  // would silently shadow the first in the process-wide session registry.
+
+  static void Register(const std::set<FIX::SessionID>& ids,
+                       const std::shared_ptr<SessionOpGate>& gate) {
+    Registry& r = GetRegistry();
+    std::lock_guard<std::mutex> lock(r.mtx);
+    for (const FIX::SessionID& id : ids) r.gates[id] = gate;
+  }
+
+  // Remove `ids` only where they still point at `gate`: a new engine may
+  // already have registered the same ids after this one unregistered them.
+  static void Unregister(const std::set<FIX::SessionID>& ids,
+                         const SessionOpGate* gate) {
+    Registry& r = GetRegistry();
+    std::lock_guard<std::mutex> lock(r.mtx);
+    for (const FIX::SessionID& id : ids) {
+      auto it = r.gates.find(id);
+      if (it != r.gates.end() && it->second.get() == gate) r.gates.erase(it);
+    }
+  }
+
+  // The gate of the engine owning `id`, or nullptr if no engine does.
+  static std::shared_ptr<SessionOpGate> Lookup(const FIX::SessionID& id) {
+    Registry& r = GetRegistry();
+    std::lock_guard<std::mutex> lock(r.mtx);
+    auto it = r.gates.find(id);
+    return it == r.gates.end() ? nullptr : it->second;
+  }
+
+  // Hold an OpScope on `gate` -- the registered owner of `id` when the
+  // caller looked it up on the JS thread -- or return nullptr if it no longer
+  // is (-> SessionNotFound). Constructing the scope may block (the owner is
+  // stopping); once it is held the registry is re-read, and the scope is kept
+  // only if the same gate is still registered. Otherwise the owner was
+  // destroyed while we waited -- possibly replaced by a new engine with the
+  // same id -- and the operation is refused (nullptr) rather than run against
+  // the new owner, mirroring SessionWrap::Resolve().
+  static std::unique_ptr<OpScope> Acquire(
+      const std::shared_ptr<SessionOpGate>& gate, const FIX::SessionID& id) {
+    auto scope = std::make_unique<OpScope>(gate);
+    if (Lookup(id) != gate) return nullptr;
+    return scope;
+  }
+
+ private:
+  struct Registry {
+    std::mutex mtx;
+    std::map<FIX::SessionID, std::shared_ptr<SessionOpGate>> gates;
+  };
+  static Registry& GetRegistry() {
+    static Registry registry;
+    return registry;
+  }
+
+  std::mutex mtx_;
+  std::condition_variable cv_;
+  int inflight_ = 0;
+  int frozen_ = 0;
+};
+
+}  // namespace napi_quickfix
+
+#endif  // NAPI_QUICKFIX_SESSION_OP_GATE_H