@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/foundation/service-wire-m6a-codec.js

@@ -14,6 +14,9 @@ exports.encodeApplicationPayload = encodeApplicationPayload;
 exports.encodeMultipartApplicationPayload = encodeMultipartApplicationPayload;
 exports.decodeApplicationPayload = decodeApplicationPayload;
 exports.decodeApplicationPayloadView = decodeApplicationPayloadView;
+exports.decodeMultipartApplicationPayloadView = decodeMultipartApplicationPayloadView;
+exports.decodeMultipartApplicationParts = decodeMultipartApplicationParts;
+exports.decodeMultipartParts = decodeMultipartParts;
 exports.validateApplicationPayloadFrame = validateApplicationPayloadFrame;
 exports.encodeRouteMeshAdmission = encodeRouteMeshAdmission;
 exports.decodeRouteMeshAdmission = decodeRouteMeshAdmission;
@@ -37,6 +40,10 @@ exports.APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES = 1 +
     APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
 const MAX_U32 = stream_wire_1.UINT32_MAX;
 const MAX_U64 = stream_wire_1.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_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME);
+const MULTIPART_CONTENT_TYPE_BYTES = Buffer.from(service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE);
 exports.M6A_SERVICE_WIRE_MAGIC = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC;
 exports.M6A_SERVICE_WIRE_MAJOR = service_wire_constants_generated_1.SERVICE_WIRE_MAJOR;
 exports.M6A_SERVICE_WIRE_REQUIRED_CAPABILITY = service_wire_constants_generated_1.SERVICE_WIRE_REQUIRED_CAPABILITY;
@@ -52,10 +59,9 @@ function encodeNodeSendHeader() {
     return prefix(exports.M6aServiceWireCommand.nodeSend);
 }
 function encodeNodeRequestHeader(correlation) {
-    return withU64(prefix(exports.M6aServiceWireCommand.nodeRequest), correlation, 'correlation');
+    return withU64(exports.M6aServiceWireCommand.nodeRequest, correlation, 0);
 }
