@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/streams/stream-session-runtime.js

@@ -1,29 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const abort_1 = require("../abort");
+const admission_1 = require("../admission");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const channels_1 = require("../channels");
-const bound_session_response_target_1 = require("./bound-session-response-target");
 const diagnostics_1 = require("../diagnostics");
-const payload_codec_1 = require("../messaging/payload-codec");
-const protocol_1 = require("./protocol");
 const flow_context_1 = require("../diagnostics/flow-context");
+const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
+const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const payload_codec_1 = require("../messaging/payload-codec");
+const bound_session_response_target_1 = require("./bound-session-response-target");
 const managed_stream_1 = require("./managed-stream");
+const protocol_1 = require("./protocol");
 const session_context_1 = require("./session-context");
 const session_serial_executor_1 = require("./session-serial-executor");
 const stream_message_utils_1 = require("./stream-message-utils");
-const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
-const application_job_queue_scope_2 = require("../application-jobs/application-job-queue-scope");
 const ZLINK_SEND_DONT_WAIT = 1;
 const ZLINK_RECV_DONT_WAIT = 1;
 const ZLINK_STREAM_HEARTBEAT_INTERVAL_MS = 1_000;
 const ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
 const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
-const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
 const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
 const ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS = 20;
@@ -69,7 +70,7 @@ class ZLinkStreamSessionRuntime {
     metricsClosed = false;
     livenessClock;
     lastApplicationActivityAt = 0;
-    awaitingPongSince;
+    lastInboundFrameAt = 0;
     livenessTimer;
     constructor(options, routingId, removeSession = () => { }) {
         this.options = options;
@@ -114,6 +115,7 @@ class ZLinkStreamSessionRuntime {
         this.serial.executeInfrastructure(async () => this.markConnected(localAddr, remoteAddr));
     }
     enqueuePacket(payload, decodedHeader, terminalOwner, applicationJobPermit) {
+        this.lastInboundFrameAt = Math.max(this.lastInboundFrameAt, this.livenessClock.now());
         let terminalReleased = false;
         const releaseTerminal = () => {
             if (terminalReleased)
@@ -248,7 +250,7 @@ class ZLinkStreamSessionRuntime {
                 }
                 forcedClose = true;
                 void this.close().catch((error) => this.options.onError?.(error));
-            }, this.options.replacementCallbackTimeoutMs ?? ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS);
+            }, this.options.replacementCallbackTimeoutMs ?? Registration_1.DEFAULT_SESSION_REPLACEMENT_CALLBACK_TIMEOUT_MS);
             const callback = session.onActorBindingReplaced;
             if (callback === undefined) {
                 completeCallback();
@@ -309,10 +311,12 @@ class ZLinkStreamSessionRuntime {
             return;
         }
         this.connected = true;
-        this.lastApplicationActivityAt = this.livenessClock.now();
+        const connectedAt = this.livenessClock.now();
+        this.lastApplicationActivityAt = connectedAt;
+        this.lastInboundFrameAt = Math.max(this.lastInboundFrameAt, connectedAt);
         this.scheduleLivenessCheck();
-        this.options.metrics?.change('zlink.stream.connections.active', 1, { transport: 'tcp' });
-        this.options.metrics?.count('zlink.stream.connections.opened', 1, { transport: 'tcp' });
+        this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.StreamConnectionsActive, 1, { transport: 'tcp' });
+        this.options.metrics?.count(runtime_metrics_1.METRIC_NAMES.StreamConnectionsOpened, 1, { transport: 'tcp' });
         const session = await this.requireSession();
         await session.onConnected?.(this.context);
     }
@@ -389,7 +393,7 @@ class ZLinkStreamSessionRuntime {
                     correlationId: streamCorr,
                     sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
                 });
