@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,46 +1,65 @@
-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 { ZLinkFanoutListenerStatus } 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(
@@ -73,7 +92,6 @@ export interface ZLinkChannelClientTransport {
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
-  getFanoutListenerStatus?(channelName: string): ZLinkFanoutListenerStatus;
 }
 
 export type ZLinkChannelClientTransportSource =
@@ -187,7 +205,6 @@ interface ZLinkChannelTransportRuntime {
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>
   ): Promise<ZLinkSubmitResult>;
-  getFanoutListenerStatus(channelName: string): ZLinkFanoutListenerStatus;
   canRouteChannel(routerChannelId: string): boolean;
   canRoutePacketChannel(routerChannelId: string): boolean;
   routeSubmit(
@@ -281,7 +298,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 {
@@ -425,33 +443,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(
@@ -537,7 +614,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');
@@ -571,7 +648,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) {
@@ -593,12 +670,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)
@@ -608,12 +680,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) {
@@ -649,7 +716,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
             instanceSpotRouteFence(spotRouteTarget),
             encoded,
             undefined,
-            options.metadata
+            options.metadata,
+            options.instanceSpot
           )
         );
       }
@@ -699,12 +767,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)
@@ -714,12 +777,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);
@@ -757,7 +815,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
                 encoded,
                 options.timeoutMs,
                 undefined,
-                options.metadata
+                options.metadata,
+                options.instanceSpot
               )
             : node
                 .entrySpot()
@@ -970,7 +1029,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,
@@ -980,7 +1040,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       timeoutMs,
       undefined,
       this.codecs,
-      undefined,
+      correlationId,
       this.flowCreationEnabled(),
       metadata
     );
@@ -1024,7 +1084,7 @@ function directSpotRouteFence(
     target.authorityStoreVersion === undefined
   ) {
     throw createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.SpotRouteNotFound,
+      ZLinkFrameworkInternalErrorKind.RouteNotConnected,
       `Spot '${String(target.spotId)}' has no complete Ready authority fence.`
     );
   }
@@ -1068,24 +1128,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 {
@@ -1106,18 +1149,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;
-}

package/src/runtime/channels/client-server-service-wire.ts

@@ -1,16 +1,40 @@
-import type { ZLinkClientServerServerDescriptor } from '../../contracts/Locations';
-import { ZLinkFrameworkRuntimeState } from '../../contracts/Locations';
+import { UINT32_MAX } from '@zlink-systems/stream-wire';
+import { normalizeEndpoint } from '../../contracts/Configuration/EndpointNotation';
+import { isValidPublicWeight } from '../../contracts/Configuration/RegistrationBuilderPolicy';
+import {
+  type ZLinkClientServerServerDescriptor,
+  ZLinkFrameworkRuntimeState
+} from '../../contracts/Locations';
+
 import {
   decodeCanonicalServiceWireText,
   decodeServiceWireRoutingId,
   encodeCanonicalServiceWireText,
   encodeServiceWireRoutingId
 } from '../foundation/service-wire-binary-primitives';
-import { normalizeEndpoint } from '../../contracts/Configuration/EndpointNotation';
+import {
+  SERVICE_WIRE_MAGIC,
+  SERVICE_WIRE_MAJOR
+} from '../foundation/service-wire-constants.generated';
+export const DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT = 0x7fff_ffff;
+export function normalizeClientServerMessageLimit(value: number): number {
+  return Number.isSafeInteger(value) && value > 0
+    ? Math.min(value, UINT32_MAX)
+    : DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT;
+}
+
+const CLIENT_SERVER_PREFIX_BYTES = 5;
+const CLIENT_SERVER_ROLE_BODY_MAX_BYTES = 0xffff;
+const CLIENT_SERVER_TEXT_MAX_BYTES = 4096;
+
+export enum ClientServerRejectReason {
+  ProtocolVersionUnsupported = 1,
+  AdmissionMismatch = 3
+}
 
-const MAGIC_0 = 0x5a;
-const MAGIC_1 = 0x4d;
-const WIRE_MAJOR = 1;
+const MAGIC_0 = SERVICE_WIRE_MAGIC[0];
+const MAGIC_1 = SERVICE_WIRE_MAGIC[1];
+const WIRE_MAJOR = SERVICE_WIRE_MAJOR;
 const TOPOLOGY_CLIENT_SERVER = 2;
 const ROLE_CLIENT = 1;
 const ROLE_SERVER = 2;
