@zlink-systems/framework 0.30.1 → 0.30.2

package/src/runtime/backend/contracts/index.ts

@@ -61,13 +61,32 @@ export type ZLinkBackendObjectPlacement =
   | { readonly kind: 'capacity' }
   | { readonly kind: 'unavailable' };
 
+export type ZLinkBackendRequestSourceAcceptance = (
+  nodeRid: string,
+  nodeGeneration: bigint,
+  nodeRidStorageHex: string,
+  signal?: AbortSignal
+) =>
+  | import('../../locations/request-source-resolver').ZLinkRequestSourceFence
+  | undefined
+  | Promise<import('../../locations/request-source-resolver').ZLinkRequestSourceFence | undefined>;
+
 export interface ZLinkBackendMeshNode {
+  acceptRelocatedActorTerminal?(
+    operation: { readonly high: bigint; readonly low: bigint },
+    replyRouteId: bigint,
+    result: import('../../foundation/service-stateful-runtime').ServiceStatefulResult
+  ): 'terminalReceived' | 'alreadyTerminal' | undefined;
   readonly routingId?: RoutingId;
+  cancelPendingOperations?(reason: unknown): void;
   completeClosedInstance?(spotId: string, objectGeneration: bigint): void;
   setDispatchErrorReporter?(
     reporter: import('../../channels/dispatch-error-reporter').ZLinkDispatchErrorReporter,
     meshName: string
   ): void;
+  setSessionOwnerDescriptors?(
+    source: import('../../foundation/service-stateful-runtime').ServiceSessionOwnerDescriptors
+  ): void;
   setRoutingId(routingId: unknown): void;
   setBind(endpoint: string): void;
   setAdvertiseHost(host: string): void;
@@ -98,9 +117,9 @@ export interface ZLinkBackendMeshNode {
       'kind'
     >
   ): Promise<boolean>;
-  shutdown(timeoutMs: number): RequestResult;
+  shutdown(timeoutMs: number): Promise<RequestResult>;
   publishDraining?(): Promise<void>;
-  close(): void;
+  close(): Promise<void>;
   addChannelName(name: string): void;
   setChannelWeight(name: string, weight: number): Promise<void>;
   setPlacementWeight(weight: number): Promise<void>;
@@ -184,12 +203,23 @@ export interface ZLinkBackendMeshNode {
     readonly securityIdentity?: string;
     readonly lifecycleGeneration: bigint;
   }): void;
+  /**
+   * Installs the source request owner check the first accepting owner runs on Actor and Spot
+   * ingress (Location runtime §9.3). Undefined from the check ends the request Unavailable.
+   */
+  setRequestSourceAcceptance?(acceptance: ZLinkBackendRequestSourceAcceptance): void;
   isObjectClientNodeDirectTarget?(targetRid: unknown): boolean;
   observePeerRoute?(
     targetRid: unknown
   ): import('../../foundation/durable-service-request').PeerRouteObservation;
   hasPeerRouteOrConnectionIntent?(targetRid: unknown, endpoint: string): boolean;
   isPeerRouteReady?(targetRid: unknown, lifecycleGeneration?: bigint): boolean;
+  waitForPeerRoute?(
+    targetRid: unknown,
+    lifecycleGeneration: bigint,
+    deadlineUnixMs: bigint,
+    signal?: AbortSignal
+  ): Promise<void>;
   sendToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
@@ -317,9 +347,10 @@ export interface ZLinkBackendMeshNode {
     source: ServiceDirectSpotRouteFence
   ): ServiceSpotMessageFollowSeal | undefined;
   abortSpotMessageFollowIngress?(seal: ServiceSpotMessageFollowSeal): boolean;
