@zlink-systems/framework 0.29.1 → 0.30.1

package/dist/runtime/foundation/service-topology-registry.js

@@ -35,16 +35,19 @@ class ServiceTopologyRegistry {
         }
         this.local = cloneDescriptor(descriptor);
         for (const [nodeRoutingId, remote] of this.notRequiredByRid) {
-            if (!(0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, remote)) {
+            if (!(0, route_mesh_connection_policy_1.descriptorConnectionNotRequired)(this.local, remote.descriptor)) {
                 this.notRequiredByRid.delete(nodeRoutingId);
             }
         }
         this.rebuildSelections();
     }
-    admit(descriptor, connectionId, expected) {
+    admit(descriptor, connectionId, expected, admitLiveness, command = service_wire_constants_generated_1.ServiceWireCommand.hello, descriptorBytes) {
         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';
@@ -60,33 +63,48 @@ class ServiceTopologyRegistry {
                 descriptor.lifecycleGeneration !== expected.lifecycleGeneration)) {
             return 'invalidDescriptor';
         }
+        const current = this.peersByRid.get(descriptor.nodeRoutingId);
+        const previous = current ?? this.notRequiredByRid.get(descriptor.nodeRoutingId);
+        const receivedAdmit = command === service_wire_constants_generated_1.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 !== service_wire_constants_generated_1.ServiceWireCommand.update))
+                return 'staleDescriptor';
+            if (descriptor.descriptorRevision > existing.descriptorRevision &&
+                !sameImmutableDescriptor(existing, descriptor))
+                return 'invalidDescriptor';
+        }
+        else if (command === service_wire_constants_generated_1.ServiceWireCommand.update) {
+            return 'staleDescriptor';
+        }
+        const admission = {
+            descriptor: cloneDescriptor(descriptor),
+            ...(descriptorBytes === undefined ? {} : { descriptorBytes: Buffer.from(descriptorBytes) }),
+            connectionId,
+            remoteAdmitReceived: receivedAdmit
+        };
         if ((0, route_mesh_connection_policy_1.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),
-            connectionId
+            ...admission,
+            connectionId,
+            liveness: admitLiveness?.() ?? current?.liveness
         });
         this.remember(descriptor);
         this.rebuildSelections();
@@ -101,9 +119,15 @@ class ServiceTopologyRegistry {
         return true;
     }
     peer(nodeRoutingId) {
-        const peer = this.peersByRid.get(nodeRoutingId);
+        const peer = this.admittedPeer(nodeRoutingId);
         return peer === undefined ? undefined : clonePeer(peer);
     }
+    routeAdmission(nodeRoutingId) {
+        return this.peersByRid.get(nodeRoutingId) ?? this.notRequiredByRid.get(nodeRoutingId);
+    }
+    admittedPeer(nodeRoutingId) {
+        return this.peersByRid.get(nodeRoutingId);
+    }
     peers() {
         return this.peersCore();
     }
