mqtt-plus 1.4.25 → 1.4.27

package/.ase/config.yaml

@@ -0,0 +1 @@
+null

package/.ase/service.log

@@ -10433,3 +10433,37 @@ ase: [2026-07-11 12:45:57.471]: [INFO]: mcp: POST /mcp [initialize]
 ase: [2026-07-11 12:45:57.487]: [INFO]: mcp: POST /mcp [tools/list]
 ase: [2026-07-11 12:45:57.494]: [INFO]: mcp: POST /mcp [notifications/initialized]
 ase: [2026-07-11 12:45:57.499]: [INFO]: mcp: GET /mcp
+ase: [2026-07-11 13:19:57.333]: [INFO]: service: idle timeout reached, stopping
+ase: [2026-08-04 08:46:25.126]: [INFO]: service: listening on port 42029
+ase: [2026-08-04 08:47:07.892]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-lint","spec":"--help|-h --auto|-a --severity|-S=(LOW|MEDIUM|HIGH) --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20)... --exclude|-e=…
+ase: [2026-08-04 08:47:20.549]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-analyze","spec":"--help|-h --performance|-p --security|-s --severity|-S=(LOW|MEDIUM|HIGH) --prefix|-P=","args":"-S MEDIUM @src"}
+ase: [2026-08-04 08:49:58.001]: [INFO]: mcp: POST /mcp [tools/call] ase_config_set {"key":"agent.skill","val":"ase-docs-proofread","scope":"session:c4b8a1d3-1262-4f52-a20b-5e3caf67f11b"}
+ase: [2026-08-04 08:55:13.606]: [INFO]: mcp: POST /mcp [tools/call] ase_config_set {"key":"agent.skill","val":"ase-code-lint","scope":"session:991dfac7-3ec1-45df-b605-b85076f1133f"}
+ase: [2026-08-04 08:59:33.029]: [INFO]: mcp: POST /mcp [tools/call] ase_kv_batch {"transactional":true,"commands":[{"command":"clear","prefix":"ase-issue-"},{"command":"set","key":"ase-issue-P1","val":"Abort destroys the caller's un-consumed `data` stream with an error, causing an…
+ase: [2026-08-04 09:34:45.196]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-docs-proofread","spec":"--help|-h --auto|-a","args":"-a @."}
+ase: [2026-08-04 09:36:55.088]: [INFO]: mcp: POST /mcp [tools/call] ase_config_set {"key":"agent.skill","val":"ase-docs-proofread","scope":"session:b97f5e3e-1ebd-424b-836f-c36be1120f90"}
+ase: [2026-08-04 09:37:42.361]: [INFO]: mcp: POST /mcp [tools/call] ase_config_delete {"key":"agent.skill","scope":"session:b97f5e3e-1ebd-424b-836f-c36be1120f90"}
+ase: [2026-08-06 16:50:29.391]: [INFO]: service: idle timeout reached, stopping
+ase: [2026-08-06 18:58:21.557]: [INFO]: service: listening on port 43270
+ase: [2026-08-06 18:58:38.339]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D P1"}
+ase: [2026-08-06 18:58:56.412]: [INFO]: mcp: POST /mcp [tools/call] ase_kv_get {"key":"ase-issue-P1"}
+ase: [2026-08-06 18:59:39.600]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: HIGH): P1: Abort destroys …
+ase: [2026-08-06 18:59:58.741]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"stream-abort","session":"0e6fbbe6-4403-4b63-a1ec-9d993421b5a3"}
+ase: [2026-08-06 19:00:12.928]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: MEDIUM): P3: WithInfo appe…
+ase: [2026-08-06 19:00:13.609]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: MEDIUM): P2: Sync-throwing…
+ase: [2026-08-06 19:00:19.055]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: MEDIUM): P4: Abort destroy…
+ase: [2026-08-06 19:00:29.204]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"sync-throw","session":"6a89a55a-84c0-4a5f-9724-368cc7b50b3f"}
+ase: [2026-08-06 19:00:29.627]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: MEDIUM): P5: MIN_VERSION c…
+ase: [2026-08-06 19:00:30.442]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"info-positional","session":"8a3e2d56-af15-48dd-8026-b6d41ee9a33a"}
+ase: [2026-08-06 19:00:53.301]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"version-compat","session":"8369a65d-3b10-4294-8870-4327cc269b79"}
+ase: [2026-08-06 19:00:55.371]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: ACCEPTED): P6: Receiver mi…
+ase: [2026-08-06 19:00:56.036]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"stream-abort","session":"56995021-07c8-4b45-8916-4ab8a78d0a8b"}
+ase: [2026-08-06 19:01:07.667]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"receiver-mismatch","session":"9eb01878-9acf-43dd-9554-00066ecc7300"}
+ase: [2026-08-06 19:01:16.395]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: ACCEPTED): P7: runSettle()…
+ase: [2026-08-06 19:01:20.616]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: ACCEPTED): P8: Fire-and-fo…
+ase: [2026-08-06 19:01:34.810]: [INFO]: mcp: POST /mcp [tools/call] ase_getopt {"name":"ase-code-resolve","spec":"--help|-h --auto|-a --dry|-d --direct|-D --quick|-Q --next|-n=(none|DONE|EDIT|GRILL|PREFLIGHT|IMPLEMENT)...","args":"-D PROBLEM (Severity: ACCEPTED): P9: Enumerating…
+ase: [2026-08-06 19:01:34.828]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"spool-unroll","session":"3ae9d8dc-2ca4-400f-bd32-633859ec1f8a"}
+ase: [2026-08-06 19:01:36.333]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"onfinally-error","session":"e164c52c-d0df-4cc7-a9bc-972012577cec"}
+ase: [2026-08-06 19:01:47.858]: [INFO]: mcp: POST /mcp [tools/call] ase_task_id {"id":"exclusive-fields","session":"7bcafa3d-0cb1-4c2b-8fdb-17e7a84dc176"}
+ase: [2026-08-06 19:23:19.610]: [INFO]: mcp: POST /mcp [tools/call] ase_timestamp {"format":"yyyy-LL-dd"}
+ase: [2026-08-06 19:47:45.209]: [INFO]: mcp: POST /mcp [tools/call] ase_artifact_list {"kind":["spec","arch","code","docs","infr","othr"]}