+  /** A null target consumes the committed seal without installing a Follow route. */
   commitSpotMessageFollowIngress?(
     seal: ServiceSpotMessageFollowSeal,
-    target: ServiceDirectSpotRouteFence,
+    target: ServiceDirectSpotRouteFence | null,
     durationMs: number
   ): Promise<boolean>;
   joinActorSpot(
@@ -365,7 +396,10 @@ export interface ZLinkBackendMeshNode {
   sendToActor(
     actor: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number }
+    options?: {
+      flags?: number;
+      routeFence?: import('../../foundation/service-stateful-wire-codec').ServiceActorRouteFence;
+    }
   ): Promise<SubmitResult>;
   requestToActor(
     actor: ZLinkBackendActorRef,
@@ -375,6 +409,7 @@ export interface ZLinkBackendMeshNode {
       timeoutMs?: number;
       applicationMetadata?: Buffer;
       onAdmitted?: () => void;
+      routeFence?: import('../../foundation/service-stateful-wire-codec').ServiceActorRouteFence;
     }
   ): MeshOperationId;
   actorSendToActor(

package/src/runtime/backend/mesh-actor-session-node-adapter.ts

@@ -1,3 +1,4 @@
+import { wireReplyFailureException } from '../framework-errors-internal';
 import { classifySubmitResult } from '../messaging/submission-result';
 import type { ZLinkBackendActorSessionNode, ZLinkBackendMeshNode } from './contracts';
 import { closeMeshCompletion, type ZLinkMeshCompletionTable } from './mesh-completion-table';
@@ -26,9 +27,10 @@ export function meshActorSessionNodeAdapter(
       );
       try {
         if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-          throw new Error(
-            `Actor '${actor.actorId}' bound-session close failed with result ` +
-              `'${completion.terminalResult}' and errno '${completion.failureErrno}'.`
+          throw wireReplyFailureException(
+            completion.terminalResult,
+            completion.failureErrno,
+            `Actor '${actor.actorId}' bound-session close failed.`
           );
         }
       } finally {

package/src/runtime/backend/mesh-completion-table.ts

@@ -71,7 +71,11 @@ export class ZLinkMeshCompletionTable {
       this.slots.push(slot);
       this.free = index;
     }
+    // New slots hold no identity yet. Only a larger bucket array needs the
+    // pending identities placed again; it doubles, so growth to N pending
+    // operations re-indexes O(N) slots in total.
     const minimumBuckets = this.slots.length * COMPLETION_HASH_BUCKETS_PER_SLOT;
+    if (minimumBuckets <= this.buckets.length) return;
     this.buckets = new Int32Array(2 ** Math.ceil(Math.log2(minimumBuckets))).fill(-1);
     for (let index = 0; index < this.slots.length; index++) {
       const slot = this.slots[index]!;

package/src/runtime/backend/mesh-dispatch-pump.ts

@@ -1,6 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
+import { awaitWithAbort } from '../abort';
 import { availableParallelism } from 'node:os';
-import { runWithApplicationJobPermit } from '../application-jobs/application-job-queue-scope';
+import {
+  enterApplicationJobPermitScope,
+  leaveApplicationJobPermitScope,
+  releaseApplicationJobPermitTurn
+} from '../application-jobs/application-job-queue-scope';
 import type {
   ApplicationJobPermitPort,
   ApplicationJobQueuePort
@@ -8,6 +13,7 @@ import type {
 import { runZLinkExecutionArea } from '../execution';
 import {
   ReadyDomain,
+  type Claim,
   type ReadyBatch,
   type ReadyRecord,
   type ReceiveBatch,
@@ -58,7 +64,6 @@ export interface ZLinkMeshDispatchFailureContext {
 }
 
 export class ZLinkMeshDispatchPump {
-  private readonly dispatchOwnedRecord = this.dispatchRecord.bind(this);
   private pendingDomains: number = ReadyDomain.None;
   private infrastructureScheduled = false;
   private disposed = false;
@@ -68,6 +73,10 @@ export class ZLinkMeshDispatchPump {
   private readonly capacityStop = new AbortController();
   private recordsSinceYield = 0;
   private yieldStartedAtMs = 0;
+  /** Drains in progress; the batch budget begins when work starts on an idle pump. */
+  private draining = 0;
+  /** The macrotask boundary every drain waits for once the shared budget is spent. */
+  private pendingYield?: Promise<void>;
 
   constructor(
     private readonly node: ZLinkBackendMeshNode,
@@ -85,7 +94,7 @@ export class ZLinkMeshDispatchPump {
     });
   }
 
-  async dispose(): Promise<void> {
+  async dispose(signal?: AbortSignal): Promise<void> {
     if (this.disposed) {
       return;
     }
@@ -95,7 +104,7 @@ export class ZLinkMeshDispatchPump {
     for (const wake of this.idleApplicationWorkers) wake();
     this.idleApplicationWorkers.clear();
     while (this.activeDrains.size > 0) {
-      await Promise.all([...this.activeDrains]);
+      await awaitWithAbort(Promise.all([...this.activeDrains]), signal);
     }
   }
 
@@ -159,12 +168,40 @@ export class ZLinkMeshDispatchPump {
     try {
       for (;;) {
         await this.waitForApplicationReady();
-        if (this.disposed) return;
+        this.beginDrain();
         try {
-          await this.drainDomain(ReadyDomain.Application, readyBatch, receiveBatch);
+          while (!this.disposed) {
+            readyBatch.reset();
+            const drained = this.node.drainReady(
+              ReadyDomain.Application,
+              readyBatch,
+              ZLINK_BACKEND_RECV_DONT_WAIT
+            );
+            if (!drained.ok || drained.records.length === 0) break;
+            if (drained.hasResidue) this.markReady(ReadyDomain.Application);
+            for (let index = 0; index < drained.records.length; index += 1) {
+              const claim = readyBatch.takeClaim(index);
+              // Raw ingress already attached one host permit to each record.
+              // A claim reserving admission may receive only that permit's record.
+              await this.drainClaim(
+                ReadyDomain.Application,
+                drained.records[index]!,
+                claim,
+                receiveBatch
+              );
+            }
+            // Empty ready claims count toward the shared pump budget too.
+            this.recordsSinceYield += 1;
+            const yieldTurn = this.yieldIfNeeded();
+            if (yieldTurn !== undefined) await yieldTurn;
+          }
         } catch (error) {
           this.reportDispatchError(error);
+        } finally {
+          readyBatch.reset();
+          this.draining -= 1;
         }
+        if (this.disposed) return;
       }
     } finally {
       receiveBatch.close();
@@ -181,34 +218,62 @@ export class ZLinkMeshDispatchPump {
     return new Promise((resolve) => this.idleApplicationWorkers.add(resolve));
   }
 
-  private dispatchRecord(owner: ReadyRecord, record: ReceiveRecord): void | Promise<void> {
-    let result: void | Promise<void>;
+  /**
+   * Starts one record in this worker's turn; a permit's scope covers the
+   * synchronous dispatch. Returns `false` when the dispatch threw (already
+   * reported), `true` when it returned synchronously, or the handler's pending
+   * completion, which the draining turn awaits itself before
+   * {@link finishRecord}.
+   */
+  private dispatchRecord(
+    owner: ReadyRecord,
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): boolean | PromiseLike<void> {
+    const previous = permit === undefined ? undefined : enterApplicationJobPermitScope(permit);
+    let result: void | PromiseLike<void>;
     try {
       result = this.options.dispatch(owner, record);
     } catch (error) {
-      this.reportDispatchError(error, meshDispatchFailureContext(record));
-      return;
+      this.failRecord(error, record, permit);
+      return false;
+    } finally {
+      if (permit !== undefined) leaveApplicationJobPermitScope(previous);
     }
-    return result === undefined
-      ? this.finishRecord(record)
-      : Promise.resolve(result).then(
-          () => this.finishRecord(record),
-          (error) => this.reportDispatchError(error, meshDispatchFailureContext(record))
-        );
+    return result ?? true;
+  }
+
+  private failRecord(
+    error: unknown,
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): void {
+    releaseApplicationJobPermitTurn(permit);
+    this.reportDispatchError(error, meshDispatchFailureContext(record));
   }
 
-  private finishRecord(record: ReceiveRecord): void | Promise<void> {
-    let result: void | Promise<void>;
+  /** Runs the record's terminal completion, then releases its permit turn. */
+  private finishRecord(
+    record: ReceiveRecord,
+    permit: ApplicationJobPermitPort | undefined
+  ): void | Promise<void> {
+    let result: void | Promise<void> = undefined;
     try {
       result = record.onTerminalCompletion?.();
     } catch (error) {
       this.reportDispatchError(error, meshDispatchFailureContext(record));
+    }
+    if (result === undefined) {
+      releaseApplicationJobPermitTurn(permit);
       return;
     }
-    if (result !== undefined)
-      return Promise.resolve(result).catch((error) =>
-        this.reportDispatchError(error, meshDispatchFailureContext(record))
-      );
+    return Promise.resolve(result).then(
+      () => releaseApplicationJobPermitTurn(permit),
+      (error) => {
+        this.reportDispatchError(error, meshDispatchFailureContext(record));
+        releaseApplicationJobPermitTurn(permit);
+      }
+    );
   }
 
   private reportDispatchError(error: unknown, context?: ZLinkMeshDispatchFailureContext): void {
@@ -260,12 +325,7 @@ export class ZLinkMeshDispatchPump {
         if ((this.pendingDomains & ReadyDomain.Application) !== 0) {
           setImmediate(() => this.wakeApplicationWorker());
         }
-        const lifecycleBudgetExhausted = await this.drainDomain(
-          ReadyDomain.Infrastructure,
-          readyBatch,
-          undefined,
-          MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET
-        );
+        const lifecycleBudgetExhausted = await this.drainDomain(readyBatch);
         if (lifecycleBudgetExhausted) {
           this.pendingDomains |= ReadyDomain.Infrastructure;
           await yieldToEventLoop();
@@ -276,117 +336,40 @@ export class ZLinkMeshDispatchPump {
     }
   }
 
-  private async drainDomain(
-    domain: number,
-    readyBatch: ReadyBatch,
-    receiveBatch: ReceiveBatch | undefined,
-    claimBudget?: number
-  ): Promise<boolean> {
+  private async drainDomain(readyBatch: ReadyBatch): Promise<boolean> {
     let claimsDrained = 0;
+    this.beginDrain();
     try {
       while (!this.disposed) {
-        if (claimBudget !== undefined && claimsDrained >= claimBudget) {
+        if (claimsDrained >= MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET) {
           // Lifecycle work has priority, but a bounded turn lets application
           // work make progress when lifecycle records keep arriving.
           return true;
         }
         readyBatch.reset();
-        const drained = this.node.drainReady(domain, readyBatch, ZLINK_BACKEND_RECV_DONT_WAIT);
+        const drained = this.node.drainReady(
+          ReadyDomain.Infrastructure,
+          readyBatch,
+          ZLINK_BACKEND_RECV_DONT_WAIT
+        );
         if (!drained.ok || drained.records.length === 0) {
           return false;
         }
-        if (domain === ReadyDomain.Application && drained.hasResidue) {
-          this.markReady(ReadyDomain.Application);
-        }
         for (let index = 0; index < drained.records.length; index += 1) {
           const claim = readyBatch.takeClaim(index);
           claimsDrained += 1;
           const owner = drained.records[index]!;
-          // Raw ingress already attached one host permit to each record.
-          // A claim that reserves admission here may receive only that permit's record.
-          const drainClaim = async () => {
-            let ownerReceiveBatch = receiveBatch;
-            try {
-              ownerReceiveBatch ??= this.node.createReceiveBatch(
-                MESH_DISPATCH_RECEIVE_CAPACITY,
-                this.options.partCapacity ?? DEFAULT_MESH_PART_CAPACITY
-              );
-              const capacity =
-                owner.ordinaryIngressPreAdmitted === true ? MESH_DISPATCH_RECEIVE_CAPACITY : 1;
-              let claimPermit =
-                owner.terminalCompletion === true ||
-                owner.ordinaryIngressPreAdmitted === true ||
-                domain === ReadyDomain.Infrastructure
-                  ? undefined
-                  : await this.acquirePermit();
-              try {
-                if (this.capacityStop.signal.aborted) return;
-                ownerReceiveBatch.reset(capacity);
-                const received = claim.recvBatch(ownerReceiveBatch, ZLINK_BACKEND_RECV_DONT_WAIT);
-                if (received.ok) {
-                  // The bounded batch stays in claim order until its records finish.
-                  try {
-                    for (const record of received.records) {
-                      if (this.disposed) break;
-                      const permit = record.applicationJobPermit ?? claimPermit;
-                      if (owner.ordinaryIngressPreAdmitted === true && permit === undefined) {
-                        throw new Error(
-                          'Pre-admitted raw ingress record lost its Application Job Queue permit.'
-                        );
-                      }
-                      this.recordsSinceYield += 1;
-                      if (permit === undefined) {
-                        const dispatched = this.dispatchRecord(owner, record);
-                        if (dispatched !== undefined) await dispatched;
-                      } else {
-                        if (
-                          domain === ReadyDomain.Application &&
-                          record.applicationJobPermit === undefined
-                        )
-                          permit.markApplicationQueued();
-                        // The scope now owns this reservation, including failure
-                        // and detached handler handoff. Only unused permits remain
-                        // owned by the receive attempt's finally block.
-                        if (permit === claimPermit) claimPermit = undefined;
-                        const dispatched = runWithApplicationJobPermit(
-                          permit,
-                          this.dispatchOwnedRecord,
-                          owner,
-                          record
-                        );
-                        if (dispatched !== undefined) await dispatched;
-                      }
-                    }
-                  } finally {
-                    // Batch ownership includes records whose dispatch never began,
-                    // including on failure or shutdown in the middle of the batch.
-                    for (const record of received.records) {
-                      for (const part of record.parts) part.close();
-                      record.releaseRetainedIngress?.();
-                    }
-                  }
-                }
-              } finally {
-                claimPermit?.releaseAfterInternalProcessing();
-              }
-            } finally {
-              claim.release();
-              if (receiveBatch === undefined) ownerReceiveBatch?.close();
-            }
-            const yieldTurn = this.yieldIfNeeded();
-            if (yieldTurn !== undefined) await yieldTurn;
-          };
-          // An application worker drains the one owner it claimed. Infrastructure owners
-          // drain independently, so a suspended owner does not hold the other claims.
-          if (receiveBatch !== undefined) {
-            await drainClaim();
-          } else {
-            const drain = drainClaim().catch((error) => this.reportDispatchError(error));
-            this.activeDrains.add(drain);
-            void drain.finally(() => this.activeDrains.delete(drain));
-          }
+          this.beginDrain();
+          const drain = this.drainClaim(ReadyDomain.Infrastructure, owner, claim, undefined).catch(
+            (error) => this.reportDispatchError(error)
+          );
+          this.activeDrains.add(drain);
+          void drain.finally(() => {
+            this.draining -= 1;
+            this.activeDrains.delete(drain);
+          });
         }
-        if (claimBudget !== undefined && claimsDrained >= claimBudget) {
+        if (claimsDrained >= MESH_DISPATCH_LIFECYCLE_CLAIM_BUDGET) {
           this.wakeApplicationWorker();
           return true;
         }
@@ -399,10 +382,123 @@ export class ZLinkMeshDispatchPump {
       return false;
     } finally {
       readyBatch.reset();
+      this.draining -= 1;
+    }
+  }
+
+  /**
+   * Time the pump spent idle is not batch work: when work starts on an idle
+   * pump, its batch budget starts with it (spec 08 §6).
+   */
+  private beginDrain(): void {
+    if (this.draining === 0) {
+      this.recordsSinceYield = 0;
+      this.yieldStartedAtMs = this.nowMs();
+    }
+    this.draining += 1;
+  }
+
+  /** Drains one claimed owner in this worker's turn, in claim order. */
+  private async drainClaim(
+    domain: number,
+    owner: ReadyRecord,
+    claim: Claim,
+    receiveBatch: ReceiveBatch | undefined
+  ): Promise<void> {
+    let ownerReceiveBatch = receiveBatch;
+    try {
+      ownerReceiveBatch ??= this.node.createReceiveBatch(
+        MESH_DISPATCH_RECEIVE_CAPACITY,
+        this.options.partCapacity ?? DEFAULT_MESH_PART_CAPACITY
+      );
+      const capacity =
+        owner.ordinaryIngressPreAdmitted === true ? MESH_DISPATCH_RECEIVE_CAPACITY : 1;
+      let claimPermit =
+        owner.terminalCompletion === true ||
+        owner.ordinaryIngressPreAdmitted === true ||
+        domain === ReadyDomain.Infrastructure
+          ? undefined
+          : await this.acquirePermit();
+      try {
+        if (this.capacityStop.signal.aborted) return;
+        ownerReceiveBatch.reset(capacity);
+        const received = claim.recvBatch(ownerReceiveBatch, ZLINK_BACKEND_RECV_DONT_WAIT);
+        if (received.ok) {
+          // The bounded batch stays in claim order until its records finish.
+          try {
+            for (const record of received.records) {
+              if (this.disposed) break;
+              const permit = record.applicationJobPermit ?? claimPermit;
+              if (owner.ordinaryIngressPreAdmitted === true && permit === undefined) {
+                throw new Error(
+                  'Pre-admitted raw ingress record lost its Application Job Queue permit.'
+                );
+              }
+              this.recordsSinceYield += 1;
+              if (permit !== undefined) {
+                if (domain === ReadyDomain.Application && record.applicationJobPermit === undefined)
+                  permit.markApplicationQueued();
+                // The scope now owns this reservation, including failure
+                // and detached handler handoff. Only unused permits remain
+                // owned by the receive attempt's finally block.
+                if (permit === claimPermit) claimPermit = undefined;
+              }
+              // The record's terminal and the permit turn release follow the
+              // handler in this turn's own continuation.
+              if (record.prepareDispatch !== undefined) {
+                try {
+                  const stopSignal = this.capacityStop.signal;
+                  const preparation = record.prepareDispatch(stopSignal);
+                  const accepted = preparation instanceof Promise ? await preparation : preparation;
+                  if (!accepted || stopSignal.aborted) {
+                    releaseApplicationJobPermitTurn(permit);
+                    continue;
+                  }
+                } catch (error) {
+                  this.failRecord(error, record, permit);
+                  continue;
+                }
+              }
+              const dispatched = this.dispatchRecord(owner, record, permit);
+              if (dispatched === false) continue;
+              if (dispatched !== true) {
+                try {
+                  await dispatched;
+                } catch (error) {
+                  this.failRecord(error, record, permit);
+                  continue;
+                }
+              }
+              const finished = this.finishRecord(record, permit);
+              if (finished !== undefined) await finished;
+            }
+          } finally {
+            // Batch ownership includes records whose dispatch never began,
+            // including on failure or shutdown in the middle of the batch.
+            for (const record of received.records) {
+              for (const part of record.parts) part.close();
+              record.releaseRetainedIngress?.();
+            }
+          }
+        }
+      } finally {
+        claimPermit?.releaseAfterInternalProcessing();
+      }
+    } finally {
+      claim.release();
+      if (receiveBatch === undefined) ownerReceiveBatch?.close();
     }
+    const yieldTurn = this.yieldIfNeeded();
+    if (yieldTurn !== undefined) await yieldTurn;
   }
 
+  /**
+   * The batch budget is shared by every drain of this pump, so once it is
+   * spent every drain waits for the same macrotask boundary; one drain that
+   * keeps running would otherwise hold the event loop the yield was for.
+   */
   private yieldIfNeeded(): Promise<void> | undefined {
+    if (this.pendingYield !== undefined) return this.pendingYield;
     const nowMs = this.nowMs();
     if (
       this.recordsSinceYield < MESH_DISPATCH_YIELD_RECORDS &&
@@ -410,9 +506,12 @@ export class ZLinkMeshDispatchPump {
     )
       return undefined;
     this.recordsSinceYield = 0;
-    return yieldToTimers().then(() => {
+    const pendingYield = yieldToTimers().then(() => {
+      this.pendingYield = undefined;
       this.yieldStartedAtMs = this.nowMs();
     });
+    this.pendingYield = pendingYield;
+    return pendingYield;
   }
 
   private nowMs(): number {