@@ -114,8 +138,8 @@ class ServiceTopologyRegistry {
     }
     notRequiredPeers() {
         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) {
         const next = new Map();
@@ -124,13 +148,16 @@ class ServiceTopologyRegistry {
             if (descriptor.meshName === this.local.meshName &&
                 descriptor.nodeRoutingId !== this.local.nodeRoutingId &&
                 (0, route_mesh_connection_policy_1.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();
     }
@@ -139,10 +166,21 @@ class ServiceTopologyRegistry {
             this.rebuildSelections();
     }
     knownDescriptor(nodeRoutingId) {
-        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) {
+        const descriptor = nodeRoutingId === this.local.nodeRoutingId
+            ? this.local
+            : this.knownPeerDescriptor(nodeRoutingId);
+        return descriptor?.objectRole === 'client';
+    }
+    knownPeerDescriptor(nodeRoutingId) {
+        const admitted = this.peersByRid.get(nodeRoutingId)?.descriptor;
+        return (admitted ??
+            this.notRequiredByRid.get(nodeRoutingId)?.descriptor ??
+            this.knownByRid.get(nodeRoutingId));
+    }
     hasKnownChannelTarget(channelName) {
         requireText(channelName, 'channelName');
         return [...this.knownByRid.values()].some((descriptor) => (descriptor.state === 'serving' ||
@@ -329,7 +367,8 @@ function cloneDescriptor(descriptor) {
 function clonePeer(peer) {
     return {
         descriptor: cloneDescriptor(peer.descriptor),
-        connectionId: peer.connectionId
+        connectionId: peer.connectionId,
+        liveness: peer.liveness
     };
 }
 function sameServiceNodeDescriptor(left, right) {

package/dist/runtime/foundation/service-wire-m6a-codec.d.ts

@@ -66,11 +66,11 @@ export declare class ServiceWireProtocolError extends Error {
 }
 export declare function encodeNodeSendHeader(): Buffer;
 export declare function encodeNodeRequestHeader(correlation: bigint): Buffer;
-export declare function decodeNodeRequestHeader(frame: Uint8Array): bigint;
+export declare function decodeNodeRequestHeader(frame: Uint8Array, header?: ServiceWireHeader): bigint;
 export declare function encodeChannelSendHeader(channelName: string): Buffer;
-export declare function decodeChannelSendHeader(frame: Uint8Array): string;
+export declare function decodeChannelSendHeader(frame: Uint8Array, header?: ServiceWireHeader): string;
 export declare function encodeChannelRequestHeader(correlation: bigint, channelName: string): Buffer;
-export declare function decodeChannelRequestHeader(frame: Uint8Array): {
+export declare function decodeChannelRequestHeader(frame: Uint8Array, header?: ServiceWireHeader): {
     readonly correlation: bigint;
     readonly channelName: string;
 };

package/dist/runtime/foundation/service-wire-m6a-codec.js

@@ -54,8 +54,7 @@ function encodeNodeSendHeader() {
 function encodeNodeRequestHeader(correlation) {
     return withU64(prefix(exports.M6aServiceWireCommand.nodeRequest), correlation, 'correlation');
 }
-function decodeNodeRequestHeader(frame) {
-    const header = decodeHeader(frame);
+function decodeNodeRequestHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.nodeRequest ||
         header.flags !== 0 ||
         frame.byteLength !== 13) {
@@ -66,8 +65,7 @@ function decodeNodeRequestHeader(frame) {
 function encodeChannelSendHeader(channelName) {
     return concat(prefix(exports.M6aServiceWireCommand.channelSend), encodeText8(channelName, 'channelName'));
 }
-function decodeChannelSendHeader(frame) {
-    const header = decodeHeader(frame);
+function decodeChannelSendHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.channelSend || header.flags !== 0) {
         fail('Invalid channelSend header.');
     }
@@ -79,8 +77,7 @@ function decodeChannelSendHeader(frame) {
 function encodeChannelRequestHeader(correlation, channelName) {
     return concat(withU64(prefix(exports.M6aServiceWireCommand.channelRequest), correlation, 'correlation'), encodeText8(channelName, 'channelName'));
 }
-function decodeChannelRequestHeader(frame) {
-    const header = decodeHeader(frame);
+function decodeChannelRequestHeader(frame, header = decodeHeader(frame)) {
     if (header.command !== exports.M6aServiceWireCommand.channelRequest || header.flags !== 0) {
         fail('Invalid channelRequest header.');
     }
@@ -127,22 +124,8 @@ function decodeReplyHeader(frame) {
     return result;
 }
 function encodeApplicationPayload(payload) {
-    const packetName = encodeText8(payload.packetName, 'packetName');
-    const contentType = encodeText8(payload.contentType, 'contentType');
-    if (payload.payload.byteLength > MAX_U32)
-        fail('Application payload exceeds u32.');
-    const bodyLength = packetName.byteLength + contentType.byteLength + 4 + payload.payload.byteLength;
-    if (bodyLength > MAX_U32)
-        fail('Application payload body exceeds u32.');
-    const result = Buffer.alloc(5 + bodyLength);
-    result[0] = exports.APPLICATION_PAYLOAD_VERSION;
-    result.writeUInt32BE(bodyLength, 1);
-    let offset = 5;
-    offset += packetName.copy(result, offset);
-    offset += contentType.copy(result, offset);
-    result.writeUInt32BE(payload.payload.byteLength, offset);
-    offset += 4;
-    Buffer.from(payload.payload.buffer, payload.payload.byteOffset, payload.payload.byteLength).copy(result, offset);
+    const result = allocateApplicationPayload(payload.packetName, payload.contentType, payload.payload.byteLength);
+    result.set(payload.payload, result.byteLength - payload.payload.byteLength);
     return result;
 }
 /**
@@ -155,8 +138,6 @@ function encodeMultipartApplicationPayload(parts, packetName, contentType) {
         fail('Multipart payload must contain at least one part.');
     if (parts.length > MAX_U32)
         fail('Multipart part count exceeds u32.');
-    const packetNameBytes = encodeText8(packetName, 'packetName');
-    const contentTypeBytes = encodeText8(contentType, 'contentType');
     let multipartLength = 4;
     for (const part of parts) {
         if (part.byteLength > MAX_U32)
@@ -165,27 +146,44 @@ function encodeMultipartApplicationPayload(parts, packetName, contentType) {
         if (multipartLength > MAX_U32)
             fail('Multipart payload exceeds u32.');
     }
-    const bodyLength = packetNameBytes.byteLength + contentTypeBytes.byteLength + 4 + multipartLength;
-    if (bodyLength > MAX_U32)
-        fail('Application payload body exceeds u32.');
-    const result = Buffer.alloc(5 + bodyLength);
-    result[0] = exports.APPLICATION_PAYLOAD_VERSION;
-    result.writeUInt32BE(bodyLength, 1);
-    let offset = 5;
-    offset += packetNameBytes.copy(result, offset);
-    offset += contentTypeBytes.copy(result, offset);
-    result.writeUInt32BE(multipartLength, offset);
-    offset += 4;
+    const result = allocateApplicationPayload(packetName, contentType, multipartLength);
+    let offset = result.byteLength - multipartLength;
     result.writeUInt32BE(parts.length, offset);
     offset += 4;
     for (const part of parts) {
         result.writeUInt32BE(part.byteLength, offset);
         offset += 4;
-        Buffer.from(part.buffer, part.byteOffset, part.byteLength).copy(result, offset);
+        result.set(part, offset);
         offset += part.byteLength;
     }
     return result;
 }
+function allocateApplicationPayload(packetName, contentType, payloadLength) {
+    const packetNameBytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(packetName, 'packetName', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+    const contentTypeBytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(contentType, 'contentType', service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
+    if (payloadLength > MAX_U32)
+        fail('Application payload exceeds u32.');
+    const frameLength = exports.APPLICATION_PAYLOAD_MINIMUM_FIELD_BYTES +
+        packetNameBytes.byteLength +
+        contentTypeBytes.byteLength +
+        payloadLength;
+    const prefixLength = 1 + APPLICATION_PAYLOAD_LENGTH_FIELD_BYTES;
+    const bodyLength = frameLength - prefixLength;
+    if (bodyLength > MAX_U32)
+        fail('Application payload body exceeds u32.');
+    const result = Buffer.alloc(frameLength);
+    result[0] = exports.APPLICATION_PAYLOAD_VERSION;
+    result.writeUInt32BE(bodyLength, 1);
+    let offset = prefixLength;
+    result[offset++] = packetNameBytes.byteLength;
+    result.set(packetNameBytes, offset);
+    offset += packetNameBytes.byteLength;
+    result[offset++] = contentTypeBytes.byteLength;
+    result.set(contentTypeBytes, offset);
+    offset += contentTypeBytes.byteLength;
+    result.writeUInt32BE(payloadLength, offset);
+    return result;
+}
 function decodeApplicationPayload(frame) {
     const decoded = decodeApplicationPayloadView(frame);
     return {
@@ -419,7 +417,7 @@ function encodeU64(value) {
     return result;
 }
 function encodeText8(value, field) {
-    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, 0xff, fail);
+    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES, fail);
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
 function encodeText16(value, field) {
@@ -430,7 +428,7 @@ function tlv(id, value) {
     return concat(Buffer.of(id), encodeU32(value.byteLength), value);
 }
 function concat(...parts) {
-    return Buffer.concat(parts.map((part) => Buffer.from(part)));
+    return Buffer.concat(parts);
 }
 function readNonZeroU64(bytes, offset, field) {
     const result = bytes.readBigUInt64BE(offset);

package/dist/runtime/handlers/handler-instance-scope.d.ts

@@ -5,9 +5,17 @@ export interface ZLinkHandlerInstanceScope {
     resolve<T>(type: Type<T>): Promise<T>;
     dispose(): Promise<void>;
 }
+interface ZLinkHandlerInstanceScopeFactory {
+    prepare?(type: Type): void | (() => unknown);
+    create(context?: ZLinkMessageContext): ZLinkHandlerInstanceScope;
+}
+export declare function registerHandlerInstanceScopeFactory(providerResolver: ZLinkProviderResolver, factory: ZLinkHandlerInstanceScopeFactory): void;
+export declare function prepareHandlerInstance<T>(providerResolver: ZLinkProviderResolver | undefined, type: Type<T>): (() => T) | undefined;
 export declare function runInHandlerInstanceScope<T>(providerResolver: ZLinkProviderResolver | undefined, context: ZLinkMessageContext | undefined, callback: (scope: ZLinkHandlerInstanceScope) => Promise<T>): Promise<T>;
 export declare function resolveLifecycleHandler<T>(owner: object, type: Type<T>, providerResolver?: ZLinkProviderResolver): Promise<T>;
 export declare function runWithLifecycleHandler<THandler, TResult>(owner: object, type: Type<THandler>, providerResolver: ZLinkProviderResolver | undefined, callback: (handler: THandler) => Promise<TResult>): Promise<TResult>;
 export declare function disposeLifecycleHandlers(owner: object, detachedTaskRunner: ZLinkDetachedTaskRunner): Promise<void>;
 export declare function disposeOwnedInstance(instance: unknown): Promise<void>;
+export declare function handlerInstanceCleanup(instance: unknown): (() => unknown) | undefined;
 export declare function disposeOwnedInstances(instances: readonly unknown[]): Promise<void>;
+export {};

package/dist/runtime/handlers/handler-instance-scope.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHandlerInstanceScopeFactory = registerHandlerInstanceScopeFactory;
+exports.prepareHandlerInstance = prepareHandlerInstance;
 exports.runInHandlerInstanceScope = runInHandlerInstanceScope;
 exports.resolveLifecycleHandler = resolveLifecycleHandler;
 exports.runWithLifecycleHandler = runWithLifecycleHandler;
 exports.disposeLifecycleHandlers = disposeLifecycleHandlers;
 exports.disposeOwnedInstance = disposeOwnedInstance;
+exports.handlerInstanceCleanup = handlerInstanceCleanup;
 exports.disposeOwnedInstances = disposeOwnedInstances;
 const node_async_hooks_1 = require("node:async_hooks");
 const HANDLER_SCOPE_FACTORY = Symbol.for('@zlink-systems/framework.handler-instance-scope-factory');
@@ -13,10 +16,27 @@ const activeLifecycleScope = new node_async_hooks_1.AsyncLocalStorage();
 const detachedLifecycleResource = new node_async_hooks_1.AsyncResource('zlink:handler-instance-scope');
 const dispatchScopes = new WeakMap();
 const lifecycleScopes = new WeakMap();
+function registerHandlerInstanceScopeFactory(providerResolver, factory) {
+    Object.defineProperty(providerResolver, HANDLER_SCOPE_FACTORY, {
+        value: factory,
+        enumerable: false
+    });
+}
+function prepareHandlerInstance(providerResolver, type) {
+    if (providerResolver === undefined)
+        return () => new type();
+    const factory = providerResolver[HANDLER_SCOPE_FACTORY];
+    if (isHandlerInstanceScopeFactory(factory)) {
+        const activate = factory.prepare?.(type);
+        if (activate !== undefined)
+            return activate;
+    }
+    return undefined;
+}
 async function runInHandlerInstanceScope(providerResolver, context, callback) {
     const active = activeHandlerScope.getStore();
     if (active !== undefined) {
-        return callback(active.scope);
+        return callback(active);
     }
     if (context !== undefined) {
         const existing = dispatchScopes.get(context);
@@ -29,7 +49,7 @@ async function runInHandlerInstanceScope(providerResolver, context, callback) {
         dispatchScopes.set(context, scope);
     }
     try {
-        return await activeHandlerScope.run({ scope }, () => callback(scope));
+        return await activeHandlerScope.run(scope, () => callback(scope));
     }
     finally {
         if (context !== undefined && dispatchScopes.get(context) === scope) {
@@ -94,14 +114,15 @@ class DefaultHandlerInstanceScope {
             return existing;
         const activation = createDeferred();
         this.instances.set(type, activation.promise);
-        void this.activate(type, activation);
+        this.activate(type, activation);
         return activation.promise;
     }
     async dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
-        await Promise.allSettled(this.instances.values());
+        if (this.owned.length !== this.instances.size)
+            await Promise.allSettled(this.instances.values());
         try {
             await disposeOwnedInstances(this.owned);
         }
@@ -110,21 +131,37 @@ class DefaultHandlerInstanceScope {
             this.instances.clear();
         }
     }
-    async activate(type, activation) {
-        let instance;
+    activate(type, activation) {
         try {
             const created = this.providerResolver?.create?.(type);
-            instance = created === undefined ? new type() : await created;
+            if (created === undefined) {
+                this.completeActivation(new type(), activation);
+            }
+            else {
+                void this.activatePending(created, activation);
+            }
         }
         catch (error) {
             activation.reject(error);
-            return;
         }
+    }
+    async activatePending(created, activation) {
+        try {
+            this.completeActivation(await created, activation);
+        }
+        catch (error) {
+            activation.reject(error);
+        }
+    }
+    completeActivation(instance, activation) {
         if (!this.disposed) {
             this.owned.push(instance);
             activation.resolve(instance);
             return;
         }
+        void this.disposeLateActivation(instance, activation);
+    }
+    async disposeLateActivation(instance, activation) {
         try {
             await disposeOwnedInstance(instance);
             activation.reject(new Error('Handler instance scope was disposed during activation.'));
@@ -240,18 +277,24 @@ function startOutsideLifecycleInvocation(work) {
     return detachedLifecycleResource.runInAsyncScope(work);
 }
 async function disposeOwnedInstance(instance) {
+    const cleanup = handlerInstanceCleanup(instance);
+    if (cleanup !== undefined)
+        await cleanup.call(instance);
+}
+function handlerInstanceCleanup(instance) {
     if (instance === null || instance === undefined)
         return;
     const value = instance;
     if (typeof value.dispose === 'function') {
-        await value.dispose();
+        return value.dispose;
     }
     else if (typeof value.close === 'function') {
-        await value.close();
+        return value.close;
     }
     else if (typeof value.onModuleDestroy === 'function') {
-        await value.onModuleDestroy();
+        return value.onModuleDestroy;
     }
+    return undefined;
 }
 async function disposeOwnedInstances(instances) {
     const failures = [];

package/dist/runtime/host/actor-packet-relay.js

@@ -173,8 +173,8 @@ class ZLinkActorPacketRelay {
             const state = this.options.actorManager()?.getState(relay.actorId);
             if (frameHeader.kind === protocol_1.ZLinkStreamMessageKind.Send) {
                 const dispatch = state?.spotId === undefined
-                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
-                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
                 // Spec 05 §1.3: a one-way Session Actor relay completes at relay
                 // queue admission, not after the remote application turn. In
                 // particular, a handler may register a deferred Join whose relocation
@@ -207,8 +207,8 @@ class ZLinkActorPacketRelay {
                 frameHeader.requestSeq !== undefined &&
                 relay.returnResponse !== true) {
                 const dispatch = state?.spotId === undefined
-                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
-                    : this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
+                    ? this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef)
+                    : this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], false, remoteBoundSessionTarget, fallbackActorRef);
                 closeFrameMessages = false;
                 const deferredPacketName = frameHeader.name;
                 const deferredRequestSeq = frameHeader.requestSeq;
@@ -249,8 +249,8 @@ class ZLinkActorPacketRelay {
                 };
             }
             const response = state?.spotId === undefined
-                ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket(relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef)
-                : await this.requireSpotManager().dispatchRoutedActorPacket(state.spotId, relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef);
+                ? await this.requireSpotNodeRuntime().dispatchEntryActorPacket('remote', relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef)
+                : await this.requireSpotManager().dispatchRoutedActorPacket('remote', state.spotId, relay.actorId, [header, body], relay.returnResponse === true, remoteBoundSessionTarget, fallbackActorRef);
             return {
                 ok: true,
                 response,
@@ -551,7 +551,7 @@ class ZLinkActorPacketRelay {
         try {
             this.options.detachedTaskRunner.runDetached('local actor packet relay', async () => {
                 try {
-                    const response = await this.requireSpotManager().dispatchRoutedActorPacket(spotId, actor.actorId, [header, body], returnResponse);
+                    const response = await this.requireSpotManager().dispatchRoutedActorPacket('local', spotId, actor.actorId, [header, body], returnResponse);
                     if (!returnResponse) {
                         return;
                     }

package/dist/runtime/host/actor-runtime-options-factory.js

@@ -149,9 +149,9 @@ class ZLinkActorRuntimeOptionsFactory {
             staleActorRefReporter: (_meshName, actorId) => this.options.actorHandoff.recordStaleFailure(actorId),
             staleActorRefPredicate: (meshName, actor) => this.actorBelongsToMesh(meshName, actor.actorId) &&
                 this.options.actorHandoff.isKnownStale(actor),
-            handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs) => this.actorBelongsToMesh(meshName, actorId) &&
+            handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs, onAdmitted) => this.actorBelongsToMesh(meshName, actorId) &&
                 !this.options.actorHandoff.isProvisional(actorId)
-                ? this.options.actorHandoff.capture(actorId, parts, returnResponse, undefined, actor, deadlineUnixMs)
+                ? this.options.actorHandoff.capture('local', actorId, parts, returnResponse, undefined, actor, deadlineUnixMs, undefined, undefined, onAdmitted)
                 : undefined,
             sendErrorReporter: this.options.reportPostCommitError
         };

package/dist/runtime/host/application-job-queue.d.ts

@@ -1,4 +1,4 @@
-import type { ApplicationJobPermitPort, ApplicationJobQueuePort } from '../application-jobs/contracts';
+import type { ApplicationJobOrigin, ApplicationJobPermitPort, ApplicationJobReceiveRotationPort, ApplicationJobQueuePort } from '../application-jobs/contracts';
 export type ApplicationJobQueueProfileValue = 'compact' | 'low_latency' | 'balanced' | 'throughput';
 export interface ApplicationJobQueueOptions {
     readonly profile?: ApplicationJobQueueProfileValue;
@@ -39,12 +39,18 @@ export interface ApplicationJobQueueSnapshot extends ApplicationJobQueueConfigur
 export declare function resolveApplicationJobQueueConfiguration(options?: ApplicationJobQueueOptions, effectiveProcessorCount?: () => bigint): ApplicationJobQueueConfiguration;
 export declare class ApplicationJobQueuePermit implements ApplicationJobPermitPort {
     private readonly owner;
+    readonly origin: ApplicationJobOrigin;
+    private readonly reusable;
+    detachedForHandlerTurn: boolean;
     private state;
-    constructor(owner: ApplicationJobQueue);
+    constructor(owner: ApplicationJobQueue, origin: ApplicationJobOrigin, reusable?: boolean);
+    reserveStorage(): boolean;
+    releaseStorage(): void;
+    detachForHandlerTurn(): void;
     markApplicationQueued(): void;
     releaseBeforeHandler(): void;
     releaseAfterInternalProcessing(): void;
-    private release;
+    takeReleaseState(): 'reserved' | 'queued' | undefined;
 }
 /**
  * Host-instance owner of the ordinary-ingress queue permit lifecycle.
@@ -55,9 +61,13 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private readonly configuration;
     private readonly nowMs;
     private readonly handlerStartGate?;
-    private reservedSupplyPermits;
-    private queuedApplicationJobs;
-    private peakPermitsInUse;
+    private readonly loggerFailureReporter?;
+    private localWaiters;
+    private localBacklogLogged;
+    private readonly permitCounts;
+    private readonly limitCount;
+    private readonly pauseCount;
+    private readonly resumeCount;
     private capacityWaitCount;
     private capacityWaitDurationSeconds;
     private metricsEpoch;
@@ -73,11 +83,15 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     private readonly waiters;
     private readonly receiveFlowTargets;
     private readonly receiveFlowController;
-    constructor(configuration: ApplicationJobQueueConfiguration, nowMs?: () => number, handlerStartGate?: (() => boolean) | undefined);
+    constructor(configuration: ApplicationJobQueueConfiguration, nowMs?: () => number, handlerStartGate?: (() => boolean) | undefined, loggerFailureReporter?: ((error: unknown) => void) | undefined);
     shouldHoldPermitBeforeHandler(): boolean;
+    createReceiveRotation(capacity: number, origin: ApplicationJobOrigin): ApplicationJobReceiveRotationPort;
+    receiveRotationCapacity(capacity: number): number;
+    reserveReceiveRotation(count: number): void;
     registerReceiveFlowTarget(identity: object, applyState: (state: ApplicationJobQueuePressureState) => void, failureSink?: (error: unknown) => void): boolean;
     unregisterReceiveFlowTarget(identity: object): void;
-    acquire(signal?: AbortSignal): Promise<ApplicationJobQueuePermit>;
+    acquire(signal: AbortSignal | undefined, origin: ApplicationJobOrigin): Promise<ApplicationJobQueuePermit>;
+    acquireOrResume(resume: (permit: ApplicationJobQueuePermit) => void, reject: (reason: unknown) => void, signal: AbortSignal | undefined, origin: ApplicationJobOrigin): ApplicationJobQueuePermit | undefined;
     snapshot(): ApplicationJobQueueSnapshot;
     resetMetrics(): void;
     pressureState(): ApplicationJobQueuePressureState;
@@ -85,13 +99,18 @@ export declare class ApplicationJobQueue implements ApplicationJobQueuePort {
     onPressureStateChange(listener: (state: ApplicationJobQueuePressureState, sequence: bigint) => void): () => void;
     recordFlowStateConfigFailure(): void;
     markQueued(): void;
-    release(state: 'reserved' | 'queued'): void;
+    releasePermit(permit: ApplicationJobQueuePermit): void;
+    releaseUnusedReceiveRotation(grants: readonly (ApplicationJobQueuePermit | undefined)[], consumed: number, granted: number): void;
+    release(state: 'reserved' | 'queued', count?: number): void;
     private limit;
     private permitsInUse;
+    private reserveSupply;
     private reserve;
     private drainWaiters;
     private cancel;
     private recordCompletedWait;
+    private updateLocalWaiters;
+    private logLocalBacklog;
     private evaluatePressure;
     private pauseDurationAt;
     private cumulativePauseDurationAt;