-                (0, application_job_queue_scope_2.releaseApplicationJobPermitBeforeHandler)();
+                (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
                 (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched)?.trace({
                     outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched,
                     surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
@@ -450,7 +454,6 @@ class ZLinkStreamSessionRuntime {
             return;
         }
         if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG) {
-            this.awaitingPongSince = undefined;
             return;
         }
         if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
@@ -477,13 +480,11 @@ class ZLinkStreamSessionRuntime {
             await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.IdleTimeout, 'idle_timeout', 'Application idle timeout.');
             return;
         }
-        if (this.awaitingPongSince !== undefined &&
-            now - this.awaitingPongSince >= ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS) {
+        if (now - this.lastInboundFrameAt >= ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS) {
             await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.HeartbeatTimeout, 'heartbeat_timeout', 'Heartbeat timeout.');
             return;
         }
         await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PING);
-        this.awaitingPongSince ??= now;
         this.scheduleLivenessCheck();
     }
     async closeForLiveness(reason, closeReason, diagnostic) {
@@ -592,8 +593,8 @@ class ZLinkStreamSessionRuntime {
     async cleanup() {
         if (this.connected && !this.metricsClosed) {
             this.metricsClosed = true;
-            this.options.metrics?.change('zlink.stream.connections.active', -1, { transport: 'tcp' });
-            this.options.metrics?.count('zlink.stream.connections.closed', 1, {
+            this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.StreamConnectionsActive, -1, { transport: 'tcp' });
+            this.options.metrics?.count(runtime_metrics_1.METRIC_NAMES.StreamConnectionsClosed, 1, {
                 transport: 'tcp',
                 close_reason: normalizeStreamCloseReason(this.closeReason)
             });
@@ -688,7 +689,6 @@ class ZLinkStreamSessionNodeRuntime {
     unaddressedMonitorSessions = [];
     unaddressedMonitorSessionHead = 0;
     unaddressedMonitorSessionCount = 0;
-    disconnectedEndpoints = new Set();
     pendingEndpointlessDisconnect;
     activityVersion = 0;
     stopped = false;
@@ -945,18 +945,13 @@ class ZLinkStreamSessionNodeRuntime {
         }
         switch (event.nativeEvent) {
             case internal_event_contracts_1.ZLinkSocketNativeEventType.ConnectionReady:
+                if (!event.readyEdge)
+                    return;
                 this.activityVersion += 1;
-                {
-                    const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
-                    if (this.disconnectedEndpoints.delete(endpointKey)) {
-                        return;
-                    }
-                }
                 if (event.routingId === undefined) {
                     const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
                     const unaddressed = this.firstUnaddressedSession();
                     if (unaddressed !== undefined) {
-                        this.disconnectedEndpoints.delete(endpointKey);
                         unaddressed.enqueueConnected(event.localAddr, event.remoteAddr);
                         this.enqueueUnaddressedMonitorSession(unaddressed.stream.sessionId);
                         return;
@@ -976,7 +971,6 @@ class ZLinkStreamSessionNodeRuntime {
             case internal_event_contracts_1.ZLinkSocketNativeEventType.Disconnected:
                 {
                     const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
-                    this.disconnectedEndpoints.add(endpointKey);
                     this.removePendingConnectionMetadata(endpointKey);
                     const session = this.resolveMonitorSession(event);
                     const error = new Error(`Stream disconnected: ${event.nativeEvent}/${event.value}`);
@@ -1035,8 +1029,7 @@ class ZLinkStreamSessionNodeRuntime {
             this.pendingConnectionMetadata.length = 0;
             this.pendingConnectionMetadataHead = 0;
         }
-        else if (this.pendingConnectionMetadataHead >= 1024 &&
-            this.pendingConnectionMetadataHead * 2 >= this.pendingConnectionMetadata.length) {
+        else if ((0, admission_1.shouldCompactBackingArray)(this.pendingConnectionMetadataHead, this.pendingConnectionMetadata.length)) {
             this.pendingConnectionMetadata.splice(0, this.pendingConnectionMetadataHead);
             this.pendingConnectionMetadataHead = 0;
         }
@@ -1060,8 +1053,7 @@ class ZLinkStreamSessionNodeRuntime {
             this.unaddressedMonitorSessions.length = 0;
             this.unaddressedMonitorSessionHead = 0;
         }
-        else if (this.unaddressedMonitorSessionHead >= 1024 &&
-            this.unaddressedMonitorSessionHead * 2 >= this.unaddressedMonitorSessions.length) {
+        else if ((0, admission_1.shouldCompactBackingArray)(this.unaddressedMonitorSessionHead, this.unaddressedMonitorSessions.length)) {
             this.unaddressedMonitorSessions.splice(0, this.unaddressedMonitorSessionHead);
             this.unaddressedMonitorSessionHead = 0;
         }

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

@@ -1,5 +1,5 @@
-import type { ZLinkWorkerCall } from '../../contracts';
-import type { ZLinkWorkerOptions } from '../configuration';
+import { type ZLinkWorkerCall } from '../../contracts';
+import { type ZLinkWorkerOptions } from '../configuration';
 export type ZLinkCpuWorkerWork<T> = (signal: AbortSignal) => T;
 export type ZLinkIoWorkerWork<T> = (signal: AbortSignal) => Promise<T>;
 export interface ZLinkWorkerRuntimeOptions {

package/dist/runtime/workers/index.js

@@ -3,12 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkWorkerCall = exports.ZLinkWorkerRuntime = void 0;
 exports.resolveWorkerRuntimeOptions = resolveWorkerRuntimeOptions;
 exports.deliverOnSerial = deliverOnSerial;
-const framework_errors_internal_1 = require("../framework-errors-internal");
 const node_worker_threads_1 = require("node:worker_threads");
-const configuration_1 = require("../configuration");
 const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
 const abort_1 = require("../abort");
+const admission_1 = require("../admission");
+const configuration_1 = require("../configuration");
 const execution_1 = require("../execution");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 function resolveWorkerRuntimeOptions(options) {
     const resolved = {
         minThreads: options?.minThreads ?? InternalDefaults_1.DEFAULT_WORKER_MIN_THREADS,
@@ -264,7 +265,7 @@ class ZLinkCpuWorkerPool {
             this.queue.length = 0;
             this.queueHead = 0;
         }
-        else if (this.queueHead >= 1024 && this.queueHead * 2 >= this.queue.length) {
+        else if ((0, admission_1.shouldCompactBackingArray)(this.queueHead, this.queue.length)) {
             this.queue.splice(0, this.queueHead);
             this.queueHead = 0;
         }
@@ -284,7 +285,7 @@ class ZLinkCpuWorkerPool {
                 while (this.queueHead < this.queue.length && this.queue[this.queueHead] === undefined) {
                     this.queueHead += 1;
                 }
-                if (this.queueHead >= 1024 && this.queueHead * 2 >= this.queue.length) {
+                if ((0, admission_1.shouldCompactBackingArray)(this.queueHead, this.queue.length)) {
                     this.queue.splice(0, this.queueHead);
                     this.queueHead = 0;
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.25.0",
-    "@zlink-systems/zlink": "1.7.0"
+    "@zlink-systems/stream-wire": "0.27.0",
+    "@zlink-systems/zlink": "1.14.0"
   }
 }

package/src/contracts/Channels/IZLinkFanoutClient.ts

@@ -1,13 +1,6 @@
 import type { ZLinkFanoutPublishCall } from './Calls';
 
-export interface ZLinkFanoutListenerStatus {
-  readonly channelName: string;
-  readonly endpoint: string;
-  readonly observedAt: Date;
-}
-
 export interface ZLinkFanoutClient {
   publish(channelName: string, event: unknown): ZLinkFanoutPublishCall;
   publish(channelName: string, topic: string, event: unknown): ZLinkFanoutPublishCall;
-  getListenerStatus(channelName: string): ZLinkFanoutListenerStatus;
 }

package/src/contracts/Common/CoreTypes.ts

@@ -4,3 +4,10 @@ export type RoutingId = string;
 export type ActorId = string;
 /** Global logical Spot identity. It is not a transport RoutingId. */
 export type SpotId = string;
+
+export const ZLINK_MAX_ACTOR_ID_BYTES = 255;
+export const ZLINK_MAX_SPOT_ID_BYTES = 255;
+export const ZLINK_MAX_ROUTING_ID_BYTES = 255;
+export const ZLINK_MAX_STABLE_TYPE_BYTES = 255;
+export const ZLINK_MAX_MESH_NAME_BYTES = 255;
+export const ZLINK_MAX_IDENTITY_TEXT_BYTES = 255;

package/src/contracts/Common/index.ts

@@ -1,5 +1,5 @@
 export * from './ActorRef';
-export * from './CoreTypes';
+export type { Type, RoutingId, ActorId, SpotId } from './CoreTypes';
 export * from './ZLinkEncodedPayload';
 export * from './ZLinkMessageMetadata';
 export { ZLinkMessage, isZLinkMessage } from './ZLinkMessage';

package/src/contracts/Configuration/InternalDefaults.ts

@@ -3,6 +3,12 @@ import * as os from 'node:os';
 /** Default complete header plus payload size accepted by a StreamNode. */
 export const DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE = 64 * 1024;
 
+/** service-wire 스키마가 정한 relocation chunk payload의 바이트 상한입니다. */
+export const RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = 67_108_864;
+
+/** Default MeshNode pending activation limit (spec 03-mesh-node §5.1). */
+export const DEFAULT_ACTIVATION_CONCURRENCY_LIMIT = 128;
+
 /** Defaults shared by registration normalization and the runtime worker pool. */
 export const DEFAULT_WORKER_MIN_THREADS = 0;
 export const DEFAULT_WORKER_IDLE_TIMEOUT_MS = 30_000;
@@ -10,3 +16,9 @@ export const DEFAULT_WORKER_IDLE_TIMEOUT_MS = 30_000;
 export function defaultWorkerMaxThreads(): number {
   return Math.max(2, os.availableParallelism());
 }
+
+export const ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = 4096;
+
+export const AUTHORITY_ENVELOPE_MAX_BYTES = 1024 * 1024;
+export const CREATION_INTENT_MAX_BYTES = 1024 * 1024;
+export const CREATION_TERMINAL_ENVELOPE_MAX_BYTES = 1024 * 1024;

package/src/contracts/Configuration/Registration.ts

@@ -1,8 +1,9 @@
+import { AutoHwmProfile } from '@zlink-systems/zlink';
 import type { ZLinkFrameworkOptions } from '../../contracts';
+import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../Common/CoreTypes';
 import { ZLinkApplicationJobQueueProfile } from '../Dispatch';
-export { ZLinkConfigurationException } from './ConfigurationException';
+import { zlinkDefaultLocationOptions } from '../Locations/Options';
 import { createFrameworkOptions } from './RegistrationBuilders';
-export { createFrameworkOptions } from './RegistrationBuilders';
 import { createCodecRegistry } from './RegistrationCodecRegistry';
 import {
   actorFactoriesFromSpotNodes,
@@ -19,18 +20,22 @@ import {
   toSpotPublisherClientSet,
   toStreamNodeMap
 } from './RegistrationNormalizers';
+import type {
+  ZLinkFrameworkRegistration,
+  ZLinkFrameworkRegistrationOptions
+} from './RegistrationTypes';
+import { validateFrameworkRegistration } from './RegistrationValidators';
+
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export { ZLinkConfigurationException } from './ConfigurationException';
+export { createFrameworkOptions } from './RegistrationBuilders';
 export {
   hasActorManager,
   hasSpotNode,
   hasSpotPublisherClient,
   requirePositiveInteger
 } from './RegistrationNormalizers';
-import type {
-  ZLinkFrameworkRegistration,
-  ZLinkFrameworkRegistrationOptions
-} from './RegistrationTypes';
 export * from './RegistrationTypes';
-import { validateFrameworkRegistration } from './RegistrationValidators';
 export { validateFrameworkRegistration };
 export {
   normalizeEndpoint,
@@ -38,11 +43,18 @@ export {
   parseEndpointHostPort
 } from './EndpointNotation';
 
-const DEFAULT_MESSAGE_FOLLOW_DURATION_MS = 30_000;
-const DEFAULT_SESSION_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
+export const DEFAULT_SESSION_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
 
 export function createFrameworkRegistration(
   options: ZLinkFrameworkRegistrationOptions = {}
+): ZLinkFrameworkRegistration {
+  const registration = normalizeFrameworkRegistration(options);
+  validateFrameworkRegistration(registration, options);
+  return registration;
+}
+
+export function normalizeFrameworkRegistration(
+  options: ZLinkFrameworkRegistrationOptions
 ): ZLinkFrameworkRegistration {
   const codecRegistry = createCodecRegistry(options.codecs);
   const network = normalizeNetworkOptions(options.network);
@@ -66,7 +78,7 @@ export function createFrameworkRegistration(
     messageFollowDurationMs: normalizeNonNegativeInteger(
       options.messageFollowDurationMs,
       'messageFollowDurationMs',
-      DEFAULT_MESSAGE_FOLLOW_DURATION_MS
+      zlinkDefaultLocationOptions.messageFollowDurationMs
     ),
     sessionReplacementCallbackTimeoutMs: normalizePositiveInteger(
       options.sessionReplacementCallbackTimeoutMs,
@@ -94,53 +106,75 @@ export function createFrameworkRegistration(
     applicationJobQueue: normalizeApplicationJobQueue(options.applicationJobQueue),
     locations: normalizeLocationRegistration(options.locations)
   };
-  validateFrameworkRegistration(registration, options);
   return registration;
 }
 
-function normalizeApplicationJobQueue(
-  value: ZLinkFrameworkRegistrationOptions['applicationJobQueue']
-): NonNullable<ZLinkFrameworkRegistrationOptions['applicationJobQueue']> {
-  const profile = value?.profile ?? ZLinkApplicationJobQueueProfile.Balanced;
-  if (!Object.values(ZLinkApplicationJobQueueProfile).includes(profile)) {
-    throw new TypeError('applicationJobQueue.profile must be a supported profile.');
-  }
-  const maxQueuedApplicationJobs = value?.maxQueuedApplicationJobs;
+export const MAX_QUEUED_APPLICATION_JOBS = 2_147_483_647n;
+export const DEFAULT_PAUSE_THRESHOLD_PERCENT = 80;
+export const DEFAULT_RESUME_THRESHOLD_PERCENT = 60;
+export const APPLICATION_JOB_QUEUE_PERCENT_SCALE = 100;
+
+export function isKnownApplicationJobQueueProfile(
+  value: unknown
+): value is ZLinkApplicationJobQueueProfile {
+  return Object.values(ZLinkApplicationJobQueueProfile).includes(
+    value as ZLinkApplicationJobQueueProfile
+  );
+}
+
+export function validateApplicationJobQueueMaximum(
+  value: bigint | undefined,
+  createError: (message: string) => Error
+): void {
   if (
-    maxQueuedApplicationJobs !== undefined &&
-    (typeof maxQueuedApplicationJobs !== 'bigint' ||
-      maxQueuedApplicationJobs < 1n ||
-      maxQueuedApplicationJobs > 2_147_483_647n)
+    value !== undefined &&
+    (typeof value !== 'bigint' || value < 1n || value > MAX_QUEUED_APPLICATION_JOBS)
   ) {
-    throw new TypeError(
-      'applicationJobQueue.maxQueuedApplicationJobs must be a bigint in the range 1..2147483647.'
+    throw createError(
+      `maxQueuedApplicationJobs must be a bigint in the range 1..${MAX_QUEUED_APPLICATION_JOBS}.`
     );
   }
-  const pauseThresholdPercent = value?.pauseThresholdPercent ?? 80;
-  const resumeThresholdPercent = value?.resumeThresholdPercent ?? 60;
-  if (
-    !Number.isInteger(pauseThresholdPercent) ||
-    pauseThresholdPercent < 1 ||
-    pauseThresholdPercent > 100
-  ) {
-    throw new TypeError(
-      'applicationJobQueue.pauseThresholdPercent must be an integer in the range 1..100.'
+}
+
+export function validateApplicationJobQueuePressureThresholds(
+  pause: number,
+  resume: number,
+  createError: (message: string) => Error
+): void {
+  if (!Number.isInteger(pause) || pause < 1 || pause > APPLICATION_JOB_QUEUE_PERCENT_SCALE) {
+    throw createError(
+      `pauseThresholdPercent must be an integer in the range 1..${APPLICATION_JOB_QUEUE_PERCENT_SCALE}.`
     );
   }
-  if (
-    !Number.isInteger(resumeThresholdPercent) ||
-    resumeThresholdPercent < 0 ||
-    resumeThresholdPercent > 99
-  ) {
-    throw new TypeError(
-      'applicationJobQueue.resumeThresholdPercent must be an integer in the range 0..99.'
+  if (!Number.isInteger(resume) || resume < 0 || resume >= APPLICATION_JOB_QUEUE_PERCENT_SCALE) {
+    throw createError(
+      `resumeThresholdPercent must be an integer in the range 0..${APPLICATION_JOB_QUEUE_PERCENT_SCALE - 1}.`
     );
   }
-  if (resumeThresholdPercent >= pauseThresholdPercent) {
-    throw new TypeError(
-      'applicationJobQueue.resumeThresholdPercent must be less than pauseThresholdPercent.'
-    );
+  if (resume >= pause) {
+    throw createError('resumeThresholdPercent must be less than pauseThresholdPercent.');
   }
+}
+
+function normalizeApplicationJobQueue(
+  value: ZLinkFrameworkRegistrationOptions['applicationJobQueue']
+): NonNullable<ZLinkFrameworkRegistrationOptions['applicationJobQueue']> {
+  const profile = value?.profile ?? ZLinkApplicationJobQueueProfile.Balanced;
+  if (!isKnownApplicationJobQueueProfile(profile)) {
+    throw new TypeError('applicationJobQueue.profile must be a supported profile.');
+  }
+  const maxQueuedApplicationJobs = value?.maxQueuedApplicationJobs;
+  validateApplicationJobQueueMaximum(
+    maxQueuedApplicationJobs,
+    (message) => new TypeError(`applicationJobQueue.${message}`)
+  );
+  const pauseThresholdPercent = value?.pauseThresholdPercent ?? DEFAULT_PAUSE_THRESHOLD_PERCENT;
+  const resumeThresholdPercent = value?.resumeThresholdPercent ?? DEFAULT_RESUME_THRESHOLD_PERCENT;
+  validateApplicationJobQueuePressureThresholds(
+    pauseThresholdPercent,
+    resumeThresholdPercent,
+    (message) => new TypeError(`applicationJobQueue.${message}`)
+  );
   return Object.freeze({
     profile,
     maxQueuedApplicationJobs,
@@ -154,7 +188,10 @@ function normalizeCoreHwm(
 ): ZLinkFrameworkRegistrationOptions['coreHwm'] {
   if (value === undefined) return undefined;
   const { profile, memoryLimitBytes, budgetBytes } = value;
-  if (profile !== undefined && (!Number.isInteger(profile) || profile < 0 || profile > 3)) {
+  if (
+    profile !== undefined &&
+    (!Number.isInteger(profile) || profile < 0 || profile > AutoHwmProfile.Throughput)
+  ) {
     throw new TypeError('coreHwm.profile must be a Core Auto HWM profile value.');
   }
   for (const [name, bytes] of [
@@ -183,8 +220,15 @@ function normalizeApplicationVersion(value: bigint | undefined): bigint {
 function normalizeMaintenanceWave(value: string | undefined): string | undefined {
   if (value === undefined) return undefined;
   const byteLength = typeof value === 'string' ? new TextEncoder().encode(value).byteLength : 0;
-  if (typeof value !== 'string' || byteLength === 0 || byteLength > 255 || value.includes('\0')) {
-    throw new TypeError('maintenanceWave must be a 1..255 byte UTF-8 string without NUL.');
+  if (
+    typeof value !== 'string' ||
+    byteLength === 0 ||
+    byteLength > ZLINK_MAX_IDENTITY_TEXT_BYTES ||
+    value.includes('\0')
+  ) {
+    throw new TypeError(
+      `maintenanceWave must be a 1..${ZLINK_MAX_IDENTITY_TEXT_BYTES} byte UTF-8 string without NUL.`
+    );
   }
   return value;
 }

package/src/contracts/Configuration/RegistrationBuilderPolicy.ts

@@ -1,5 +1,44 @@
-import type { Type, ZLinkEntrySpot, ZLinkSpot } from '../../contracts';
+import type { Type, ZLinkEntrySpot, ZLinkSpot, ZLinkRelocationStore } from '../../contracts';
+import { ZLINK_MAX_ROUTING_ID_BYTES } from '../Common/CoreTypes';
 import { ZLinkConfigurationException } from './ConfigurationException';
+export const MAX_LISTENER_PORT = 65_535;
+
+export function registerRelocationStore(
+  options: { relocationStoreInstance?: ZLinkRelocationStore },
+  store: ZLinkRelocationStore
+): void {
+  if (options.relocationStoreInstance !== undefined) {
+    throw new ZLinkConfigurationException('Relocation Store is already registered.');
+  }
+  options.relocationStoreInstance = store;
+}
+export function isValidListenerPort(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= MAX_LISTENER_PORT;
+}
+
+export const ZLINK_MAX_CAPACITY = 0x7fff_ffff;
+export function isValidPositiveCapacity(value: number): boolean {
+  return Number.isSafeInteger(value) && value > 0 && value <= ZLINK_MAX_CAPACITY;
+}
+export function isValidCapacity(value: number): boolean {
+  return Number.isSafeInteger(value) && value >= 0 && value <= ZLINK_MAX_CAPACITY;
+}
+
+export const ZLINK_DEFAULT_PUBLIC_WEIGHT = 100;
+export const ZLINK_MAX_PUBLIC_WEIGHT = 10_000;
+
+export function isValidPublicWeight(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= ZLINK_MAX_PUBLIC_WEIGHT;
+}
+
+export function requirePublicWeight(value: number, label: string): number {
+  if (!isValidPublicWeight(value)) {
+    throw new ZLinkConfigurationException(
+      `${label} must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`
+    );
+  }
+  return value;
+}
 
 export function validateMessageFollowDuration(timeoutMs: number): number {
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0) {
@@ -69,7 +108,10 @@ export function validateRoutingIdPrefix(prefix: string): string {
   if (prefix.trim().length === 0 || prefix !== prefix.trim()) {
     throw new ZLinkConfigurationException('Routing-id prefix must not be empty or padded.');
   }
-  if (Buffer.byteLength(`${prefix}-00000000-0000-0000-0000-000000000000`, 'utf8') > 255) {
+  if (
+    Buffer.byteLength(`${prefix}-00000000-0000-0000-0000-000000000000`, 'utf8') >
+    ZLINK_MAX_ROUTING_ID_BYTES
+  ) {
     throw new ZLinkConfigurationException(
       'Routing-id prefix is too long for a generated routing id.'
     );