@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/foundation/service-wire-m6a-codec.ts

@@ -8,10 +8,14 @@ import {
 } from './service-topology-registry';
 import {
   SERVICE_WIRE_PREFIX_SIZE,
+  SERVICE_WIRE_TEXT8_MAX_BYTES,
+  canonicalServiceWireTextLength,
   decodeCanonicalServiceWireText,
   encodeCanonicalServiceWireText
 } from './service-wire-binary-primitives';
 import {
+  SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
+  SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
   SERVICE_WIRE_MAGIC,
   SERVICE_WIRE_MAJOR,
   SERVICE_WIRE_REQUIRED_CAPABILITY,
@@ -32,6 +36,10 @@ export const APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES =
   APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
 const MAX_U32 = UINT32_MAX;
 const MAX_U64 = UINT64_MAX;
+// The framework multipart frame always carries these two schema constants;
+// decoding compares their bytes in place instead of decoding text.
+const MULTIPART_PACKET_NAME_BYTES = Buffer.from(SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME);
+const MULTIPART_CONTENT_TYPE_BYTES = Buffer.from(SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE);
 export const M6A_SERVICE_WIRE_MAGIC = SERVICE_WIRE_MAGIC;
 export const M6A_SERVICE_WIRE_MAJOR = SERVICE_WIRE_MAJOR;
 export const M6A_SERVICE_WIRE_REQUIRED_CAPABILITY = SERVICE_WIRE_REQUIRED_CAPABILITY;
@@ -67,11 +75,10 @@ export function encodeNodeSendHeader(): Buffer {
 }
 
 export function encodeNodeRequestHeader(correlation: bigint): Buffer {
-  return withU64(prefix(M6aServiceWireCommand.nodeRequest), correlation, 'correlation');
+  return withU64(M6aServiceWireCommand.nodeRequest, correlation, 0);
 }
 
-export function decodeNodeRequestHeader(frame: Uint8Array): bigint {
-  const header = decodeHeader(frame);
+export function decodeNodeRequestHeader(frame: Uint8Array, header = decodeHeader(frame)): bigint {
   if (
     header.command !== M6aServiceWireCommand.nodeRequest ||
     header.flags !== 0 ||
@@ -83,11 +90,13 @@ export function decodeNodeRequestHeader(frame: Uint8Array): bigint {
 }
 
 export function encodeChannelSendHeader(channelName: string): Buffer {
-  return concat(prefix(M6aServiceWireCommand.channelSend), encodeText8(channelName, 'channelName'));
+  const length = channelNameLength(channelName);
+  const result = frame(M6aServiceWireCommand.channelSend, 1 + length);
+  writeText8(result, PREFIX_SIZE, channelName, length);
+  return result;
 }
 
-export function decodeChannelSendHeader(frame: Uint8Array): string {
-  const header = decodeHeader(frame);
+export function decodeChannelSendHeader(frame: Uint8Array, header = decodeHeader(frame)): string {
   if (header.command !== M6aServiceWireCommand.channelSend || header.flags !== 0) {
     fail('Invalid channelSend header.');
   }
@@ -98,17 +107,28 @@ export function decodeChannelSendHeader(frame: Uint8Array): string {
 }
 
 export function encodeChannelRequestHeader(correlation: bigint, channelName: string): Buffer {
-  return concat(
-    withU64(prefix(M6aServiceWireCommand.channelRequest), correlation, 'correlation'),
-    encodeText8(channelName, 'channelName')
+  const length = channelNameLength(channelName);
+  const result = withU64(M6aServiceWireCommand.channelRequest, correlation, 1 + length);
+  writeText8(result, PREFIX_SIZE + 8, channelName, length);
+  return result;
+}
+
+function channelNameLength(channelName: string): number {
+  return canonicalServiceWireTextLength(
+    channelName,
+    'channelName',
+    SERVICE_WIRE_TEXT8_MAX_BYTES,
+    fail
   );
 }
 
-export function decodeChannelRequestHeader(frame: Uint8Array): {
+export function decodeChannelRequestHeader(
+  frame: Uint8Array,
+  header = decodeHeader(frame)
+): {
   readonly correlation: bigint;
   readonly channelName: string;
 } {
-  const header = decodeHeader(frame);
   if (header.command !== M6aServiceWireCommand.channelRequest || header.flags !== 0) {
     fail('Invalid channelRequest header.');
   }
@@ -123,7 +143,7 @@ export function encodeReplyHeader(
   correlation: bigint,
   terminalResult = 0,
   failureCode = 0,
-  tail: Uint8Array = Buffer.alloc(0)
+  tail?: Uint8Array
 ): Buffer {
   validateReplyFields(correlation, terminalResult, failureCode);
   //  service-wire-v1.schema.json: reply(20).tail -> `request-specific-tail`,
@@ -132,12 +152,11 @@ export function encodeReplyHeader(
   //  length on the wire; an empty tail yields exactly 21 bytes. (Contrast
   //  `actor-join-reply-tail`, which does declare `bodyLengthType: u16` and
   //  therefore carries its own inner length prefix.)
-  const result = Buffer.alloc(PREFIX_SIZE + 16 + tail.byteLength);
-  prefix(M6aServiceWireCommand.reply).copy(result);
+  const result = frame(M6aServiceWireCommand.reply, 16 + (tail?.byteLength ?? 0));
   result.writeBigUInt64BE(correlation, PREFIX_SIZE);
   result.writeUInt32BE(terminalResult, PREFIX_SIZE + 8);
   result.writeUInt32BE(failureCode, PREFIX_SIZE + 12);
-  Buffer.from(tail).copy(result, PREFIX_SIZE + 16);
+  if (tail !== undefined) result.set(tail, PREFIX_SIZE + 16);
   return result;
 }
 
@@ -158,31 +177,20 @@ export function decodeReplyHeader(frame: Uint8Array): ServiceReplyHeader {
     correlation: bytes.readBigUInt64BE(PREFIX_SIZE),
     terminalResult: bytes.readUInt32BE(PREFIX_SIZE + 8),
     failureCode: bytes.readUInt32BE(PREFIX_SIZE + 12),
-    tail: Buffer.from(bytes.subarray(PREFIX_SIZE + 16))
+    // A view of the frame: the caller validates the tail before the frame is released.
+    tail: bytes.subarray(PREFIX_SIZE + 16)
   };
   validateReplyFields(result.correlation, result.terminalResult, result.failureCode);
   return result;
 }
 
 export function encodeApplicationPayload(payload: ServiceApplicationPayload): Buffer {
-  const packetName = encodeText8(payload.packetName, 'packetName');
-  const contentType = encodeText8(payload.contentType, 'contentType');
-  if (payload.payload.byteLength > MAX_U32) fail('Application payload exceeds u32.');
-  const bodyLength =
-    packetName.byteLength + contentType.byteLength + 4 + payload.payload.byteLength;
-  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
-  const result = Buffer.alloc(5 + bodyLength);
-  result[0] = APPLICATION_PAYLOAD_VERSION;
-  result.writeUInt32BE(bodyLength, 1);
-  let offset = 5;
-  offset += packetName.copy(result, offset);
-  offset += contentType.copy(result, offset);
-  result.writeUInt32BE(payload.payload.byteLength, offset);
-  offset += 4;
-  Buffer.from(payload.payload.buffer, payload.payload.byteOffset, payload.payload.byteLength).copy(
-    result,
-    offset
+  const result = allocateApplicationPayload(
+    payload.packetName,
+    payload.contentType,
+    payload.payload.byteLength
   );
+  result.set(payload.payload, result.byteLength - payload.payload.byteLength);
   return result;
 }
 
@@ -198,35 +206,57 @@ export function encodeMultipartApplicationPayload(
 ): Buffer {
   if (parts.length === 0) fail('Multipart payload must contain at least one part.');
   if (parts.length > MAX_U32) fail('Multipart part count exceeds u32.');
-  const packetNameBytes = encodeText8(packetName, 'packetName');
-  const contentTypeBytes = encodeText8(contentType, 'contentType');
   let multipartLength = 4;
   for (const part of parts) {
     if (part.byteLength > MAX_U32) fail('Multipart part exceeds u32.');
     multipartLength += 4 + part.byteLength;
     if (multipartLength > MAX_U32) fail('Multipart payload exceeds u32.');
   }
-  const bodyLength = packetNameBytes.byteLength + contentTypeBytes.byteLength + 4 + multipartLength;
-  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
-  const result = Buffer.alloc(5 + bodyLength);
-  result[0] = APPLICATION_PAYLOAD_VERSION;
-  result.writeUInt32BE(bodyLength, 1);
-  let offset = 5;
-  offset += packetNameBytes.copy(result, offset);
-  offset += contentTypeBytes.copy(result, offset);
-  result.writeUInt32BE(multipartLength, offset);
-  offset += 4;
+  const result = allocateApplicationPayload(packetName, contentType, multipartLength);
+  let offset = result.byteLength - multipartLength;
   result.writeUInt32BE(parts.length, offset);
   offset += 4;
   for (const part of parts) {
     result.writeUInt32BE(part.byteLength, offset);
     offset += 4;
-    Buffer.from(part.buffer, part.byteOffset, part.byteLength).copy(result, offset);
+    result.set(part, offset);
     offset += part.byteLength;
   }
   return result;
 }
 
+function allocateApplicationPayload(
+  packetName: string,
+  contentType: string,
+  payloadLength: number
+): Buffer {
+  const packetNameLength = canonicalServiceWireTextLength(
+    packetName,
+    'packetName',
+    SERVICE_WIRE_TEXT8_MAX_BYTES,
+    fail
+  );
+  const contentTypeLength = canonicalServiceWireTextLength(
+    contentType,
+    'contentType',
+    SERVICE_WIRE_TEXT8_MAX_BYTES,
+    fail
+  );
+  if (payloadLength > MAX_U32) fail('Application payload exceeds u32.');
+  const frameLength =
+    APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES + packetNameLength + contentTypeLength + payloadLength;
+  const prefixLength = 1 + APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+  const bodyLength = frameLength - prefixLength;
+  if (bodyLength > MAX_U32) fail('Application payload body exceeds u32.');
+  const result = Buffer.alloc(frameLength);
+  result[0] = APPLICATION_PAYLOAD_VERSION;
+  result.writeUInt32BE(bodyLength, 1);
+  let offset = writeText8(result, prefixLength, packetName, packetNameLength);
+  offset = writeText8(result, offset, contentType, contentTypeLength);
+  result.writeUInt32BE(payloadLength, offset);
+  return result;
+}
+
 export function decodeApplicationPayload(frame: Uint8Array): ServiceApplicationPayload {
   const decoded = decodeApplicationPayloadView(frame);
   return {
@@ -241,18 +271,127 @@ export function decodeApplicationPayload(frame: Uint8Array): ServiceApplicationP
  * they must hand the multipart bytes to another runtime-owned queue.
  */
 export function decodeApplicationPayloadView(frame: Uint8Array): ServiceApplicationPayload {
-  const reader = new Reader(frame);
-  if (reader.u8('version') !== APPLICATION_PAYLOAD_VERSION)
-    fail('Invalid application payload version.');
-  const bodyLength = reader.u32('bodyLength');
-  if (bodyLength !== reader.remaining) fail('Application payload body length mismatch.');
+  const reader = applicationPayloadReader(frame);
   const packetName = reader.text8('packetName');
   const contentType = reader.text8('contentType');
-  const payloadLength = reader.u32('payloadLength');
-  if (payloadLength !== reader.remaining) fail('Application payload length mismatch.');
-  const payload = reader.view(payloadLength, 'payload');
-  reader.end();
-  return { packetName, contentType, payload };
+  return { packetName, contentType, payload: applicationPayloadView(reader) };
+}
+
+/**
+ * Decodes the framework multipart application frame, whose packet name and
+ * content type are the schema's multipart constants, and returns a view of its
+ * multipart payload without decoding either text field.
+ */
+export function decodeMultipartApplicationPayloadView(
+  frame: Uint8Array
+): ServiceApplicationPayload {
+  const bytes = asBuffer(frame);
+  const offset = multipartApplicationPayloadOffset(bytes);
+  return {
+    packetName: SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
+    contentType: SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
+    payload: bytes.subarray(offset)
+  };
+}
+
+/** Materializes final message parts directly over the retained application frame. */
+export function decodeMultipartApplicationParts<T>(
+  frame: Uint8Array,
+  materialize: (part: Buffer) => T,
+  release?: (part: T) => void
+): T[] {
+  const bytes = asBuffer(frame);
+  return decodeMultipartParts(
+    bytes,
+    materialize,
+    release,
+    multipartApplicationPayloadOffset(bytes)
+  );
+}
+
+function multipartApplicationPayloadOffset(bytes: Buffer): number {
+  let offset = applicationPayloadBodyOffset(bytes);
+  offset = expectText8At(bytes, offset, MULTIPART_PACKET_NAME_BYTES, 'packetName');
+  offset = expectText8At(bytes, offset, MULTIPART_CONTENT_TYPE_BYTES, 'contentType');
+  return applicationPayloadDataOffset(bytes, offset);
+}
+
+function expectText8At(bytes: Buffer, offset: number, expected: Buffer, field: string): number {
+  if (bytes.length <= offset) fail(`Truncated ${field}.length.`);
+  const length = bytes[offset++]!;
+  if (bytes.length - offset < length) fail(`Truncated ${field}.`);
+  if (length !== expected.length || expected.compare(bytes, offset, offset + length) !== 0) {
+    fail(`Unexpected ${field}.`);
+  }
+  return offset + length;
+}
+
+function applicationPayloadBodyOffset(bytes: Buffer): number {
+  if (bytes.length === 0) fail('Truncated version.');
+  if (bytes[0] !== APPLICATION_PAYLOAD_VERSION) fail('Invalid application payload version.');
+  const offset = 1 + APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+  if (bytes.length < offset) fail('Truncated bodyLength.');
+  if (bytes.readUInt32BE(1) !== bytes.length - offset)
+    fail('Application payload body length mismatch.');
+  return offset;
+}
+
+function applicationPayloadDataOffset(bytes: Buffer, offset: number): number {
+  if (bytes.length - offset < APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES)
+    fail('Truncated payloadLength.');
+  const length = bytes.readUInt32BE(offset);
+  offset += APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+  if (length !== bytes.length - offset) fail('Application payload length mismatch.');
+  return offset;
+}
+
+function applicationPayloadReader(frame: Uint8Array): Reader {
+  const bytes = asBuffer(frame);
+  return new Reader(bytes, applicationPayloadBodyOffset(bytes));
+}
+
+function applicationPayloadView(reader: Reader): Buffer {
+  return reader.buffer.subarray(applicationPayloadDataOffset(reader.buffer, reader.offset));
+}
+
+export function decodeMultipartParts<T>(
+  payload: Uint8Array,
+  materialize: (part: Buffer) => T,
+  release?: (part: T) => void,
+  offset = 0
+): T[] {
+  const bytes = asBuffer(payload);
+  if (bytes.length - offset < 4) throw new ServiceWireProtocolError('Truncated multipart payload.');
+  const count = bytes.readUInt32BE(offset);
+  if (count === 0 || count > Math.floor((bytes.length - offset - 4) / 4)) {
+    throw new ServiceWireProtocolError('Invalid multipart part count.');
+  }
+  const result = new Array<T>(count);
+  offset += 4;
+  let index = 0;
+  try {
+    for (; index < count; index++) {
+      if (bytes.length - offset < 4) {
+        throw new ServiceWireProtocolError('Truncated multipart part length.');
+      }
+      const length = bytes.readUInt32BE(offset);
+      offset += 4;
+      if (bytes.length - offset < length) {
+        throw new ServiceWireProtocolError('Truncated multipart part.');
+      }
+      result[index] = materialize(bytes.subarray(offset, offset + length));
+      offset += length;
+    }
+    if (offset !== bytes.length) {
+      throw new ServiceWireProtocolError('Multipart payload has trailing bytes.');
+    }
+    return result;
+  } catch (error) {
+    if (release !== undefined) {
+      for (let retained = 0; retained < index; retained++) release(result[retained]!);
+    }
+    throw error;
+  }
 }
 
 /**
@@ -262,11 +401,7 @@ export function decodeApplicationPayloadView(frame: Uint8Array): ServiceApplicat
  * message is admitted to an execution queue.
  */
 export function validateApplicationPayloadFrame(frame: Uint8Array): void {
-  const reader = new Reader(frame);
-  if (reader.u8('version') !== APPLICATION_PAYLOAD_VERSION)
-    fail('Invalid application payload version.');
-  const bodyLength = reader.u32('bodyLength');
-  if (bodyLength !== reader.remaining) fail('Application payload body length mismatch.');
+  const reader = applicationPayloadReader(frame);
   reader.text8('packetName');
   reader.text8('contentType');
   const payloadLength = reader.u32('payloadLength');
@@ -450,19 +585,37 @@ export function decodeHeader(frame: Uint8Array): ServiceWireHeader {
   return { command: frame[3]!, flags: frame[4]! };
 }
 
+/** Allocates a whole service wire record once and writes its prefix; the caller fills the body. */
+function frame(command: number, bodyLength: number): Buffer {
+  const result = Buffer.allocUnsafe(PREFIX_SIZE + bodyLength);
+  result[0] = M6A_SERVICE_WIRE_MAGIC[0];
+  result[1] = M6A_SERVICE_WIRE_MAGIC[1];
+  result[2] = M6A_SERVICE_WIRE_MAJOR;
+  result[3] = command;
+  result[4] = 0;
+  return result;
+}
+
 function prefix(command: number): Buffer {
-  return Buffer.from([
-    M6A_SERVICE_WIRE_MAGIC[0],
-    M6A_SERVICE_WIRE_MAGIC[1],
-    M6A_SERVICE_WIRE_MAJOR,
-    command,
-    0
-  ]);
+  return frame(command, 0);
 }
 
-function withU64(head: Buffer, value: bigint, field: string): Buffer {
-  if (value <= 0n || value > MAX_U64) fail(`${field} must be a non-zero u64.`);
-  return concat(head, encodeU64(value));
+/** A record whose body starts with the non-zero u64 correlation, followed by `restLength` bytes. */
+function withU64(command: number, correlation: bigint, restLength: number): Buffer {
+  if (correlation <= 0n || correlation > MAX_U64) fail('correlation must be a non-zero u64.');
+  const result = frame(command, 8 + restLength);
+  result.writeBigUInt64BE(correlation, PREFIX_SIZE);
+  return result;
+}
+
+/**
+ * Writes a validated text8 field — the byte length from
+ * canonicalServiceWireTextLength, then the UTF-8 text — and returns the next offset.
+ */
+function writeText8(target: Buffer, offset: number, value: string, length: number): number {
+  target[offset] = length;
+  target.write(value, offset + 1, length, 'utf8');
+  return offset + 1 + length;
 }
 
 function encodeU16(value: number): Buffer {
@@ -487,7 +640,7 @@ function encodeU64(value: bigint): Buffer {
 }
 
 function encodeText8(value: string, field: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, field, 0xff, fail);
+  const bytes = encodeCanonicalServiceWireText(value, field, SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
   return concat(Buffer.of(bytes.byteLength), bytes);
 }
 
@@ -501,7 +654,7 @@ function tlv(id: number, value: Buffer): Buffer {
 }
 
 function concat(...parts: readonly Uint8Array[]): Buffer {
-  return Buffer.concat(parts.map((part) => Buffer.from(part)));
+  return Buffer.concat(parts);
 }
 
 function readNonZeroU64(bytes: Buffer, offset: number, field: string): bigint {
@@ -511,7 +664,9 @@ function readNonZeroU64(bytes: Buffer, offset: number, field: string): bigint {
 }
 
 function asBuffer(value: Uint8Array): Buffer {
-  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  return Buffer.isBuffer(value)
+    ? value
+    : Buffer.from(value.buffer, value.byteOffset, value.byteLength);
 }
 
 function validateAdmissionCommand(command: number): void {
@@ -633,13 +788,13 @@ class Reader {
   text8(field: string): string {
     const length = this.u8(`${field}.length`);
     if (length === 0) fail(`${field} must be non-empty.`);
-    return decodeText(this.bytes(length, field), field);
+    return decodeText(this.view(length, field), field);
   }
 
   text16(field: string): string {
     const length = this.u16(`${field}.length`);
     if (length === 0 || length > SERVICE_ROUTE_TEXT_MAX_BYTES) fail(`${field} has invalid length.`);
-    return decodeText(this.bytes(length, field), field);
+    return decodeText(this.view(length, field), field);
   }
 
   bytes(length: number, field: string): Buffer {

package/src/runtime/handlers/handler-instance-scope.ts

@@ -9,13 +9,10 @@ export interface ZLinkHandlerInstanceScope {
 }
 
 interface ZLinkHandlerInstanceScopeFactory {
+  prepare?(type: Type): void | (() => unknown);
   create(context?: ZLinkMessageContext): ZLinkHandlerInstanceScope;
 }
 
-interface ActiveHandlerScope {
-  readonly scope: ZLinkHandlerInstanceScope;
-}
-
 interface Deferred<T> {
   readonly promise: Promise<T>;
   readonly resolve: (value: T) => void;
@@ -29,12 +26,37 @@ interface LifecycleScopeDisposal {
 }
 
 const HANDLER_SCOPE_FACTORY = Symbol.for('@zlink-systems/framework.handler-instance-scope-factory');
-const activeHandlerScope = new AsyncLocalStorage<ActiveHandlerScope>();
+const activeHandlerScope = new AsyncLocalStorage<ZLinkHandlerInstanceScope>();
 const activeLifecycleScope = new AsyncLocalStorage<LifecycleHandlerInstanceScope>();
 const detachedLifecycleResource = new AsyncResource('zlink:handler-instance-scope');
 const dispatchScopes = new WeakMap<object, ZLinkHandlerInstanceScope>();
 const lifecycleScopes = new WeakMap<object, LifecycleHandlerInstanceScope>();
 
+export function registerHandlerInstanceScopeFactory(
+  providerResolver: ZLinkProviderResolver,
+  factory: ZLinkHandlerInstanceScopeFactory
+): void {
+  Object.defineProperty(providerResolver, HANDLER_SCOPE_FACTORY, {
+    value: factory,
+    enumerable: false
+  });
+}
+
+export function prepareHandlerInstance<T>(
+  providerResolver: ZLinkProviderResolver | undefined,
+  type: Type<T>
+): (() => T) | undefined {
+  if (providerResolver === undefined) return () => new type();
+  const factory = (providerResolver as unknown as Record<PropertyKey, unknown>)[
+    HANDLER_SCOPE_FACTORY
+  ];
+  if (isHandlerInstanceScopeFactory(factory)) {
+    const activate = factory.prepare?.(type);
+    if (activate !== undefined) return activate as () => T;
+  }
+  return undefined;
+}
+
 export async function runInHandlerInstanceScope<T>(
   providerResolver: ZLinkProviderResolver | undefined,
   context: ZLinkMessageContext | undefined,
@@ -42,7 +64,7 @@ export async function runInHandlerInstanceScope<T>(
 ): Promise<T> {
   const active = activeHandlerScope.getStore();
   if (active !== undefined) {
-    return callback(active.scope);
+    return callback(active);
   }
   if (context !== undefined) {
     const existing = dispatchScopes.get(context);
@@ -56,7 +78,7 @@ export async function runInHandlerInstanceScope<T>(
     dispatchScopes.set(context, scope);
   }
   try {
-    return await activeHandlerScope.run({ scope }, () => callback(scope));
+    return await activeHandlerScope.run(scope, () => callback(scope));
   } finally {
     if (context !== undefined && dispatchScopes.get(context) === scope) {
       dispatchScopes.delete(context);
@@ -144,14 +166,15 @@ class DefaultHandlerInstanceScope implements ZLinkHandlerInstanceScope {
     if (existing !== undefined) return existing;
     const activation = createDeferred<unknown>();
     this.instances.set(type, activation.promise);
-    void this.activate(type, activation);
+    this.activate(type, activation);
     return activation.promise as Promise<T>;
   }
 
   async dispose(): Promise<void> {
     if (this.disposed) return;
     this.disposed = true;
-    await Promise.allSettled(this.instances.values());
+    if (this.owned.length !== this.instances.size)
+      await Promise.allSettled(this.instances.values());
     try {
       await disposeOwnedInstances(this.owned);
     } finally {
@@ -159,21 +182,43 @@ class DefaultHandlerInstanceScope implements ZLinkHandlerInstanceScope {
       this.instances.clear();
     }
   }
-  private async activate<T>(type: Type<T>, activation: Deferred<unknown>): Promise<void> {
-    let instance: T;
+  private activate<T>(type: Type<T>, activation: Deferred<unknown>): void {
     try {
       const created = this.providerResolver?.create?.(type);
-      instance = created === undefined ? new type() : await created;
+      if (created === undefined) {
+        this.completeActivation(new type(), activation);
+      } else {
+        void this.activatePending(created, activation);
+      }
     } catch (error) {
       activation.reject(error);
-      return;
     }
+  }
 
+  private async activatePending<T>(
+    created: T | Promise<T>,
+    activation: Deferred<unknown>
+  ): Promise<void> {
+    try {
+      this.completeActivation(await created, activation);
+    } catch (error) {
+      activation.reject(error);
+    }
+  }
+
+  private completeActivation(instance: unknown, activation: Deferred<unknown>): void {
     if (!this.disposed) {
       this.owned.push(instance);
       activation.resolve(instance);
       return;
     }
+    void this.disposeLateActivation(instance, activation);
+  }
+
+  private async disposeLateActivation(
+    instance: unknown,
+    activation: Deferred<unknown>
+  ): Promise<void> {
     try {
       await disposeOwnedInstance(instance);
       activation.reject(new Error('Handler instance scope was disposed during activation.'));
@@ -306,6 +351,11 @@ function startOutsideLifecycleInvocation<T>(work: () => T): T {
 }
 
 export async function disposeOwnedInstance(instance: unknown): Promise<void> {
+  const cleanup = handlerInstanceCleanup(instance);
+  if (cleanup !== undefined) await cleanup.call(instance);
+}
+
+export function handlerInstanceCleanup(instance: unknown): (() => unknown) | undefined {
   if (instance === null || instance === undefined) return;
   const value = instance as {
     dispose?: () => unknown;
@@ -313,12 +363,13 @@ export async function disposeOwnedInstance(instance: unknown): Promise<void> {
     onModuleDestroy?: () => unknown;
   };
   if (typeof value.dispose === 'function') {
-    await value.dispose();
+    return value.dispose;
   } else if (typeof value.close === 'function') {
-    await value.close();
+    return value.close;
   } else if (typeof value.onModuleDestroy === 'function') {
-    await value.onModuleDestroy();
+    return value.onModuleDestroy;
   }
+  return undefined;
 }
 
 export async function disposeOwnedInstances(instances: readonly unknown[]): Promise<void> {