@zlink-systems/framework 0.26.0 → 0.28.0

package/src/runtime/channels/channel-transports.ts

@@ -1,52 +1,71 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind,
-  internalFrameworkErrorKindFromWireReply,
-  isCanonicalWireReplyTerminal
-} from '../framework-errors-internal';
-import { ZLinkBufferMessage } from '../backend/runtime-message';
-import {
-  RequestResult,
-  SubmitResult,
-  isZLinkBackendResultError,
-  type ZLinkBackendMessageLike as MessageLike
-} from '../backend/runtime-values';
-import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
-import type { ZLinkFrameworkInternalErrorKind as ZLinkFrameworkInternalErrorKindType } from '../framework-errors-internal';
 import { ZLinkFrameworkException } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
-import { ZLinkConfigurationException } from '../configuration';
-import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import { ZLinkSpotKind } from '../../contracts/Spots';
 import { throwIfAborted } from '../abort';
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
 import {
   closeMeshCompletion,
   type ZLinkMeshCompletion,
   type ZLinkMeshCompletionTable
 } from '../backend/mesh-completion-table';
-import { routingIdsEqual, toBackendRoutingId as toBackendRoutingId } from '../routing-id';
+import { ZLinkBufferMessage } from '../backend/runtime-message';
 import {
-  decodeChannelReply,
-  encodeChannelEnvelopeParts,
-  type ZLinkChannelEnvelopeCodecRegistry,
-  ZLinkChannelMessageKind
-} from './channel-envelope';
+  RequestResult,
+  isZLinkBackendResultError,
+  type ZLinkBackendMessageLike as MessageLike
+} from '../backend/runtime-values';
+import { ZLinkConfigurationException } from '../configuration';
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import { runWithOutboundFlow } from '../diagnostics/flow-context';
+import { flowIfEnabled, type ZLinkMessageFlowTracer } from '../diagnostics';
+import {
+  ZLinkDispatchErrorSurface,
+  ZLinkDispatchMessageKind,
+  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
+  type ZLinkRuntimeMessageFlowResult
+} from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { isRemoteChannelErrorReply, requestTerminalResult } from './channel-outbound-operations';
+import { ServiceStaleGenerationError } from '../foundation/service-stateful-registry';
 import type {
   ServiceDirectSpotRouteFence,
   ServiceInstanceRouteFence
 } from '../foundation/service-stateful-wire-codec';
