@zlink-systems/framework 0.30.0 → 0.30.1

package/src/runtime/messaging/packet-name.ts

@@ -1,3 +1,7 @@
+import {
+  readFrameworkPacketJsonContract,
+  normalizePacketName
+} from '@zlink-systems/stream-wire/internal/json';
 import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
 import type { ZLinkPacketJsonContract } from '../../contracts/Handlers/JsonContract';
 import { ZLinkConfigurationException } from '../configuration';
@@ -42,23 +46,7 @@ export function resolveFrameworkPacketJsonContract(
   return readFrameworkPacketJsonContract(constructor, explicitPacketName);
 }
 
-export function readFrameworkPacketJsonContract(
-  type: object,
-  explicitPacketName?: string
-): ZLinkPacketJsonContract | undefined {
-  const expectedPacketName = normalizePacketName(explicitPacketName);
-  for (const metadata of readZLinkDecoratorMetadata(type)) {
-    if (
-      metadata.kind === 'packet' &&
-      metadata.jsonContract !== undefined &&
-      (expectedPacketName === undefined ||
-        normalizePacketName(metadata.packetName) === expectedPacketName)
-    ) {
-      return metadata.jsonContract;
-    }
-  }
-  return undefined;
-}
+export { readFrameworkPacketJsonContract } from '@zlink-systems/stream-wire/internal/json';
 
 function tryDecoratorPacketName(payload: unknown): string | undefined {
   if (typeof payload !== 'object' || payload === null) {
@@ -86,11 +74,3 @@ function tryConstructorPacketName(payload: unknown): string | undefined {
   }
   return normalizePacketName(name);
 }
-
-function normalizePacketName(value: unknown): string | undefined {
-  if (typeof value !== 'string') {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : undefined;
-}

package/src/runtime/messaging/request-result.ts

@@ -0,0 +1,58 @@
+import type { ZLinkRequest } from '../../contracts/Handlers/Attributes';
+
+const completedAdmission = Promise.resolve();
+const ignoreAdmissionFailure = (): void => {};
+
+export function createZLinkRequest<TReply>(
+  start: (onAdmitted: () => void) => Promise<TReply>,
+  deliverReply?: (reply: Promise<TReply>) => Promise<TReply>
+): ZLinkRequest<TReply> {
+  let admitted: Promise<void> | undefined;
+  let resolveAdmission: (() => void) | undefined;
+  let rejectAdmission: ((error: unknown) => void) | undefined;
+  const confirmAdmission = (): void => {
+    admitted ??= completedAdmission;
+    resolveAdmission?.();
+  };
+  const failAdmission = (error: unknown): void => {
+    if (admitted === undefined) {
+      admitted = Promise.reject(error);
+      // Existing callers may observe only the reply Promise. Observing the
+      // rejection here leaves the public admission Promise rejected.
+      void admitted.catch(ignoreAdmissionFailure);
+    } else {
+      rejectAdmission?.(error);
+    }
+  };
+  const observeAdmission = (): Promise<void> => {
+    if (admitted === undefined) {
+      admitted = new Promise<void>((resolve, reject) => {
+        resolveAdmission = resolve;
+        rejectAdmission = reject;
+      });
+      void admitted.catch(ignoreAdmissionFailure);
+    }
+    return admitted;
+  };
+  let pending: Promise<TReply>;
+  try {
+    pending = start(confirmAdmission);
+  } catch (error) {
+    pending = Promise.reject(error);
+  }
+  const observed = pending.then(
+    (value) => {
+      // A successful reply proves admission even without an observation callback.
+      confirmAdmission();
+      return value;
+    },
+    (error: unknown) => {
+      failAdmission(error);
+      throw error;
+    }
+  );
+  const reply = deliverReply?.(observed) ?? observed;
+  return Object.defineProperty(reply, 'admitted', {
+    get: observeAdmission
+  }) as ZLinkRequest<TReply>;
+}

package/src/runtime/messaging/submission-result.ts

@@ -18,6 +18,10 @@ export interface ZLinkSubmitResult {
   readonly status: ZLinkSubmitStatus;
 }
 
+export const submittedResult: ZLinkSubmitResult = Object.freeze({
+  status: ZLinkSubmitStatus.Submitted
+});
+
 /** Projects typed submit failure; capacity refusal has no admission wait token. */
 export function submitToRequestResult(result: number, phase: 'submit' | 'completion'): number {
   switch (result) {
@@ -54,7 +58,7 @@ export function classifySubmitResult(
   const terminal = submitToRequestResult(result, phase);
   switch (terminal) {
     case RequestResult.Ok:
-      return { status: ZLinkSubmitStatus.Submitted };
+      return submittedResult;
     case RequestResult.TimedOut:
       return { status: ZLinkSubmitStatus.TimedOut };
     case RequestResult.NotFound:

package/src/runtime/protocol/service_wire_codec.generated.ts

@@ -7584,7 +7584,127 @@ function writeRelocationPendingTimerTickVector(input: RelocationPendingTimerTick
 export function decodeRelocationPendingTimerTickVector(bytes: Uint8Array, context: ServiceWireDecoderContext): RelocationPendingTimerTickVector { const reader = new Reader(bytes); const value = readRelocationPendingTimerTickVector(reader, context, {}, 0); reader.done("relocation-pending-timer-tick-vector"); return value; }
 export function encodeRelocationPendingTimerTickVector(value: RelocationPendingTimerTickVector, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeRelocationPendingTimerTickVector(value, writer, context, {}, 0); return writer.result(); }
 
-export type RelocationEnvelopeV1 = { readonly relocation: RelocationId; readonly object: RelocationObjectIdentity; readonly applicationVersion: ApplicationVersion; readonly applicationStates: RelocationParticipantApplicationStateVector; readonly savedWork: SavedWorkVector; readonly timerRegistrations: RelocationTimerRegistrationVector; readonly pendingTimerTicks: RelocationPendingTimerTickVector };
+export type RelocationSessionBinding = { readonly participantId: NonzeroU64; readonly sessionOwnerNodeRid: Rid; readonly sessionOwnerNodeGeneration: NonzeroU64; readonly sessionOwnerId: Text8; readonly sessionOwnerLeaseGeneration: NonzeroU64; readonly sessionRid: Rid; readonly bindingGeneration: NonzeroU64 };
+
+function readRelocationSessionBinding(reader: Reader, context: ServiceWireDecoderContext, enclosing: any, flags: number): RelocationSessionBinding {
+  void context; void enclosing; void flags;
+  const value: any = {};
+  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: IncrementalInput, context: ServiceWireDecoderContext, enclosing: any, flags: number): Generator<void, RelocationSessionBinding, void> {
+  void context; void enclosing; void flags;
+  const value: any = {};
+  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: RelocationSessionBinding, writer: Writer, context: ServiceWireDecoderContext, enclosing: any, flags: number): void {
+  void context; void enclosing; void flags; const value: any = 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);
+}
+export function decodeRelocationSessionBinding(bytes: Uint8Array, context: ServiceWireDecoderContext): RelocationSessionBinding { const reader = new Reader(bytes); const value = readRelocationSessionBinding(reader, context, {}, 0); reader.done("relocation-session-binding"); return value; }
+export function encodeRelocationSessionBinding(value: RelocationSessionBinding, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeRelocationSessionBinding(value, writer, context, {}, 0); return writer.result(); }
+
+export type RelocationSessionBindingVector = readonly RelocationSessionBinding[];
+
+function readRelocationSessionBindingVector(reader: Reader, context: ServiceWireDecoderContext, enclosing: any, flags: number): RelocationSessionBindingVector {
+  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: any = 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: IncrementalInput, context: ServiceWireDecoderContext, enclosing: any, flags: number): Generator<void, RelocationSessionBindingVector, void> {
+  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: any[] = []; 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: RelocationSessionBindingVector, writer: Writer, context: ServiceWireDecoderContext, enclosing: any, flags: number): void {
+  void context; void enclosing; void flags; const value: any = 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);
+}
+export function decodeRelocationSessionBindingVector(bytes: Uint8Array, context: ServiceWireDecoderContext): RelocationSessionBindingVector { const reader = new Reader(bytes); const value = readRelocationSessionBindingVector(reader, context, {}, 0); reader.done("relocation-session-binding-vector"); return value; }
+export function encodeRelocationSessionBindingVector(value: RelocationSessionBindingVector, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeRelocationSessionBindingVector(value, writer, context, {}, 0); return writer.result(); }
+
+export type RelocationEnvelopeV1 = { readonly relocation: RelocationId; readonly object: RelocationObjectIdentity; readonly applicationVersion: ApplicationVersion; readonly applicationStates: RelocationParticipantApplicationStateVector; readonly savedWork: SavedWorkVector; readonly timerRegistrations: RelocationTimerRegistrationVector; readonly pendingTimerTicks: RelocationPendingTimerTickVector; readonly sessionBindings: RelocationSessionBindingVector };
 
 function readRelocationEnvelopeV1(reader: Reader, context: ServiceWireDecoderContext, enclosing: any, flags: number): RelocationEnvelopeV1 {
   void context; void enclosing; void flags;
@@ -7610,6 +7730,9 @@ function readRelocationEnvelopeV1(reader: Reader, context: ServiceWireDecoderCon
   value["pendingTimerTicks"] = readRelocationPendingTimerTickVector(reader, context, value, flags);
 
 
+  value["sessionBindings"] = readRelocationSessionBindingVector(reader, context, value, flags);
+
+
 
 
   return value;
@@ -7638,6 +7761,9 @@ function* readIncrementalRelocationEnvelopeV1(reader: IncrementalInput, context:
   value["pendingTimerTicks"] = yield* readIncrementalRelocationPendingTimerTickVector(reader, context, value, flags);
 
 
+  value["sessionBindings"] = yield* readIncrementalRelocationSessionBindingVector(reader, context, value, flags);
+
+
 
 
   return value;
@@ -7674,6 +7800,10 @@ function writeRelocationEnvelopeV1(input: RelocationEnvelopeV1, writer: Writer,
 
 
   writeRelocationPendingTimerTickVector(value["pendingTimerTicks"], writer, context, value, flags);
+  if (value["sessionBindings"] === undefined) fail("sessionBindings required");
+
+
+  writeRelocationSessionBindingVector(value["sessionBindings"], writer, context, value, flags);
 }
 export function decodeRelocationEnvelopeV1(bytes: Uint8Array, context: ServiceWireDecoderContext): RelocationEnvelopeV1 { const reader = new Reader(bytes); const value = readRelocationEnvelopeV1(reader, context, {}, 0); reader.done("relocation-envelope-v1"); return value; }
 export function encodeRelocationEnvelopeV1(value: RelocationEnvelopeV1, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeRelocationEnvelopeV1(value, writer, context, {}, 0); return writer.result(); }

package/src/runtime/protocol/service_wire_pilot_codec.generated.ts

@@ -1,4 +1,4 @@
-// <auto-generated> DO NOT EDIT. schema-sha256: 818fcd2f767793be8b5f626e5ac688807e671e546af2b11786e6fbaa02010ba5
+// <auto-generated> DO NOT EDIT. schema-sha256: c9a343a64d205ce666d1e866df72538c11b3b52cf4bff41562e46d4aeaf20df6
 export interface ServiceWireRouteFence { readonly id: string; readonly generation: bigint; readonly targetNodeRid: Uint8Array; readonly targetNodeGeneration: bigint; readonly expectedAuthorityOwnerGeneration: bigint; readonly expectedOwnerLeaseGeneration: bigint; }
 	export interface ApplicationPayloadEnvelopeV1 { readonly packetName: string; readonly contentType: string; readonly payload: Uint8Array; }
 	export interface ActorJoin28 { readonly correlation: bigint; readonly actor: ServiceWireRouteFence; readonly entry: boolean; readonly targetSpot: ServiceWireRouteFence; readonly payload?: ApplicationPayloadEnvelopeV1; }
@@ -19,7 +19,7 @@ export interface ServiceWireRouteFence { readonly id: string; readonly generatio
 	export function encodeActorJoin28(value: ActorJoin28): readonly Uint8Array[] { const out=[90,77,1,28,0]; if(value.correlation===0n) throw new RangeError("correlation"); u64(out,value.correlation); fence(out,value.actor); out.push(value.entry?1:0); fence(out,value.targetSpot); return value.payload===undefined?[Uint8Array.from(out)]:[Uint8Array.from(out),encodePayload(value.payload)]; }
 	export function decodeActorJoin28(frames: readonly Uint8Array[]): ActorJoin28 { if(frames.length<1||frames.length>2)throw new RangeError("actorJoin frames");const bytes=frames[0]!; const at={value:0}; if(bytes.length<5 || bytes[at.value++]!==90 || bytes[at.value++]!==77 || bytes[at.value++]!==1 || bytes[at.value++]!==28 || bytes[at.value++]!==0) throw new RangeError("actorJoin header"); const correlation=read64(bytes,at); const actor=readFence(bytes,at); const entry=bytes[at.value++]; const targetSpot=readFence(bytes,at); if(correlation===0n || entry>1 || at.value!==bytes.length) throw new RangeError("actorJoin body"); const payload=frames.length===2?decodePayload(frames[1]!):undefined; return payload===undefined?{ correlation, actor, entry:entry===1, targetSpot }:{ correlation, actor, entry:entry===1, targetSpot,payload }; }
 export type RelocationObjectIdentity = { readonly objectKind:"actor";readonly actorId:string;readonly objectGeneration:bigint;readonly expectedAuthorityOwnerGeneration:bigint; }|{ readonly objectKind:"userSpot";readonly spotId:string;readonly objectGeneration:bigint;readonly expectedAuthorityOwnerGeneration:bigint; }|{ readonly objectKind:"instanceSpot";readonly instanceType:string;readonly spotId:string;readonly objectGeneration:bigint; };
-export interface RelocationEnvelopeV1 { readonly relocationHigh: bigint; readonly relocationLow: bigint; readonly object: RelocationObjectIdentity; readonly applicationVersion: bigint; readonly applicationStates: readonly { readonly participantId: bigint; readonly hasState: boolean; readonly payload: Uint8Array; }[]; readonly savedWork: readonly { readonly participantId: bigint; readonly order: bigint; readonly frozenRecord: Uint8Array; }[]; readonly timerRegistrations: readonly { readonly participantId: bigint; readonly name: string; readonly handlerType: string; readonly periodMilliseconds: bigint; readonly overrunPolicy: 1|2|3; readonly maxCatchUpTicks: bigint; readonly stopOnUnhandledException: boolean; readonly lastCompletedDeliveryIndex: bigint; readonly lastCompletedScheduledIndex: bigint; readonly nextScheduledAtUnixMilliseconds: bigint; }[]; readonly pendingTimerTicks: readonly { readonly participantId: bigint; readonly order: bigint; readonly timerName: string; readonly deliveryIndex: bigint; readonly scheduledIndex: bigint; readonly scheduledAtUnixMilliseconds: bigint; readonly skippedTicks: bigint; }[]; }
+export interface RelocationEnvelopeV1 { readonly relocationHigh: bigint; readonly relocationLow: bigint; readonly object: RelocationObjectIdentity; readonly applicationVersion: bigint; readonly applicationStates: readonly { readonly participantId: bigint; readonly hasState: boolean; readonly payload: Uint8Array; }[]; readonly savedWork: readonly { readonly participantId: bigint; readonly order: bigint; readonly frozenRecord: Uint8Array; }[]; readonly timerRegistrations: readonly { readonly participantId: bigint; readonly name: string; readonly handlerType: string; readonly periodMilliseconds: bigint; readonly overrunPolicy: 1|2|3; readonly maxCatchUpTicks: bigint; readonly stopOnUnhandledException: boolean; readonly lastCompletedDeliveryIndex: bigint; readonly lastCompletedScheduledIndex: bigint; readonly nextScheduledAtUnixMilliseconds: bigint; }[]; readonly pendingTimerTicks: readonly { readonly participantId: bigint; readonly order: bigint; readonly timerName: string; readonly deliveryIndex: bigint; readonly scheduledIndex: bigint; 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;readonly data:Uint8Array; }
 export interface RelocationChunkEntryV1 { readonly order:number;readonly reference:string;readonly length:bigint;readonly checksumCrc32c:number; }
 export interface RelocationManifestV1 { readonly logicalFormatVersion:1;readonly totalLength:bigint;readonly totalChecksumCrc32c:number;readonly inventoryDigestSha256:Uint8Array;readonly chunks:readonly RelocationChunkEntryV1[]; }
@@ -51,8 +51,8 @@ function skipFrozenRecord(bytes:Uint8Array,at:{value:number}):void{const kind=re
 function compareUtf8(a:string,b:string):number{const x=text.encode(a),y=text.encode(b),n=Math.min(x.length,y.length);for(let i=0;i<n;i++)if(x[i]!==y[i])return x[i]!-y[i]!;return x.length-y.length;}
 function writeRelocationObject(out:number[],value:RelocationObjectIdentity):void{const kind=value.objectKind==="actor"?1:value.objectKind==="userSpot"?2:3;out.push(kind);body16(out,b=>{if(value.objectKind==="actor"){text8(b,value.actorId);if(value.objectGeneration===0n||value.expectedAuthorityOwnerGeneration===0n)throw new RangeError("object");u64(b,value.objectGeneration);u64(b,value.expectedAuthorityOwnerGeneration);}else if(value.objectKind==="userSpot"){text8(b,value.spotId);if(value.objectGeneration===0n||value.expectedAuthorityOwnerGeneration===0n)throw new RangeError("object");u64(b,value.objectGeneration);u64(b,value.expectedAuthorityOwnerGeneration);}else{text8(b,value.instanceType);text8(b,value.spotId);if(value.objectGeneration===0n)throw new RangeError("object");u64(b,value.objectGeneration);}});}
 function readRelocationObject(bytes:Uint8Array,at:{value:number}):RelocationObjectIdentity{const kind=read8(bytes,at),end=boundedEnd(bytes,at,read16(bytes,at),"relocation object");let value:RelocationObjectIdentity;if(kind===1)value={objectKind:"actor",actorId:readText8(bytes,at),objectGeneration:nonzero64(bytes,at,"object generation"),expectedAuthorityOwnerGeneration:nonzero64(bytes,at,"authority generation")};else if(kind===2)value={objectKind:"userSpot",spotId:readText8(bytes,at),objectGeneration:nonzero64(bytes,at,"object generation"),expectedAuthorityOwnerGeneration:nonzero64(bytes,at,"authority generation")};else if(kind===3)value={objectKind:"instanceSpot",instanceType:readText8(bytes,at),spotId:readText8(bytes,at),objectGeneration:nonzero64(bytes,at,"object generation")};else throw new RangeError("object kind");exactEnd(at,end,"relocation object");return value;}
-export function encodeRelocationEnvelopeV1(value:RelocationEnvelopeV1):Uint8Array{const out:number[]=[];if(value.relocationHigh===0n&&value.relocationLow===0n)throw new RangeError("relocation");u64(out,value.relocationHigh);u64(out,value.relocationLow);writeRelocationObject(out,value.object);if(value.applicationVersion<0n||value.applicationVersion>9223372036854775807n)throw new RangeError("application version");u64(out,value.applicationVersion);sorted(value.applicationStates,(a,b)=>a.participantId<b.participantId?-1:a.participantId>b.participantId?1:0,"applicationStates");if(value.applicationStates.length===0)throw new RangeError("applicationStates");u32(out,value.applicationStates.length);for(const s of value.applicationStates){if(s.participantId===0n)throw new RangeError("participant");u64(out,s.participantId);out.push(s.hasState?1:0);body64(out,b=>{if(s.hasState)bytes64(b,s.payload);else if(s.payload.length!==0)throw new RangeError("absent state payload");});}sorted(value.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");u32(out,value.savedWork.length);for(const w of value.savedWork){if(w.participantId===0n||w.order===0n)throw new RangeError("saved work");const at={value:0};skipFrozenRecord(w.frozenRecord,at);exactEnd(at,w.frozenRecord.length,"frozen record");u64(out,w.participantId);u64(out,w.order);appendBytes(out,w.frozenRecord);}sorted(value.timerRegistrations,(a,b)=>a.participantId===b.participantId?compareUtf8(a.name,b.name):a.participantId<b.participantId?-1:1,"timerRegistrations");u32(out,value.timerRegistrations.length);for(const t of value.timerRegistrations){if(t.participantId===0n||t.periodMilliseconds===0n||t.maxCatchUpTicks===0n||t.overrunPolicy<1||t.overrunPolicy>3)throw new RangeError("timer");u64(out,t.participantId);text8(out,t.name);text8(out,t.handlerType);u64(out,t.periodMilliseconds);out.push(t.overrunPolicy);u64(out,t.maxCatchUpTicks);out.push(t.stopOnUnhandledException?1:0);u64(out,t.lastCompletedDeliveryIndex);u64(out,t.lastCompletedScheduledIndex);u64(out,t.nextScheduledAtUnixMilliseconds);}sorted(value.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");u32(out,value.pendingTimerTicks.length);for(const p of value.pendingTimerTicks){if(p.participantId===0n||p.order===0n||p.deliveryIndex===0n||p.scheduledIndex===0n)throw new RangeError("pending timer");u64(out,p.participantId);u64(out,p.order);text8(out,p.timerName);u64(out,p.deliveryIndex);u64(out,p.scheduledIndex);u64(out,p.scheduledAtUnixMilliseconds);u64(out,p.skippedTicks);}if(out.length>274877906944)throw new RangeError("relocation logical bytes");return Uint8Array.from(out);}
-export function decodeRelocationEnvelopeV1(chunks:readonly Uint8Array[]):RelocationEnvelopeV1{const n=chunks.reduce((s,c)=>s+c.length,0);if(n>274877906944)throw new RangeError("relocation logical bytes");const bytes=new Uint8Array(n);let offset=0;for(const c of chunks){bytes.set(c,offset);offset+=c.length;}const at={value:0},relocationHigh=read64(bytes,at),relocationLow=read64(bytes,at);if(relocationHigh===0n&&relocationLow===0n)throw new RangeError("relocation");const object=readRelocationObject(bytes,at),applicationVersion=read64(bytes,at);if(applicationVersion>9223372036854775807n)throw new RangeError("application version");const applicationStates:RelocationEnvelopeV1["applicationStates"][number][]=[];const stateCount=read32(bytes,at);if(stateCount===0)throw new RangeError("applicationStates");for(let i=0,count=stateCount;i<count;i++){const participantId=nonzero64(bytes,at,"participant"),has=read8(bytes,at),end=boundedEnd(bytes,at,Number(read64(bytes,at)),"application state");if(has>1)throw new RangeError("application state");let payload=new Uint8Array();if(has===1)payload=take(bytes,at,Number(read64(bytes,at)),"state payload");exactEnd(at,end,"application state");applicationStates.push({participantId,hasState:has===1,payload});}const participants=new Set(applicationStates.map((s)=>s.participantId));const savedWork:RelocationEnvelopeV1["savedWork"][number][]=[];for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("saved work participant");const order=nonzero64(bytes,at,"order"),start=at.value;skipFrozenRecord(bytes,at);savedWork.push({participantId,order,frozenRecord:bytes.slice(start,at.value)});}const timerRegistrations:RelocationEnvelopeV1["timerRegistrations"][number][]=[],registeredTimerNames=new Map<bigint,Set<string>>();for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("timer participant");const name=readText8(bytes,at),handlerType=readText8(bytes,at),periodMilliseconds=nonzero64(bytes,at,"period"),overrunPolicy=read8(bytes,at);if(overrunPolicy<1||overrunPolicy>3)throw new RangeError("overrun policy");const maxCatchUpTicks=nonzero64(bytes,at,"catch-up"),stop=read8(bytes,at);if(stop>1)throw new RangeError("stop flag");let names=registeredTimerNames.get(participantId);if(names===undefined){names=new Set<string>();registeredTimerNames.set(participantId,names);}names.add(name);timerRegistrations.push({participantId,name,handlerType,periodMilliseconds,overrunPolicy:overrunPolicy as 1|2|3,maxCatchUpTicks,stopOnUnhandledException:stop===1,lastCompletedDeliveryIndex:read64(bytes,at),lastCompletedScheduledIndex:read64(bytes,at),nextScheduledAtUnixMilliseconds:read64(bytes,at)});}const pendingTimerTicks:RelocationEnvelopeV1["pendingTimerTicks"][number][]=[];for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("pending timer participant");const order=nonzero64(bytes,at,"order"),timerName=readText8(bytes,at);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};}
+export function encodeRelocationEnvelopeV1(value:RelocationEnvelopeV1):Uint8Array{const out:number[]=[];if(value.relocationHigh===0n&&value.relocationLow===0n)throw new RangeError("relocation");u64(out,value.relocationHigh);u64(out,value.relocationLow);writeRelocationObject(out,value.object);if(value.applicationVersion<0n||value.applicationVersion>9223372036854775807n)throw new RangeError("application version");u64(out,value.applicationVersion);sorted(value.applicationStates,(a,b)=>a.participantId<b.participantId?-1:a.participantId>b.participantId?1:0,"applicationStates");if(value.applicationStates.length===0)throw new RangeError("applicationStates");u32(out,value.applicationStates.length);for(const s of value.applicationStates){if(s.participantId===0n)throw new RangeError("participant");u64(out,s.participantId);out.push(s.hasState?1:0);body64(out,b=>{if(s.hasState)bytes64(b,s.payload);else if(s.payload.length!==0)throw new RangeError("absent state payload");});}sorted(value.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");u32(out,value.savedWork.length);for(const w of value.savedWork){if(w.participantId===0n||w.order===0n)throw new RangeError("saved work");const at={value:0};skipFrozenRecord(w.frozenRecord,at);exactEnd(at,w.frozenRecord.length,"frozen record");u64(out,w.participantId);u64(out,w.order);appendBytes(out,w.frozenRecord);}sorted(value.timerRegistrations,(a,b)=>a.participantId===b.participantId?compareUtf8(a.name,b.name):a.participantId<b.participantId?-1:1,"timerRegistrations");u32(out,value.timerRegistrations.length);for(const t of value.timerRegistrations){if(t.participantId===0n||t.periodMilliseconds===0n||t.maxCatchUpTicks===0n||t.overrunPolicy<1||t.overrunPolicy>3)throw new RangeError("timer");u64(out,t.participantId);text8(out,t.name);text8(out,t.handlerType);u64(out,t.periodMilliseconds);out.push(t.overrunPolicy);u64(out,t.maxCatchUpTicks);out.push(t.stopOnUnhandledException?1:0);u64(out,t.lastCompletedDeliveryIndex);u64(out,t.lastCompletedScheduledIndex);u64(out,t.nextScheduledAtUnixMilliseconds);}sorted(value.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");u32(out,value.pendingTimerTicks.length);for(const p of value.pendingTimerTicks){if(p.participantId===0n||p.order===0n||p.deliveryIndex===0n||p.scheduledIndex===0n)throw new RangeError("pending timer");u64(out,p.participantId);u64(out,p.order);text8(out,p.timerName);u64(out,p.deliveryIndex);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);}
+export function decodeRelocationEnvelopeV1(chunks:readonly Uint8Array[]):RelocationEnvelopeV1{const n=chunks.reduce((s,c)=>s+c.length,0);if(n>274877906944)throw new RangeError("relocation logical bytes");const bytes=new Uint8Array(n);let offset=0;for(const c of chunks){bytes.set(c,offset);offset+=c.length;}const at={value:0},relocationHigh=read64(bytes,at),relocationLow=read64(bytes,at);if(relocationHigh===0n&&relocationLow===0n)throw new RangeError("relocation");const object=readRelocationObject(bytes,at),applicationVersion=read64(bytes,at);if(applicationVersion>9223372036854775807n)throw new RangeError("application version");const applicationStates:RelocationEnvelopeV1["applicationStates"][number][]=[];const stateCount=read32(bytes,at);if(stateCount===0)throw new RangeError("applicationStates");for(let i=0,count=stateCount;i<count;i++){const participantId=nonzero64(bytes,at,"participant"),has=read8(bytes,at),end=boundedEnd(bytes,at,Number(read64(bytes,at)),"application state");if(has>1)throw new RangeError("application state");let payload=new Uint8Array();if(has===1)payload=take(bytes,at,Number(read64(bytes,at)),"state payload");exactEnd(at,end,"application state");applicationStates.push({participantId,hasState:has===1,payload});}const participants=new Set(applicationStates.map((s)=>s.participantId));const savedWork:RelocationEnvelopeV1["savedWork"][number][]=[];for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("saved work participant");const order=nonzero64(bytes,at,"order"),start=at.value;skipFrozenRecord(bytes,at);savedWork.push({participantId,order,frozenRecord:bytes.slice(start,at.value)});}const timerRegistrations:RelocationEnvelopeV1["timerRegistrations"][number][]=[],registeredTimerNames=new Map<bigint,Set<string>>();for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("timer participant");const name=readText8(bytes,at),handlerType=readText8(bytes,at),periodMilliseconds=nonzero64(bytes,at,"period"),overrunPolicy=read8(bytes,at);if(overrunPolicy<1||overrunPolicy>3)throw new RangeError("overrun policy");const maxCatchUpTicks=nonzero64(bytes,at,"catch-up"),stop=read8(bytes,at);if(stop>1)throw new RangeError("stop flag");let names=registeredTimerNames.get(participantId);if(names===undefined){names=new Set<string>();registeredTimerNames.set(participantId,names);}names.add(name);timerRegistrations.push({participantId,name,handlerType,periodMilliseconds,overrunPolicy:overrunPolicy as 1|2|3,maxCatchUpTicks,stopOnUnhandledException:stop===1,lastCompletedDeliveryIndex:read64(bytes,at),lastCompletedScheduledIndex:read64(bytes,at),nextScheduledAtUnixMilliseconds:read64(bytes,at)});}const pendingTimerTicks:RelocationEnvelopeV1["pendingTimerTicks"][number][]=[];for(let i=0,count=read32(bytes,at);i<count;i++){const participantId=nonzero64(bytes,at,"participant");if(!participants.has(participantId))throw new RangeError("pending timer participant");const order=nonzero64(bytes,at,"order"),timerName=readText8(bytes,at);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)});}const sessionBindings:RelocationEnvelopeV1["sessionBindings"][number][]=[];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:Uint8Array):number{let crc=0xffffffff;for(const octet of bytes){crc^=octet;for(let bit=0;bit<8;bit++)crc=(crc>>>1)^((crc&1)!==0?0x82f63b78:0);}return(~crc)>>>0;}
 function encodeDurable(magic:readonly number[],body:readonly number[],maximum:number):Uint8Array{const out=[...magic,1,0,0];u32(out,body.length);appendBytes(out,body);if(out.length+4>maximum)throw new RangeError("durable format bytes");u32(out,crc32c(Uint8Array.from(out)));return Uint8Array.from(out);}
 function decodeDurable(bytes:Uint8Array,magic:readonly number[],maximum:number):Uint8Array{if(bytes.length>maximum||bytes.length<15||magic.some((v,i)=>bytes[i]!==v)||bytes[4]!==1||bytes[5]!==0||bytes[6]!==0)throw new RangeError("durable header");const at={value:7},length=read32(bytes,at),end=boundedEnd(bytes,at,length,"durable body");if(end+4!==bytes.length)throw new RangeError("durable length");const body=bytes.slice(at.value,end);at.value=end;const expected=read32(bytes,at);if(crc32c(bytes.slice(0,end))!==expected)throw new RangeError("durable checksum");return body;}

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

@@ -33,7 +33,14 @@ function objectKey(actorId: string, objectGeneration: bigint): string {
 }
 
 export type ZLinkFormalRemoteActorAdmissionState =
-  'provisional' | 'admitting' | 'admitted' | 'rejected' | 'committed' | 'aborted' | 'failed';
+  | 'provisional'
+  | 'admitting'
+  | 'admitted'
+  | 'restoring'
+  | 'rejected'
+  | 'committed'
+  | 'aborted'
+  | 'failed';
 
 export interface ZLinkFormalRemoteActorAdmission {
   readonly actorId: string;
@@ -78,7 +85,7 @@ export interface ZLinkFormalRemoteActorAdmissionRecord {
 }
 
 interface ZLinkFormalRemoteActorAdmissionEntry extends ZLinkFormalRemoteActorAdmissionRecord {
-  readonly timer: ReturnType<typeof setTimeout>;
+  timer: ReturnType<typeof setTimeout>;
   readonly resolveResult: (result: ZLinkFormalRemoteActorAdmissionResult) => void;
   admission: ZLinkFormalRemoteActorAdmission;
   state: ZLinkFormalRemoteActorAdmissionState;
@@ -107,6 +114,35 @@ export class ZLinkFormalRemoteActorAdmissionRegistry {
     return this.admissions.get(transferId);
   }
 
+  /** PREPARE transfers prepared resources to the target attempt until its terminal. */
+  beginRestore(transferId: string): void {
+    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: string): void {
+    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);
+    }
+  }
+
+  private scheduleExpiry(transferId: string): ReturnType<typeof setTimeout> {
+    const timer = setTimeout(() => this.delete(transferId), ADMISSION_RETENTION_MS);
+    timer.unref();
+    return timer;
+  }
+
   begin(input: ZLinkFormalRemoteActorAdmission): {
     readonly record: ZLinkFormalRemoteActorAdmissionEntry;
     readonly created: boolean;
@@ -182,10 +218,7 @@ export class ZLinkFormalRemoteActorAdmissionRegistry {
     const resultTask = new Promise<ZLinkFormalRemoteActorAdmissionResult>((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,
@@ -309,7 +342,7 @@ export class ZLinkFormalRemoteActorAdmissionRegistry {
   markCommitted(transferId: string, actor: ZLinkActor): void {
     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';
@@ -320,7 +353,7 @@ export class ZLinkFormalRemoteActorAdmissionRegistry {
     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
@@ -354,7 +387,7 @@ export class ZLinkFormalRemoteActorAdmissionRegistry {
    */
   delete(transferId: string): void {
     const pending = this.admissions.get(transferId);
-    if (pending === undefined) return;
+    if (pending === undefined || pending.state === 'restoring') return;
     clearTimeout(pending.timer);
     this.admissions.delete(transferId);
     this.failParked(pending);
@@ -369,20 +402,7 @@ function sameAdmission(
   left: ZLinkFormalRemoteActorAdmission,
   right: ZLinkFormalRemoteActorAdmission
 ): boolean {
-  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(

package/src/runtime/spots/index.ts

@@ -215,6 +215,7 @@ export interface ZLinkSpotManagerOptions {
     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>
@@ -408,6 +409,7 @@ export class DefaultZLinkSpotManager {
       nodeRid: options.nodeRid,
       nodeRidProvider: options.nodeRidProvider,
       actorCountProvider: options.actorCountProvider,
+      releaseActorMembers: options.releaseActorMembers,
       userSpotExecutionMode: options.userSpotExecutionMode,
       userSpotRelocationCoordinationMode: options.userSpotRelocationCoordinationMode,
       channelClient: options.channelClient,
@@ -1620,6 +1622,7 @@ export class DefaultZLinkSpotManager {
       readonly workOptions?: import('../execution/serial-execution-queue').ZLinkSerialWorkOptions;
       readonly admissionTimeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply> {
     return await this.routedSpotPackets.request<TReply>(spotId, packetName, request, context);
@@ -3075,7 +3078,7 @@ export 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;
@@ -3135,6 +3138,11 @@ export class DefaultZLinkSpotManager {
     return true;
   }
 
+  beginActorJoinRelocation(relocationId: string): () => void {
+    this.formalRemoteActorAdmissions.beginRestore(relocationId);
+    return () => this.formalRemoteActorAdmissions.finishRestore(relocationId);
+  }
+
   async restoreCanonicalActorJoinRecovery(
     recovery: CanonicalActorJoinRecovery,
     signal?: AbortSignal
@@ -3147,7 +3155,11 @@ export class DefaultZLinkSpotManager {
       );
     }
     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.`
       );

package/src/runtime/spots/spot-activation.ts

@@ -101,6 +101,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>
@@ -215,7 +216,10 @@ export class ZLinkSpotActivationLifecycle {
     );
     const serialExecutor = new ZLinkSpotSerialExecutor(serial, executionMode, spotId);
     const actorHandlers = new ZLinkSpotActorHandlerRegistryRuntime();
-    const handlers = new DefaultZLinkSpotHandlerRegistry(actorHandlers);
+    const handlers = new DefaultZLinkSpotHandlerRegistry(
+      actorHandlers,
+      this.options.providerResolver
+    );
     applySpotHandlerRegistrations(
       handlers,
       implementation as unknown as Type<ZLinkSpot>,
@@ -381,7 +385,10 @@ export class ZLinkSpotActivationLifecycle {
       spotId
     );
     const actorHandlers = new ZLinkSpotActorHandlerRegistryRuntime();
-    const handlers = new DefaultZLinkSpotHandlerRegistry(actorHandlers);
+    const handlers = new DefaultZLinkSpotHandlerRegistry(
+      actorHandlers,
+      this.options.providerResolver
+    );
     const instanceHandlers = new DefaultZLinkInstanceSpotHandlerRegistry(handlers);
     applySpotHandlerRegistrations(handlers, implementation as unknown as Type<ZLinkSpot>, {
       packetHandlers: this.options.spotPacketHandlers
@@ -533,7 +540,10 @@ export class ZLinkSpotActivationLifecycle {
     );
     const serialExecutor = new ZLinkSpotSerialExecutor(serial, executionMode, spotId);
     const actorHandlers = new ZLinkSpotActorHandlerRegistryRuntime();
-    const handlers = new DefaultZLinkSpotHandlerRegistry(actorHandlers);
+    const handlers = new DefaultZLinkSpotHandlerRegistry(
+      actorHandlers,
+      this.options.providerResolver
+    );
     applySpotHandlerRegistrations(handlers, spotType, {
       actorSendHandlers: this.options.spotActorSendHandlers,
       actorRequestHandlers: this.options.spotActorRequestHandlers,
@@ -1049,10 +1059,12 @@ export class ZLinkSpotActivationLifecycle {
       } catch (error) {
         // An OnClosing failure is diagnostic and cleanup continues. It is
         // returned so host shutdown can classify its teardown outcome.
-        this.options.closeErrorSink?.reportRuntimeTaskException(
-          `spot ${String(activation.spotId)} onClosing`,
-          error
-        );
+        if (reason !== ZLinkSpotCloseReason.HostShutdown) {
+          this.options.closeErrorSink?.reportRuntimeTaskException(
+            `spot ${String(activation.spotId)} onClosing`,
+            error
+          );
+        }
         closingFailure = error;
       }
     }
@@ -1093,7 +1105,12 @@ export class ZLinkSpotActivationLifecycle {
     }
     if (!state.nativeDisposed) {
       await cleanup(
-        () => activation.nativeSpot?.dispose(),
+        async () => {
+          if (reason === ZLinkSpotCloseReason.HostShutdown) {
+            await this.options.releaseActorMembers?.(locationMeshName, activation.spotId);
+          }
+          await activation.nativeSpot?.dispose();
+        },
         () => {
           state.nativeDisposed = true;
         }
@@ -1121,8 +1138,9 @@ export class ZLinkSpotActivationLifecycle {
         }
       );
     }
-    if (errors.length === 1) throw errors[0];
-    if (errors.length > 1) {
+    if (errors.length > 0) {
+      if (closingFailure !== undefined) errors.unshift(closingFailure);
+      if (errors.length === 1) throw errors[0];
       throw new AggregateError(errors, `Spot '${activation.spotId}' cleanup failed.`);
     }
     return closingFailure;