@zlink-systems/framework 0.30.1 → 0.30.2

package/dist/runtime/backend/node/node-raw-mesh-backend.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkNodeRawMeshBackend = void 0;
 exports.requestFailureResult = requestFailureResult;
+const routing_id_1 = require("../../routing-id");
 const durable_service_request_1 = require("../../foundation/durable-service-request");
+const routing_id_2 = require("../../routing-id");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const zlink_1 = require("@zlink-systems/zlink");
 const node_crypto_1 = require("node:crypto");
@@ -33,11 +35,13 @@ const DEFAULT_NATIVE_ACTIVE_CAPACITY = 10_000;
 const UNSTARTED_DIAGNOSTIC_ENDPOINT = 'inproc://not-started';
 const MULTIPART_PACKET_NAME = service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME;
 const MULTIPART_CONTENT_TYPE = service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE;
-const FATAL_UTF8 = new TextDecoder('utf-8', { fatal: true });
 const MAX_DRAIN_RECORDS = 64;
-// Preserve the existing route observation/admission/liveness cadence. Only the binding
-// readable handler admits receive work; this timer never probes the socket.
+// The maintenance timer runs at the nearest management deadline and never
+// sooner than this. Only the binding readable handler admits receive work;
+// this timer never probes the socket.
 const MESH_BACKEND_MAINTENANCE_INTERVAL_MS = 1;
+/** The longest single timer delay Node accepts. */
+const MESH_BACKEND_MAINTENANCE_MAX_DELAY_MS = 2 ** 31 - 1;
 // Spec 08 §4.2 bounds the combined turn. Raw gets one equal share; stateful
 // can use the remaining turn, including time the raw registry did not consume.
 const MESH_BACKEND_RAW_MAINTENANCE_SHARE = 1 / 2;