-import { ServiceStaleGenerationError } from '../foundation/service-stateful-registry';
-import { runWithOutboundFlow } from '../diagnostics/flow-context';
+import {
+  type ZLinkFrameworkInternalErrorKind as ZLinkFrameworkInternalErrorKindType,
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  internalFrameworkErrorKindFromWireReply,
+  isCanonicalWireReplyTerminal,
+  requestResultToPublicErrorKind
+} from '../framework-errors-internal';
+
+import {
+  classifySubmitResult,
+  submitToRequestResult,
+  ZLinkSubmitStatus,
+  type ZLinkSubmitResult
+} from '../messaging/submission-result';
+import { routingIdsEqual, toBackendRoutingId } from '../routing-id';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type {
+  ZLinkSpotRoutedSendOptions,
+  ZLinkSpotRoutedRequestOptions
+} from '../spots/spot-outbound';
+import {
+  ZLinkChannelMessageKind,
+  decodeChannelReply,
+  encodeChannelEnvelopeParts,
+  newChannelCorrelationId,
+  type ZLinkChannelEnvelopeCodecRegistry
+} from './channel-envelope';
 
 export interface ZLinkChannelClientTransport {
   send(
     channelName: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
   request<TReply>(
@@ -103,7 +122,6 @@ export interface ZLinkRouteClientTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
   request<TReply>(
@@ -120,7 +138,6 @@ export interface ZLinkRouteClientTransport {
     channelName: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
   requestToChannel<TReply>(
@@ -137,8 +154,6 @@ export interface ZLinkRouteClientTransport {
     message: unknown,
     options: {
       readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
       readonly metadata?: ReadonlyMap<string, string>;
     }
   ): Promise<ZLinkSubmitResult>;
@@ -159,7 +174,6 @@ interface ZLinkChannelTransportRuntime {
     channelName: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult>;
   request<TReply>(
@@ -192,7 +206,6 @@ interface ZLinkChannelTransportRuntime {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult>;
   routeRequest<TReply>(
@@ -208,18 +221,14 @@ interface ZLinkChannelTransportRuntime {
     spotRouteTarget: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    timeoutMs?: number
+    metadata?: ReadonlyMap<string, string>
   ): Promise<void>;
   routeSendFromSpotToSpot(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    timeoutMs?: number
+    metadata?: ReadonlyMap<string, string>
   ): Promise<void>;
   routeRequestToSpot<TReply>(
     spotRouteTarget: ZLinkSpotRouteTarget,
@@ -278,7 +287,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       parts: readonly MessageLike[]
     ) => ZLinkSubmitResult,
     private readonly metrics?: ZLinkRuntimeMetrics,
-    private readonly flowCreationEnabled: () => boolean = () => true
+    private readonly flowCreationEnabled: () => boolean = () => true,
+    private readonly outboundFlow: () => ZLinkMessageFlowTracer | undefined = () => undefined
   ) {}
 
   canRouteChannel(routerChannelId: string): boolean {
@@ -302,13 +312,12 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
     // Call-scoped flow (spec 27 §4): the envelope flow pair lives only for
     // the duration of this outbound call, never in the caller's context.
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
-      this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, false)
+      this.submitNode(meshName, targetNodeRid, packetName, message, metadata, false)
     );
   }
 
@@ -317,11 +326,10 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
-      this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, true)
+      this.submitNode(meshName, targetNodeRid, packetName, message, metadata, true)
     );
   }
 
@@ -330,7 +338,6 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown,
-    signal: AbortSignal | undefined,
     metadata: ReadonlyMap<string, string> | undefined,
     allowObjectClientTarget: boolean
   ): Promise<ZLinkSubmitResult> {
@@ -341,11 +348,9 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         targetNodeRid,
         packetName,
         message,
-        signal,
         metadata
       );
     }
-    throwIfAborted(signal);
     if (
       !allowObjectClientTarget &&
       node.isObjectClientNodeDirectTarget?.(toBackendRoutingId(targetNodeRid)) === true
@@ -422,33 +427,92 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         metadata
       );
     }
-    throwIfAborted(signal);
-    if (node.isObjectClientNodeDirectTarget?.(toBackendRoutingId(targetNodeRid)) === true) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-        `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`
+    const correlationId = newChannelCorrelationId();
+    try {
+      throwIfAborted(signal);
+      if (node.isObjectClientNodeDirectTarget?.(toBackendRoutingId(targetNodeRid)) === true) {
+        throw createInternalFrameworkException(
+          ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+          `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`
+        );
+      }
+      const parts = this.encodeMessage(
+        ZLinkChannelMessageKind.Request,
+        meshName,
+        packetName,
+        request,
+        timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        metadata,
+        correlationId
       );
+      const completion = await this.submitRequestOperation(
+        meshName,
+        timeoutMs,
+        signal,
+        `MeshNode '${meshName}' request to node '${targetNodeRid}'`,
+        (remainingTimeoutMs) => {
+          const operationId = node.requestToNode(toBackendRoutingId(targetNodeRid), parts, {
+            flags: 1,
+            timeoutMs: remainingTimeoutMs
+          });
+          this.traceNodeRequest(
+            ZLinkMessageFlowOutcome.Sent,
+            undefined,
+            meshName,
+            targetNodeRid,
+            packetName,
+            correlationId
+          );
+          return operationId;
+        }
+      );
+      const reply = this.decodeMeshReply<TReply>(meshName, completion);
+      this.traceNodeRequest(
+        ZLinkMessageFlowOutcome.ReplyReceived,
+        'succeeded',
+        meshName,
+        targetNodeRid,
+        packetName,
+        correlationId
+      );
+      return reply;
+    } catch (error) {
+      if (!isRemoteChannelErrorReply(error)) {
+        this.traceNodeRequest(
+          ZLinkMessageFlowOutcome.ReplyReceived,
+          requestTerminalResult(error, signal),
+          meshName,
+          targetNodeRid,
+          packetName,
+          correlationId,
+          error
+        );
+      }
+      throw error;
     }
-    const parts = this.encodeMessage(
-      ZLinkChannelMessageKind.Request,
+  }
+
+  private traceNodeRequest(
+    outcome: ZLinkMessageFlowOutcome,
+    result: ZLinkRuntimeMessageFlowResult | undefined,
+    meshName: string,
+    targetRid: string,
+    packetName: string | undefined,
+    correlationId: string,
+    error?: unknown
+  ): void {
+    if (!this.flowCreationEnabled()) return;
+    flowIfEnabled(this.outboundFlow(), outcome, result)?.trace({
+      outcome,
+      result,
+      surface: ZLinkDispatchErrorSurface.Node,
+      messageKind: ZLinkDispatchMessageKind.Request,
       meshName,
+      targetRid,
       packetName,
-      request,
-      timeoutMs ?? 30_000,
-      metadata
-    );
-    const completion = await this.submitRequestOperation(
-      meshName,
-      timeoutMs,
-      signal,
-      `MeshNode '${meshName}' request to node '${targetNodeRid}'`,
-      (remainingTimeoutMs) =>
-        node.requestToNode(toBackendRoutingId(targetNodeRid), parts, {
-          flags: 1,
-          timeoutMs: remainingTimeoutMs
-        })
-    );
-    return this.decodeMeshReply(meshName, completion);
+      correlationId,
+      ...(error instanceof Error ? { errorType: error.name, errorMessage: error.message } : {})
+    });
   }
 
   submitToChannel(
@@ -456,11 +520,10 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     channelName: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
-      this.submitToChannelScoped(meshName, channelName, packetName, message, signal, metadata)
+      this.submitToChannelScoped(meshName, channelName, packetName, message, metadata)
     );
   }
 
