@zlink-systems/framework 0.31.0 → 0.32.1

package/dist/contracts/Actors/ZLinkActor.d.ts

@@ -1,7 +1,9 @@
 import type { ZLinkActorContext } from './ZLinkActorContext';
 import type { ZLinkActorJoinCompletion } from './ZLinkActorFactory';
+import type { ZLinkSessionBindingIdentity } from './ZLinkSessionBindingIdentity';
 export interface ZLinkActor {
     readonly context: ZLinkActorContext;
     configure?(): void;
     onJoinCompleted?(completion: ZLinkActorJoinCompletion): Promise<void>;
+    onDuplicateBind?(current: ZLinkSessionBindingIdentity, incoming: ZLinkSessionBindingIdentity, signal: AbortSignal): Promise<string | undefined>;
 }

package/dist/contracts/Actors/ZLinkSessionBindingIdentity.d.ts

@@ -0,0 +1,6 @@
+import type { RoutingId } from '../Common';
+export interface ZLinkSessionBindingIdentity {
+    readonly sessionOwnerNodeRid: RoutingId;
+    readonly sessionOwnerNodeGeneration: bigint;
+    readonly bindingGeneration: bigint;
+}

package/dist/contracts/Actors/ZLinkSessionBindingIdentity.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/Actors/index.d.ts

@@ -1,4 +1,5 @@
 export * from './ZLinkActor';
+export * from './ZLinkSessionBindingIdentity';
 export * from './ZLinkActorContext';
 export * from './ZLinkActorClient';
 export * from './ZLinkActorFactory';

package/dist/contracts/Actors/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./ZLinkActor"), exports);
+__exportStar(require("./ZLinkSessionBindingIdentity"), exports);
 __exportStar(require("./ZLinkActorContext"), exports);
 __exportStar(require("./ZLinkActorClient"), exports);
 __exportStar(require("./ZLinkActorFactory"), exports);

package/dist/contracts/Common/payload-slab.d.ts

@@ -0,0 +1,4 @@
+/** Allocates independent bytes; previously returned regions are never reused. */
+export declare function allocatePayloadBytes(length: number): Buffer;
+/** Copies bytes into an exact, standalone backing store with no Buffer pool. */
+export declare function copyPayloadBytes(bytes: Uint8Array): Buffer;

package/dist/contracts/Common/payload-slab.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allocatePayloadBytes = allocatePayloadBytes;
+exports.copyPayloadBytes = copyPayloadBytes;
+const SLAB_BYTES = 64 * 1024;
+const MAX_POOLED_BYTES = 16 * 1024;
+const ALIGNMENT = 8;
+let slab;
+let offset = 0;
+/** Allocates independent bytes; previously returned regions are never reused. */
+function allocatePayloadBytes(length) {
+    if (length > MAX_POOLED_BYTES || length < 0 || !Number.isInteger(length)) {
+        return Buffer.allocUnsafe(length);
+    }
+    if (slab === undefined || offset + length > SLAB_BYTES) {
+        slab = Buffer.allocUnsafe(SLAB_BYTES);
+        offset = 0;
+    }
+    const bytes = slab.subarray(offset, offset + length);
+    offset += Math.ceil(length / ALIGNMENT) * ALIGNMENT;
+    // Transient runtime frames only; local queues and application boundaries
+    // copy before they retain or expose these bytes.
+    return bytes;
+}
+/** Copies bytes into an exact, standalone backing store with no Buffer pool. */
+function copyPayloadBytes(bytes) {
+    const copy = Buffer.allocUnsafeSlow(bytes.byteLength);
+    copy.set(bytes);
+    return copy;
+}

package/dist/contracts/Handlers/Contexts.d.ts