-function decodeNodeRequestHeader(frame) {
-    const header = decodeHeader(frame);
+function decodeNodeRequestHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.nodeRequest ||
         header.flags !== 0 ||
         frame.byteLength !== 13) {
@@ -64,10 +70,12 @@ function decodeNodeRequestHeader(frame) {
     return readNonZeroU64(asBuffer(frame), PREFIX_SIZE, 'correlation');
 }
 function encodeChannelSendHeader(channelName) {
-    return concat(prefix(exports.M6aServiceWireCommand.channelSend), encodeText8(channelName, 'channelName'));
+    const length = channelNameLength(channelName);
+    const result = frame(exports.M6aServiceWireCommand.channelSend, 1 + length);
+    writeText8(result, PREFIX_SIZE, channelName, length);
+    return result;
 }
-function decodeChannelSendHeader(frame) {
-    const header = decodeHeader(frame);
+function decodeChannelSendHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.channelSend || header.flags !== 0) {
         fail('Invalid channelSend header.');
     }
@@ -77,10 +85,15 @@ function decodeChannelSendHeader(frame) {
     return channelName;
 }
 function encodeChannelRequestHeader(correlation, channelName) {
-    return concat(withU64(prefix(exports.M6aServiceWireCommand.channelRequest), correlation, 'correlation'), encodeText8(channelName, 'channelName'));
+    const length = channelNameLength(channelName);
+    const result = withU64(exports.M6aServiceWireCommand.channelRequest, correlation, 1 + length);
+    writeText8(result, PREFIX_SIZE + 8, channelName, length);
+    return result;
 }
-function decodeChannelRequestHeader(frame) {
-    const header = decodeHeader(frame);
+function channelNameLength(channelName) {
+    return (0, service_wire_binary_primitives_1.canonicalServiceWireTextLength)(channelName, 'channelName', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+}
+function decodeChannelRequestHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.channelRequest || header.flags !== 0) {
         fail('Invalid channelRequest header.');
     }
@@ -90,7 +103,7 @@ function decodeChannelRequestHeader(frame) {
     reader.end();
     return { correlation, channelName };
 }
-function encodeReplyHeader(correlation, terminalResult = 0, failureCode = 0, tail = Buffer.alloc(0)) {
+function encodeReplyHeader(correlation, terminalResult = 0, failureCode = 0, tail) {
     validateReplyFields(correlation, terminalResult, failureCode);
     //  service-wire-v1.schema.json: reply(20).tail -> `request-specific-tail`,
     //  a conditional-union with NO `bodyLengthType`, so the selected case's
@@ -98,12 +111,12 @@ function encodeReplyHeader(correlation, terminalResult = 0, failureCode = 0, tai
     //  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(exports.M6aServiceWireCommand.reply).copy(result);
+    const result = frame(exports.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;
 }
 function decodeReplyHeader(frame) {
@@ -121,28 +134,15 @@ function decodeReplyHeader(frame) {
         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;
 }
 function encodeApplicationPayload(payload) {
-    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] = exports.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;
 }
 /**
@@ -155,8 +155,6 @@ function encodeMultipartApplicationPayload(parts, packetName, contentType) {
         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)
@@ -165,27 +163,36 @@ function encodeMultipartApplicationPayload(parts, packetName, contentType) {
         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] = exports.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, contentType, payloadLength) {
+    const packetNameLength = (0, service_wire_binary_primitives_1.canonicalServiceWireTextLength)(packetName, 'packetName', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+    const contentTypeLength = (0, service_wire_binary_primitives_1.canonicalServiceWireTextLength)(contentType, 'contentType', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+    if (payloadLength > MAX_U32)
+        fail('Application payload exceeds u32.');
+    const frameLength = exports.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] = exports.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;
+}
 function decodeApplicationPayload(frame) {
     const decoded = decodeApplicationPayloadView(frame);
     return {
@@ -199,20 +206,111 @@ function decodeApplicationPayload(frame) {
  * they must hand the multipart bytes to another runtime-owned queue.
  */
 function decodeApplicationPayloadView(frame) {
-    const reader = new Reader(frame);
-    if (reader.u8('version') !== exports.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)
+    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.
+ */
+function decodeMultipartApplicationPayloadView(frame) {
+    const bytes = asBuffer(frame);
+    const offset = multipartApplicationPayloadOffset(bytes);
+    return {
+        packetName: service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
+        contentType: service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
+        payload: bytes.subarray(offset)
+    };
+}
+/** Materializes final message parts directly over the retained application frame. */
+function decodeMultipartApplicationParts(frame, materialize, release) {
+    const bytes = asBuffer(frame);
+    return decodeMultipartParts(bytes, materialize, release, multipartApplicationPayloadOffset(bytes));
+}
+function multipartApplicationPayloadOffset(bytes) {
+    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, offset, expected, field) {
+    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) {
+    if (bytes.length === 0)
+        fail('Truncated version.');
+    if (bytes[0] !== exports.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, offset) {
+    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.');
-    const payload = reader.view(payloadLength, 'payload');
-    reader.end();
-    return { packetName, contentType, payload };
+    return offset;
+}
+function applicationPayloadReader(frame) {
+    const bytes = asBuffer(frame);
+    return new Reader(bytes, applicationPayloadBodyOffset(bytes));
+}
+function applicationPayloadView(reader) {
+    return reader.buffer.subarray(applicationPayloadDataOffset(reader.buffer, reader.offset));
+}
+function decodeMultipartParts(payload, materialize, release, offset = 0) {
+    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(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;
+    }
 }
 /**
  * Validates the M6A envelope without retaining a second payload buffer. The
@@ -221,12 +319,7 @@ function decodeApplicationPayloadView(frame) {
  * message is admitted to an execution queue.
  */
 function validateApplicationPayloadFrame(frame) {
-    const reader = new Reader(frame);
-    if (reader.u8('version') !== exports.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');
@@ -383,19 +476,35 @@ function decodeHeader(frame) {
         fail('Unsupported service wire major.');
     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, bodyLength) {
+    const result = Buffer.allocUnsafe(PREFIX_SIZE + bodyLength);
+    result[0] = exports.M6A_SERVICE_WIRE_MAGIC[0];
+    result[1] = exports.M6A_SERVICE_WIRE_MAGIC[1];
+    result[2] = exports.M6A_SERVICE_WIRE_MAJOR;
+    result[3] = command;
+    result[4] = 0;
+    return result;
+}
 function prefix(command) {
-    return Buffer.from([
-        exports.M6A_SERVICE_WIRE_MAGIC[0],
-        exports.M6A_SERVICE_WIRE_MAGIC[1],
-        exports.M6A_SERVICE_WIRE_MAJOR,
-        command,
-        0
-    ]);
-}
-function withU64(head, value, field) {
-    if (value <= 0n || value > MAX_U64)
-        fail(`${field} must be a non-zero u64.`);
-    return concat(head, encodeU64(value));
+    return frame(command, 0);
+}
+/** A record whose body starts with the non-zero u64 correlation, followed by `restLength` bytes. */
+function withU64(command, correlation, restLength) {
+    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, offset, value, length) {
+    target[offset] = length;
+    target.write(value, offset + 1, length, 'utf8');
+    return offset + 1 + length;
 }
 function encodeU16(value) {
     if (!Number.isInteger(value) || value < 0 || value > 0xffff)
@@ -419,7 +528,7 @@ function encodeU64(value) {
     return result;
 }
 function encodeText8(value, field) {
-    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, 0xff, fail);
+    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
 function encodeText16(value, field) {
@@ -430,7 +539,7 @@ function tlv(id, value) {
     return concat(Buffer.of(id), encodeU32(value.byteLength), value);
 }
 function concat(...parts) {
-    return Buffer.concat(parts.map((part) => Buffer.from(part)));
+    return Buffer.concat(parts);
 }
 function readNonZeroU64(bytes, offset, field) {
     const result = bytes.readBigUInt64BE(offset);
@@ -439,7 +548,9 @@ function readNonZeroU64(bytes, offset, field) {
     return result;
 }
 function asBuffer(value) {
-    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) {
     if (command !== exports.M6aServiceWireCommand.hello &&
@@ -545,13 +656,13 @@ class Reader {
         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) {
         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, field) {
         this.require(length, field);

package/dist/runtime/handlers/handler-instance-scope.d.ts

@@ -5,9 +5,17 @@ export interface ZLinkHandlerInstanceScope {
     resolve<T>(type: Type<T>): Promise<T>;
     dispose(): Promise<void>;
 }
+interface ZLinkHandlerInstanceScopeFactory {
+    prepare?(type: Type): void | (() => unknown);
+    create(context?: ZLinkMessageContext): ZLinkHandlerInstanceScope;
+}
+export declare function registerHandlerInstanceScopeFactory(providerResolver: ZLinkProviderResolver, factory: ZLinkHandlerInstanceScopeFactory): void;
+export declare function prepareHandlerInstance<T>(providerResolver: ZLinkProviderResolver | undefined, type: Type<T>): (() => T) | undefined;
 export declare function runInHandlerInstanceScope<T>(providerResolver: ZLinkProviderResolver | undefined, context: ZLinkMessageContext | undefined, callback: (scope: ZLinkHandlerInstanceScope) => Promise<T>): Promise<T>;
 export declare function resolveLifecycleHandler<T>(owner: object, type: Type<T>, providerResolver?: ZLinkProviderResolver): Promise<T>;
 export declare function runWithLifecycleHandler<THandler, TResult>(owner: object, type: Type<THandler>, providerResolver: ZLinkProviderResolver | undefined, callback: (handler: THandler) => Promise<TResult>): Promise<TResult>;
 export declare function disposeLifecycleHandlers(owner: object, detachedTaskRunner: ZLinkDetachedTaskRunner): Promise<void>;
 export declare function disposeOwnedInstance(instance: unknown): Promise<void>;
+export declare function handlerInstanceCleanup(instance: unknown): (() => unknown) | undefined;
 export declare function disposeOwnedInstances(instances: readonly unknown[]): Promise<void>;
+export {};

package/dist/runtime/handlers/handler-instance-scope.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHandlerInstanceScopeFactory = registerHandlerInstanceScopeFactory;
+exports.prepareHandlerInstance = prepareHandlerInstance;
 exports.runInHandlerInstanceScope = runInHandlerInstanceScope;
 exports.resolveLifecycleHandler = resolveLifecycleHandler;
 exports.runWithLifecycleHandler = runWithLifecycleHandler;
 exports.disposeLifecycleHandlers = disposeLifecycleHandlers;
 exports.disposeOwnedInstance = disposeOwnedInstance;
+exports.handlerInstanceCleanup = handlerInstanceCleanup;
 exports.disposeOwnedInstances = disposeOwnedInstances;
 const node_async_hooks_1 = require("node:async_hooks");
 const HANDLER_SCOPE_FACTORY = Symbol.for('@zlink-systems/framework.handler-instance-scope-factory');
@@ -13,10 +16,27 @@ const activeLifecycleScope = new node_async_hooks_1.AsyncLocalStorage();
 const detachedLifecycleResource = new node_async_hooks_1.AsyncResource('zlink:handler-instance-scope');
 const dispatchScopes = new WeakMap();
 const lifecycleScopes = new WeakMap();
+function registerHandlerInstanceScopeFactory(providerResolver, factory) {
+    Object.defineProperty(providerResolver, HANDLER_SCOPE_FACTORY, {
+        value: factory,
+        enumerable: false
+    });
+}
+function prepareHandlerInstance(providerResolver, type) {
+    if (providerResolver === undefined)
+        return () => new type();
+    const factory = providerResolver[HANDLER_SCOPE_FACTORY];
+    if (isHandlerInstanceScopeFactory(factory)) {
+        const activate = factory.prepare?.(type);
+        if (activate !== undefined)
+            return activate;
+    }
+    return undefined;
+}
 async function runInHandlerInstanceScope(providerResolver, context, callback) {
     const active = activeHandlerScope.getStore();
     if (active !== undefined) {
-        return callback(active.scope);
+        return callback(active);
     }
     if (context !== undefined) {
         const existing = dispatchScopes.get(context);
@@ -29,7 +49,7 @@ async function runInHandlerInstanceScope(providerResolver, context, callback) {
         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) {
@@ -94,14 +114,15 @@ class DefaultHandlerInstanceScope {
             return existing;
         const activation = createDeferred();
         this.instances.set(type, activation.promise);
-        void this.activate(type, activation);
+        this.activate(type, activation);
         return activation.promise;
     }
     async dispose() {
         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);
         }
@@ -110,21 +131,37 @@ class DefaultHandlerInstanceScope {
             this.instances.clear();
         }
     }
-    async activate(type, activation) {
-        let instance;
+    activate(type, activation) {
         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;
         }
+    }
+    async activatePending(created, activation) {
+        try {
+            this.completeActivation(await created, activation);
+        }
+        catch (error) {
+            activation.reject(error);
+        }
+    }
+    completeActivation(instance, activation) {
         if (!this.disposed) {
             this.owned.push(instance);
             activation.resolve(instance);
             return;
         }
+        void this.disposeLateActivation(instance, activation);
+    }
+    async disposeLateActivation(instance, activation) {
         try {
             await disposeOwnedInstance(instance);
             activation.reject(new Error('Handler instance scope was disposed during activation.'));
@@ -240,18 +277,24 @@ function startOutsideLifecycleInvocation(work) {
     return detachedLifecycleResource.runInAsyncScope(work);
 }
 async function disposeOwnedInstance(instance) {
+    const cleanup = handlerInstanceCleanup(instance);
+    if (cleanup !== undefined)
+        await cleanup.call(instance);
+}
+function handlerInstanceCleanup(instance) {
     if (instance === null || instance === undefined)
         return;
     const value = instance;
     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;
 }
 async function disposeOwnedInstances(instances) {
     const failures = [];

package/dist/runtime/host/actor-packet-relay.d.ts

@@ -6,6 +6,7 @@ import type { DefaultZLinkActorManager } from '../actors';
 import type { DefaultZLinkSpotManager, ZLinkSpotNodeRuntimeManager } from '../spots';
 import type { ZLinkDetachedTaskRunner } from '../spots/spot-actor-join-dispatch';
 import type { ZLinkBoundSessionResponsePort, ZLinkSessionBindingConfirmationOptions, ZLinkStreamActorLookupPort } from '../streams/stream-binding-runtime-ports';
+import type { ServiceStreamSessionBinding } from '../foundation/service-runtime-contracts';
 import { type ZLinkStreamFrameHeader } from '../streams/protocol';
 import type { MeshRouterResolver } from './mesh-router-resolver';
 import type { ZLinkStoreLocationResolvers } from '../locations';
@@ -29,12 +30,11 @@ export declare class ZLinkActorPacketRelay {
     private readonly options;
     private readonly targets;
     constructor(options: ZLinkActorPacketRelayOptions);
-    notifyBoundActorDisconnected(actor: ZLinkSessionActor, signal?: AbortSignal): Promise<void>;
+    notifyBoundActorDisconnected(actor: ZLinkSessionActor, signal?: AbortSignal, binding?: ServiceStreamSessionBinding): Promise<void>;
     clearRemoteActorPacketTarget(actorId: string): void;
     updateRemoteActorPacketTarget(actorId: string, value: unknown): Promise<void>;
     actorPacketTargetForState(actorId: string): ZLinkRemoteActorPacketTarget | undefined;
-    notifyActorDisconnectedById(actorId: string, signal?: AbortSignal): Promise<void>;
-    notifyLocalActorDisconnectedById(actorId: string, signal?: AbortSignal): Promise<void>;
+    notifyLocalActorDisconnectedById(actorId: string, signal?: AbortSignal, binding?: ServiceStreamSessionBinding, bindingActorRef?: ActorRef): Promise<void>;
     receiveRemoteActorPacketRelay(payload: unknown, _routeContext: ZLinkRouteMessageContext): Promise<{
         readonly ok: boolean;
         readonly error?: unknown;
@@ -52,8 +52,10 @@ export declare class ZLinkActorPacketRelay {
      */
     private installSameNodeSessionBinding;
     relayRemoteActorPacket(actor: ZLinkSessionActor, frameHeader: ZLinkStreamFrameHeader, payload: Message): Promise<boolean>;
-    notifyRemoteActorDisconnected(actorId: string, remoteTarget: ZLinkRemoteBoundSessionTarget | ZLinkRemoteActorPacketTarget, signal?: AbortSignal, bindingActorRef?: ActorRef): Promise<void>;
+    notifyRemoteActorDisconnected(actorId: string, remoteTarget: ZLinkRemoteBoundSessionTarget | ZLinkRemoteActorPacketTarget, signal?: AbortSignal, bindingActorRef?: ActorRef, binding?: ServiceStreamSessionBinding): Promise<void>;
+    private disconnectedFrame;
     private requireCurrentRemoteBinding;
+    private matchesCurrentRemoteBinding;
     private requestRemoteTarget;
     private relayLocalActorPacket;
     private sendCapturedOrCurrentBoundSessionResponse;