@zlink-systems/framework 0.29.1 → 0.30.1

package/dist/runtime/protocol/service_wire_codec.generated.js

@@ -351,6 +351,10 @@ exports.decodeRelocationPendingTimerTick = decodeRelocationPendingTimerTick;
 exports.encodeRelocationPendingTimerTick = encodeRelocationPendingTimerTick;
 exports.decodeRelocationPendingTimerTickVector = decodeRelocationPendingTimerTickVector;
 exports.encodeRelocationPendingTimerTickVector = encodeRelocationPendingTimerTickVector;
+exports.decodeRelocationSessionBinding = decodeRelocationSessionBinding;
+exports.encodeRelocationSessionBinding = encodeRelocationSessionBinding;
+exports.decodeRelocationSessionBindingVector = decodeRelocationSessionBindingVector;
+exports.encodeRelocationSessionBindingVector = encodeRelocationSessionBindingVector;
 exports.decodeRelocationEnvelopeV1 = decodeRelocationEnvelopeV1;
 exports.encodeRelocationEnvelopeV1 = encodeRelocationEnvelopeV1;
 exports.decodeHelloCommand = decodeHelloCommand;
@@ -8487,6 +8491,141 @@ function writeRelocationPendingTimerTickVector(input, writer, context, enclosing
 }
 function decodeRelocationPendingTimerTickVector(bytes, context) { const reader = new Reader(bytes); const value = readRelocationPendingTimerTickVector(reader, context, {}, 0); reader.done("relocation-pending-timer-tick-vector"); return value; }
 function encodeRelocationPendingTimerTickVector(value, context) { const writer = new Writer(); writeRelocationPendingTimerTickVector(value, writer, context, {}, 0); return writer.result(); }