@@ -71,18 +75,19 @@ class ZLinkNodeRawMeshBackend {
     stateful;
     readyHandler;
     maintenanceTimer;
-    pumping = false;
+    maintenanceDueMs = Number.POSITIVE_INFINITY;
+    pumpTask;
     readable = 0;
     onReadable = (receiveReady, routeReady) => {
         if (receiveReady)
             this.readable |= 1;
         if (routeReady)
             this.readable |= 2;
-        if (!this.closed && !this.pumping)
-            void this.pump();
+        this.pump();
     };
     onMaintenance = () => {
         this.maintenanceTimer = undefined;
+        this.maintenanceDueMs = Number.POSITIVE_INFINITY;
         if (this.closed)
             return;
         const nowMs = performance.now();
@@ -90,7 +95,7 @@ class ZLinkNodeRawMeshBackend {
         this.runtime?.expireOperations(nowMs, nowMs + raw_service_mesh_runtime_1.RAW_MESH_RECEIVE_TIME_BUDGET_MS * MESH_BACKEND_RAW_MAINTENANCE_SHARE);
         this.stateful?.expireOperations(nowMs, turnDeadlineMs);
         this.scheduleMaintenance();
-        void this.pump();
+        this.pump();
     };
     onPendingOperationsChanged = () => this.scheduleMaintenance();
     nextPeerIntent = 1n;
@@ -105,6 +110,8 @@ class ZLinkNodeRawMeshBackend {
     protocolError;
     messageFollowHandler;
     dispatchErrors;
+    sessionOwnerDescriptors;
+    requestSourceAcceptance;
     peerDisconnectedHandlers = new Set();
     constructor(meshName, routingId, bindingPort, applicationJobQueue, applicationJobReceiveFlowFailureSink, peerAdmissionSealed, infrastructureTaskRunner) {
         this.meshName = meshName;
@@ -138,6 +145,10 @@ class ZLinkNodeRawMeshBackend {
         this.dispatchErrors = reporter;
         this.stateful?.setDispatchErrorReporter(reporter, this.meshName);
     }
+    setSessionOwnerDescriptors(source) {
+        this.sessionOwnerDescriptors = source;
+        this.stateful?.setSessionOwnerDescriptors(source);
+    }
     setProtocolErrorHandler(handler) {
         this.protocolError = handler;
     }
@@ -173,7 +184,7 @@ class ZLinkNodeRawMeshBackend {
         return this.observeStateful(service_runtime_contracts_1.OperationKind.InstanceSpotRequest, this.requireStateful().requestToMissingInstanceSpotFrame(target, encodeMultipartApplicationFrame(parts), deadlineUnixMs, sourceSpotId, metadata === undefined ? undefined : (0, service_metadata_codec_1.encodeServiceMetadataFrame)(metadata), onAdmitted));
     }
     setRoutingId(routingId) {
-        if (String(routingId) !== this.routingId) {
+        if (!(0, routing_id_1.routingIdsEqual)((0, routing_id_2.toBackendRoutingId)(routingId), this.routingId)) {
             throw new Error('MeshNode routing id is immutable after construction.');
         }
     }
@@ -232,16 +243,22 @@ class ZLinkNodeRawMeshBackend {
         if (this.dispatchErrors !== undefined) {
             this.stateful.setDispatchErrorReporter(this.dispatchErrors, this.meshName);
         }
+        if (this.sessionOwnerDescriptors !== undefined) {
+            this.stateful.setSessionOwnerDescriptors(this.sessionOwnerDescriptors);
+        }
         if (this.mailboxRecordDropped !== undefined) {
             this.stateful.setMailboxDropHandler(this.mailboxRecordDropped);
         }
         this.stateful.setMessageFollowHandler((record) => this.messageFollowHandler?.(record));
+        if (this.requestSourceAcceptance !== undefined) {
+            this.stateful.setRequestSourceAcceptance(this.requestSourceAcceptance);
+        }
         this.runtime = runtime;
         try {
             runtime.setReadableHandler(this.onReadable);
         }
         catch (error) {
-            this.close();
+            void this.close().catch((failure) => runtime.reportInfrastructureFailure(failure));
             throw error;
         }
         this.scheduleMaintenance();
@@ -252,26 +269,30 @@ class ZLinkNodeRawMeshBackend {
     async sendMessageFollowNotification(targetNodeRid, record) {
         return await this.requireStateful().sendMessageFollowNotification(targetNodeRid, record);
     }
-    shutdown(_timeoutMs) {
-        this.close();
+    async shutdown(_timeoutMs) {
+        await this.close();
         return zlink_1.RequestResult.Ok;
     }
+    cancelPendingOperations(reason) {
+        this.stateful?.cancelPendingOperations(reason);
+        this.runtime?.cancelPendingOperations(reason);
+    }
     async publishDraining() {
         for (const name of this.channels.keys())
             this.channels.set(name, 0);
         await this.requireRuntime().updateLocalDescriptor({ state: 'draining' });
     }
-    close() {
-        if (this.closed)
-            return;
+    async close() {
+        this.closed = true;
         if (this.maintenanceTimer !== undefined)
             clearTimeout(this.maintenanceTimer);
         this.maintenanceTimer = undefined;
+        if (this.pumpTask !== undefined)
+            await this.pumpTask;
         this.stateful?.close();
         this.stateful = undefined;
         this.runtime?.close();
         this.runtime = undefined;
-        this.closed = true;
     }
     addChannelName(name) {
         this.requireNotStarted();
@@ -323,6 +344,10 @@ class ZLinkNodeRawMeshBackend {
         });
         return intent;
     }
+    setRequestSourceAcceptance(acceptance) {
+        this.requestSourceAcceptance = acceptance;
+        this.stateful?.setRequestSourceAcceptance(acceptance);
+    }
     expectPeer(peer) {
         this.requireRuntime().expectPeerByRoutingId(peer.endpoint, peer.nodeRoutingId, peer.securityIdentity, peer.lifecycleGeneration);
     }
@@ -374,6 +399,9 @@ class ZLinkNodeRawMeshBackend {
     isObjectClientNodeDirectTarget(targetRid) {
         return this.requireRuntime().isObjectClientNodeDirectTarget(String(targetRid));
     }
+    waitForPeerRoute(targetRid, lifecycleGeneration, deadlineUnixMs, signal) {
+        return this.requireRuntime().waitForPeerRoute(String(targetRid), lifecycleGeneration, deadlineUnixMs, signal);
+    }
     observePeerRoute(targetRid) {
         return this.requireRuntime().observePeerRoute(String(targetRid));
     }
@@ -411,15 +439,15 @@ class ZLinkNodeRawMeshBackend {
         return (0, durable_service_request_1.requestDurableService)(this.requireRuntime(), String(targetRid), frames, performance.now() + (options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS), 'relocation control', options?.signal, options?.onSubmitted);
     }
     requestToNode(targetRid, parts, options) {
-        const pending = this.requireRuntime().requestToNode(String(targetRid), encodeMultipartApplicationFrame(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, options?.onAdmitted);
-        return this.observeCompletion(pending.id, service_runtime_contracts_1.OperationKind.NodeRequest, pending.promise);
+        const pending = this.requireRuntime().requestToNode(String(targetRid), encodeMultipartApplicationFrame(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, options?.onAdmitted, this.requestObserver, service_runtime_contracts_1.OperationKind.NodeRequest);
+        return this.observedOperation(pending, service_runtime_contracts_1.OperationKind.NodeRequest);
     }
     async sendToChannel(channelName, parts) {
         return this.requireRuntime().sendToChannel(channelName, encodeMultipartApplicationFrame(parts));
     }
     requestToChannel(channelName, parts, options) {
-        const pending = this.requireRuntime().requestToChannel(channelName, encodeMultipartApplicationFrame(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, options?.onAdmitted);
-        return this.observeCompletion(pending.id, service_runtime_contracts_1.OperationKind.ChannelRequest, pending.promise);
+        const pending = this.requireRuntime().requestToChannel(channelName, encodeMultipartApplicationFrame(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, options?.onAdmitted, this.requestObserver, service_runtime_contracts_1.OperationKind.ChannelRequest);
+        return this.observedOperation(pending, service_runtime_contracts_1.OperationKind.ChannelRequest);
     }
     status() {
         const descriptor = this.runtime?.topology.localDescriptor() ?? this.createDescriptor();
@@ -580,7 +608,8 @@ class ZLinkNodeRawMeshBackend {
         return this.requireStateful().instanceSpotApplicationTarget(spotId);
     }
     waitForInstanceApplicationQuiescence(spotId, signal) {
-        return this.requireStateful().waitForInstanceApplicationQuiescence(spotId, signal);
+        // Closing the stateful owner terminalizes its operations and clears these waiters.
+        return this.stateful?.waitForInstanceApplicationQuiescence(spotId, signal) ?? Promise.resolve();
     }
     restoreUserSpotAuthority(spotId, stableType, generation, authorityOwnerGeneration) {
         return new RawServiceSpot(this, this.requireStateful().restoreUserSpotAuthority(spotId, stableType, generation, authorityOwnerGeneration));
@@ -608,7 +637,7 @@ class ZLinkNodeRawMeshBackend {
             nodeRid: String(actor.nodeRid),
             actorId: actor.actorId,
             generation: actor.generation
-        }, String(sessionNodeRid), String(sessionRid), bindingGeneration);
+        }, String(sessionNodeRid), (0, routing_id_2.toBackendRoutingId)(sessionRid), bindingGeneration);
     }
     registerInstanceIntent(instanceType, route, expectedCurrentRoute) {
         this.requireStateful().registerInstanceIntent(instanceType, route, expectedCurrentRoute);
@@ -713,27 +742,26 @@ class ZLinkNodeRawMeshBackend {
         const target = String(targetNodeRid);
         return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorJoin, this.requireStateful().joinActorEntrySpotCanonical(actor, target, request, actorFence, local, timeoutMs));
     }
-    async sendToActor(actor, parts) {
-        return this.requireStateful().sendToActor(actor, this.peerGeneration(String(actor.nodeRid)), actor.generation, encodeMultipart(parts));
+    async sendToActor(actor, parts, options) {
+        return this.requireStateful().sendToActor(actor, encodeMultipart(parts), undefined, undefined, options?.routeFence);
     }
     requestToActor(actor, parts, options) {
-        return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorRequest, this.requireStateful().requestToActor(actor, this.peerGeneration(String(actor.nodeRid)), actor.generation, encodeMultipart(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, undefined, undefined, options?.onAdmitted));
+        return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorRequest, this.requireStateful().requestToActor(actor, encodeMultipart(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, undefined, undefined, options?.onAdmitted, options?.routeFence));
+    }
+    acceptRelocatedActorTerminal(operation, replyRouteId, result) {
+        return this.requireStateful().acceptRelocatedActorTerminal(operation, replyRouteId, result);
     }
     async actorSendToActor(source, target, parts) {
-        return (await this.requireStateful().sendToActor(target, this.peerGeneration(String(target.nodeRid)), target.generation, encodeMultipart(parts), source));
+        return (await this.requireStateful().sendToActor(target, encodeMultipart(parts), source));
     }
     actorRequestToActor(source, target, parts, options) {
-        return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorRequest, this.requireStateful().requestToActor(target, this.peerGeneration(String(target.nodeRid)), target.generation, encodeMultipart(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, source, undefined, options?.onAdmitted));
+        return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorRequest, this.requireStateful().requestToActor(target, encodeMultipart(parts), options?.timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, source, undefined, options?.onAdmitted));
     }
     async sendActorBoundSession(actor, expectedBindingGeneration, parts, _flags) {
         return (await this.requireStateful().sendBoundSession(actor, expectedBindingGeneration, encodeMultipart(parts)));
     }
     closeActorBoundSession(actor, expectedBindingGeneration, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS) {
-        const binding = this.requireStateful().registry.binding(actor);
-        if (binding === undefined) {
-            return this.observeImmediateFailure(service_runtime_contracts_1.OperationKind.StreamUnbind, zlink_1.RequestResult.NotFound);
-        }
-        return this.observeStateful(service_runtime_contracts_1.OperationKind.StreamUnbind, this.requireStateful().unbindSession(binding.sessionRid, actor, expectedBindingGeneration, timeoutMs));
+        return this.observeStateful(service_runtime_contracts_1.OperationKind.StreamUnbind, this.requireStateful().closeBoundSession(actor, expectedBindingGeneration, timeoutMs));
     }
     leaveActor(actor, expectedMembershipEpoch, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS) {
         return this.observeStateful(service_runtime_contracts_1.OperationKind.ActorLeave, this.requireStateful().leaveActor(actor, expectedMembershipEpoch, timeoutMs));
@@ -796,10 +824,29 @@ class ZLinkNodeRawMeshBackend {
         }
         return result;
     }
+    /**
+     * Arms the one maintenance timer for the nearest management deadline
+     * (spec 08 §4.2): request expiry, liveness, or a pending peer handshake.
+     * An earlier deadline re-arms it; a later one keeps the armed time.
+     */
     scheduleMaintenance() {
         if (this.closed)
             return;
-        this.maintenanceTimer ??= setTimeout(this.onMaintenance, MESH_BACKEND_MAINTENANCE_INTERVAL_MS);
+        const nowMs = performance.now();
+        const dueMs = Math.max(nowMs + MESH_BACKEND_MAINTENANCE_INTERVAL_MS, Math.min(this.runtime?.nextMaintenanceDeadlineMs(nowMs) ?? Number.POSITIVE_INFINITY, this.stateful?.nextMaintenanceDeadlineMs() ?? Number.POSITIVE_INFINITY));
+        if (dueMs === Number.POSITIVE_INFINITY) {
+            if (this.maintenanceTimer !== undefined)
+                clearTimeout(this.maintenanceTimer);
+            this.maintenanceTimer = undefined;
+            this.maintenanceDueMs = dueMs;
+            return;
+        }
+        if (this.maintenanceTimer === undefined || dueMs < this.maintenanceDueMs) {
+            if (this.maintenanceTimer !== undefined)
+                clearTimeout(this.maintenanceTimer);
+            this.maintenanceTimer = setTimeout(this.onMaintenance, Math.min(MESH_BACKEND_MAINTENANCE_MAX_DELAY_MS, Math.ceil(dueMs - nowMs)));
+            this.maintenanceDueMs = dueMs;
+        }
         const pending = (this.runtime?.pendingOperationCount ?? 0) + (this.stateful?.pendingOperationCount ?? 0) > 0;
         if (pending === this.maintenanceTimer.hasRef())
             return;
@@ -810,15 +857,19 @@ class ZLinkNodeRawMeshBackend {
             this.maintenanceTimer.unref();
         }
     }
-    async pump() {
-        if (this.isClosed() || this.pumping)
+    pump() {
+        if (this.closed || this.pumpTask !== undefined)
             return;
-        this.pumping = true;
+        this.pumpTask = this.runPump(this.requireRuntime());
+    }
+    async runPump(runtime) {
+        // Publish pumpTask before any callback can signal readiness or begin close.
+        await Promise.resolve();
         try {
             do {
                 const ready = this.readable;
                 this.readable = 0;
-                const more = await this.requireRuntime().pumpBatch((ready & 1) !== 0, (ready & 2) !== 0);
+                const more = await runtime.pumpBatch((ready & 1) !== 0, (ready & 2) !== 0);
                 if (more) {
                     // Yield only after actual progress, retaining readiness across the
                     // existing batch limits until receive reports no data.
@@ -827,14 +878,14 @@ class ZLinkNodeRawMeshBackend {
                 }
             } while (!this.closed && this.readable !== 0);
         }
+        catch (error) {
+            runtime.reportInfrastructureFailure(error);
+        }
         finally {
-            this.pumping = false;
+            this.pumpTask = undefined;
             this.scheduleMaintenance();
         }
     }
-    isClosed() {
-        return this.closed;
-    }
     notifyReady() {
         const runtime = this.runtime;
         let domains = service_runtime_contracts_1.ReadyDomain.None;
@@ -847,6 +898,19 @@ class ZLinkNodeRawMeshBackend {
         if (domains !== service_runtime_contracts_1.ReadyDomain.None)
             this.readyHandler?.(domains);
     }
+    /**
+     * The raw registry takes a remote request's terminal and hands it here,
+     * where the Framework completion owner receives it in the same turn.
+     */
+    requestObserver = {
+        operationCompleted: (id, result, operationKind) => this.deliverCompletion({ high: 1n, low: id }, operationKind ?? 0, result),
+        operationFailed: (id, error, operationKind) => this.deliverCompletion({ high: 1n, low: id }, operationKind ?? 0, requestFailureResult(error))
+    };
+    observedOperation(pending, operationKind) {
+        return pending.promise === undefined
+            ? { high: 1n, low: pending.id }
+            : this.observeCompletion(pending.id, operationKind, pending.promise);
+    }
     observeCompletion(low, operationKind, promise) {
         const id = { high: 1n, low };
         void promise.then((result) => this.deliverCompletion(id, operationKind, result), (error) => this.deliverCompletion(id, operationKind, requestFailureResult(error)));
@@ -857,10 +921,6 @@ class ZLinkNodeRawMeshBackend {
         void pending.promise.then((result) => this.deliverCompletion(id, operationKind, result), (error) => this.deliverCompletion(id, operationKind, requestFailureResult(error)));
         return id;
     }
-    observeImmediateFailure(operationKind, terminalResult) {
-        const low = this.nextPeerIntent++;
-        return this.observeCompletion(low, operationKind, Promise.resolve({ terminalResult, failureCode: 0 }));
-    }
     deliverCompletion(operationId, operationKind, result) {
         if (this.completionHandler !== undefined) {
             this.completionHandler({ operationId, terminalResult: result.terminalResult }, () => completionRecord(operationId, operationKind, result));
@@ -1055,7 +1115,7 @@ class RawStreamSessionService {
         return {
             state: this.state,
             lifecycleGeneration: 1n,
-            sessionCount: BigInt(new Set(bindings.map((value) => value.sessionRid)).size),
+            sessionCount: BigInt(new Set(bindings.map((value) => (0, routing_id_2.encodeRoutingIdStorageHex)(value.sessionRid))).size),
             bindingCount: BigInt(bindings.length),
             pendingMessageCount: 0n,
             pendingByteCount: 0n,
@@ -1066,32 +1126,32 @@ class RawStreamSessionService {
         this.requireStarted();
         return this.observe(service_runtime_contracts_1.OperationKind.ActorLookup, this.stateful.lookupRemoteActor(String(targetNodeRid), actorId, timeoutMs));
     }
-    bindActor(sessionRid, actor, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, onBindingReplaced, actorAuthority) {
+    bindActor(sessionRid, actor, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, onBindingReplaced, actorAuthority, close) {
         this.requireStarted();
         const sessionKey = String(sessionRid);
         this.sessionTargets.set(sessionKey, sessionRid);
-        return this.observe(service_runtime_contracts_1.OperationKind.StreamBind, this.stateful.bindSession(sessionKey, actor, timeoutMs, (targetSessionRid, payloadFrame) => this.deliver(targetSessionRid, actor.actorId, payloadFrame), onBindingReplaced, actorAuthority));
+        return this.observe(service_runtime_contracts_1.OperationKind.StreamBind, this.stateful.bindSession(sessionRid, actor, timeoutMs, (_targetSessionRid, payloadFrame) => this.deliver(sessionKey, actor.actorId, payloadFrame), onBindingReplaced, actorAuthority, close));
     }
     unbindActor(sessionRid, actor, expectedBindingGeneration, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS) {
         this.requireStarted();
-        return this.observe(service_runtime_contracts_1.OperationKind.StreamUnbind, this.stateful.unbindSession(String(sessionRid), actor, expectedBindingGeneration, timeoutMs));
+        return this.observe(service_runtime_contracts_1.OperationKind.StreamUnbind, this.stateful.unbindSession(sessionRid, actor, expectedBindingGeneration, timeoutMs));
     }
     bindings(sessionRid) {
-        return this.stateful.sessionBindings(String(sessionRid));
+        return this.stateful.sessionBindings(sessionRid);
     }
     async sendToActor(sessionRid, actor, parts) {
         this.requireStarted();
-        return (await this.stateful.sendSessionToActor(String(sessionRid), actor, encodeMultipart(parts)));
+        return (await this.stateful.sendSessionToActor(sessionRid, actor, encodeMultipart(parts)));
     }
     async deliver(sessionRid, actorId, payload) {
         const target = this.sessionTargets.get(sessionRid);
         if (target === undefined)
             return false;
         const operation = this.stream.send(target);
-        const parts = decodeMultipartParts((0, service_wire_m6a_codec_1.decodeApplicationPayloadView)(payload).payload, borrowMultipartPart);
+        const parts = (0, service_wire_m6a_codec_1.decodeMultipartParts)((0, service_wire_m6a_codec_1.decodeApplicationPayloadView)(payload).payload, borrowMultipartPart);
         if (parts.length === 0)
             return false;
-        const actorSlot = await (0, service_session_binding_ingress_port_1.serviceSessionBindingIngressPortIfRegistered)(this)?.actorSlot(actorId, sessionRid);
+        const actorSlot = await (0, service_session_binding_ingress_port_1.serviceSessionBindingIngressPortIfRegistered)(this)?.actorSlot(actorId, target);
         if (actorSlot === undefined)
             return false;
         parts[0] = Buffer.from(streamFrameWithActorSlot(parts[0], actorSlot));
@@ -1112,7 +1172,7 @@ class RawStreamSessionService {
                 case zlink_1.SubmitResult.Terminated:
                     // Let the socket monitor drive the existing STREAM close/unbind
                     // lifecycle instead of maintaining a second session-close state.
-                    (0, node_socket_backend_adapter_1.disconnectStreamPeer)(this.stream, target);
+                    (0, node_socket_backend_adapter_1.disconnectSocketPeer)(this.stream, (0, node_backend_adapter_support_1.toNativeRoutingId)(target));
                     throw new runtime_values_1.ZLinkBackendResultError('submit', error.result, error.nativeErrno, {
                         cause: error
                     });
@@ -1340,7 +1400,7 @@ function decodeMultipartRecord(runtime, record) {
     const header = record.parts[0];
     const command = header[service_wire_binary_primitives_1.SERVICE_WIRE_COMMAND_OFFSET];
     const payloadFrame = record.parts[1];
-    const application = decodeApplicationEnvelope(payloadFrame);
+    const parts = (0, service_wire_m6a_codec_1.decodeMultipartApplicationParts)(payloadFrame, runtime_message_1.ZLinkBufferMessage.fromOwned, closeMultipartMessage);
     const channelName = record.owner.startsWith('channel:')
         ? record.owner.slice('channel:'.length)
         : null;
@@ -1359,7 +1419,7 @@ function decodeMultipartRecord(runtime, record) {
         : kind === service_runtime_contracts_1.ReceiveKind.ChannelRequest
             ? service_runtime_contracts_1.OperationKind.ChannelRequest
             : 0;
-    const ingressLifecycle = receiveIngressLifecycle(record);
+    const applicationJob = record.applicationJob;
     return {
         kind,
         domain: readyDomain(record.domain),
@@ -1372,22 +1432,30 @@ function decodeMultipartRecord(runtime, record) {
         channelName,
         topic: null,
         applicationMetadata: null,
-        packetName: application.packetName,
-        contentType: application.contentType,
+        packetName: service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME,
+        contentType: service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE,
         kindData: null,
         terminalResult: 0,
         failureErrno: 0,
-        ...ingressLifecycle,
-        parts: decodeMultipart(application.payload),
+        applicationJobPermit: applicationJob,
+        releaseRetainedIngress: applicationJob === undefined ? undefined : releaseRecordApplicationJob,
+        parts,
         reply(parts) {
             if (record.correlation === undefined)
                 return zlink_1.SubmitResult.InvalidState;
             runtime.reply(record, encodeMultipartApplicationFrame(parts));
             return zlink_1.SubmitResult.Ok;
         },
-        replyActorJoin: () => zlink_1.SubmitResult.NotSupported
+        replyActorJoin: replyActorJoinNotSupported
     };
 }
+/** Shared by every ordinary record: the record's own permit lease is its retained ingress. */
+function releaseRecordApplicationJob() {
+    this.applicationJobPermit?.close();
+}
+function replyActorJoinNotSupported() {
+    return zlink_1.SubmitResult.NotSupported;
+}
 function decodeStatefulRecord(record, stateful) {
     const payloadFrame = record.parts.length < 2 ? undefined : record.parts[1];
     const canonicalActorJoin = stateful.kindData?.kind === 'actorControl' &&
@@ -1398,13 +1466,18 @@ function decodeStatefulRecord(record, stateful) {
         ? stateful.canonicalApplicationPayload
         : payloadFrame === undefined
             ? undefined
-            : decodeApplicationEnvelope(payloadFrame);
+            : (0, service_wire_m6a_codec_1.decodeMultipartApplicationPayloadView)(payloadFrame);
     const operationId = record.correlation === undefined
         ? { high: 0n, low: 0n }
         : { high: operation_identity_1.ZLINK_NATIVE_CORRELATION_OPERATION_NAMESPACE, low: record.correlation };
     const ingressLifecycle = receiveIngressLifecycle(record);
     return {
         kind: stateful.receiveKind,
+        get requestSource() {
+            return record.requestSource;
+        },
+        prepareDispatch: record.sourcePreparationOwner === undefined ? undefined : prepareStatefulMailboxDispatch,
+        statefulMailboxRecord: record,
         domain: readyDomain(record.domain),
         sourceNodeRid: record.sourceRoutingId ?? null,
         sourceSpotId: stateful.sourceSpotId ?? null,
@@ -1498,6 +1571,13 @@ function receiveIngressLifecycle(record) {
             releaseRetainedIngress: () => applicationJob.close()
         };
 }
+function prepareStatefulMailboxDispatch(signal) {
+    const mailboxRecord = this.statefulMailboxRecord;
+    const owner = mailboxRecord?.sourcePreparationOwner;
+    return mailboxRecord === undefined || owner === undefined
+        ? true
+        : owner.prepareDispatch(mailboxRecord, signal);
+}
 function readyOwner(owner, nodeRid, stateful, domain) {
     if (owner.startsWith('spot:')) {
         return {
@@ -1607,52 +1687,8 @@ function encodeMultipartApplicationFrame(parts) {
         throw new TypeError('Multipart payload must contain at least one part.');
     return (0, service_wire_m6a_codec_1.encodeMultipartApplicationPayload)(values.map(messageBytesView), MULTIPART_PACKET_NAME, MULTIPART_CONTENT_TYPE);
 }
-function decodeApplicationEnvelope(frame) {
-    const bytes = Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength);
-    if (bytes.length < service_wire_m6a_codec_1.APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES ||
-        bytes[0] !== service_wire_m6a_codec_1.APPLICATION_PAYLOAD_VERSION) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope.');
-    }
-    const bodyLength = bytes.readUInt32BE(1);
-    if (bodyLength !== bytes.length - 5) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope length.');
-    }
-    let offset = 5;
-    const packetLength = bytes[offset++];
-    if (packetLength === 0 || bytes.length - offset < packetLength + 1) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope packet name.');
-    }
-    let packetName;
-    try {
-        packetName = FATAL_UTF8.decode(bytes.subarray(offset, offset + packetLength));
-    }
-    catch {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope packet name.');
-    }
-    offset += packetLength;
-    const contentLength = bytes[offset++];
-    if (contentLength === 0 || bytes.length - offset < contentLength + 4) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope content type.');
-    }
-    let contentType;
-    try {
-        contentType = FATAL_UTF8.decode(bytes.subarray(offset, offset + contentLength));
-    }
-    catch {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid application envelope content type.');
-    }
-    offset += contentLength;
-    const payloadLength = bytes.readUInt32BE(offset);
-    offset += 4;
-    if (packetName !== MULTIPART_PACKET_NAME ||
-        contentType !== MULTIPART_CONTENT_TYPE ||
-        payloadLength !== bytes.length - offset) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Unexpected M6A application payload.');
-    }
-    return { packetName, contentType, payload: bytes.subarray(offset) };
-}
 function decodeMultipart(payload) {
-    return decodeMultipartParts(payload, runtime_message_1.ZLinkBufferMessage.fromOwned, closeMultipartMessage);
+    return (0, service_wire_m6a_codec_1.decodeMultipartParts)(payload, runtime_message_1.ZLinkBufferMessage.fromOwned, closeMultipartMessage);
 }
 function closeMultipartMessage(part) {
     part.close();
@@ -1660,43 +1696,6 @@ function closeMultipartMessage(part) {
 function borrowMultipartPart(part) {
     return part;
 }
-function decodeMultipartParts(payload, materialize, release) {
-    const bytes = Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
-    if (bytes.length < 4)
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Truncated multipart payload.');
-    const count = bytes.readUInt32BE(0);
-    if (count === 0 || count > Math.floor((bytes.length - 4) / 4)) {
-        throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Invalid multipart part count.');
-    }
-    const result = new Array(count);
-    let offset = 4;
-    let index = 0;
-    try {
-        for (; index < count; index++) {
-            if (bytes.length - offset < 4) {
-                throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Truncated multipart part length.');
-            }
-            const length = bytes.readUInt32BE(offset);
-            offset += 4;
-            if (bytes.length - offset < length) {
-                throw new service_wire_m6a_codec_1.ServiceWireProtocolError('Truncated multipart part.');
-            }
-            result[index] = materialize(bytes.subarray(offset, offset + length));
-            offset += length;
-        }
-        if (offset !== bytes.length) {
-            throw new service_wire_m6a_codec_1.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;
-    }
-}
 function messageBytesView(value) {
     if (typeof value === 'object' && 'data' in value) {
         return value.data();

package/dist/runtime/backend/node/node-socket-backend-adapter.d.ts

@@ -4,7 +4,7 @@ export declare function wrapSocket<T extends {
     close(): void;
 }>(nativeInstance: T, pollCompletion?: boolean): T & ZLinkBackendObject;
 export declare function nodeEventLoopPollerOf(socket: object): ZLinkNodeEventLoopPoller;
-export declare function disconnectStreamPeer(socket: {
+export declare function disconnectSocketPeer(socket: {
     disconnectRid(routingId: unknown): void;
 }, routingId: unknown): void;
 export declare function isEndpointCloseIgnorableError(error: unknown): boolean;

package/dist/runtime/backend/node/node-socket-backend-adapter.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapSocket = wrapSocket;
 exports.nodeEventLoopPollerOf = nodeEventLoopPollerOf;
-exports.disconnectStreamPeer = disconnectStreamPeer;
+exports.disconnectSocketPeer = disconnectSocketPeer;
 exports.isEndpointCloseIgnorableError = isEndpointCloseIgnorableError;
 const RegistrationBuilderPolicy_1 = require("../../../contracts/Configuration/RegistrationBuilderPolicy");
 const node_backend_adapter_support_1 = require("./node-backend-adapter-support");
@@ -205,7 +205,7 @@ function wrapSocket(nativeInstance, pollCompletion) {
             return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.requestToSpot((0, node_backend_adapter_support_1.toNativeRoutingId)(targetRid), (0, node_backend_adapter_support_1.toNativeRoutingId)(targetSpot)), payload, timeoutMs, undefined, onAdmitted);
         },
         disconnectPeer(routingId) {
-            disconnectStreamPeer(nativeInstance, routingId);
+            disconnectSocketPeer(nativeInstance, (0, node_backend_adapter_support_1.toNativeRoutingId)(routingId));
         },
         async bindActor(_sessionRid, _actor, _timeoutMs, _signal) {
             throw new Error('Session Actor dispatch requires enableActorDispatch() and a Framework MeshNode service route.');
@@ -228,13 +228,13 @@ function nodeEventLoopPollerOf(socket) {
     }
     return poller;
 }
-function disconnectStreamPeer(socket, routingId) {
+function disconnectSocketPeer(socket, routingId) {
     try {
-        socket.disconnectRid((0, node_backend_adapter_support_1.toNativeRoutingId)(routingId));
+        socket.disconnectRid(routingId);
     }
     catch (error) {
         // An absent RID has already completed the physical close. The existing
-        // session lifecycle still owns local cleanup and unbind.
+        // logical lifecycle still owns local cleanup and unbind.
         if (!(0, node_backend_adapter_support_1.isBindingNotFound)(error))
             throw error;
     }

package/dist/runtime/channels/channel-clients.d.ts

@@ -36,6 +36,7 @@ export declare class DefaultZLinkRouteClient implements ZLinkRouteClient {
     private readonly spotRouterChannelIdForMesh;
     private readonly channelTransport?;
     private readonly nodeSends;
+    private readonly nodeRequests;
     constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkRouteClientTransport | undefined, spotRouterChannelIdForMesh?: (meshName: string) => string, channelTransport?: ZLinkChannelClientTransportSource | undefined);
     sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall;
     requestToNode(meshName: string, targetNodeRid: string, request: unknown): ZLinkRequestCall;