@zlink-systems/framework 0.22.0 → 0.24.0

package/src/runtime/streams/protocol.ts

@@ -70,7 +70,8 @@ export enum ZLinkStreamHeaderFlags {
   HasMetadata = 0x02,
   PayloadCompressed = 0x04,
   HasCorrelationId = 0x08,
-  HasFlowId = 0x10
+  HasFlowId = 0x10,
+  HasActorSlot = 0x20
 }
 
 export enum ZLinkStreamCloseReasonCode {
@@ -95,6 +96,7 @@ export interface ZLinkStreamFrameHeader {
   readonly correlationId?: string;
   readonly flowId?: string;
   readonly flowOrigin?: ZLinkFlowOrigin;
+  readonly actorSlot?: number;
 }
 
 export type ZLinkStreamReplyMessageKind =
@@ -139,6 +141,28 @@ export function encodeStreamControlFrame(name: string): Uint8Array {
   );
 }
 
+export function encodeActorBoundFrame(actorSlot: number, actorId: string): Uint8Array {
+  const actorIdBytes = 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);
+}
+
+export function encodeActorUnboundFrame(actorSlot: number): Uint8Array {
+  const payload = new Uint8Array(3);
+  payload[0] = 1;
+  payload[1] = actorSlot >>> 8;
+  payload[2] = actorSlot & 0xff;
+  return encodeStreamFrame(controlHeader('$zlink.actor.unbound'), payload);
+}
+
 export function encodeSessionClosingFrame(
   diagnostic = '',
   reason = ZLinkStreamCloseReasonCode.ServerDrain
@@ -176,9 +200,10 @@ export function encodeStreamHeader(header: ZLinkStreamFrameHeader): Uint8Array {
   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.'
@@ -195,7 +220,8 @@ export function encodeStreamHeader(header: ZLinkStreamFrameHeader): Uint8Array {
     metadata: header.metadata,
     correlationId: header.correlationId,
     flowId: header.flowId,
-    flowOrigin: encodeFlowOrigin(header.flowOrigin)
+    flowOrigin: encodeFlowOrigin(header.flowOrigin),
+    actorSlot: header.actorSlot
   });
 }
 
@@ -207,9 +233,10 @@ export function decodeStreamHeader(header: Uint8Array, flowEnabled = true): ZLin
   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.'
@@ -227,7 +254,8 @@ export function decodeStreamHeader(header: Uint8Array, flowEnabled = true): ZLin
     metadata,
     correlationId: decoded.correlationId,
     flowId: decoded.flowId,
-    flowOrigin: decodeFlowOrigin(decoded.flowOrigin)
+    flowOrigin: decodeFlowOrigin(decoded.flowOrigin),
+    actorSlot: decoded.actorSlot
   };
 }
 
