@zlink-systems/framework 0.21.0 → 0.23.0

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

@@ -36,10 +36,7 @@ import {
   DefaultZLinkSessionReplyCall,
   DefaultZLinkSessionSendCall
 } from './session-calls';
-import {
-  ZLinkSessionRequestTracker,
-  type ZLinkPendingSessionRequest
-} from './session-requests';
+import { ZLinkSessionRequestTracker, type ZLinkPendingSessionRequest } from './session-requests';
 import { ZLinkSessionLocalActorBindings } from './session-local-actors';
 import type { ServiceActorRef } from '../foundation/service-stateful-registry';
 import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service-stateful-wire-codec';
@@ -48,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 {
@@ -126,10 +125,13 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
     correlationId: string | undefined
   ) => void;
   private closingForActorReplacement = false;
-  private readonly retiredActorBindings = new Map<string, {
-    readonly actorGeneration: bigint;
-    readonly retiredSession: ServiceRetiredBoundSessionRouteFence;
-  }>();
+  private readonly retiredActorBindings = new Map<
+    string,
+    {
+      readonly actorGeneration: bigint;
+      readonly retiredSession: ServiceRetiredBoundSessionRouteFence;
+    }
+  >();
 
   constructor(
     private readonly runtime: ZLinkSessionContextRuntime,
@@ -173,11 +175,13 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
   }
 
   /** Wired by the owning session runtime; see ZLinkSessionCallContext.traceFrameWritten. */
-  setFrameWrittenObserver(observer: (
-    kind: ZLinkStreamMessageKind,
-    packetName: string,
-    correlationId: string | undefined
-  ) => void): void {
+  setFrameWrittenObserver(
+    observer: (
+      kind: ZLinkStreamMessageKind,
+      packetName: string,
+      correlationId: string | undefined
+    ) => void
+  ): void {
     this.frameWrittenObserver = observer;
   }
 
@@ -199,9 +203,9 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
   ): boolean {
     const previous = this.retiredActorBindings.get(actor.actorId);
     if (
-      previous !== undefined
-      && previous.actorGeneration === actor.generation
-      && sameRetiredSession(previous.retiredSession, retiredSession)
+      previous !== undefined &&
+      previous.actorGeneration === actor.generation &&
+      sameRetiredSession(previous.retiredSession, retiredSession)
     ) {
       return false;
     }
@@ -219,17 +223,19 @@ export class DefaultZLinkSessionContext implements ZLinkSessionContext {
   ): boolean {
     const expected = this.retiredActorBindings.get(actor.actorId);
     if (
-      expected === undefined
-      || expected.actorGeneration !== actor.generation
-      || !sameRetiredSession(expected.retiredSession, retiredSession)
+      expected === undefined ||
+      expected.actorGeneration !== actor.generation ||
+      !sameRetiredSession(expected.retiredSession, retiredSession)
     ) {
       return false;
     }
     const current = this.findBoundActor(actor.actorId);
     if (current === undefined) return true;
     const currentRef = current.ref as ActorRef & { readonly bindingGeneration?: bigint };
-    return BigInt(currentRef.objectGeneration) === actor.generation
-      && currentRef.bindingGeneration === retiredSession.retiredBindingGeneration;
+    return (
+      BigInt(currentRef.objectGeneration) === actor.generation &&
+      currentRef.bindingGeneration === retiredSession.retiredBindingGeneration
+    );
   }
 
   createTextMessage(payload: string): Message {
@@ -340,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 {
@@ -372,13 +401,14 @@ class DefaultZLinkSessionHandlerRegistry implements ZLinkSessionHandlerRegistry
         `Session packet '${packetName}' is already registered.`
       );
     }
-    if (typeof (handlerType as { prototype?: { handle?: unknown } }).prototype?.handle !== 'function') {
+    if (
+      typeof (handlerType as { prototype?: { handle?: unknown } }).prototype?.handle !== 'function'
+    ) {
       throw new TypeError(`Session handler '${handlerType.name}' must implement handle(...).`);
     }
-    this.handlersByPacket.set(
-      packetName,
-      { handlerType: handlerType as Type<ZLinkSessionPacketHandler<ZLinkSessionContext>> }
-    );
+    this.handlersByPacket.set(packetName, {
+      handlerType: handlerType as Type<ZLinkSessionPacketHandler<ZLinkSessionContext>>
+    });
     return this;
   }
 
@@ -386,7 +416,10 @@ class DefaultZLinkSessionHandlerRegistry implements ZLinkSessionHandlerRegistry
     this.registrationOpen = false;
   }
 