package/.ase/service.yaml

@@ -1 +1 @@
-port: 42424
+port: 43270

package/.ase/task/TASK-P18.md

@@ -12,7 +12,7 @@
 
 -   **WHY**: When publishing the push request fails (`src/mqtt-plus-sink.ts:795-796`), the `catch`
     block aborts (`src/mqtt-plus-sink.ts:866`) and `onAbort` (`src/mqtt-plus-sink.ts:773-783`) calls
-    `pushInitialReject(error)` before `await pushInitial` (`src/mqtt-plus-sink.ts:797`) ever attached
+    `pushInitialReject(error)` before `await pushInitial` (`src/mqtt-plus-sink.ts:797`) ever attaches
     a handler — an *unhandled promise rejection*, fatal by default in Node.js ≥ 15. The same hazard
     exists for early rejections from the response/credit handlers while the publish is still pending.
 

package/.ase/task/TASK-P21.md

@@ -11,7 +11,7 @@
 
 -   **WHY**: `destroy()` cannot reach the fetcher-side closure state (`src/mqtt-plus-source.ts:457`),
     so pending `fetch()` consumers hang forever on `stream`/`buffer`/`meta` (the timeout timer is
-    cleared and neutralized, the `onResponse` handlers are dropped); aborting settles all three with
+    cleared and neutralized and the `onResponse` handlers are dropped); aborting settles all three with
     *"instance destroyed"*, analogous to the service-caller `pendingCalls` pattern
     (`src/mqtt-plus-service.ts:51-54`).
 

package/.claude/settings.local.json

@@ -1,7 +1,10 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npx tsx *)"
+      "Bash(npx tsx *)",
+      "Bash(npm start *)",
+      "Bash(echo \"EXIT=$?\")",
+      "Read(//tmp/claude-10000/-Users-rse-Work-node-mqtt-plus/6a89a55a-84c0-4a5f-9724-368cc7b50b3f/scratchpad/**)"
     ]
   }
 }

package/AGENTS.md

@@ -50,7 +50,7 @@ Configuration lives in `etc/`: `tsc.json`, `vite.mts`, `eslint.mts`,
 `knip.jsonc`, `stx.conf`, `d2.mts`, `d2.theme.d2`, `logo.ai`,
 `logo.svg`.
 
