@zlink-systems/framework 0.29.0 → 0.30.0

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type {
   ActorRef,
   RoutingId,
@@ -857,6 +858,7 @@ export class ZLinkSpotActivationLifecycle {
   }
 
   async dispatchActorPacket(
+    origin: ApplicationJobOrigin,
     activation: ZLinkSpotActivation,
     actorId: string,
     parts: readonly Message[],
@@ -867,6 +869,7 @@ export class ZLinkSpotActivationLifecycle {
     messageFollowOrigin?: ZLinkMessageFollowOrigin
   ): Promise<unknown> {
     return await this.actorAdmission.dispatchActorPacket(
+      origin,
       activation,
       actorId,
       parts,
@@ -880,6 +883,7 @@ export class ZLinkSpotActivationLifecycle {
 
   /** @internal Dispatches a held Actor record after its handoff owner releases it. */
   dispatchActorPacketDirect(
+    origin: ApplicationJobOrigin,
     activation: ZLinkSpotActivation,
     actorId: string,
     parts: readonly Message[],
@@ -888,6 +892,7 @@ export class ZLinkSpotActivationLifecycle {
     fallbackActorRef?: ActorRef
   ): Promise<unknown> {
     return this.actorAdmission.dispatchActorPacketDirect(
+      origin,
       activation,
       actorId,
       parts,

package/src/runtime/spots/spot-actor-admission-coordinator.ts

@@ -1,3 +1,5 @@
+import { currentApplicationJobOrigin } from '../application-jobs/application-job-queue-scope';
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, ZLinkActor } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
@@ -39,6 +41,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
   constructor(private readonly options: AdmissionOptions) {}
 
   async dispatchActorPacket(
+    origin: ApplicationJobOrigin,
     activation: ZLinkSpotActivation,
     actorId: string,
     parts: readonly Message[],
@@ -49,6 +52,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
     messageFollowOrigin?: ZLinkMessageFollowOrigin
   ): Promise<unknown> {
     const handoff = this.options.actorHandoffRuntime?.capture(
+      origin,
       actorId,
       parts,
       returnResponse,
@@ -63,6 +67,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
         replayFallbackActorRef
       ) =>
         this.dispatchActorPacketDirect(
+          origin,
           activation,
           actorId,
           replayedParts,
@@ -73,6 +78,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
     );
     if (handoff !== undefined) return await handoff;
     return await this.dispatchActorPacketDirect(
+      origin,
       activation,
       actorId,
       parts,
@@ -116,6 +122,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       packets: {
         handle: (delivery) =>
           this.dispatchActorPacket(
+            'remote',
             activation,
             delivery.actorId,
             delivery.parts,
@@ -149,6 +156,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
 
   /** @internal Dispatches a coordinator-owned replay without recapturing it. */
   dispatchActorPacketDirect(
+    origin: ApplicationJobOrigin,
     activation: ZLinkSpotActivation,
     actorId: string,
     parts: readonly Message[],
@@ -159,6 +167,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
   ): Promise<unknown> {
     return activation.executeActor(actorId, (actorSerial) =>
       this.dispatchActorPacketInActorTurn(
+        origin,
         activation,
         actorSerial,
         actorId,
@@ -190,6 +199,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
           record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
             executeChild((actorSerial) =>
               this.dispatchActorPacketInActorTurn(
+                currentApplicationJobOrigin(),
                 activation,
                 actorSerial,
                 actorId,
@@ -217,6 +227,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
   }
 
   private dispatchActorPacketInActorTurn(
+    origin: ApplicationJobOrigin,
     activation: ZLinkSpotActivation,
     actorSerial: ZLinkSpotSerialTurnExecutor,
     actorId: string,
@@ -250,6 +261,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       dispatchErrors: this.options.dispatchErrors,
       routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
     }).dispatch(
+      origin,
       actorId,
       parts,
       returnResponse,
@@ -305,6 +317,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       backlog,
       (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
         this.dispatchActorPacketDirect(
+          'remote',
           activation,
           actor.context.actorId,
           parts,

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
@@ -57,6 +58,7 @@ export interface ZLinkActorRequestTerminal {
 
 /** One admitted Actor packet and the routing context that must move with it. */
 export interface ZLinkActorPacketDelivery {
+  readonly origin: ApplicationJobOrigin;
   readonly actorId: string;
   readonly parts: readonly Message[];
   readonly returnResponse: boolean;
@@ -79,6 +81,7 @@ export type ZLinkRouteToActorJoinPrewarm = (
   actorId: string,
   objectGeneration: bigint,
   arrival: {
+    readonly origin: ApplicationJobOrigin;
     readonly header: Buffer;
     readonly payload: Buffer;
     readonly returnResponse: boolean;
@@ -133,6 +136,7 @@ export class ZLinkSpotActorPacketDispatch {
   constructor(private readonly options: ZLinkSpotActorPacketDispatchOptions) {}
 
   dispatch(
+    origin: ApplicationJobOrigin,
     actorId: string,
     parts: readonly Message[],
     returnResponse = false,
@@ -141,6 +145,7 @@ export class ZLinkSpotActorPacketDispatch {
     requestTerminal?: ZLinkActorRequestTerminal
   ): Promise<unknown> {
     return this.dispatchDelivery({
+      origin,
       actorId,
       parts,
       returnResponse,
@@ -212,6 +217,7 @@ export class ZLinkSpotActorPacketDispatch {
         const actor = this.options.resolveActor(actorId);
         if (actor === undefined) {
           return this.handleMissingActor(
+            delivery.origin,
             actorId,
             parts,
             header,
@@ -250,6 +256,7 @@ export class ZLinkSpotActorPacketDispatch {
   }
 
   private async handleMissingActor(
+    origin: ApplicationJobOrigin,
     actorId: string,
     parts: readonly Message[],
     header: ReturnType<typeof decodeStreamHeader>,
@@ -271,6 +278,7 @@ export class ZLinkSpotActorPacketDispatch {
       (messageKind !== ZLinkDispatchMessageKind.ActorRequest || requestTerminal !== undefined)
     ) {
       const parked = this.parkForActorJoinPrewarm(
+        origin,
         actorId,
         parts,
         messageKind,
@@ -328,6 +336,7 @@ export class ZLinkSpotActorPacketDispatch {
    * lifetime.
    */
   private parkForActorJoinPrewarm(
+    origin: ApplicationJobOrigin,
     actorId: string,
     parts: readonly Message[],
     messageKind: ZLinkDispatchMessageKind,
@@ -369,6 +378,7 @@ export class ZLinkSpotActorPacketDispatch {
       actorId,
       fallbackActorRef.objectGeneration,
       {
+        origin,
         header: Buffer.from(parts[0].data()),
         payload: Buffer.from(parts[1].data()),
         returnResponse,

package/src/runtime/spots/spot-actor-packet-drain.ts

@@ -135,6 +135,7 @@ export class ZLinkSpotActorPacketDrain {
         await this.dispatchNoBindActorRequest(noBindInfo, actorId, parts, actorRef);
       } else {
         await this.options.actorPacketHandler({
+          origin: 'remote',
           actorId,
           parts,
           returnResponse: false,
@@ -198,6 +199,7 @@ export class ZLinkSpotActorPacketDrain {
   ): Promise<void> {
     try {
       const response = await this.options.actorPacketHandler?.({
+        origin: 'remote',
         actorId,
         parts,
         returnResponse: true,

package/src/runtime/spots/spot-actor-packet-relay-dispatch.ts

@@ -111,6 +111,7 @@ export class ZLinkSpotActorPacketRelayDispatch {
         actorPacketRelay.messageFollowContext !== undefined &&
         remoteBoundSessionTarget !== undefined;
       const response = await this.options.actorPacketHandler({
+        origin: 'remote',
         actorId: actorPacketRelay.actorId,
         parts: [header, payload],
         returnResponse: !followedBoundSessionReply,

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

@@ -378,6 +378,10 @@ export class ZLinkEntrySpotActivation {
     return this.spotSerialExecutor.executeActor(actorId, operation);
   }
 
+  terminateActor(actorId: string, terminal: () => Promise<void>): Promise<void> {
+    return this.spotSerialExecutor.terminateActor(actorId, terminal);
+  }
+
   /**
    * Entry Spot membership does not have an application admission callback.
    * The shared core round-trip therefore accepts a valid returning Actor and
@@ -461,6 +465,7 @@ export class ZLinkEntrySpotActivation {
       messageFollowOrigin
     } = delivery;
     const handoff = this.options.actorHandoffRuntime?.capture(
+      delivery.origin,
       actorId,
       parts,
       returnResponse,
@@ -476,6 +481,7 @@ export class ZLinkEntrySpotActivation {
       ) =>
         this.spotSerialExecutor.executeActor(actorId, () =>
           this.dispatchActorPacketInsideMailbox({
+            origin: delivery.origin,
             actorId,
             parts: replayedParts,
             returnResponse: replayReturnResponse,
@@ -499,6 +505,7 @@ export class ZLinkEntrySpotActivation {
       (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
         this.spotSerialExecutor.executeActor(actor.context.actorId, () =>
           this.dispatchActorPacketInsideMailbox({
+            origin: 'remote',
             actorId: actor.context.actorId,
             parts,
             returnResponse,

package/src/runtime/spots/spot-node-runtime-manager.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { RuntimeDisposal } from '../disposal';
 import { randomUUID } from 'node:crypto';
 import {
@@ -62,7 +63,6 @@ import {
 } from '../configuration';
 import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
 import { runWithOutboundFlow } from '../diagnostics/flow-context';
-import { requireZLinkInfrastructureExecutionArea } from '../execution';
 import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import {
   type ZLinkMessageFollowOrigin,
@@ -285,6 +285,7 @@ export class ZLinkSpotNodeRuntimeManager {
         routingId,
         receiveTimeoutMs: spotNode.router?.receiveTimeoutMs,
         applicationJobQueue: this.applicationJobQueue,
+        infrastructureTaskRunner: this.options.detachedTaskRunner,
         applicationJobReceiveFlowFailureSink: this.options.applicationJobReceiveFlowFailureSink,
         peerAdmissionSealed: () => this.options.peerAdmissionSealed?.(spotNodeName) ?? false
       });
@@ -324,6 +325,9 @@ export class ZLinkSpotNodeRuntimeManager {
       let pump: ZLinkMeshDispatchPump | undefined;
       const completions = new ZLinkMeshCompletionTable();
       try {
+        node.setCompletionHandler((terminal, materialize) =>
+          completions.complete(terminal, materialize)
+        );
         node.setBind(bind);
         if (spotNode.router?.advertiseHost !== undefined) {
           node.setAdvertiseHost(spotNode.router.advertiseHost);
@@ -783,6 +787,13 @@ export class ZLinkSpotNodeRuntimeManager {
     return activation?.notifyJoinActor(actor, signal) ?? Promise.resolve();
   }
 
+  terminateActorActivation(actor: ZLinkActor, terminal: () => Promise<void>): Promise<void> {
+    const activation = this.entryActivations.get(actor.context.meshName);
+    return activation === undefined
+      ? terminal()
+      : activation.terminateActor(actor.context.actorId, terminal);
+  }
+
   notifyPrimaryEntrySpotActorLeft(
     actor: ZLinkActor,
     signal?: AbortSignal,
@@ -864,17 +875,6 @@ export class ZLinkSpotNodeRuntimeManager {
     owner: ReadyRecord,
     record: ReceiveRecord
   ): Promise<void> {
-    if (record.kind === ReceiveKind.Completion) {
-      requireZLinkInfrastructureExecutionArea();
-      const completions = this.meshCompletions.get(meshName);
-      if (completions === undefined) {
-        throw new ZLinkConfigurationException(
-          `MeshNode '${meshName}' received a completion before its completion table was registered.`
-        );
-      }
-      completions.complete(record);
-      return;
-    }
     const node = this.meshNodes.get(meshName);
     const targetsEntrySpot =
       owner.spotId === null ||
@@ -1044,6 +1044,7 @@ export class ZLinkSpotNodeRuntimeManager {
   }
 
   async dispatchEntryActorPacket(
+    origin: ApplicationJobOrigin,
     actorId: string,
     parts: readonly Message[],
     returnResponse = false,
@@ -1083,6 +1084,7 @@ export class ZLinkSpotNodeRuntimeManager {
       );
     }
     return await activation.dispatchActorPacket({
+      origin,
       actorId,
       parts,
       returnResponse,

package/src/runtime/spots/spot-routing-internal.ts

@@ -2,6 +2,11 @@ import type { RoutingId } from '../../contracts/Common';
 import type { ZLinkFrameworkRuntimeState, ZLinkSpotKind } from '../../contracts';
 
 export interface ZLinkSpotRouteResolver {
+  resolve(
+    spotId: RoutingId,
+    signal: AbortSignal | undefined,
+    instanceIntent: true
+  ): Promise<ZLinkSpotRouteTarget | ZLinkInstanceReactivationRoute>;
   resolve(spotId: RoutingId, signal?: AbortSignal): Promise<ZLinkSpotRouteTarget>;
   invalidate?(spotId: RoutingId): void;
 }
@@ -28,3 +33,12 @@ export interface ZLinkSpotRouteTarget {
   /** Current state of the owning MeshNode, when the route was resolved from Location Store. */
   readonly targetNodeState?: ZLinkFrameworkRuntimeState;
 }
+
+export interface ZLinkInstanceReactivationRoute extends Pick<
+  ZLinkSpotRouteTarget,
+  'spotId' | 'spotKind' | 'stableType'
+> {
+  readonly kind: 'coldActivation';
+  readonly meshName: string;
+  readonly stableType: string;
+}

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type {
   ActorRef,
   RoutingId,
@@ -151,6 +152,7 @@ export interface ZLinkSpotBoundSessionRuntime {
 
 export interface ZLinkSpotActorHandoffRuntime {
   capture(
+    origin: ApplicationJobOrigin,
     actorId: string,
     parts: readonly Message[],
     returnResponse?: boolean,

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

@@ -51,10 +51,8 @@ export class ZLinkSpotSerialExecutor {
     operation: (serial: ZLinkSpotSerialTurnExecutor) => Promise<T> | T,
     workOptions?: ZLinkSerialWorkOptions
   ): Promise<T> {
-    return this.actorExecutor(actorId).execute(
-      () => operation(this.actorSerial(actorId)),
-      workOptions
-    );
+    const serial = this.actorSerial(actorId);
+    return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
   }
 
   /** @internal Restores a durable Actor FIFO prefix without starting it. */
@@ -102,6 +100,14 @@ export class ZLinkSpotSerialExecutor {
     return this.spotSerial.execute(operation, { ...workOptions, lane: 'lifecycle' });
   }
 
+  async terminateActor(actorId: string, terminal: () => Promise<void>): Promise<void> {
+    const executor = this.actorExecutor(actorId);
+    await executor.close();
+    await terminal();
+    if (this.actorExecutors.get(actorId) === executor) this.actorExecutors.delete(actorId);
+    this.actorSerials.delete(actorId);
+  }
+
   /**
    * Makes all child queues unreachable and completes them in one synchronous
    * ownership turn. Already accepted work remains drainable.

package/src/runtime/streams/stream-session-runtime.ts

@@ -1048,7 +1048,7 @@ export class ZLinkStreamSessionNodeRuntime {
       let packet: ZLinkBackendStreamPacket | undefined;
       let packetTransferred = false;
       try {
-        permit = await this.options.applicationJobQueue.acquire(signal);
+        permit = await this.options.applicationJobQueue.acquire(signal, 'remote');
         if (this.isReceiveStopped(signal)) {
           permit.releaseAfterInternalProcessing();
           break;