@zlink-systems/framework 0.25.0 → 0.26.0

package/dist/contracts/Channels/IZLinkFanoutClient.d.ts

@@ -1,11 +1,5 @@
 import type { ZLinkFanoutPublishCall } from './Calls';
-export interface ZLinkFanoutListenerStatus {
-    readonly channelName: string;
-    readonly endpoint: string;
-    readonly observedAt: Date;
-}
 export interface ZLinkFanoutClient {
     publish(channelName: string, event: unknown): ZLinkFanoutPublishCall;
     publish(channelName: string, topic: string, event: unknown): ZLinkFanoutPublishCall;
-    getListenerStatus(channelName: string): ZLinkFanoutListenerStatus;
 }

package/dist/contracts/RouteMesh/RuntimeTopology.d.ts

@@ -123,11 +123,19 @@ export interface ZLinkHostCapacityStatus {
 }
 export interface ZLinkFrameworkRuntime {
     readonly status: ZLinkFrameworkRuntimeStatus;
+    getListenerStatus(kind: ZLinkListenerKind, name: string): ZLinkListenerStatus;
     observe(signal?: AbortSignal): AsyncIterable<ZLinkObservedStatus<ZLinkFrameworkRuntimeStatus>>;
     resetCapacityMetrics(): void;
     relocate(options: ZLinkFrameworkRelocationOptions): Promise<ZLinkFrameworkRelocationResult>;
     shutdown(options?: ZLinkFrameworkLifecycleOptions): Promise<ZLinkFrameworkTerminationResult>;
 }
+export type ZLinkListenerKind = 'routeMesh' | 'clientServer' | 'fanout' | 'stream';
+export interface ZLinkListenerStatus {
+    readonly kind: ZLinkListenerKind;
+    readonly name: string;
+    readonly endpoint: string;
+    readonly observedAt: Date;
+}
 export type ZLinkClientServerRole = 'client' | 'server' | 'clientAndServer';
 export interface ZLinkClientServerTargetStatus {
     readonly nodeRid: RoutingId;

package/dist/internal.d.ts

@@ -3,6 +3,7 @@ export * from './index';
 export * from './runtime/diagnostics';
 export * from './runtime/host';
 export * from './runtime/admission';
+export * from './runtime/activation-admission';
 export * from './runtime/streams';
 export * from './runtime/streams/protocol';
 export * from './runtime/actors';

package/dist/internal.js

@@ -20,6 +20,7 @@ __exportStar(require("./index"), exports);
 __exportStar(require("./runtime/diagnostics"), exports);
 __exportStar(require("./runtime/host"), exports);
 __exportStar(require("./runtime/admission"), exports);
+__exportStar(require("./runtime/activation-admission"), exports);
 __exportStar(require("./runtime/streams"), exports);
 __exportStar(require("./runtime/streams/protocol"), exports);
 __exportStar(require("./runtime/actors"), exports);

package/dist/runtime/activation-admission.d.ts

@@ -0,0 +1,29 @@
+/** Current activation admission count and limit of one MeshNode. */
+export interface ZLinkActivationConcurrency {
+    readonly active: number;
+    readonly limit: number;
+}
+/**
+ * MeshNode §5.1 "Pending activation": the single per-MeshNode record of activation admissions.
+ *
+ * Actor creation, User Spot creation, Instance Spot cold activation and a relocation target's
+ * Restore each hold one admission from the moment the target MeshNode receives the operation
+ * until Ready or its target commit, or until it ends by rejection, failure or cleanup. Entry Spot
+ * and Actor Join never acquire one. The limit is enforced here, and the status current value and
+ * the placement `IsAvailable` headroom both read this record.
+ */
+export declare class ZLinkActivationAdmission {
+    private readonly limitOf;
+    private readonly changed?;
+    private readonly records;
+    constructor(limitOf: (meshName: string) => number, changed?: ((meshName: string) => void) | undefined);
+    current(meshName: string): ZLinkActivationConcurrency;
+    hasHeadroom(meshName: string): boolean;
+    /**
+     * Holds one admission for `meshName`. A MeshNode without headroom does not accept a new
+     * admission (MeshNode §5.1): the operation fails as Unavailable at once. The returned release
+     * is idempotent.
+     */
+    acquire(meshName: string, signal?: AbortSignal): Promise<() => void>;
+    private record;
+}

package/dist/runtime/activation-admission.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActivationAdmission = void 0;
+const framework_errors_internal_1 = require("./framework-errors-internal");
+/**
+ * MeshNode §5.1 "Pending activation": the single per-MeshNode record of activation admissions.
+ *
+ * Actor creation, User Spot creation, Instance Spot cold activation and a relocation target's
+ * Restore each hold one admission from the moment the target MeshNode receives the operation
+ * until Ready or its target commit, or until it ends by rejection, failure or cleanup. Entry Spot
+ * and Actor Join never acquire one. The limit is enforced here, and the status current value and
+ * the placement `IsAvailable` headroom both read this record.
+ */
+class ZLinkActivationAdmission {
+    limitOf;
+    changed;
+    records = new Map();
+    constructor(limitOf, changed) {
+        this.limitOf = limitOf;
+        this.changed = changed;
+    }
+    current(meshName) {
+        const record = this.records.get(meshName);
+        return { active: record?.active ?? 0, limit: record?.limit ?? this.limitOf(meshName) };
+    }
+    hasHeadroom(meshName) {
+        const { active, limit } = this.current(meshName);
+        return active < limit;
+    }
+    /**
+     * Holds one admission for `meshName`. A MeshNode without headroom does not accept a new
+     * admission (MeshNode §5.1): the operation fails as Unavailable at once. The returned release
+     * is idempotent.
+     */
+    async acquire(meshName, signal) {
+        signal?.throwIfAborted();
+        const record = this.record(meshName);
+        if (record.active >= record.limit) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `MeshNode '${meshName}' has no activation admission headroom.`);
+        }
+        record.active += 1;
+        this.changed?.(meshName);
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            record.active -= 1;
+            this.changed?.(meshName);
+        };
+    }
+    record(meshName) {
+        let record = this.records.get(meshName);
+        if (record === undefined) {
+            record = { meshName, limit: this.limitOf(meshName), active: 0 };
+            this.records.set(meshName, record);
+        }
+        return record;
+    }
+}
+exports.ZLinkActivationAdmission = ZLinkActivationAdmission;

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

