@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/host/application-job-queue.ts

@@ -9,11 +9,7 @@ import {
   type ApplicationJobReceiveFlowTarget
 } from '../application-jobs/receive-flow-controller';
 
-export type ApplicationJobQueueProfileValue =
-  | 'compact'
-  | 'low_latency'
-  | 'balanced'
-  | 'throughput';
+export type ApplicationJobQueueProfileValue = 'compact' | 'low_latency' | 'balanced' | 'throughput';
 
 export interface ApplicationJobQueueOptions {
   readonly profile?: ApplicationJobQueueProfileValue;
@@ -79,35 +75,29 @@ export function resolveApplicationJobQueueConfiguration(
   }
 
   const configuredManualMax = options.maxQueuedApplicationJobs;
-  if (configuredManualMax !== undefined
-      && (typeof configuredManualMax !== 'bigint'
-        || configuredManualMax < 1n
-        || configuredManualMax > MAX_QUEUED_APPLICATION_JOBS)) {
-    throw new RangeError(
-      'maxQueuedApplicationJobs must be a bigint in the range 1..2147483647.'
-    );
+  if (
+    configuredManualMax !== undefined &&
+    (typeof configuredManualMax !== 'bigint' ||
+      configuredManualMax < 1n ||
+      configuredManualMax > MAX_QUEUED_APPLICATION_JOBS)
+  ) {
+    throw new RangeError('maxQueuedApplicationJobs must be a bigint in the range 1..2147483647.');
   }
 
   const processors = effectiveProcessorCount();
   if (typeof processors !== 'bigint' || processors < 1n) {
     throw new RangeError('effectiveProcessorCount must be a positive bigint.');
   }
-  const effectiveMax = configuredManualMax
-    ?? JOBS_PER_PROCESSOR[configuredProfile] * processors;
+  const effectiveMax = configuredManualMax ?? JOBS_PER_PROCESSOR[configuredProfile] * processors;
   if (effectiveMax < 1n || effectiveMax > MAX_QUEUED_APPLICATION_JOBS) {
-    throw new RangeError(
-      'Application job queue profile calculation exceeds the supported range.'
-    );
+    throw new RangeError('Application job queue profile calculation exceeds the supported range.');
   }
 
-  const configuredPauseThresholdPercent = options.pauseThresholdPercent
-    ?? DEFAULT_PAUSE_THRESHOLD_PERCENT;
-  const configuredResumeThresholdPercent = options.resumeThresholdPercent
-    ?? DEFAULT_RESUME_THRESHOLD_PERCENT;
-  validatePressureThresholds(
-    configuredPauseThresholdPercent,
-    configuredResumeThresholdPercent
-  );
+  const configuredPauseThresholdPercent =
+    options.pauseThresholdPercent ?? DEFAULT_PAUSE_THRESHOLD_PERCENT;
+  const configuredResumeThresholdPercent =
+    options.resumeThresholdPercent ?? DEFAULT_RESUME_THRESHOLD_PERCENT;
+  validatePressureThresholds(configuredPauseThresholdPercent, configuredResumeThresholdPercent);
   const pauseNumerator = effectiveMax * BigInt(configuredPauseThresholdPercent);
   const resumeNumerator = effectiveMax * BigInt(configuredResumeThresholdPercent);
 
@@ -182,28 +172,22 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
   private pausedTransitionCount = 0n;
   private cumulativePauseDurationSeconds = 0;
   private flowStateConfigFailureCount = 0n;
-  private readonly pressureListeners = new Set<(
-    state: ApplicationJobQueuePressureState,
-    sequence: bigint
-  ) => void>();
+  private readonly pressureListeners = new Set<
+    (state: ApplicationJobQueuePressureState, sequence: bigint) => void
+  >();
   private readonly waiters: CapacityWaiter[] = [];
   private readonly receiveFlowTargets = new Map<
     object,
     ApplicationJobReceiveFlowTarget<ApplicationJobQueuePressureState>
   >();
-  private readonly receiveFlowController: ApplicationJobReceiveFlowController<
-    ApplicationJobQueuePressureState
-  >;
+  private readonly receiveFlowController: ApplicationJobReceiveFlowController<ApplicationJobQueuePressureState>;
 
   constructor(
     private readonly configuration: ApplicationJobQueueConfiguration,
     private readonly nowMs: () => number = () => performance.now(),
     private readonly handlerStartGate?: () => boolean
   ) {
-    this.receiveFlowController = new ApplicationJobReceiveFlowController(
-      this,
-      state => state
-    );
+    this.receiveFlowController = new ApplicationJobReceiveFlowController(this, (state) => state);
   }
 
   shouldHoldPermitBeforeHandler(): boolean {
@@ -307,9 +291,8 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
     this.runningTransitionCount = 0n;
     this.pausedTransitionCount = 0n;
     this.cumulativePauseDurationSeconds = 0;
-    this.cumulativePauseStartedAtMs = this.pressureStateValue === 'paused'
-      ? this.nowMs()
-      : undefined;
+    this.cumulativePauseStartedAtMs =
+      this.pressureStateValue === 'paused' ? this.nowMs() : undefined;
     this.flowStateConfigFailureCount = 0n;
   }
 
@@ -405,9 +388,14 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
 
   private evaluatePressure(): void {
     const permitsInUse = this.permitsInUse();
-    const next = this.pressureStateValue === 'running'
-      ? permitsInUse >= this.configuration.pausePermitCount ? 'paused' : 'running'
-      : permitsInUse <= this.configuration.resumePermitCount ? 'running' : 'paused';
+    const next =
+      this.pressureStateValue === 'running'
+        ? permitsInUse >= this.configuration.pausePermitCount
+          ? 'paused'
+          : 'running'
+        : permitsInUse <= this.configuration.resumePermitCount
+          ? 'running'
+          : 'paused';
     if (next === this.pressureStateValue) return;
 
     const now = this.nowMs();
@@ -485,18 +473,14 @@ function quotaProcessorCount(quotaText: string, periodText: string): number | un
     if (quota <= 0n || period <= 0n) return undefined;
     const floored = quota / period;
     const count = floored < 1n ? 1n : floored;
-    return count > BigInt(Number.MAX_SAFE_INTEGER)
-      ? Number.MAX_SAFE_INTEGER
-      : Number(count);
+    return count > BigInt(Number.MAX_SAFE_INTEGER) ? Number.MAX_SAFE_INTEGER : Number(count);
   } catch {
     return undefined;
   }
 }
 
 function positiveSafeInteger(value: number | undefined): number | undefined {
-  return value !== undefined && Number.isSafeInteger(value) && value > 0
-    ? value
-    : undefined;
+  return value !== undefined && Number.isSafeInteger(value) && value > 0 ? value : undefined;
 }
 
 function readSystemFile(path: string): string | undefined {

package/src/runtime/host/bound-session-relay.ts

@@ -1,8 +1,6 @@
 import type { ActorRef } from '../../contracts';
 import type { ZLinkBackendActorSessionNode } from '../backend';
-import {
-  type ZLinkActorRoutedJoinTransport
-} from '../actors';
+import { type ZLinkActorRoutedJoinTransport } from '../actors';
 import type { DefaultZLinkActorManager } from '../actors';
 import type { DefaultZLinkSpotManager, ZLinkSpotNodeRuntimeManager } from '../spots';
 import type { ZLinkDetachedTaskRunner } from '../spots/spot-actor-join-dispatch';
@@ -23,8 +21,9 @@ export interface ZLinkBoundSessionRelayOptions {
   readonly requestTimeoutMs?: number;
   readonly sessionRelocationSealTimeoutMs: number;
   readonly routeTransport: ZLinkActorRoutedJoinTransport;
-  readonly streamBindingRuntime: () =>
-    ZLinkBoundSessionResponsePort & ZLinkRemoteBoundSessionPort & ZLinkStreamActorLookupPort;
+  readonly streamBindingRuntime: () => ZLinkBoundSessionResponsePort &
+    ZLinkRemoteBoundSessionPort &
+    ZLinkStreamActorLookupPort;
   readonly meshRouters: MeshRouterResolver;
   readonly actorManager: () => DefaultZLinkActorManager | undefined;
   readonly spotManager: () => DefaultZLinkSpotManager | undefined;
@@ -76,10 +75,9 @@ export class ZLinkBoundSessionRelay {
       actorPacketTargetForState: (actorId, routerChannelIdHint) =>
         this.actorPackets.actorPacketTargetForState(actorId, routerChannelIdHint),
       reportOwnershipRefreshError: (actorId, error) =>
-        options.errorSink().reportRuntimeTaskException(
-          `bound session ownership refresh for '${actorId}'`,
-          error
-        )
+        options
+          .errorSink()
+          .reportRuntimeTaskException(`bound session ownership refresh for '${actorId}'`, error)
     });
     this.actorJoins = new ZLinkRemoteActorJoinReceiver({
       actorManager: options.actorManager,

package/src/runtime/host/channel-runtime-options-factory.ts

@@ -38,59 +38,99 @@ export class ZLinkChannelRuntimeOptionsFactory {
       internalRouteRequestHandlers: this.internalRouteRequestHandlers(),
       localSpotRouteDispatcher: {
         send: async (spotId, packetName, message, routeContext) => {
-          await this.requireSpotManager().dispatchRoutedSpotSend(spotId, packetName, message, routeContext);
+          await this.requireSpotManager().dispatchRoutedSpotSend(
+            spotId,
+            packetName,
+            message,
+            routeContext
+          );
         },
         request: async (spotId, packetName, request, routeContext) =>
-          await this.requireSpotManager().dispatchRoutedSpotRequest(spotId, packetName, request, routeContext)
+          await this.requireSpotManager().dispatchRoutedSpotRequest(
+            spotId,
+            packetName,
+            request,
+            routeContext
+          )
       }
     };
   }
 
   private internalRouteSendHandlers(): ZLinkChannelRuntimeManagerOptions['internalRouteSendHandlers'] {
     return new Map([
-      [ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET, {
-        handle: async (payload) => {
-          const { ok } = await this.options.boundSessionRelay.boundSessions
-            .receiveRemoteBoundSessionSend(payload);
-          if (!ok) {
-            // A rejected relocation-fenced outbound must not read as a
-            // completed flow: surface it so the dispatch pipeline records
-            // an error terminal instead of silently dropping the notify.
-            throw createInternalFrameworkException(
-              ZLinkFrameworkInternalErrorKind.RelocationFailed,
-              `Bound-session send for '${ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET}' was rejected by the Session binding registry.`
-            );
+      [
+        ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
+        {
+          handle: async (payload) => {
+            const { ok } =
+              await this.options.boundSessionRelay.boundSessions.receiveRemoteBoundSessionSend(
+                payload
+              );
+            if (!ok) {
+              // A rejected relocation-fenced outbound must not read as a
+              // completed flow: surface it so the dispatch pipeline records
+              // an error terminal instead of silently dropping the notify.
+              throw createInternalFrameworkException(
+                ZLinkFrameworkInternalErrorKind.RelocationFailed,
+                `Bound-session send for '${ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET}' was rejected by the Session binding registry.`
+              );
+            }
           }
         }
-      }],
-      [ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET, {
-        handle: async (payload) => {
-          await this.options.boundSessionRelay.boundSessions.receiveRemoteBoundSessionResponse(payload);
+      ],
+      [
+        ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET,
+        {
+          handle: async (payload) => {
+            await this.options.boundSessionRelay.boundSessions.receiveRemoteBoundSessionResponse(
+              payload
+            );
+          }
         }
-      }],
-      [ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET, {
-        handle: async (payload) => {
-          await this.options.boundSessionRelay.boundSessions.receiveRemoteBoundSessionError(payload);
+      ],
+      [
+        ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET,
+        {
+          handle: async (payload) => {
+            await this.options.boundSessionRelay.boundSessions.receiveRemoteBoundSessionError(
+              payload
+            );
+          }
         }
-      }],
-      [ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, {
-        handle: async (payload, routeContext) => {
-          await this.options.boundSessionRelay.actorPackets.receiveRemoteActorPacketRelay(payload, routeContext);
+      ],
+      [
+        ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+        {
+          handle: async (payload, routeContext) => {
+            await this.options.boundSessionRelay.actorPackets.receiveRemoteActorPacketRelay(
+              payload,
+              routeContext
+            );
+          }
         }
-      }]
+      ]
     ]);
   }
 
   private internalRouteRequestHandlers(): ZLinkChannelRuntimeManagerOptions['internalRouteRequestHandlers'] {
     return new Map([
-      [ZLINK_REMOTE_ACTOR_JOIN_PACKET, {
-        handle: (payload, routeContext) =>
-          this.options.boundSessionRelay.actorJoins.receive(payload, routeContext)
-      }],
-      [ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET, {
-        handle: (payload, routeContext) =>
-          this.options.boundSessionRelay.actorPackets.receiveRemoteActorPacketRelay(payload, routeContext)
-      }]
+      [
+        ZLINK_REMOTE_ACTOR_JOIN_PACKET,
+        {
+          handle: (payload, routeContext) =>
+            this.options.boundSessionRelay.actorJoins.receive(payload, routeContext)
+        }
+      ],
+      [
+        ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+        {
+          handle: (payload, routeContext) =>
+            this.options.boundSessionRelay.actorPackets.receiveRemoteActorPacketRelay(
+              payload,
+              routeContext
+            )
+        }
+      ]
     ]);
   }
 

package/src/runtime/host/host-capacity-status.ts

@@ -33,9 +33,7 @@ export class HostCapacityStatusProjection {
   }
 }
 
-function projectApplicationJobQueue(
-  queue: ApplicationJobQueue
-): ZLinkApplicationJobQueueStatus {
+function projectApplicationJobQueue(queue: ApplicationJobQueue): ZLinkApplicationJobQueueStatus {
   const snapshot = queue.snapshot();
   return Object.freeze({
     configuredProfile: snapshot.configuredProfile as ZLinkApplicationJobQueueProfile,
@@ -83,8 +81,7 @@ function projectCoreHwm(
     totalInstanceAccountedBytes: snapshot?.totalInstanceAccountedBytes ?? 0n,
     blockedRatioPpm: BigInt(Math.trunc(snapshot?.blockedRatioPpm ?? 0)),
     activeDirectionalQueueCount: snapshot?.activeDirectionalQueueCount ?? 0n,
-    activeCompletionDirectionalQueueCount:
-      snapshot?.activeCompletionDirectionalQueueCount ?? 0n,
+    activeCompletionDirectionalQueueCount: snapshot?.activeCompletionDirectionalQueueCount ?? 0n,
     activeSendQueueCount: snapshot?.activeSendQueueCount ?? 0n,
     activeReceiveQueueCount: snapshot?.activeReceiveQueueCount ?? 0n,
     outstandingApplicationLeaseCount: snapshot?.outstandingApplicationLeaseCount ?? 0n,
@@ -95,9 +92,13 @@ function projectCoreHwm(
 
 function projectCoreProfile(value: AutoHwmProfileValue | undefined): ZLinkCoreHwmProfile {
   switch (value ?? AutoHwmProfile.Balanced) {
-    case AutoHwmProfile.Compact: return ZLinkCoreHwmProfile.Compact;
-    case AutoHwmProfile.LowLatency: return ZLinkCoreHwmProfile.LowLatency;
-    case AutoHwmProfile.Throughput: return ZLinkCoreHwmProfile.Throughput;
-    default: return ZLinkCoreHwmProfile.Balanced;
+    case AutoHwmProfile.Compact:
+      return ZLinkCoreHwmProfile.Compact;
+    case AutoHwmProfile.LowLatency:
+      return ZLinkCoreHwmProfile.LowLatency;
+    case AutoHwmProfile.Throughput:
+      return ZLinkCoreHwmProfile.Throughput;
+    default:
+      return ZLinkCoreHwmProfile.Balanced;
   }
 }