@@ -22,7 +46,7 @@ const COMMAND_UPDATE = 4;
 const COMMAND_LIVENESS_PROBE = 5;
 const COMMAND_LIVENESS_ACK = 6;
 const MAX_DESCRIPTOR_BYTES = 1024 * 1024;
-const MAX_U32 = 0xffff_ffff;
+const MAX_U32 = UINT32_MAX;
 const MAX_GENERATION = 0x7fff_ffff_ffff_ffffn;
 
 export interface ZLinkClientServerHello {
@@ -99,7 +123,10 @@ export function encodeClientServerLivenessAck(probeId: bigint): Buffer {
 
 export function isClientServerControlFrame(frame: Uint8Array): boolean {
   return (
-    frame.byteLength >= 5 && frame[0] === MAGIC_0 && frame[1] === MAGIC_1 && frame[2] === WIRE_MAJOR
+    frame.byteLength >= CLIENT_SERVER_PREFIX_BYTES &&
+    frame[0] === MAGIC_0 &&
+    frame[1] === MAGIC_1 &&
+    frame[2] === WIRE_MAJOR
   );
 }
 
@@ -177,7 +204,8 @@ function encodeServerAdmission(
 }
 
 function encodeAdmission(command: number, role: number, roleBody: Buffer): Buffer {
-  if (roleBody.byteLength > 0xffff) fail('ClientServer role body is oversized.');
+  if (roleBody.byteLength > CLIENT_SERVER_ROLE_BODY_MAX_BYTES)
+    fail('ClientServer role body is oversized.');
   const admission = concat(Buffer.of(role), encodeU16(roleBody.byteLength), roleBody);
   const result = concat(
     prefix(command),
@@ -210,7 +238,7 @@ function decodeServerAdmission(reader: Reader): ZLinkClientServerAdmission {
   const lifecycleGeneration = reader.nonZeroU64('lifecycleGeneration');
   const descriptorRevision = reader.nonZeroU64('descriptorRevision');
   const weight = reader.u32('weight');
-  if (weight > 10_000) fail('ClientServer weight is invalid.');
+  if (!isValidPublicWeight(weight)) fail('ClientServer weight is invalid.');
   return {
     channelName,
     serverRid,
@@ -261,7 +289,7 @@ function encodeText8(value: string, field: string): Buffer {
 }
 
 function encodeText16(value: string, field: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, field, 4096, fail);
+  const bytes = encodeCanonicalServiceWireText(value, field, CLIENT_SERVER_TEXT_MAX_BYTES, fail);
   return concat(encodeU16(bytes.byteLength), bytes);
 }
 
@@ -373,7 +401,7 @@ class Reader {
 
   text16(field: string): string {
     const length = this.u16(`${field}.length`);
-    if (length < 1 || length > 4096) fail(`${field} length is invalid.`);
+    if (length < 1 || length > CLIENT_SERVER_TEXT_MAX_BYTES) fail(`${field} length is invalid.`);
     return decodeText(this.bytes(length, field), field);
   }
 

package/src/runtime/channels/dispatch-error-reporter.ts

@@ -1,19 +1,21 @@
 import {
-  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind,
+  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
   type ZLinkDispatchFailure
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
 import {
-  ZLinkMessageFlowTracer,
+  type ZLinkRuntimeMetrics,
   DEFAULT_ZLINK_DIAGNOSTICS,
+  ZLinkMessageFlowTracer,
   type ZLinkDiagnosticsContext
 } from '../diagnostics';
-import type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
+
 import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
+import type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
+import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
 
 export type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
 
@@ -49,7 +51,7 @@ export class ZLinkDispatchErrorReporter {
     const normalized = normalizeDispatchFailure(event);
     const dropReason = channelDropReason(normalized);
     if (dropReason !== undefined) {
-      this.metrics?.count('zlink.mesh_node.messages.dropped', 1, {
+      this.metrics?.count(METRIC_NAMES.MeshNodeMessagesDropped, 1, {
         surface: normalized.surface,
         message_kind: normalized.messageKind,
         reason: dropReason