@zlink-systems/framework 0.29.1 → 0.30.0

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

@@ -1,7 +1,7 @@
 import { UINT64_MAX } from '@zlink-systems/stream-wire';
 export interface ServiceProbe {
   readonly nodeRoutingId: string;
-  readonly connectionId: string;
+  readonly connectionId: string | bigint;
   readonly probeId: bigint;
 }
 
@@ -10,20 +10,52 @@ export interface ServiceLivenessTick {
   readonly timedOutNodes: readonly string[];
 }
 
-interface PeerState {
-  readonly connectionId: string;
+export const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
+export const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+
+export class ServiceLivenessConnection {
   deadlineMs: number;
   nextProbeMs: number;
   outstandingProbe?: bigint;
-  ready: boolean;
-}
 
-export const DEFAULT_SERVICE_PROBE_INTERVAL_MS = 5_000;
-export const DEFAULT_SERVICE_PEER_TIMEOUT_MS = 15_000;
+  constructor(
+    readonly connectionId: string | bigint,
+    nowMs: number,
+    private readonly probeIntervalMs = DEFAULT_SERVICE_PROBE_INTERVAL_MS,
+    private readonly peerTimeoutMs = DEFAULT_SERVICE_PEER_TIMEOUT_MS
+  ) {
+    this.deadlineMs = nowMs + peerTimeoutMs;
+    this.nextProbeMs = nowMs;
+  }
+
+  readonly recordReceived = (nowMs = performance.now()): void => {
+    this.deadlineMs = Math.max(this.deadlineMs, nowMs + this.peerTimeoutMs);
+  };
+
+  isExpired(nowMs: number): boolean {
+    return nowMs >= this.deadlineMs;
+  }
+
+  tryGetProbe(nowMs: number, allocateProbeId: () => bigint): bigint | undefined {
+    if (nowMs < this.nextProbeMs) return undefined;
+    this.outstandingProbe ??= allocateProbeId();
+    do {
+      this.nextProbeMs += this.probeIntervalMs;
+    } while (this.nextProbeMs <= nowMs);
+    return this.outstandingProbe;
+  }
+
+  acknowledge(probeId: bigint, nowMs: number): boolean {
+    this.recordReceived(nowMs);
+    if (this.outstandingProbe !== probeId) return false;
+    this.outstandingProbe = undefined;
+    return true;
+  }
+}
 
 /** Uses monotonic milliseconds and never treats application traffic as a probe ACK. */
 export class ServiceLivenessRegistry {
-  private readonly peers = new Map<string, PeerState>();
+  private readonly peers = new Map<string, ServiceLivenessConnection>();
   private nextProbeId = 1n;
 
   constructor(
@@ -40,33 +72,31 @@ export class ServiceLivenessRegistry {
     }
   }
 
-  admit(nodeRoutingId: string, connectionId: string, nowMs: number): void {
+  admit(
+    nodeRoutingId: string,
+    connectionId: string | bigint,
+    nowMs: number
+  ): ServiceLivenessConnection {
     requireIdentity(nodeRoutingId, 'nodeRoutingId');
-    requireIdentity(connectionId, 'connectionId');
+    if (typeof connectionId === 'string') requireIdentity(connectionId, 'connectionId');
+    else if (connectionId === 0n) throw new TypeError('connectionId must be nonzero.');
     const current = this.peers.get(nodeRoutingId);
-    if (current?.connectionId === connectionId) return;
-    this.peers.set(nodeRoutingId, {
+    if (current?.connectionId === connectionId) return current;
+    const admitted = new ServiceLivenessConnection(
       connectionId,
-      deadlineMs: nowMs + this.peerTimeoutMs,
-      nextProbeMs: nowMs + this.probeIntervalMs,
-      ready: false
-    });
+      nowMs,
+      this.probeIntervalMs,
+      this.peerTimeoutMs
+    );
+    this.peers.set(nodeRoutingId, admitted);
+    return admitted;
   }
 
-  requestProbe(nodeRoutingId: string, connectionId: string, nowMs: number): boolean {
-    const current = this.peers.get(nodeRoutingId);
-    if (
-      current === undefined ||
-      current.connectionId !== connectionId ||
-      current.ready ||
-      current.outstandingProbe !== undefined
-    )
-      return false;
-    current.nextProbeMs = Math.min(current.nextProbeMs, nowMs);
-    return true;
+  recordReceived(connection: ServiceLivenessConnection, nowMs: number): void {
+    connection.recordReceived(nowMs);
   }
 
-  disconnect(nodeRoutingId: string, connectionId: string): boolean {
+  disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean {
     const current = this.peers.get(nodeRoutingId);
     if (current === undefined || current.connectionId !== connectionId) return false;
     this.peers.delete(nodeRoutingId);
@@ -75,27 +105,18 @@ export class ServiceLivenessRegistry {
 
   acknowledge(
     nodeRoutingId: string,
-    connectionId: string,
+    connectionId: string | bigint,
     probeId: bigint,
     nowMs: number
   ): boolean {
     const current = this.peers.get(nodeRoutingId);
-    if (
-      current === undefined ||
-      current.connectionId !== connectionId ||
-      current.outstandingProbe !== probeId
-    ) {
-      return false;
-    }
-    current.outstandingProbe = undefined;
-    current.deadlineMs = nowMs + this.peerTimeoutMs;
-    current.ready = true;
-    return true;
+    if (current === undefined || current.connectionId !== connectionId) return false;
+    return current.acknowledge(probeId, nowMs);
   }
 
   acknowledgeProbe(
     nodeRoutingId: string,
-    connectionId: string,
+    connectionId: string | bigint,
     probeId: bigint
   ): ServiceProbe | undefined {
     const current = this.peers.get(nodeRoutingId);
@@ -109,21 +130,14 @@ export class ServiceLivenessRegistry {
     const probes: ServiceProbe[] = [];
     const timedOutNodes: string[] = [];
     for (const [nodeRoutingId, peer] of this.peers) {
-      if (peer.deadlineMs <= nowMs) {
+      if (peer.isExpired(nowMs)) {
         timedOutNodes.push(nodeRoutingId);
         this.peers.delete(nodeRoutingId);
         continue;
       }
-      if (peer.nextProbeMs > nowMs) continue;
-      peer.outstandingProbe ??= this.allocateProbeId();
-      probes.push({
-        nodeRoutingId,
-        connectionId: peer.connectionId,
-        probeId: peer.outstandingProbe
-      });
-      do {
-        peer.nextProbeMs += this.probeIntervalMs;
-      } while (peer.nextProbeMs <= nowMs);
+      const probeId = peer.tryGetProbe(nowMs, this.allocateProbeId);
+      if (probeId !== undefined)
+        probes.push({ nodeRoutingId, connectionId: peer.connectionId, probeId });
     }
     timedOutNodes.sort();
     return { probes, timedOutNodes };
@@ -133,16 +147,11 @@ export class ServiceLivenessRegistry {
     return this.peers.size;
   }
 
-  isReady(nodeRoutingId: string, connectionId: string): boolean {
-    const current = this.peers.get(nodeRoutingId);
-    return current?.connectionId === connectionId && current.ready;
-  }
-
-  private allocateProbeId(): bigint {
+  private readonly allocateProbeId = (): bigint => {
     const result = this.nextProbeId++;
     if (this.nextProbeId > UINT64_MAX) this.nextProbeId = 1n;
     return result;
-  }
+  };
 }
 
 function requireIdentity(value: string, field: string): void {

package/src/runtime/foundation/service-mailbox.ts

@@ -1,4 +1,5 @@
 import type { ApplicationJobRecordLease } from '../application-jobs/application-ingress-record-owner';
+import type { ReceiveRecord } from './service-runtime-contracts';
 
 export type ServiceMailboxDomain = 'application' | 'infrastructure';
 
@@ -23,6 +24,8 @@ export interface ServiceMailboxRecord {
   readonly stateful?: unknown;
   /** Host queue permit plus its ordinary Framework-owned ingress record. */
   readonly applicationJob?: ApplicationJobRecordLease;
+  /** Unregistered raw-pull terminal, retained by the existing mailbox owner. */
+  readonly completion?: ReceiveRecord;
 }
 
 export interface ServiceMailboxClaim {
@@ -85,7 +88,10 @@ export class ServiceMailbox {
   }
 
   tryEnqueue(record: ServiceMailboxRecord): boolean {
-    if (record.owner.length === 0 || record.parts.length === 0) {
+    if (
+      record.owner.length === 0 ||
+      (record.parts.length === 0 && record.completion === undefined)
+    ) {
       throw new TypeError('Mailbox records require an owner and retained payload.');
     }
     const target = this.domain(record.domain);

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

@@ -90,6 +90,7 @@ import {
   type ServiceBoundSessionActorAuthority,
   type ServiceDirectSpotRouteFence,
   type ServiceInstanceActivationTarget,
+  type ServiceInstanceColdActivationTarget,
   type ServiceInstanceRouteFence,
   type ServiceMessageFollowRoute,
   type ServiceRetiredBoundSessionRouteFence,
@@ -313,7 +314,12 @@ export interface ServiceInstanceActivationAuthority {
  * operation completes; the binding callback itself never blocks.
  */
 export interface ServiceAsyncInstanceActivationAuthority {
-  read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
+  read(
+    target: ServiceInstanceActivationTarget,
+    instanceIntent?: true,
+    activation?: ServiceInstanceActivationRecoveryEnvelope,
+    acceptsLocal?: (route: ServiceInstanceRouteFence) => boolean
+  ): Promise<ServiceInstanceAuthorityRead>;
   reserve(
     activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>,
     signal?: AbortSignal
@@ -883,7 +889,7 @@ export class ServiceStatefulRuntime {
     const record = {
       kind: 'instanceSpot' as const,
       activation: 'missing' as const,
-      target,
+      target: { ...target, targetMeshName: envelope.targetMeshName },
       sourceNodeGeneration: envelope.sourceNodeGeneration,
       sourceNodeRid: envelope.sourceNodeRid,
       ...(envelope.sourceSpotId === undefined ? {} : { sourceSpotId: envelope.sourceSpotId }),
@@ -902,7 +908,7 @@ export class ServiceStatefulRuntime {
           sourceRoutingId: envelope.sourceNodeRid,
           parts: [
             encodeInstanceSpotActivationHeader(
-              target,
+              record.target,
               envelope.sourceNodeGeneration,
               envelope.sourceNodeRid,
               envelope.sourceSpotId,
@@ -1442,7 +1448,7 @@ export class ServiceStatefulRuntime {
   }
 
   async sendToMissingInstanceSpot(
-    target: ServiceInstanceActivationTarget,
+    target: ServiceInstanceColdActivationTarget,
     payload: ServiceApplicationPayload,
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
@@ -1458,7 +1464,7 @@ export class ServiceStatefulRuntime {
   }
 
   async sendToMissingInstanceSpotFrame(
-    target: ServiceInstanceActivationTarget,
+    target: ServiceInstanceColdActivationTarget,
     payloadFrame: Buffer,
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
@@ -1523,7 +1529,7 @@ export class ServiceStatefulRuntime {
   }
 
   requestToMissingInstanceSpot(
-    target: ServiceInstanceActivationTarget,
+    target: ServiceInstanceColdActivationTarget,
     payload: ServiceApplicationPayload,
     timeoutMs: number,
     sourceSpotId?: string,
@@ -1541,7 +1547,7 @@ export class ServiceStatefulRuntime {
   }
 
   requestToMissingInstanceSpotFrame(
-    target: ServiceInstanceActivationTarget,
+    target: ServiceInstanceColdActivationTarget,
     payloadFrame: Buffer,
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
@@ -2941,6 +2947,24 @@ export class ServiceStatefulRuntime {
     return activation.spot;
   }
 
+  private localReadyInstance(
+    target: ServiceInstanceActivationTarget,
+    route: ServiceInstanceRouteFence
+  ): ServiceSpotState | undefined {
+    const local = this.registry.spot(target.targetSpotId);
+    if (
+      local !== undefined &&
+      (local.kind !== 'instance' || local.stableType !== target.stableType)
+    ) {
+      throw new ServiceStaleGenerationError('spot', target.targetSpotId);
+    }
+    return local !== undefined &&
+      local.state === 'ready' &&
+      routeMatchesLocal(route, local, this.nodeRid, this.nodeGeneration)
+      ? local
+      : undefined;
+  }
+
   private activateMissingInstanceAsync(
     record: Extract<
       ServiceStatefulWireRecord,
@@ -2961,7 +2985,20 @@ export class ServiceStatefulRuntime {
         ...activation,
         stableType: record.target.stableType
       }));
-    const operation = ready.then((value) => {
+    const operation = ready.then(async (value) => {
+      if (pending !== undefined) {
+        await this.asyncInstanceAuthority?.read(
+          record.target,
+          undefined,
+          {
+            ...record,
+            targetMeshName: record.target.targetMeshName,
+            ...(metadataFrame === undefined ? {} : { metadataFrame }),
+            applicationPayloadFrame: payloadFrame
+          },
+          (route) => this.localReadyInstance(record.target, route) !== undefined
+        );
+      }
       if (value.stableType !== record.target.stableType) {
         throw new ZLinkFrameworkException(
           ZLinkFrameworkErrorKind.TypeMismatch,
@@ -3010,8 +3047,19 @@ export class ServiceStatefulRuntime {
       throw new Error('Async Instance activation authority is not registered.');
     }
 
+    const activationRequest = {
+      ...record,
+      targetMeshName: record.target.targetMeshName,
+      ...(metadataFrame === undefined ? {} : { metadataFrame }),
+      applicationPayloadFrame: payloadFrame
+    };
+    const current = await authority.read(
+      target,
+      true,
+      activationRequest,
+      (route) => this.localReadyInstance(target, route) !== undefined
+    );
     const local = this.registry.spot(target.targetSpotId);
-    const current = await authority.read(target);
     if (
       current.kind === 'creating' &&
       current.authority?.allocation.state === 'active' &&
@@ -3061,17 +3109,9 @@ export class ServiceStatefulRuntime {
       if (current.route.targetNodeGeneration !== this.nodeGeneration) {
         throw new ServiceStaleGenerationError('spot', target.targetSpotId);
       }
-      if (
-        local !== undefined &&
-        (local.kind !== 'instance' || local.stableType !== target.stableType)
-      ) {
-        throw new ServiceStaleGenerationError('spot', target.targetSpotId);
-      }
-      if (
-        local !== undefined &&
-        routeMatchesLocal(current.route, local, this.nodeRid, this.nodeGeneration)
-      ) {
-        return { spot: local, route: current.route };
+      const readyLocal = this.localReadyInstance(target, current.route);
+      if (readyLocal !== undefined) {
+        return { spot: readyLocal, route: current.route };
       }
       return await this.reconcileReadyInstanceProjection(target, current.route, authority);
     }
@@ -3113,21 +3153,7 @@ export class ServiceStatefulRuntime {
     const deadline = operationDeadline(record.deadlineUnixMs);
     let reserved: ServiceInstanceAuthorityReserve;
     try {
-      reserved = await authority.reserve(
-        {
-          target,
-          sourceNodeRid: record.sourceNodeRid,
-          sourceNodeGeneration: record.sourceNodeGeneration,
-          ...(record.sourceSpotId === undefined ? {} : { sourceSpotId: record.sourceSpotId }),
-          operationKind: record.operationKind,
-          operation: record.operation,
-          ...(record.replyRouteId === undefined ? {} : { replyRouteId: record.replyRouteId }),
-          deadlineUnixMs: record.deadlineUnixMs,
-          ...(metadataFrame === undefined ? {} : { metadataFrame }),
-          applicationPayloadFrame: payloadFrame
-        },
-        deadline.signal
-      );
+      reserved = await authority.reserve(activationRequest, deadline.signal);
     } finally {
       deadline.close();
     }

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

@@ -14,6 +14,7 @@ import {
   encodeInstanceRouteV1,
   encodeSpotRequestCommand,
   encodeSpotSendCommand,
+  type InstanceRouteV1,
   type ServiceWireDecoderContext
 } from '../protocol/service_wire_codec.generated';
 import {
@@ -82,8 +83,6 @@ import {
 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 = SERVICE_WIRE_PREFIX_SIZE;
 const MAGIC_0 = SERVICE_WIRE_MAGIC[0];
@@ -946,6 +945,10 @@ export interface ServiceInstanceActivationTarget {
   readonly descriptorVersion: string;
 }
 
+export interface ServiceInstanceColdActivationTarget extends ServiceInstanceActivationTarget {
+  readonly targetMeshName: string;
+}
+
 export interface ServiceUserSpotReservationFence {
   readonly reservationId: string;
   readonly expectedStoreVersion: string;
@@ -1105,7 +1108,7 @@ export type ServiceStatefulWireRecord =
   | {
       readonly kind: 'instanceSpot';
       readonly activation: 'missing';
-      readonly target: ServiceInstanceActivationTarget;
+      readonly target: ServiceInstanceColdActivationTarget;
       readonly sourceNodeGeneration: bigint;
       readonly sourceNodeRid: string;
       readonly sourceSpotId?: string;
@@ -1435,7 +1438,7 @@ export function encodeInstanceSpotHeader(
 }
 
 export function encodeInstanceSpotActivationHeader(
-  target: ServiceInstanceActivationTarget,
+  target: ServiceInstanceColdActivationTarget,
   sourceNodeGeneration: bigint,
   sourceNodeRid: string,
   sourceSpotId: string | undefined,
@@ -1454,25 +1457,28 @@ export function encodeInstanceSpotActivationHeader(
   if (operationKind === 'send' && replyRouteId !== undefined) {
     throw new RangeError('Instance Spot send must not carry a reply route.');
   }
-  const targetBody = concat(
-    rid(target.targetNodeRid, 'targetNodeRid'),
-    u64(target.targetNodeGeneration),
-    rid(target.targetSpotId, 'targetSpotId'),
-    text16(target.stableType, 'stableType'),
-    text16(target.descriptorVersion, 'descriptorVersion')
+  const encodedRoute = encodeInstanceRouteV1(
+    {
+      routeKind: 'coldActivation',
+      targetNodeRid: toGeneratedRoutingId(target.targetNodeRid, 'targetNodeRid'),
+      targetNodeGeneration: target.targetNodeGeneration,
+      targetSpotId: target.targetSpotId,
+      targetMeshName: target.targetMeshName,
+      stableType: target.stableType,
+      targetDescriptorVersion: target.descriptorVersion,
+      deadlineUnixMs
+    },
+    STATEFUL_MESSAGE_CONTEXT
   );
   return concat(
     prefix(M6bServiceWireCommand.instanceSpot, hasMetadata ? M6bServiceWireFlag.metadata : 0),
-    Buffer.of(INSTANCE_ACTIVATION_VERSION),
-    u16(targetBody.byteLength),
-    targetBody,
+    encodedRoute,
     u64Any(sourceNodeGeneration),
     rid(sourceNodeRid, 'sourceNodeRid'),
     optionalRid(sourceSpotId),
     Buffer.of(operationKind === 'send' ? 1 : 2),
     u64Any(operation.high),
     u64Any(operation.low),
-    u64(deadlineUnixMs),
     ...(operationKind === 'request' ? [u64(requirePositive(replyRouteId, 'replyRouteId'))] : [])
   );
 }
@@ -1741,53 +1747,31 @@ export function decodeStatefulHeader(
         fail(`Invalid command flags '${command.flags}'.`);
       }
       const routeStart = reader.offset;
-      const version = reader.u8('instanceRoute.version');
-      if (version !== INSTANCE_ROUTE_VERSION && version !== INSTANCE_ACTIVATION_VERSION)
-        fail('Unsupported Instance route version.');
+      reader.u8('instanceRoute.kind');
       const routeLength = reader.u16('instanceRoute.length');
       const routeEnd = reader.offset + routeLength;
-      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 =
-        generatedReadyRoute?.routeKind === 'ready'
-          ? {
-              ...commonTarget,
-              ...generatedReadyRoute.authority
-            }
+      const generatedRoute = decodeCanonicalInstanceRoute(
+        reader.bytes.subarray(routeStart, routeEnd)
+      );
+      const commonTarget = {
+        targetNodeRid: fromGeneratedRoutingId(generatedRoute.targetNodeRid, 'targetNodeRid'),
+        targetNodeGeneration: generatedRoute.targetNodeGeneration,
+        targetSpotId: generatedRoute.targetSpotId
+      };
+      const route =
+        generatedRoute.routeKind === 'ready'
+          ? { ...commonTarget, ...generatedRoute.authority }
           : undefined;
-      const target: ServiceInstanceActivationTarget | undefined =
-        version === INSTANCE_ACTIVATION_VERSION
+      const target =
+        generatedRoute.routeKind === 'coldActivation'
           ? {
               ...commonTarget,
-              stableType: reader.text16('stableType'),
-              descriptorVersion: reader.text16('descriptorVersion')
+              targetMeshName: generatedRoute.targetMeshName,
+              stableType: generatedRoute.stableType,
+              descriptorVersion: generatedRoute.targetDescriptorVersion
             }
           : undefined;
-      if (generatedReadyRoute !== undefined) reader.offset = routeEnd;
-      if (reader.offset !== routeEnd) fail('Invalid Instance route body length.');
+      reader.offset = routeEnd;
       const sourceNodeGeneration = reader.nonZeroU64('sourceNodeGeneration');
       const sourceNodeRid = reader.rid('sourceNodeRid');
       const sourceSpotId = reader.optionalRid('sourceSpotId');
@@ -1799,21 +1783,21 @@ export function decodeStatefulHeader(
       };
       const operationKind = operationValue === 1 ? ('send' as const) : ('request' as const);
       if (
-        version === INSTANCE_ROUTE_VERSION &&
+        generatedRoute.routeKind === 'ready' &&
         ((operationKind === 'send' && (operation.high !== 0n || operation.low !== 0n)) ||
           (operationKind === 'request' && operation.high === 0n && operation.low === 0n))
       ) {
         fail('Invalid Instance operation identity.');
       }
       if (
-        version === INSTANCE_ACTIVATION_VERSION &&
+        generatedRoute.routeKind === 'coldActivation' &&
         operation.high === 0n &&
         operation.low === 0n
       ) {
         fail('Instance activation requires a non-zero operation identity.');
       }
       const deadlineUnixMs =
-        version === INSTANCE_ACTIVATION_VERSION ? reader.nonZeroU64('deadlineUnixMs') : undefined;
+        generatedRoute.routeKind === 'coldActivation' ? generatedRoute.deadlineUnixMs : undefined;
       const replyRouteId =
         operationKind === 'request' ? reader.nonZeroU64('replyRouteId') : undefined;
       reader.end();
@@ -1826,12 +1810,12 @@ export function decodeStatefulHeader(
         operation,
         ...(replyRouteId === undefined ? {} : { replyRouteId })
       };
-      return version === INSTANCE_ROUTE_VERSION
+      return generatedRoute.routeKind === 'ready'
         ? {
             ...common,
             activation: 'ready',
             route: route!,
-            instanceIntent: generatedReadyRoute!.instanceIntent === 'true'
+            instanceIntent: generatedRoute.instanceIntent === 'true'
           }
         : {
             ...common,
@@ -2387,11 +2371,6 @@ function text8(value: string, name: string): Buffer {
   return sized8(value, name);
 }
 
-function text16(value: string, name: string): Buffer {
-  const bytes = encodeCanonicalServiceWireText(value, name, 0xffff, outOfRange);
-  return concat(u16(bytes.byteLength), bytes);
-}
-
 function optionalRid(value: string | undefined): Buffer {
   return value === undefined ? Buffer.of(0) : rid(value, 'sourceSpotId');
 }
@@ -2448,6 +2427,15 @@ function concat(...parts: readonly Uint8Array[]): Buffer {
   return Buffer.concat(parts.map((part) => Buffer.from(part)));
 }
 
+function decodeCanonicalInstanceRoute(bytes: Uint8Array): InstanceRouteV1 {
+  try {
+    return decodeInstanceRouteV1(bytes, STATEFUL_MESSAGE_CONTEXT);
+  } catch (error) {
+    if (error instanceof RangeError) throw new ServiceWireProtocolError(error.message);
+    throw error;
+  }
+}
+
 function fail(message: string): never {
   throw new ServiceWireProtocolError(message);
 }
@@ -3093,21 +3081,9 @@ 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');
-    body.text8('targetMeshName');
-    body.text8('stableType');
-    body.text8('targetDescriptorVersion');
-    body.nonZeroU64('deadlineUnixMs');
-    body.end('Instance route');
+    this.u8('instanceRouteKind');
+    this.body16('Instance route');
+    decodeCanonicalInstanceRoute(this.bytes.subarray(start, this.offset));
   }
 
   private relocationObject(): void {