+function readRelocationSessionBinding(reader, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const value = {};
+    value["participantId"] = readNonzeroU64(reader, context, value, flags);
+    value["sessionOwnerNodeRid"] = readRid(reader, context, value, flags);
+    value["sessionOwnerNodeGeneration"] = readNonzeroU64(reader, context, value, flags);
+    value["sessionOwnerId"] = readText8(reader, context, value, flags);
+    value["sessionOwnerLeaseGeneration"] = readNonzeroU64(reader, context, value, flags);
+    value["sessionRid"] = readRid(reader, context, value, flags);
+    value["bindingGeneration"] = readNonzeroU64(reader, context, value, flags);
+    return value;
+}
+function* readIncrementalRelocationSessionBinding(reader, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const value = {};
+    value["participantId"] = yield* readIncrementalNonzeroU64(reader, context, value, flags);
+    value["sessionOwnerNodeRid"] = yield* readIncrementalRid(reader, context, value, flags);
+    value["sessionOwnerNodeGeneration"] = yield* readIncrementalNonzeroU64(reader, context, value, flags);
+    value["sessionOwnerId"] = yield* readIncrementalText8(reader, context, value, flags);
+    value["sessionOwnerLeaseGeneration"] = yield* readIncrementalNonzeroU64(reader, context, value, flags);
+    value["sessionRid"] = yield* readIncrementalRid(reader, context, value, flags);
+    value["bindingGeneration"] = yield* readIncrementalNonzeroU64(reader, context, value, flags);
+    return value;
+}
+function writeRelocationSessionBinding(input, writer, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const value = input;
+    if (value["participantId"] === undefined)
+        fail("participantId required");
+    writeNonzeroU64(numeric(value["participantId"]), writer, context, value, flags);
+    if (value["sessionOwnerNodeRid"] === undefined)
+        fail("sessionOwnerNodeRid required");
+    writeRid(value["sessionOwnerNodeRid"], writer, context, value, flags);
+    if (value["sessionOwnerNodeGeneration"] === undefined)
+        fail("sessionOwnerNodeGeneration required");
+    writeNonzeroU64(numeric(value["sessionOwnerNodeGeneration"]), writer, context, value, flags);
+    if (value["sessionOwnerId"] === undefined)
+        fail("sessionOwnerId required");
+    writeText8(value["sessionOwnerId"], writer, context, value, flags);
+    if (value["sessionOwnerLeaseGeneration"] === undefined)
+        fail("sessionOwnerLeaseGeneration required");
+    writeNonzeroU64(numeric(value["sessionOwnerLeaseGeneration"]), writer, context, value, flags);
+    if (value["sessionRid"] === undefined)
+        fail("sessionRid required");
+    writeRid(value["sessionRid"], writer, context, value, flags);
+    if (value["bindingGeneration"] === undefined)
+        fail("bindingGeneration required");
+    writeNonzeroU64(numeric(value["bindingGeneration"]), writer, context, value, flags);
+}
+function decodeRelocationSessionBinding(bytes, context) { const reader = new Reader(bytes); const value = readRelocationSessionBinding(reader, context, {}, 0); reader.done("relocation-session-binding"); return value; }
+function encodeRelocationSessionBinding(value, context) { const writer = new Writer(); writeRelocationSessionBinding(value, writer, context, {}, 0); return writer.result(); }
+function readRelocationSessionBindingVector(reader, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const count = Number(readU32(reader, context, enclosing, flags));
+    if (count > 1024)
+        fail("relocation-session-binding-vector count");
+    const value = Array.from({ length: count }, () => readRelocationSessionBinding(reader, context, enclosing, flags));
+    try {
+        for (let index = 1; index < value.length; ++index)
+            if (compareResults([compareBigint(numeric(value[index - 1]["participantId"]), numeric(value[index]["participantId"]))]) >= 0)
+                fail("relocation-session-binding-vector sorted");
+    }
+    catch (error) {
+        if (error instanceof ServiceWireProtocolError || error instanceof ServiceWireCapacityError)
+            throw error;
+        if (error instanceof RangeError)
+            capacityFail("relocation-session-binding-vector constraint capacity");
+        throw error;
+    }
+    return value;
+}
+function* readIncrementalRelocationSessionBindingVector(reader, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const count = Number(yield* readIncrementalU32(reader, context, enclosing, flags));
+    if (count > 1024)
+        fail("relocation-session-binding-vector count");
+    const value = [];
+    for (let index = 0; index < count; ++index) {
+        const item = yield* readIncrementalRelocationSessionBinding(reader, context, enclosing, flags);
+        try {
+            value.push(item);
+        }
+        catch {
+            capacityFail("relocation-session-binding-vector capacity");
+        }
+    }
+    try {
+        for (let index = 1; index < value.length; ++index)
+            if (compareResults([compareBigint(numeric(value[index - 1]["participantId"]), numeric(value[index]["participantId"]))]) >= 0)
+                fail("relocation-session-binding-vector sorted");
+    }
+    catch (error) {
+        if (error instanceof ServiceWireProtocolError || error instanceof ServiceWireCapacityError)
+            throw error;
+        if (error instanceof RangeError)
+            capacityFail("relocation-session-binding-vector constraint capacity");
+        throw error;
+    }
+    return value;
+}
+function writeRelocationSessionBindingVector(input, writer, context, enclosing, flags) {
+    void context;
+    void enclosing;
+    void flags;
+    const value = input;
+    if (!Array.isArray(value) || value.length > 1024)
+        fail("relocation-session-binding-vector count");
+    try {
+        for (let index = 1; index < value.length; ++index)
+            if (compareResults([compareBigint(numeric(value[index - 1]["participantId"]), numeric(value[index]["participantId"]))]) >= 0)
+                fail("relocation-session-binding-vector sorted");
+    }
+    catch (error) {
+        if (error instanceof ServiceWireProtocolError || error instanceof ServiceWireCapacityError)
+            throw error;
+        if (error instanceof RangeError)
+            capacityFail("relocation-session-binding-vector constraint capacity");
+        throw error;
+    }
+    writeU32(value.length, writer, context, enclosing, flags);
+    for (const item of value)
+        writeRelocationSessionBinding(item, writer, context, enclosing, flags);
+}
+function decodeRelocationSessionBindingVector(bytes, context) { const reader = new Reader(bytes); const value = readRelocationSessionBindingVector(reader, context, {}, 0); reader.done("relocation-session-binding-vector"); return value; }
+function encodeRelocationSessionBindingVector(value, context) { const writer = new Writer(); writeRelocationSessionBindingVector(value, writer, context, {}, 0); return writer.result(); }
 function readRelocationEnvelopeV1(reader, context, enclosing, flags) {
     void context;
     void enclosing;
@@ -8499,6 +8638,7 @@ function readRelocationEnvelopeV1(reader, context, enclosing, flags) {
     value["savedWork"] = readSavedWorkVector(reader, context, value, flags);
     value["timerRegistrations"] = readRelocationTimerRegistrationVector(reader, context, value, flags);
     value["pendingTimerTicks"] = readRelocationPendingTimerTickVector(reader, context, value, flags);
+    value["sessionBindings"] = readRelocationSessionBindingVector(reader, context, value, flags);
     return value;
 }
 function* readIncrementalRelocationEnvelopeV1(reader, context, enclosing, flags) {
@@ -8513,6 +8653,7 @@ function* readIncrementalRelocationEnvelopeV1(reader, context, enclosing, flags)
     value["savedWork"] = yield* readIncrementalSavedWorkVector(reader, context, value, flags);
     value["timerRegistrations"] = yield* readIncrementalRelocationTimerRegistrationVector(reader, context, value, flags);
     value["pendingTimerTicks"] = yield* readIncrementalRelocationPendingTimerTickVector(reader, context, value, flags);
+    value["sessionBindings"] = yield* readIncrementalRelocationSessionBindingVector(reader, context, value, flags);
     return value;
 }
 function writeRelocationEnvelopeV1(input, writer, context, enclosing, flags) {
@@ -8541,6 +8682,9 @@ function writeRelocationEnvelopeV1(input, writer, context, enclosing, flags) {
     if (value["pendingTimerTicks"] === undefined)
         fail("pendingTimerTicks required");
     writeRelocationPendingTimerTickVector(value["pendingTimerTicks"], writer, context, value, flags);
+    if (value["sessionBindings"] === undefined)
+        fail("sessionBindings required");
+    writeRelocationSessionBindingVector(value["sessionBindings"], writer, context, value, flags);
 }
 function decodeRelocationEnvelopeV1(bytes, context) { const reader = new Reader(bytes); const value = readRelocationEnvelopeV1(reader, context, {}, 0); reader.done("relocation-envelope-v1"); return value; }
 function encodeRelocationEnvelopeV1(value, context) { const writer = new Writer(); writeRelocationEnvelopeV1(value, writer, context, {}, 0); return writer.result(); }

package/dist/runtime/protocol/service_wire_pilot_codec.generated.d.ts

@@ -72,6 +72,15 @@ export interface RelocationEnvelopeV1 {
         readonly scheduledAtUnixMilliseconds: bigint;
         readonly skippedTicks: bigint;
     }[];
+    readonly sessionBindings: readonly {
+        readonly participantId: bigint;
+        readonly sessionOwnerNodeRid: Uint8Array;
+        readonly sessionOwnerNodeGeneration: bigint;
+        readonly sessionOwnerId: string;
+        readonly sessionOwnerLeaseGeneration: bigint;
+        readonly sessionRid: Uint8Array;
+        readonly bindingGeneration: bigint;
+    }[];
 }
 export interface RelocationDataChunkV1 {
     readonly order: number;

package/dist/runtime/protocol/service_wire_pilot_codec.generated.js

@@ -331,6 +331,17 @@ function encodeRelocationEnvelopeV1(value) { const out = []; if (value.relocatio
     u64(out, p.scheduledIndex);
     u64(out, p.scheduledAtUnixMilliseconds);
     u64(out, p.skippedTicks);
+} sorted(value.sessionBindings, (a, b) => a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0, "sessionBindings"); if (value.sessionBindings.length > 1024)
+    throw new RangeError("bindings count"); u32(out, value.sessionBindings.length); for (const b of value.sessionBindings) {
+    if (b.participantId === 0n || b.sessionOwnerNodeGeneration === 0n || b.sessionOwnerLeaseGeneration === 0n || b.bindingGeneration === 0n)
+        throw new RangeError("binding");
+    u64(out, b.participantId);
+    rid(out, b.sessionOwnerNodeRid);
+    u64(out, b.sessionOwnerNodeGeneration);
+    text8(out, b.sessionOwnerId);
+    u64(out, b.sessionOwnerLeaseGeneration);
+    rid(out, b.sessionRid);
+    u64(out, b.bindingGeneration);
 } if (out.length > 274877906944)
     throw new RangeError("relocation logical bytes"); return Uint8Array.from(out); }
 function decodeRelocationEnvelopeV1(chunks) { const n = chunks.reduce((s, c) => s + c.length, 0); if (n > 274877906944)
@@ -381,7 +392,9 @@ function decodeRelocationEnvelopeV1(chunks) { const n = chunks.reduce((s, c) =>
     if (registeredTimerNames.get(participantId)?.has(timerName) !== true)
         throw new RangeError("pending timer registration");
     pendingTimerTicks.push({ participantId, order, timerName, deliveryIndex: nonzero64(bytes, at, "delivery"), scheduledIndex: nonzero64(bytes, at, "scheduled"), scheduledAtUnixMilliseconds: read64(bytes, at), skippedTicks: read64(bytes, at) });
-} exactEnd(at, bytes.length, "relocation envelope"); sorted(applicationStates, (a, b) => a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0, "applicationStates"); sorted(savedWork, (a, b) => a.participantId === b.participantId ? (a.order < b.order ? -1 : a.order > b.order ? 1 : 0) : (a.participantId < b.participantId ? -1 : 1), "savedWork"); sorted(timerRegistrations, (a, b) => a.participantId === b.participantId ? compareUtf8(a.name, b.name) : a.participantId < b.participantId ? -1 : 1, "timerRegistrations"); sorted(pendingTimerTicks, (a, b) => a.participantId === b.participantId ? (a.order < b.order ? -1 : a.order > b.order ? 1 : 0) : (a.participantId < b.participantId ? -1 : 1), "pendingTimerTicks"); return { relocationHigh, relocationLow, object, applicationVersion, applicationStates, savedWork, timerRegistrations, pendingTimerTicks }; }
+} const sessionBindings = []; const bindingCount = read32(bytes, at); if (bindingCount > 1024)
+    throw new RangeError("bindings count"); for (let n = 0; n < bindingCount; n++)
+    sessionBindings.push({ participantId: nonzero64(bytes, at, "participant"), sessionOwnerNodeRid: readRid(bytes, at), sessionOwnerNodeGeneration: nonzero64(bytes, at, "session node"), sessionOwnerId: readText8(bytes, at), sessionOwnerLeaseGeneration: nonzero64(bytes, at, "session lease"), sessionRid: readRid(bytes, at), bindingGeneration: nonzero64(bytes, at, "binding") }); sorted(sessionBindings, (a, b) => a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0, "sessionBindings"); exactEnd(at, bytes.length, "relocation envelope"); sorted(applicationStates, (a, b) => a.participantId < b.participantId ? -1 : a.participantId > b.participantId ? 1 : 0, "applicationStates"); sorted(savedWork, (a, b) => a.participantId === b.participantId ? (a.order < b.order ? -1 : a.order > b.order ? 1 : 0) : (a.participantId < b.participantId ? -1 : 1), "savedWork"); sorted(timerRegistrations, (a, b) => a.participantId === b.participantId ? compareUtf8(a.name, b.name) : a.participantId < b.participantId ? -1 : 1, "timerRegistrations"); sorted(pendingTimerTicks, (a, b) => a.participantId === b.participantId ? (a.order < b.order ? -1 : a.order > b.order ? 1 : 0) : (a.participantId < b.participantId ? -1 : 1), "pendingTimerTicks"); return { relocationHigh, relocationLow, object, applicationVersion, applicationStates, savedWork, timerRegistrations, pendingTimerTicks, sessionBindings }; }
 function crc32c(bytes) { let crc = 0xffffffff; for (const octet of bytes) {
     crc ^= octet;
     for (let bit = 0; bit < 8; bit++)

package/dist/runtime/spots/formal-remote-actor-admission-registry.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId } from '../../contracts';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import type { ZLinkDeferredJoinCompletion } from '../actors/deferred-join-completion';
@@ -10,6 +11,7 @@ import type { ZLinkActorRequestTerminal } from './spot-actor-packet-dispatch';
  * how long the underlying buffer stays valid.
  */
 export interface ZLinkParkedActorArrival {
+    readonly origin: ApplicationJobOrigin;
     readonly header: Buffer;
     readonly payload: Buffer;
     readonly returnResponse: boolean;
@@ -20,7 +22,7 @@ export interface ZLinkParkedActorArrival {
     readonly reject: (reason: unknown) => void;
 }
 export type ZLinkActorJoinIngressRoute = 'parked' | 'not-found';
-export type ZLinkFormalRemoteActorAdmissionState = 'provisional' | 'admitting' | 'admitted' | 'rejected' | 'committed' | 'aborted' | 'failed';
+export type ZLinkFormalRemoteActorAdmissionState = 'provisional' | 'admitting' | 'admitted' | 'restoring' | 'rejected' | 'committed' | 'aborted' | 'failed';
 export interface ZLinkFormalRemoteActorAdmission {
     readonly actorId: string;
     readonly actorType: string;
@@ -54,7 +56,7 @@ export interface ZLinkFormalRemoteActorAdmissionRecord {
     readonly resultTask: Promise<ZLinkFormalRemoteActorAdmissionResult>;
 }
 interface ZLinkFormalRemoteActorAdmissionEntry extends ZLinkFormalRemoteActorAdmissionRecord {
-    readonly timer: ReturnType<typeof setTimeout>;
+    timer: ReturnType<typeof setTimeout>;
     readonly resolveResult: (result: ZLinkFormalRemoteActorAdmissionResult) => void;
     admission: ZLinkFormalRemoteActorAdmission;
     state: ZLinkFormalRemoteActorAdmissionState;
@@ -68,6 +70,11 @@ export declare class ZLinkFormalRemoteActorAdmissionRegistry {
     private readonly admissions;
     private readonly byObject;
     get(transferId: string): ZLinkFormalRemoteActorAdmissionEntry | undefined;
+    /** PREPARE transfers prepared resources to the target attempt until its terminal. */
+    beginRestore(transferId: string): void;
+    /** Retains successful commit replay; unsuccessful attempts release their resources now. */
+    finishRestore(transferId: string): void;
+    private scheduleExpiry;
     begin(input: ZLinkFormalRemoteActorAdmission): {
         readonly record: ZLinkFormalRemoteActorAdmissionEntry;
         readonly created: boolean;

package/dist/runtime/spots/formal-remote-actor-admission-registry.js

@@ -17,6 +17,34 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
     get(transferId) {
         return this.admissions.get(transferId);
     }
+    /** PREPARE transfers prepared resources to the target attempt until its terminal. */
+    beginRestore(transferId) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined || (entry.state !== 'admitted' && entry.state !== 'restoring')) {
+            throw new Error(`Remote actor admission '${transferId}' is not ready to restore.`);
+        }
+        clearTimeout(entry.timer);
+        entry.state = 'restoring';
+    }
+    /** Retains successful commit replay; unsuccessful attempts release their resources now. */
+    finishRestore(transferId) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined)
+            return;
+        if (entry.state === 'committed') {
+            clearTimeout(entry.timer);
+            entry.timer = this.scheduleExpiry(transferId);
+        }
+        else {
+            this.abort(transferId);
+            this.delete(transferId);
+        }
+    }
+    scheduleExpiry(transferId) {
+        const timer = setTimeout(() => this.delete(transferId), ADMISSION_RETENTION_MS);
+        timer.unref();
+        return timer;
+    }
     begin(input) {
         const existing = this.admissions.get(input.transferId);
         if (existing !== undefined) {
@@ -71,10 +99,7 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
         const resultTask = new Promise((resolve) => {
             resolveResult = resolve;
         });
-        const timer = setTimeout(() => {
-            this.delete(input.transferId);
-        }, ADMISSION_RETENTION_MS);
-        timer.unref();
+        const timer = this.scheduleExpiry(input.transferId);
         const entry = {
             admission: input,
             state,
@@ -186,7 +211,7 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
         const entry = this.admissions.get(transferId);
         if (entry === undefined)
             return;
-        if (entry.state !== 'admitted' && entry.state !== 'committed') {
+        if (entry.state !== 'admitted' && entry.state !== 'restoring' && entry.state !== 'committed') {
             throw new Error(`Remote actor admission '${transferId}' is not ready to commit.`);
         }
         entry.state = 'committed';
@@ -195,7 +220,7 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
     attachDeferredJoinCompletion(transferId, root) {
         const entry = this.admissions.get(transferId);
         if (entry === undefined ||
-            entry.state !== 'admitted' ||
+            (entry.state !== 'admitted' && entry.state !== 'restoring') ||
             entry.result === undefined ||
             'error' in entry.result ||
             !entry.result.accepted) {
@@ -227,7 +252,7 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
      */
     delete(transferId) {
         const pending = this.admissions.get(transferId);
-        if (pending === undefined)
+        if (pending === undefined || pending.state === 'restoring')
             return;
         clearTimeout(pending.timer);
         this.admissions.delete(transferId);
@@ -240,18 +265,7 @@ class ZLinkFormalRemoteActorAdmissionRegistry {
 }
 exports.ZLinkFormalRemoteActorAdmissionRegistry = ZLinkFormalRemoteActorAdmissionRegistry;
 function sameAdmission(left, right) {
-    return (left.actorId === right.actorId &&
-        left.actorType === right.actorType &&
-        String(left.spotId) === String(right.spotId) &&
-        left.targetSpotGeneration === right.targetSpotGeneration &&
-        left.expectedMembershipEpoch === right.expectedMembershipEpoch &&
-        left.requestFingerprint === right.requestFingerprint &&
-        sameOperationId(left.completionOperationId, right.completionOperationId) &&
-        String(left.sourceSpotId ?? '') === String(right.sourceSpotId ?? '') &&
-        String(left.sourceActorNodeRid ?? '') === String(right.sourceActorNodeRid ?? '') &&
-        left.actorRef.actorId === right.actorRef.actorId &&
-        String(left.actorRef.nodeRid) === String(right.actorRef.nodeRid) &&
-        left.actorRef.objectGeneration === right.actorRef.objectGeneration);
+    return left.actorType === right.actorType && sameProvisionalAdmission(left, right);
 }
 function sameProvisionalAdmission(left, right) {
     return (left.actorId === right.actorId &&

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, Type, ZLinkMessageSerializer, ZLinkInstanceSpot, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkSpot, ZLinkSpotActorJoinResult, ZLinkSpotInfo, ZLinkSpotPublisherClient } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandlerRegistration, ZLinkSpotPacketHandlerRegistration, ZLinkSpotSubscriptionHandlerRegistration, ZLinkSpotTimerHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
@@ -55,7 +56,7 @@ export interface ZLinkSpotManagerOptions {
     readonly entrySpotCallbacks?: {
         onLeaveActor(actor: ZLinkActor, signal?: AbortSignal, actorRef?: ActorRef, membershipEpoch?: bigint): Promise<void>;
     };
-    readonly dispatchEntryActorPacket?: (actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin) => Promise<unknown>;
+    readonly dispatchEntryActorPacket?: (origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin) => Promise<unknown>;
     /**
      * Commits a stateful MeshNode Actor return to the Entry Spot after the
      * stateful reply has committed Core membership.
@@ -63,6 +64,7 @@ export interface ZLinkSpotManagerOptions {
     readonly dispatchEntryActorJoin?: (meshName: string, actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[]) => Promise<void>;
     readonly executeEntryActor?: <T>(meshName: string, actorId: string, operation: () => Promise<T>) => Promise<T>;
     readonly actorCountProvider?: (spotId: RoutingId) => number;
+    readonly releaseActorMembers?: (meshName: string, spotId: RoutingId) => Promise<void>;
     readonly userSpotExecutionMode?: (meshName: string, spotType: Type<ZLinkSpot>) => import('../../contracts').ZLinkUserSpotExecutionMode;
     readonly userSpotRelocationCoordinationMode?: (meshName: string, spotType: Type<ZLinkSpot>) => import('../../contracts').ZLinkSpotRelocationCoordinationMode;
     readonly actorDispatchOwnerResolver?: (actorId: string) => {
@@ -200,7 +202,7 @@ export declare class DefaultZLinkSpotManager {
     beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     cancelActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     notifyJoinedSpotActorDisconnected(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<boolean>;
-    dispatchRoutedActorPacket(spotId: RoutingId, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<unknown>;
+    dispatchRoutedActorPacket(origin: ApplicationJobOrigin, spotId: RoutingId, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef): Promise<unknown>;
     dispatchRoutedSpotSend(spotId: RoutingId, packetName: string | undefined, message: unknown, context: {
         readonly channelName: string;
         readonly contentType?: string;
@@ -214,19 +216,21 @@ export declare class DefaultZLinkSpotManager {
         readonly workOptions?: import('../execution/serial-execution-queue').ZLinkSerialWorkOptions;
         readonly admissionTimeoutMs?: number;
         readonly signal?: AbortSignal;
+        readonly onAdmitted?: () => void;
     }): Promise<TReply>;
     dispatchMeshSpot(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private ensureInstanceApplicationActivation;
     dispatchMeshInstance(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private reportInstanceDispatchFailure;
     private traceInstanceMessage;
-    dispatchMeshActor(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
+    dispatchMeshActor(origin: ApplicationJobOrigin, meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     dispatchMeshActorJoin(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private dispatchMeshActorJoinCore;
     dispatchMeshSpotControl(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private dispatchMeshSpotControlCore;
     completeFormalSourceLeaveTerminal(actorId: string, transferId: string, succeeded: boolean): Promise<boolean>;
     finalizeActorJoinRelocation(meshName: string, relocationId: string, actor: ZLinkActor, actorRef: ActorRef, submitSourceLeave: (sourceNodeRid: RoutingId) => Promise<void>, signal?: AbortSignal): Promise<boolean>;
+    beginActorJoinRelocation(relocationId: string): () => void;
     restoreCanonicalActorJoinRecovery(recovery: CanonicalActorJoinRecovery, signal?: AbortSignal): Promise<void>;
     private encodeMeshActorReply;
     private createActivation;

package/dist/runtime/spots/index.js

@@ -130,6 +130,7 @@ class DefaultZLinkSpotManager {
             nodeRid: options.nodeRid,
             nodeRidProvider: options.nodeRidProvider,
             actorCountProvider: options.actorCountProvider,
+            releaseActorMembers: options.releaseActorMembers,
             userSpotExecutionMode: options.userSpotExecutionMode,
             userSpotRelocationCoordinationMode: options.userSpotRelocationCoordinationMode,
             channelClient: options.channelClient,
@@ -860,20 +861,20 @@ class DefaultZLinkSpotManager {
     async notifyJoinedSpotActorDisconnected(spotId, actor, signal) {
         return await this.actorMembership.notifyJoinedActorDisconnected(spotId, actor, signal);
     }
-    dispatchRoutedActorPacket(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+    dispatchRoutedActorPacket(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
         const activation = this.activations.resolveUnique(spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
         }
-        return this.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+        return this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
     }
     /** @internal Replays a record already owned by the Actor handoff queue. */
-    dispatchRoutedActorPacketDirect(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+    dispatchRoutedActorPacketDirect(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
         const activation = this.activations.resolveUnique(spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
         }
-        return this.activationLifecycle.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+        return this.activationLifecycle.dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
     }
     /** @internal Atomically restores one durable packet prefix to an Actor FIFO. */
     admitRoutedActorPacketPrefix(spotId, actorId, records) {
@@ -1071,7 +1072,7 @@ class DefaultZLinkSpotManager {
             errorReason
         });
     }
-    async dispatchMeshActor(meshName, owner, record) {
+    async dispatchMeshActor(origin, meshName, owner, record) {
         const spotId = owner.spotId;
         const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
         const targetsEntrySpot = spotId === null || (entrySpotId !== undefined && spotId === entrySpotId);
@@ -1115,8 +1116,8 @@ class DefaultZLinkSpotManager {
                 throw new Error(`Actor '${actor.actorId}' target transfer reconciliation is not complete.`);
             }
             const response = targetsEntrySpot
-                ? await this.options.dispatchEntryActorPacket?.(actor.actorId, record.parts, request, undefined, ownerActorRef, requestTerminal, record.messageFollowOrigin)
-                : await this.dispatchMeshActorPacket(meshName, spotId, actor.actorId, record.parts, request, ownerActorRef, requestTerminal, record.messageFollowOrigin);
+                ? await this.options.dispatchEntryActorPacket?.(origin, actor.actorId, record.parts, request, undefined, ownerActorRef, requestTerminal, record.messageFollowOrigin)
+                : await this.dispatchMeshActorPacket(origin, meshName, spotId, actor.actorId, record.parts, request, ownerActorRef, requestTerminal, record.messageFollowOrigin);
             if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
                 throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot Actor dispatch is not configured.');
             }
@@ -1631,7 +1632,7 @@ class DefaultZLinkSpotManager {
                                 if (this.options.dispatchEntryActorPacket === undefined) {
                                     throw new Error('Entry Spot saved handoff replay requires its Actor packet runtime.');
                                 }
-                                return await this.options.dispatchEntryActorPacket(entryActor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+                                return await this.options.dispatchEntryActorPacket('remote', entryActor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
                             }, (index) => this.options.runtimeEventPublisher?.publish({
                                 sourceName: 'zlink.framework.actor-handoff',
                                 timestamp: new Date(),
@@ -1790,7 +1791,7 @@ class DefaultZLinkSpotManager {
                 };
                 const completeTargetReady = async () => {
                     if (pendingTransfer !== undefined) {
-                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket(activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
+                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket('remote', activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
                             sourceName: 'zlink.framework.actor-handoff',
                             timestamp: new Date(),
                             marker: 'backlog_enqueued',
@@ -1894,7 +1895,7 @@ class DefaultZLinkSpotManager {
         const outcome = admission.result ?? (await admission.resultTask);
         if ('error' in outcome)
             throw outcome.error;
-        if (!outcome.accepted || admission.state !== 'admitted') {
+        if (!outcome.accepted || (admission.state !== 'admitted' && admission.state !== 'restoring')) {
             throw new Error(`Actor Join relocation '${relocationId}' has no accepted admission.`);
         }
         const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
@@ -1944,6 +1945,10 @@ class DefaultZLinkSpotManager {
         this.formalRemoteActorAdmissions.markCommitted(relocationId, actor);
         return true;
     }
+    beginActorJoinRelocation(relocationId) {
+        this.formalRemoteActorAdmissions.beginRestore(relocationId);
+        return () => this.formalRemoteActorAdmissions.finishRestore(relocationId);
+    }
     async restoreCanonicalActorJoinRecovery(recovery, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const admission = this.formalRemoteActorAdmissions.get(recovery.request.handoffId);
@@ -1951,7 +1956,9 @@ class DefaultZLinkSpotManager {
             throw new Error(`Actor Join recovery '${recovery.request.handoffId}' has no canonical command-28 admission.`);
         }
         const outcome = admission.result ?? (await admission.resultTask);
-        if ('error' in outcome || !outcome.accepted || admission.state !== 'admitted') {
+        if ('error' in outcome ||
+            !outcome.accepted ||
+            (admission.state !== 'admitted' && admission.state !== 'restoring')) {
             throw new Error(`Actor Join recovery '${recovery.request.handoffId}' has no accepted admission.`);
         }
         const admitted = admission.admission;
@@ -2033,8 +2040,8 @@ class DefaultZLinkSpotManager {
             throw new configuration_1.ZLinkConfigurationException('Spot type is not registered as a spot factory.');
         }
     }
-    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
-        return await this.activationLifecycle.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    async dispatchActorPacket(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        return await this.activationLifecycle.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
     /**
      * Spec 15 §4.2 relocation temporary queue: drains every arrival parked
@@ -2050,7 +2057,7 @@ class DefaultZLinkSpotManager {
         const drained = this.formalRemoteActorAdmissions.completeMigration(transferId);
         for (const arrival of drained) {
             try {
-                const response = await this.dispatchActorPacket(activation, actor.context.actorId, [runtime_message_1.ZLinkBufferMessage.from(arrival.header), runtime_message_1.ZLinkBufferMessage.from(arrival.payload)], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
+                const response = await this.dispatchActorPacket(arrival.origin, activation, actor.context.actorId, [runtime_message_1.ZLinkBufferMessage.from(arrival.header), runtime_message_1.ZLinkBufferMessage.from(arrival.payload)], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
                 arrival.resolve(response);
             }
             catch (error) {
@@ -2058,12 +2065,12 @@ class DefaultZLinkSpotManager {
             }
         }
     }
-    async dispatchMeshActorPacket(meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+    async dispatchMeshActorPacket(origin, meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         const activation = this.activations.resolve(meshName, spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${String(spotId)}' is not active in mesh '${meshName}'.`);
         }
-        return await this.dispatchActorPacket(activation, actorId, parts, returnResponse, undefined, fallbackActorRef, requestTerminal, messageFollowOrigin);
+        return await this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, undefined, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
 }
 exports.DefaultZLinkSpotManager = DefaultZLinkSpotManager;

package/dist/runtime/spots/spot-activation.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, Type, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkMessageSerializer, ZLinkInstanceSpot, ZLinkSpot, ZLinkSpotPublisherClient } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkRuntimeAdmissionGate } from '../admission';
@@ -28,6 +29,7 @@ export interface ZLinkSpotActivationLifecycleOptions {
     readonly nodeRid?: RoutingId;
     readonly nodeRidProvider?: (meshName: string) => RoutingId | undefined;
     readonly actorCountProvider?: (spotId: RoutingId) => number;
+    readonly releaseActorMembers?: (meshName: string, spotId: RoutingId) => Promise<void>;
     readonly userSpotExecutionMode?: (meshName: string, spotType: Type<ZLinkSpot>) => ZLinkUserSpotExecutionMode;
     readonly userSpotRelocationCoordinationMode?: (meshName: string, spotType: Type<ZLinkSpot>) => ZLinkSpotRelocationCoordinationMode;
     readonly channelClient?: ZLinkChannelClient;
@@ -82,7 +84,7 @@ export declare class ZLinkSpotActivationLifecycle {
     /** Returns the OnClosing failure, which cleanup records and does not rethrow. */
     cleanupClosedActivation(activation: ZLinkSpotActivation, reason?: ZLinkSpotCloseReason, deadline?: Date): Promise<unknown>;
     cleanupFailedIncarnation(activation: ZLinkSpotActivation): Promise<void>;
-    dispatchActorPacket(activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    dispatchActorPacket(origin: ApplicationJobOrigin, activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     private runCreateLifecycle;
     private cleanupActivation;
     private runCleanup;