-Tests require an MQTT broker under run-time; the test suite starts/stops
+Tests require an MQTT broker at run-time; the test suite starts/stops
 one automatically. If Docker is available, a Mosquitto broker is used;
 otherwise, the Aedes in-process broker serves as the fallback.
 For regression testing always use the all-in-one command `npm start build test`.

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 ChangeLog
 =========
 
+1.4.27 (2026-08-05)
+-------------------
+
+- BUGFIX [code]: expose the version information as static members of the MQTTp class instead of re-exporting the "mqtt-plus-version" module
+
+1.4.26 (2026-08-06)
+-------------------
+
+- IMPROVEMENT [code]: sanity check the numeric option ranges of "timeout", "chunkSize" and "chunkCredit" at construction time and guard the chunk sending helpers against an invalid chunk size
+- IMPROVEMENT [infr]: upgrade the NPM patch generation procedure to use "npm install --package-lock-only" instead of "npm shrinkwrap"
+- BUGFIX [code, othr]: guard the handler-supplied source fetch stream and the caller-supplied sink push stream with a no-op "error" listener before destroying them on abort, as an abort before the chunk sending phase (field validation, nak, early cancel, ack timeout) otherwise raised an unhandled "error" event and crashed the process
+- BUGFIX [code, docs]: drop instead of just warn about a message received on a direct topic whose "receiver" field does not match the peer id of the topic, as such a mislabeled message is addressed to a foreign peer and was still dispatched to the response handlers
+- BUGFIX [code, othr]: settle the epilog of run() adaptively when the action throws synchronously, as an asynchronous onfinally, oncleanup or spool cleanup was previously mistaken for a non-async context and replaced the original error
+- BUGFIX [code, othr]: attach a failing onfinally callback of run() as a "suppressed" error to the propagated pending error instead of discarding it entirely
+- BUGFIX [code, othr]: align received parameters to the handler arity in the event/service/source/sink traits, as an endpoint with trailing optional parameters otherwise shifted the trailing "info" argument into a data parameter slot
+- BUGFIX [code, othr]: define the mutually exclusive "stream"/"buffer" fields as non-enumerable and assignable, as a mere object spread, Object.values() or JSON.stringify() otherwise consumed one field and then threw on the other
+- BUGFIX [code]: surface the cleanup failures of the fire-and-forget spool unrolling in the service call settle path as "error" events, as they were previously silently suppressed
+- BUGFIX [code]: re-export the "mqtt-plus-version" module with "export *" instead of "export type *", as its version utility is a run-time value and was stripped from the public API
+- BUGFIX [code]: settle the sink push race window with setTimeout() instead of setImmediate(), as setImmediate() is unavailable in browser environments
+- UPDATE [infr, othr]: upgrade NPM dependencies
+- CLEANUP [code]: prefix the private members of BaseTrait with an underscore
+- CLEANUP [docs, infr, othr]: fix spelling in the documentation
+- REFACTOR [code]: factor out the repeated push abort and settle logic in the sink trait into a "failPush" helper
+
 1.4.25 (2026-07-11)
 -------------------
 
@@ -79,12 +103,12 @@ ChangeLog
 - IMPROVEMENT: bump minimum Node version to 20 for ES2022
 - BUGFIX: Spool.unroll() silently skipped remaining cleanups on first async failure
 - BUGFIX: improve semantics of info.authenticated field for event/service/sink/source in case of optional authentication
-- BUGFIX: in the ReadableTee class, do not run read() twice: once ourself and once via the base class
+- BUGFIX: in the ReadableTee class, do not run read() twice: once ourselves and once via the base class
 - BUGFIX: correctly propagate description in run() also to finally callback
 - BUGFIX: fix resource handling in source trait
 - BUGFIX: avoid race conditions and unhandled promise rejections in async processing
 - BUGFIX: fix cleanup and error handling across sink/source traits
-- BUGFIX: fix Mosqitto ACL
+- BUGFIX: fix Mosquitto ACL
 - UPDATE: upgrade NPM dependencies
 - CLEANUP: various code cleanups (callback handling, settle code, destroy handling, termination, subscriptions)
 - CLEANUP: align with ensureError code and fix typos
