@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,3 +1,4 @@
+import { createZLinkRequest } from '../messaging/request-result';
 import {
   type RoutingId,
   type ZLinkChannelClient,
@@ -174,6 +175,7 @@ export class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
 }
 
 export interface ZLinkSpotAddressCallOptions {
+  readonly onAdmitted?: () => void;
   readonly metadata?: ReadonlyMap<string, string>;
   readonly instanceSpot: boolean;
   readonly instanceSpotType?: string;
@@ -232,6 +234,7 @@ export interface ZLinkSpotRoutedSendOptions {
 }
 
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+  readonly onAdmitted?: () => void;
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal;
 }
@@ -308,14 +311,13 @@ function createAddressedSpotRequestCall(
   sourceSpotProvider?: () => ZLinkBackendSpot | undefined
 ): ZLinkSpotRequestCall {
   const options = newAddressCallOptions();
-  const begin = <TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal) => {
-    markSubmitted(options);
-    rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) => {
     return startRequestOnSerial<TReply>(serial, () => ({
       pending: transport.requestToSpotAddress<TReply>(spotId, request, {
         ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
         timeoutMs: options.timeoutMs,
-        signal
+        signal,
+        onAdmitted
       })
     }));
   };
@@ -356,13 +358,19 @@ function createAddressedSpotRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>('async', signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      markSubmitted(options);
+      rejectSameSpotAsyncRequest(serial, spotId, 'async');
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
-      const pending = begin<TReply>('yield', signal);
-      return turn.yieldPromise(pending);
+      markSubmitted(options);
+      rejectSameSpotAsyncRequest(serial, spotId, 'yield');
+      const pending = begin<TReply>(signal);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }
@@ -475,8 +483,12 @@ function wrapRequestCall(
   serial: ZLinkSpotSerialTurnExecutor,
   inner: ZLinkChannelRequestCall
 ): ZLinkChannelRequestCall {
-  const begin = <TReply>(signal?: AbortSignal) =>
-    startRequestOnSerial(serial, () => ({ pending: inner.submit<TReply>(signal) }));
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) =>
+    startRequestOnSerial(serial, () => {
+      const pending = inner.submit<TReply>(signal);
+      if (onAdmitted !== undefined) void pending.admitted.then(onAdmitted, () => undefined);
+      return { pending };
+    });
   return {
     metadata(key: string | ZLinkMessageMetadata, value?: string) {
       if (typeof key === 'string') inner.metadata(key, value!);
@@ -488,13 +500,15 @@ function wrapRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>(signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
       const pending = begin<TReply>(signal);
-      return turn.yieldPromise(pending);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }
@@ -571,15 +585,15 @@ function wrapRoutedSpotRequestCall(
 ): ZLinkRequestCall & Pick<ZLinkChannelRequestCall, 'yield'> {
   let selectedTimeoutMs: number | undefined;
   const metadata = new Map<string, string>();
-  const begin = <TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal) => {
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) => {
     // A request to the current Spot would wait behind the handler that owns
     // the same Spot claim. Reject it before resolving a route or submitting
     // transport work; one-way self-send remains a valid FIFO admission.
-    rejectSameSpotAsyncRequest(serial, spot.spotId, waitPolicy);
     return startRequestOnSerial<TReply>(serial, () => ({
       pending: requestToSpotHandle<TReply>(transport, spot, request, {
         timeoutMs: selectedTimeoutMs,
         signal,
+        onAdmitted,
         metadata,
         spotRouterChannelIdForMesh,
         sourceSpot: sourceSpotProvider?.()
@@ -602,13 +616,17 @@ function wrapRoutedSpotRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>('async', signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      rejectSameSpotAsyncRequest(serial, spot.spotId, 'async');
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
-      const pending = begin<TReply>('yield', signal);
-      return turn.yieldPromise(pending);
+      rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
+      const pending = begin<TReply>(signal);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }
@@ -628,6 +646,7 @@ function rejectSameSpotAsyncRequest(
 }
 
 export interface ZLinkSpotHandleCallOptions {
+  readonly onAdmitted?: () => void;
   readonly metadata?: ReadonlyMap<string, string>;
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal;
@@ -672,6 +691,7 @@ export async function requestToSpotHandle<TReply = unknown>(
       packetName,
       timeoutMs: options.timeoutMs,
       signal: options.signal,
+      onAdmitted: options.onAdmitted,
       metadata: options.metadata
     };
     if (options.sourceSpot !== undefined && transport.requestFromSpotToSpot !== undefined) {

package/src/runtime/spots/spot-remote-codec.ts

@@ -8,7 +8,7 @@ import type { Message } from '../../contracts/Common/Message';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import { decodeChannelEnvelope } from '../channels/channel-envelope';
-import { decodeRoutingId as decodeWireRoutingId } from '../routing-id';
+import { decodeRoutingId as decodeWireRoutingId, routingIdsEqual } from '../routing-id';
 import {
   REMOTE_ACTOR_JOIN_PACKET,
   type ZLinkRemoteActorJoinWirePayload
@@ -176,7 +176,14 @@ export function decodeHandoffBacklog(value: unknown): readonly ZLinkActorHandoff
           BigInt(source.ownerLeaseGeneration) <= 0n ||
           source.nodeRid.length === 0 ||
           BigInt(source.nodeGeneration) <= 0n ||
-          source.replyRouteId !== messageFollowContext.replyRouteId)) ||
+          source.replyRouteId !==
+            (packet.messageFollowOrigin !== undefined &&
+            routingIdsEqual(
+              decodeWireRoutingId(source.nodeRid, source.nodeRidHex),
+              packet.messageFollowOrigin.sourceNodeRid
+            )
+              ? packet.messageFollowOrigin.originalReplyRouteId.toString()
+              : messageFollowContext.replyRouteId))) ||
       (!packet.returnResponse && source !== undefined)
     ) {
       throw new Error('Remote actor handoff request source fence is invalid.');

package/src/runtime/spots/spot-routed-spot-packet-dispatch.ts

@@ -50,6 +50,7 @@ interface ZLinkRoutedSpotPacketDispatchOptions {
 
 interface ZLinkRoutedSpotPacketContext {
   readonly channelName: string;
+  readonly onAdmitted?: () => void;
   readonly contentType?: string;
   readonly workOptions?: ZLinkSerialWorkOptions;
   readonly admissionTimeoutMs?: number;
@@ -265,7 +266,7 @@ export class ZLinkRoutedSpotPacketDispatch {
         }
         await activation.serial.execute(
           runHandler,
-          context.workOptions,
+          { ...context.workOptions, onAdmitted: context.onAdmitted },
           instanceIntent ? runHandler : undefined
         );
       }

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

@@ -22,6 +22,7 @@ import type {
 import type { ZLinkBackendSpotNode } from '../backend/contracts';
 
 export interface ZLinkEntryActorRuntime {
+  releaseMembers?(meshName: string): Promise<void>;
   resolveActor(actorId: string): ZLinkActor | undefined;
   commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
   destroyActor(
@@ -91,7 +92,6 @@ export interface ZLinkSpotActorTransferRuntime {
   commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
   clearRoutedActor(actor: ZLinkActor): void;
   rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
-  notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
   actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
 }
 

package/src/runtime/spots/spot-serial-executor.ts

@@ -1,13 +1,24 @@
 import { ZLinkUserSpotExecutionMode } from '../../contracts';
 import { ZLinkActorSerialExecutor } from '../actors';
-import type { ZLinkExecutionBarrier } from '../execution';
+import type {
+  ZLinkActorHandoffDispatch,
+  ZLinkActorHandoffPrefixAdmission,
+  ZLinkActorHandoffPrefixRecord
+} from '../actors/actor-handoff';
+import type { ZLinkExecutionBarrier, ZLinkExecutionBarrierSeal } from '../execution';
 import type {
   ZLinkSerialSchedulerOptions,
-  ZLinkSerialWorkPreparation,
   ZLinkSerialWorkOptions
 } from '../execution/serial-execution-queue';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 
+export type ZLinkSpotPreparationCompletion = 'publication' | 'first-terminal';
+
+export type ZLinkActorPacketTurnDispatch = (
+  serial: ZLinkSpotSerialTurnExecutor,
+  ...args: Parameters<ZLinkActorHandoffDispatch>
+) => ReturnType<ZLinkActorHandoffDispatch>;
+
 /**
  * Owns every application serial unit that belongs to one Spot activation.
  *
@@ -21,6 +32,11 @@ export class ZLinkSpotSerialExecutor {
   private executionBarrier: ZLinkExecutionBarrier | undefined;
   private closing = false;
   private closePromise: Promise<void> | undefined;
+  private preparation?: {
+    readonly seal: ZLinkExecutionBarrierSeal;
+    readonly complete: (terminal?: () => Promise<void>) => void;
+    readonly execution: Promise<void>;
+  };
 
   constructor(
     private readonly spotSerial: ZLinkSpotSerialTurnExecutor,
@@ -39,6 +55,54 @@ export class ZLinkSpotSerialExecutor {
     for (const serial of this.timerSerials.values()) serial.setExecutionBarrier(barrier);
   }
 
+  get isPreparing(): boolean {
+    return this.preparation !== undefined;
+  }
+
+  beginPreparation(kind: 'activation' | 'relocation' = 'activation'): void {
+    if (this.preparation !== undefined || this.executionBarrier === undefined)
+      throw new Error('Activation preparation requires one unowned execution barrier.');
+    const barrier = this.executionBarrier;
+    const seal = barrier.seal(kind);
+    let complete!: (terminal?: () => Promise<void>) => void;
+    const terminal = new Promise<(() => Promise<void>) | undefined>((resolve) => {
+      complete = resolve;
+    });
+    // The staging seal itself owns target preparation. No normal preparation
+    // item is admitted in addition to this lifecycle owner.
+    const execution = this.spotSerial.executeControlLifecycleOperation(
+      async () => {
+        const finish = await terminal;
+        await finish?.();
+      },
+      {
+        canExecuteApplication: (record) => record.context === undefined || !barrier.isCurrent(seal)
+      }
+    );
+    this.preparation = { seal, complete, execution };
+  }
+
+  openPreparationAdmission(): void {
+    if (this.preparation !== undefined) this.executionBarrier!.abort(this.preparation.seal);
+  }
+
+  async finishPreparation(terminal?: () => Promise<void>): Promise<void> {
+    const preparation = this.preparation;
+    if (preparation === undefined) {
+      await terminal?.();
+      return;
+    }
+    preparation.complete(terminal);
+    try {
+      await preparation.execution;
+    } finally {
+      if (this.preparation === preparation) {
+        this.executionBarrier!.abort(preparation.seal);
+        this.preparation = undefined;
+      }
+    }
+  }
+
   executeSpot<T>(
     operation: () => Promise<T> | T,
     workOptions?: ZLinkSerialWorkOptions
@@ -55,35 +119,43 @@ export class ZLinkSpotSerialExecutor {
     return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
   }
 
-  /** @internal Restores a durable Actor FIFO prefix without starting it. */
-  admitActorDurablePrefix(
+  executeTimer<T>(
+    timerName: string,
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    return this.timerSerial(timerName).post(operation, workOptions);
+  }
+
+  /** Admits held packets through the same Actor FIFO as ordinary ingress. */
+  admitActorPacketPrefix(
     actorId: string,
-    records: readonly {
-      readonly operation: (
-        executeChild: <TChild>(
-          child: (serial: ZLinkSpotSerialTurnExecutor) => Promise<TChild> | TChild
-        ) => Promise<TChild>
-      ) => Promise<void>;
-      readonly preparation?: ZLinkSerialWorkPreparation;
-      readonly workOptions?: ZLinkSerialWorkOptions;
-    }[]
-  ): readonly Promise<void>[] {
+    records: readonly ZLinkActorHandoffPrefixRecord[],
+    dispatch: ZLinkActorPacketTurnDispatch
+  ): ZLinkActorHandoffPrefixAdmission {
     const serial = this.actorSerial(actorId);
-    return this.actorExecutor(actorId).admitDurablePrefix(
+    const terminals = this.actorExecutor(actorId).admitDurablePrefix(
       records.map((record) => ({
-        operation: (executeChild) => record.operation((child) => executeChild(() => child(serial))),
+        operation: (executeChild) =>
+          record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
+            executeChild(() =>
+              dispatch(serial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef)
+            )
+          ),
         preparation: record.preparation,
-        workOptions: record.workOptions
+        workOptions: { payloadBytes: record.payloadBytes, onWithdrawable: record.onWithdrawable }
       }))
     );
-  }
-
-  executeTimer<T>(
-    timerName: string,
-    operation: () => Promise<T> | T,
-    workOptions?: ZLinkSerialWorkOptions
-  ): Promise<T> {
-    return this.timerSerial(timerName).execute(operation, workOptions);
+    const terminal = Promise.allSettled(terminals).then((outcomes) => {
+      const errors = outcomes.flatMap((outcome) =>
+        outcome.status === 'rejected' ? [outcome.reason] : []
+      );
+      if (errors.length === 1) throw errors[0];
+      if (errors.length > 1) {
+        throw new AggregateError(errors, `Actor '${actorId}' durable prefix replay failed.`);
+      }
+    });
+    return { terminal };
   }
 
   isTimerExecuting(timerName: string): boolean {

package/src/runtime/spots/spot-serial-turn-executor.ts

@@ -153,7 +153,7 @@ export class ZLinkSpotSerialTurnExecutor {
    * this so they never run inline inside another callback's turn.
    */
   post<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
-    return this.enqueueApplicationTurn(operation, workOptions);
+    return this.enqueueApplicationTurn(operation, workOptions, undefined, true);
   }
 
   /**
@@ -260,12 +260,25 @@ export class ZLinkSpotSerialTurnExecutor {
   private async enqueueApplicationTurn<T>(
     operation: () => Promise<T> | T,
     workOptions: ZLinkSerialWorkOptions = {},
-    replay?: (failure?: unknown) => Promise<T>
+    replay?: (failure?: unknown) => Promise<T>,
+    retainWhilePreparing = false
   ): Promise<T> {
     this.lastActivityAtMs = performance.now();
     let barrierClaim: ZLinkExecutionBarrierClaim | undefined;
     try {
       const entry = this.executionBarrier?.enter();
+      if (
+        entry instanceof Promise &&
+        retainWhilePreparing &&
+        this.scheduler.retainsApplicationForLifecycle
+      ) {
+        try {
+          return await this.submitQueuedTurn(operation, workOptions, entry);
+        } catch (error) {
+          (await entry).release();
+          throw error;
+        }
+      }
       barrierClaim = entry instanceof Promise ? await entry : entry;
       const refusal = this.applicationAdmissionRefusal(replay !== undefined);
       if (refusal !== undefined) throw refusal;
@@ -300,7 +313,7 @@ export class ZLinkSpotSerialTurnExecutor {
   private submitQueuedTurn<T>(
     operation: () => Promise<T> | T,
     workOptions: ZLinkSerialWorkOptions,
-    barrierClaim?: ZLinkExecutionBarrierClaim
+    barrierClaim?: ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim>
   ): Promise<T> {
     const options = {
       ...workOptions,
@@ -313,6 +326,12 @@ export class ZLinkSpotSerialTurnExecutor {
   }
 
   private runQueuedRecord(record: ZLinkSerialWorkRecord<unknown>): Promise<void> {
+    if (record.context instanceof Promise) {
+      return record.context.then((claim: ZLinkExecutionBarrierClaim) => {
+        Object.assign(record, { context: claim });
+        return this.runQueuedRecord(record);
+      });
+    }
     const context = record.context as ZLinkSpotApplicationTurnContext | undefined;
     if (context?.replay !== undefined && record.operation === context.replay) {
       context.release();

package/src/runtime/spots/spot-subscription-dispatch.ts

@@ -68,9 +68,6 @@ export class ZLinkSpotSubscriptionDispatch {
       }
       const key = subscriptionKey(registration.channelName, registration.topic);
       const existing = this.handlers.get(key) ?? [];
-      if (existing.some((entry) => entry.handlerType === registration.handlerType)) {
-        continue;
-      }
       existing.push(registration);
       this.handlers.set(key, existing);
       this.options.nativeSpot.setSubscription(registration.channelName, registration.topic);
@@ -191,7 +188,7 @@ export class ZLinkSpotSubscriptionDispatch {
       undefined
     );
     try {
-      await this.options.serial.execute(
+      await this.options.serial.post(
         () =>
           runWithFlow(inboundFlow, async () => {
             // Payload deserialization belongs to the Spot serial turn. Queue