@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/spots/spot-routed-frame-dispatch.ts

@@ -8,14 +8,8 @@ import type {
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { RoutingId } from '../../contracts';
 import type { ActorRef } from '../../contracts/Common/ActorRef';
-import type {
-  ZLinkRemoteActorPacketTarget,
-  ZLinkRemoteBoundSessionTarget
-} from '../actors';
-import type {
-  ZLinkBackendReceived,
-  ZLinkBackendSpot
-} from '../backend/contracts';
+import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkBackendReceived, ZLinkBackendSpot } from '../backend/contracts';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkChannelEnvelopeCodecRegistry } from '../channels/channel-envelope';
 import { decodeRemoteActorPacketRelay } from './spot-remote-route-codec';
@@ -79,7 +73,9 @@ interface ZLinkSpotRoutedFrameDispatchOptions {
     actorPacketTarget?: unknown,
     signal?: AbortSignal
   ) => Promise<void>;
-  readonly actorPacketTargetProvider?: (actorId: string) => ZLinkRemoteActorPacketTarget | undefined;
+  readonly actorPacketTargetProvider?: (
+    actorId: string
+  ) => ZLinkRemoteActorPacketTarget | undefined;
   readonly bindRemoteSession?: (
     actor: ActorRef,
     sourceNodeRid: RoutingId,
@@ -148,7 +144,10 @@ export class ZLinkSpotRoutedFrameDispatch {
     }
   }
 