-  async tryHandle(dispatch: import('../../contracts').ZLinkSessionDispatchContext, payload: ZLinkMessage): Promise<boolean> {
+  async tryHandle(
+    dispatch: import('../../contracts').ZLinkSessionDispatchContext,
+    payload: ZLinkMessage
+  ): Promise<boolean> {
     const registration = this.handlersByPacket.get(dispatch.packetName);
     if (registration === undefined) {
       return false;
@@ -407,9 +440,11 @@ class DefaultZLinkSessionHandlerRegistry implements ZLinkSessionHandlerRegistry
   private async createHandler(
     handlerType: Type<ZLinkSessionPacketHandler<ZLinkSessionContext>>
   ): Promise<ZLinkSessionPacketHandler<ZLinkSessionContext>> {
-    return this.providerResolver?.get?.(handlerType)
-      ?? await this.providerResolver?.create?.(handlerType)
-      ?? new handlerType();
+    return (
+      this.providerResolver?.get?.(handlerType) ??
+      (await this.providerResolver?.create?.(handlerType)) ??
+      new handlerType()
+    );
   }
 }
 
@@ -420,7 +455,8 @@ interface SessionHandlerRegistration {
 
 function sessionHandlerPacketName(handlerType: new (...args: never[]) => unknown): string {
   const declared = readZLinkDecoratorMetadata(handlerType)
-    .find((metadata) => metadata.kind === 'packet')?.packetName?.trim();
+    .find((metadata) => metadata.kind === 'packet')
+    ?.packetName?.trim();
   if (declared === undefined || declared.length === 0) {
     throw new ZLinkConfigurationException(
       `Session handler '${handlerType.name}' must declare a packet name with @ZLinkPacket(...).`
@@ -489,9 +525,9 @@ export class DefaultZLinkSessionActor implements ZLinkSessionActor {
     }
     if (BigInt(ref.objectGeneration) !== BigInt(this.currentRef.objectGeneration)) {
       throw new Error(
-        `Cannot change session actor '${this.actorId}' object generation `
-          + `from ${String(this.currentRef.objectGeneration)} `
-          + `to ${String(ref.objectGeneration)}.`
+        `Cannot change session actor '${this.actorId}' object generation ` +
+          `from ${String(this.currentRef.objectGeneration)} ` +
+          `to ${String(ref.objectGeneration)}.`
       );
     }
     this.currentRef = ref;
@@ -508,9 +544,7 @@ export class DefaultZLinkSessionActor implements ZLinkSessionActor {
     payloadOrSignal?: ZLinkMessage | AbortSignal,
     signal?: AbortSignal
   ): Promise<void> {
-    const dispatch = isSessionDispatchContext(dispatchOrPayload)
-      ? dispatchOrPayload
-      : undefined;
+    const dispatch = isSessionDispatchContext(dispatchOrPayload) ? dispatchOrPayload : undefined;
     let payload: ZLinkMessage;
     let relaySignal: AbortSignal | undefined;
     let header: ZLinkStreamFrameHeader | undefined;
@@ -537,26 +571,35 @@ export class DefaultZLinkSessionActor implements ZLinkSessionActor {
 
 const SESSION_DISPATCH_HEADERS = new WeakMap<ZLinkSessionDispatchContext, ZLinkStreamFrameHeader>();
 
-export function createSessionDispatchContext(header: ZLinkStreamFrameHeader): ZLinkSessionDispatchContext {
+export function createSessionDispatchContext(
+  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;
 }
 
 function isSessionDispatchContext(value: unknown): value is ZLinkSessionDispatchContext {
-  return value !== null && typeof value === 'object'
-    && typeof (value as ZLinkSessionDispatchContext).packetName === 'string'
-    && 'canReply' in value;
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    typeof (value as ZLinkSessionDispatchContext).packetName === 'string' &&
+    'canReply' in value
+  );
 }
 
 function sessionDispatchHeader(dispatch: ZLinkSessionDispatchContext): ZLinkStreamFrameHeader {
   const header = SESSION_DISPATCH_HEADERS.get(dispatch);
   if (header === undefined) {
-    throw new Error('Session actor relay dispatch must be the context supplied to the active session handler.');
+    throw new Error(
+      'Session actor relay dispatch must be the context supplied to the active session handler.'
+    );
   }
   return header;
 }
@@ -600,10 +643,12 @@ function sameRetiredSession(
   left: ServiceRetiredBoundSessionRouteFence,
   right: ServiceRetiredBoundSessionRouteFence
 ): boolean {
-  return left.sessionOwnerNodeRid === right.sessionOwnerNodeRid
-    && left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration
-    && left.sessionOwnerId === right.sessionOwnerId
-    && left.sessionOwnerLeaseGeneration === right.sessionOwnerLeaseGeneration
-    && left.sessionRid === right.sessionRid
-    && left.retiredBindingGeneration === right.retiredBindingGeneration;
+  return (
+    left.sessionOwnerNodeRid === right.sessionOwnerNodeRid &&
+    left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration &&
+    left.sessionOwnerId === right.sessionOwnerId &&
+    left.sessionOwnerLeaseGeneration === right.sessionOwnerLeaseGeneration &&
+    left.sessionRid === right.sessionRid &&
+    left.retiredBindingGeneration === right.retiredBindingGeneration
+  );
 }

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/session-provider.ts

@@ -1,8 +1,4 @@
-import type {
-  Type,
-  ZLinkSession,
-  ZLinkSessionFactory
-} from '../../contracts';
+import type { Type, ZLinkSession, ZLinkSessionFactory } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { DefaultZLinkSessionContext } from './session-context';
 
@@ -45,6 +41,8 @@ async function createProviderInstance<T>(
 }
 
 function isSessionFactory(value: unknown): value is ZLinkSessionFactory {
-  return typeof (value as { create?: unknown }).create === 'function'
-    && (value as { context?: unknown }).context === undefined;
+  return (
+    typeof (value as { create?: unknown }).create === 'function' &&
+    (value as { context?: unknown }).context === undefined
+  );
 }

package/src/runtime/streams/session-serial-executor.ts

@@ -46,10 +46,12 @@ export class ZLinkSessionSerialExecutor {
 
   executeFinal(work: () => Promise<void>): Promise<void> {
     if (this.closed) {
-      return Promise.reject(createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RuntimeShutdown,
-        'Session execution queue is closed.'
-      ));
+      return Promise.reject(
+        createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RuntimeShutdown,
+          'Session execution queue is closed.'
+        )
+      );
     }
     const boundWork = bindApplicationJobPermit(work);
     return hasApplicationJobPermit()
@@ -69,8 +71,7 @@ export class ZLinkSessionSerialExecutor {
     const submitted = hasApplicationJobPermit()
       ? this.scheduler.submitPreAdmitted(boundWork, serialOptions)
       : this.scheduler.submit(boundWork, serialOptions);
-    void submitted
-      .catch(error => onRejected?.(error));
+    void submitted.catch((error) => onRejected?.(error));
     return true;
   }
 

package/src/runtime/streams/stream-binding-runtime-ports.ts

@@ -6,15 +6,21 @@ import type { ZLinkBoundSessionResponseTarget } from './bound-session-response-t
 
 export interface ZLinkStreamActorLookupPort {
   find(actorId: string): Promise<DefaultZLinkSessionActor | undefined>;
-  authorityFence(actorId: string): Promise<{
-    readonly authorityOwnerGeneration: bigint;
-    readonly ownerLeaseGeneration: bigint;
-  } | undefined>;
-  sessionRouteFence(actorId: string): Promise<{
-    readonly actor: ActorRef;
-    readonly sessionRid: ActorRef['nodeRid'];
-    readonly bindingGeneration: bigint;
-  } | undefined>;
+  authorityFence(actorId: string): Promise<
+    | {
+        readonly authorityOwnerGeneration: bigint;
+        readonly ownerLeaseGeneration: bigint;
+      }
+    | undefined
+  >;
+  sessionRouteFence(actorId: string): Promise<
+    | {
+        readonly actor: ActorRef;
+        readonly sessionRid: ActorRef['nodeRid'];
+        readonly bindingGeneration: bigint;
+      }
+    | undefined
+  >;
 }
 
 export interface ZLinkStreamActorLifecyclePort {
@@ -48,13 +54,22 @@ export interface ZLinkActorRouteCommitOptions {
 }
 
 export interface ZLinkBoundSessionResponsePort {
-  captureBoundSessionResponseTarget(actor: ZLinkSessionActor): Promise<ZLinkBoundSessionResponseTarget | undefined>;
+  captureBoundSessionResponseTarget(
+    actor: ZLinkSessionActor
+  ): Promise<ZLinkBoundSessionResponseTarget | undefined>;
   sendLocalBoundSessionResponse(
-    actorId: string, packetName: string, requestSeq: bigint, message: unknown,
-    metadata: ReadonlyMap<string, string>, compressPayload: boolean
+    actorId: string,
+    packetName: string,
+    requestSeq: bigint,
+    message: unknown,
+    metadata: ReadonlyMap<string, string>,
+    compressPayload: boolean
   ): Promise<boolean>;
   sendLocalBoundSessionError(
-    actorId: string, packetName: string, requestSeq: bigint, error: unknown,
+    actorId: string,
+    packetName: string,
+    requestSeq: bigint,
+    error: unknown,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean>;
 }
@@ -62,45 +77,80 @@ export interface ZLinkBoundSessionResponsePort {
 export interface ZLinkRemoteBoundSessionPort extends ZLinkStreamActorLifecyclePort {
   disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
   sendLocalBoundSession(
-    actorId: string, message: unknown, packetName: string | undefined,
+    actorId: string,
+    message: unknown,
+    packetName: string | undefined,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean>;
   sendLocalBoundSessionResponse(
-    actorId: string, packetName: string, requestSeq: bigint, message: unknown,
-    metadata: ReadonlyMap<string, string>, compressPayload: boolean
+    actorId: string,
+    packetName: string,
+    requestSeq: bigint,
+    message: unknown,
+    metadata: ReadonlyMap<string, string>,
+    compressPayload: boolean
   ): Promise<boolean>;
   sendLocalBoundSessionError(
-    actorId: string, packetName: string, requestSeq: bigint, error: unknown,
+    actorId: string,
+    packetName: string,
+    requestSeq: bigint,
+    error: unknown,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean>;
   sendNativeBoundSessionResponse(
-    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint,
-    message: unknown, metadata: ReadonlyMap<string, string>, compressPayload: boolean,
+    node: ZLinkBackendActorSessionNode,
+    actorRef: ActorRef,
+    packetName: string,
+    requestSeq: bigint,
+    message: unknown,
+    metadata: ReadonlyMap<string, string>,
+    compressPayload: boolean,
     signal?: AbortSignal
   ): Promise<void>;
   sendNativeBoundSessionError(
-    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint,
-    error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+    node: ZLinkBackendActorSessionNode,
+    actorRef: ActorRef,
+    packetName: string,
+    requestSeq: bigint,
+    error: unknown,
+    metadata: ReadonlyMap<string, string>,
+    signal?: AbortSignal
   ): Promise<void>;
 }
 
 export interface ZLinkNativeFallbackBoundSessionPort {
-  disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+  disconnectNativeBoundSession(
+    node: ZLinkBackendActorSessionNode,
+    actorRef: ActorRef,
+    signal?: AbortSignal
+  ): Promise<void>;
   disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
   sendLocalBoundSession(
-    actorId: string, message: unknown, packetName: string | undefined,
+    actorId: string,
+    message: unknown,
+    packetName: string | undefined,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean>;
   submitLocalBoundSession(
-    actorId: string, message: unknown, packetName: string | undefined,
-    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+    actorId: string,
+    message: unknown,
+    packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>,
+    signal?: AbortSignal
   ): Promise<ZLinkSubmitResult>;
   sendNativeBoundSession(
-    node: ZLinkBackendActorSessionNode, actorRef: ActorRef, message: unknown, packetName: string | undefined,
-    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+    node: ZLinkBackendActorSessionNode,
+    actorRef: ActorRef,
+    message: unknown,
+    packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>,
+    signal?: AbortSignal
   ): Promise<ZLinkSubmitResult>;
   sendBoundSession(
-    actorId: string, message: unknown, packetName: string | undefined,
-    metadata: ReadonlyMap<string, string>, signal?: AbortSignal
+    actorId: string,
+    message: unknown,
+    packetName: string | undefined,
+    metadata: ReadonlyMap<string, string>,
+    signal?: AbortSignal
   ): Promise<ZLinkSubmitResult>;
 }