@@ -286,14 +310,14 @@ ChangeLog
 - CLEANUP: simplify typing and remove unused code
 - CLEANUP: rename variables and align code formatting
 - CLEANUP: various code cleanups
-- CLEANUP: splitted documentation from README.md into doc/*.md
+- CLEANUP: split documentation from README.md into doc/*.md
 - UPDATE: upgrade NPM dependencies
 
 1.3.0 (2026-02-07)
 ------------------
 
 - IMPROVEMENT: add credit-based flow control to sink/source facility
-- IMPROVEMENT: make "buffer" and "stream" fields always mutual-exlusive
+- IMPROVEMENT: make "buffer" and "stream" fields always mutually exclusive
 - IMPROVEMENT: provide version field in protocol messages
 
 1.2.1 (2026-02-07)
@@ -368,7 +392,7 @@ ChangeLog
 0.9.17 (2026-01-25)
 -------------------
 
-- IMPROVEMENT: add Dry-Run mode will null MQTT client
+- IMPROVEMENT: add Dry-Run mode with null MQTT client
 - IMPROVEMENT: add Dry-Run mode for emit() to generate last-will message
 
 0.9.16 (2026-01-24)

package/README.md

@@ -55,7 +55,7 @@ The following is a simple but self-contained example usage of
 and an MQTT infrastructure. It can be found in the file
 [sample.ts](sample/sample.ts) and can be executed from the **MQTT+**
 source tree via `npm start sample` (assuming the prerequisite *Docker* is
-available for the underlying *Mosquitto* broker based infrastructure):
+available for the underlying *Mosquitto* broker-based infrastructure):
 
 ```ts
 import { Readable }                          from "node:stream"
@@ -175,7 +175,7 @@ Notice
 ------
 
 > [!Note]
-> **MQTT+** and its peer dependency **MQTT.js** provide a powerful
+> **MQTT+** and its peer dependency **MQTT.js** provide powerful
 > functionality, but are not small in size. **MQTT+** is 4,000 LoC
 > and 75 KB in size (ESM and CJS format). When bundled with all its
 > dependencies, it is 220 KB in size (UMD format). Its peer dependency

package/doc/mqtt-plus-broker-setup.md

@@ -5,7 +5,7 @@ MQTT+ Broker Setup
 **MQTT+** can be used with an arbitrary MQTT broker. One popular
 MQTT broker is [Mosquitto](https://mosquitto.org/).
 For establishing your own permanent MQTT environment, you can install the
-[Mosquitto](https://mosquitto.org/) MQTT broker yourself and a setup
+[Mosquitto](https://mosquitto.org/) MQTT broker yourself and set up
 a `mosquitto.conf` file like...
 
 ```

package/doc/mqtt-plus-comm.md

@@ -13,7 +13,7 @@ case of a directed event emission) or *all* receivers are called and
 receive the parameters as extra information.
 
 > In contrast to the regular MQTT message publish/subscribe, this
-> pattern allows to direct the event to particular receivers,
+> pattern allows directing the event to particular receivers,
 > provides optional information about the sender and receiver to
 > receivers, supports authentication and meta-data, etc.
 
@@ -48,7 +48,7 @@ sink push) or *one* arbitrary sink is called and receives the data
 chunks as a stream with arguments.
 
 > In contrast to the regular MQTT message publish/subscribe, this
-> pattern allows to transfer arbitrary amounts of arbitrary data by
+> pattern allows transferring arbitrary amounts of arbitrary data by
 > chunking the data via a stream. Additionally, it supports authentication
 > and meta-data, provides an `AbortSignal` to the sink handler for
 > cooperative cancellation, and allows the receiver to cancel an
@@ -67,7 +67,7 @@ directed source fetch) or *one* arbitrary source is called and sends the
 data chunks as a stream with arguments.
 
 > In contrast to the regular MQTT message publish/subscribe, this
-> pattern allows to transfer arbitrary amounts of arbitrary data by
+> pattern allows transferring arbitrary amounts of arbitrary data by
 > chunking the data via a stream. Additionally, it supports
 > authentication and meta-data, and provides an `AbortSignal` to the
 > source handler for cooperative cancellation, etc.

package/doc/mqtt-plus-internals.md

@@ -328,6 +328,12 @@ the configured credential and required roles:
 Message Dispatching
 -------------------
 
+### Receiver Validation
+
+A message received on a direct topic (i.e. a topic carrying a concrete
+peer id instead of `any`) is dropped if its `receiver` field does not
+match that peer id, as it is addressed to a foreign peer.
+
 ### Request Dispatching
 
 Incoming request messages are dispatched based on the combination of

package/dst-stage1/mqtt-plus-base.d.ts

@@ -4,8 +4,8 @@ import type { APIOptions } from "./mqtt-plus-options";
 import { TraceTrait } from "./mqtt-plus-trace";
 import { Spool } from "./mqtt-plus-error";
 export declare class BaseTrait<T extends APISchema = APISchema> extends TraceTrait<T> {
-    private mqtt;
-    private messageHandler;
+    private _mqtt;
+    private _messageHandler;
     protected destroyed: boolean;
     protected onRequest: Map<string, (message: any, topicName: string) => void | Promise<void>>;
     protected onResponse: Map<string, (message: any, topicName: string) => void | Promise<void>>;

package/dst-stage1/mqtt-plus-base.js

@@ -55,7 +55,7 @@ export class BaseTrait extends TraceTrait {
             });
         }
         /*  store MQTT client  */