-  async drain(received: ZLinkBackendReceived | undefined = undefined, retryDeadlineMs = performance.now()): Promise<void> {
+  async drain(
+    received: ZLinkBackendReceived | undefined = undefined,
+    retryDeadlineMs = performance.now()
+  ): Promise<void> {
     if (this.routeDraining) {
       if (received !== undefined) {
         try {
@@ -226,7 +225,10 @@ export class ZLinkSpotRoutedFrameDispatch {
       this.channelCodecs(),
       this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true
     );
-    if (actorPacketRelay !== undefined && await this.actorPacketRelayDispatch.dispatch(received, actorPacketRelay)) {
+    if (
+      actorPacketRelay !== undefined &&
+      (await this.actorPacketRelayDispatch.dispatch(received, actorPacketRelay))
+    ) {
       return;
     }
     if (await this.routePacketDispatch.dispatch(received)) {
@@ -237,14 +239,15 @@ export class ZLinkSpotRoutedFrameDispatch {
 }
 
 function isRouteRecvRetryable(error: unknown): boolean {
-  return typeof error === 'object' &&
+  return (
+    typeof error === 'object' &&
     error !== null &&
-    [201, 202, 204].includes(Number((error as { result?: unknown }).result));
+    [201, 202, 204].includes(Number((error as { result?: unknown }).result))
+  );
 }
 
 function closeReceivedQuietly(received: ZLinkBackendReceived): void {
   try {
     received.close();
-  } catch {
-  }
+  } catch {}
 }

package/src/runtime/spots/spot-routed-spot-packet-dispatch.ts

@@ -84,7 +84,7 @@ export class ZLinkRoutedSpotPacketDispatch {
     request: unknown,
     context: ZLinkRoutedSpotPacketContext
   ): Promise<TReply> {
-    return await this.dispatch(spotId, packetName, () => request, context, true) as TReply;
+    return (await this.dispatch(spotId, packetName, () => request, context, true)) as TReply;
   }
 
   async requestEncoded<TReply>(
@@ -93,7 +93,7 @@ export class ZLinkRoutedSpotPacketDispatch {
     decodePayload: () => unknown,
     context: ZLinkRoutedSpotPacketContext
   ): Promise<TReply> {
-    return await this.dispatch(spotId, packetName, decodePayload, context, true) as TReply;
+    return (await this.dispatch(spotId, packetName, decodePayload, context, true)) as TReply;
   }
 
   private async dispatch(
@@ -112,10 +112,13 @@ export class ZLinkRoutedSpotPacketDispatch {
       throw new ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
     }
 
-    const registrations = activation.handlers.snapshot().filter((registration) =>
-      registration.kind === 'packet' &&
-      (registration.packetName ?? registration.handlerType.name) === (packetName ?? '')
-    );
+    const registrations = activation.handlers
+      .snapshot()
+      .filter(
+        (registration) =>
+          registration.kind === 'packet' &&
+          (registration.packetName ?? registration.handlerType.name) === (packetName ?? '')
+      );
     if (registrations.length === 0) {
       this.reportMissing(spotId, packetName, context, returnResponse);
       if (!returnResponse) {
@@ -128,16 +131,18 @@ export class ZLinkRoutedSpotPacketDispatch {
     let detached = false;
     let resolveFirstHandlerTurn: (() => void) | undefined;
     let rejectFirstHandlerTurn: ((error: unknown) => void) | undefined;
-    const firstHandlerTurn = context.awaitFirstHandlerTurn === true
-      ? new Promise<void>((resolve, reject) => {
-        resolveFirstHandlerTurn = resolve;
-        rejectFirstHandlerTurn = reject;
-      })
-      : undefined;
+    const firstHandlerTurn =
+      context.awaitFirstHandlerTurn === true
+        ? new Promise<void>((resolve, reject) => {
+            resolveFirstHandlerTurn = resolve;
+            rejectFirstHandlerTurn = reject;
+          })
+        : undefined;
     void firstHandlerTurn?.catch(() => undefined);
-    const applicationClaim = activation.meshName === undefined
-      ? undefined
-      : this.options.claimApplicationWork?.(activation.meshName);
+    const applicationClaim =
+      activation.meshName === undefined
+        ? undefined
+        : this.options.claimApplicationWork?.(activation.meshName);
     const runHandler = async () => {
       try {
         // Decode only after the Spot has acquired both application admission
@@ -147,8 +152,8 @@ export class ZLinkRoutedSpotPacketDispatch {
           const handler = await resolveLifecycleHandler(
             activation.spot,
             registration.handlerType as Type<
-              ZLinkSpotPacketHandler<ZLinkSpot, unknown> |
-              ZLinkSpotRequestHandler<ZLinkSpot, unknown, unknown>
+              | ZLinkSpotPacketHandler<ZLinkSpot, unknown>
+              | ZLinkSpotRequestHandler<ZLinkSpot, unknown, unknown>
             >,
             this.options.providerResolver
           );
@@ -217,16 +222,18 @@ export class ZLinkRoutedSpotPacketDispatch {
     returnResponse: boolean,
     error: unknown
   ): void {
-    const frameworkErrorKind = error instanceof ZLinkFrameworkException
-      ? internalFrameworkErrorKind(error)
-      : undefined;
+    const frameworkErrorKind =
+      error instanceof ZLinkFrameworkException ? internalFrameworkErrorKind(error) : undefined;
     this.options.dispatchErrors?.report({
       surface: ZLinkDispatchErrorSurface.SpotRoute,
-      messageKind: returnResponse ? ZLinkDispatchMessageKind.Request : ZLinkDispatchMessageKind.Send,
-      reason: frameworkErrorKind === ZLinkFrameworkInternalErrorKind.WorkerQueueFull
-        || frameworkErrorKind === ZLinkFrameworkInternalErrorKind.DeadlineExceeded
-        ? ZLinkDispatchErrorReason.Backpressure
-        : ZLinkDispatchErrorReason.HandlerException,
+      messageKind: returnResponse
+        ? ZLinkDispatchMessageKind.Request
+        : ZLinkDispatchMessageKind.Send,
+      reason:
+        frameworkErrorKind === ZLinkFrameworkInternalErrorKind.WorkerQueueFull ||
+        frameworkErrorKind === ZLinkFrameworkInternalErrorKind.DeadlineExceeded
+          ? ZLinkDispatchErrorReason.Backpressure
+          : ZLinkDispatchErrorReason.HandlerException,
       action: returnResponse ? ZLinkDispatchErrorAction.FailCaller : ZLinkDispatchErrorAction.Drop,
       packetName,
       channelName: context.channelName,
@@ -243,7 +250,9 @@ export class ZLinkRoutedSpotPacketDispatch {
   ): void {
     this.options.dispatchErrors?.report({
       surface: ZLinkDispatchErrorSurface.SpotRoute,
-      messageKind: returnResponse ? ZLinkDispatchMessageKind.Request : ZLinkDispatchMessageKind.Send,
+      messageKind: returnResponse
+        ? ZLinkDispatchMessageKind.Request
+        : ZLinkDispatchMessageKind.Send,
       reason: ZLinkDispatchErrorReason.HandlerMissing,
       action: returnResponse ? ZLinkDispatchErrorAction.FailCaller : ZLinkDispatchErrorAction.Drop,
       packetName,

package/src/runtime/spots/spot-routing-internal.ts

@@ -1,8 +1,5 @@
 import type { RoutingId } from '../../contracts/Common';
-import type {
-  ZLinkFrameworkRuntimeState,
-  ZLinkSpotKind
-} from '../../contracts';
+import type { ZLinkFrameworkRuntimeState, ZLinkSpotKind } from '../../contracts';
 
 export interface ZLinkSpotRouteResolver {
   resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget>;

package/src/runtime/spots/spot-runtime-ports.ts

@@ -106,10 +106,7 @@ export interface ZLinkSpotActorTransferRuntime {
   bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
   commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
   clearRoutedActor(actor: ZLinkActor): void;
-  rollbackNativeActorJoin(
-    actor: ZLinkActor,
-    snapshot: ZLinkNativeActorJoinSnapshot
-  ): Promise<void>;
+  rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
   rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
   notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
   actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
@@ -154,7 +151,10 @@ export interface ZLinkSpotBoundSessionRuntime {
     actorPacketTarget?: unknown,
     signal?: AbortSignal
   ): Promise<void>;
-  rememberRemoteBoundSessionTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
+  rememberRemoteBoundSessionTarget(
+    actorId: string,
+    target: ZLinkRemoteBoundSessionTarget | undefined
+  ): void;
   resolveRemoteBoundSessionTarget(
     sourceNodeRid: RoutingId,
     sourceSessionRid: RoutingId

package/src/runtime/spots/spot-serial-executor.ts

@@ -72,9 +72,8 @@ export class ZLinkSpotSerialExecutor {
   ): readonly Promise<void>[] {
     const serial = this.actorSerial(actorId);
     return this.actorExecutor(actorId).admitDurablePrefix(
-      records.map(record => ({
-        operation: executeChild =>
-          record.operation(child => executeChild(() => child(serial))),
+      records.map((record) => ({
+        operation: (executeChild) => record.operation((child) => executeChild(() => child(serial))),
         preparation: record.preparation,
         workOptions: record.workOptions
       }))
@@ -110,18 +109,15 @@ export class ZLinkSpotSerialExecutor {
   close(): Promise<void> {
     if (this.closePromise !== undefined) return this.closePromise;
     this.closing = true;
-    const childSerials = [
-      ...this.actorSerials.values(),
-      ...this.timerSerials.values()
-    ];
+    const childSerials = [...this.actorSerials.values(), ...this.timerSerials.values()];
     const actorExecutors = [...this.actorExecutors.values()];
     this.actorSerials.clear();
     this.timerSerials.clear();
     this.actorExecutors.clear();
     this.closePromise = Promise.all([
       this.spotSerial.close(),
-      ...childSerials.map(serial => serial.close()),
-      ...actorExecutors.map(executor => executor.close())
+      ...childSerials.map((serial) => serial.close()),
+      ...actorExecutors.map((executor) => executor.close())
     ]).then(() => undefined);
     return this.closePromise;
   }

package/src/runtime/spots/spot-serial-turn-executor.ts

@@ -69,18 +69,14 @@ export class ZLinkSpotSerialTurnExecutor {
 
   /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
   isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean {
-    return this.depth > 0
-      && (
-        this.resumedOwnerTurn === turn
-        || (turnId === this.activeTurnId && !turn.isSuspended)
-      );
+    return (
+      this.depth > 0 &&
+      (this.resumedOwnerTurn === turn || (turnId === this.activeTurnId && !turn.isSuspended))
+    );
   }
 
   setExecutionBarrier(barrier: ZLinkExecutionBarrier): void {
-    if (
-      this.executionBarrier !== undefined
-      && this.executionBarrier !== barrier
-    ) {
+    if (this.executionBarrier !== undefined && this.executionBarrier !== barrier) {
       throw new Error('ZLink Spot serial executor already belongs to another execution barrier.');
     }
     if (this.turnSequence !== 0 && this.executionBarrier === undefined) {
@@ -90,10 +86,7 @@ export class ZLinkSpotSerialTurnExecutor {
   }
 
   /** Runs `operation` in serial order, one turn at a time. */
-  execute<T>(
-    operation: () => Promise<T> | T,
-    workOptions?: ZLinkSerialWorkOptions
-  ): Promise<T> {
+  execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
     if (this.isCurrentTurn) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.InvalidOperation,
@@ -108,10 +101,7 @@ export class ZLinkSpotSerialTurnExecutor {
    * from within the currently active turn. Detached completion callbacks use
    * this so they never run inline inside another callback's turn.
    */
-  post<T>(
-    operation: () => Promise<T> | T,
-    workOptions?: ZLinkSerialWorkOptions
-  ): Promise<T> {
+  post<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
     return this.enqueueApplicationTurn(operation, workOptions);
   }
 
@@ -142,7 +132,7 @@ export class ZLinkSpotSerialTurnExecutor {
       const submitted = hasApplicationJobPermit()
         ? this.scheduler.submitPreAdmitted(boundOperation, options, barrierClaim)
         : this.scheduler.submit(boundOperation, options, barrierClaim);
-      void submitted.catch(error => {
+      void submitted.catch((error) => {
         barrierClaim?.release();
         onError(error);
       });
@@ -194,9 +184,7 @@ export class ZLinkSpotSerialTurnExecutor {
     return await this.submitQueuedTurn(operation, workOptions);
   }
 
-  private async enqueueContinuationTurn<T>(
-    operation: () => Promise<T> | T
-  ): Promise<T> {
+  private async enqueueContinuationTurn<T>(operation: () => Promise<T> | T): Promise<T> {
     this.lastActivityAtMs = performance.now();
     await Promise.resolve();
     return await this.scheduler.submitContinuation(operation);
@@ -274,7 +262,10 @@ export class ZLinkSpotSerialTurnExecutor {
     );
     owner.then(resolve, reject);
     return Promise.race([
-      owner.then(() => undefined, () => undefined),
+      owner.then(
+        () => undefined,
+        () => undefined
+      ),
       turn.suspended
     ]);
   }
@@ -287,10 +278,12 @@ export class ZLinkSpotSerialTurnExecutor {
     const barrier = this.executionBarrier;
     const resumeClaim = barrier?.tryEnter();
     if (barrier !== undefined && resumeClaim === undefined) {
-      reject(createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.SpotMoving,
-        'The yielded Spot turn cannot resume after its execution unit was sealed.'
-      ));
+      reject(
+        createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.SpotMoving,
+          'The yielded Spot turn cannot resume after its execution unit was sealed.'
+        )
+      );
       return true;
     }
     turn.bindExecutionClaim(resumeClaim);

package/src/runtime/spots/spot-subscription-dispatch.ts

@@ -59,9 +59,11 @@ export class ZLinkSpotSubscriptionDispatch {
 
   configure(registrations: readonly ZLinkSpotHandlerRegistration[]): void {
     for (const registration of registrations) {
-      if (registration.kind !== 'subscribe'
-        || registration.channelName === undefined
-        || registration.topic === undefined) {
+      if (
+        registration.kind !== 'subscribe' ||
+        registration.channelName === undefined ||
+        registration.topic === undefined
+      ) {
         continue;
       }
       const key = subscriptionKey(registration.channelName, registration.topic);
@@ -163,7 +165,9 @@ export class ZLinkSpotSubscriptionDispatch {
       });
       return;
     }
-    const registrations = this.handlers.get(subscriptionKey(envelope.header.channelName, message.topic));
+    const registrations = this.handlers.get(
+      subscriptionKey(envelope.header.channelName, message.topic)
+    );
     if (registrations === undefined || registrations.length === 0) {
       this.options.dispatchErrors?.report({
         surface: ZLinkDispatchErrorSurface.SpotSubscription,
@@ -183,52 +187,59 @@ export class ZLinkSpotSubscriptionDispatch {
     const inboundFlow = createInboundFlow(
       envelope.header.flowId,
       envelope.header.flowOrigin,
-      this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+      this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true,
+      undefined
     );
     try {
-      await this.options.serial.execute(() => runWithFlow(inboundFlow, async () => {
-        // Payload deserialization belongs to the Spot serial turn. Queue
-        // admission and execution authority therefore precede this work.
-        const event = decodeChannelPayload(envelope, this.channelCodecs());
-        for (const registration of registrations) {
-          const handler = await resolveLifecycleHandler(
-            spot,
-            registration.handlerType as Type<ZLinkSpotSubscriptionHandler<ZLinkSpot, unknown>>,
-            this.options.providerResolver
-          );
-          try {
-            await handler.handle(spot, event, {
-              channelName: envelope.header.channelName,
-              contentType: envelope.header.contentType,
-              packetName: envelope.packetName!,
-              topic: message.topic,
-              source: subSource,
-              metadata: zlinkMessageMetadata(envelope.header.metadata),
-              correlationId: envelope.header.correlationId ?? undefined
-            });
-          } catch (error) {
-            this.options.dispatchErrors?.report({
-              surface: ZLinkDispatchErrorSurface.SpotSubscription,
-              messageKind: ZLinkDispatchMessageKind.Send,
-              reason: ZLinkDispatchErrorReason.HandlerException,
-              action: ZLinkDispatchErrorAction.Drop,
-              packetName: envelope.packetName,
-              channelName: envelope.header.channelName,
-              topic: message.topic,
-              sourceRid: message.routingId === null ? undefined : String(message.routingId),
-              correlationId: envelope.header.correlationId ?? undefined,
-              error
-            });
-            throw error;
-          }
-        }
-      }), zlinkSerialWorkOptions(
-        envelope.payload.byteLength,
-        zlinkMetadataByteLength(envelope.header.metadata)
-      ));
+      await this.options.serial.execute(
+        () =>
+          runWithFlow(inboundFlow, async () => {
+            // Payload deserialization belongs to the Spot serial turn. Queue
+            // admission and execution authority therefore precede this work.
+            const event = decodeChannelPayload(envelope, this.channelCodecs());
+            for (const registration of registrations) {
+              const handler = await resolveLifecycleHandler(
+                spot,
+                registration.handlerType as Type<ZLinkSpotSubscriptionHandler<ZLinkSpot, unknown>>,
+                this.options.providerResolver
+              );
+              try {
+                await handler.handle(spot, event, {
+                  channelName: envelope.header.channelName,
+                  contentType: envelope.header.contentType,
+                  packetName: envelope.packetName!,
+                  topic: message.topic,
+                  source: subSource,
+                  metadata: zlinkMessageMetadata(envelope.header.metadata),
+                  correlationId: envelope.header.correlationId ?? undefined
+                });
+              } catch (error) {
+                this.options.dispatchErrors?.report({
+                  surface: ZLinkDispatchErrorSurface.SpotSubscription,
+                  messageKind: ZLinkDispatchMessageKind.Send,
+                  reason: ZLinkDispatchErrorReason.HandlerException,
+                  action: ZLinkDispatchErrorAction.Drop,
+                  packetName: envelope.packetName,
+                  channelName: envelope.header.channelName,
+                  topic: message.topic,
+                  sourceRid: message.routingId === null ? undefined : String(message.routingId),
+                  correlationId: envelope.header.correlationId ?? undefined,
+                  error
+                });
+                throw error;
+              }
+            }
+          }),
+        zlinkSerialWorkOptions(
+          envelope.payload.byteLength,
+          zlinkMetadataByteLength(envelope.header.metadata)
+        )
+      );
     } catch (error) {
-      if (error instanceof ZLinkFrameworkException
-        && internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed) {
+      if (
+        error instanceof ZLinkFrameworkException &&
+        internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed
+      ) {
         this.options.dispatchErrors?.report({
           surface: ZLinkDispatchErrorSurface.SpotSubscription,
           messageKind: ZLinkDispatchMessageKind.Send,