@zlink-systems/framework 0.30.0 → 0.30.1

package/src/runtime/foundation/service-relocation-object-owner.ts

@@ -17,6 +17,7 @@ const DEFAULT_RELOCATION_CALLBACK_CONCURRENCY = 8;
 
 export interface ServiceRelocationSealedWork {
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: ServiceRelocationParticipant['sessionBinding'];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -185,6 +186,7 @@ export class ServiceRelocationObjectCaptureOwner {
           authorityOwnerGeneration: unit.authorityOwnerGeneration,
           applicationState: Buffer.from(await unit.captureApplicationState(signal)),
           boundSessionState: Buffer.from(work.boundSessionState),
+          ...(work.sessionBinding === undefined ? {} : { sessionBinding: work.sessionBinding }),
           queuedMessages: work.queuedMessages.map((message) => ({
             sequence: message.sequence,
             payload: Buffer.from(message.payload)

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

@@ -39,6 +39,7 @@ export interface ServiceRelocationParticipant {
   readonly applicationStatePresent?: boolean;
   readonly applicationState: Uint8Array;
   readonly boundSessionState: Uint8Array;
+  readonly sessionBinding?: GeneratedRelocationEnvelopeV1['sessionBindings'][number];
   readonly queuedMessages: readonly ServiceRelocationQueuedMessage[];
   readonly timers: readonly ServiceRelocationTimer[];
 }
@@ -726,6 +727,11 @@ export function encodeServiceRelocationEnvelope(
           'timer due time'
         )
       })),
+      sessionBindings: participants.flatMap((participant, index) =>
+        participant.sessionBinding === undefined
+          ? []
+          : [{ ...participant.sessionBinding, participantId: BigInt(index + 1) }]
+      ),
       pendingTimerTicks: pending.map((value) => ({
         participantId: value.participantId,
         order: value.order,
@@ -765,11 +771,22 @@ export function decodeServiceRelocationEnvelope(
   const aggregateId = uuid(generated.relocationHigh, generated.relocationLow);
   if (aggregateId === undefined) throw new TypeError('Invalid relocation identity.');
   positiveBigInt(aggregateGeneration, 'aggregate generation');
+  const bindings = new Map(
+    generated.sessionBindings.map((binding) => [binding.participantId, binding])
+  );
+  for (const id of bindings.keys()) {
+    if (id > BigInt(generated.applicationStates.length))
+      throw new TypeError('Session binding participant is outside its inventory.');
+  }
   const participants = generated.applicationStates.map((state, index) => {
     if (state.participantId !== BigInt(index + 1)) {
       throw new TypeError('Application state participant order is invalid.');
     }
-    return wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload));
+    const binding = bindings.get(state.participantId);
+    return {
+      ...wireParticipant(state.participantId, state.hasState, Buffer.from(state.payload)),
+      ...(binding === undefined ? {} : { sessionBinding: binding })
+    };
   });
   const byId = new Map(participants.map((value) => [value.participantId!, value]));
   for (const work of generated.savedWork) {

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

@@ -422,7 +422,12 @@ export interface ServiceSpot {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendToSpot(
     targetNodeRid: unknown,
@@ -445,6 +450,7 @@ export interface ServiceSpot {
       timeoutMs?: number;
       applicationMetadata?: Buffer;
       routeFence?: ServiceDirectSpotRouteFence;
+      onAdmitted?: () => void;
       entrySpot?: boolean;
     }
   ): MeshOperationId;

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

@@ -10,7 +10,7 @@ import {
   ZLinkDispatchMessageKind,
   ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import { awaitWithAbort } from '../abort';
+import { requestDurableService } from './durable-service-request';
 import { shouldCompactBackingArray } from '../admission';
 import { RequestResult, SubmitResult, isZLinkBackendResultError } from '../backend/runtime-values';
 import type { ZLinkDispatchErrorReporter } from '../channels/dispatch-error-reporter';
@@ -112,7 +112,6 @@ import {
   encodeApplicationPayload,
   type ServiceApplicationPayload
 } from './service-wire-m6a-codec';
-const STATEFUL_OPERATION_RETRY_TICK_MS = 20;
 
 const MAX_NODE_TIMER_DELAY_MS = 2_147_483_647;
 
@@ -454,7 +453,7 @@ export class ServiceStatefulRuntime {
     );
     this.registry = new ServiceStatefulRegistry(nodeRid, nodeGeneration);
     this.registry.createEntrySpot(nodeRid);
-    raw.setServiceIngress((record) => this.ingress(record));
+    raw.setServiceIngress((record) => this.ingress(record), acceptsStatefulIngress);
   }
 
   setMailboxDropHandler(
@@ -1326,7 +1325,8 @@ export class ServiceStatefulRuntime {
     sourceSpotId: string,
     requested: ServiceDirectSpotRouteFence,
     payload: ServiceApplicationPayload,
-    timeoutMs: number
+    timeoutMs: number,
+    onAdmitted?: () => void
   ): ServiceStatefulPendingOperation {
     const pending = this.operations.register(timeoutMs);
     const target = this.acceptSpotAuthority(requested);
@@ -1346,7 +1346,9 @@ export class ServiceStatefulRuntime {
       target.targetNodeRid,
       [header, encodeApplicationPayload(payload)],
       timeoutMs,
-      'spotRequest'
+      'spotRequest',
+      undefined,
+      onAdmitted
     );
     return pending;
   }
@@ -1384,7 +1386,8 @@ export class ServiceStatefulRuntime {
     payload: ServiceApplicationPayload,
     timeoutMs: number,
     sourceActor?: ServiceActorRef,
-    boundSession?: { readonly sessionRid: string; readonly bindingGeneration: bigint }
+    boundSession?: { readonly sessionRid: string; readonly bindingGeneration: bigint },
+    onAdmitted?: () => void
   ): ServiceStatefulPendingOperation {
     const pending = this.operations.register(timeoutMs);
     const route = this.tryActorFence(target);
@@ -1413,7 +1416,9 @@ export class ServiceStatefulRuntime {
       target.nodeRid,
       [header, encodeApplicationPayload(payload)],
       timeoutMs,
-      'actorRequest'
+      'actorRequest',
+      undefined,
+      onAdmitted
     );
     return pending;
   }
@@ -1499,7 +1504,8 @@ export class ServiceStatefulRuntime {
     timeoutMs: number,
     sourceSpotId?: string,
     metadataFrame?: Uint8Array,
-    instanceIntent = false
+    instanceIntent = false,
+    onAdmitted?: () => void
   ): ServiceStatefulPendingOperation {
     const pending = this.operations.register(timeoutMs);
     this.submitRequest(
@@ -1523,7 +1529,9 @@ export class ServiceStatefulRuntime {
         metadataFrame
       ),
       timeoutMs,
-      'instanceSpotRequest'
+      'instanceSpotRequest',
+      undefined,
+      onAdmitted
     );
     return pending;
   }
@@ -1551,7 +1559,8 @@ export class ServiceStatefulRuntime {
     payloadFrame: Buffer,
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
-    metadataFrame?: Uint8Array
+    metadataFrame?: Uint8Array,
+    onAdmitted?: () => void
   ): ServiceStatefulPendingOperation {
     const timeoutMs = remainingDeadlineMs(deadlineUnixMs);
     const pending = this.operations.register(timeoutMs);
@@ -1576,7 +1585,9 @@ export class ServiceStatefulRuntime {
         metadataFrame
       ),
       timeoutMs,
-      'instanceSpotRequest'
+      'instanceSpotRequest',
+      undefined,
+      onAdmitted
     );
     return pending;
   }
@@ -2029,29 +2040,6 @@ export class ServiceStatefulRuntime {
   private async ingress(
     record: RawServiceIngressRecord
   ): Promise<RawServicePumpResult | undefined> {
-    // These frozen relocation controls overlap the legacy stateful command
-    // number range (30-34). They are bare infrastructure records and must
-    // fall through to RawServiceMeshRuntime's relocation ingress instead of
-    // being decoded as stateful actor/spot work.
-    if (
-      record.command === M6bServiceWireCommand.relocationReady ||
-      record.command === M6bServiceWireCommand.relocationData ||
-      record.command === M6bServiceWireCommand.replyRelay ||
-      record.command === M6bServiceWireCommand.relocationCutover
-    ) {
-      return undefined;
-    }
-    if (
-      record.command < M6bServiceWireCommand.spotSend ||
-      (record.command > M6bServiceWireCommand.instanceSpot &&
-        record.command !== M6bServiceWireCommand.userSpotCreate &&
-        record.command !== M6bServiceWireCommand.userSpotClose &&
-        record.command !== M6bServiceWireCommand.actorCreate &&
-        record.command !== M6bServiceWireCommand.messageFollow &&
-        record.command !== M6bServiceWireCommand.boundSessionReplaced)
-    ) {
-      return undefined;
-    }
     let decoded: ServiceStatefulWireRecord;
     let canonicalActorJoin: ActorJoin28 | undefined;
     try {
@@ -2371,6 +2359,7 @@ export class ServiceStatefulRuntime {
         localReply,
         metadataFrame
       ).finally(() => ownedIngress.applicationJobOwner?.close());
+      ingress.onAdmitted?.();
       return 'infrastructure';
     }
     if (
@@ -2384,6 +2373,7 @@ export class ServiceStatefulRuntime {
         payloadFrame,
         metadataFrame
       ).finally(() => ownedIngress.applicationJobOwner?.close());
+      ingress.onAdmitted?.();
       return 'infrastructure';
     }
     const spot = this.requireInstanceActivation(ingress, record);
@@ -3821,7 +3811,10 @@ export class ServiceStatefulRuntime {
       stateful,
       applicationJob
     });
-    if (accepted) return domain;
+    if (accepted) {
+      ingress.onAdmitted?.();
+      return domain;
+    }
     applicationJob.close();
     if (stateful.reply !== undefined) {
       const result = failure(
@@ -4212,64 +4205,15 @@ export class ServiceStatefulRuntime {
     operationKind: 'userSpotCreate' | 'userSpotClose' | 'actorCreate' | 'streamBind' | 'actorJoin',
     deadlineMs: number
   ): Promise<readonly Buffer[]> {
-    const stop = new AbortController();
-    const unobserve = this.raw.observePeerConnectionIntentRemoved((nodeRoutingId) => {
-      if (nodeRoutingId === targetNodeRid) {
-        stop.abort(
-          createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-            `${operationKind} target node lifecycle ended.`,
-            true
-          )
-        );
-      }
-    });
-    let wasAdmitted = false;
-    try {
-      // Only durable lifecycle operations replay these frozen frames. Received
-      // envelopes leave this loop before decoding, including failure terminals.
-      for (;;) {
-        this.requireOpen();
-        stop.signal.throwIfAborted();
-        const remainingMs = Math.ceil(deadlineMs - performance.now());
-        if (remainingMs <= 0) throw durableOperationExhausted(operationKind, wasAdmitted);
-        try {
-          return await awaitWithAbort(
-            targetNodeRid === this.nodeRid
-              ? this.requestLocalInfrastructure(parts[0]!, correlation, remainingMs)
-              : this.raw.requestService(targetNodeRid, parts, remainingMs),
-            stop.signal
-          );
-        } catch (error) {
-          stop.signal.throwIfAborted();
-          if (!durableRequestCanReplay(error)) throw error;
-          if (durableRequestWasAdmitted(error)) wasAdmitted = true;
-          const retryDelayMs = Math.min(
-            STATEFUL_OPERATION_RETRY_TICK_MS,
-            deadlineMs - performance.now()
-          );
-          if (retryDelayMs <= 0) {
-            throw durableOperationExhausted(operationKind, wasAdmitted, error);
-          }
-          let timer: ReturnType<typeof setTimeout> | undefined;
-          try {
-            await awaitWithAbort(
-              new Promise<void>((resolve) => {
-                timer = setTimeout(resolve, retryDelayMs);
-              }),
-              stop.signal
-            );
-          } finally {
-            if (timer !== undefined) clearTimeout(timer);
-          }
-        }
-      }
-    } catch (error) {
-      stop.signal.throwIfAborted();
-      throw error;
-    } finally {
-      unobserve();
+    this.requireOpen();
+    if (targetNodeRid === this.nodeRid) {
+      return this.requestLocalInfrastructure(
+        parts[0]!,
+        correlation,
+        Math.ceil(deadlineMs - performance.now())
+      );
     }
+    return requestDurableService(this.raw, targetNodeRid, parts, deadlineMs, operationKind);
   }
 
   private requestLocalInfrastructure(
@@ -4393,7 +4337,8 @@ export class ServiceStatefulRuntime {
       | 'streamBind'
       | 'streamUnbind'
       | 'instanceSpotRequest',
-    actor?: ServiceActorRef
+    actor?: ServiceActorRef,
+    onAdmitted?: () => void
   ): void {
     if (targetNodeRid === this.nodeRid) {
       const deadlineUnixMs = BigInt(Date.now() + Math.max(0, timeoutMs));
@@ -4411,6 +4356,7 @@ export class ServiceStatefulRuntime {
             flags: parts[0]![SERVICE_WIRE_FLAGS_OFFSET]!,
             sourceRoutingId: this.nodeRid,
             requestSequence: pending.id,
+            onAdmitted,
             parts,
             applicationJobOwner
           };
@@ -4429,7 +4375,7 @@ export class ServiceStatefulRuntime {
       })().catch((error) => this.operations.reply(pending.id, failure(error)));
       return;
     }
-    void this.raw.requestService(targetNodeRid, parts, timeoutMs).then(
+    void this.raw.requestService(targetNodeRid, parts, timeoutMs, onAdmitted).then(
       (reply) => this.completeRemoteReply(pending, targetNodeRid, operationKind, actor, reply),
       (error) => this.operations.fail(pending.id, error)
     );
@@ -5414,37 +5360,6 @@ function operationReplayExpired(replayExpiresAtMs: number): boolean {
   return performance.now() > replayExpiresAtMs;
 }
 
-function durableRequestWasAdmitted(error: unknown): boolean {
-  // Request NotConnected includes Core handover of an admitted request. The
-  // submit/request phase, rather than the result number, owns this distinction.
-  return isZLinkBackendResultError(error) && error.operation === 'request';
-}
-
-function durableOperationExhausted(
-  operationKind: 'userSpotCreate' | 'userSpotClose' | 'actorCreate' | 'streamBind' | 'actorJoin',
-  wasAdmitted: boolean,
-  cause?: unknown
-): ZLinkFrameworkException {
-  return createInternalFrameworkException(
-    wasAdmitted
-      ? ZLinkFrameworkInternalErrorKind.DeadlineExceeded
-      : ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-    `${operationKind} exhausted its end-to-end deadline.`,
-    true,
-    cause
-  );
-}
-
-function durableRequestCanReplay(error: unknown): boolean {
-  if (!isZLinkBackendResultError(error)) return false;
-  return error.operation === 'request'
-    ? error.result === RequestResult.NotConnected || error.result === RequestResult.TimedOut
-    : error.result === SubmitResult.NotConnected ||
-        error.result === SubmitResult.NotFound ||
-        error.result === SubmitResult.NotAdmitted ||
-        error.result === SubmitResult.Backpressured;
-}
-
 function remainingDeadlineMs(deadlineUnixMs: bigint): number {
   const remainingMs = deadlineUnixMs - BigInt(Date.now());
   if (remainingMs <= 0n) {
@@ -5937,3 +5852,30 @@ export function statefulMailboxData(
 ): ServiceStatefulMailboxData | undefined {
   return record.stateful as ServiceStatefulMailboxData | undefined;
 }
+
+function acceptsStatefulIngress(command: number): boolean {
+  // These frozen relocation controls overlap the legacy stateful command
+  // number range (30-34). They are bare infrastructure records and must
+  // fall through to RawServiceMeshRuntime's relocation ingress instead of
+  // being decoded as stateful actor/spot work.
+  if (
+    command === M6bServiceWireCommand.relocationReady ||
+    command === M6bServiceWireCommand.relocationData ||
+    command === M6bServiceWireCommand.replyRelay ||
+    command === M6bServiceWireCommand.relocationCutover
+  ) {
+    return false;
+  }
+  if (
+    command < M6bServiceWireCommand.spotSend ||
+    (command > M6bServiceWireCommand.instanceSpot &&
+      command !== M6bServiceWireCommand.userSpotCreate &&
+      command !== M6bServiceWireCommand.userSpotClose &&
+      command !== M6bServiceWireCommand.actorCreate &&
+      command !== M6bServiceWireCommand.messageFollow &&
+      command !== M6bServiceWireCommand.boundSessionReplaced)
+  ) {
+    return false;
+  }
+  return true;
+}

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

@@ -189,11 +189,6 @@ export interface ServiceMaintenanceRelocationPrepare extends ServiceWireRelocati
   /** CRC-32C (Castagnoli) over the fully assembled payload bytes. */
   readonly payloadChecksumCrc32c: number;
   readonly applicationVersion: bigint;
-  /** NODE-INTERNAL; serialized as extra frames after canonical command 40. */
-  readonly nodeInternalBoundSessions?: readonly {
-    readonly participantKey: string;
-    readonly payload: Uint8Array;
-  }[];
 }
 
 export interface ServiceMaintenanceRelocationReady extends ServiceWireRelocationBase {

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

@@ -8,7 +8,10 @@ import {
 } 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';
+import {
+  SERVICE_WIRE_REQUIRED_CAPABILITY,
+  ServiceWireCommand
+} from './service-wire-constants.generated';
 
 export type ServiceNodeState =
   'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
@@ -40,8 +43,14 @@ export interface ServiceNodeDescriptor {
   readonly pendingCapacityUsed: number;
 }
 
-export interface AdmittedServicePeer {
+interface ServiceRouteAdmission {
   readonly descriptor: ServiceNodeDescriptor;
+  readonly descriptorBytes?: Uint8Array;
+  readonly connectionId?: string | bigint;
+  readonly remoteAdmitReceived?: boolean;
+}
+
+export interface AdmittedServicePeer extends ServiceRouteAdmission {
   // The Core selected-route generation this admission belongs to (Core ROUTER
   // §10.1), as an opaque token compared only for equality.
   readonly connectionId: string | bigint;
@@ -69,7 +78,7 @@ interface ServiceSelectionCacheEntry {
 export class ServiceTopologyRegistry {
   private local: ServiceNodeDescriptor;
   private readonly peersByRid = new Map<string, AdmittedServicePeer>();
-  private readonly notRequiredByRid = new Map<string, ServiceNodeDescriptor>();
+  private readonly notRequiredByRid = new Map<string, ServiceRouteAdmission>();
   private readonly knownByRid = new Map<string, ServiceNodeDescriptor>();
   private readonly selections = new Map<string, ServiceSelectionCacheEntry>();
 
@@ -96,7 +105,7 @@ export class ServiceTopologyRegistry {
     }
     this.local = cloneDescriptor(descriptor);
     for (const [nodeRoutingId, remote] of this.notRequiredByRid) {
-      if (!descriptorConnectionNotRequired(this.local, remote)) {
+      if (!descriptorConnectionNotRequired(this.local, remote.descriptor)) {
         this.notRequiredByRid.delete(nodeRoutingId);
       }
     }
@@ -107,7 +116,9 @@ export class ServiceTopologyRegistry {
     descriptor: ServiceNodeDescriptor,
     connectionId: string | bigint,
     expected?: ServicePeerAdmissionExpectation,
-    admitLiveness?: () => ServiceLivenessConnection
+    admitLiveness?: () => ServiceLivenessConnection,
+    command: number = ServiceWireCommand.hello,
+    descriptorBytes?: Uint8Array
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
@@ -127,37 +138,53 @@ export class ServiceTopologyRegistry {
     ) {
       return 'invalidDescriptor';
     }
+    const current = this.peersByRid.get(descriptor.nodeRoutingId);
+    const previous = current ?? this.notRequiredByRid.get(descriptor.nodeRoutingId);
+    const receivedAdmit =
+      command === ServiceWireCommand.admit ||
+      (previous?.connectionId === connectionId && previous.remoteAdmitReceived === true);
+    if (
+      previous !== undefined &&
+      previous.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration
+    ) {
+      const existing = previous.descriptor;
+      if (
+        descriptor.descriptorRevision < existing.descriptorRevision ||
+        (descriptor.descriptorRevision === existing.descriptorRevision &&
+          !(previous.descriptorBytes !== undefined && descriptorBytes !== undefined
+            ? Buffer.compare(previous.descriptorBytes, descriptorBytes) === 0
+            : sameServiceNodeDescriptor(existing, descriptor))) ||
+        (descriptor.descriptorRevision > existing.descriptorRevision &&
+          command !== ServiceWireCommand.update)
+      )
+        return 'staleDescriptor';
+      if (
+        descriptor.descriptorRevision > existing.descriptorRevision &&
+        !sameImmutableDescriptor(existing, descriptor)
+      )
+        return 'invalidDescriptor';
+    } else if (command === ServiceWireCommand.update) {
+      return 'staleDescriptor';
+    }
+    const admission: ServiceRouteAdmission = {
+      descriptor: cloneDescriptor(descriptor),
+      ...(descriptorBytes === undefined ? {} : { descriptorBytes: Buffer.from(descriptorBytes) }),
+      connectionId,
+      remoteAdmitReceived: receivedAdmit
+    };
     if (descriptorConnectionNotRequired(this.local, descriptor)) {
       this.peersByRid.delete(descriptor.nodeRoutingId);
       this.remember(descriptor);
-      this.notRequiredByRid.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+      this.notRequiredByRid.set(descriptor.nodeRoutingId, admission);
       this.rebuildSelections();
       return 'notRequired';
     }
     this.notRequiredByRid.delete(descriptor.nodeRoutingId);
 
-    const current = this.peersByRid.get(descriptor.nodeRoutingId);
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      descriptor.descriptorRevision > current.descriptor.descriptorRevision &&
-      !sameImmutableDescriptor(current.descriptor, descriptor)
-    ) {
-      return 'invalidDescriptor';
-    }
-    if (
-      current !== undefined &&
-      current.descriptor.lifecycleGeneration === descriptor.lifecycleGeneration &&
-      (current.descriptor.descriptorRevision > descriptor.descriptorRevision ||
-        (current.descriptor.descriptorRevision === descriptor.descriptorRevision &&
-          !sameServiceNodeDescriptor(current.descriptor, descriptor)))
-    ) {
-      return 'staleDescriptor';
-    }
     // Core selects the one route per RID (Core ROUTER §10.1); an admission on
     // that route replaces the admission of a route it replaced.
     this.peersByRid.set(descriptor.nodeRoutingId, {
-      descriptor: cloneDescriptor(descriptor),
+      ...admission,
       connectionId,
       liveness: admitLiveness?.() ?? current?.liveness
     });
@@ -175,10 +202,18 @@ export class ServiceTopologyRegistry {
   }
 
   peer(nodeRoutingId: string): AdmittedServicePeer | undefined {
-    const peer = this.peersByRid.get(nodeRoutingId);
+    const peer = this.admittedPeer(nodeRoutingId);
     return peer === undefined ? undefined : clonePeer(peer);
   }
 
+  routeAdmission(nodeRoutingId: string): ServiceRouteAdmission | undefined {
+    return this.peersByRid.get(nodeRoutingId) ?? this.notRequiredByRid.get(nodeRoutingId);
+  }
+
+  admittedPeer(nodeRoutingId: string): AdmittedServicePeer | undefined {
+    return this.peersByRid.get(nodeRoutingId);
+  }
+
   peers(): readonly AdmittedServicePeer[] {
     return this.peersCore();
   }
@@ -193,12 +228,14 @@ export class ServiceTopologyRegistry {
 
   notRequiredPeers(): readonly ServiceNodeDescriptor[] {
     return [...this.notRequiredByRid.values()]
-      .sort((left, right) => compareOrdinal(left.nodeRoutingId, right.nodeRoutingId))
-      .map(cloneDescriptor);
+      .sort((left, right) =>
+        compareOrdinal(left.descriptor.nodeRoutingId, right.descriptor.nodeRoutingId)
+      )
+      .map((peer) => cloneDescriptor(peer.descriptor));
   }
 
   replaceDiscoveredNotRequired(descriptors: readonly ServiceNodeDescriptor[]): void {
-    const next = new Map<string, ServiceNodeDescriptor>();
+    const next = new Map<string, ServiceRouteAdmission>();
     for (const descriptor of descriptors) {
       validateDescriptor(descriptor);
       if (
@@ -206,13 +243,16 @@ export class ServiceTopologyRegistry {
         descriptor.nodeRoutingId !== this.local.nodeRoutingId &&
         descriptorConnectionNotRequired(this.local, descriptor)
       ) {
-        next.set(descriptor.nodeRoutingId, cloneDescriptor(descriptor));
+        next.set(descriptor.nodeRoutingId, {
+          ...this.notRequiredByRid.get(descriptor.nodeRoutingId),
+          descriptor: cloneDescriptor(descriptor)
+        });
       }
     }
     this.notRequiredByRid.clear();
-    for (const [nodeRoutingId, descriptor] of next) {
-      this.notRequiredByRid.set(nodeRoutingId, descriptor);
-      this.remember(descriptor);
+    for (const [nodeRoutingId, admission] of next) {
+      this.notRequiredByRid.set(nodeRoutingId, admission);
+      this.remember(admission.descriptor);
     }
     this.rebuildSelections();
   }
@@ -222,12 +262,27 @@ export class ServiceTopologyRegistry {
   }
 
   knownDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined {
-    const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
-    const descriptor =
-      admitted ?? this.notRequiredByRid.get(nodeRoutingId) ?? this.knownByRid.get(nodeRoutingId);
+    const descriptor = this.knownPeerDescriptor(nodeRoutingId);
     return descriptor === undefined ? undefined : cloneDescriptor(descriptor);
   }
 
+  isObjectClientNodeDirectTarget(nodeRoutingId: string): boolean {
+    const descriptor =
+      nodeRoutingId === this.local.nodeRoutingId
+        ? this.local
+        : this.knownPeerDescriptor(nodeRoutingId);
+    return descriptor?.objectRole === 'client';
+  }
+
+  private knownPeerDescriptor(nodeRoutingId: string): ServiceNodeDescriptor | undefined {
+    const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
+    return (
+      admitted ??
+      this.notRequiredByRid.get(nodeRoutingId)?.descriptor ??
+      this.knownByRid.get(nodeRoutingId)
+    );
+  }
+
   hasKnownChannelTarget(channelName: string): boolean {
     requireText(channelName, 'channelName');
     return [...this.knownByRid.values()].some(