@@ -6,6 +6,7 @@ export interface ZLinkMessageContext {
     readonly contentType?: string;
     readonly metadata: ZLinkMessageMetadata;
     readonly correlationId?: string;
+    readonly receivedAt: Date;
 }
 export interface ZLinkPublishMessageContext extends ZLinkMessageContext {
     readonly channelName: string;

package/dist/internal.d.ts

@@ -3,6 +3,11 @@ export * from './index';
 export { requireValidSendTimeoutMs } from './contracts/Configuration/SendTimeoutValidation';
 export * from './runtime/diagnostics';
 export * from './runtime/host';
+export { ZLinkActorPlacementCoordinator } from './runtime/host/actor-placement-coordinator';
+export { ZLinkActorTransferRuntime } from './runtime/host/actor-transfer-runtime';
+export { ApplicationJobQueue, ApplicationJobQueuePermit, nodeEffectiveProcessorCount, resolveApplicationJobQueueConfiguration } from './runtime/host/application-job-queue';
+export { ZLinkLocationRuntimeOwner } from './runtime/host/location-runtime-owner';
+export { relocationFailedFailureCode, ZLinkHostServiceRelocationRuntime } from './runtime/host/service-relocation-host-runtime';
 export * from './runtime/admission';
 export * from './runtime/activation-admission';
 export * from './runtime/streams';
@@ -17,9 +22,13 @@ export * from './runtime/locations/canonical-codec';
 export { ZLinkLocationAutoConnectType, ZLinkLocationKind, ZLinkRouteKind } from './contracts/Locations/Values';
 export { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from './contracts/Locations/Writes';
 export * from './runtime/channels';
+export { ZLinkChannelRuntimeLifecycle } from './runtime/channels/channel-runtime-lifecycle';
+export { ZLinkChannelSocketRegistry } from './runtime/channels/channel-socket-registry';
+export { ZLinkChannelDispatchPipeline } from './runtime/channels/channel-dispatch-pipeline';
 export * from './runtime/backend';
 export * from './runtime/codecs';
 export * from './runtime/execution';
+export { ZLinkSerialExecutionQueue } from './runtime/execution/serial-execution-queue';
 export * from './runtime/handlers';
 export * from './runtime/messaging';
 export * from './runtime/foundation';

package/dist/internal.js

@@ -14,13 +14,27 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.requirePublicWeight = exports.isValidCapacity = exports.isValidListenerPort = exports.isValidPositiveCapacity = exports.isValidPublicWeight = exports.ZLINK_MAX_CAPACITY = exports.ZLINK_MAX_PUBLIC_WEIGHT = exports.MAX_LISTENER_PORT = exports.ZLINK_MAX_STABLE_TYPE_BYTES = exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = exports.ZLinkLocationWriteStatus = exports.ZLinkLocationWriteIntent = exports.ZLinkRouteKind = exports.ZLinkLocationKind = exports.ZLinkLocationAutoConnectType = exports.requireValidSendTimeoutMs = void 0;
+exports.requirePublicWeight = exports.isValidCapacity = exports.isValidListenerPort = exports.isValidPositiveCapacity = exports.isValidPublicWeight = exports.ZLINK_MAX_CAPACITY = exports.ZLINK_MAX_PUBLIC_WEIGHT = exports.MAX_LISTENER_PORT = exports.ZLINK_MAX_STABLE_TYPE_BYTES = exports.ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = exports.ZLinkSerialExecutionQueue = exports.ZLinkChannelDispatchPipeline = exports.ZLinkChannelSocketRegistry = exports.ZLinkChannelRuntimeLifecycle = exports.ZLinkLocationWriteStatus = exports.ZLinkLocationWriteIntent = exports.ZLinkRouteKind = exports.ZLinkLocationKind = exports.ZLinkLocationAutoConnectType = exports.ZLinkHostServiceRelocationRuntime = exports.relocationFailedFailureCode = exports.ZLinkLocationRuntimeOwner = exports.resolveApplicationJobQueueConfiguration = exports.nodeEffectiveProcessorCount = exports.ApplicationJobQueuePermit = exports.ApplicationJobQueue = exports.ZLinkActorTransferRuntime = exports.ZLinkActorPlacementCoordinator = exports.requireValidSendTimeoutMs = void 0;
 /** Test and companion-package integration surface. It is not exported by package.json. */
 __exportStar(require("./index"), exports);
 var SendTimeoutValidation_1 = require("./contracts/Configuration/SendTimeoutValidation");
 Object.defineProperty(exports, "requireValidSendTimeoutMs", { enumerable: true, get: function () { return SendTimeoutValidation_1.requireValidSendTimeoutMs; } });
 __exportStar(require("./runtime/diagnostics"), exports);
 __exportStar(require("./runtime/host"), exports);
+var actor_placement_coordinator_1 = require("./runtime/host/actor-placement-coordinator");
+Object.defineProperty(exports, "ZLinkActorPlacementCoordinator", { enumerable: true, get: function () { return actor_placement_coordinator_1.ZLinkActorPlacementCoordinator; } });
+var actor_transfer_runtime_1 = require("./runtime/host/actor-transfer-runtime");
+Object.defineProperty(exports, "ZLinkActorTransferRuntime", { enumerable: true, get: function () { return actor_transfer_runtime_1.ZLinkActorTransferRuntime; } });
+var application_job_queue_1 = require("./runtime/host/application-job-queue");
+Object.defineProperty(exports, "ApplicationJobQueue", { enumerable: true, get: function () { return application_job_queue_1.ApplicationJobQueue; } });
+Object.defineProperty(exports, "ApplicationJobQueuePermit", { enumerable: true, get: function () { return application_job_queue_1.ApplicationJobQueuePermit; } });
+Object.defineProperty(exports, "nodeEffectiveProcessorCount", { enumerable: true, get: function () { return application_job_queue_1.nodeEffectiveProcessorCount; } });
+Object.defineProperty(exports, "resolveApplicationJobQueueConfiguration", { enumerable: true, get: function () { return application_job_queue_1.resolveApplicationJobQueueConfiguration; } });
+var location_runtime_owner_1 = require("./runtime/host/location-runtime-owner");
+Object.defineProperty(exports, "ZLinkLocationRuntimeOwner", { enumerable: true, get: function () { return location_runtime_owner_1.ZLinkLocationRuntimeOwner; } });
+var service_relocation_host_runtime_1 = require("./runtime/host/service-relocation-host-runtime");
+Object.defineProperty(exports, "relocationFailedFailureCode", { enumerable: true, get: function () { return service_relocation_host_runtime_1.relocationFailedFailureCode; } });
+Object.defineProperty(exports, "ZLinkHostServiceRelocationRuntime", { enumerable: true, get: function () { return service_relocation_host_runtime_1.ZLinkHostServiceRelocationRuntime; } });
 __exportStar(require("./runtime/admission"), exports);
 __exportStar(require("./runtime/activation-admission"), exports);
 __exportStar(require("./runtime/streams"), exports);
@@ -40,9 +54,17 @@ var Writes_1 = require("./contracts/Locations/Writes");
 Object.defineProperty(exports, "ZLinkLocationWriteIntent", { enumerable: true, get: function () { return Writes_1.ZLinkLocationWriteIntent; } });
 Object.defineProperty(exports, "ZLinkLocationWriteStatus", { enumerable: true, get: function () { return Writes_1.ZLinkLocationWriteStatus; } });
 __exportStar(require("./runtime/channels"), exports);
+var channel_runtime_lifecycle_1 = require("./runtime/channels/channel-runtime-lifecycle");
+Object.defineProperty(exports, "ZLinkChannelRuntimeLifecycle", { enumerable: true, get: function () { return channel_runtime_lifecycle_1.ZLinkChannelRuntimeLifecycle; } });
+var channel_socket_registry_1 = require("./runtime/channels/channel-socket-registry");
+Object.defineProperty(exports, "ZLinkChannelSocketRegistry", { enumerable: true, get: function () { return channel_socket_registry_1.ZLinkChannelSocketRegistry; } });
+var channel_dispatch_pipeline_1 = require("./runtime/channels/channel-dispatch-pipeline");
+Object.defineProperty(exports, "ZLinkChannelDispatchPipeline", { enumerable: true, get: function () { return channel_dispatch_pipeline_1.ZLinkChannelDispatchPipeline; } });
 __exportStar(require("./runtime/backend"), exports);
 __exportStar(require("./runtime/codecs"), exports);
 __exportStar(require("./runtime/execution"), exports);
+var serial_execution_queue_1 = require("./runtime/execution/serial-execution-queue");
+Object.defineProperty(exports, "ZLinkSerialExecutionQueue", { enumerable: true, get: function () { return serial_execution_queue_1.ZLinkSerialExecutionQueue; } });
 __exportStar(require("./runtime/handlers"), exports);
 __exportStar(require("./runtime/messaging"), exports);
 __exportStar(require("./runtime/foundation"), exports);

package/dist/runtime/actors/actor-client.d.ts

@@ -30,7 +30,7 @@ export declare class DefaultZLinkActorClient implements ZLinkActorClient {
     private send;
     private request;
     private resolveActorRoute;
-    private invalidateActorRoute;
+    private mapActorFailure;
     private throwIfKnownStale;
     private createPacketParts;
     private submitActorSend;

package/dist/runtime/actors/actor-client.js

@@ -42,10 +42,12 @@ class DefaultZLinkActorClient {
     async send(actorId, explicitPacketName, message, metadata) {
         const route = await this.resolveActorRoute(actorId);
         const { meshName, actorRef: actor } = route;
-        this.throwIfKnownStale(meshName, actor);
+        this.throwIfKnownStale(route);
         const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Send, undefined, explicitPacketName, message, metadata);
+        let routeFence;
         try {
             const messageFollow = createActorMessageFollowContext(route, parts, false);
+            routeFence = actorRouteInvalidationFence(route);
             const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
             const submissionCopies = (await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'oneWay')) ?? 1;
             const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, false, routedActor);
@@ -76,12 +78,7 @@ class DefaultZLinkActorClient {
             return await this.submitActorSend(meshName, toBackendActorRef(actor), parts, route);
         }
         catch (error) {
-            if (isStaleActorError(error)) {
-                this.invalidateActorRoute(actorId);
-                this.options.staleActorRefReporter?.(meshName, actor.actorId);
-                throw actorLocationStale(actor.actorId, error);
-            }
-            throw error;
+            throw this.mapActorFailure(actorId, error, routeFence, meshName);
         }
         finally {
             closeMessages(parts);
@@ -92,6 +89,7 @@ class DefaultZLinkActorClient {
         const sourceSpotId = (0, actor_execution_context_1.currentZLinkActorExecution)()?.spotId ?? (0, execution_1.currentZLinkSpotSerialSourceId)();
         const effectiveTimeoutMs = timeoutMs ?? this.options.defaultRequestTimeoutMs;
         let meshName;
+        let routeFence;
         return this.requests.prepare(effectiveTimeoutMs, signal, (requestOperation, receiver) => {
             void (async () => {
                 const deadlineMs = requestOperation.deadlineMs;
@@ -106,14 +104,17 @@ class DefaultZLinkActorClient {
                 }
                 const { actorRef: actor } = route;
                 meshName = route.meshName;
-                if (this.options.staleActorRefPredicate?.(meshName, actor) === true)
+                if (this.options.staleActorRefPredicate?.(meshName, actor) === true) {
+                    routeFence = actorRouteInvalidationFence(route);
                     throw actorLocationStale(actor.actorId, undefined);
+                }
                 const operationId = (0, actor_message_follow_context_1.createMessageFollowId)();
                 const correlationId = (0, actor_message_follow_context_1.createMessageFollowId)();
                 const requestSequence = BigInt(`0x${operationId.slice(16)}`);
                 const parts = this.createPacketParts(protocol_1.ZLinkStreamMessageKind.Request, requestSequence === 0n ? 1n : requestSequence, explicitPacketName, request, mergeActorRequestMetadata(metadata, deadlineUnixMs), correlationId);
                 try {
                     const messageFollow = createActorMessageFollowContext(route, parts, true, deadlineUnixMs, correlationId, operationId);
+                    routeFence = actorRouteInvalidationFence(route);
                     const routedActor = (0, actor_message_follow_context_1.attachActorMessageFollowContext)(actor, messageFollow);
                     const delivery = this.options
                         .transportDeliveryGate?.()
@@ -139,15 +140,7 @@ class DefaultZLinkActorClient {
                     closeMessages(parts);
                 }
             })().catch((error) => receiver.operationFailed(requestOperation.id, error, undefined));
-        }, (value) => value, (error) => {
-            if (isStaleActorError(error)) {
-                this.invalidateActorRoute(actorId);
-                if (meshName !== undefined)
-                    this.options.staleActorRefReporter?.(meshName, actorId);
-                return actorLocationStale(actorId, error);
-            }
-            return error;
-        });
+        }, (value) => value, (error) => this.mapActorFailure(actorId, error, routeFence, meshName));
     }
     async resolveActorRoute(actorId, signal, deadlineMs, requestOperation) {
         const resolver = this.options.locationResolver();
@@ -163,15 +156,21 @@ class DefaultZLinkActorClient {
         }
         return resolution.route;
     }
-    invalidateActorRoute(actorId) {
-        this.options.locationResolver()?.invalidateActorRoute(actorId);
+    mapActorFailure(actorId, error, routeFence, meshName) {
+        if (!isStaleActorError(error))
+            return error;
+        const resolver = this.options.locationResolver();
+        if (routeFence !== undefined && resolver !== undefined)
+            resolver.invalidateActorRouteIfMatches(routeFence);
+        if (meshName !== undefined)
+            this.options.staleActorRefReporter?.(meshName, actorId);
+        return actorLocationStale(actorId, error);
     }
-    throwIfKnownStale(meshName, actor) {
+    throwIfKnownStale(route) {
+        const { meshName, actorRef: actor } = route;
         if (this.options.staleActorRefPredicate?.(meshName, actor) !== true)
             return;
-        this.invalidateActorRoute(actor.actorId);
-        this.options.staleActorRefReporter?.(meshName, actor.actorId);
-        throw actorLocationStale(actor.actorId, undefined);
+        throw this.mapActorFailure(actor.actorId, actorLocationStale(actor.actorId, undefined), actorRouteInvalidationFence(route), meshName);
     }
     createPacketParts(kind, requestSeq, explicitPacketName, message, metadata, correlationId) {
         const packetName = (0, packet_name_1.resolveFrameworkPacketName)(message, explicitPacketName, 'Actor');
@@ -301,6 +300,16 @@ function nativeActorRouteFence(route, actor) {
         ownerLeaseGeneration: route.ownerLeaseGeneration
     };
 }
+function actorRouteInvalidationFence(route) {
+    return {
+        actorId: route.actorRef.actorId,
+        objectGeneration: route.actorRef.objectGeneration,
+        targetNodeRid: route.actorRef.nodeRid,
+        targetNodeGeneration: route.ownerNodeGeneration,
+        authorityOwnerGeneration: route.authorityOwnerGeneration,
+        ownerLeaseGeneration: route.ownerLeaseGeneration
+    };
+}
 function remoteActorRouteTarget(route) {
     if (route.enclosingSpotRoute !== undefined) {
         return route.enclosingSpotRoute;

package/dist/runtime/actors/actor-context.js

@@ -59,7 +59,7 @@ class DefaultZLinkActorContext {
         return this.state.boundSession;
     }
     get objectGeneration() {
-        return this.state.nativeActorRef?.generation ?? 1n;
+        return this.state.currentActorRef().generation;
     }
     get spotId() {
         return this.state.spotId;

package/dist/runtime/actors/actor-creation.js

@@ -116,7 +116,7 @@ class ZLinkActorCreationCoordinator {
                 }
             }
             else if (nodeRid !== undefined && updateLocation) {
-                await this.options.locationLifecycle?.setActorRef(actorType, actorId, { actorId, objectGeneration: 1n, meshName, nodeRid }, 0n);
+                await this.options.locationLifecycle?.setActorRef(actorType, actorId, (0, actor_runtime_state_1.toFrameworkActorRef)(state.currentActorRef(), meshName), 0n);
             }
             return { status: 'created', actor, reply: response.reply };
         }

package/dist/runtime/actors/actor-mailbox.d.ts

@@ -2,7 +2,7 @@ import { ZLinkSerialExecutionQueue, type ZLinkSerialSchedulerOptions, type ZLink
 export declare class ZLinkActorSerialExecutor {
     private readonly actorId;
     private readonly sourceSpotId;
-    private readonly scheduler;
+    readonly scheduler: ZLinkSerialExecutionQueue;
     constructor(actorId: string, sourceSpotId: unknown, options?: ZLinkSerialSchedulerOptions, sharedOwner?: ZLinkSerialExecutionQueue);
     execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
     close(): Promise<void>;

package/dist/runtime/actors/actor-runtime-state.d.ts

@@ -76,8 +76,9 @@ export declare class ZLinkActorRuntimeState {
     private spotGenerationValue;
     private spotMembershipEpochValue;
     private nativeActorRefValue;
+    private nativeActorDestroyed;
     private entryNodeRidValue;
-    private boundSessionValue;
+    boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
     private remoteActorPacketTargetValue;
     private createRequestPayloadValue;
     private ownsLocationValue;
@@ -96,6 +97,7 @@ export declare class ZLinkActorRuntimeState {
     get spotMembershipEpoch(): bigint;
     get spotGeneration(): bigint | undefined;
     get nativeActorRef(): ZLinkBackendActorRef | undefined;
+    currentActorRef(): ZLinkBackendActorRef;
     get boundSessionBindingGeneration(): bigint;
     get entryNodeRid(): RoutingId | undefined;
     /** The one current Session binding of this Actor (Session–Actor binding §6). */
@@ -124,7 +126,6 @@ export declare class ZLinkActorRuntimeState {
     setOwnerLeaseGeneration(generation: bigint): void;
     getOrStartDestroy(entryNodeRid: RoutingId, destroy: (actorRef: ZLinkBackendActorRef | undefined) => Promise<void>): Promise<void>;
     markNativeActorDestroyed(actorRef: ZLinkBackendActorRef): void;
-    clearFailedDestroy(task: Promise<void>): void;
     ensureContext(createContext: () => ZLinkActorContext): ZLinkActorContext;
     getOrStartCreation(actorType: string, failIfExists: boolean, createActor: () => Promise<ZLinkActorCreationAttemptResult>): ZLinkActorCreationOperation;
     clearFailedCreation(task: Promise<ZLinkActorCreationAttemptResult>): boolean;

package/dist/runtime/actors/actor-runtime-state.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorRuntimeState = void 0;
 exports.toFrameworkRoutingId = toFrameworkRoutingId;
 exports.toFrameworkActorRef = toFrameworkActorRef;
+const configuration_1 = require("../configuration");
 const state_lane_1 = require("../execution/state-lane");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const routing_id_1 = require("../routing-id");
@@ -57,7 +58,9 @@ class ZLinkActorRuntimeState {
     spotIdValue;
     spotGenerationValue;
     spotMembershipEpochValue = 0n;
+    // Preserve the exact incarnation until teardown finalization, even after native removal.
     nativeActorRefValue;
+    nativeActorDestroyed = false;
     entryNodeRidValue;
     boundSessionValue;
     remoteActorPacketTargetValue;
@@ -103,6 +106,12 @@ class ZLinkActorRuntimeState {
     get nativeActorRef() {
         return this.nativeActorRefValue;
     }
+    currentActorRef() {
+        if (this.nativeActorRefValue === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${this.actorId}' lifecycle identity is not initialized.`);
+        }
+        return this.nativeActorRefValue;
+    }
     get boundSessionBindingGeneration() {
         return this.boundSessionValue?.bindingGeneration ?? 0n;
     }
@@ -194,20 +203,23 @@ class ZLinkActorRuntimeState {
             !(0, routing_id_1.routingIdsEqual)(toFrameworkRoutingId(actorRef.nodeRid), entryNodeRid)) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${this.actorId}' is not owned by this Entry Spot.`);
         }
-        const task = Promise.resolve().then(() => destroy(actorRef));
+        const task = Promise.resolve()
+            .then(() => destroy(this.nativeActorDestroyed ? undefined : actorRef))
+            .catch((error) => {
+            // A caller may start another attempt only after this attempt has failed.
+            if (this.destroyTask === task) {
+                this.destroyTask = undefined;
+                this.movingValue = false;
+            }
+            throw error;
+        });
         this.destroyTask = task;
         return task;
     }
     markNativeActorDestroyed(actorRef) {
         if (this.nativeActorRefValue === actorRef) {
-            this.nativeActorRefValue = undefined;
-        }
-    }
-    clearFailedDestroy(task) {
-        if (this.destroyTask === task) {
-            this.destroyTask = undefined;
+            this.nativeActorDestroyed = true;
         }
-        this.movingValue = false;
     }
     ensureContext(createContext) {
         this.context ??= createContext();
@@ -243,6 +255,7 @@ class ZLinkActorRuntimeState {
             this.createRequestPayloadValue = undefined;
             this.configured = false;
             this.nativeActorRefValue = undefined;
+            this.nativeActorDestroyed = false;
             this.entryNodeRidValue = undefined;
             return true;
         }
@@ -278,6 +291,7 @@ class ZLinkActorRuntimeState {
     }
     setNativeActorRef(actorRef) {
         this.nativeActorRefValue = actorRef;
+        this.nativeActorDestroyed = false;
         this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
     }
     /** @internal Installs one authority-confirmed binding inside its Actor owner turn. */
@@ -344,6 +358,7 @@ class ZLinkActorRuntimeState {
         this.spotGenerationValue = undefined;
         this.spotMembershipEpochValue = 0n;
         this.nativeActorRefValue = undefined;
+        this.nativeActorDestroyed = false;
         this.entryNodeRidValue = undefined;
         this.boundSessionValue = undefined;
         this.remoteActorPacketTargetValue = undefined;
@@ -366,6 +381,7 @@ class ZLinkActorRuntimeState {
         this.spotValue = undefined;
         this.spotIdValue = undefined;
         this.nativeActorRefValue = undefined;
+        this.nativeActorDestroyed = false;
         // The arriving relocation installs the binding it carries.
         this.boundSessionValue = undefined;
         this.remoteActorPacketTargetValue = undefined;

package/dist/runtime/actors/index.d.ts

@@ -64,7 +64,7 @@ export declare class DefaultZLinkActorManager implements ZLinkActorManager {
     private awaitActorDestroy;
     getOrCreateActor(actorId: string, actorType: string, signal?: AbortSignal): Promise<ZLinkActor>;
     getOrCreateWithNativeRef(actorId: string, actorType: string, actorRef: ZLinkBackendActorRef, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActor>;
-    getOrCreateActorResult(actorId: string, actorType: string, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActorLocalCreateResult>;
+    getOrCreateActorResult(actorId: string, actorType: string, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>>;
     createReservedActorResult(actorId: string, actorType: string, createRequest: unknown, signal?: AbortSignal, nativeActorRef?: ZLinkBackendActorRef): Promise<ZLinkActorLocalCreateResult>;
     adoptCreatedAuthority(actorId: string, authorityOwnerGeneration: bigint, ownerLeaseGeneration: bigint): void;
     getState(actorId: string): ZLinkActorRuntimeState | undefined;
@@ -77,10 +77,10 @@ export declare class DefaultZLinkActorManager implements ZLinkActorManager {
     private getOrCreateState;
     private actorRefForState;
 }
-export type ZLinkActorLocalCreateResult = {
+export type ZLinkActorLocalCreateResult<TActorRef extends ActorRef | undefined = ActorRef> = {
     readonly status: 'existing' | 'created';
     readonly actor: ZLinkActor;
-    readonly actorRef: ActorRef;
+    readonly actorRef: TActorRef;
     readonly reply?: unknown;
 } | {
     readonly status: 'rejected';

package/dist/runtime/actors/index.js

@@ -17,7 +17,6 @@ const actor_creation_1 = require("./actor-creation");
 const actor_runtime_state_1 = require("./actor-runtime-state");
 const transferred_actor_rollback_1 = require("./transferred-actor-rollback");
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
-const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 var actor_client_1 = require("./actor-client");
 Object.defineProperty(exports, "DefaultZLinkActorClient", { enumerable: true, get: function () { return actor_client_1.DefaultZLinkActorClient; } });
 var actor_context_1 = require("./actor-context");
@@ -100,7 +99,7 @@ class DefaultZLinkActorManager {
         if (this.relocationStaged.has(actorId))
             return undefined;
         const state = this.states.get(actorId);
-        if (state?.actor !== undefined) {
+        if (state?.actor !== undefined && state.nativeActorRef !== undefined) {
             return this.actorRefForState(state);
         }
         return await this.options.actorRefResolver?.resolveActorRef(actorId, signal);
@@ -111,7 +110,9 @@ class DefaultZLinkActorManager {
     async findSpot(actorId, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const state = this.states.get(actorId);
-        if (state?.actor === undefined || state.spotId === undefined)
+        if (state?.actor === undefined ||
+            state.spotId === undefined ||
+            state.nativeActorRef === undefined)
             return undefined;
         const spotId = state.spotId;
         const actorRef = this.actorRefForState(state);
@@ -162,13 +163,7 @@ class DefaultZLinkActorManager {
             }
             await this.finalizeDestroyedActor(actor.actorId, state);
         }));
-        try {
-            await this.awaitActorDestroy(state, destroyTask);
-        }
-        catch (error) {
-            state.clearFailedDestroy(destroyTask);
-            throw error;
-        }
+        await this.awaitActorDestroy(state, destroyTask);
         return true;
     }
     async materializeTransferredActor(actorId, actorType, adapterKey, transferState, signal) {
@@ -235,9 +230,10 @@ class DefaultZLinkActorManager {
         if (result.status === 'failed') {
             throw actorApplicationFailure(actorId, result.error);
         }
+        const actorRef = result.actorRef ?? this.actorRefForState(this.states.get(actorId));
         return result.reply === undefined
-            ? { status: result.status, actor: result.actorRef }
-            : { status: result.status, actor: result.actorRef, reply: result.reply };
+            ? { status: result.status, actor: actorRef }
+            : { status: result.status, actor: actorRef, reply: result.reply };
     }
     ensureActorTypeBelongsToMesh(meshName, actorType) {
         const registeredMesh = this.options.actorMeshNameProvider?.(actorType);
@@ -442,7 +438,13 @@ class DefaultZLinkActorManager {
     }
     async createReservedActorResult(actorId, actorType, createRequest, signal, nativeActorRef) {
         this.rememberActorMeshFromType(actorId, actorType);
-        return await this.createOrGet(actorId, actorType, false, createRequest, signal, false, Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef);
+        const result = await this.createOrGet(actorId, actorType, false, createRequest, signal, false, Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef);
+        if (result.status === 'failed' || result.status === 'rejected')
+            return result;
+        return {
+            ...result,
+            actorRef: this.actorRefForState(this.states.get(actorId))
+        };
     }
     adoptCreatedAuthority(actorId, authorityOwnerGeneration, ownerLeaseGeneration) {
         const state = this.states.get(actorId);
@@ -473,7 +475,7 @@ class DefaultZLinkActorManager {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.context.actorId}' must leave its current SPOT before destroy.`);
         }
         const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) => this.terminateActor(state, async () => {
-            const destroyedActorRef = actorRef === undefined ? undefined : (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, state.meshName ?? '');
+            const destroyedActorRef = state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
             if (actorRef !== undefined) {
                 await node.destroyActor(actorRef, 0, destroySignal);
                 state.markNativeActorDestroyed(actorRef);
@@ -483,13 +485,7 @@ class DefaultZLinkActorManager {
             }
             await this.finalizeDestroyedActor(actor.context.actorId, state);
         }));
-        try {
-            await this.awaitActorDestroy(state, destroyTask);
-        }
-        catch (error) {
-            state.clearFailedDestroy(destroyTask);
-            throw error;
-        }
+        await this.awaitActorDestroy(state, destroyTask);
     }
     async createOrGet(actorId, actorType, failIfExists, request, signal, claimLocation = true, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef) {
         const deadline = performance.now() + timeoutMs;
@@ -533,7 +529,7 @@ class DefaultZLinkActorManager {
             try {
                 const result = await operation.task;
                 if (result.status === 'created') {
-                    const actorRef = this.actorRefForState(state);
+                    const actorRef = state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
                     return {
                         status: operation.created ? 'created' : 'existing',
                         actor: result.actor,
@@ -602,16 +598,7 @@ class DefaultZLinkActorManager {
         return state;
     }
     actorRefForState(state) {
-        const nativeActorRef = state.nativeActorRef;
-        if (nativeActorRef !== undefined) {
-            return (0, actor_runtime_state_1.toFrameworkActorRef)(nativeActorRef, state.meshName ?? '');
-        }
-        return {
-            actorId: state.actorId,
-            objectGeneration: 1n,
-            meshName: state.meshName ?? '',
-            nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
-        };
+        return (0, actor_runtime_state_1.toFrameworkActorRef)(state.currentActorRef(), state.meshName ?? '');
     }
 }
 exports.DefaultZLinkActorManager = DefaultZLinkActorManager;

package/dist/runtime/actors/spot-actor-dispatch.d.ts

@@ -54,8 +54,10 @@ export declare class ZLinkSpotActorDispatcher {
     notifyDisconnectActor(actor: ZLinkActor): Promise<void>;
     private requirePacket;
     private ensureActorType;
-    private invokeHandler;
+    invokeHandler<THandler, TResult>(actor: ZLinkActor, descriptor: Pick<ZLinkActorPacketDescriptor, 'handlerType' | 'methodName'>, callback: (handler: THandler, method: THandler extends {
+        handle: infer TMethod;
+    } ? TMethod : never) => Promise<TResult>): Promise<TResult>;
     private execute;
-    private createContext;
+    createContext(packetName: string, context: Partial<ZLinkMessageContext> | undefined): ZLinkMessageContext;
 }
 export {};

package/dist/runtime/actors/spot-actor-dispatch.js

@@ -205,7 +205,8 @@ class ZLinkSpotActorDispatcher {
             packetName,
             contentType: context?.contentType,
             metadata: context?.metadata ?? contracts_1.ZLinkMessageMetadataEmpty,
-            correlationId: context?.correlationId
+            correlationId: context?.correlationId,
+            receivedAt: context?.receivedAt ?? new Date()
         };
     }
 }

package/dist/runtime/application-jobs/application-ingress-record-owner.d.ts

@@ -29,6 +29,7 @@ export declare class ApplicationJobRecordLease implements ApplicationJobPermitPo
     private processingTerminal;
     detachedForHandlerTurn: boolean;
     constructor(shared: SharedIngressRecordState, permit: ApplicationJobPermitPort | undefined);
+    reacquire(signal: AbortSignal): Promise<ApplicationJobPermitPort>;
     get origin(): ApplicationJobOrigin;
     markApplicationQueued(): void;
     detachForHandlerTurn(): void;

package/dist/runtime/application-jobs/application-ingress-record-owner.js

@@ -84,6 +84,9 @@ class ApplicationJobRecordLease {
         this.shared = shared;
         this.permit = permit;
     }
+    reacquire(signal) {
+        return this.shared.acquirePermit(signal);
+    }
     get origin() {
         return this.shared.origin;
     }

package/dist/runtime/backend/contracts/index.d.ts

@@ -472,6 +472,8 @@ export interface ZLinkMeshBackendAdapter {
     createMeshNode(context: ZLinkBackendContext, options: {
         readonly meshName: string;
         readonly routingId?: RoutingId;
+        readonly sendHighWaterMark?: number;
+        readonly receiveHighWaterMark?: number;
         readonly receiveTimeoutMs?: number;
         readonly trustProfile?: string;
         readonly applicationJobQueue: import('../../application-jobs/contracts').ApplicationJobQueuePort;