feat: differentiate driver events from Firebird POST_EVENT API, fix EventConnection race, add debug API, ASCII diagrams, FIREBIRD_DEBUG trace logging, offline SRP auth protocol tests, and SRP protocol documentation

.github/workflows/node.js.yml

@@ -7,6 +7,7 @@ jobs:
     runs-on: ubuntu-latest
 
     strategy:
+      fail-fast: false
       matrix:        
         node: [20, 22, 24]
         firebird: [3, 4, 5]
@@ -72,6 +73,7 @@ jobs:
     - name: Test (Linux)      
       run: |
         export FIREBIRD_DATA=/firebird/data
+        export FIREBIRD_DEBUG=1
         npm test
 
     - name: Show Firebird log on failure

README.md

@@ -377,43 +377,95 @@ Firebird.attach(options, function (err, db) {
 });
 ```
 
-### Events
+### Driver Events
+
+Driver events are synchronous notifications emitted on the `Database` object for connection-level operations. Subscribe with `db.on(eventName, handler)`.
 
 ```js
 Firebird.attach(options, function (err, db) {
   if (err) throw err;
 
-  db.on('row', function (row, index, isObject) {
-    // index === Number
-    // isObject === is row object or array?
+  db.on('attach', function () {
+    // fired once the database is attached
+  });
+
+  db.on('detach', function (isPoolConnection) {
+    // isPoolConnection === Boolean
   });
 
-  db.on('result', function (result) {
-    // result === Array
+  db.on('reconnect', function () {
+    // fired after the driver reconnects a dropped socket
   });
 
-  db.on('attach', function () {});
+  db.on('error', function (err) {
+    // connection-level errors (socket errors, closed connection, etc.)
+  });
 
-  db.on('detach', function (isPoolConnection) {
-    // isPoolConnection == Boolean
+  db.on('transaction', function (options) {
+    // fired when a transaction is started (before server response)
+    // options === resolved transaction options object
   });
 
-  db.on('reconnect', function () {});
+  db.on('commit', function () {
+    // fired when a transaction commit is sent
+  });
 
-  db.on('error', function (err) {});
+  db.on('rollback', function () {
+    // fired when a transaction rollback is sent
+  });
 
-  db.on('transaction', function (isolation) {
-    // isolation === Number
+  db.on('query', function (sql) {
+    // fired with the SQL string when a statement is prepared
   });
 
-  db.on('commit', function () {});
+  db.on('row', function (row, index, isObject) {
+    // fired for each row decoded during a fetch
+    // index === Number, isObject === Boolean
+  });
 
-  db.on('rollback', function () {});
+  db.on('result', function (rows) {
+    // fired with the full rows array once all rows are fetched
+    // rows === Array
+  });
 
   db.detach();
 });
 ```
 
+### Firebird Database Events (POST_EVENT)
+
+Firebird database events are **asynchronous** notifications triggered by `POST_EVENT` inside PSQL triggers or stored procedures. They travel over a separate aux connection and are handled through `FbEventManager`.
+
+> **Note:** Full POST_EVENT reception is not yet implemented. `attachEvent` and `registerEvent` are available, but actual event delivery requires completing the `op_que_events`/`op_event` wire-protocol implementation.
+
+```js
+Firebird.attach(options, function (err, db) {
+  if (err) throw err;
+
+  // 1. Open the aux event connection and get a FbEventManager
+  db.attachEvent(function (err, evtmgr) {
+    if (err) throw err;
+
+    // 2. Subscribe to one or more named events
+    evtmgr.registerEvent(['MY_EVENT'], function (err) {
+      if (err) throw err;
+
+      // 3. Listen for POST_EVENT notifications
+      evtmgr.on('post_event', function (name, count) {
+        // name  === event name string (e.g. 'MY_EVENT')
+        // count === cumulative trigger count since last notification
+      });
+    });
+
+    // 4. Unsubscribe from events when no longer needed
+    // evtmgr.unregisterEvent(['MY_EVENT'], function (err) { ... });
+
+    // 5. Release the aux connection when done
+    // evtmgr.close(function (err) { ... });
+  });
+});
+```
+
 ### Escaping Query values
 
 ```js