@@ -146,7 +146,7 @@ class DefaultZLinkActorJoinSpotCall {
             discarded = true;
             this.state.endDeferredJoin();
             try {
-                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state);
             }
             finally {
                 deadline.close();
@@ -164,7 +164,7 @@ class DefaultZLinkActorJoinSpotCall {
                         // The provisional ingress fence is installed only after the
                         // handler terminal. Target admission starts before reply encoding,
                         // while completion and finalization remain in execute().
-                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state);
                         pendingJoin = this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
@@ -189,7 +189,7 @@ class DefaultZLinkActorJoinSpotCall {
                     catch (error) {
                         this.state.endDeferredJoin();
                         await this.coordinator
-                            .abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .abortDeferredJoin?.(this.actor, this.state)
                             .catch(() => undefined);
                         await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
                         return;
@@ -271,7 +271,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
             discarded = true;
             this.state.endDeferredJoin();
             try {
-                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state);
             }
             finally {
                 deadline.close();
@@ -286,7 +286,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     prepared = true;
                     this.state.endDeferredJoin();
                     try {
-                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state);
                         pendingJoin = this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
                         if (this.turn === undefined) {
                             await pendingJoin.catch(() => undefined);
@@ -311,7 +311,7 @@ class DefaultZLinkActorJoinEntrySpotCall {
                     catch (error) {
                         this.state.endDeferredJoin();
                         await this.coordinator
-                            .abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .abortDeferredJoin?.(this.actor, this.state)
                             .catch(() => undefined);
                         await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
                         return;

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

@@ -115,14 +115,14 @@ export declare class ZLinkActorHandoffCoordinator {
     private readonly replyRoutes;
     constructor(options: ZLinkActorHandoffCoordinatorOptions);
     begin(actorId: string, oldGeneration: bigint): void;
-    beginProvisional(actorId: string, operationId: string, oldGeneration: bigint): void;
+    beginProvisional(actorId: string, oldGeneration: bigint): void;
     private startHandoff;
     isActive(actorId: string): boolean;
     isProvisional(actorId: string): boolean;
-    promoteProvisional(actorId: string, operationId: string): void;
+    promoteProvisional(actorId: string): void;
     sealConnectionBoundIngress(actorId: string): void;
     activeSourceOwner(actorId: string): ZLinkActorMessageFollowOwnerFence | undefined;
-    releaseDeferred(actorId: string, operationId: string, dispatch?: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
+    releaseDeferred(actorId: string, dispatch?: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
     releaseCanceled(actorId: string, dispatch: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
     private admitHandoffPrefix;
     private admitPendingPrefix;
@@ -134,6 +134,12 @@ export declare class ZLinkActorHandoffCoordinator {
     private replayReleasedBacklog;
     private replayReleasedPending;
     private failReleasedPending;
+    /**
+     * Expired-owner terminal of a relocation (spec 28 §4.4): every pending
+     * record without a terminal fails once with `reason`. The handoff stays
+     * active, so the source never dispatches the Actor again.
+     */
+    failPending(actorId: string, reason: unknown): void;
     cancel(actorId: string): void;
     capture(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch): Promise<unknown> | undefined;
     snapshot(actorId: string): readonly ZLinkActorHandoffPacket[];

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

@@ -50,12 +50,12 @@ class ZLinkActorHandoffCoordinator {
             options.messageFollowDurationMs ?? exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS;
     }
     begin(actorId, oldGeneration) {
-        this.startHandoff(actorId, oldGeneration, { phase: 'relocating' });
+        this.startHandoff(actorId, oldGeneration, 'relocating');
     }
-    beginProvisional(actorId, operationId, oldGeneration) {
-        this.startHandoff(actorId, oldGeneration, { phase: 'provisional', operationId });
+    beginProvisional(actorId, oldGeneration) {
+        this.startHandoff(actorId, oldGeneration, 'provisional');
     }
-    startHandoff(actorId, oldGeneration, transition) {
+    startHandoff(actorId, oldGeneration, phase) {
         if (this.active.has(actorId)) {
             throw new Error(`Actor '${actorId}' already has an active packet handoff.`);
         }
@@ -98,8 +98,8 @@ class ZLinkActorHandoffCoordinator {
             oldNodeRidHex: sourceEvidence.nodeRidHex,
             sourceEvidence,
             sourceOwner,
-            phase: transition.phase,
-            ...(transition.phase === 'provisional' ? { operationId: transition.operationId } : {}),
+            phase,
+            deferredJoin: phase === 'provisional',
             connectionBoundSealed: false,
             pending: [],
             nextIndex: 0,
@@ -113,14 +113,11 @@ class ZLinkActorHandoffCoordinator {
     isProvisional(actorId) {
         return this.active.get(actorId)?.phase === 'provisional';
     }
-    promoteProvisional(actorId, operationId) {
+    promoteProvisional(actorId) {
         const handoff = this.active.get(actorId);
-        if (handoff === undefined) {
+        if (handoff?.phase !== 'provisional') {
             throw new Error(`Actor '${actorId}' does not have a provisional packet handoff.`);
         }
-        if (handoff.phase !== 'provisional' || handoff.operationId !== operationId) {
-            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
-        }
         handoff.phase = 'relocating';
     }
     sealConnectionBoundIngress(actorId) {
@@ -131,12 +128,12 @@ class ZLinkActorHandoffCoordinator {
     activeSourceOwner(actorId) {
         return this.active.get(actorId)?.sourceOwner;
     }
-    async releaseDeferred(actorId, operationId, dispatch, admission) {
+    async releaseDeferred(actorId, dispatch, admission) {
         const handoff = this.active.get(actorId);
         if (handoff === undefined)
             return;
-        if (handoff.operationId !== operationId) {
-            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+        if (!handoff.deferredJoin) {
+            throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
         }
         await this.releaseHandoff(actorId, handoff, dispatch ?? handoff.replay, admission);
     }
@@ -153,12 +150,12 @@ class ZLinkActorHandoffCoordinator {
      *
      * @internal
      */
-    admitDeferredPrefix(actorId, operationId, queue, preparation, start = Promise.resolve()) {
+    admitDeferredPrefix(actorId, queue, preparation, start = Promise.resolve()) {
         const handoff = this.active.get(actorId);
         if (handoff === undefined)
             return { terminal: Promise.resolve() };
-        if (handoff.operationId !== operationId) {
-            throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+        if (!handoff.deferredJoin) {
+            throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
         }
         return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
     }
@@ -396,6 +393,20 @@ class ZLinkActorHandoffCoordinator {
         }
         pending.reject?.(error);
     }
+    /**
+     * Expired-owner terminal of a relocation (spec 28 §4.4): every pending
+     * record without a terminal fails once with `reason`. The handoff stays
+     * active, so the source never dispatches the Actor again.
+     */
+    failPending(actorId, reason) {
+        const handoff = this.active.get(actorId);
+        if (handoff === undefined)
+            return;
+        for (const pending of handoff.pending.splice(0))
+            this.failReleasedPending(pending, reason);
+        handoff.snapshotIndex = -1;
+        handoff.pendingBytes = 0;
+    }
     cancel(actorId) {
         const handoff = this.active.get(actorId);
         if (handoff === undefined)

package/dist/runtime/actors/actor-local-native-join.js

@@ -193,7 +193,7 @@ class ZLinkLocalNativeActorJoin {
             //  (spec 32-framework-error-model:83-118); an OK terminal with no join
             //  control is a protocol violation.
             throw admission.terminalResult !== 0 || admission.failureErrno !== 0
-                ? remoteActorJoinFailureException(node, target, admission.terminalResult, admission.failureErrno, message)
+                ? (0, framework_errors_internal_1.wireReplyFailureException)(admission.terminalResult, admission.failureErrno, message)
                 : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, message);
         }
         if (control.joinResult !== 0) {
@@ -210,7 +210,7 @@ class ZLinkLocalNativeActorJoin {
         }
         if (admission.terminalResult !== 0 || admission.failureErrno !== 0) {
             (0, mesh_completion_table_1.closeMeshCompletion)(admission);
-            throw remoteActorJoinFailureException(node, target, admission.terminalResult, admission.failureErrno, `Actor admission failed for '${actor.context.actorId}' with result '${admission.terminalResult}' and errno '${admission.failureErrno}'.`);
+            throw (0, framework_errors_internal_1.wireReplyFailureException)(admission.terminalResult, admission.failureErrno, `Actor admission failed for '${actor.context.actorId}' with result '${admission.terminalResult}' and errno '${admission.failureErrno}'.`);
         }
         disposeParts(admission.parts.slice(1));
         if (control.canonicalHandoffId !== undefined) {
@@ -359,22 +359,6 @@ function canonicalHandoffRelocationId(handoffId) {
     return (`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}` +
         `-${hex.slice(16, 20)}-${hex.slice(20)}`);
 }
-function remoteActorJoinFailureException(node, target, terminalResult, failureErrno, message) {
-    const failure = (0, framework_errors_internal_1.wireReplyFailureException)(terminalResult, failureErrno, message);
-    const targetGeneration = target.targetNodeGeneration;
-    if (failure.kind === contracts_1.ZLinkFrameworkErrorKind.DeadlineExceeded &&
-        targetGeneration !== undefined &&
-        targetGeneration !== 0n &&
-        !node
-            .peers()
-            .some((peer) => peer.state === 3 &&
-            peer.routingId !== null &&
-            (0, routing_id_2.routingIdsEqual)(peer.routingId, target.targetNodeRid) &&
-            peer.lifecycleGeneration === targetGeneration)) {
-        return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, 'wire Actor join target RouteMesh peer became unavailable');
-    }
-    return failure;
-}
 function runtimeActorMeshName(actor, state, fallback) {
     const context = actor.context;
     const stateMeshName = state?.meshName;

package/dist/runtime/actors/actor-remote-joiner.d.ts

@@ -28,8 +28,8 @@ export declare class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCo
     private readonly localJoin;
     messageFlow(): import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
     constructor(options: ZLinkActorNativeJoinCoordinatorOptions);
-    beginDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): void;
-    abortDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): Promise<void>;
+    beginDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
+    abortDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
     joinSpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, spotId: RoutingId, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, nodeRid: RoutingId | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     private withDeferredJoinFinalizer;

package/dist/runtime/actors/actor-remote-joiner.js

@@ -7,7 +7,6 @@ const actor_native_lookup_1 = require("./actor-native-lookup");
 const post_commit_actor_location_1 = require("./post-commit-actor-location");
 const actor_local_native_join_1 = require("./actor-local-native-join");
 const post_commit_actor_binder_1 = require("./post-commit-actor-binder");
-const operation_identity_1 = require("../foundation/operation-identity");
 /** Selects local native join or remote two-phase transfer for each destination. */
 class ZLinkActorNativeJoinCoordinator {
     options;
@@ -38,11 +37,11 @@ class ZLinkActorNativeJoinCoordinator {
             messageSerializers: options.messageSerializers
         });
     }
-    beginDeferredJoin(actor, state, operationId) {
-        this.options.sourceTransfer?.beginDeferredActorHandoff?.(actor, state, (0, operation_identity_1.operationIdentityKey)(operationId));
+    beginDeferredJoin(actor, state) {
+        this.options.sourceTransfer?.beginDeferredActorHandoff?.(actor, state);
     }
-    async abortDeferredJoin(actor, state, operationId) {
-        await this.options.sourceTransfer?.cancelDeferredActorHandoff?.(actor, state, (0, operation_identity_1.operationIdentityKey)(operationId));
+    async abortDeferredJoin(actor, state) {
+        await this.options.sourceTransfer?.cancelDeferredActorHandoff?.(actor, state);
     }
     async joinSpot(actor, state, spotId, request, timeoutMs, signal, completionOperationId) {
         (0, abort_1.throwIfAborted)(signal);
@@ -85,15 +84,14 @@ class ZLinkActorNativeJoinCoordinator {
     withDeferredJoinFinalizer(actor, state, target, result, operationId) {
         if (operationId === undefined || this.options.sourceTransfer === undefined)
             return result;
-        const key = (0, operation_identity_1.operationIdentityKey)(operationId);
         return {
             ...result,
             finalizeDeferredJoin: async () => {
                 if (result.accepted && result.actor !== undefined && target !== undefined) {
-                    await this.options.sourceTransfer.completeDeferredActorHandoff?.(actor, target, result.actor, key);
+                    await this.options.sourceTransfer.completeDeferredActorHandoff?.(actor, target, result.actor);
                 }
                 else {
-                    await this.options.sourceTransfer.cancelDeferredActorHandoff?.(actor, state, key);
+                    await this.options.sourceTransfer.cancelDeferredActorHandoff?.(actor, state);
                 }
             }
         };

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

@@ -6,6 +6,7 @@ import type { ZLinkLocationLifecycle } from '../locations';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
 import type { ZLinkActorTransferRegistry } from './actor-transfer-registry';
 import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkActivationAdmission } from '../activation-admission';
 export interface ZLinkActorJoinRuntimeResult<TReply> {
     readonly accepted: boolean;
     readonly actor?: import('../../contracts').ActorRef;
@@ -34,6 +35,7 @@ export interface ZLinkActorManagerOptions {
     readonly shutdownSignal?: AbortSignal;
     readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
     readonly admission?: ZLinkRuntimeAdmissionGate;
+    readonly activationAdmission?: ZLinkActivationAdmission;
     readonly placementCreate?: (actorId: string, actorType: string, createOnly: boolean, options: {
         readonly meshName?: string;
         readonly request?: unknown;
@@ -56,8 +58,8 @@ export interface ZLinkActorJoinCoordinator {
      * lookup. This is an internal ordering fence; it is not part of the public
      * actor context contract.
      */
-    beginDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): void;
-    abortDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): Promise<void>;
+    beginDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
+    abortDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
     joinSpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, spotId: RoutingId, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, nodeRid: RoutingId | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
 }

package/dist/runtime/actors/actor-source-transfer.d.ts

@@ -16,12 +16,12 @@ export interface ZLinkPreparedActorSource {
 }
 export interface ZLinkActorSourceTransfer {
     /** Starts the ingress handoff before target route lookup. */
-    beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): void;
+    beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
     /** Changes a provisional ingress fence into a relocation handoff. */
-    promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): void;
+    promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
     /** Finishes a same-node deferred Join handoff after completion callback. */
-    completeDeferredActorHandoff?(actor: ZLinkActor, target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, operationId: string): Promise<void>;
+    completeDeferredActorHandoff?(actor: ZLinkActor, target: ZLinkSpotRouteTarget, targetActorRef: ActorRef): Promise<void>;
     /** Releases an early handoff when Join cannot commit. */
-    cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): Promise<void>;
-    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredOperationId?: string, relocation?: ServiceWireOperationId): Promise<ZLinkPreparedActorSource>;
+    cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
+    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredJoin?: boolean, relocation?: ServiceWireOperationId): Promise<ZLinkPreparedActorSource>;
 }

package/dist/runtime/actors/deferred-join-completion.d.ts

@@ -0,0 +1,14 @@
+import type { ActorRef, ZLinkActorJoinOperationId } from '../../contracts';
+/**
+ * The Accepted completion of a deferred cross-node Join. Spot Actor membership
+ * sections 4-5: the public OperationId, the optional reply and the delivery
+ * state live only while the current source and target processes run. The
+ * completion is never written to a Store and never replayed after a restart.
+ */
+export interface ZLinkDeferredJoinCompletion {
+    readonly operationId: ZLinkActorJoinOperationId;
+    readonly actor: ActorRef;
+    readonly rawReply: Buffer;
+    readonly replyContentType?: string;
+}
+export declare function createDeferredJoinCompletion(actorId: string, operationId: ZLinkActorJoinOperationId, actor: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;

package/dist/runtime/actors/deferred-join-completion.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeferredJoinCompletion = createDeferredJoinCompletion;
+function createDeferredJoinCompletion(actorId, operationId, actor, rawReply, replyContentType) {
+    if (actorId.length === 0 ||
+        actor.actorId !== actorId ||
+        actor.objectGeneration <= 0n ||
+        (operationId.high === 0n && operationId.low === 0n)) {
+        throw new Error('Deferred Join completion identity is invalid.');
+    }
+    if (replyContentType !== undefined && replyContentType.length === 0) {
+        throw new TypeError('Deferred Join reply content type must be non-empty.');
+    }
+    return {
+        operationId,
+        actor,
+        rawReply: Buffer.from(rawReply),
+        ...(replyContentType === undefined ? {} : { replyContentType })
+    };
+}

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

@@ -7,7 +7,7 @@ export { ZLinkActorSerialExecutor } from './actor-mailbox';
 export { DEFAULT_MESSAGE_FOLLOW_DURATION_MS, ZLinkActorHandoffCoordinator, decodeHandoffPacket, type ZLinkActorHandoffPacket, type ZLinkActorHandoffDispatch, type ZLinkActorHandoffPrefixAdmission, type ZLinkActorHandoffPrefixQueue, type ZLinkActorHandoffPrefixRecord, type ZLinkActorHandoffPreparedReplayAdmission, type ZLinkActorHandoffReplayAdmission, type ZLinkActorHandoffReplayPreparation, type ZLinkActorHandoffResult } from './actor-handoff';
 export { actorMessageFollowContext, attachActorMessageFollowContext, decodeActorMessageFollowContext, type ZLinkActorMessageFollowContext, type ZLinkActorMessageFollowOwnerFence } from './actor-message-follow-context';
 export { ZLinkActorRuntimeState, mergeRemoteBoundSessionTarget, preferredRemoteBoundSessionTarget, toFrameworkActorRef, toFrameworkRoutingId, type ZLinkActorCreationOperation, type ZLinkRemoteActorPacketTarget, type ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
-export { isDeferredJoinAcceptedRootPublication, ZLinkDeferredJoinAcceptedJournal, type ZLinkDeferredJoinAcceptedRoot, type ZLinkDeferredJoinRootIdentity, type ZLinkDeferredJoinDeliveryCursor } from './deferred-join-accepted-journal';
+export { createDeferredJoinCompletion, type ZLinkDeferredJoinCompletion } from './deferred-join-completion';
 export { decodeActorAuthorityIdentity, decodeRelocatingActorAuthorityIdentity, encodeActorAuthorityIdentity, isActorAuthorityPayload, rewriteActorAuthorityRoute, rewriteActorAuthorityOwner, publishInitialActorAuthority, type ZLinkActorAuthorityIdentity } from './actor-authority-publication';
 import { ZLinkActorRuntimeState } from './actor-runtime-state';
 export { ZLinkActorPacketKind, ZLinkSpotActorDispatcher, ZLinkSpotActorHandlerRegistryRuntime, type ZLinkActorPacketDescriptor, type ZLinkSpotActorDispatcherOptions } from './spot-actor-dispatch';

package/dist/runtime/actors/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultZLinkActorManager = exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = exports.createActorMembership = exports.createActorJoinRequest = exports.actorJoinIdentity = exports.ZLinkRemoteBoundSessionFenceError = exports.isRemoteBoundSessionFenceError = exports.encodeRemoteBoundSessionNack = exports.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE = exports.ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET = exports.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = exports.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = exports.decodeRemoteActorSourceLeaveTerminal = exports.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL = exports.ZLINK_REMOTE_ACTOR_JOIN_PACKET = exports.ZLinkActorTransferRegistry = exports.ZLinkActorNativeJoinCoordinator = exports.ZLinkSpotActorHandlerRegistryRuntime = exports.ZLinkSpotActorDispatcher = exports.ZLinkActorPacketKind = exports.publishInitialActorAuthority = exports.rewriteActorAuthorityOwner = exports.rewriteActorAuthorityRoute = exports.isActorAuthorityPayload = exports.encodeActorAuthorityIdentity = exports.decodeRelocatingActorAuthorityIdentity = exports.decodeActorAuthorityIdentity = exports.ZLinkDeferredJoinAcceptedJournal = exports.isDeferredJoinAcceptedRootPublication = exports.toFrameworkRoutingId = exports.toFrameworkActorRef = exports.preferredRemoteBoundSessionTarget = exports.mergeRemoteBoundSessionTarget = exports.ZLinkActorRuntimeState = exports.decodeActorMessageFollowContext = exports.attachActorMessageFollowContext = exports.actorMessageFollowContext = exports.decodeHandoffPacket = exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = exports.ZLinkActorSerialExecutor = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = exports.DefaultZLinkActorContext = exports.forwardEncodedActorPacket = exports.DefaultZLinkActorClient = void 0;
+exports.DefaultZLinkActorManager = exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = exports.createActorMembership = exports.createActorJoinRequest = exports.actorJoinIdentity = exports.ZLinkRemoteBoundSessionFenceError = exports.isRemoteBoundSessionFenceError = exports.encodeRemoteBoundSessionNack = exports.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE = exports.ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET = exports.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = exports.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = exports.decodeRemoteActorSourceLeaveTerminal = exports.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL = exports.ZLINK_REMOTE_ACTOR_JOIN_PACKET = exports.ZLinkActorTransferRegistry = exports.ZLinkActorNativeJoinCoordinator = exports.ZLinkSpotActorHandlerRegistryRuntime = exports.ZLinkSpotActorDispatcher = exports.ZLinkActorPacketKind = exports.publishInitialActorAuthority = exports.rewriteActorAuthorityOwner = exports.rewriteActorAuthorityRoute = exports.isActorAuthorityPayload = exports.encodeActorAuthorityIdentity = exports.decodeRelocatingActorAuthorityIdentity = exports.decodeActorAuthorityIdentity = exports.createDeferredJoinCompletion = exports.toFrameworkRoutingId = exports.toFrameworkActorRef = exports.preferredRemoteBoundSessionTarget = exports.mergeRemoteBoundSessionTarget = exports.ZLinkActorRuntimeState = exports.decodeActorMessageFollowContext = exports.attachActorMessageFollowContext = exports.actorMessageFollowContext = exports.decodeHandoffPacket = exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = exports.ZLinkActorSerialExecutor = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = exports.DefaultZLinkActorContext = exports.forwardEncodedActorPacket = exports.DefaultZLinkActorClient = void 0;
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const runtime_message_1 = require("../backend/runtime-message");
@@ -34,9 +34,8 @@ Object.defineProperty(exports, "mergeRemoteBoundSessionTarget", { enumerable: tr
 Object.defineProperty(exports, "preferredRemoteBoundSessionTarget", { enumerable: true, get: function () { return actor_runtime_state_1.preferredRemoteBoundSessionTarget; } });
 Object.defineProperty(exports, "toFrameworkActorRef", { enumerable: true, get: function () { return actor_runtime_state_1.toFrameworkActorRef; } });
 Object.defineProperty(exports, "toFrameworkRoutingId", { enumerable: true, get: function () { return actor_runtime_state_1.toFrameworkRoutingId; } });
-var deferred_join_accepted_journal_1 = require("./deferred-join-accepted-journal");
-Object.defineProperty(exports, "isDeferredJoinAcceptedRootPublication", { enumerable: true, get: function () { return deferred_join_accepted_journal_1.isDeferredJoinAcceptedRootPublication; } });
-Object.defineProperty(exports, "ZLinkDeferredJoinAcceptedJournal", { enumerable: true, get: function () { return deferred_join_accepted_journal_1.ZLinkDeferredJoinAcceptedJournal; } });
+var deferred_join_completion_1 = require("./deferred-join-completion");
+Object.defineProperty(exports, "createDeferredJoinCompletion", { enumerable: true, get: function () { return deferred_join_completion_1.createDeferredJoinCompletion; } });
 var actor_authority_publication_1 = require("./actor-authority-publication");
 Object.defineProperty(exports, "decodeActorAuthorityIdentity", { enumerable: true, get: function () { return actor_authority_publication_1.decodeActorAuthorityIdentity; } });
 Object.defineProperty(exports, "decodeRelocatingActorAuthorityIdentity", { enumerable: true, get: function () { return actor_authority_publication_1.decodeRelocatingActorAuthorityIdentity; } });
@@ -451,7 +450,18 @@ class DefaultZLinkActorManager {
             if (request !== undefined && createRequest.nativeRequest !== undefined) {
                 state.setCreateRequestPayload(createRequest.nativeRequest.data());
             }
-            const operation = state.getOrStartCreation(actorType, failIfExists, () => this.creation.createActor(actorId, actorType, state, createRequest, claimLocation, signal));
+            const operation = state.getOrStartCreation(actorType, failIfExists, async () => {
+                const meshName = state.meshName ?? this.options.actorMeshNameProvider?.(actorType);
+                const release = meshName === undefined
+                    ? undefined
+                    : await this.options.activationAdmission?.acquire(meshName, signal);
+                try {
+                    return await this.creation.createActor(actorId, actorType, state, createRequest, claimLocation, signal);
+                }
+                finally {
+                    release?.();
+                }
+            });
             if (operation.created) {
                 void operation.task.then((result) => {
                     if (result.status !== 'created') {

package/dist/runtime/admission.d.ts

@@ -1,7 +1,11 @@
 import { ZLinkFrameworkInternalErrorKind } from './framework-errors-internal';
 export declare class ZLinkRuntimeAdmissionGate {
-    private readonly ownerAdmissionOpen;
+    readonly ownerAdmissionOpen: () => boolean;
     private readonly meshes;
+    /**
+     * Location runtime §5: the host's single new-work decision (local admission deadline and host
+     * execution combination). A host without a Location Store has no such block.
+     */
     constructor(ownerAdmissionOpen?: () => boolean);
     get acceptsNewWork(): boolean;
     register(meshName: string): void;

package/dist/runtime/admission.js

@@ -5,6 +5,10 @@ const framework_errors_internal_1 = require("./framework-errors-internal");
 class ZLinkRuntimeAdmissionGate {
     ownerAdmissionOpen;
     meshes = new Map();
+    /**
+     * Location runtime §5: the host's single new-work decision (local admission deadline and host
+     * execution combination). A host without a Location Store has no such block.
+     */
     constructor(ownerAdmissionOpen = () => true) {
         this.ownerAdmissionOpen = ownerAdmissionOpen;
     }