@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,14 +1,10 @@
 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';
+import type { ZLinkActorSessionAuthorityFence, ZLinkActorSessionRelocationClaim, ZLinkActorSessionRelocationSnapshot, 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>;
-    admitRelocationOutbound(claim: ServiceSessionBindingAdmissionClaim, operation: ZLinkActorSessionRetainedOutbound): Promise<ServiceSessionBindingAdmissionResult>;
-    discardRelocationOutbound(actorId: string, sealId: string, error: unknown): Promise<void>;
-    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, action: 'commit' | 'abort', commitOwnerTransition: () => Promise<void>, acceptedProducerProof?: ZLinkActorSessionAcceptedProducerProof): Promise<void>;
+    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, commitOwnerTransition: () => Promise<void>): Promise<void>;
     observeRelocationTerminal(actorId: string, sealId: string, applyFingerprint: string): Promise<void>;
     clearRelocation(actorId: string, error: unknown): Promise<void>;
     committedRoute(actorId: string): Promise<{

package/dist/runtime/streams/bound-actor-relay-sender.d.ts

@@ -1,12 +1,15 @@
 import type { ZLinkMessage, ZLinkMessageSerializer, ZLinkSessionActor } from '../../contracts';
-import { type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
-import { type ZLinkStreamFrameHeader } from './protocol';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
 import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
+import { type ZLinkStreamFrameHeader } from './protocol';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
 import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+export declare const DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS = 2000;
 export interface ZLinkBoundActorRelaySenderOptions {
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly actorBindTimeoutMs?: number;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
     readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal) => Promise<boolean>;
@@ -19,6 +22,7 @@ export declare class ZLinkBoundActorRelaySender {
     private readonly lifecycle;
     constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, frameMessages: ZLinkStreamFrameMessageFactory, options?: ZLinkBoundActorRelaySenderOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
     relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, signal?: AbortSignal, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
+    private traceHeldDrop;
     private relayAcceptedFrame;
     private currentHeader;
     private requireDispatchHeader;

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

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkBoundActorRelaySender = void 0;
-const submission_result_1 = require("../messaging/submission-result");
-const payload_codec_1 = require("../messaging/payload-codec");
-const protocol_1 = require("./protocol");
+exports.ZLinkBoundActorRelaySender = exports.DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS = void 0;
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const abort_1 = require("../abort");
-const execution_1 = require("../execution");
+const diagnostics_1 = require("../diagnostics");
+const payload_codec_1 = require("../messaging/payload-codec");
+const submission_result_1 = require("../messaging/submission-result");
 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");
+const protocol_1 = require("./protocol");
+exports.DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS = 2000;
 class ZLinkBoundActorRelaySender {
     routes;
     frameMessages;
@@ -34,37 +36,58 @@ class ZLinkBoundActorRelaySender {
                     await admission.complete();
                 }
             };
-            if ((await this.routes.isSealed(actor.actorId)) &&
-                (0, execution_1.captureZLinkExecutionTurn)() !== undefined) {
-                void operation().catch(() => undefined);
-                return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
-            }
             return await operation();
         }
-        if ((await this.routes.isSealed(actor.actorId)) && (0, execution_1.captureZLinkExecutionTurn)() !== undefined) {
-            //  Spec 32:62 — a Send completes once the source outbound queue
-            //  accepts it; spec 05 — infrastructure send progress must not depend
-            //  on the application turn. When the CALLER IS an application turn
-            //  (a lifecycle callback pushing to a bound actor), awaiting the seal
-            //  release here deadlocks: the relocation seal waits for that very
-            //  callback to finish (onJoinedActor -> push -> seal ->
-            //  onJoinedActor). Accept the frame now and deliver it after the
-            //  seal releases, in per-actor order through the lifecycle lane; the
-            //  bounded seal wait converts a stuck seal into a typed failure.
-            //  Non-turn callers (stream ingress relays) keep the waiting
-            //  semantics so a held frame across a failed rebind still
-            //  terminalizes to the caller.
-            void this.routes
-                .runAcceptedFrameWhenReady(actor.actorId, actor.bindingToken, () => this.relayAcceptedFrame(actor, payload, signal), signal)
-                .catch(() => undefined);
+        (0, abort_1.throwIfAborted)(signal);
+        const held = await this.routes.acceptOneWay(actor.actorId, actor.bindingToken, () => {
+            let heldMessage = (0, payload_codec_1.encodeFrameworkPayloadMessage)(payload, this.options.messageSerializers);
+            return {
+                deliver: async () => {
+                    try {
+                        const result = await this.routes.runAcceptedFrameWhenReady(actor.actorId, actor.bindingToken, () => this.relayAcceptedFrame(actor, payload, undefined, header, undefined, heldMessage));
+                        if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+                            this.traceHeldDrop(header, result.status === submission_result_1.ZLinkSubmitStatus.Backpressured ||
+                                result.status === submission_result_1.ZLinkSubmitStatus.TimedOut
+                                ? 'backpressure'
+                                : result.status === submission_result_1.ZLinkSubmitStatus.Shutdown
+                                    ? 'shutdown'
+                                    : 'stale_target');
+                        }
+                    }
+                    finally {
+                        heldMessage?.close();
+                        heldMessage = undefined;
+                    }
+                },
+                drop: (reason, error) => {
+                    heldMessage?.close();
+                    heldMessage = undefined;
+                    this.traceHeldDrop(header, reason, error);
+                }
+            };
+        });
+        if (held) {
             return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
         }
         return this.routes.runAcceptedFrameWhenReady(actor.actorId, actor.bindingToken, () => this.relayAcceptedFrame(actor, payload, signal), signal);
     }
-    async relayAcceptedFrame(actor, payload, signal, header, requestAdmission) {
+    traceHeldDrop(header, reason, error) {
+        (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, undefined, header.flowId)?.trace({
+            outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+            messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            packetName: header.name,
+            flowId: header.flowId,
+            flowOrigin: header.flowOrigin,
+            correlationId: header.correlationId,
+            errorReason: reason,
+            ...(error instanceof Error ? { errorType: error.name, errorMessage: error.message } : {})
+        });
+    }
+    async relayAcceptedFrame(actor, payload, signal, header, requestAdmission, acceptedPayload) {
         const activeHeader = header ?? (await this.currentHeader(actor));
         const started = await this.lifecycle.run(actor.actorId, async () => {
-            const completion = this.relayInsideLifecycle(actor, payload, signal, activeHeader, requestAdmission);
+            const completion = this.relayInsideLifecycle(actor, payload, signal, activeHeader, requestAdmission, acceptedPayload);
             if (activeHeader.kind === protocol_1.ZLinkStreamMessageKind.Request &&
                 activeHeader.requestSeq !== undefined) {
                 // A routed REQUEST only needs this lane while its ordered submission
@@ -96,13 +119,13 @@ class ZLinkBoundActorRelaySender {
         }
         return header;
     }
-    async relayInsideLifecycle(actor, payload, signal, currentHeader, requestAdmission) {
+    async relayInsideLifecycle(actor, payload, signal, currentHeader, requestAdmission, acceptedPayload) {
         const header = currentHeader ?? (await this.currentHeader(actor));
         const held = requestAdmission?.beginSubmission(signal);
         if (held !== undefined)
             await held;
         (0, abort_1.throwIfAborted)(signal);
-        const payloadMessage = (0, payload_codec_1.encodeFrameworkPayloadMessage)(payload, this.options.messageSerializers);
+        const payloadMessage = acceptedPayload ?? (0, payload_codec_1.encodeFrameworkPayloadMessage)(payload, this.options.messageSerializers);
         try {
             if (this.options.relay !== undefined) {
                 const handled = await this.options.relay(actor, header, payloadMessage, signal);
@@ -125,7 +148,8 @@ class ZLinkBoundActorRelaySender {
             }
         }
         finally {
-            payloadMessage.close();
+            if (acceptedPayload === undefined)
+                payloadMessage.close();
         }
     }
     async notifyDisconnected(actor, signal) {
@@ -141,13 +165,13 @@ class ZLinkBoundActorRelaySender {
         if (unbindNative &&
             detached.bindingToken === actor.bindingToken &&
             detached.context.stream instanceof managed_stream_1.ZLinkManagedStream) {
-            await detached.context.stream.unbindActor(actor.actorId, this.options.actorBindTimeoutMs ?? 2000, signal);
+            await detached.context.stream.unbindActor(actor.actorId, this.options.actorBindTimeoutMs ?? exports.DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS, signal);
         }
         await this.options.notifyDisconnected?.(actor, signal);
     }
     async notifyPhysicalDisconnect(context) {
         const snapshot = [...context.boundActors];
-        const timeoutMs = this.options.actorBindTimeoutMs ?? 2000;
+        const timeoutMs = this.options.actorBindTimeoutMs ?? exports.DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS;
         await Promise.allSettled(snapshot.map(async (actor) => {
             const detached = await this.lifecycle.run(actor.actorId, async () => {
                 const route = await this.routes.route(actor.actorId);

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

@@ -5,6 +5,7 @@ import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-regist
 import type { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
 import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
 import { ZLinkManagedStream } from './managed-stream';
+import type { ZLinkSessionBindingIdentity } from './stream-binding-runtime-ports';
 export interface ZLinkBoundSessionTransport {
     send(actorId: string, message: unknown, options: ZLinkBoundSessionSendOptions): Promise<ZLinkSubmitResult>;
     disconnect(actorId: string, options: ZLinkBoundSessionDisconnectOptions): Promise<void>;
@@ -39,6 +40,12 @@ export declare class ZLinkBoundSessionService {
     sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
     disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
     disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Closes the physical Session of one exact binding after its relocation
+     * failed (Session–Actor binding §8.1). A newer binding of the same Actor is
+     * not selected.
+     */
+    closeSessionBinding(actorId: string, expected: ZLinkSessionBindingIdentity, signal?: AbortSignal): Promise<void>;
     relayRemoteBoundSessionBind(stream: ZLinkManagedStream, actorRef: ActorRef): Promise<void>;
     private writeLocalBoundSessionFrame;
     private sendNativeBoundSessionPayload;

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

@@ -7,6 +7,7 @@ const submission_result_1 = require("../messaging/submission-result");
 const abort_1 = require("../abort");
 const protocol_1 = require("./protocol");
 const bound_session_response_target_1 = require("./bound-session-response-target");
+const spot_remote_codec_1 = require("../spots/spot-remote-codec");
 const ZLINK_SEND_DONT_WAIT = 1;
 class ZLinkBoundSessionService {
     routes;
@@ -102,12 +103,21 @@ class ZLinkBoundSessionService {
             await this.routes.unbind(actorId, route.context, route.bindingToken);
         }
     }
+    /**
+     * Closes the physical Session of one exact binding after its relocation
+     * failed (Session–Actor binding §8.1). A newer binding of the same Actor is
+     * not selected.
+     */
+    async closeSessionBinding(actorId, expected, signal) {
+        const route = await this.routes.routeForSessionBinding(actorId, expected.sessionRid, expected.bindingGeneration);
+        await route?.context.close(signal);
+    }
     async relayRemoteBoundSessionBind(stream, actorRef) {
         const encodedBindHeader = (0, protocol_1.encodeStreamHeader)({
             kind: protocol_1.ZLinkStreamMessageKind.Send,
             codec: protocol_1.ZLinkStreamCodec.Raw,
             flags: protocol_1.ZLinkStreamHeaderFlags.None,
-            name: 'zlink.framework.actor.bound_session.bind',
+            name: spot_remote_codec_1.REMOTE_BOUND_SESSION_BIND_PACKET,
             metadata: new Map()
         });
         //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
@@ -157,7 +167,7 @@ class ZLinkBoundSessionService {
     async submitNativeBoundSessionFrame(node, actorRef, frame, signal) {
         const backendActorRef = toBoundSessionSendActorRef(actorRef);
         (0, abort_1.throwIfAborted)(signal);
-        return await node.sendActorBoundSession(backendActorRef, requireBoundSessionGeneration(actorRef), [frame], ZLINK_SEND_DONT_WAIT, boundSessionSendFence(node, backendActorRef, actorRef));
+        return await node.sendActorBoundSession(backendActorRef, requireBoundSessionGeneration(actorRef), [frame], ZLINK_SEND_DONT_WAIT);
     }
     requireTransport() {
         if (this.options.transport === undefined) {
@@ -184,20 +194,3 @@ function toBoundSessionSendActorRef(actor) {
         generation: actor.objectGeneration
     };
 }
-function boundSessionSendFence(node, backendActor, actor) {
-    const internal = actor;
-    const ownerNodeGeneration = internal.ownerNodeGeneration ?? node.actorNodeGeneration?.(backendActor);
-    if (internal.ownershipGeneration === undefined ||
-        internal.ownershipGeneration <= 0n ||
-        internal.ownerLeaseGeneration === undefined ||
-        internal.ownerLeaseGeneration <= 0n ||
-        ownerNodeGeneration === undefined ||
-        ownerNodeGeneration <= 0n) {
-        return undefined;
-    }
-    return Object.freeze({
-        targetNodeGeneration: ownerNodeGeneration,
-        authorityOwnerGeneration: internal.ownershipGeneration,
-        ownerLeaseGeneration: internal.ownerLeaseGeneration
-    });
-}

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

@@ -1,21 +1,21 @@
-import type { ActorRef, ZLinkActor, ZLinkBoundSession, ZLinkSessionActor, ZLinkMessageSerializer, ZLinkStreamCompressionOptions } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import type { ZLinkSubmitResult } from '../messaging/submission-result';
-import { ZLinkMessage } from '../../contracts';
+import { type ActorRef, type ZLinkActor, type ZLinkBoundSession, type ZLinkMessageSerializer, type ZLinkSessionActor, type ZLinkStreamCompressionOptions, ZLinkMessage } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import { type ZLinkFrameworkRegistration } from '../configuration';
-import { ZLinkDispatchErrorReporter } from '../channels';
-import type { ZLinkBackendAdapterFactory, ZLinkBackendActorSessionNode, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkBackendActorSessionNode, ZLinkBackendAdapterFactory, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
 import type { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
-import { ZLinkStreamCodec, type ZLinkStreamFrameHeader, ZLinkStreamMessageKind, type ZLinkStreamReplyMessageKind } from './protocol';
-import { type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+import { ZLinkDispatchErrorReporter } from '../channels';
+import { type ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import { ApplicationJobQueue } from '../host/application-job-queue';
-import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import type { ZLinkSubmitResult } from '../messaging/submission-result';
+import { type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
 import { type ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
 import { type ZLinkBoundSessionTransport } from './bound-session-service';
 import { ZLinkManagedStream } from './managed-stream';
+import { ZLinkStreamCodec, ZLinkStreamMessageKind, type ZLinkStreamFrameHeader, type ZLinkStreamReplyMessageKind } from './protocol';
+import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import type { ZLinkActorRouteCommitOptions, ZLinkSessionBindingConfirmationOptions, ZLinkSessionBindingIdentity } from './stream-binding-runtime-ports';
 import { ZLinkStreamSessionNodeRuntime as ZLinkStreamSessionNodeRuntimeCore, ZLinkStreamSessionRuntime as ZLinkStreamSessionRuntimeCore, type ZLinkStreamSessionNodeRuntimeOptions as ZLinkStreamSessionNodeRuntimeCoreOptions, type ZLinkStreamSessionRuntimeOptions as ZLinkStreamSessionRuntimeCoreOptions } from './stream-session-runtime';
-import type { ZLinkActorRouteCommitOptions } from './stream-binding-runtime-ports';
 export { ZLinkPendingSessionRequest } from './session-requests';
 export { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 export { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
@@ -25,6 +25,7 @@ export { DefaultZLinkBoundSession, DefaultZLinkBoundSessionFactory, DefaultZLink
 export type { ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
 export type { ZLinkBoundSessionDisconnectOptions, ZLinkBoundSessionSendOptions, ZLinkBoundSessionTransport } from './bound-session-service';
 export interface ZLinkStreamBindingRuntimeOptions {
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly transport?: ZLinkBoundSessionTransport;
     readonly messageFactory?: ZLinkStreamMessageFactory;
     readonly streamPayloadCodec?: ZLinkStreamPayloadCodec;
@@ -40,9 +41,7 @@ export interface ZLinkStreamBindingRuntimeOptions {
             readonly routingId: unknown;
         };
     } | undefined;
-    readonly confirmRemoteActorSessionBinding?: (actor: ActorRef, sessionRid: ActorRef['nodeRid'], signal?: AbortSignal, options?: {
-        readonly waitForAcknowledgement?: boolean;
-    }) => Promise<void>;
+    readonly confirmRemoteActorSessionBinding?: (actor: ActorRef, sessionRid: ActorRef['nodeRid'], signal?: AbortSignal, options?: ZLinkSessionBindingConfirmationOptions) => Promise<void>;
     readonly errorSink?: () => {
         reportRuntimeTaskException(taskName: string, error: unknown): void;
     } | undefined;
@@ -68,6 +67,7 @@ export interface ZLinkStreamSessionNodeRuntimeOptions extends Omit<ZLinkStreamSe
     readonly bindingRuntime?: ZLinkStreamBindingRuntime;
 }
 export interface ZLinkStreamRuntimeManagerOptions {
+    readonly listenerRecords?: ZLinkListenerRecords;
     readonly registration: ZLinkFrameworkRegistration;
     readonly backendAdapterFactory: ZLinkBackendAdapterFactory;
     readonly context: ZLinkBackendContext;
@@ -142,6 +142,7 @@ export declare class ZLinkStreamBindingRuntime {
     sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
     disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
     disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+    closeSessionBinding(actorId: string, expected: ZLinkSessionBindingIdentity, signal?: AbortSignal): Promise<void>;
     relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, signal?: AbortSignal, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
     notifyDisconnected(actor: DefaultZLinkSessionActor, signal?: AbortSignal): Promise<void>;
     createTextMessage(payload: string): Message;

package/dist/runtime/streams/index.js

@@ -1,23 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkStreamBindingRuntime = exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = exports.ZLinkStreamRuntimeManager = exports.DefaultZLinkSessionContext = exports.DefaultZLinkSessionActor = exports.DefaultZLinkBoundSessionFactory = exports.DefaultZLinkBoundSession = exports.ZLinkManagedStream = exports.zlinkStreamLz4CompressionCodec = exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionLifecycleCoordinator = exports.ZLinkPendingSessionRequest = void 0;
+const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
+const Options_1 = require("../../contracts/Locations/Options");
 const configuration_1 = require("../configuration");
 const service_session_binding_ingress_port_1 = require("../foundation/service-session-binding-ingress-port");
-const protocol_1 = require("./protocol");
+const application_job_queue_1 = require("../host/application-job-queue");
 const actor_session_binding_registry_1 = require("./actor-session-binding-registry");
 const actor_session_binding_runtime_owner_1 = require("./actor-session-binding-runtime-owner");
 const actor_session_lifecycle_coordinator_1 = require("./actor-session-lifecycle-coordinator");
-const stream_frame_factory_1 = require("./stream-frame-factory");
-const application_job_queue_1 = require("../host/application-job-queue");
-const stream_message_utils_1 = require("./stream-message-utils");
-const session_context_1 = require("./session-context");
+const bound_actor_relay_sender_1 = require("./bound-actor-relay-sender");
 const bound_session_response_target_1 = require("./bound-session-response-target");
 const bound_session_service_1 = require("./bound-session-service");
+const protocol_1 = require("./protocol");
 const session_actor_coordinator_1 = require("./session-actor-coordinator");
-const bound_actor_relay_sender_1 = require("./bound-actor-relay-sender");
+const session_context_1 = require("./session-context");
 const session_provider_1 = require("./session-provider");
-const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
+const stream_frame_factory_1 = require("./stream-frame-factory");
+const stream_message_utils_1 = require("./stream-message-utils");
 const stream_session_runtime_1 = require("./stream-session-runtime");
+const DEFAULT_STREAM_SERVICE_SHUTDOWN_TIMEOUT_MS = 1000;
 var session_requests_1 = require("./session-requests");
 Object.defineProperty(exports, "ZLinkPendingSessionRequest", { enumerable: true, get: function () { return session_requests_1.ZLinkPendingSessionRequest; } });
 var actor_session_lifecycle_coordinator_2 = require("./actor-session-lifecycle-coordinator");
@@ -56,6 +58,12 @@ class ZLinkStreamRuntimeManager {
             const nativeMeshNode = actorDispatchEnabled ? this.options.nativeMeshNode : undefined;
             const meshCompletions = actorDispatchEnabled ? this.options.meshCompletions : undefined;
             const socket = streamAdapter.createStreamSocket(this.options.context);
+            const node = {
+                meshName: applicationMeshName,
+                socket,
+                nativeSessionServices: []
+            };
+            this.nodes.set(nodeName, node);
             // Core uses -1 as the explicit unlimited value. The Framework value 0
             // means that it adds no separate STREAM cap, so preserve that meaning
             // when applying the socket option.
@@ -71,7 +79,6 @@ class ZLinkStreamRuntimeManager {
             if (advertisedEndpoint === undefined) {
                 throw new configuration_1.ZLinkConfigurationException(`STREAM node '${nodeName}' advertised host requires a TCP endpoint, received '${boundEndpoint}'.`);
             }
-            const readablePoller = streamAdapter.createReadablePoller(socket);
             const nativeSessionRoutes = new Map();
             if (actorDispatchEnabled) {
                 for (const [meshName, mesh] of this.options.registration.spotNodes) {
@@ -86,11 +93,10 @@ class ZLinkStreamRuntimeManager {
                     if (typeof createService !== 'function' || completions === undefined)
                         continue;
                     const service = createService.call(meshNode, socket.nativeInstance);
+                    node.nativeSessionServices.push(service);
                     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)
+                        actorSlot: (actorId, sessionRid) => bindingOwner.actorSlot(actorId, sessionRid)
                     });
                     nativeSessionRoutes.set(meshName, {
                         service,
@@ -102,8 +108,12 @@ class ZLinkStreamRuntimeManager {
                 ? undefined
                 : nativeSessionRoutes.get(applicationMeshName)?.service;
             const monitor = monitoringAdapter.openSocketMonitor(socket);
+            node.monitor = monitor;
             const sessionType = streamNode.session;
             const sessionHandlerTypes = streamNode[Symbol.for('@zlink-systems/framework:session-handler-types')] ?? [];
+            // The runtime disposes the poller, so the poller is created where nothing
+            // can fail before the runtime owns it.
+            const readablePoller = streamAdapter.createReadablePoller(socket);
             const runtime = new stream_session_runtime_1.ZLinkStreamSessionNodeRuntime({
                 nodeName,
                 socket,
@@ -123,42 +133,33 @@ class ZLinkStreamRuntimeManager {
                 replacementCallbackTimeoutMs: this.options.registration.sessionReplacementCallbackTimeoutMs,
                 sessionFactory: (context) => (0, session_provider_1.createStreamSessionInstance)(sessionType, this.options.providerResolver, context, sessionHandlerTypes)
             });
+            node.runtime = runtime;
             runtime.start();
-            this.nodes.set(nodeName, {
-                meshName: applicationMeshName,
-                advertisedEndpoint,
-                runtime,
-                socket,
-                monitor,
-                nativeSessionService,
-                nativeSessionServices: [...nativeSessionRoutes.values()].map((route) => route.service)
-            });
+            this.options.listenerRecords?.record('stream', nodeName, advertisedEndpoint);
         }
     }
     async dispose() {
         const nodes = [...this.nodes.values()];
-        this.nodes.clear();
         for (const node of nodes.reverse()) {
-            await node.runtime.dispose();
-            const nativeServices = node.nativeSessionServices ??
-                (node.nativeSessionService === undefined ? [] : [node.nativeSessionService]);
-            for (const service of nativeServices) {
-                service.shutdown(1000);
+            await node.runtime?.dispose();
+            for (const service of node.nativeSessionServices) {
+                service.shutdown(DEFAULT_STREAM_SERVICE_SHUTDOWN_TIMEOUT_MS);
                 service.close();
             }
-            await node.monitor.dispose();
+            await node.monitor?.dispose();
             await node.socket.dispose();
         }
+        this.nodes.clear();
     }
     async notifyServerDrain(meshName) {
         await Promise.all([...this.nodes.values()]
             .filter((node) => node.meshName === meshName)
-            .map((node) => node.runtime.drainCloseSessions()));
+            .map((node) => node.runtime?.drainCloseSessions()));
     }
     async notifyUnscopedServerDrain() {
         await Promise.all([...this.nodes.values()]
             .filter((node) => node.meshName === undefined)
-            .map((node) => node.runtime.drainCloseSessions()));
+            .map((node) => node.runtime?.drainCloseSessions()));
     }
 }
 exports.ZLinkStreamRuntimeManager = ZLinkStreamRuntimeManager;
@@ -169,6 +170,7 @@ class ZLinkStreamSessionRuntime extends stream_session_runtime_1.ZLinkStreamSess
         // dispatch-error flow tracer.
         const bindingRuntime = options.bindingRuntime ??
             new ZLinkStreamBindingRuntime({
+                dispatchErrors: options.dispatchErrors,
                 flowCreationEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
             });
         super({
@@ -186,6 +188,7 @@ class ZLinkStreamSessionNodeRuntime extends stream_session_runtime_1.ZLinkStream
         // process diagnostics Off gate (see ZLinkStreamSessionRuntime above).
         const bindingRuntime = options.bindingRuntime ??
             new ZLinkStreamBindingRuntime({
+                dispatchErrors: options.dispatchErrors,
                 flowCreationEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
             });
         super({
@@ -207,7 +210,8 @@ 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, runtimeOptions.errorSink);
+        this.routes = new actor_session_binding_registry_1.ZLinkActorSessionBindingRegistry(actor_session_binding_registry_1.DEFAULT_TERMINAL_RELOCATION_CAPACITY, runtimeOptions.sessionRelocationSealTimeoutMs ??
+            Options_1.zlinkDefaultLocationOptions.sessionRelocationSealTimeoutMs, 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);
@@ -215,17 +219,9 @@ 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;
-            },
+            actorSlot: async (actorId, sessionRid) => (await this.routes.routeForSessionBinding(actorId, sessionRid))?.actorSlot,
             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),
-            admitRelocationOutbound: (claim, operation) => this.routes.admitRelocationOutbound(claim, operation),
-            discardRelocationOutbound: (actorId, sealId, error) => this.routes.discardRelocationOutbound(actorId, sealId, error),
             applyRelocation: (...args) => this.routes.applyRelocation(...args),
             observeRelocationTerminal: (...args) => this.routes.observeRelocationTerminal(...args),
             clearRelocation: (actorId, error) => this.routes.clearRelocation(actorId, error),
@@ -328,6 +324,9 @@ class ZLinkStreamBindingRuntime {
     async disconnectBoundSession(actorId, signal) {
         await this.boundSessions.disconnectBoundSession(actorId, signal);
     }
+    async closeSessionBinding(actorId, expected, signal) {
+        await this.boundSessions.closeSessionBinding(actorId, expected, signal);
+    }
     async relay(actor, payload, signal, dispatchHeader) {
         return await this.boundActorRelay.relay(actor, payload, signal, dispatchHeader);
     }

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

@@ -5,6 +5,7 @@ import type { ZLinkBackendSendFlags, ZLinkBackendStreamSocket } from '../backend
 import type { StreamSessionService } from '../foundation/service-runtime-contracts';
 import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service-stateful-wire-codec';
 import type { ServiceActorRef } from '../foundation/service-stateful-registry';
+import type { ServiceStreamSessionBinding } from '../foundation/service-runtime-contracts';
 import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
 import { ZLinkStreamCloseReasonCode } from './protocol';
 import type { ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
@@ -29,6 +30,8 @@ export declare class ZLinkManagedStream implements ZLinkStream {
     get routingId(): RoutingId;
     get actorBindingRoutingId(): RoutingId;
     actorBindingGeneration(actorId: string): bigint | undefined;
+    /** The Session owner's registry snapshot of the Actor's current native binding. */
+    actorBinding(actorId: string): ServiceStreamSessionBinding | undefined;
     private isTransportClosed;
     get localAddr(): string | undefined;
     get remoteAddr(): string | undefined;

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

@@ -8,6 +8,7 @@ const abort_1 = require("../abort");
 const payload_codec_1 = require("../messaging/payload-codec");
 const runtime_values_1 = require("../backend/runtime-values");
 const runtime_message_1 = require("../backend/runtime-message");
+const diagnostic_text_1 = require("../diagnostics/diagnostic-text");
 const mesh_completion_table_1 = require("../backend/mesh-completion-table");
 const protocol_1 = require("./protocol");
 const ZLINK_SEND_DONT_WAIT = 1;
@@ -47,7 +48,11 @@ class ZLinkManagedStream {
         return this.backendSessionRoutingId;
     }
     actorBindingGeneration(actorId) {
-        return this.nativeActorBindings.get(actorId)?.bindingGeneration;
+        return this.nativeActorBindings.get(actorId)?.binding?.bindingGeneration;
+    }
+    /** The Session owner's registry snapshot of the Actor's current native binding. */
+    actorBinding(actorId) {
+        return this.nativeActorBindings.get(actorId)?.binding;
     }
     isTransportClosed() {
         return this.transportClosed;
@@ -77,8 +82,9 @@ class ZLinkManagedStream {
             return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
         }
         catch (error) {
-            if ((0, runtime_values_1.isBackendNotConnectedError)(error))
-                return { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
+            if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'submit') {
+                return (0, submission_result_1.classifySubmitResult)(error.result, 'STREAM submit', error.phase);
+            }
             throw error;
         }
     }
@@ -157,7 +163,7 @@ class ZLinkManagedStream {
             }
             this.nativeActorBindings.set(actor.actorId, {
                 actor: nativeActor,
-                bindingGeneration: binding.bindingGeneration,
+                binding,
                 route
             });
             return;
@@ -179,7 +185,9 @@ class ZLinkManagedStream {
                 String(resolved.nodeRid) !== String(actor.nodeRid)) {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.actorId}' native route fence does not match its ActorRef ` +
                     `(expected ${String(actor.nodeRid)}/${actor.objectGeneration}, ` +
-                    `resolved ${resolved === undefined ? 'none' : `${String(resolved.nodeRid)}/${resolved.generation}`}, ` +
+                    `resolved ${(0, diagnostic_text_1.diagnosticTextOrAbsent)(resolved === undefined
+                        ? undefined
+                        : `${String(resolved.nodeRid)}/${resolved.generation}`)}, ` +
                     `terminal=${completion.terminalResult}, failure=${completion.failureErrno}).`);
             }
         }
@@ -198,12 +206,13 @@ class ZLinkManagedStream {
         const binding = this.nativeActorBindings.get(actorId);
         if (binding?.route !== undefined) {
             const route = binding.route;
-            if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+            const bindingGeneration = binding.binding.bindingGeneration;
+            if (!this.hasNativeBinding(route, actorId, bindingGeneration)) {
                 this.nativeActorBindings.delete(actorId);
                 return;
             }
             try {
-                await this.requireSuccessfulCompletion(route.completions.submit(() => route.service.unbindActor(this.backendRoutingId(), binding.actor, binding.bindingGeneration, timeoutMs), signal), `Actor '${actorId}' native session unbind`, 
+                await this.requireSuccessfulCompletion(route.completions.submit(() => route.service.unbindActor(this.backendRoutingId(), binding.actor, bindingGeneration, timeoutMs), signal), `Actor '${actorId}' native session unbind`, 
                 // Destroy can remove the actor registry entry before the old
                 // session owner processes its cleanup. Both a disconnected route and
                 // that stale actor route are idempotent unbind outcomes.
@@ -214,7 +223,7 @@ class ZLinkManagedStream {
                 // tombstone. A transport teardown can therefore report an internal
                 // completion after the exact binding is already gone. Treat only that
                 // exact missing binding as stale cleanup; preserve other failures.
-                if (this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+                if (this.hasNativeBinding(route, actorId, bindingGeneration)) {
                     throw error;
                 }
             }