@zlink-systems/framework 0.22.0 → 0.24.0

package/src/runtime/streams/actor-session-binding-registry.ts

@@ -18,7 +18,11 @@ export interface ZLinkActorSessionBindingActor {
 
 export interface ZLinkActorSessionBindingContext<TActor extends ZLinkActorSessionBindingActor> {
   readonly routingId?: unknown;
-  bindLocal(actor: TActor, bindingToken: string): void;
+  readonly actorSlotControls?: {
+    enqueueBound(actorSlot: number, actorId: string): Promise<void>;
+    enqueueUnbound(actorSlot: number): Promise<void>;
+  };
+  bindLocal(actor: TActor, bindingToken: string, actorSlot?: number): void;
   unbindLocal(actorId: string, bindingToken: string): void;
 }
 
@@ -29,6 +33,7 @@ export interface ZLinkActorSessionRoute<
   readonly context: TContext;
   readonly actor: TActor;
   readonly bindingToken: string;
+  readonly actorSlot?: number;
   readonly sessionIdentity?: string;
   readonly activeFrames: ZLinkActorSessionActiveFrames;
   sealId?: string;
@@ -137,12 +142,18 @@ export interface ZLinkActorSessionAuthorityFence {
   readonly actorType?: string;
 }
 
+export enum ZLinkActorSessionBindingTermination {
+  BindingEnd,
+  PhysicalDisconnect
+}
+
 export class ZLinkActorSessionBindingRegistry<
   TContext extends ZLinkActorSessionBindingContext<TActor>,
   TActor extends ZLinkActorSessionBindingActor
 > {
   private readonly lane = new ZLinkStateLane();
   private readonly routes = new Map<string, ZLinkActorSessionRoute<TContext, TActor>>();
+  private readonly nextActorSlots = new WeakMap<TContext, number>();
   private readonly sealWaiters = new Map<
     string,
     Set<{
@@ -164,7 +175,9 @@ export class ZLinkActorSessionBindingRegistry<
     //  (the sealing side) must observe that bound; an unbounded wait here
     //  turns a lost control or a lifecycle interlock into a silent stall
     //  (spec 48:205 — transport/deadline limits apply during relocation).
-    private readonly sealWaitTimeoutMs = 3_000
+    private readonly sealWaitTimeoutMs = 3_000,
+    private readonly errorSink?: () =>
+      { reportRuntimeTaskException(taskName: string, error: unknown): void } | undefined
   ) {
     if (!Number.isSafeInteger(terminalRelocationCapacity) || terminalRelocationCapacity <= 0) {
       throw new RangeError('Session relocation terminal capacity must be a positive safe integer.');
@@ -182,83 +195,120 @@ export class ZLinkActorSessionBindingRegistry<
     actor: TActor,
     bindingToken: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
+    sessionIdentity?: string,
+    commitActor?: () => void
   ): Promise<void> {
     await this.lane.run(() =>
-      this.bindCore(context, actor, bindingToken, authorityFence, sessionIdentity)
+      this.commitCore(
+        undefined,
+        context,
+        actor,
+        bindingToken,
+        authorityFence,
+        sessionIdentity,
+        commitActor
+      )
     );
   }
 
-  private bindCore(
-    context: TContext,
-    actor: TActor,
-    bindingToken: string,
-    authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
-  ): void {
-    this.routes.set(actor.actorId, {
-      context,
-      actor,
-      bindingToken,
-      sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
-      activeFrames: { count: 0, requests: new Set() },
-      authorityFence
-    });
-    context.bindLocal(actor, bindingToken);
-  }
-
-  async replace(
-    previous: ZLinkActorSessionRoute<TContext, TActor>,
+  private async commitCore(
+    previous: ZLinkActorSessionRoute<TContext, TActor> | undefined,
     context: TContext,
     actor: TActor,
     bindingToken: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
+    sessionIdentity?: string,
+    commitActor?: () => void
   ): Promise<void> {
-    await this.lane.run(() =>
-      this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity)
-    );
-  }
-
-  private replaceCore(
-    previous: ZLinkActorSessionRoute<TContext, TActor>,
-    context: TContext,
-    actor: TActor,
-    bindingToken: string,
-    authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
-  ): void {
     const current = this.routes.get(actor.actorId);
     if (current !== previous) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorSessionNotBound,
-        `Actor '${actor.actorId}' session binding changed before route replacement.`,
+        `Actor '${actor.actorId}' session binding changed before route commit.`,
         true
       );
     }
 
-    context.bindLocal(actor, bindingToken);
-    const sameLocalBinding = previous.context === context && previous.bindingToken === bindingToken;
-    if (!sameLocalBinding) {
-      try {
+    const sameBinding =
+      previous !== undefined &&
+      previous.context === context &&
+      previous.bindingToken === bindingToken;
+    const actorSlot = sameBinding ? previous.actorSlot : this.issueActorSlot(context);
+    commitActor?.();
+    context.bindLocal(actor, bindingToken, actorSlot);
+
+    try {
+      if (previous !== undefined && !sameBinding) {
+        this.routes.delete(actor.actorId);
         previous.context.unbindLocal(actor.actorId, previous.bindingToken);
-      } catch (error) {
-        context.unbindLocal(actor.actorId, bindingToken);
-        previous.context.bindLocal(previous.actor, previous.bindingToken);
-        throw error;
+        if (previous.actorSlot !== undefined) {
+          let unbound: Promise<void> | undefined;
+          try {
+            unbound = previous.context.actorSlotControls?.enqueueUnbound(previous.actorSlot);
+          } catch (error) {
+            unbound = Promise.reject(error);
+          }
+          void unbound?.catch((error) =>
+            this.errorSink?.()?.reportRuntimeTaskException('retired session actor unbound', error)
+          );
+        }
       }
+
+      if (!sameBinding && actorSlot !== undefined) {
+        await context.actorSlotControls!.enqueueBound(actorSlot, actor.actorId);
+      }
+    } catch (error) {
+      context.unbindLocal(actor.actorId, bindingToken);
+      throw error;
     }
+
     this.routes.set(actor.actorId, {
       context,
       actor,
       bindingToken,
+      actorSlot,
       sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
-      activeFrames: previous.activeFrames,
-      sealId: previous.sealId,
-      authorityFence: authorityFence ?? previous.authorityFence
+      activeFrames: previous?.activeFrames ?? { count: 0, requests: new Set() },
+      sealId: previous?.sealId,
+      authorityFence: authorityFence ?? previous?.authorityFence
     });
   }
 
+  private issueActorSlot(context: TContext): number | undefined {
+    if (context.actorSlotControls === undefined) return undefined;
+    const actorSlot = this.nextActorSlots.get(context) ?? 1;
+    if (actorSlot > 0xffff) {
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        `Stream session '${String(context.routingId)}' exhausted its Actor slots.`
+      );
+    }
+    this.nextActorSlots.set(context, actorSlot + 1);
+    return actorSlot;
+  }
+
+  async replace(
+    previous: ZLinkActorSessionRoute<TContext, TActor>,
+    context: TContext,
+    actor: TActor,
+    bindingToken: string,
+    authorityFence?: ZLinkActorSessionAuthorityFence,
+    sessionIdentity?: string,
+    commitActor?: () => void
+  ): Promise<void> {
+    await this.lane.run(() =>
+      this.commitCore(
+        previous,
+        context,
+        actor,
+        bindingToken,
+        authorityFence,
+        sessionIdentity,
+        commitActor
+      )
+    );
+  }
+
   async replaceAndReleaseSeal(
     previous: ZLinkActorSessionRoute<TContext, TActor>,
     context: TContext,
@@ -266,7 +316,8 @@ export class ZLinkActorSessionBindingRegistry<
     bindingToken: string,
     sealId: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
+    sessionIdentity?: string,
+    commitActor?: () => void
   ): Promise<void> {
     await this.lane.run(() =>
       this.replaceAndReleaseSealCore(
@@ -276,20 +327,22 @@ export class ZLinkActorSessionBindingRegistry<
         bindingToken,
         sealId,
         authorityFence,
-        sessionIdentity
+        sessionIdentity,
+        commitActor
       )
     );
   }
 
-  private replaceAndReleaseSealCore(
+  private async replaceAndReleaseSealCore(
     previous: ZLinkActorSessionRoute<TContext, TActor>,
     context: TContext,
     actor: TActor,
     bindingToken: string,
     sealId: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string
-  ): void {
+    sessionIdentity?: string,
+    commitActor?: () => void
+  ): Promise<void> {
     if (previous.sealId !== sealId) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorLocationStale,
@@ -300,7 +353,15 @@ export class ZLinkActorSessionBindingRegistry<
     // JavaScript cannot interleave another ingress turn between these two
     // synchronous mutations. The replacement preserves the seal, then the
     // exact release publishes the route to held ingress as one owner turn.
-    this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity);
+    await this.commitCore(
+      previous,
+      context,
+      actor,
+      bindingToken,
+      authorityFence,
+      sessionIdentity,
+      commitActor
+    );
     if (!this.abortSealCore(actor.actorId, sealId)) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorLocationStale,
@@ -348,11 +409,21 @@ export class ZLinkActorSessionBindingRegistry<
     return Object.freeze({ context: route.context });
   }
 
-  async unbind(actorId: string, context: TContext, bindingToken: string): Promise<void> {
-    await this.lane.run(() => this.unbindCore(actorId, context, bindingToken));
+  async unbind(
+    actorId: string,
+    context: TContext,
+    bindingToken: string,
+    termination = ZLinkActorSessionBindingTermination.BindingEnd
+  ): Promise<void> {
+    await this.lane.run(() => this.unbindCore(actorId, context, bindingToken, termination));
   }
 
-  private unbindCore(actorId: string, context: TContext, bindingToken: string): void {
+  private async unbindCore(
+    actorId: string,
+    context: TContext,
+    bindingToken: string,
+    termination: ZLinkActorSessionBindingTermination
+  ): Promise<void> {
     const route = this.routes.get(actorId);
     if (route === undefined || route.context !== context || route.bindingToken !== bindingToken) {
       return;
@@ -372,28 +443,44 @@ export class ZLinkActorSessionBindingRegistry<
       route,
       new Error(`Actor '${actorId}' session binding was removed.`)
     );
+    if (
+      termination === ZLinkActorSessionBindingTermination.BindingEnd &&
+      route.actorSlot !== undefined
+    ) {
+      await context.actorSlotControls?.enqueueUnbound(route.actorSlot);
+    }
   }
 
   async unbindActor(actorId: string): Promise<void> {
     await this.lane.run(() => this.unbindActorCore(actorId));
   }
 
-  private unbindActorCore(actorId: string): void {
+  private async unbindActorCore(actorId: string): Promise<void> {
     const route = this.routes.get(actorId);
     if (route === undefined) {
       return;
     }
-    this.unbindCore(actorId, route.context, route.bindingToken);
+    await this.unbindCore(
+      actorId,
+      route.context,
+      route.bindingToken,
+      ZLinkActorSessionBindingTermination.BindingEnd
+    );
   }
 
   async cleanup(context: TContext): Promise<void> {
     await this.lane.run(() => this.cleanupCore(context));
   }
 
-  private cleanupCore(context: TContext): void {
+  private async cleanupCore(context: TContext): Promise<void> {
     for (const route of [...this.routes.values()]) {
       if (route.context === context) {
-        this.unbindCore(route.actor.actorId, context, route.bindingToken);
+        await this.unbindCore(
+          route.actor.actorId,
+          context,
+          route.bindingToken,
+          ZLinkActorSessionBindingTermination.PhysicalDisconnect
+        );
       }
     }
   }

package/src/runtime/streams/actor-session-binding-runtime-owner.ts

@@ -13,6 +13,7 @@ import type {
 } from './actor-session-binding-registry';
 
 export interface ZLinkActorSessionBindingRuntimeOwner {
+  actorSlot(actorId: string, sessionRid: string): Promise<number | undefined>;
   sealRelocation(
     claim: ZLinkActorSessionRelocationClaim,
     expected: ZLinkActorSessionRouteFence,

package/src/runtime/streams/bound-actor-relay-sender.ts

@@ -10,7 +10,10 @@ import {
 } from './protocol';
 import { throwIfAborted } from '../abort';
 import { captureZLinkExecutionTurn } from '../execution';
-import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
+import {
+  ZLinkActorSessionBindingRegistry,
+  ZLinkActorSessionBindingTermination
+} from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { ZLinkManagedStream } from './managed-stream';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
@@ -246,7 +249,12 @@ export class ZLinkBoundActorRelaySender {
           // The transport is already closed, so remove its exact route before
           // invoking application lifecycle code. A reconnect can then install
           // a successor while this best-effort notification is in flight.
-          await this.routes.unbind(actor.actorId, context, actor.bindingToken);
+          await this.routes.unbind(
+            actor.actorId,
+            context,
+            actor.bindingToken,
+            ZLinkActorSessionBindingTermination.PhysicalDisconnect
+          );
           return true;
         });
         if (!detached) return;

package/src/runtime/streams/bound-session-response-target.ts

@@ -1,4 +1,7 @@
 import type { Message } from '../../contracts/Common/Message';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
+import { channelErrorCodeName } from '../channels/channel-envelope';
+import { ZLinkRouteDisconnectedError } from '../channels/route-disconnected-error';
 import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import { ZLinkStreamMessageKind } from './protocol';
 import type { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
@@ -96,7 +99,13 @@ export function boundSessionErrorPayload(error: unknown): {
   readonly message: string;
 } {
   return {
-    code: error instanceof Error ? error.constructor.name : 'RemoteError',
+    code: channelErrorCodeName(
+      error instanceof ZLinkFrameworkException
+        ? error.kind
+        : error instanceof ZLinkRouteDisconnectedError
+          ? ZLinkFrameworkErrorKind.Unavailable
+          : ZLinkFrameworkErrorKind.InternalFailure
+    ),
     message: errorMessage(error)
   };
 }

package/src/runtime/streams/bound-session-service.ts

@@ -87,7 +87,9 @@ export class ZLinkBoundSessionService {
       metadata,
       false,
       undefined,
-      message
+      message,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       const result = await this.requireTransport().send(actorId, frame, {
@@ -120,7 +122,9 @@ export class ZLinkBoundSessionService {
       metadata,
       false,
       undefined,
-      message
+      message,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       throwIfAborted(signal);
@@ -348,7 +352,9 @@ export class ZLinkBoundSessionService {
       metadata,
       compressPayload,
       requestSeq,
-      payload
+      payload,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
@@ -448,6 +454,10 @@ export class ZLinkBoundSessionService {
     }
     return this.options.transport;
   }
+
+  private actorSlot(route: ZLinkStreamActorSessionRoute): number | undefined {
+    return route.actorSlot;
+  }
 }
 
 function requireBoundSessionGeneration(actorRef: ActorRef): bigint {

package/src/runtime/streams/index.ts

@@ -264,6 +264,7 @@ export class ZLinkStreamRuntimeManager {
           const service = createService.call(meshNode, socket.nativeInstance as never);
           const bindingOwner = actorSessionBindingRuntimeOwner(this.options.bindingRuntime);
           registerServiceSessionBindingIngressPort(service, {
+            actorSlot: (actorId, sessionRid) => bindingOwner.actorSlot(actorId, sessionRid),
             retainOutbound: (claim, delivery) =>
               bindingOwner.admitRelocationOutbound(claim, delivery),
             clearOutbound: (actorId, error) => bindingOwner.clearRelocation(actorId, error)
@@ -419,7 +420,7 @@ export class ZLinkStreamBindingRuntime {
     this.routes = new ZLinkActorSessionBindingRegistry<
       DefaultZLinkSessionContext,
       DefaultZLinkSessionActor
-    >(4096, 4096, runtimeOptions.sessionRelocationSealTimeoutMs ?? 3_000);
+    >(4096, 4096, runtimeOptions.sessionRelocationSealTimeoutMs ?? 3_000, runtimeOptions.errorSink);
     this.compressionCodec = resolveStreamCompressionCodec(runtimeOptions.streamCompression);
     this.frameMessages = new ZLinkStreamFrameMessageFactory(runtimeOptions);
     this.boundSessions = new ZLinkBoundSessionService(
@@ -441,6 +442,12 @@ export class ZLinkStreamBindingRuntime {
       actorSessionLifecycle
     );
     registerActorSessionBindingRuntimeOwner(this, {
+      actorSlot: async (actorId, sessionRid) => {
+        const route = await this.routes.route(actorId);
+        return route !== undefined && route.sessionIdentity === sessionRid
+          ? route.actorSlot
+          : undefined;
+      },
       sealRelocation: (claim, expected, signal) =>
         this.routes.sealRelocation(claim, expected, signal),
       relocationSnapshot: (actorId, sealId) => this.routes.relocationSnapshot(actorId, sealId),

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

@@ -33,6 +33,8 @@ import {
   type ZLinkMeshCompletionTable
 } from '../backend/mesh-completion-table';
 import {
+  encodeActorBoundFrame,
+  encodeActorUnboundFrame,
   encodeSessionClosingFrame,
   encodeStreamControlFrame,
   ZLinkStreamCloseReasonCode
@@ -51,18 +53,17 @@ export interface ZLinkNativeSessionRoute {
   readonly completions: ZLinkMeshCompletionTable;
 }
 
+interface ZLinkManagedActorBinding {
+  readonly actor: ZLinkBackendActorRef;
+  readonly bindingGeneration?: bigint;
+  readonly route?: ZLinkNativeSessionRoute;
+}
+
 export class ZLinkManagedStream implements ZLinkStream {
   private currentLocalAddr: string | undefined;
   private currentRemoteAddr: string | undefined;
   private transportClosed = false;
-  private readonly nativeActorBindings = new Map<
-    string,
-    {
-      readonly actor: ZLinkBackendActorRef;
-      readonly bindingGeneration: bigint;
-      readonly route?: ZLinkNativeSessionRoute;
-    }
-  >();
+  private readonly nativeActorBindings = new Map<string, ZLinkManagedActorBinding>();
 
   constructor(
     private readonly socket: ZLinkBackendStreamSocket,
@@ -195,12 +196,12 @@ export class ZLinkManagedStream implements ZLinkStream {
         `Stream session '${this.sessionId}' is disconnected.`
       );
     }
+    const nativeActor = toNativeActorRef(actor);
     const route = this.nativeRoute(actor.meshName);
     if (route !== undefined) {
       if (route.service.status().state === 1) {
         route.service.start();
       }
-      const nativeActor = toNativeActorRef(actor);
       await this.ensureNativeActorRoute(route, actor, timeoutMs, signal);
       if (this.isTransportClosed()) {
         throw createInternalFrameworkException(
@@ -278,6 +279,7 @@ export class ZLinkManagedStream implements ZLinkStream {
       timeoutMs,
       signal
     );
+    this.nativeActorBindings.set(actor.actorId, { actor: nativeActor });
   }
 
   private async ensureNativeActorRoute(
@@ -327,7 +329,7 @@ export class ZLinkManagedStream implements ZLinkStream {
     const binding = this.nativeActorBindings.get(actorId);
     if (binding?.route !== undefined) {
       const route = binding.route;
-      if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration)) {
+      if (!this.hasNativeBinding(route, actorId, binding.bindingGeneration!)) {
         this.nativeActorBindings.delete(actorId);
         return;
       }
@@ -338,7 +340,7 @@ export class ZLinkManagedStream implements ZLinkStream {
               route.service.unbindActor(
                 this.backendRoutingId(),
                 binding.actor as never,
-                binding.bindingGeneration,
+                binding.bindingGeneration!,
                 timeoutMs
               ),
             signal
@@ -354,7 +356,7 @@ export class ZLinkManagedStream implements ZLinkStream {
         // 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, binding.bindingGeneration!)) {
           throw error;
         }
       }
@@ -364,6 +366,26 @@ export class ZLinkManagedStream implements ZLinkStream {
       return;
     }
     await this.socket.unbindActor(this.backendRoutingId(), actorId, timeoutMs, signal);
+    if (binding !== undefined && this.nativeActorBindings.get(actorId) === binding) {
+      this.nativeActorBindings.delete(actorId);
+    }
+  }
+
+  async enqueueActorBound(actorSlot: number, actorId: string): Promise<void> {
+    await this.submitActorBindingControl(encodeActorBoundFrame(actorSlot, actorId));
+  }
+
+  async enqueueActorUnbound(actorSlot: number): Promise<void> {
+    await this.submitActorBindingControl(encodeActorUnboundFrame(actorSlot));
+  }
+
+  private async submitActorBindingControl(frame: Uint8Array): Promise<void> {
+    const message = NativeMessage.from(frame);
+    try {
+      await this.socket.submit(this.backendRoutingId(), message);
+    } finally {
+      message.close();
+    }
   }
 
   async sendBoundActor(