@zlink-systems/framework 0.22.0 → 0.23.0

package/dist/runtime/streams/actor-session-binding-registry.js

@@ -1,18 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkActorSessionBindingRegistry = void 0;
+exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionBindingTermination = void 0;
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const abort_1 = require("../abort");
 const node_async_hooks_1 = require("node:async_hooks");
 const state_lane_1 = require("../execution/state-lane");
 const routing_id_1 = require("../routing-id");
 const detachedStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:actor-session-binding-registry');
+var ZLinkActorSessionBindingTermination;
+(function (ZLinkActorSessionBindingTermination) {
+    ZLinkActorSessionBindingTermination[ZLinkActorSessionBindingTermination["BindingEnd"] = 0] = "BindingEnd";
+    ZLinkActorSessionBindingTermination[ZLinkActorSessionBindingTermination["PhysicalDisconnect"] = 1] = "PhysicalDisconnect";
+})(ZLinkActorSessionBindingTermination || (exports.ZLinkActorSessionBindingTermination = ZLinkActorSessionBindingTermination = {}));
 class ZLinkActorSessionBindingRegistry {
     terminalRelocationCapacity;
     outboundCapacity;
     sealWaitTimeoutMs;
+    errorSink;
     lane = new state_lane_1.ZLinkStateLane();
     routes = new Map();
+    nextActorSlots = new WeakMap();
     sealWaiters = new Map();
     activeFrameWaiters = new Map();
     relocations = new Map();
@@ -24,10 +31,11 @@ class ZLinkActorSessionBindingRegistry {
     //  (the sealing side) must observe that bound; an unbounded wait here
     //  turns a lost control or a lifecycle interlock into a silent stall
     //  (spec 48:205 — transport/deadline limits apply during relocation).
-    sealWaitTimeoutMs = 3_000) {
+    sealWaitTimeoutMs = 3_000, errorSink) {
         this.terminalRelocationCapacity = terminalRelocationCapacity;
         this.outboundCapacity = outboundCapacity;
         this.sealWaitTimeoutMs = sealWaitTimeoutMs;
+        this.errorSink = errorSink;
         if (!Number.isSafeInteger(terminalRelocationCapacity) || terminalRelocationCapacity <= 0) {
             throw new RangeError('Session relocation terminal capacity must be a positive safe integer.');
         }
@@ -38,61 +46,78 @@ class ZLinkActorSessionBindingRegistry {
             throw new RangeError('Session relocation seal timeout must be a positive safe integer.');
         }
     }
-    async bind(context, actor, bindingToken, authorityFence, sessionIdentity) {
-        await this.lane.run(() => this.bindCore(context, actor, bindingToken, authorityFence, sessionIdentity));
+    async bind(context, actor, bindingToken, authorityFence, sessionIdentity, commitActor) {
+        await this.lane.run(() => this.commitCore(undefined, context, actor, bindingToken, authorityFence, sessionIdentity, commitActor));
     }
-    bindCore(context, actor, bindingToken, authorityFence, sessionIdentity) {
-        this.routes.set(actor.actorId, {
-            context,
-            actor,
-            bindingToken,
-            sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
-            activeFrames: { count: 0, requests: new Set() },
-            authorityFence
-        });
-        context.bindLocal(actor, bindingToken);
-    }
-    async replace(previous, context, actor, bindingToken, authorityFence, sessionIdentity) {
-        await this.lane.run(() => this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity));
-    }
-    replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity) {
+    async commitCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity, commitActor) {
         const current = this.routes.get(actor.actorId);
         if (current !== previous) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actor.actorId}' session binding changed before route replacement.`, true);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actor.actorId}' session binding changed before route commit.`, true);
         }
-        context.bindLocal(actor, bindingToken);
-        const sameLocalBinding = previous.context === context && previous.bindingToken === bindingToken;
-        if (!sameLocalBinding) {
-            try {
+        const sameBinding = previous !== undefined &&
+            previous.context === context &&
+            previous.bindingToken === bindingToken;
+        const actorSlot = sameBinding ? previous.actorSlot : this.issueActorSlot(context);
+        commitActor?.();
+        context.bindLocal(actor, bindingToken, actorSlot);
+        try {
+            if (previous !== undefined && !sameBinding) {
+                this.routes.delete(actor.actorId);
                 previous.context.unbindLocal(actor.actorId, previous.bindingToken);
+                if (previous.actorSlot !== undefined) {
+                    let unbound;
+                    try {
+                        unbound = previous.context.actorSlotControls?.enqueueUnbound(previous.actorSlot);
+                    }
+                    catch (error) {
+                        unbound = Promise.reject(error);
+                    }
+                    void unbound?.catch((error) => this.errorSink?.()?.reportRuntimeTaskException('retired session actor unbound', error));
+                }
             }
-            catch (error) {
-                context.unbindLocal(actor.actorId, bindingToken);
-                previous.context.bindLocal(previous.actor, previous.bindingToken);
-                throw error;
+            if (!sameBinding && actorSlot !== undefined) {
+                await context.actorSlotControls.enqueueBound(actorSlot, actor.actorId);
             }
         }
+        catch (error) {
+            context.unbindLocal(actor.actorId, bindingToken);
+            throw error;
+        }
         this.routes.set(actor.actorId, {
             context,
             actor,
             bindingToken,
+            actorSlot,
             sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
-            activeFrames: previous.activeFrames,
-            sealId: previous.sealId,
-            authorityFence: authorityFence ?? previous.authorityFence
+            activeFrames: previous?.activeFrames ?? { count: 0, requests: new Set() },
+            sealId: previous?.sealId,
+            authorityFence: authorityFence ?? previous?.authorityFence
         });
     }
-    async replaceAndReleaseSeal(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity) {
-        await this.lane.run(() => this.replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity));
+    issueActorSlot(context) {
+        if (context.actorSlotControls === undefined)
+            return undefined;
+        const actorSlot = this.nextActorSlots.get(context) ?? 1;
+        if (actorSlot > 0xffff) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Stream session '${String(context.routingId)}' exhausted its Actor slots.`);
+        }
+        this.nextActorSlots.set(context, actorSlot + 1);
+        return actorSlot;
+    }
+    async replace(previous, context, actor, bindingToken, authorityFence, sessionIdentity, commitActor) {
+        await this.lane.run(() => this.commitCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity, commitActor));
     }
