@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/host/application-job-queue.js

@@ -3,12 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApplicationJobQueue = exports.ApplicationJobQueuePermit = void 0;
 exports.resolveApplicationJobQueueConfiguration = resolveApplicationJobQueueConfiguration;
 exports.nodeEffectiveProcessorCount = nodeEffectiveProcessorCount;
+const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
+const Dispatch_1 = require("../../contracts/Dispatch");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const node_fs_1 = require("node:fs");
 const node_os_1 = require("node:os");
 const receive_flow_controller_1 = require("../application-jobs/receive-flow-controller");
-const MAX_QUEUED_APPLICATION_JOBS = 2147483647n;
-const DEFAULT_PAUSE_THRESHOLD_PERCENT = 80;
-const DEFAULT_RESUME_THRESHOLD_PERCENT = 60;
 const CGROUP_V2_CPU_MAX = '/sys/fs/cgroup/cpu.max';
 const CGROUP_V1_CPU_QUOTA = '/sys/fs/cgroup/cpu/cpu.cfs_quota_us';
 const CGROUP_V1_CPU_PERIOD = '/sys/fs/cgroup/cpu/cpu.cfs_period_us';
@@ -19,28 +19,22 @@ const JOBS_PER_PROCESSOR = {
     throughput: 256n
 };
 function resolveApplicationJobQueueConfiguration(options = {}, effectiveProcessorCount = () => nodeEffectiveProcessorCount()) {
-    const configuredProfile = options.profile ?? 'balanced';
-    if (!(configuredProfile in JOBS_PER_PROCESSOR)) {
+    const configuredProfile = options.profile ?? Dispatch_1.ZLinkApplicationJobQueueProfile.Balanced;
+    if (!(0, Registration_1.isKnownApplicationJobQueueProfile)(configuredProfile)) {
         throw new TypeError('applicationJobQueueProfile must be a supported profile.');
     }
     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.');
-    }
+    (0, Registration_1.validateApplicationJobQueueMaximum)(configuredManualMax, (message) => new RangeError(message));
     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;
-    if (effectiveMax < 1n || effectiveMax > MAX_QUEUED_APPLICATION_JOBS) {
-        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);
+    (0, Registration_1.validateApplicationJobQueueMaximum)(effectiveMax, () => new RangeError('Application job queue profile calculation exceeds the supported range.'));
+    const configuredPauseThresholdPercent = options.pauseThresholdPercent ?? Registration_1.DEFAULT_PAUSE_THRESHOLD_PERCENT;
+    const configuredResumeThresholdPercent = options.resumeThresholdPercent ?? Registration_1.DEFAULT_RESUME_THRESHOLD_PERCENT;
+    (0, Registration_1.validateApplicationJobQueuePressureThresholds)(configuredPauseThresholdPercent, configuredResumeThresholdPercent, (message) => new RangeError(message));
+    const percentScale = BigInt(Registration_1.APPLICATION_JOB_QUEUE_PERCENT_SCALE);
     const pauseNumerator = effectiveMax * BigInt(configuredPauseThresholdPercent);
     const resumeNumerator = effectiveMax * BigInt(configuredResumeThresholdPercent);
     return Object.freeze({
@@ -50,8 +44,8 @@ function resolveApplicationJobQueueConfiguration(options = {}, effectiveProcesso
         configuredResumeThresholdPercent,
         effectiveProcessorCount: processors,
         effectiveMaxQueuedApplicationJobs: effectiveMax,
-        pausePermitCount: (pauseNumerator + 99n) / 100n,
-        resumePermitCount: resumeNumerator / 100n
+        pausePermitCount: (pauseNumerator + percentScale - 1n) / percentScale,
+        resumePermitCount: resumeNumerator / percentScale
     });
 }
 class ApplicationJobQueuePermit {
@@ -295,7 +289,7 @@ class ApplicationJobQueue {
         if (waiter.metricsEpoch !== this.metricsEpoch)
             return;
         const durationMs = Math.max(0, this.nowMs() - waiter.startedAtMs);
-        this.capacityWaitDurationSeconds += durationMs / 1_000;
+        this.capacityWaitDurationSeconds += durationMs / runtime_metrics_1.MILLISECONDS_PER_SECOND;
     }
     evaluatePressure() {
         const permitsInUse = this.permitsInUse();
@@ -329,26 +323,15 @@ class ApplicationJobQueue {
     pauseDurationAt(nowMs) {
         if (this.pauseStartedAtMs === undefined)
             return 0;
-        return Math.max(0, nowMs - this.pauseStartedAtMs) / 1_000;
+        return Math.max(0, nowMs - this.pauseStartedAtMs) / runtime_metrics_1.MILLISECONDS_PER_SECOND;
     }
     cumulativePauseDurationAt(nowMs) {
         if (this.cumulativePauseStartedAtMs === undefined)
             return 0;
-        return Math.max(0, nowMs - this.cumulativePauseStartedAtMs) / 1_000;
+        return Math.max(0, nowMs - this.cumulativePauseStartedAtMs) / runtime_metrics_1.MILLISECONDS_PER_SECOND;
     }
 }
 exports.ApplicationJobQueue = ApplicationJobQueue;
-function validatePressureThresholds(pause, resume) {
-    if (!Number.isInteger(pause) || pause < 1 || pause > 100) {
-        throw new RangeError('pauseThresholdPercent must be an integer in the range 1..100.');
-    }
-    if (!Number.isInteger(resume) || resume < 0 || resume > 99) {
-        throw new RangeError('resumeThresholdPercent must be an integer in the range 0..99.');
-    }
-    if (resume >= pause) {
-        throw new RangeError('resumeThresholdPercent must be less than pauseThresholdPercent.');
-    }
-}
 function nodeEffectiveProcessorCount(explicitExecutorMaximum, runtimeConstrainedLogicalCount = (0, node_os_1.availableParallelism)(), readSystemText = readSystemFile) {
     const candidates = [
         positiveSafeInteger(runtimeConstrainedLogicalCount),

package/dist/runtime/host/bound-session-relay.js

@@ -36,7 +36,7 @@ class ZLinkBoundSessionRelay {
             destroyedActorRefs: options.destroyedActorRefs,
             boundSessionFactory: options.boundSessionFactory,
             updateRemoteActorPacketTarget: (actorId, value) => this.actorPackets.updateRemoteActorPacketTarget(actorId, value),
-            actorPacketTargetForState: (actorId, routerChannelIdHint) => this.actorPackets.actorPacketTargetForState(actorId, routerChannelIdHint),
+            actorPacketTargetForState: (actorId) => this.actorPackets.actorPacketTargetForState(actorId),
             reportOwnershipRefreshError: (actorId, error) => options
                 .errorSink()
                 .reportRuntimeTaskException(`bound session ownership refresh for '${actorId}'`, error)

package/dist/runtime/host/channel-runtime-options-factory.js

@@ -71,7 +71,7 @@ class ZLinkChannelRuntimeOptionsFactory {
             [
                 actors_1.ZLINK_REMOTE_ACTOR_JOIN_PACKET,
                 {
-                    handle: (payload, routeContext) => this.options.boundSessionRelay.actorJoins.receive(payload, routeContext)
+                    handle: (payload) => this.options.boundSessionRelay.actorJoins.receive(payload)
                 }
             ],
             [

package/dist/runtime/host/index.d.ts

@@ -1,19 +1,17 @@
-import type { ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend';
-import type { ZLinkFrameworkRegistration } from '../configuration';
-import type { ZLinkMeshNodeDescriptor, ZLinkClientServerRuntime, ZLinkFanoutRuntime, ZLinkFrameworkRuntime, ZLinkFrameworkLifecycleOptions, ZLinkFrameworkRelocationOptions, ZLinkFrameworkRelocationResult, ZLinkObservedStatus, ZLinkFrameworkRuntimeStatus, ZLinkFrameworkTerminationResult, ZLinkRouteMeshRuntime } from '../../contracts';
+import { type ZLinkClientServerRuntime, type ZLinkFanoutRuntime, type ZLinkFrameworkLifecycleOptions, type ZLinkFrameworkRelocationOptions, type ZLinkFrameworkRelocationResult, type ZLinkFrameworkRuntime, type ZLinkFrameworkRuntimeStatus, type ZLinkFrameworkTerminationResult, type ZLinkListenerKind, type ZLinkListenerStatus, type ZLinkMeshNodeDescriptor, type ZLinkMessageFlowControl, type ZLinkMessageFlowLogMode, type ZLinkObservedStatus, type ZLinkRouteMeshRuntime } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
-import type { ZLinkMessageFlowControl, ZLinkMessageFlowLogMode } from '../../contracts';
+import { type ZLinkLocationRuntimeQuery } from '../../contracts/Locations';
+import { type DefaultZLinkActorManager, type ZLinkActorManagerOptions, DefaultZLinkActorClient } from '../actors';
+import { type ZLinkBackendContext, type ZLinkBackendMeshNode } from '../backend';
 import { DefaultZLinkChannelRuntimeOptions, ZLinkChannelRuntimeManager, ZLinkRuntimeRouteTransport } from '../channels';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import { type ZLinkRuntimeEventPublisher } from '../diagnostics';
 import { ZLinkFrameworkExecutionState } from '../execution';
-import { DefaultZLinkSpotManager, ZLinkRuntimeSpotPublisherTransport, type ZLinkSpotManagerOptions } from '../spots';
-import type { DefaultZLinkActorManager, ZLinkActorManagerOptions } from '../actors';
-import { DefaultZLinkActorClient } from '../actors';
-import { DefaultZLinkBoundSessionFactory, ZLinkStreamBindingRuntime } from '../streams';
 import { type ZLinkStoreLocationResolvers } from '../locations';
-import { type ZLinkLocationRuntimeQuery } from '../../contracts/Locations';
-import { ZLinkHostSpotAddressTransport } from './spot-address-transport';
+import { DefaultZLinkSpotManager, ZLinkRuntimeSpotPublisherTransport, type ZLinkDetachedTaskRunner, type ZLinkSpotManagerOptions } from '../spots';
+import { DefaultZLinkBoundSessionFactory, ZLinkStreamBindingRuntime } from '../streams';
 import { DefaultZLinkRouteMeshRuntimeOptions } from './route-mesh-runtime-options';
+import { ZLinkHostSpotAddressTransport } from './spot-address-transport';
 export interface ZLinkFrameworkRuntimeLifecycle {
     readonly isStarted: boolean;
     readonly locationRuntimeQuery?: ZLinkLocationRuntimeQuery;
@@ -35,6 +33,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private runtimeSequence;
     private readonly runtimeObservationSource;
     private runtimeDeadline?;
+    private shutdownDeadline?;
     private runtimeRelocationResult?;
     private runtimeTerminationResult?;
     private relocationOperation?;
@@ -61,6 +60,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private actorManager?;
     private actorPlacement?;
     private spotManager?;
+    private userSpotCoordinator?;
     private ownerLeaseRecoveryRuntime?;
     private ownerLeaseRecoveryHandler?;
     private registerUserSpotHandlers?;
@@ -71,6 +71,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private readonly capacityStatus;
     private readonly metricRegistrations;
     private readonly admission;
+    private readonly activationAdmission;
     private cachedLocationSpotRouteResolver?;
     private actorClientLocationResolver?;
     private readonly messageFlowModeCell;
@@ -94,17 +95,21 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     constructor(options: ZLinkFrameworkRuntimeHostOptions, internalOptions?: unknown);
     get isStarted(): boolean;
     get status(): ZLinkFrameworkRuntimeStatus;
+    private listenerRecords;
+    getListenerStatus(kind: ZLinkListenerKind, name: string): ZLinkListenerStatus;
     observe(signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkFrameworkRuntimeStatus>>;
     resetCapacityMetrics(): void;
     relocate(options: ZLinkFrameworkRelocationOptions): Promise<ZLinkFrameworkRelocationResult>;
     shutdown(options?: ZLinkFrameworkLifecycleOptions): Promise<ZLinkFrameworkTerminationResult>;
     private runRelocation;
     private runShutdown;
+    private runWithShutdownDeadline;
     private resetBlockedRelocation;
     private completeRelocation;
     private recordRelocationResult;
     private completeTermination;
     private setRuntimeState;
+    private publishRuntimeStatus;
     private notifyTopologyHostStateChanged;
     private stopTopologyObservers;
     private publishActorHandoffEvent;
@@ -150,7 +155,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private registerInstanceApplicationLifecycle;
     setActorManager(actorManager: DefaultZLinkActorManager): void;
     setSpotManager(spotManager: DefaultZLinkSpotManager): void;
-    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'locationLifecycle' | 'boundSessionFactory' | 'shutdownSignal' | 'admission' | 'placementCreate'>;
+    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'locationLifecycle' | 'boundSessionFactory' | 'shutdownSignal' | 'admission' | 'activationAdmission' | 'placementCreate'>;
     createActorClientOptions(): ConstructorParameters<typeof DefaultZLinkActorClient>[0];
     createLocationHandleResolver(): ZLinkStoreLocationResolvers | undefined;
     createSpotManagerOptions(): Partial<ZLinkSpotManagerOptions>;
@@ -162,7 +167,7 @@ export declare class ZLinkFrameworkRuntimeHost implements ZLinkFrameworkRuntimeL
     private submitLocalMeshRoute;
     private dispatchMeshSpotRecord;
     private createDispatchErrorReporter;
-    private detachedTaskRunner;
+    detachedTaskRunner(): ZLinkDetachedTaskRunner;
     private diagnosticsContext;
     private flowCreationEnabled;
     private runLifecycle;
@@ -183,7 +188,7 @@ export declare function hasExactPeerReadiness(descriptors: readonly ZLinkMeshNod
     readonly state: number;
 }[]): boolean;
 export { ZLinkActorTransferAuthorityRuntime, transferIdString } from './actor-transfer-authority-runtime';
-export { ZLinkRetiringRollbackError, ZLinkRouteMeshRuntimeCoordinator } from './route-mesh-runtime';
+export { ZLinkDrainingStatePublishError, ZLinkRetiringRollbackError, ZLinkRouteMeshRuntimeCoordinator } from './route-mesh-runtime';
 export { ZLinkRelocationStateIncompatibleError } from './service-relocation-host-runtime';
 export { ZLinkHostSpotAddressTransport, type ZLinkHostSpotAddressTransportOptions } from './spot-address-transport';
 export { ZLinkUserSpotCreationCoordinator, type ZLinkUserSpotCreationCoordinatorOptions, type ZLinkUserSpotCreationRequest, type ZLinkUserSpotCreationResult } from './user-spot-creation-coordinator';