@@ -469,10 +532,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     channelName: string,
     packetName: string | undefined,
     message: unknown,
-    signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult> {
-    throwIfAborted(signal);
     const node = this.requireMeshNode(meshName);
     const parts = this.encodeMessage(
       ZLinkChannelMessageKind.Command,
@@ -534,7 +595,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       channelName,
       packetName,
       request,
-      timeoutMs ?? 30_000,
+      timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
       metadata
     );
     const metric = this.metrics?.startRequest(meshName, 'channel');
@@ -568,7 +629,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       remainingTimeoutMs: number
     ) => ReturnType<Parameters<ZLinkMeshCompletionTable['submit']>[0]>
   ): Promise<ZLinkMeshCompletion> {
-    const effectiveTimeoutMs = Math.max(1, timeoutMs ?? 30_000);
+    const effectiveTimeoutMs = Math.max(1, timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
     const deadlineMs = performance.now() + effectiveTimeoutMs;
     const remainingTimeoutMs = deadlineMs - performance.now();
     if (remainingTimeoutMs <= 0) {
@@ -590,12 +651,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
-    options: {
-      readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
-      readonly metadata?: ReadonlyMap<string, string>;
-    }
+    options: ZLinkSpotRoutedSendOptions
   ): Promise<ZLinkSubmitResult> {
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
       this.sendToSpotScoped(spotRouteTarget, message, options)
@@ -605,12 +661,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   private async sendToSpotScoped(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
-    options: {
-      readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
-      readonly metadata?: ReadonlyMap<string, string>;
-    }
+    options: ZLinkSpotRoutedSendOptions
   ): Promise<ZLinkSubmitResult> {
     const node = this.meshNode(spotRouteTarget.routerChannelId);
     if (node === undefined) {
@@ -623,13 +674,10 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         spotRouteTarget,
         options.packetName,
         message,
-        options.signal,
-        options.metadata,
-        options.timeoutMs
+        options.metadata
       );
       return { status: ZLinkSubmitStatus.Submitted };
     }
-    throwIfAborted(options.signal);
     const operation = `MeshNode '${spotRouteTarget.routerChannelId}' send to Spot '${spotRouteTarget.spotId}'`;
     try {
       const encoded = this.encodeMessage(
@@ -646,7 +694,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
             instanceSpotRouteFence(spotRouteTarget),
             encoded,
             undefined,
-            options.metadata
+            options.metadata,
+            options.instanceSpot
           )
         );
       }
@@ -676,8 +725,6 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     message: unknown,
     options: {
       readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
       readonly metadata?: ReadonlyMap<string, string>;
     }
   ): Promise<ZLinkSubmitResult> {
@@ -686,9 +733,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       spotRouteTarget,
       options.packetName,
       message,
-      options.signal,
-      options.metadata,
-      options.timeoutMs
+      options.metadata
     );
     return { status: ZLinkSubmitStatus.Submitted };
   }
