@zlink-systems/framework 0.30.1 → 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,7 +59,7 @@ 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, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.nodeRequest ||
@@ -63,7 +70,10 @@ function decodeNodeRequestHeader(frame, header = decodeHeader(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, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.channelSend || header.flags !== 0) {
@@ -75,7 +85,13 @@ function decodeChannelSendHeader(frame, header = decodeHeader(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 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) {
@@ -87,7 +103,7 @@ function decodeChannelRequestHeader(frame, header = decodeHeader(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
@@ -95,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) {
@@ -118,7 +134,8 @@ 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;
@@ -159,14 +176,11 @@ function encodeMultipartApplicationPayload(parts, packetName, contentType) {
     return result;
 }
 function allocateApplicationPayload(packetName, contentType, payloadLength) {
-    const packetNameBytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(packetName, 'packetName', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
-    const contentTypeBytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(contentType, 'contentType', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+    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 +
-        packetNameBytes.byteLength +
-        contentTypeBytes.byteLength +
-        payloadLength;
+    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)
@@ -174,13 +188,8 @@ function allocateApplicationPayload(packetName, contentType, payloadLength) {
     const result = Buffer.alloc(frameLength);
     result[0] = exports.APPLICATION_PAYLOAD_VERSION;
     result.writeUInt32BE(bodyLength, 1);
-    let offset = prefixLength;
-    result[offset++] = packetNameBytes.byteLength;
-    result.set(packetNameBytes, offset);
-    offset += packetNameBytes.byteLength;
-    result[offset++] = contentTypeBytes.byteLength;
-    result.set(contentTypeBytes, offset);
-    offset += contentTypeBytes.byteLength;
+    let offset = writeText8(result, prefixLength, packetName, packetNameLength);
+    offset = writeText8(result, offset, contentType, contentTypeLength);
     result.writeUInt32BE(payloadLength, offset);
     return result;
 }
@@ -197,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
@@ -219,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');
@@ -381,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)
@@ -437,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 &&
@@ -543,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/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;

package/dist/runtime/host/actor-packet-relay.js

@@ -5,12 +5,14 @@ const framework_errors_internal_1 = require("../framework-errors-internal");
 const runtime_message_1 = require("../backend/runtime-message");
 const contracts_1 = require("../../contracts");
 const ConfigurationException_1 = require("../../contracts/Configuration/ConfigurationException");
+const abort_1 = require("../abort");
 const actors_1 = require("../actors");
 const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
 const actor_routed_json_request_1 = require("../actors/actor-routed-json-request");
 const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
 const bound_session_wire_1 = require("../actors/bound-session-wire");
 const routing_id_1 = require("../routing-id");
+const session_disconnected_wire_1 = require("../actors/session-disconnected-wire");
 const submission_result_1 = require("../messaging/submission-result");
 const actor_session_binding_runtime_owner_1 = require("../streams/actor-session-binding-runtime-owner");
 const protocol_1 = require("../streams/protocol");
@@ -32,29 +34,14 @@ class ZLinkActorPacketRelay {
             spotRouterChannelIdForMesh: spotRouterChannelIdByMesh?.call(options.meshRouters) ?? ((meshName) => meshName)
         });
     }
-    async notifyBoundActorDisconnected(actor, signal) {
-        const state = this.options.actorManager()?.getState(actor.actorId);
-        const currentRemoteBoundSessionTarget = state?.spotId === undefined ? undefined : state.remoteBoundSessionTarget;
-        const currentRemoteActorPacketTarget = state?.spotId === undefined ? undefined : state.remoteActorPacketTarget;
-        const remoteTarget = currentRemoteBoundSessionTarget ??
-            currentRemoteActorPacketTarget ??
-            (state?.spotId === undefined ? undefined : this.targets.cachedTargetForActor(actor));
-        if (remoteTarget !== undefined) {
-            await this.notifyRemoteActorDisconnected(actor.actorId, remoteTarget, signal, actor.ref);
-            return;
-        }
+    async notifyBoundActorDisconnected(actor, signal, binding) {
+        // The Session binding owns this route, including after relocation and detach (§5, §7).
         const actorRefTarget = this.targets.targetForActorRef(actor.ref);
         if (actorRefTarget !== undefined) {
-            await this.notifyRemoteActorDisconnected(actor.actorId, actorRefTarget, signal, actor.ref);
+            await this.notifyRemoteActorDisconnected(actor.actorId, actorRefTarget, signal, actor.ref, binding);
             return;
         }
-        if (state?.spotId !== undefined && state.actor !== undefined) {
-            const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(state.spotId, state.actor, signal);
-            if (handled) {
-                return;
-            }
-        }
-        await this.notifyActorDisconnectedById(actor.actorId, signal);
+        await this.notifyLocalActorDisconnectedById(actor.actorId, signal, binding, actor.ref);
     }
     clearRemoteActorPacketTarget(actorId) {
         this.targets.clear(actorId);
@@ -65,34 +52,22 @@ class ZLinkActorPacketRelay {
     actorPacketTargetForState(actorId) {
         return this.targets.targetForState(actorId);
     }
-    async notifyActorDisconnectedById(actorId, signal) {
+    async notifyLocalActorDisconnectedById(actorId, signal, binding, bindingActorRef) {
+        (0, abort_1.throwIfAborted)(signal);
         const state = this.options.actorManager()?.getState(actorId);
-        const remoteTarget = state === undefined
-            ? undefined
-            : (state.remoteBoundSessionTarget ?? state.remoteActorPacketTarget);
-        if (remoteTarget !== undefined) {
-            await this.notifyRemoteActorDisconnected(actorId, remoteTarget, signal);
-            return;
-        }
-        await this.notifyLocalActorDisconnectedById(actorId, signal);
-    }
-    async notifyLocalActorDisconnectedById(actorId, signal) {
-        const state = this.options.actorManager()?.getState(actorId);
-        if (state?.spotId !== undefined && state.actor !== undefined) {
-            const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(state.spotId, state.actor, signal);
-            if (handled) {
-                return;
-            }
-        }
-        const localActor = state?.actor;
-        if (localActor === undefined) {
-            throw new Error(`Actor '${actorId}' does not have a local actor instance.`);
+        const frame = this.disconnectedFrame(actorId, binding);
+        const header = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(frame.header));
+        const body = runtime_message_1.ZLinkBufferMessage.fromOwned(frame.payload);
+        try {
+            if (state?.spotId === undefined)
+                await this.requireSpotNodeRuntime().dispatchEntryActorPacket('local', actorId, [header, body], false, undefined, bindingActorRef);
+            else
+                await this.requireSpotManager().dispatchRoutedActorPacket('local', state.spotId, actorId, [header, body], false, undefined, bindingActorRef);
         }
-        const meshName = state?.meshName;
-        if (meshName === undefined) {
-            throw new Error(`Actor '${actorId}' does not have a RouteMesh identity.`);
+        finally {
+            header.close();
+            body.close();
         }
-        await this.requireSpotNodeRuntime().notifyEntrySpotActorDisconnected(meshName, localActor, signal);
     }
     async receiveRemoteActorPacketRelay(payload, _routeContext) {
         const relay = (0, actor_packet_relay_wire_1.decodeRemoteActorPacketRelayPayload)(payload);
@@ -159,22 +134,23 @@ class ZLinkActorPacketRelay {
                 }
                 return { ok: true, response: { acknowledged: true } };
             }
-            if (frameHeader.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
-                this.requireCurrentRemoteBinding(relay, _routeContext);
-                await this.notifyLocalActorDisconnectedById(relay.actorId);
-                return {
-                    ok: true,
-                    actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId))
-                };
-            }
-            if (remoteBoundSessionTarget !== undefined) {
+            if (remoteBoundSessionTarget !== undefined &&
+                frameHeader.name !== actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
                 this.requireCurrentRemoteBinding(relay, _routeContext);
             }
             const state = this.options.actorManager()?.getState(relay.actorId);
-            if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send) {
+            if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send ||
+                frameHeader.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
                 const dispatch = state?.spotId === undefined
                     ? this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
                     : this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                if (frameHeader.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+                    await dispatch;
+                    return {
+                        ok: true,
+                        actorPacketTarget: (0, actor_packet_relay_wire_1.encodeRemoteActorPacketTarget)(this.actorPacketTargetForState(relay.actorId))
+                    };
+                }
                 // Spec 05 §1.3: a one-way Session Actor relay completes at relay
                 // queue admission, not after the remote application turn. In
                 // particular, a handler may register a deferred Join whose relocation
@@ -469,21 +445,14 @@ class ZLinkActorPacketRelay {
         }
         return true;
     }
-    async notifyRemoteActorDisconnected(actorId, remoteTarget, signal, bindingActorRef) {
+    async notifyRemoteActorDisconnected(actorId, remoteTarget, signal, bindingActorRef, binding) {
         const spotKind = 'spotKind' in remoteTarget ? remoteTarget.spotKind : undefined;
-        const header = {
-            kind: protocol_1.ZLinkStreamMessageKind.Send,
-            codec: protocol_1.ZLinkStreamCodec.Raw,
-            flags: protocol_1.ZLinkStreamHeaderFlags.None,
-            name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
-            metadata: new Map()
-        };
+        const frame = this.disconnectedFrame(actorId, binding, 'sessionNodeRid' in remoteTarget ? remoteTarget : undefined);
         const payload = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
             actorId,
             routerChannelId: remoteTarget.routerChannelId,
             bindingActorRef,
-            header: (0, protocol_1.encodeStreamHeader)(header),
-            payload: Buffer.alloc(0)
+            ...frame
         });
         if ((spotKind ?? contracts_1.ZLinkSpotKind.Entry) === contracts_1.ZLinkSpotKind.Entry) {
             await this.options.routeTransport.request(remoteTarget.routerChannelId, String(remoteTarget.targetNodeRid), actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, payload, this.options.requestTimeoutMs, signal);
@@ -500,18 +469,36 @@ class ZLinkActorPacketRelay {
             signal
         });
     }
+    disconnectedFrame(actorId, binding, target) {
+        const current = binding === undefined
+            ? (this.options.actorManager()?.getState(actorId)?.boundSession ?? target)
+            : undefined;
+        const header = {
+            kind: protocol_1.ZLinkStreamMessageKind.Send,
+            codec: protocol_1.ZLinkStreamCodec.Raw,
+            flags: protocol_1.ZLinkStreamHeaderFlags.None,
+            name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+            metadata: new Map()
+        };
+        return {
+            header: (0, protocol_1.encodeStreamHeader)(header),
+            payload: (0, session_disconnected_wire_1.encodeSessionDisconnected)(binding?.sessionOwnerNodeRid ?? current?.sessionNodeRid, binding?.sessionOwnerNodeGeneration ?? current?.sessionOwnerNodeGeneration, binding?.bindingGeneration ?? current?.bindingGeneration)
+        };
+    }
     requireCurrentRemoteBinding(relay, routeContext) {
-        const state = this.options.actorManager()?.getState(relay.actorId);
-        const current = state?.boundSession;
-        if (current === undefined ||
-            current.sessionNodeRid === undefined ||
-            !(0, routing_id_1.routingIdsEqual)(current.sessionNodeRid, routeContext.sourceNodeRid) ||
-            current.bindingGeneration === undefined ||
-            relay.bindingGeneration === undefined ||
-            current.bindingGeneration !== BigInt(relay.bindingGeneration)) {
+        if (!this.matchesCurrentRemoteBinding(relay, routeContext)) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${relay.actorId}' bound session identity is stale.`, true);
         }
     }
+    matchesCurrentRemoteBinding(relay, routeContext) {
+        const current = this.options.actorManager()?.getState(relay.actorId)?.boundSession;
+        return (current !== undefined &&
+            current.sessionNodeRid !== undefined &&
+            (0, routing_id_1.routingIdsEqual)(current.sessionNodeRid, routeContext.sourceNodeRid) &&
+            current.bindingGeneration !== undefined &&
+            relay.bindingGeneration !== undefined &&
+            current.bindingGeneration === BigInt(relay.bindingGeneration));
+    }
     async requestRemoteTarget(target, request, unavailableMessage, decodeReply, signal) {
         if (target.spotKind === contracts_1.ZLinkSpotKind.Entry) {
             try {

package/dist/runtime/host/actor-placement-coordinator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorPlacementCoordinator = void 0;
+const routing_id_1 = require("../routing-id");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const node_crypto_1 = require("node:crypto");
 const runtime_values_1 = require("../backend/runtime-values");
@@ -33,6 +34,13 @@ class ZLinkActorPlacementCoordinator {
             for (;;) {
                 const target = await this.options.target(meshName, stableType, deadline.signal, excluded);
                 if (target === undefined) {
+                    // Entry eligibility limits new creation, not lookup of a Ready Actor (Actor model §6.3, §6.5).
+                    if (!createOnly) {
+                        const current = await this.options.store.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', actorId), deadline.signal);
+                        const existing = existingActor(current, actorId, stableType);
+                        if (existing !== undefined)
+                            return { status: 'existing', actor: existing };
+                    }
                     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `No eligible Actor placement target is ready for '${stableType}'.`, true);
                 }
                 const creatingPayload = (0, actor_authority_publication_1.encodeActorAuthorityIdentity)({
@@ -75,7 +83,7 @@ class ZLinkActorPlacementCoordinator {
                     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorTypeMismatch, `Actor '${actorId}' is registered with another stable type.`);
                 }
                 if (reserved.kind === 'placementCapacityExhausted') {
-                    excluded.add(String(target.nodeRid));
+                    excluded.add((0, routing_id_1.encodeRoutingIdStorageHex)(target.nodeRid));
                     continue;
                 }
                 if (reserved.kind === 'alreadyExists' || reserved.kind === 'conflict') {
@@ -106,6 +114,13 @@ class ZLinkActorPlacementCoordinator {
                 }
                 if (remote === undefined)
                     throw transportFailure;
+                if ((0, framework_errors_internal_1.internalFrameworkErrorKindFromWireReply)(remote.terminalResult, remote.failureCode) ===
+                    framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected) {
+                    //  The target refused before the callback and cancelled its reservation
+                    //  (Actor model §6.3); exclude this host run like a Reserve failure.
+                    excluded.add((0, routing_id_1.encodeRoutingIdStorageHex)(target.nodeRid));
+                    continue;
+                }
                 if (remote.terminalResult !== runtime_values_1.RequestResult.Ok || remote.failureCode !== 0) {
                     //  Classify the (terminal, fine failure code) pair via the shared
                     //  ownership-aware translator instead of collapsing every non-OK
@@ -274,12 +289,14 @@ function creationTarget(snapshot) {
         }
     };
 }
-function existingActor(reserved, actorId, stableType) {
-    const snapshot = reserved.kind === 'alreadyExists'
-        ? reserved.current
-        : reserved.kind === 'conflict' && reserved.current.kind === 'snapshot'
-            ? reserved.current
-            : undefined;
+function existingActor(current, actorId, stableType) {
+    const snapshot = current.kind === 'snapshot'
+        ? current
+        : current.kind === 'alreadyExists'
+            ? current.current
+            : current.kind === 'conflict' && current.current.kind === 'snapshot'
+                ? current.current
+                : undefined;
     if (snapshot === undefined ||
         snapshot.allocation.state !== 'active' ||
         snapshot.allocation.objectKind !== 'actor' ||
@@ -348,7 +365,7 @@ function requireExactReservation(current, record) {
         current.allocation.stableType !== record.stableType ||
         current.objectGeneration !== record.reservation.objectGeneration ||
         current.authorityOwnerGeneration !== record.reservation.authorityOwnerGeneration ||
-        String(current.allocation.descriptor.rid) !== record.reservation.targetNodeRid ||
+        !(0, routing_id_1.routingIdsEqual)(current.allocation.descriptor.rid, record.reservation.targetNodeRid) ||
         current.allocation.descriptorLifecycleGeneration !== record.reservation.targetNodeGeneration ||
         current.ownerId !== record.reservation.targetOwnerId ||
         current.ownerLeaseGeneration !== record.reservation.targetOwnerLeaseGeneration ||