-    replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity) {
+    async replaceAndReleaseSeal(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity, commitActor) {
+        await this.lane.run(() => this.replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity, commitActor));
+    }
+    async replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity, commitActor) {
         if (previous.sealId !== sealId) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actor.actorId}' route switch did not match its relocation seal.`, true);
         }
         // JavaScript cannot interleave another ingress turn between these two
         // synchronous mutations. The replacement preserves the seal, then the
         // exact release publishes the route to held ingress as one owner turn.
-        this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity);
+        await this.commitCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity, commitActor);
         if (!this.abortSealCore(actor.actorId, sealId)) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actor.actorId}' route switch lost its relocation seal.`, true);
         }
@@ -119,10 +144,10 @@ class ZLinkActorSessionBindingRegistry {
         }
         return Object.freeze({ context: route.context });
     }
-    async unbind(actorId, context, bindingToken) {
-        await this.lane.run(() => this.unbindCore(actorId, context, bindingToken));
+    async unbind(actorId, context, bindingToken, termination = ZLinkActorSessionBindingTermination.BindingEnd) {
+        await this.lane.run(() => this.unbindCore(actorId, context, bindingToken, termination));
     }
-    unbindCore(actorId, context, bindingToken) {
+    async unbindCore(actorId, context, bindingToken, termination) {
         const route = this.routes.get(actorId);
         if (route === undefined || route.context !== context || route.bindingToken !== bindingToken) {
             return;
@@ -132,24 +157,28 @@ class ZLinkActorSessionBindingRegistry {
         this.rejectSealWaiters(actorId, new Error(`Actor '${actorId}' session binding was removed while ingress was held.`));
         this.rejectActiveFrameWaiters(actorId, new Error(`Actor '${actorId}' session binding was removed while accepted frames were active.`));
         this.clearRouteRelocation(actorId, route, new Error(`Actor '${actorId}' session binding was removed.`));
+        if (termination === ZLinkActorSessionBindingTermination.BindingEnd &&
+            route.actorSlot !== undefined) {
+            await context.actorSlotControls?.enqueueUnbound(route.actorSlot);
+        }
     }
     async unbindActor(actorId) {
         await this.lane.run(() => this.unbindActorCore(actorId));
     }
-    unbindActorCore(actorId) {
+    async unbindActorCore(actorId) {
         const route = this.routes.get(actorId);
         if (route === undefined) {
             return;
         }
-        this.unbindCore(actorId, route.context, route.bindingToken);
+        await this.unbindCore(actorId, route.context, route.bindingToken, ZLinkActorSessionBindingTermination.BindingEnd);
     }
     async cleanup(context) {
         await this.lane.run(() => this.cleanupCore(context));
     }
-    cleanupCore(context) {
+    async cleanupCore(context) {
         for (const route of [...this.routes.values()]) {
             if (route.context === context) {
-                this.unbindCore(route.actor.actorId, context, route.bindingToken);
+                await this.unbindCore(route.actor.actorId, context, route.bindingToken, ZLinkActorSessionBindingTermination.PhysicalDisconnect);
             }
         }
     }

package/dist/runtime/streams/actor-session-binding-runtime-owner.d.ts

@@ -2,6 +2,7 @@ import type { ActorRef } from '../../contracts';
 import type { ServiceSessionBindingAdmissionClaim, ServiceSessionBindingAdmissionResult } from '../foundation/service-session-binding-ingress-port';
 import type { ZLinkActorSessionAuthorityFence, ZLinkActorSessionAcceptedProducerProof, ZLinkActorSessionRelocationClaim, ZLinkActorSessionRelocationSnapshot, ZLinkActorSessionRetainedOutbound, ZLinkActorSessionRouteFence } from './actor-session-binding-registry';
 export interface ZLinkActorSessionBindingRuntimeOwner {
+    actorSlot(actorId: string, sessionRid: string): Promise<number | undefined>;
     sealRelocation(claim: ZLinkActorSessionRelocationClaim, expected: ZLinkActorSessionRouteFence, signal?: AbortSignal): Promise<void>;
     relocationSnapshot(actorId: string, sealId: string): Promise<ZLinkActorSessionRelocationSnapshot | undefined>;
     retainRelocationOutbound(actorId: string, operation: ZLinkActorSessionRetainedOutbound, sealId?: string): Promise<ServiceSessionBindingAdmissionResult>;

package/dist/runtime/streams/bound-actor-relay-sender.js

@@ -6,6 +6,7 @@ const payload_codec_1 = require("../messaging/payload-codec");
 const protocol_1 = require("./protocol");
 const abort_1 = require("../abort");
 const execution_1 = require("../execution");
+const actor_session_binding_registry_1 = require("./actor-session-binding-registry");
 const actor_session_lifecycle_coordinator_1 = require("./actor-session-lifecycle-coordinator");
 const managed_stream_1 = require("./managed-stream");
 class ZLinkBoundActorRelaySender {
@@ -159,7 +160,7 @@ class ZLinkBoundActorRelaySender {
                 // The transport is already closed, so remove its exact route before
                 // invoking application lifecycle code. A reconnect can then install
                 // a successor while this best-effort notification is in flight.
-                await this.routes.unbind(actor.actorId, context, actor.bindingToken);
+                await this.routes.unbind(actor.actorId, context, actor.bindingToken, actor_session_binding_registry_1.ZLinkActorSessionBindingTermination.PhysicalDisconnect);
                 return true;
             });
             if (!detached)

package/dist/runtime/streams/bound-session-response-target.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkBoundSessionResponseTarget = void 0;
 exports.boundSessionErrorPayload = boundSessionErrorPayload;
+const contracts_1 = require("../../contracts");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const route_disconnected_error_1 = require("../channels/route-disconnected-error");
 const submission_result_1 = require("../messaging/submission-result");
 const protocol_1 = require("./protocol");
 class DefaultZLinkBoundSessionResponseTarget {
@@ -36,7 +39,11 @@ class DefaultZLinkBoundSessionResponseTarget {
 exports.DefaultZLinkBoundSessionResponseTarget = DefaultZLinkBoundSessionResponseTarget;
 function boundSessionErrorPayload(error) {
     return {
-        code: error instanceof Error ? error.constructor.name : 'RemoteError',
+        code: (0, channel_envelope_1.channelErrorCodeName)(error instanceof contracts_1.ZLinkFrameworkException
+            ? error.kind
+            : error instanceof route_disconnected_error_1.ZLinkRouteDisconnectedError
+                ? contracts_1.ZLinkFrameworkErrorKind.Unavailable
+                : contracts_1.ZLinkFrameworkErrorKind.InternalFailure),
         message: errorMessage(error)
     };
 }

package/dist/runtime/streams/bound-session-service.d.ts

@@ -45,4 +45,5 @@ export declare class ZLinkBoundSessionService {
     private submitNativeBoundSessionPayload;
     private submitNativeBoundSessionFrame;
     private requireTransport;
+    private actorSlot;
 }

package/dist/runtime/streams/bound-session-service.js

@@ -20,7 +20,7 @@ class ZLinkBoundSessionService {
     async sendBoundSession(actorId, message, packetName, metadata, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const route = await this.routes.requireRoute(actorId);
-        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message);
+        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message, undefined, this.actorSlot(route));
         try {
             const result = await this.requireTransport().send(actorId, frame, {
                 bindingToken: route.bindingToken,
@@ -40,7 +40,7 @@ class ZLinkBoundSessionService {
         if (route === undefined) {
             return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
         }
-        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message);
+        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message, undefined, this.actorSlot(route));
         try {
             (0, abort_1.throwIfAborted)(signal);
             if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
@@ -124,7 +124,7 @@ class ZLinkBoundSessionService {
         }
     }
     async writeLocalBoundSessionFrame(actorId, route, kind, packetName, metadata, compressPayload, requestSeq, payload, operationName) {
-        const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressPayload, requestSeq, payload);
+        const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressPayload, requestSeq, payload, undefined, this.actorSlot(route));
         try {
             if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
                 return false;
@@ -165,6 +165,9 @@ class ZLinkBoundSessionService {
         }
         return this.options.transport;
     }
+    actorSlot(route) {
+        return route.actorSlot;
+    }
 }
 exports.ZLinkBoundSessionService = ZLinkBoundSessionService;
 function requireBoundSessionGeneration(actorRef) {

package/dist/runtime/streams/index.js

@@ -88,6 +88,7 @@ class ZLinkStreamRuntimeManager {
                     const service = createService.call(meshNode, socket.nativeInstance);
                     const bindingOwner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.bindingRuntime);
                     (0, service_session_binding_ingress_port_1.registerServiceSessionBindingIngressPort)(service, {
+                        actorSlot: (actorId, sessionRid) => bindingOwner.actorSlot(actorId, sessionRid),
                         retainOutbound: (claim, delivery) => bindingOwner.admitRelocationOutbound(claim, delivery),
                         clearOutbound: (actorId, error) => bindingOwner.clearRelocation(actorId, error)
                     });
@@ -206,7 +207,7 @@ class ZLinkStreamBindingRuntime {
             ...options,
             actorBindTimeoutMs: options.actorBindTimeoutMs ?? DEFAULT_ACTOR_BIND_TIMEOUT_MS
         };
-        this.routes = new actor_session_binding_registry_1.ZLinkActorSessionBindingRegistry(4096, 4096, runtimeOptions.sessionRelocationSealTimeoutMs ?? 3_000);
+        this.routes = new actor_session_binding_registry_1.ZLinkActorSessionBindingRegistry(4096, 4096, runtimeOptions.sessionRelocationSealTimeoutMs ?? 3_000, runtimeOptions.errorSink);
         this.compressionCodec = (0, stream_frame_factory_1.resolveStreamCompressionCodec)(runtimeOptions.streamCompression);
         this.frameMessages = new stream_frame_factory_1.ZLinkStreamFrameMessageFactory(runtimeOptions);
         this.boundSessions = new bound_session_service_1.ZLinkBoundSessionService(this.routes, this.frameMessages, runtimeOptions);
@@ -214,6 +215,12 @@ class ZLinkStreamBindingRuntime {
         this.sessionActors = new session_actor_coordinator_1.ZLinkSessionActorCoordinator(this.routes, this, runtimeOptions, actorSessionLifecycle);
         this.boundActorRelay = new bound_actor_relay_sender_1.ZLinkBoundActorRelaySender(this.routes, this.frameMessages, runtimeOptions, actorSessionLifecycle);
         (0, actor_session_binding_runtime_owner_1.registerActorSessionBindingRuntimeOwner)(this, {
+            actorSlot: async (actorId, sessionRid) => {
+                const route = await this.routes.route(actorId);
+                return route !== undefined && route.sessionIdentity === sessionRid
+                    ? route.actorSlot
+                    : undefined;
+            },
             sealRelocation: (claim, expected, signal) => this.routes.sealRelocation(claim, expected, signal),
             relocationSnapshot: (actorId, sealId) => this.routes.relocationSnapshot(actorId, sealId),
             retainRelocationOutbound: (actorId, operation, sealId) => this.routes.retainRelocationOutbound(actorId, operation, sealId),

package/dist/runtime/streams/managed-stream.d.ts

@@ -43,6 +43,9 @@ export declare class ZLinkManagedStream implements ZLinkStream {
     bindActor(actor: ActorRef, timeoutMs: number, signal?: AbortSignal, onBindingReplaced?: (actor: ServiceActorRef, retiredSession: ServiceRetiredBoundSessionRouteFence) => void, authorityFence?: ZLinkActorSessionAuthorityFence): Promise<void>;
     private ensureNativeActorRoute;
     unbindActor(actorId: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    enqueueActorBound(actorSlot: number, actorId: string): Promise<void>;
+    enqueueActorUnbound(actorSlot: number): Promise<void>;
+    private submitActorBindingControl;
     sendBoundActor(actorId: string, parts: readonly Message[], flags?: ZLinkBackendSendFlags): Promise<boolean>;
     updateAddresses(localAddr: string | undefined, remoteAddr: string | undefined): void;
     private hasNativeBinding;

package/dist/runtime/streams/managed-stream.js

@@ -122,12 +122,12 @@ class ZLinkManagedStream {
         if (this.transportClosed) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
         }
+        const nativeActor = toNativeActorRef(actor);
         const route = this.nativeRoute(actor.meshName);
         if (route !== undefined) {
             if (route.service.status().state === 1) {
                 route.service.start();
             }
-            const nativeActor = toNativeActorRef(actor);
             await this.ensureNativeActorRoute(route, actor, timeoutMs, signal);
             if (this.isTransportClosed()) {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Stream session '${this.sessionId}' is disconnected.`);
@@ -163,6 +163,7 @@ class ZLinkManagedStream {
             return;
         }
         await this.socket.bindActor(this.backendRoutingId(), toBackendActorRef(actor), timeoutMs, signal);
+        this.nativeActorBindings.set(actor.actorId, { actor: nativeActor });
     }
     async ensureNativeActorRoute(route, actor, timeoutMs, signal) {
         const completion = await route.completions.submit(() => route.service.lookupActor(actor.nodeRid, actor.actorId, timeoutMs), signal);
@@ -223,6 +224,24 @@ class ZLinkManagedStream {
             return;
         }
         await this.socket.unbindActor(this.backendRoutingId(), actorId, timeoutMs, signal);
+        if (binding !== undefined && this.nativeActorBindings.get(actorId) === binding) {
+            this.nativeActorBindings.delete(actorId);
+        }
+    }
+    async enqueueActorBound(actorSlot, actorId) {
+        await this.submitActorBindingControl((0, protocol_1.encodeActorBoundFrame)(actorSlot, actorId));
+    }
+    async enqueueActorUnbound(actorSlot) {
+        await this.submitActorBindingControl((0, protocol_1.encodeActorUnboundFrame)(actorSlot));
+    }
+    async submitActorBindingControl(frame) {
+        const message = runtime_message_1.ZLinkBufferMessage.from(frame);
+        try {
+            await this.socket.submit(this.backendRoutingId(), message);
+        }
+        finally {
+            message.close();
+        }
     }
     async sendBoundActor(actorId, parts, flags) {
         if (this.transportClosed) {

package/dist/runtime/streams/protocol.d.ts

@@ -22,7 +22,8 @@ export declare enum ZLinkStreamHeaderFlags {
     HasMetadata = 2,
     PayloadCompressed = 4,
     HasCorrelationId = 8,
-    HasFlowId = 16
+    HasFlowId = 16,
+    HasActorSlot = 32
 }
 export declare enum ZLinkStreamCloseReasonCode {
     ClientClose = 1,
@@ -44,6 +45,7 @@ export interface ZLinkStreamFrameHeader {
     readonly correlationId?: string;
     readonly flowId?: string;
     readonly flowOrigin?: ZLinkFlowOrigin;
+    readonly actorSlot?: number;
 }
 export type ZLinkStreamReplyMessageKind = ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error;
 export interface ZLinkStreamFrame {
@@ -54,6 +56,8 @@ export declare function resolvePacketName(message: unknown, explicitPacketName:
 export declare function ensureSingleSubmit(executed: boolean): void;
 export declare function encodeStreamFrame(header: ZLinkStreamFrameHeader, payload: Uint8Array): Uint8Array;
 export declare function encodeStreamControlFrame(name: string): Uint8Array;
+export declare function encodeActorBoundFrame(actorSlot: number, actorId: string): Uint8Array;
+export declare function encodeActorUnboundFrame(actorSlot: number): Uint8Array;
 export declare function encodeSessionClosingFrame(diagnostic?: string, reason?: ZLinkStreamCloseReasonCode): Uint8Array;
 export declare function decodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame;
 export declare function tryDecodeStreamFrame(frame: Uint8Array): ZLinkStreamFrame | undefined;

package/dist/runtime/streams/protocol.js

@@ -7,6 +7,8 @@ exports.resolvePacketName = resolvePacketName;
 exports.ensureSingleSubmit = ensureSingleSubmit;
 exports.encodeStreamFrame = encodeStreamFrame;
 exports.encodeStreamControlFrame = encodeStreamControlFrame;
+exports.encodeActorBoundFrame = encodeActorBoundFrame;
+exports.encodeActorUnboundFrame = encodeActorUnboundFrame;
 exports.encodeSessionClosingFrame = encodeSessionClosingFrame;
 exports.decodeStreamFrame = decodeStreamFrame;
 exports.tryDecodeStreamFrame = tryDecodeStreamFrame;
@@ -78,6 +80,7 @@ var ZLinkStreamHeaderFlags;
     ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["PayloadCompressed"] = 4] = "PayloadCompressed";
     ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasCorrelationId"] = 8] = "HasCorrelationId";
     ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasFlowId"] = 16] = "HasFlowId";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasActorSlot"] = 32] = "HasActorSlot";
 })(ZLinkStreamHeaderFlags || (exports.ZLinkStreamHeaderFlags = ZLinkStreamHeaderFlags = {}));
 var ZLinkStreamCloseReasonCode;
 (function (ZLinkStreamCloseReasonCode) {
@@ -114,6 +117,26 @@ function encodeStreamControlFrame(name) {
         metadata: EMPTY_STREAM_METADATA
     }, new Uint8Array());
 }
+function encodeActorBoundFrame(actorSlot, actorId) {
+    const actorIdBytes = (0, stream_wire_1.utf8Encode)(actorId);
+    if (actorIdBytes.length < 1 || actorIdBytes.length > 0xff) {
+        throw new Error('Actor id length is invalid for a STREAM binding control packet.');
+    }
+    const payload = new Uint8Array(4 + actorIdBytes.length);
+    payload[0] = 1;
+    payload[1] = actorSlot >>> 8;
+    payload[2] = actorSlot & 0xff;
+    payload[3] = actorIdBytes.length;
+    payload.set(actorIdBytes, 4);
+    return encodeStreamFrame(controlHeader('$zlink.actor.bound'), payload);
+}
+function encodeActorUnboundFrame(actorSlot) {
+    const payload = new Uint8Array(3);
+    payload[0] = 1;
+    payload[1] = actorSlot >>> 8;
+    payload[2] = actorSlot & 0xff;
+    return encodeStreamFrame(controlHeader('$zlink.actor.unbound'), payload);
+}
 function encodeSessionClosingFrame(diagnostic = '', reason = ZLinkStreamCloseReasonCode.ServerDrain) {
     const diagnosticBytes = (0, stream_wire_1.utf8Encode)(diagnostic);
     if (diagnosticBytes.length > 512)
@@ -143,8 +166,9 @@ function encodeStreamHeader(header) {
     const hasMetadata = header.metadata.size > 0;
     const hasCorrelation = header.correlationId !== undefined && header.correlationId.length > 0;
     const hasFlow = header.flowId !== undefined || header.flowOrigin !== undefined;
+    const hasActorSlot = header.actorSlot !== undefined;
     if (header.kind === ZLinkStreamMessageKind.Control &&
-        (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+        (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow || hasActorSlot)) {
         throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
     }
     //  Explicit construction: this runs for every outbound frame, so avoid a
@@ -158,7 +182,8 @@ function encodeStreamHeader(header) {
         metadata: header.metadata,
         correlationId: header.correlationId,
         flowId: header.flowId,
-        flowOrigin: encodeFlowOrigin(header.flowOrigin)
+        flowOrigin: encodeFlowOrigin(header.flowOrigin),
+        actorSlot: header.actorSlot
     });
 }
 function decodeStreamHeader(header, flowEnabled = true) {
@@ -169,8 +194,9 @@ function decodeStreamHeader(header, flowEnabled = true) {
     const hasMetadata = (flags & ZLinkStreamHeaderFlags.HasMetadata) !== 0;
     const hasCorrelation = (flags & ZLinkStreamHeaderFlags.HasCorrelationId) !== 0;
     const hasFlow = (flags & ZLinkStreamHeaderFlags.HasFlowId) !== 0;
+    const hasActorSlot = (flags & ZLinkStreamHeaderFlags.HasActorSlot) !== 0;
     if (kind === ZLinkStreamMessageKind.Control &&
-        (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+        (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow || hasActorSlot)) {
         throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
     }
     const metadata = publicStreamMetadata(decoded.metadata);
@@ -184,7 +210,8 @@ function decodeStreamHeader(header, flowEnabled = true) {
         metadata,
         correlationId: decoded.correlationId,
         flowId: decoded.flowId,
-        flowOrigin: decodeFlowOrigin(decoded.flowOrigin)
+        flowOrigin: decodeFlowOrigin(decoded.flowOrigin),
+        actorSlot: decoded.actorSlot
     };
 }
 function actorRequestDeadlineMetadata(deadlineUnixMs) {
@@ -221,9 +248,19 @@ function createStreamReplyHeader(requestHeader, kind, codec, flags, metadata, in
         // observation-only and is not copied into the reply when tracing is Off
         // (spec 27 §4, §7).
         correlationId: requestHeader.correlationId,
+        actorSlot: requestHeader.actorSlot,
         ...(includeFlow ? { flowId: requestHeader.flowId, flowOrigin: requestHeader.flowOrigin } : {})
     };
 }
+function controlHeader(name) {
+    return {
+        kind: ZLinkStreamMessageKind.Control,
+        codec: ZLinkStreamCodec.Raw,
+        flags: ZLinkStreamHeaderFlags.None,
+        name,
+        metadata: EMPTY_STREAM_METADATA
+    };
+}
 function encodeFlowOrigin(origin) {
     return origin === undefined
         ? undefined

package/dist/runtime/streams/session-actor-coordinator.js

@@ -60,18 +60,17 @@ class ZLinkSessionActorCoordinator {
         const sessionActor = reuseActor ??
             new session_context_1.DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
         const sessionIdentity = String(this.actorBindingRoutingId(context));
-        sessionActor.updateRef(boundActorRef);
         if (previous === undefined) {
             if (releaseSeal !== undefined) {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorRef.actorId}' route switch has no Session binding to release.`, true);
             }
-            await this.routes.bind(context, sessionActor, bindingToken, authorityFence, sessionIdentity);
+            await this.routes.bind(context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
         else if (releaseSeal !== undefined) {
-            await this.routes.replaceAndReleaseSeal(previous, context, sessionActor, bindingToken, releaseSeal.sealId, authorityFence, sessionIdentity);
+            await this.routes.replaceAndReleaseSeal(previous, context, sessionActor, bindingToken, releaseSeal.sealId, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
         else {
-            await this.routes.replace(previous, context, sessionActor, bindingToken, authorityFence, sessionIdentity);
+            await this.routes.replace(previous, context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
         if (confirmRemoteSessionBinding !== false &&
             this.options.confirmRemoteActorSessionBinding !== undefined) {

package/dist/runtime/streams/session-context.d.ts

@@ -10,6 +10,8 @@ import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service
 export interface ZLinkSessionContextStream extends ZLinkStream {
     writeRaw(payload: Message, flags?: number): boolean;
     submitRaw(payload: Message, signal?: AbortSignal, timeoutMs?: number): Promise<ZLinkSubmitResult>;
+    enqueueActorBound?(actorSlot: number, actorId: string): Promise<void>;
+    enqueueActorUnbound?(actorSlot: number): Promise<void>;
 }
 interface ZLinkSessionContextRuntime {
     cleanup(context: DefaultZLinkSessionContext): Promise<void>;
@@ -76,7 +78,12 @@ export declare class DefaultZLinkSessionContext implements ZLinkSessionContext {
     payloadForHeader(header: ZLinkStreamFrameHeader, payload: Message): Message;
     get boundActors(): readonly DefaultZLinkSessionActor[];
     findBoundActor(actorId: string): DefaultZLinkSessionActor | undefined;
-    bindLocal(actor: DefaultZLinkSessionActor, token: string): void;
+    actorForSlot(actorSlot: number | undefined): DefaultZLinkSessionActor | undefined;
+    get actorSlotControls(): {
+        enqueueBound(actorSlot: number, actorId: string): Promise<void>;
+        enqueueUnbound(actorSlot: number): Promise<void>;
+    } | undefined;
+    bindLocal(actor: DefaultZLinkSessionActor, token: string, actorSlot?: number): void;
     unbindLocal(actorId: string, token: string): void;
     completeConfiguration(): void;
 }
@@ -92,7 +99,7 @@ export declare class DefaultZLinkSessionActor implements ZLinkSessionActor {
     relay(dispatch: ZLinkSessionDispatchContext, payload: ZLinkMessage, signal?: AbortSignal): Promise<void>;
     notifyDisconnected(signal?: AbortSignal): Promise<void>;
 }
-export declare function createSessionDispatchContext(header: ZLinkStreamFrameHeader): ZLinkSessionDispatchContext;
+export declare function createSessionDispatchContext(header: ZLinkStreamFrameHeader, actor?: DefaultZLinkSessionActor): ZLinkSessionDispatchContext;
 export declare class DefaultZLinkBoundSession implements ZLinkBoundSession {
     private readonly runtime;
     private readonly actorId;

package/dist/runtime/streams/session-context.js

@@ -163,8 +163,23 @@ class DefaultZLinkSessionContext {
     findBoundActor(actorId) {
         return this.localActors.find(actorId);
     }
-    bindLocal(actor, token) {
-        this.localActors.bind(actor, token);
+    actorForSlot(actorSlot) {
+        if (actorSlot === undefined)
+            return undefined;
+        return this.localActors.findBySlot(actorSlot);
+    }
+    get actorSlotControls() {
+        if (this.stream.enqueueActorBound === undefined ||
+            this.stream.enqueueActorUnbound === undefined) {
+            return undefined;
+        }
+        return {
+            enqueueBound: (actorSlot, actorId) => this.stream.enqueueActorBound(actorSlot, actorId),
+            enqueueUnbound: (actorSlot) => this.stream.enqueueActorUnbound(actorSlot)
+        };
+    }
+    bindLocal(actor, token, actorSlot) {
+        this.localActors.bind(actor, token, actorSlot);
     }
     unbindLocal(actorId, token) {
         this.localActors.unbind(actorId, token);
@@ -313,11 +328,12 @@ class DefaultZLinkSessionActor {
 }
 exports.DefaultZLinkSessionActor = DefaultZLinkSessionActor;
 const SESSION_DISPATCH_HEADERS = new WeakMap();
-function createSessionDispatchContext(header) {
+function createSessionDispatchContext(header, actor) {
     const dispatch = {
         packetName: header.name,
         metadata: header.metadata,
-        canReply: header.requestSeq !== undefined
+        canReply: header.requestSeq !== undefined,
+        ...(actor === undefined ? {} : { actor })
     };
     SESSION_DISPATCH_HEADERS.set(dispatch, header);
     return dispatch;

package/dist/runtime/streams/session-local-actors.d.ts

@@ -3,8 +3,10 @@ export interface ZLinkSessionLocalActor {
 }
 export declare class ZLinkSessionLocalActorBindings<TActor extends ZLinkSessionLocalActor> {
     private readonly actors;
+    private readonly actorIdsBySlot;
     snapshot(): readonly TActor[];
     find(actorId: string): TActor | undefined;
-    bind(actor: TActor, token: string): void;
+    findBySlot(actorSlot: number): TActor | undefined;
+    bind(actor: TActor, token: string, actorSlot?: number): void;
     unbind(actorId: string, token: string): void;
 }