@@ -275,10 +303,21 @@ export function createStreamReplyHeader(
     // 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: string): ZLinkStreamFrameHeader {
+  return {
+    kind: ZLinkStreamMessageKind.Control,
+    codec: ZLinkStreamCodec.Raw,
+    flags: ZLinkStreamHeaderFlags.None,
+    name,
+    metadata: EMPTY_STREAM_METADATA
+  };
+}
+
 function encodeFlowOrigin(origin: ZLinkFlowOrigin | undefined): number | undefined {
   return origin === undefined
     ? undefined

package/src/runtime/streams/session-actor-coordinator.ts

@@ -133,7 +133,6 @@ export class ZLinkSessionActorCoordinator {
       reuseActor ??
       new DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
     const sessionIdentity = String(this.actorBindingRoutingId(context));
-    sessionActor.updateRef(boundActorRef);
     if (previous === undefined) {
       if (releaseSeal !== undefined) {
         throw createInternalFrameworkException(
@@ -142,7 +141,14 @@ export class ZLinkSessionActorCoordinator {
           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,
@@ -151,7 +157,8 @@ export class ZLinkSessionActorCoordinator {
         bindingToken,
         releaseSeal.sealId,
         authorityFence,
-        sessionIdentity
+        sessionIdentity,
+        () => sessionActor.updateRef(boundActorRef)
       );
     } else {
       await this.routes.replace(
@@ -160,7 +167,8 @@ export class ZLinkSessionActorCoordinator {
         sessionActor,
         bindingToken,
         authorityFence,
-        sessionIdentity
+        sessionIdentity,
+        () => sessionActor.updateRef(boundActorRef)
       );
     }
     if (

package/src/runtime/streams/session-context.ts

@@ -45,6 +45,8 @@ import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/ap
 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 {
@@ -344,8 +346,31 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
     return this.localActors.find(actorId);
   }
 
-  bindLocal(actor: DefaultZLinkSessionActor, token: string): void {
-    this.localActors.bind(actor, token);
+  actorForSlot(actorSlot: number | undefined): DefaultZLinkSessionActor | undefined {
+    if (actorSlot === undefined) return undefined;
+    return this.localActors.findBySlot(actorSlot);
+  }
+
+  get actorSlotControls():
+    | {
+        enqueueBound(actorSlot: number, actorId: string): Promise<void>;
+        enqueueUnbound(actorSlot: number): Promise<void>;
+      }
+    | undefined {
+    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: DefaultZLinkSessionActor, token: string, actorSlot?: number): void {
+    this.localActors.bind(actor, token, actorSlot);
   }
 
   unbindLocal(actorId: string, token: string): void {
@@ -547,12 +572,14 @@ export class DefaultZLinkSessionActor implements ZLinkSessionActor {
 const SESSION_DISPATCH_HEADERS = new WeakMap<ZLinkSessionDispatchContext, ZLinkStreamFrameHeader>();
 
 export function createSessionDispatchContext(
-  header: ZLinkStreamFrameHeader
+  header: ZLinkStreamFrameHeader,
+  actor?: DefaultZLinkSessionActor
 ): ZLinkSessionDispatchContext {
   const dispatch: ZLinkSessionDispatchContext = {
     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/src/runtime/streams/session-local-actors.ts

@@ -3,7 +3,8 @@ export interface ZLinkSessionLocalActor {
 }
 
 export class ZLinkSessionLocalActorBindings<TActor extends ZLinkSessionLocalActor> {
-  private readonly actors = new Map<string, { actor: TActor; token: string }>();
+  private readonly actors = new Map<string, { actor: TActor; token: string; actorSlot?: number }>();
+  private readonly actorIdsBySlot = new Map<number, string>();
 
   snapshot(): readonly TActor[] {
     const snapshot: TActor[] = [];
@@ -17,14 +18,29 @@ export class ZLinkSessionLocalActorBindings<TActor extends ZLinkSessionLocalActo
     return this.actors.get(actorId)?.actor;
   }
 
-  bind(actor: TActor, token: string): void {
-    this.actors.set(actor.actorId, { actor, token });
+  findBySlot(actorSlot: number): TActor | undefined {
+    const actorId = this.actorIdsBySlot.get(actorSlot);
+    return actorId === undefined ? undefined : this.actors.get(actorId)?.actor;
+  }
+
+  bind(actor: TActor, token: string, actorSlot?: number): void {
+    const previous = this.actors.get(actor.actorId);
+    if (previous?.actorSlot !== undefined && previous.actorSlot !== actorSlot) {
+      this.actorIdsBySlot.delete(previous.actorSlot);
+    }
+    this.actors.set(actor.actorId, { actor, token, actorSlot });
+    if (actorSlot !== undefined) {
+      this.actorIdsBySlot.set(actorSlot, actor.actorId);
+    }
   }
 
   unbind(actorId: string, token: string): void {
     const current = this.actors.get(actorId);
     if (current?.token === token) {
       this.actors.delete(actorId);
+      if (current.actorSlot !== undefined) {
+        this.actorIdsBySlot.delete(current.actorSlot);
+      }
     }
   }
 }

package/src/runtime/streams/stream-frame-factory.ts

@@ -74,7 +74,8 @@ export class ZLinkStreamFrameMessageFactory {
     compressed: boolean,
     requestSeq: bigint | undefined,
     payload: unknown,
-    correlationId?: string
+    correlationId?: string,
+    actorSlot?: number
   ): Message {
     const flow =
       (this.options.flowCreationEnabled?.() ?? true)
@@ -97,7 +98,8 @@ export class ZLinkStreamFrameMessageFactory {
         metadata,
         correlationId,
         flowId: flow?.flowId,
-        flowOrigin: flow?.flowOrigin
+        flowOrigin: flow?.flowOrigin,
+        actorSlot
       })
     );
   }

package/src/runtime/streams/stream-session-runtime.ts

@@ -4,7 +4,6 @@ import {
 } from '../framework-errors-internal';
 import type { ZLinkMessageSerializer, RoutingId, ZLinkSession } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
 import { ZLinkSocketNativeEventType } from '../diagnostics/internal-event-contracts';
 import {
   ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
@@ -16,6 +15,7 @@ import {
 import type { Message } from '../../contracts/Common/Message';
 import { throwIfAborted } from '../abort';
 import { ZLinkDispatchErrorReporter, ZLinkRouteDisconnectedError } from '../channels';
+import { boundSessionErrorPayload } from './bound-session-response-target';
 import { flowIfEnabled } from '../diagnostics';
 import type { ZLinkRuntimeMetrics } from '../diagnostics';
 import { wrapFrameworkPayloadMessage } from '../messaging/payload-codec';
@@ -477,6 +477,55 @@ export class ZLinkStreamSessionRuntime {
       if (this.context.tryCompleteResponse(decodedHeader, dispatchPayload)) {
         return;
       }
+      const dispatchActor = this.context.actorForSlot(decodedHeader.actorSlot);
+      if (decodedHeader.actorSlot !== undefined && dispatchActor === undefined) {
+        const staleFlowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
+        await runWithFlow(
+          createInboundFlow(
+            decodedHeader.flowId,
+            decodedHeader.flowOrigin,
+            staleFlowEnabled,
+            staleFlowEnabled ? this.stream.sessionId : undefined
+          ),
+          async () => {
+            if (decodedHeader.kind === ZLinkStreamMessageKind.Request) {
+              const error = createInternalFrameworkException(
+                ZLinkFrameworkInternalErrorKind.InvalidOperation,
+                'Actor slot is not a current binding.'
+              );
+              this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchErrorSurface.StreamSession,
+                messageKind: ZLinkDispatchMessageKind.Request,
+                reason: ZLinkDispatchErrorReason.StaleTarget,
+                action: ZLinkDispatchErrorAction.ReplyError,
+                packetName: decodedHeader.name,
+                sourceRid:
+                  this.context.routingId === undefined ? undefined : String(this.context.routingId),
+                correlationId: decodedHeader.correlationId,
+                flowId: decodedHeader.flowId,
+                flowOrigin: decodedHeader.flowOrigin,
+                error
+              });
+              await this.replyDispatchError(decodedHeader, error);
+            } else {
+              flowIfEnabled(
+                this.options.dispatchErrors?.flow,
+                ZLinkMessageFlowOutcome.Dropped
+              )?.trace({
+                outcome: ZLinkMessageFlowOutcome.Dropped,
+                surface: ZLinkDispatchErrorSurface.StreamSession,
+                messageKind: ZLinkDispatchMessageKind.Send,
+                packetName: decodedHeader.name,
+                correlationId: decodedHeader.correlationId,
+                sourceRid:
+                  this.context.routingId === undefined ? undefined : String(this.context.routingId),
+                errorReason: ZLinkDispatchErrorReason.StaleTarget
+              });
+            }
+          }
+        );
+        return;
+      }
       this.context.enterDispatch(decodedHeader);
       enteredDispatch = true;
       const session = await this.requireSession();
@@ -486,11 +535,13 @@ export class ZLinkStreamSessionRuntime {
           : ZLinkDispatchMessageKind.Send;
       const streamCorr = decodedHeader.correlationId;
       const inboundHeader = decodedHeader;
+      const flowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
       await runWithFlow(
         createInboundFlow(
           inboundHeader.flowId,
           inboundHeader.flowOrigin,
-          this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+          flowEnabled,
+          flowEnabled ? this.stream.sessionId : undefined
         ),
         async () => {
           flowIfEnabled(this.options.dispatchErrors?.flow, ZLinkMessageFlowOutcome.Received)?.trace(
@@ -529,7 +580,7 @@ export class ZLinkStreamSessionRuntime {
               this.context.routingId === undefined ? undefined : String(this.context.routingId)
           });
           await session.onDispatch?.(
-            createSessionDispatchContext(inboundHeader),
+            createSessionDispatchContext(inboundHeader, dispatchActor),
             wrapFrameworkPayloadMessage(
               dispatchPayload,
               this.options.messageSerializers,
@@ -694,15 +745,7 @@ export class ZLinkStreamSessionRuntime {
       ZLinkStreamMessageKind.Error,
       new Map(),
       false,
-      {
-        code:
-          error instanceof ZLinkFrameworkException
-            ? ZLinkFrameworkErrorKind[error.kind]
-            : error instanceof Error
-              ? error.constructor.name
-              : 'RemoteError',
-        message: error instanceof Error ? error.message : String(error)
-      }
+      boundSessionErrorPayload(error)
     );
     try {
       if (!this.context.stream.writeRaw(message, ZLINK_SEND_DONT_WAIT)) {
@@ -740,7 +783,8 @@ export class ZLinkStreamSessionRuntime {
             : ZLinkDispatchMessageKind.Send,
       packetName: packetName.length === 0 ? undefined : packetName,
       correlationId,
-      sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+      sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId),
+      streamSessionId: this.stream.sessionId
     });
   }
 
@@ -874,6 +918,7 @@ export class ZLinkStreamSessionRuntime {
       packetName: header.name === '' ? undefined : header.name,
       correlationId: header.correlationId,
       sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId),
+      streamSessionId: this.stream.sessionId,
       flowId: flowEnabled ? header.flowId : undefined,
       flowOrigin: flowEnabled ? header.flowOrigin : undefined,
       errorReason: ZLinkDispatchErrorReason.Shutdown