@zlink-systems/framework 0.26.0 → 0.27.0

package/src/runtime/foundation/service-stateful-wire-codec.ts

@@ -1,40 +1,24 @@
-import type {
-  ServiceActorRef,
-  ServiceSessionBinding,
-  ServiceSpotRef
-} from './service-stateful-registry';
-import { operationRequiresReply } from './service-runtime-contracts';
-import { ServiceWireProtocolError } from './service-wire-m6a-codec';
+import { UINT64_MAX, ZlinkStreamContentType } from '@zlink-systems/stream-wire';
+import { RELOCATION_STATE_CHUNK_DATA_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 import { isCanonicalWireReplyTerminal } from '../framework-errors-internal';
-import { routingIdsEqual } from '../routing-id';
-import {
-  SERVICE_WIRE_MAGIC,
-  SERVICE_WIRE_MAJOR,
-  ServiceWireCommand,
-  ServiceWireFlag
-} from './service-wire-constants.generated';
-import {
-  decodeCanonicalServiceWireText,
-  decodeServiceWireRoutingId,
-  encodeCanonicalServiceWireText,
-  encodeServiceWireRoutingId
-} from './service-wire-binary-primitives';
 import {
   decodeActorRequestCommand,
   decodeActorSendCommand,
   decodeMetadataFrame,
+  decodeInstanceRouteV1,
   decodeSpotRequestCommand,
   decodeSpotSendCommand,
   encodeActorRequestCommand,
   encodeActorSendCommand,
   encodeApplicationPayloadEnvelopeV1,
+  encodeInstanceRouteV1,
   encodeSpotRequestCommand,
   encodeSpotSendCommand,
   type ServiceWireDecoderContext
 } from '../protocol/service_wire_codec.generated';
 import {
-  decodeActorCreate49 as decodeGeneratedActorCreate49,
   decodeActorJoin28,
+  decodeActorCreate49 as decodeGeneratedActorCreate49,
   decodeRelocationCutover34 as decodeGeneratedRelocationCutover34,
   decodeRelocationData31 as decodeGeneratedRelocationData31,
   decodeRelocationFailed53 as decodeGeneratedRelocationFailed53,
@@ -63,20 +47,45 @@ import {
   encodeUserSpotClose48 as encodeGeneratedUserSpotClose48,
   encodeUserSpotCreate47 as encodeGeneratedUserSpotCreate47,
   type ActorCreate49 as GeneratedActorCreate49,
+  type ServiceWireCoordinatorFence as GeneratedCoordinatorFence,
   type RelocationObjectIdentity as GeneratedRelocationObjectIdentity,
   type ReplyRelay33 as GeneratedReplyRelay33,
-  type ServiceWireCoordinatorFence as GeneratedCoordinatorFence,
   type ServiceWireRequestSourceFence as GeneratedRequestSourceFence,
   type ServiceWireRouteFence as GeneratedRouteFence,
-  type ServiceWireTargetFence as GeneratedTargetFence,
   type SessionRelocationRoute44 as GeneratedSessionRelocationRoute44,
   type SessionRelocationSeal42 as GeneratedSessionRelocationSeal42,
   type SessionRelocationSealed43 as GeneratedSessionRelocationSealed43,
+  type ServiceWireTargetFence as GeneratedTargetFence,
   type UserSpotClose48 as GeneratedUserSpotClose48,
   type UserSpotCreate47 as GeneratedUserSpotCreate47
 } from '../protocol/service_wire_pilot_codec.generated';
+import { routingIdsEqual } from '../routing-id';
+import { operationRequiresReply } from './service-runtime-contracts';
+import type {
+  ServiceActorRef,
+  ServiceSessionBinding,
+  ServiceSpotRef
+} from './service-stateful-registry';
+import {
+  decodeCanonicalServiceWireText,
+  decodeServiceWireRoutingId,
+  encodeCanonicalServiceWireText,
+  encodeServiceWireRoutingId,
+  SERVICE_WIRE_PREFIX_SIZE
+} from './service-wire-binary-primitives';
+import {
+  SERVICE_WIRE_MAGIC,
+  SERVICE_WIRE_MAJOR,
+  ServiceWireCommand,
+  ServiceWireFlag
+} from './service-wire-constants.generated';
+import { APPLICATION_PAYLOAD_VERSION, ServiceWireProtocolError } from './service-wire-m6a-codec';
+const MESSAGE_FOLLOW_MAX_BODY_BYTES = 16 * 1024 * 1024;
+const MESSAGE_FOLLOW_VERSION = 1;
+const INSTANCE_ROUTE_VERSION = 1;
+const INSTANCE_ACTIVATION_VERSION = 2;
 
-const PREFIX_SIZE = 5;
+const PREFIX_SIZE = SERVICE_WIRE_PREFIX_SIZE;
 const MAGIC_0 = SERVICE_WIRE_MAGIC[0];
 const MAGIC_1 = SERVICE_WIRE_MAGIC[1];
 const MAJOR = SERVICE_WIRE_MAJOR;
@@ -161,7 +170,7 @@ export type ServiceWireRelocationObject =
 /** Shared CRC-32C wire bounds for the direct relocation payload transfer. */
 export const RELOCATION_PAYLOAD_TOTAL_LENGTH_MAX = 274_877_906_944n;
 export const RELOCATION_PAYLOAD_CHUNK_COUNT_MAX = 4096;
-export const RELOCATION_STATE_CHUNK_DATA_MAX_BYTES = 67_108_864;
+export { RELOCATION_STATE_CHUNK_DATA_MAX_BYTES } from '../../contracts/Configuration/InternalDefaults';
 
 interface ServiceWireRelocationBase {
   readonly relocation: ServiceWireOperationId;
@@ -1086,6 +1095,7 @@ export type ServiceStatefulWireRecord =
   | {
       readonly kind: 'instanceSpot';
       readonly activation: 'ready';
+      readonly instanceIntent: boolean;
       readonly route: ServiceInstanceRouteFence;
       readonly sourceNodeGeneration: bigint;
       readonly sourceNodeRid: string;
@@ -1161,7 +1171,7 @@ const STATEFUL_MESSAGE_CONTEXT: ServiceWireDecoderContext = {
 };
 const STATEFUL_HEADER_PAYLOAD = {
   packetName: 'wire',
-  contentType: 'application/json',
+  contentType: ZlinkStreamContentType.Json,
   payload: Buffer.from('{}')
 };
 
@@ -1384,17 +1394,25 @@ export function encodeInstanceSpotHeader(
   operationKind: 'send' | 'request',
   operation: { readonly high: bigint; readonly low: bigint },
   replyRouteId?: bigint,
-  hasMetadata = false
+  hasMetadata = false,
+  instanceIntent = false
 ): Buffer {
-  const routeBody = concat(
-    rid(route.targetNodeRid, 'targetNodeRid'),
-    u64(route.targetNodeGeneration),
-    rid(route.targetSpotId, 'targetSpotId'),
-    u64(route.objectGeneration),
-    text8(route.ownerId, 'ownerId'),
-    u64(route.authorityOwnerGeneration),
-    u64(route.leaseGeneration),
-    text16(route.storeVersion, 'storeVersion')
+  const encodedRoute = encodeInstanceRouteV1(
+    {
+      routeKind: 'ready',
+      targetNodeRid: toGeneratedRoutingId(route.targetNodeRid, 'targetNodeRid'),
+      targetNodeGeneration: route.targetNodeGeneration,
+      targetSpotId: route.targetSpotId,
+      authority: {
+        objectGeneration: route.objectGeneration,
+        ownerId: route.ownerId,
+        authorityOwnerGeneration: route.authorityOwnerGeneration,
+        leaseGeneration: route.leaseGeneration,
+        storeVersion: route.storeVersion
+      },
+      instanceIntent: instanceIntent ? 'true' : 'false'
+    },
+    STATEFUL_MESSAGE_CONTEXT
   );
   if (
     operationKind === 'send' &&
@@ -1407,9 +1425,7 @@ export function encodeInstanceSpotHeader(
   }
   return concat(
     prefix(M6bServiceWireCommand.instanceSpot, hasMetadata ? M6bServiceWireFlag.metadata : 0),
-    Buffer.of(1),
-    u16(routeBody.byteLength),
-    routeBody,
+    encodedRoute,
     u64Any(sourceNodeGeneration),
     rid(sourceNodeRid, 'sourceNodeRid'),
     optionalRid(sourceSpotId),
@@ -1449,7 +1465,7 @@ export function encodeInstanceSpotActivationHeader(
   );
   return concat(
     prefix(M6bServiceWireCommand.instanceSpot, hasMetadata ? M6bServiceWireFlag.metadata : 0),
-    Buffer.of(2),
+    Buffer.of(INSTANCE_ACTIVATION_VERSION),
     u16(targetBody.byteLength),
     targetBody,
     u64Any(sourceNodeGeneration),
@@ -1493,12 +1509,14 @@ export function encodeMessageFollowHeader(
     u64Any(record.originalOperation.low),
     u64Any(record.originalReplyRouteId)
   );
-  if (body.byteLength > 16 * 1024 * 1024) {
-    throw new RangeError('Message Follow body exceeds 16 MiB.');
+  if (body.byteLength > MESSAGE_FOLLOW_MAX_BODY_BYTES) {
+    throw new RangeError(
+      `Message Follow body exceeds ${MESSAGE_FOLLOW_MAX_BODY_BYTES / (1024 * 1024)} MiB.`
+    );
   }
   return concat(
     prefix(M6bServiceWireCommand.messageFollow),
-    Buffer.of(1),
+    Buffer.of(MESSAGE_FOLLOW_VERSION),
     u32(body.byteLength, 'messageFollow.length'),
     body
   );
@@ -1724,34 +1742,53 @@ export function decodeStatefulHeader(
       if ((command.flags & ~M6bServiceWireFlag.metadata) !== 0) {
         fail(`Invalid command flags '${command.flags}'.`);
       }
+      const routeStart = reader.offset;
       const version = reader.u8('instanceRoute.version');
-      if (version !== 1 && version !== 2) fail('Unsupported Instance route version.');
+      if (version !== INSTANCE_ROUTE_VERSION && version !== INSTANCE_ACTIVATION_VERSION)
+        fail('Unsupported Instance route version.');
       const routeLength = reader.u16('instanceRoute.length');
       const routeEnd = reader.offset + routeLength;
-      const commonTarget = {
-        targetNodeRid: reader.rid('targetNodeRid'),
-        targetNodeGeneration: reader.nonZeroU64('targetNodeGeneration'),
-        targetSpotId: reader.rid('targetSpotId')
-      };
+      const generatedReadyRoute =
+        version === INSTANCE_ROUTE_VERSION
+          ? decodeInstanceRouteV1(
+              reader.bytes.subarray(routeStart, routeEnd),
+              STATEFUL_MESSAGE_CONTEXT
+            )
+          : undefined;
+      if (generatedReadyRoute !== undefined && generatedReadyRoute.routeKind !== 'ready') {
+        fail('Invalid Ready Instance route kind.');
+      }
+      const commonTarget =
+        generatedReadyRoute?.routeKind === 'ready'
+          ? {
+              targetNodeRid: fromGeneratedRoutingId(
+                generatedReadyRoute.targetNodeRid,
+                'targetNodeRid'
+              ),
+              targetNodeGeneration: generatedReadyRoute.targetNodeGeneration,
+              targetSpotId: generatedReadyRoute.targetSpotId
+            }
+          : {
+              targetNodeRid: reader.rid('targetNodeRid'),
+              targetNodeGeneration: reader.nonZeroU64('targetNodeGeneration'),
+              targetSpotId: reader.rid('targetSpotId')
+            };
       const route: ServiceInstanceRouteFence | undefined =
-        version === 1
+        generatedReadyRoute?.routeKind === 'ready'
           ? {
               ...commonTarget,
-              objectGeneration: reader.nonZeroU64('objectGeneration'),
-              ownerId: reader.text8('ownerId'),
-              authorityOwnerGeneration: reader.nonZeroU64('authorityOwnerGeneration'),
-              leaseGeneration: reader.nonZeroU64('leaseGeneration'),
-              storeVersion: reader.text16('storeVersion')
+              ...generatedReadyRoute.authority
             }
           : undefined;
       const target: ServiceInstanceActivationTarget | undefined =
-        version === 2
+        version === INSTANCE_ACTIVATION_VERSION
           ? {
               ...commonTarget,
               stableType: reader.text16('stableType'),
               descriptorVersion: reader.text16('descriptorVersion')
             }
           : undefined;
+      if (generatedReadyRoute !== undefined) reader.offset = routeEnd;
       if (reader.offset !== routeEnd) fail('Invalid Instance route body length.');
       const sourceNodeGeneration = reader.nonZeroU64('sourceNodeGeneration');
       const sourceNodeRid = reader.rid('sourceNodeRid');
@@ -1764,16 +1801,21 @@ export function decodeStatefulHeader(
       };
       const operationKind = operationValue === 1 ? ('send' as const) : ('request' as const);
       if (
-        version === 1 &&
+        version === INSTANCE_ROUTE_VERSION &&
         ((operationKind === 'send' && (operation.high !== 0n || operation.low !== 0n)) ||
           (operationKind === 'request' && operation.high === 0n && operation.low === 0n))
       ) {
         fail('Invalid Instance operation identity.');
       }
-      if (version === 2 && operation.high === 0n && operation.low === 0n) {
+      if (
+        version === INSTANCE_ACTIVATION_VERSION &&
+        operation.high === 0n &&
+        operation.low === 0n
+      ) {
         fail('Instance activation requires a non-zero operation identity.');
       }
-      const deadlineUnixMs = version === 2 ? reader.nonZeroU64('deadlineUnixMs') : undefined;
+      const deadlineUnixMs =
+        version === INSTANCE_ACTIVATION_VERSION ? reader.nonZeroU64('deadlineUnixMs') : undefined;
       const replyRouteId =
         operationKind === 'request' ? reader.nonZeroU64('replyRouteId') : undefined;
       reader.end();
@@ -1786,8 +1828,13 @@ export function decodeStatefulHeader(
         operation,
         ...(replyRouteId === undefined ? {} : { replyRouteId })
       };
-      return version === 1
-        ? { ...common, activation: 'ready', route: route! }
+      return version === INSTANCE_ROUTE_VERSION
+        ? {
+            ...common,
+            activation: 'ready',
+            route: route!,
+            instanceIntent: generatedReadyRoute!.instanceIntent === 'true'
+          }
         : {
             ...common,
             activation: 'missing',
@@ -1797,12 +1844,12 @@ export function decodeStatefulHeader(
     }
     case M6bServiceWireCommand.messageFollow: {
       requireFlags(command.flags, 0);
-      if (reader.u8('messageFollow.version') !== 1) {
+      if (reader.u8('messageFollow.version') !== MESSAGE_FOLLOW_VERSION) {
         fail('Unsupported Message Follow version.');
       }
       const length = reader.u32('messageFollow.length');
       const end = reader.offset + length;
-      if (length > 16 * 1024 * 1024 || end > reader.bytes.byteLength) {
+      if (length > MESSAGE_FOLLOW_MAX_BODY_BYTES || end > reader.bytes.byteLength) {
         fail('Invalid Message Follow body length.');
       }
       const record: ServiceMessageFollowRecord = {
@@ -2231,7 +2278,11 @@ function applicationPayload(value: NonNullable<ServiceMaintenanceReplyRelay['pay
     u32(value.bytes.byteLength, 'payload.length'),
     value.bytes
   );
-  return concat(Buffer.of(1), u32(body.byteLength, 'applicationPayload.length'), body);
+  return concat(
+    Buffer.of(APPLICATION_PAYLOAD_VERSION),
+    u32(body.byteLength, 'applicationPayload.length'),
+    body
+  );
 }
 
 function prefix(command: number, flags = 0): Buffer {
@@ -2316,7 +2367,7 @@ function validateMessageFollowRecord(
   if (value.originalOperation.high === 0n && value.originalOperation.low === 0n) {
     invalid('Message Follow originalOperation must not be zero.');
   }
-  if (value.originalReplyRouteId < 0n || value.originalReplyRouteId > 0xffff_ffff_ffff_ffffn) {
+  if (value.originalReplyRouteId < 0n || value.originalReplyRouteId > UINT64_MAX) {
     invalid('Message Follow originalReplyRouteId must be a u64.');
   }
 }
@@ -2376,7 +2427,7 @@ function u64(value: bigint): Buffer {
 }
 
 function u64Any(value: bigint): Buffer {
-  if (value < 0n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value < 0n || value > UINT64_MAX) {
     throw new RangeError('u64 value is out of range.');
   }
   const result = Buffer.alloc(8);
@@ -2385,7 +2436,7 @@ function u64Any(value: bigint): Buffer {
 }
 
 function requirePositive(value: bigint | undefined, name: string): bigint {
-  if (value === undefined || value < 1n || value > 0xffff_ffff_ffff_ffffn) {
+  if (value === undefined || value < 1n || value > UINT64_MAX) {
     throw new RangeError(`${name} must be a non-zero u64.`);
   }
   return value;
@@ -2909,7 +2960,7 @@ class FrozenReader {
   }
 
   applicationPayload(): NonNullable<ServiceMaintenanceReplyRelay['payload']> {
-    if (this.u8('applicationPayload.version') !== 1) {
+    if (this.u8('applicationPayload.version') !== APPLICATION_PAYLOAD_VERSION) {
       fail('Application payload envelope version must be one.');
     }
     const body = this.body32('application payload');
@@ -3066,24 +3117,21 @@ class FrozenReader {
   }
 
   private instanceRoute(): void {
+    const start = this.offset;
     const kind = this.u8('instanceRouteKind');
     if (kind < 1 || kind > 2) fail('Invalid Instance route kind.');
     const body = this.body16('Instance route');
+    if (kind === INSTANCE_ROUTE_VERSION) {
+      decodeInstanceRouteV1(this.bytes.subarray(start, this.offset), STATEFUL_MESSAGE_CONTEXT);
+      return;
+    }
     body.rid8('targetNodeRid');
     body.nonZeroU64('targetNodeGeneration');
     body.text8('targetSpotId');
-    if (kind === 1) {
-      body.nonZeroU64('objectGeneration');
-      body.text8('ownerId');
-      body.nonZeroU64('authorityOwnerGeneration');
-      body.nonZeroU64('leaseGeneration');
-      body.text16('storeVersion');
-    } else {
-      body.text8('targetMeshName');
-      body.text8('stableType');
-      body.text8('targetDescriptorVersion');
-      body.nonZeroU64('deadlineUnixMs');
-    }
+    body.text8('targetMeshName');
+    body.text8('stableType');
+    body.text8('targetDescriptorVersion');
+    body.nonZeroU64('deadlineUnixMs');
     body.end('Instance route');
   }
 

package/src/runtime/foundation/service-topology-registry.ts

@@ -1,3 +1,10 @@
+import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
+import {
+  ZLINK_MAX_PUBLIC_WEIGHT,
+  isValidCapacity,
+  isValidPositiveCapacity,
+  isValidPublicWeight
+} from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import { descriptorConnectionNotRequired } from './route-mesh-connection-policy';
 import { SmoothWeightedSelection } from './service-weighted-selection';
 import { SERVICE_WIRE_REQUIRED_CAPABILITY } from './service-wire-constants.generated';
@@ -51,8 +58,6 @@ export type PeerAdmissionResult =
 export type ServiceObjectPlacementStatus = 'available' | 'unsupported' | 'capacity' | 'unavailable';
 
 const REQUIRED_CAPABILITY = SERVICE_WIRE_REQUIRED_CAPABILITY;
-const MAX_CAPACITY = 0x7fff_ffff;
-const MAX_PUBLIC_WEIGHT = 10_000;
 
 interface ServiceSelectionCacheEntry {
   readonly selection: SmoothWeightedSelection<unknown>;
@@ -207,21 +212,6 @@ export class ServiceTopologyRegistry {
     this.rebuildSelections();
   }
 
-  markNotRequired(descriptor: ServiceNodeDescriptor): void {
-    validateDescriptor(descriptor);
-    if (
-      descriptor.meshName !== this.local.meshName ||
-      descriptor.nodeRoutingId === this.local.nodeRoutingId ||
-      !descriptorConnectionNotRequired(this.local, descriptor)
-    ) {
-      return;
-    }
-    this.peersByRid.delete(descriptor.nodeRoutingId);
-    this.remember(descriptor);
-    this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
-    this.rebuildSelections();
-  }
-
   forgetNotRequired(nodeRoutingId: string): void {
     if (this.notRequiredByRid.delete(nodeRoutingId)) this.rebuildSelections();
   }
@@ -235,8 +225,12 @@ export class ServiceTopologyRegistry {
 
   hasKnownChannelTarget(channelName: string): boolean {
     requireText(channelName, 'channelName');
-    return [this.local, ...this.knownByRid.values()].some(
-      (descriptor) => selectableChannel(descriptor, channelName) !== undefined
+    return [...this.knownByRid.values()].some(
+      (descriptor) =>
+        (descriptor.state === 'serving' ||
+          descriptor.state === 'retiring' ||
+          descriptor.state === 'draining') &&
+        findChannel(descriptor, channelName) !== undefined
     );
   }
 
@@ -259,12 +253,8 @@ export class ServiceTopologyRegistry {
     requireText(channelName, 'channelName');
     return this.selectWeightedCycle(
       `channel:${channelName}`,
-      () => {
-        const local: AdmittedServicePeer = {
-          descriptor: cloneDescriptor(this.local),
-          connectionId: 'local'
-        };
-        return [local, ...this.peersByRid.values()]
+      () =>
+        [...this.peersByRid.values()]
           .map((peer) => ({
             peer: clonePeer(peer),
             channel: selectableChannel(peer.descriptor, channelName)
@@ -276,8 +266,7 @@ export class ServiceTopologyRegistry {
               peer: AdmittedServicePeer;
               channel: ServiceChannelDescriptor;
             } => value.channel !== undefined
-          );
-      },
+          ),
       (value) => value.channel.weight,
       (value) => value.peer.descriptor.nodeRoutingId,
       (left, right) =>
@@ -427,8 +416,10 @@ export function validateDescriptor(descriptor: ServiceNodeDescriptor): void {
   }
   if (descriptor.maintenanceWave !== undefined) {
     requireText(descriptor.maintenanceWave, 'maintenanceWave');
-    if (Buffer.byteLength(descriptor.maintenanceWave, 'utf8') > 255) {
-      throw new RangeError('maintenanceWave must not exceed 255 UTF-8 bytes.');
+    if (Buffer.byteLength(descriptor.maintenanceWave, 'utf8') > ZLINK_MAX_IDENTITY_TEXT_BYTES) {
+      throw new RangeError(
+        `maintenanceWave must not exceed ${ZLINK_MAX_IDENTITY_TEXT_BYTES} UTF-8 bytes.`
+      );
     }
   }
   validatePublicWeight(descriptor.placementWeight, 'placementWeight');
@@ -465,14 +456,14 @@ export function validateDescriptor(descriptor: ServiceNodeDescriptor): void {
 }
 
 function validateCapacity(value: number, allowZero: boolean, field: string): void {
-  if (!Number.isInteger(value) || value < (allowZero ? 0 : 1) || value > MAX_CAPACITY) {
+  if (!(allowZero ? isValidCapacity(value) : isValidPositiveCapacity(value))) {
     throw new RangeError(`${field} is outside its supported range.`);
   }
 }
 
 function validatePublicWeight(value: number, field: string): void {
-  if (!Number.isInteger(value) || value < 0 || value > MAX_PUBLIC_WEIGHT) {
-    throw new RangeError(`${field} must be an integer in 0..10000.`);
+  if (!isValidPublicWeight(value)) {
+    throw new RangeError(`${field} must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`);
   }
 }
 

package/src/runtime/foundation/service-wire-binary-primitives.ts

@@ -1,5 +1,11 @@
 import type { RoutingId } from '../../contracts';
 import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
+export const SERVICE_WIRE_MAJOR_OFFSET = 2;
+export const SERVICE_WIRE_COMMAND_OFFSET = SERVICE_WIRE_MAJOR_OFFSET + 1;
+export const SERVICE_WIRE_FLAGS_OFFSET = SERVICE_WIRE_COMMAND_OFFSET + 1;
+export const SERVICE_WIRE_PREFIX_SIZE = SERVICE_WIRE_FLAGS_OFFSET + 1;
+
+export const SERVICE_WIRE_TEXT8_MAX_BYTES = 255;
 
 export type ServiceWireInvalid = (message: string) => never;
 

package/src/runtime/foundation/service-wire-codec.ts

@@ -1,4 +1,11 @@
-const PREFIX_SIZE = 5;
+import { UINT64_MAX } from '@zlink-systems/stream-wire';
+import {
+  SERVICE_WIRE_COMMAND_OFFSET,
+  SERVICE_WIRE_FLAGS_OFFSET,
+  SERVICE_WIRE_MAJOR_OFFSET,
+  SERVICE_WIRE_PREFIX_SIZE
+} from './service-wire-binary-primitives';
+const PREFIX_SIZE = SERVICE_WIRE_PREFIX_SIZE;
 const LIVENESS_FRAME_SIZE = PREFIX_SIZE + 8;
 
 export interface ServiceWireDefinition {
@@ -46,16 +53,16 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       ) {
         throw new RangeError('command must be a liveness command.');
       }
-      if (record.probeId <= 0n || record.probeId > 0xffff_ffff_ffff_ffffn) {
+      if (record.probeId <= 0n || record.probeId > UINT64_MAX) {
         throw new RangeError('probeId must be a non-zero unsigned 64-bit integer.');
       }
 
       const frame = Buffer.allocUnsafe(LIVENESS_FRAME_SIZE);
       frame[0] = definition.magic[0];
       frame[1] = definition.magic[1];
-      frame[2] = definition.major;
-      frame[3] = record.command;
-      frame[4] = 0;
+      frame[SERVICE_WIRE_MAJOR_OFFSET] = definition.major;
+      frame[SERVICE_WIRE_COMMAND_OFFSET] = record.command;
+      frame[SERVICE_WIRE_FLAGS_OFFSET] = 0;
       frame.writeBigUInt64BE(record.probeId, PREFIX_SIZE);
       return frame;
     },
@@ -64,9 +71,9 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       if (frame[0] !== definition.magic[0] || frame[1] !== definition.magic[1]) {
         fail('invalid-magic');
       }
-      if (frame[2] !== definition.major) fail('unsupported-major');
+      if (frame[SERVICE_WIRE_MAJOR_OFFSET] !== definition.major) fail('unsupported-major');
 
-      const command = frame[3];
+      const command = frame[SERVICE_WIRE_COMMAND_OFFSET];
       if (!knownCommands.has(command)) fail('unknown-command');
       if (
         command !== definition.commands.livenessProbe &&
@@ -74,7 +81,7 @@ export function createServiceWireCodec(definition: ServiceWireDefinition): Servi
       ) {
         fail('unknown-command');
       }
-      if (frame[4] !== 0) fail('forbidden-flag');
+      if (frame[SERVICE_WIRE_FLAGS_OFFSET] !== 0) fail('forbidden-flag');
       if (frame.byteLength < LIVENESS_FRAME_SIZE) fail('truncated-field');
       if (frame.byteLength > LIVENESS_FRAME_SIZE) fail('trailing-byte');
 

package/src/runtime/foundation/service-wire-constants.generated.ts

@@ -1,6 +1,7 @@
 // Generated from service-wire-v1.schema.json. Do not edit.
 export const SERVICE_WIRE_MAGIC = [90, 77] as const;
 export const SERVICE_WIRE_MAJOR = 1 as const;
+export const SERVICE_WIRE_METADATA_BYTES = 1024 as const;
 export const SERVICE_WIRE_REQUIRED_CAPABILITY = "framework-service-v13" as const;
 export const SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME = "ZLinkFrameworkMultipart" as const;
 export const SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE = "application/x-zlink-multipart" as const;