@zlink-systems/framework 0.30.3 → 0.32.0

package/dist/runtime/spots/spot-subscription-dispatch.js

@@ -6,6 +6,7 @@ const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOp
 const channel_envelope_1 = require("../channels/channel-envelope");
 const flow_context_1 = require("../diagnostics/flow-context");
 const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const HandlerMessageType_1 = require("../../contracts/Common/HandlerMessageType");
 const spot_native_flags_1 = require("./spot-native-flags");
 const serial_work_size_1 = require("../execution/serial-work-size");
 const framework_errors_internal_1 = require("../framework-errors-internal");
@@ -85,6 +86,7 @@ class ZLinkSpotSubscriptionDispatch {
         }
     }
     async dispatch(message) {
+        const receivedAt = new Date();
         if (message.parts.length === 0) {
             this.options.dispatchErrors?.report({
                 surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotSubscription,
@@ -133,8 +135,8 @@ class ZLinkSpotSubscriptionDispatch {
             await this.options.serial.post(() => (0, flow_context_1.runWithFlow)(inboundFlow, async () => {
                 // Payload deserialization belongs to the Spot serial turn. Queue
                 // admission and execution authority therefore precede this work.
-                const event = (0, channel_envelope_1.decodeChannelPayload)(envelope, this.channelCodecs());
                 for (const registration of registrations) {
+                    const event = (0, channel_envelope_1.decodeChannelPayload)(envelope, this.channelCodecs(), (0, HandlerMessageType_1.resolveMessageTypeForDecode)(registration.messageType));
                     const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(spot, registration.handlerType, this.options.providerResolver);
                     try {
                         await handler.handle(spot, event, {
@@ -144,7 +146,8 @@ class ZLinkSpotSubscriptionDispatch {
                             topic: message.topic,
                             source: subSource,
                             metadata: (0, contracts_1.zlinkMessageMetadata)(envelope.header.metadata),
-                            correlationId: envelope.header.correlationId ?? undefined
+                            correlationId: envelope.header.correlationId ?? undefined,
+                            receivedAt
                         });
                     }
                     catch (error) {

package/dist/runtime/spots/spot-timer.d.ts

@@ -123,7 +123,7 @@ export declare class ZLinkManagedTimer implements ZLinkTimer {
     private pendingScheduledIndex;
     private timeout;
     /** The dispatch in flight, from its timer callback until `completeFireCore`. */
-    private running;
+    running: Promise<void> | undefined;
     private dispatchFailure;
     private finalization;
     constructor(name: string, periodMs: number, options: Required<ZLinkTimerOptions>, onTick: (tick: ZLinkTimerTick) => Promise<void>, onFailure?: ZLinkTimerFailureReporter | undefined, shouldWaitForRunningOnCancel?: () => boolean, clock?: ZLinkTimerClock, start?: ZLinkManagedTimerStart);

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

@@ -1,3 +1,5 @@
+import { type ZLinkStreamFrameHeader } from './protocol';
+import { ZLinkStateLane } from '../execution/state-lane';
 import type { RoutingId } from '../../contracts';
 import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed } from '../foundation/service-stateful-wire-codec';
 export interface ZLinkPreparedSessionRelocationSeal {
@@ -100,13 +102,16 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     private readonly terminalRelocationCapacity;
     private readonly sealWaitTimeoutMs;
     private readonly errorSink?;
-    private readonly lane;
+    readonly lane: ZLinkStateLane;
     private readonly routes;
-    private readonly nextActorSlots;
+    readonly nextActorSlots: WeakMap<TContext, number>;
     private readonly sealWaiters;
     private readonly activeFrameWaiters;
     private readonly relocations;
-    private readonly absentSessionRelocationResults;
+    readonly absentSessionRelocationResults: Map<string, {
+        readonly result: SessionRelocationResult;
+        readonly expiry: ReturnType<typeof setTimeout>;
+    }>;
     private readonly terminalRelocations;
     constructor(terminalRelocationCapacity?: number, sealWaitTimeoutMs?: number, errorSink?: (() => {
         reportRuntimeTaskException(taskName: string, error: unknown): void;
@@ -120,6 +125,9 @@ export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActo
     find(actorId: string): Promise<TActor | undefined>;
     private findCore;
     route(actorId: string): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined>;
+    submitReply<T>(context: TContext, header: ZLinkStreamFrameHeader, submit: (header: ZLinkStreamFrameHeader) => Promise<T>): Promise<T>;
+    /** Registers a current binding's frame in the same turn that can retire its slot. */
+    submitCurrent<T>(actorId: string, bindingToken: string, submit: (route: ZLinkActorSessionRoute<TContext, TActor>) => Promise<T>): Promise<T | undefined>;
     /** Selects the route only when it is the exact Session binding (§8.1 validation values). */
     routeForSessionBinding(actorId: string, sessionRid: RoutingId, bindingGeneration?: bigint): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined>;
     private routeCore;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionBindingTermination = exports.DEFAULT_TERMINAL_RELOCATION_CAPACITY = void 0;
+const protocol_1 = require("./protocol");
 const ZLinkFrameworkException_1 = require("../../contracts/Errors/ZLinkFrameworkException");
 const Options_1 = require("../../contracts/Locations/Options");
 const abort_1 = require("../abort");
@@ -139,6 +140,33 @@ class ZLinkActorSessionBindingRegistry {
     async route(actorId) {
         return await this.lane.run(() => this.routeCore(actorId));
     }
+    async submitReply(context, header, submit) {
+        const { submission } = await this.lane.run(() => {
+            const current = header.actorSlot === undefined ||
+                [...this.routes.values()].some((route) => route.context === context && route.actorSlot === header.actorSlot);
+            return {
+                submission: submit(current
+                    ? header
+                    : {
+                        ...header,
+                        actorSlot: undefined,
+                        flags: header.flags & ~protocol_1.ZLinkStreamHeaderFlags.HasActorSlot
+                    })
+            };
+        });
+        return await submission;
+    }
+    /** Registers a current binding's frame in the same turn that can retire its slot. */
+    async submitCurrent(actorId, bindingToken, submit) {
+        const { submission } = await this.lane.run(() => {
+            const route = this.routeCore(actorId);
+            return {
+                submission: route?.bindingToken === bindingToken ? submit(route) : undefined
+            };
+        });
+        // Transport completion must not hold the registry lane.
+        return await submission;
+    }
     /** Selects the route only when it is the exact Session binding (§8.1 validation values). */
     async routeForSessionBinding(actorId, sessionRid, bindingGeneration) {
         return await this.lane.run(() => {

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

@@ -2,7 +2,7 @@ import type { ZLinkMessage, ZLinkMessageSerializer, ZLinkSessionActor } from '..
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import { type ZLinkSubmitResult } from '../messaging/submission-result';
-import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
+import { type ZLinkActorSessionAuthorityFence, ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { type ZLinkStreamFrameHeader } from './protocol';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
@@ -14,7 +14,7 @@ export interface ZLinkBoundActorRelaySenderOptions {
     readonly actorBindTimeoutMs?: number;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
     readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message) => Promise<boolean>;
-    readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal, binding?: ServiceStreamSessionBinding) => Promise<void>;
+    readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal, binding?: ServiceStreamSessionBinding, authorityFence?: ZLinkActorSessionAuthorityFence) => Promise<void>;
 }
 export declare class ZLinkBoundActorRelaySender {
     private readonly routes;

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

@@ -170,7 +170,7 @@ class ZLinkBoundActorRelaySender {
             detached.route.context.stream instanceof managed_stream_1.ZLinkManagedStream) {
             await detached.route.context.stream.unbindActor(actor.actorId, this.options.actorBindTimeoutMs ?? exports.DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS, signal);
         }
-        await this.options.notifyDisconnected?.(actor, signal, detached.binding);
+        await this.options.notifyDisconnected?.(actor, signal, detached.binding, detached.route.authorityFence);
     }
     async notifyPhysicalDisconnect(context) {
         const snapshot = [...context.boundActors];
@@ -191,7 +191,7 @@ class ZLinkBoundActorRelaySender {
                     ? context.stream.actorBinding(actor.actorId)
                     : undefined;
                 await this.routes.unbind(actor.actorId, context, actor.bindingToken, actor_session_binding_registry_1.ZLinkActorSessionBindingTermination.PhysicalDisconnect);
-                return { binding };
+                return { binding, authorityFence: route.authorityFence };
             });
             if (detached === false)
                 return;
@@ -199,8 +199,7 @@ class ZLinkBoundActorRelaySender {
             const timer = setTimeout(() => controller.abort(), timeoutMs);
             try {
                 await Promise.race([
-                    this.options.notifyDisconnected?.(actor, controller.signal, detached.binding) ??
-                        Promise.resolve(),
+                    this.options.notifyDisconnected?.(actor, controller.signal, detached.binding, detached.authorityFence) ?? Promise.resolve(),
                     new Promise((_, reject) => {
                         controller.signal.addEventListener('abort', () => reject(new Error(`Actor '${actor.actorId}' disconnect notification exceeded ${timeoutMs} ms.`)), { once: true });
                     })

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

@@ -43,11 +43,10 @@ class ZLinkBoundSessionService {
         }
         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) {
-                return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
-            }
-            return await route.context.stream.submitRaw(frame);
+            return ((await this.routes.submitCurrent(actorId, route.bindingToken, (current) => {
+                (0, abort_1.throwIfAborted)(signal);
+                return current.context.stream.submitRaw(frame);
+            })) ?? { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound });
         }
         finally {
             frame.close();
@@ -131,10 +130,10 @@ class ZLinkBoundSessionService {
     async writeLocalBoundSessionFrame(actorId, route, kind, packetName, metadata, compressPayload, requestSeq, payload, operationName) {
         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) {
+            const result = await this.routes.submitCurrent(actorId, route.bindingToken, (current) => current.context.stream.submitRaw(frame));
+            if (result === undefined) {
                 return false;
             }
-            const result = await route.context.stream.submitRaw(frame);
             if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
                 throw new Error(`Actor '${actorId}' local bound session ${operationName} failed.`);
             }

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

@@ -8,7 +8,7 @@ import { type ZLinkFrameworkRegistration } from '../configuration';
 import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import { ApplicationJobQueue } from '../host/application-job-queue';
 import type { ZLinkSubmitResult } from '../messaging/submission-result';
-import { type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+import { ZLinkActorSessionBindingRegistry, type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
 import { type ZLinkBoundActorRelaySenderOptions } from './bound-actor-relay-sender';
 import { type ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
 import { type ZLinkBoundSessionTransport } from './bound-session-service';
@@ -100,7 +100,7 @@ export declare class ZLinkStreamSessionNodeRuntime extends ZLinkStreamSessionNod
     constructor(options: ZLinkStreamSessionNodeRuntimeOptions);
 }
 export declare class ZLinkStreamBindingRuntime {
-    private readonly routes;
+    readonly routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>;
     private readonly frameMessages;
     private readonly compressionCodec;
     private readonly boundSessions;
@@ -149,5 +149,5 @@ export declare class ZLinkStreamBindingRuntime {
     createBinaryMessage(payload: Uint8Array): Message;
     decompressPayload(payload: Message): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(context: DefaultZLinkSessionContext, requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
 }

package/dist/runtime/streams/index.js

@@ -348,8 +348,28 @@ class ZLinkStreamBindingRuntime {
     createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId) {
         return this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId);
     }
-    createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload) {
-        return this.frameMessages.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+    async submitReply(context, requestHeader, kind, metadata, compressed, payload) {
+        const frame = this.frameMessages.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+        try {
+            return await this.routes.submitReply(context, requestHeader, async (header) => {
+                if (header === requestHeader)
+                    return await context.stream.submitRaw(frame);
+                const encoded = (0, protocol_1.decodeStreamFrame)((0, protocol_1.messageToBytes)(frame));
+                const normalized = this.createBinaryMessage((0, protocol_1.encodeStreamFrame)({
+                    ...(0, protocol_1.decodeStreamHeader)(encoded.header),
+                    actorSlot: header.actorSlot
+                }, encoded.payload));
+                try {
+                    return await context.stream.submitRaw(normalized);
+                }
+                finally {
+                    normalized.close();
+                }
+            });
+        }
+        finally {
+            frame.close();
+        }
     }
 }
 exports.ZLinkStreamBindingRuntime = ZLinkStreamBindingRuntime;

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

@@ -297,7 +297,8 @@ class ZLinkManagedStream {
         try {
             if (completion.terminalResult !== 0 &&
                 !acceptedTerminalResults.has(completion.terminalResult)) {
-                throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`);
+                throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, completion.failureMessage ??
+                    `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`);
             }
         }
         finally {

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

@@ -12,7 +12,7 @@ export interface ZLinkSessionCallContext {
     };
     readonly dispatchHeader: ZLinkStreamFrameHeader | undefined;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     claimReply(requestHeader: ZLinkStreamFrameHeader): void;
     /**
      * Spec 26 §2.2: the STREAM surface records session-connected sends and the

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

@@ -93,15 +93,9 @@ class DefaultZLinkSessionReplyCall {
             throw new Error('Reply is only available while handling a request packet.');
         }
         this.context.claimReply(requestHeader);
-        const message = this.context.createJsonReplyFrameMessage(requestHeader, protocol_1.ZLinkStreamMessageKind.Response, new Map(), this.compressionEnabled, this.message);
-        try {
-            const result = await this.context.stream.submitRaw(message);
-            (0, submission_result_1.requireOneWayCompletion)(result, 'STREAM session reply');
-            this.context.traceFrameWritten?.(protocol_1.ZLinkStreamMessageKind.Response, requestHeader.name, requestHeader.correlationId);
-        }
-        finally {
-            message.close();
-        }
+        const result = await this.context.submitReply(requestHeader, protocol_1.ZLinkStreamMessageKind.Response, new Map(), this.compressionEnabled, this.message);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'STREAM session reply');
+        this.context.traceFrameWritten?.(protocol_1.ZLinkStreamMessageKind.Response, requestHeader.name, requestHeader.correlationId);
     }
 }
 exports.DefaultZLinkSessionReplyCall = DefaultZLinkSessionReplyCall;

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

@@ -17,7 +17,7 @@ interface ZLinkSessionContextRuntime {
     createTextMessage(payload: string): Message;
     createBinaryMessage(payload: Uint8Array): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(context: DefaultZLinkSessionContext, requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     decompressPayload(payload: Message): Message;
     bind(context: DefaultZLinkSessionContext, actor: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
@@ -64,7 +64,7 @@ export declare class DefaultZLinkSessionContext implements ZLinkSessionContext {
     createTextMessage(payload: string): Message;
     createBinaryMessage(payload: Uint8Array): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     enterDispatch(header: ZLinkStreamFrameHeader): void;
     exitDispatch(): void;
     get dispatchHeader(): ZLinkStreamFrameHeader | undefined;

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

@@ -105,8 +105,8 @@ class DefaultZLinkSessionContext {
     createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId) {
         return this.runtime.createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId);
     }
-    createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload) {
-        return this.runtime.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+    submitReply(requestHeader, kind, metadata, compressed, payload) {
+        return this.runtime.submitReply(this, requestHeader, kind, metadata, compressed, payload);
     }
     enterDispatch(header) {
         if (this.closingForActorReplacement) {

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

@@ -93,6 +93,7 @@ export declare class ZLinkStreamSessionRuntime {
     private markConnected;
     private dispatchPacket;
     private handleControl;
+    private logIgnoredControl;
     private scheduleLivenessCheck;
     private runLivenessCheck;
     private closeForLiveness;

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

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = void 0;
+const submission_result_1 = require("../messaging/submission-result");
+const api_logs_1 = require("@opentelemetry/api-logs");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const Registration_1 = require("../../contracts/Configuration/Registration");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const abort_1 = require("../abort");
@@ -8,6 +11,7 @@ const admission_1 = require("../admission");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const channels_1 = require("../channels");
 const diagnostics_1 = require("../diagnostics");
+const message_flow_record_1 = require("../diagnostics/message-flow-record");
 const flow_context_1 = require("../diagnostics/flow-context");
 const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
 const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
@@ -20,7 +24,6 @@ const session_context_1 = require("./session-context");
 const session_serial_executor_1 = require("./session-serial-executor");
 const stream_message_utils_1 = require("./stream-message-utils");
 const RegistrationNormalizers_1 = require("../../contracts/Configuration/RegistrationNormalizers");
-const ZLINK_SEND_DONT_WAIT = 1;
 const ZLINK_RECV_DONT_WAIT = 1;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
@@ -28,6 +31,7 @@ const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
 const ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS = 20;
 const ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS = 7;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const STREAM_RUNTIME_LOGGER = api_logs_1.logs.getLogger(message_flow_record_1.TELEMETRY_INSTRUMENTATION_NAME);
 const systemLivenessClock = {
     now: () => performance.now(),
     setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
@@ -324,7 +328,6 @@ class ZLinkStreamSessionRuntime {
                     correlationId: streamCorr,
                     sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
                 });
-                (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
                 (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched)?.trace({
                     outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched,
                     surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
@@ -333,7 +336,12 @@ class ZLinkStreamSessionRuntime {
                     correlationId: streamCorr,
                     sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
                 });
-                await session.onDispatch?.((0, session_context_1.createSessionDispatchContext)(inboundHeader, dispatchActor), (0, payload_codec_1.wrapFrameworkPayloadMessage)(dispatchPayload, this.options.messageSerializers, (0, protocol_1.streamCodecContentType)(inboundHeader.codec), inboundHeader.name));
+                if (session.onDispatch !== undefined) {
+                    const sessionDispatchContext = (0, session_context_1.createSessionDispatchContext)(inboundHeader, dispatchActor);
+                    const frameworkPayload = (0, payload_codec_1.wrapFrameworkPayloadMessage)(dispatchPayload, this.options.messageSerializers, (0, protocol_1.streamCodecContentType)(inboundHeader.codec), inboundHeader.name);
+                    (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
+                    await session.onDispatch(sessionDispatchContext, frameworkPayload);
+                }
                 if (streamKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send) {
                     (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed)?.trace({
                         outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed,
@@ -380,19 +388,45 @@ class ZLinkStreamSessionRuntime {
         }
     }
     async handleControl(header, payload) {
-        if ((0, protocol_1.messageToBytes)(payload).length !== 0) {
-            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', 'Control heartbeat payload must be empty.');
+        const payloadBytes = (0, protocol_1.messageToBytes)(payload);
+        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
+            if (payloadBytes.length !== 0) {
+                this.logIgnoredControl(header.name, payloadBytes.length);
+            }
+            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PONG);
             return;
         }
         if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG) {
+            if (payloadBytes.length !== 0) {
+                this.logIgnoredControl(header.name, payloadBytes.length);
+            }
             return;
         }
-        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
-            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PONG);
+        if (header.name === stream_wire_1.ZlinkStreamControlPacket.ActorBound ||
+            header.name === stream_wire_1.ZlinkStreamControlPacket.ActorUnbound) {
+            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', `Unexpected stream actor control frame: ${header.name}`);
+            return;
+        }
+        if (header.name.startsWith('$zlink.')) {
+            this.logIgnoredControl(header.name, payloadBytes.length);
             return;
         }
         await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', `Unknown stream control frame: ${header.name}`);
     }
+    logIgnoredControl(name, payloadLength) {
+        STREAM_RUNTIME_LOGGER.emit({
+            eventName: 'zlink.stream.control_ignored',
+            timestamp: new Date(),
+            severityNumber: api_logs_1.SeverityNumber.DEBUG,
+            severityText: 'DEBUG',
+            body: `Ignored STREAM control name=${name} payloadBytes=${payloadLength} peerSessionRid=${this.stream.sessionId}`,
+            attributes: {
+                control_name: name,
+                payload_bytes: payloadLength,
+                peer_session_rid: this.stream.sessionId
+            }
+        });
+    }
     scheduleLivenessCheck() {
         if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
             return;
@@ -435,9 +469,11 @@ class ZLinkStreamSessionRuntime {
         this.closeReason = closeReason;
         this.stopLivenessChecks();
         await this.stream.closeForReason(reason, diagnostic);
-        void this.serial
-            .executeFinal(async () => this.complete(undefined, true))
-            .catch((error) => this.options.onError?.(error));
+        const bindingsCleanup = this.context.cleanupBindings();
+        void Promise.all([
+            bindingsCleanup,
+            this.serial.executeFinal(async () => this.complete(undefined, true, bindingsCleanup))
+        ]).catch((error) => this.options.onError?.(error));
     }
     stopLivenessChecks() {
         if (this.livenessTimer !== undefined) {
@@ -455,19 +491,14 @@ class ZLinkStreamSessionRuntime {
             // record (spec 26 §2.2) and confuse the peer's reply matching.
             return;
         }
-        const message = this.context.createJsonReplyFrameMessage(header, protocol_1.ZLinkStreamMessageKind.Error, new Map(), false, (0, bound_session_response_target_1.boundSessionErrorPayload)(error));
         try {
-            if (!this.context.stream.writeRaw(message, ZLINK_SEND_DONT_WAIT)) {
-                throw new Error('Client stream error reply send failed.');
-            }
+            const result = await this.context.submitReply(header, protocol_1.ZLinkStreamMessageKind.Error, new Map(), false, (0, bound_session_response_target_1.boundSessionErrorPayload)(error));
+            (0, submission_result_1.requireOneWayCompletion)(result, 'Client stream error reply');
             this.traceFrameWritten(protocol_1.ZLinkStreamMessageKind.Error, header.name, header.correlationId);
         }
         catch (replyError) {
             this.options.onError?.(replyError);
         }
-        finally {
-            message.close();
-        }
     }
     /**
      * Spec 26 §2.1/§2.2: a successful session write is the surface's terminal
@@ -492,7 +523,7 @@ class ZLinkStreamSessionRuntime {
             streamSessionId: this.stream.sessionId
         });
     }
-    async complete(error, notifyDisconnected) {
+    async complete(error, notifyDisconnected, bindingsCleanup) {
         try {
             if (error !== undefined && this.closeReason !== 'server_drain') {
                 this.closeReason = 'transport_error';
@@ -510,7 +541,7 @@ class ZLinkStreamSessionRuntime {
             }
         }
         finally {
-            await this.cleanup();
+            await this.cleanup(bindingsCleanup);
         }
     }
     queueDisconnect(error) {
@@ -518,20 +549,20 @@ class ZLinkStreamSessionRuntime {
             return;
         this.disconnectQueued = true;
         this.stopLivenessChecks();
-        void this.serial
-            .executeFinal(async () => {
-            this.disconnectQueued = false;
-            if (this.disconnected)
-                return;
-            this.stream.markTransportClosed();
-            this.disconnected = true;
-            await this.complete(error, true);
-        })
-            .catch(() => {
-            this.disconnectQueued = false;
-        });
+        this.stream.markTransportClosed();
+        const bindingsCleanup = this.context.cleanupBindings();
+        void Promise.all([
+            bindingsCleanup,
+            this.serial.executeFinal(async () => {
+                this.disconnectQueued = false;
+                if (this.disconnected)
+                    return;
+                this.disconnected = true;
+                await this.complete(error, true, bindingsCleanup);
+            })
+        ]).catch((failure) => this.options.onError?.(failure));
     }
-    async cleanup() {
+    async cleanup(bindingsCleanup) {
         if (this.connected && !this.metricsClosed) {
             this.metricsClosed = true;
             this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.StreamConnectionsActive, -1, { transport: 'tcp' });
@@ -540,7 +571,7 @@ class ZLinkStreamSessionRuntime {
                 close_reason: normalizeStreamCloseReason(this.closeReason)
             });
         }
-        await this.context.cleanupBindings();
+        await (bindingsCleanup ?? this.context.cleanupBindings());
         this.removeSession(this.stream.sessionId, this);
     }
     enqueueControl(work, onRejected, onShutdownRejected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.30.3",
+  "version": "0.32.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.30.3",
-    "@zlink-systems/zlink": "1.20.0"
+    "@zlink-systems/stream-wire": "0.32.0",
+    "@zlink-systems/zlink": "1.23.0"
   }
 }

package/src/contracts/Actors/ZLinkActor.ts

@@ -1,8 +1,14 @@
 import type { ZLinkActorContext } from './ZLinkActorContext';
 import type { ZLinkActorJoinCompletion } from './ZLinkActorFactory';
+import type { ZLinkSessionBindingIdentity } from './ZLinkSessionBindingIdentity';
 
 export interface ZLinkActor {
   readonly context: ZLinkActorContext;
   configure?(): void;
   onJoinCompleted?(completion: ZLinkActorJoinCompletion): Promise<void>;
+  onDuplicateBind?(
+    current: ZLinkSessionBindingIdentity,
+    incoming: ZLinkSessionBindingIdentity,
+    signal: AbortSignal
+  ): Promise<string | undefined>;
 }

package/src/contracts/Actors/ZLinkSessionBindingIdentity.ts

@@ -0,0 +1,7 @@
+import type { RoutingId } from '../Common';
+
+export interface ZLinkSessionBindingIdentity {
+  readonly sessionOwnerNodeRid: RoutingId;
+  readonly sessionOwnerNodeGeneration: bigint;
+  readonly bindingGeneration: bigint;
+}

package/src/contracts/Actors/index.ts

@@ -1,4 +1,5 @@
 export * from './ZLinkActor';
+export * from './ZLinkSessionBindingIdentity';
 export * from './ZLinkActorContext';
 export * from './ZLinkActorClient';
 export * from './ZLinkActorFactory';

package/src/contracts/Common/CoreTypes.ts

@@ -1,4 +1,5 @@
 export type Type<T = unknown> = new (...args: never[]) => T;
+export type ZLinkMessageTypeResolver<T = unknown> = Type<T> | (() => Type<T>);
 export type RoutingId = string;
 /** Global logical Actor identity. It does not encode a Mesh or owner route. */
 export type ActorId = string;