-        this.mqtt = mqtt;
+        this._mqtt = mqtt;
         /*  resolve the instance "id": if the user did not provide an
             explicit one, fetch the "clientId" from the underlying MQTT
             client, and only as a last resort fall back to a generated id
@@ -70,7 +70,7 @@ export class BaseTrait extends TraceTrait {
         }
         /*  hook into the MQTT message processing  */
         this.log("info", "hooking into MQTT client");
-        this.messageHandler = (topic, message, packet) => {
+        this._messageHandler = (topic, message, packet) => {
             if (this.destroyed)
                 return;
             /*  convert message to codec-specific input format
@@ -90,13 +90,13 @@ export class BaseTrait extends TraceTrait {
             }
             this._onMessage(topic, input, packet);
         };
-        this.mqtt.on("message", this.messageHandler);
+        this._mqtt.on("message", this._messageHandler);
     }
     /*  destroy API class  */
     async destroy() {
         this.destroyed = true;
         this.log("info", "un-hooking from MQTT client");
-        this.mqtt.off("message", this.messageHandler);
+        this._mqtt.off("message", this._messageHandler);
         this.onRequest.clear();
         this.onResponse.clear();
     }
@@ -120,7 +120,7 @@ export class BaseTrait extends TraceTrait {
     async subscribeTopic(topic, options = {}) {
         this.log("info", `subscribing to MQTT topic "${topic}"`);
         return new Promise((resolve, reject) => {
-            this.mqtt.subscribe(topic, { qos: 2, ...options }, (err, granted) => {
+            this._mqtt.subscribe(topic, { qos: 2, ...options }, (err, granted) => {
                 if (err) {
                     this.error(err, `subscribing to MQTT topic "${topic}" failed`);
                     reject(err);
@@ -142,7 +142,7 @@ export class BaseTrait extends TraceTrait {
     async unsubscribeTopic(topic) {
         this.log("info", `unsubscribing from MQTT topic "${topic}"`);
         return new Promise((resolve, reject) => {
-            this.mqtt.unsubscribe(topic, (err, _packet) => {
+            this._mqtt.unsubscribe(topic, (err, _packet) => {
                 if (err) {
                     this.error(err, `unsubscribing from MQTT topic "${topic}" failed`);
                     reject(err);
@@ -178,7 +178,7 @@ export class BaseTrait extends TraceTrait {
             const messageData = typeof message === "string"
                 ? message
                 : Buffer.from(message.buffer, message.byteOffset, message.byteLength);
-            this.mqtt.publish(topic, messageData, options, (err) => {
+            this._mqtt.publish(topic, messageData, options, (err) => {
                 if (err) {
                     this.error(err, `publishing to MQTT topic "${topic}" failed`);
                     reject(err);
@@ -226,12 +226,15 @@ export class BaseTrait extends TraceTrait {
             return;
         }
         this.log("debug", `received from MQTT topic "${topic}"`, { message });
-        /*  warn on receiver mismatch on direct topics  */
+        /*  drop message on receiver mismatch on direct topics, as it is
+            addressed to a foreign peer and hence must not be processed here  */
         if (topicMatch.peerId !== undefined
             && message.receiver !== undefined
-            && message.receiver !== topicMatch.peerId)
-            this.log("warning", `receiver mismatch on direct topic "${topic}"` +
+            && message.receiver !== topicMatch.peerId) {
+            this.log("warning", `receiver mismatch -- dropped message from direct topic "${topic}"` +
                 ` (expected "${topicMatch.peerId}", got "${message.receiver}")`);
+            return;
+        }
         /*  dispatch MQTT+ message  */
         if (this.msg.isRequest(message)) {
             /*  dispatch request message  */

package/dst-stage1/mqtt-plus-error.js

@@ -188,10 +188,14 @@ function runSettle(isAsync, pending, spool, onfinally, description) {
         catch (arg) {
             failure = ensureError(arg, description);
         }
-        if (pending || failure !== undefined) {
+        if (pending !== undefined || failure !== undefined) {
             runUnroll(false, spool);
-            if (!pending && failure !== undefined)
-                throw failure;
+            if (failure !== undefined) {
+                if (pending !== undefined)
+                    pending.suppressed = failure;
+                else
+                    throw failure;
+            }
         }
     }
     else {
@@ -203,14 +207,39 @@ function runSettle(isAsync, pending, spool, onfinally, description) {
             catch (arg) {
                 failure = ensureError(arg, description);
             }
-            if (pending || failure !== undefined) {
+            if (pending !== undefined || failure !== undefined) {
                 await runUnroll(true, spool);
-                if (!pending && failure !== undefined)
-                    throw failure;
+                if (failure !== undefined) {
+                    if (pending !== undefined)
+                        pending.suppressed = failure;
+                    else
+                        throw failure;
+                }
             }
         })();
     }
 }
+/*  helper function for settling the epilog of "run" and then failing with
+    a pending error in a still unknown synchronous/asynchronous context:
+    operate synchronously as long as possible and continue asynchronously as
+    soon as a callback returns a Promise. As the pending error always takes
+    precedence, a failing finally code is attached to it as a suppressed error.  */
+function runFail(error, spool, onfinally, description) {
+    const attach = (arg) => { error.suppressed = ensureError(arg, description); };
+    let result = undefined;
+    try {
+        result = onfinally?.();
+    }
+    catch (arg) {
+        attach(arg);
+    }
+    if (result instanceof Promise)
+        return result.catch(attach).then(() => spool?.unroll()).then(() => { throw error; });
+    const unrolled = spool?.unroll();
+    if (unrolled instanceof Promise)
+        return unrolled.then(() => { throw error; });
+    throw error;
+}
 export function run(...args) {
     /*  support overloaded signatures  */
     let description;
@@ -267,31 +296,28 @@ export function run(...args) {
         result = action();
     }
     catch (arg) {
-        /*  synchronous case (error branch)  */
-        let error = ensureError(arg, description);
-        if (oncatch) {
-            try {
-                result = oncatch(error);
-            }
-            catch (arg) {
-                error = ensureError(arg, description);
-                runSettle(false, true, spool, onfinally, description);
-                throw error;
-            }
-            if (spool && oncleanup)
-                spool.roll(result, oncleanup);
-            runSettle(false, false, spool, onfinally, description);
-            return result;
+        /*  synchronous case (error branch): as the action failed before
+            returning its potentially asynchronous result, the context is
+            still unknown here and hence has to be probed  */
+        const error = ensureError(arg, description);
+        if (!oncatch)
+            return runFail(error, spool, onfinally, description);
+        try {
+            result = oncatch(error);
+        }
+        catch (arg) {
+            return runFail(ensureError(arg, description), spool, onfinally, description);
         }
-        runSettle(false, true, spool, onfinally, description);
-        throw error;
+        /*  the recovery already ran, so let the common epilog below settle
+            its potentially asynchronous result without re-entering it  */
+        oncatch = undefined;
     }
     if (result instanceof Promise) {
         /*  asynchronous case (result or error branch)  */
         return result.then(async (result) => {
             if (spool && oncleanup)
                 spool.roll(result, oncleanup);
-            await runSettle(true, false, spool, onfinally, description);
+            await runSettle(true, undefined, spool, onfinally, description);
             return result;
         }, async (arg) => {
             /*  asynchronous case (error branch)  */
@@ -303,15 +329,15 @@ export function run(...args) {
                 }
                 catch (arg) {
                     error = ensureError(arg, description);
-                    await runSettle(true, true, spool, onfinally, description);
+                    await runSettle(true, error, spool, onfinally, description);
                     throw error;
                 }
                 if (spool && oncleanup)
                     spool.roll(result, oncleanup);
-                await runSettle(true, false, spool, onfinally, description);
+                await runSettle(true, undefined, spool, onfinally, description);
                 return result;
             }
-            await runSettle(true, true, spool, onfinally, description);
+            await runSettle(true, error, spool, onfinally, description);
             throw error;
         });
     }
@@ -319,7 +345,7 @@ export function run(...args) {
         /*  synchronous case (result branch)  */
         if (spool && oncleanup)
             spool.roll(result, oncleanup);
-        runSettle(false, false, spool, onfinally, description);
+        runSettle(false, undefined, spool, onfinally, description);
         return result;
     }
 }

package/dst-stage1/mqtt-plus-event.js

@@ -22,6 +22,8 @@
 **  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 import { nanoid } from "nanoid";
+/*  internal requirements  */
+import { alignHandlerParams } from "./mqtt-plus-util";
 import { AuthTrait } from "./mqtt-plus-auth";
 import { Spool, ensureError, run } from "./mqtt-plus-error";
 /*  Event Emission Trait  */
@@ -100,7 +102,7 @@ export class EventTrait extends AuthTrait {
                     ` (topic: "${topicName}", payload: "${request.name}")`, { requestId });
                 return;
             }
-            const params = request.params ?? [];
+            const params = alignHandlerParams(request.params ?? [], callback);
             /*  sanity check request id  */
             if (this.eventControllers.has(requestId)) {
                 this.log("warning", `duplicate event request id -- dropped request for event "${name}"`, { requestId });

package/dst-stage1/mqtt-plus-options.js

@@ -46,5 +46,12 @@ export class OptionsTrait {
             },
             ...options
         };
+        /*  sanity check numeric option ranges  */
+        if (!(Number.isFinite(this.options.timeout) && this.options.timeout > 0))
+            throw new Error("options: \"timeout\" must be a positive number");
+        if (!(Number.isInteger(this.options.chunkSize) && this.options.chunkSize > 0))
+            throw new Error("options: \"chunkSize\" must be a positive integer");
+        if (!(Number.isInteger(this.options.chunkCredit) && this.options.chunkCredit >= 0))
+            throw new Error("options: \"chunkCredit\" must be a non-negative integer");
     }
 }

package/dst-stage1/mqtt-plus-service.js

@@ -23,6 +23,7 @@
 */
 import { nanoid } from "nanoid";
 /*  internal requirements  */
+import { alignHandlerParams } from "./mqtt-plus-util";
 import { run, Spool, ensureError } from "./mqtt-plus-error";
 import { EventTrait } from "./mqtt-plus-event";
 /*  Service Call Trait  */
@@ -96,7 +97,7 @@ export class ServiceTrait extends EventTrait {
             /*  determine request information  */
             const requestId = request.id;
             const senderId = request.sender;
-            const params = request.params ?? [];
+            const params = alignHandlerParams(request.params ?? [], callback);
             if (senderId === undefined || senderId === "") {
                 this.error(new Error("invalid request: missing sender"));
                 return;
@@ -237,11 +238,13 @@ export class ServiceTrait extends EventTrait {
             if (settled)
                 return false;
             settled = true;
-            /*  unroll fire-and-forget: the "settled" boolean guard is the
-                primary protection against concurrent/duplicate responses,
-                while cleanup errors are suppressed and the async MQTT
-                unsubscription is handled by reference-counting/linger  */
-            spool.unroll();
+            /*  unroll fire-and-forget: the "settled" boolean guard protects
+                against concurrent/duplicate responses and the async MQTT
+                unsubscription is handled by reference-counting/linger, while
+                cleanup failures are surfaced as "error" events  */
+            spool.unroll(false)?.catch((err) => {
+                this.error(ensureError(err, `cleanup after call of service "${name}" failed`));
+            });
             return true;
         };
         const promise = new Promise((resolve, reject) => {