@@ -696,12 +741,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: {
-      readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
-      readonly metadata?: ReadonlyMap<string, string>;
-    }
+    options: ZLinkSpotRoutedRequestOptions
   ): Promise<TReply> {
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
       this.requestToSpotScoped<TReply>(spotRouteTarget, request, options)
@@ -711,12 +751,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   private async requestToSpotScoped<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: {
-      readonly packetName?: string;
-      readonly timeoutMs?: number;
-      readonly signal?: AbortSignal;
-      readonly metadata?: ReadonlyMap<string, string>;
-    }
+    options: ZLinkSpotRoutedRequestOptions
   ): Promise<TReply> {
     const meshName = spotRouteTarget.routerChannelId;
     const node = this.meshNode(meshName);
@@ -754,7 +789,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
                 encoded,
                 options.timeoutMs,
                 undefined,
-                options.metadata
+                options.metadata,
+                options.instanceSpot
               )
             : node
                 .entrySpot()
@@ -967,7 +1003,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     packetName: string | undefined,
     message: unknown,
     timeoutMs?: number,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    correlationId?: string
   ): readonly MessageLike[] {
     return encodeChannelEnvelopeParts(
       kind,
@@ -977,7 +1014,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       timeoutMs,
       undefined,
       this.codecs,
-      undefined,
+      correlationId,
       this.flowCreationEnabled(),
       metadata
     );
@@ -1021,7 +1058,7 @@ function directSpotRouteFence(
     target.authorityStoreVersion === undefined
   ) {
     throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.SpotRouteNotFound,
+      ZLinkFrameworkInternalErrorKind.RouteNotConnected,
       `Spot '${String(target.spotId)}' has no complete Ready authority fence.`
     );
   }
@@ -1065,24 +1102,7 @@ function instanceSpotRouteFence(target: ZLinkSpotRouteTarget): ServiceInstanceRo
 }
 
 function mapMeshSubmitResult(result: number): ZLinkSubmitResult {
-  switch (result) {
-    case SubmitResult.Ok:
-      return { status: ZLinkSubmitStatus.Submitted };
-    case SubmitResult.Backpressured:
-    case SubmitResult.NotAdmitted:
-      return { status: ZLinkSubmitStatus.Backpressured };
-    case SubmitResult.NotFound:
-      return { status: ZLinkSubmitStatus.TargetNotFound };
-    case SubmitResult.NotConnected:
-      return { status: ZLinkSubmitStatus.RouteNotConnected };
-    case SubmitResult.Terminated:
-      return { status: ZLinkSubmitStatus.Shutdown };
-    default:
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestFailed,
-        `Mesh submission failed with result ${result}.`
-      );
-  }
+  return classifySubmitResult(result, 'Mesh submission');
 }
 
 function mapMeshSubmissionError(error: unknown, operation: string): Error {
@@ -1103,18 +1123,21 @@ function mapMeshSubmissionError(error: unknown, operation: string): Error {
     );
   }
   if (isZLinkBackendResultError(error)) {
-    const notFound = error.result === SubmitResult.NotFound || error.result === 102;
-    const retriable =
-      error.result === SubmitResult.Backpressured ||
-      error.result === SubmitResult.NotConnected ||
-      error.result === 109 ||
-      error.result === 113;
-    return createInternalFrameworkException(
-      notFound
-        ? ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
-        : ZLinkFrameworkInternalErrorKind.RouteNotConnected,
+    const terminal =
+      error.operation === 'request'
+        ? error.result
+        : submitToRequestResult(error.result, error.phase);
+    if (terminal === RequestResult.NotFound) {
+      return createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+        `${operation} failed with result ${error.result}.`,
+        false,
+        error
+      );
+    }
+    return new ZLinkFrameworkException(
+      requestResultToPublicErrorKind(terminal),
       `${operation} failed with result ${error.result}.`,
-      retriable,
       error
     );
   }

