@zlink-systems/framework 0.29.0 → 0.30.0

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 {

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

@@ -1,4 +1,5 @@
 import { ZLINK_MAX_IDENTITY_TEXT_BYTES } from '../../contracts/Common/CoreTypes';
+import type { ServiceLivenessConnection } from './service-liveness-registry';
 import {
   ZLINK_MAX_PUBLIC_WEIGHT,
   isValidCapacity,
@@ -43,7 +44,8 @@ export interface AdmittedServicePeer {
   readonly descriptor: ServiceNodeDescriptor;
   // The Core selected-route generation this admission belongs to (Core ROUTER
   // §10.1), as an opaque token compared only for equality.
-  readonly connectionId: string;
+  readonly connectionId: string | bigint;
+  readonly liveness?: ServiceLivenessConnection;
 }
 
 export interface ServicePeerAdmissionExpectation {
@@ -103,12 +105,14 @@ export class ServiceTopologyRegistry {
 
   admit(
     descriptor: ServiceNodeDescriptor,
-    connectionId: string,
-    expected?: ServicePeerAdmissionExpectation
+    connectionId: string | bigint,
+    expected?: ServicePeerAdmissionExpectation,
+    admitLiveness?: () => ServiceLivenessConnection
   ): PeerAdmissionResult {
     try {
       validateDescriptor(descriptor);
-      requireText(connectionId, 'connectionId');
+      if (typeof connectionId === 'string') requireText(connectionId, 'connectionId');
+      else if (connectionId === 0n) throw new TypeError('connectionId must be nonzero.');
     } catch (error) {
       return 'invalidDescriptor';
     }
@@ -154,14 +158,15 @@ export class ServiceTopologyRegistry {
     // that route replaces the admission of a route it replaced.
     this.peersByRid.set(descriptor.nodeRoutingId, {
       descriptor: cloneDescriptor(descriptor),
-      connectionId
+      connectionId,
+      liveness: admitLiveness?.() ?? current?.liveness
     });
     this.remember(descriptor);
     this.rebuildSelections();
     return 'admitted';
   }
 
-  disconnect(nodeRoutingId: string, connectionId: string): boolean {
+  disconnect(nodeRoutingId: string, connectionId: string | bigint): boolean {
     const current = this.peersByRid.get(nodeRoutingId);
     if (current === undefined || current.connectionId !== connectionId) return false;
     this.peersByRid.delete(nodeRoutingId);
@@ -525,7 +530,8 @@ function cloneDescriptor(descriptor: ServiceNodeDescriptor): ServiceNodeDescript
 function clonePeer(peer: AdmittedServicePeer): AdmittedServicePeer {
   return {
     descriptor: cloneDescriptor(peer.descriptor),
-    connectionId: peer.connectionId
+    connectionId: peer.connectionId,
+    liveness: peer.liveness
   };
 }
 

package/src/runtime/handlers/handler-instance-scope.ts

@@ -212,7 +212,8 @@ class LifecycleHandlerInstanceScope {
   }
 
   async dispose(detachedTaskRunner: ZLinkDetachedTaskRunner): Promise<void> {
-    const disposeFromActiveInvocation = activeLifecycleScope.getStore() === this;
+    const disposeFromActiveInvocation =
+      this.activeInvocations > 0 && activeLifecycleScope.getStore() === this;
     const disposal = this.beginDisposeCore();
     if (disposal.deferred !== undefined) {
       startOutsideLifecycleInvocation(() => {

package/src/runtime/host/actor-packet-relay.ts

@@ -303,6 +303,7 @@ export class ZLinkActorPacketRelay {
         const dispatch =
           state?.spotId === undefined
             ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+                'remote',
                 relay.actorId,
                 [header, body],
                 false,
@@ -310,6 +311,7 @@ export class ZLinkActorPacketRelay {
                 fallbackActorRef
               )
             : this.requireSpotManager().dispatchRoutedActorPacket(
+                'remote',
                 state.spotId,
                 relay.actorId,
                 [header, body],
@@ -356,6 +358,7 @@ export class ZLinkActorPacketRelay {
         const dispatch =
           state?.spotId === undefined
             ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+                'remote',
                 relay.actorId,
                 [header, body],
                 false,
@@ -363,6 +366,7 @@ export class ZLinkActorPacketRelay {
                 fallbackActorRef
               )
             : this.requireSpotManager().dispatchRoutedActorPacket(
+                'remote',
                 state.spotId,
                 relay.actorId,
                 [header, body],
@@ -423,6 +427,7 @@ export class ZLinkActorPacketRelay {
       const response =
         state?.spotId === undefined
           ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+              'remote',
               relay.actorId,
               [header, body],
               relay.returnResponse === true,
@@ -430,6 +435,7 @@ export class ZLinkActorPacketRelay {
               fallbackActorRef
             )
           : await this.requireSpotManager().dispatchRoutedActorPacket(
+              'remote',
               state.spotId,
               relay.actorId,
               [header, body],
@@ -892,6 +898,7 @@ export class ZLinkActorPacketRelay {
       this.options.detachedTaskRunner.runDetached('local actor packet relay', async () => {
         try {
           const response = await this.requireSpotManager().dispatchRoutedActorPacket(
+            'local',
             spotId,
             actor.actorId,
             [header, body],

package/src/runtime/host/actor-placement-coordinator.ts

@@ -11,7 +11,8 @@ import type {
   ZLinkAuthoritySnapshot,
   ZLinkCreationOperationIdentity,
   ZLinkLocationOwnerToken,
-  ZLinkObjectReserveResult
+  ZLinkObjectReserveResult,
+  ZLinkObjectReserveRequest
 } from '../locations/internal-location-contracts';
 import type {
   ZLinkAuthorityStore,
@@ -57,6 +58,10 @@ export interface ZLinkActorPlacementTarget {
 }
 
 export interface ZLinkActorPlacementCoordinatorOptions {
+  readonly actorRelocationPolicy?: (
+    meshName: string,
+    stableType: string
+  ) => ZLinkObjectReserveRequest['actorRelocationPolicy'];
   readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
   readonly target: (
     meshName: string | undefined,
@@ -130,7 +135,8 @@ export class ZLinkActorPlacementCoordinator {
             },
             target: reservationTarget(target),
             creatingPayload,
-            capacity: { actors: 1, spots: 0 }
+            capacity: { actors: 1, spots: 0 },
+            actorRelocationPolicy: this.options.actorRelocationPolicy?.(target.meshName, stableType)
           },
           deadline.signal,
           BigInt(deadlineUnixMs)

package/src/runtime/host/actor-runtime-options-factory.ts

@@ -34,6 +34,10 @@ import type { ZLinkRemoteActorPacketTarget } from '../actors';
 import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
 
 export interface ZLinkActorRuntimeOptionsFactoryOptions {
+  readonly terminateActorActivation: (
+    actor: ZLinkActor,
+    terminal: () => Promise<void>
+  ) => Promise<void>;
   readonly registration: ZLinkFrameworkRegistration;
   /** Message flow tracer, so a failed deferred Join records its cause on the flow. */
   readonly messageFlow?: () =>
@@ -101,6 +105,7 @@ export class ZLinkActorRuntimeOptionsFactory {
     | 'actorRefResolver'
     | 'actorCreatedNotifier'
     | 'actorDestroyedCleanup'
+    | 'terminateActorActivation'
     | 'publishActorAuthority'
     | 'locationLifecycle'
     | 'boundSessionFactory'
@@ -111,6 +116,7 @@ export class ZLinkActorRuntimeOptionsFactory {
   > {
     const actorTransferRegistry = this.options.actorTransferRegistry;
     return {
+      terminateActorActivation: this.options.terminateActorActivation,
       actorMeshNameProvider: this.options.actorMeshName,
       actorLeaveSpot: (meshName, spotId, actor, signal) => {
         const spotManager = this.options.spotManager();
@@ -274,6 +280,7 @@ export class ZLinkActorRuntimeOptionsFactory {
         this.actorBelongsToMesh(meshName, actorId) &&
         !this.options.actorHandoff.isProvisional(actorId)
           ? this.options.actorHandoff.capture(
+              'local',
               actorId,
               parts,
               returnResponse,

package/src/runtime/host/application-job-queue.ts

@@ -1,3 +1,5 @@
+import { SeverityNumber } from '@opentelemetry/api-logs';
+import { telemetryLogger } from '../diagnostics/message-flow';
 import { MILLISECONDS_PER_SECOND } from '../diagnostics/runtime-metrics';
 import { ZLinkApplicationJobQueueProfile } from '../../contracts/Dispatch';
 import {
@@ -11,6 +13,7 @@ import {
 import { readFileSync } from 'node:fs';
 import { availableParallelism } from 'node:os';
 import type {
+  ApplicationJobOrigin,
   ApplicationJobPermitPort,
   ApplicationJobQueuePort
 } from '../application-jobs/contracts';
@@ -122,7 +125,10 @@ export function resolveApplicationJobQueueConfiguration(
 export class ApplicationJobQueuePermit implements ApplicationJobPermitPort {
   private state: 'reserved' | 'queued' | 'released' = 'reserved';
 
-  constructor(private readonly owner: ApplicationJobQueue) {}
+  constructor(
+    private readonly owner: ApplicationJobQueue,
+    readonly origin: ApplicationJobOrigin
+  ) {}
 
   markApplicationQueued(): void {
     if (this.state !== 'reserved') {
@@ -149,6 +155,7 @@ export class ApplicationJobQueuePermit implements ApplicationJobPermitPort {
 }
 
 interface CapacityWaiter {
+  readonly origin: ApplicationJobOrigin;
   readonly resolve: (permit: ApplicationJobQueuePermit) => void;
   readonly reject: (reason: unknown) => void;
   readonly signal?: AbortSignal;
@@ -164,6 +171,8 @@ interface CapacityWaiter {
  * directly to the oldest live waiter without allocating the configured limit.
  */
 export class ApplicationJobQueue implements ApplicationJobQueuePort {
+  private localWaiters = 0;
+  private localBacklogLogged = false;
   private reservedSupplyPermits = 0n;
   private queuedApplicationJobs = 0n;
   private peakPermitsInUse = 0n;
@@ -191,7 +200,8 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
   constructor(
     private readonly configuration: ApplicationJobQueueConfiguration,
     private readonly nowMs: () => number = () => performance.now(),
-    private readonly handlerStartGate?: () => boolean
+    private readonly handlerStartGate?: () => boolean,
+    private readonly loggerFailureReporter?: (error: unknown) => void
   ) {
     this.receiveFlowController = new ApplicationJobReceiveFlowController(this, (state) => state);
   }
@@ -242,16 +252,33 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
     this.receiveFlowController.unregister(target);
   }
 
-  acquire(signal?: AbortSignal): Promise<ApplicationJobQueuePermit> {
+  acquire(
+    signal: AbortSignal | undefined,
+    origin: ApplicationJobOrigin
+  ): Promise<ApplicationJobQueuePermit> {
+    return new Promise((resolve, reject) => {
+      const permit = this.acquireOrResume(resolve, reject, signal, origin);
+      if (permit !== undefined) resolve(permit);
+    });
+  }
+
+  acquireOrResume(
+    resume: (permit: ApplicationJobQueuePermit) => void,
+    reject: (reason: unknown) => void,
+    signal: AbortSignal | undefined,
+    origin: ApplicationJobOrigin
+  ): ApplicationJobQueuePermit | undefined {
     if (signal?.aborted === true) {
-      return Promise.reject(abortReason(signal));
+      reject(abortReason(signal));
+      return undefined;
     }
     if (this.waiters.length === 0 && this.permitsInUse() < this.limit()) {
-      return Promise.resolve(this.reserve());
+      return this.reserve(origin);
     }
 
-    return new Promise<ApplicationJobQueuePermit>((resolve, reject) => {
+    new Promise<ApplicationJobQueuePermit>((resolve, reject) => {
       const waiter: CapacityWaiter = {
+        origin,
         resolve,
         reject,
         signal,
@@ -262,9 +289,14 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
       };
       this.waiters.push(waiter);
       this.capacityWaitCount += 1n;
+      const warningCount = this.updateLocalWaiters(origin, 1);
       signal?.addEventListener('abort', waiter.abort, { once: true });
       this.drainWaiters();
-    });
+      if (warningCount !== undefined) this.logLocalBacklog(warningCount);
+    })
+      .then(resume)
+      .catch(reject);
+    return undefined;
   }
 
   snapshot(): ApplicationJobQueueSnapshot {
@@ -356,12 +388,15 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
     return this.reservedSupplyPermits + this.queuedApplicationJobs;
   }
 
-  private reserve(evaluatePressure = true): ApplicationJobQueuePermit {
+  private reserve(
+    origin: ApplicationJobOrigin,
+    evaluatePressure = true
+  ): ApplicationJobQueuePermit {
     this.reservedSupplyPermits += 1n;
     const current = this.permitsInUse();
     if (current > this.peakPermitsInUse) this.peakPermitsInUse = current;
     if (evaluatePressure) this.evaluatePressure();
-    return new ApplicationJobQueuePermit(this);
+    return new ApplicationJobQueuePermit(this, origin);
   }
 
   private drainWaiters(): void {
@@ -371,7 +406,7 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
       waiter.active = false;
       waiter.signal?.removeEventListener('abort', waiter.abort);
       this.recordCompletedWait(waiter);
-      waiter.resolve(this.reserve(false));
+      waiter.resolve(this.reserve(waiter.origin, false));
     }
   }
 
@@ -387,11 +422,43 @@ export class ApplicationJobQueue implements ApplicationJobQueuePort {
   }
 
   private recordCompletedWait(waiter: CapacityWaiter): void {
+    this.updateLocalWaiters(waiter.origin, -1);
     if (waiter.metricsEpoch !== this.metricsEpoch) return;
     const durationMs = Math.max(0, this.nowMs() - waiter.startedAtMs);
     this.capacityWaitDurationSeconds += durationMs / MILLISECONDS_PER_SECOND;
   }
 
+  private updateLocalWaiters(origin: ApplicationJobOrigin, delta: number): number | undefined {
+    if (origin !== 'local') return undefined;
+    this.localWaiters += delta;
+    if (this.localWaiters === 0) this.localBacklogLogged = false;
+    if (!this.localBacklogLogged && this.localWaiters > Number(this.limit())) {
+      this.localBacklogLogged = true;
+      return this.localWaiters;
+    }
+    return undefined;
+  }
+
+  private logLocalBacklog(localWaiters: number): void {
+    try {
+      telemetryLogger.emit({
+        eventName: 'zlink.runtime.host.local_job_backlog_exceeded',
+        timestamp: new Date(),
+        severityNumber: SeverityNumber.WARN,
+        severityText: 'WARN',
+        body: 'Same-host jobs waiting for a host permit exceeded the application job queue maximum.',
+        attributes: {
+          source_kind: 'host',
+          source_name: 'zlink.runtime.host',
+          local_waiters: localWaiters,
+          effective_maximum: Number(this.limit())
+        }
+      });
+    } catch (error) {
+      this.loggerFailureReporter?.(error);
+    }
+  }
+
   private evaluatePressure(): void {
     const permitsInUse = this.permitsInUse();
     const next =

package/src/runtime/host/entry-actor-runtime.ts

@@ -95,6 +95,7 @@ export class ZLinkEntryActorRuntimeService implements ZLinkEntryActorRuntime {
     return {
       handled: true,
       response: await spotManager.dispatchRoutedActorPacket(
+        'remote',
         spotId,
         actorId,
         parts,