package/src/runtime/channels/client-server-location-runtime.ts

@@ -1,3 +1,5 @@
+import type { Message } from '../../contracts/Common/Message';
+import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import {
   ZLinkFrameworkRuntimeState,
   ZLinkLocationWriteIntent,
@@ -5,26 +7,28 @@ import {
   type ZLinkClientServerServerDescriptor,
   type ZLinkLocationOwnerToken
 } from '../../contracts/Locations';
-import type { ZLinkClientServerLocationStore } from '../locations/internal-store-contracts';
 import {
   zlinkRuntimeDefaultLocationOptions,
   type ZLinkLocationOptionOverrides
 } from '../../contracts/Locations/Options';
-import type { ZLinkFrameworkRegistration } from '../configuration';
-import { ZLinkConfigurationException } from '../configuration';
-import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
-import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+import { ZLINK_PROVIDER_MAX_PAGE_SIZE } from '../../contracts/Locations/Stores';
 import type { ZLinkBackendDealerSocket } from '../backend/contracts';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import type { Message } from '../../contracts/Common/Message';
+import { isBackendRequestTimeoutError } from '../backend/runtime-values';
+import { type ZLinkFrameworkRegistration, ZLinkConfigurationException } from '../configuration';
+
+import { ZLinkStateLane } from '../execution/state-lane';
+import { discoveryAvailabilityForRuntimeState } from '../foundation/runtime-state-projections';
+import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
+import type { ZLinkClientServerLocationStore } from '../locations/internal-store-contracts';
+import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
 import {
   decodeClientServerControl,
+  DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT,
   encodeClientServerHello,
+  normalizeClientServerMessageLimit,
   type ZLinkClientServerAdmission
 } from './client-server-service-wire';
-import { discoveryAvailabilityForRuntimeState } from '../foundation/runtime-state-projections';
-import { ZLinkStateLane } from '../execution/state-lane';
-import { isBackendRequestTimeoutError } from '../backend/runtime-values';
 
 interface ActiveClientServerTarget {
   descriptor: ZLinkClientServerServerDescriptor;
@@ -170,7 +174,7 @@ export class ZLinkClientServerLocationRuntime {
         lifecycleGeneration: identity.lifecycleGeneration,
         descriptorRevision: 1n,
         endpoint: identity.endpoint,
-        weight: channel.server.weight ?? 100,
+        weight: channel.server.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT,
         state: ZLinkFrameworkRuntimeState.Serving,
         securityIdentity: 'default',
         ownerId: owner.ownerId,
@@ -250,7 +254,7 @@ export class ZLinkClientServerLocationRuntime {
     do {
       const page = await this.store.listClientServers(
         channelName,
-        { pageSize: 1000, continuationToken },
+        { pageSize: ZLINK_PROVIDER_MAX_PAGE_SIZE, continuationToken },
         signal
       );
       rows.push(...page.items);
@@ -517,7 +521,7 @@ function sameDescriptor(
 
 function toDiscoveryDescriptor(
   descriptor: ZLinkClientServerServerDescriptor,
-  effectiveMaxMessageBytes = 0x7fff_ffff
+  effectiveMaxMessageBytes: number = DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT
 ) {
   return {
     channelName: descriptor.channelName,
@@ -541,7 +545,7 @@ function requestAdmission(
     encodeClientServerHello({
       channelName: descriptor.channelName,
       securityIdentity: descriptor.securityIdentity,
-      normalizedEffectiveMaxMessageBytes: normalizedMessageLimit(dealer.maxMessageSize)
+      normalizedEffectiveMaxMessageBytes: normalizeClientServerMessageLimit(dealer.maxMessageSize)
     })
   );
   return dealer.request(message, timeoutMs).then(
@@ -600,7 +604,3 @@ function requireMatchingAdmission(
 function closeMessages(parts: readonly Message[]): void {
   for (const part of parts) part.close();
 }
-
-function normalizedMessageLimit(value: number): number {
-  return Number.isSafeInteger(value) && value > 0 ? Math.min(value, 0xffff_ffff) : 0x7fff_ffff;
-}