@zlink-systems/framework 0.29.1 → 0.30.1

package/src/runtime/actors/actor-routed-join-transport.ts

@@ -19,13 +19,13 @@ export interface ZLinkActorRoutedJoinTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   submitInfrastructure?(
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -34,7 +34,11 @@ export interface ZLinkActorRoutedJoinTransport {
   requestRawToSpot?(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
@@ -43,6 +47,7 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestFromSpotToSpot?<TReply = unknown>(
@@ -53,12 +58,17 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestRawFromSpotToSpot?(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
 }

package/src/runtime/actors/actor-routed-json-request.ts

@@ -7,7 +7,11 @@ export async function tryRequestRoutedJson(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  }
 ): Promise<boolean> {
   const request = transport.requestRawToSpot;
   if (request === undefined) return false;
@@ -24,7 +28,11 @@ export async function requestRoutedJsonReply<T>(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal },
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  },
   unavailableMessage: string,
   decode: (replyParts: readonly Message[]) => T
 ): Promise<T> {

package/src/runtime/actors/index.ts

@@ -191,7 +191,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const actorRef = this.actorRefForState(state);
     return {
       spotId: spotId,
-      objectGeneration: state.locationGeneration ?? 0n,
+      objectGeneration: state.spotGeneration ?? 0n,
       meshName: this.actorMeshNames.get(actorId) ?? '',
       nodeRid: actorRef.nodeRid
     };
@@ -467,7 +467,8 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         await registry.restore(transfer.adapterKey, actor, transfer.state, signal);
       }
       state.setLocationGeneration(authorityOwnerGeneration);
-      if (spotId !== undefined) state.setJoinedSpot(spotId, undefined, membershipEpoch);
+      if (spotId !== undefined)
+        state.setJoinedSpot(spotId, undefined, membershipEpoch, spotGeneration);
       return actor;
     } catch (error) {
       if (nativeRef !== undefined) node.discardRelocatedActor?.(nativeRef);
@@ -486,17 +487,30 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   }
 
   async abortRelocationActor(actorId: string): Promise<void> {
-    await this.removeRelocationActor(actorId);
+    await this.releaseLocalActor(actorId);
   }
 
   async completeRelocationSource(
     actorId: string,
     sourceActorRef?: ZLinkBackendActorRef
   ): Promise<void> {
-    await this.removeRelocationActor(actorId, sourceActorRef);
+    await this.releaseLocalActor(actorId, sourceActorRef);
   }
 
-  private async removeRelocationActor(
+  async releaseSpotActorMembers(meshName: string, spotId?: RoutingId): Promise<void> {
+    const results = await Promise.allSettled(
+      [...this.states.values()]
+        .filter((state) => state.meshName === meshName && state.spotId === spotId)
+        .map((state) => this.releaseLocalActor(state.actorId))
+    );
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, 'Actor member cleanup failed.');
+  }
+
+  private async releaseLocalActor(
     actorId: string,
     exactNativeActorRef?: ZLinkBackendActorRef
   ): Promise<void> {

package/src/runtime/actors/spot-actor-dispatch.ts

@@ -49,7 +49,8 @@ export class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRe
     );
     const resolvedPacketName = packetName ?? metadata?.packetName;
     if (metadata === undefined || resolvedPacketName === undefined) {
-      throw new ZLinkConfigurationException(
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
         `Actor packet handler '${handlerType.name}' must declare a packet name.`
       );
     }
@@ -68,7 +69,8 @@ export class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRe
   addPacket(descriptor: ZLinkActorPacketDescriptor): this {
     const key = packetKey(descriptor.kind, descriptor.actorType, descriptor.packetName);
     if (this.packets.has(key)) {
-      throw new ZLinkConfigurationException(
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
         `Actor packet '${descriptor.packetName}' for '${descriptor.actorType.name}' is already registered.`
       );
     }

package/src/runtime/admission.ts

@@ -86,12 +86,25 @@ export class ZLinkRuntimeAdmissionGate {
     );
   }
 
-  async run<T>(meshName: string, operation: string, work: () => Promise<T>): Promise<T> {
-    const claim = this.claim(meshName, operation);
+  run<T>(meshName: string, operation: string, work: () => T | Promise<T>): Promise<T> {
+    let claim: ZLinkApplicationWorkClaim | undefined;
     try {
-      return await work();
-    } finally {
-      claim.close();
+      claim = this.claim(meshName, operation);
+      const result = work();
+      const close = claim.close;
+      return Promise.resolve(result).then(
+        (value) => {
+          close();
+          return value;
+        },
+        (error) => {
+          close();
+          throw error;
+        }
+      );
+    } catch (error) {
+      claim?.close();
+      return Promise.reject(error);
     }
   }
 

package/src/runtime/application-jobs/application-ingress-record-owner.ts

@@ -1,4 +1,8 @@
-import type { ApplicationJobPermitPort, ApplicationJobQueuePort } from './contracts';
+import type {
+  ApplicationJobOrigin,
+  ApplicationJobPermitPort,
+  ApplicationJobQueuePort
+} from './contracts';
 
 export type ApplicationJobRecordDomain = 'application' | 'infrastructure';
 
@@ -12,7 +16,7 @@ export interface IngressRecordPort {
  * ordinary Framework-owned ingress record closes after the last child terminal.
  */
 export class ApplicationIngressRecordOwner {
-  private readonly stop = new AbortController();
+  private stop?: AbortController;
   private closed = false;
 
   private constructor(private readonly shared: SharedIngressRecordState) {}
@@ -42,17 +46,34 @@ export class ApplicationIngressRecordOwner {
     return job;
   }
 
-  async acquire(
+  acquire(
     domain: ApplicationJobRecordDomain,
     signal?: AbortSignal
-  ): Promise<ApplicationJobRecordLease> {
-    this.requireOpen();
-    const initial = this.shared.takeInitialPermit(domain);
-    if (initial !== undefined) return initial;
+  ): ApplicationJobRecordLease | Promise<ApplicationJobRecordLease> {
+    try {
+      this.requireOpen();
+      const initial = this.shared.takeInitialPermit(domain);
+      if (initial !== undefined) return initial;
+    } catch (error) {
+      return Promise.reject(error);
+    }
 
-    const waitSignal =
-      signal === undefined ? this.stop.signal : AbortSignal.any([this.stop.signal, signal]);
-    const permit = await this.shared.acquirePermit(waitSignal);
+    return this.acquireAdditional(domain, signal);
+  }
+
+  private async acquireAdditional(
+    domain: ApplicationJobRecordDomain,
+    signal?: AbortSignal
+  ): Promise<ApplicationJobRecordLease> {
+    const stop = (this.stop ??= new AbortController());
+    const waitSignal = signal === undefined ? stop.signal : AbortSignal.any([stop.signal, signal]);
+    let permit: ApplicationJobPermitPort;
+    try {
+      permit = await this.shared.acquirePermit(waitSignal);
+    } catch (error) {
+      if (error === ownerClosedError) throw ownerClosedError();
+      throw error;
+    }
     if (this.closed) {
       permit.releaseAfterInternalProcessing();
       throw ownerClosedError();
@@ -63,7 +84,8 @@ export class ApplicationIngressRecordOwner {
   close(): void {
     if (this.closed) return;
     this.closed = true;
-    this.stop.abort(ownerClosedError());
+    // The queue forwards this reason; only a rejected acquisition constructs the error.
+    this.stop?.abort(ownerClosedError);
     this.shared.releaseOwner();
   }
 
@@ -75,16 +97,18 @@ export class ApplicationIngressRecordOwner {
 /** Queue-permit child of one shared raw ingress record. */
 export class ApplicationJobRecordLease implements ApplicationJobPermitPort {
   private ingressClosed = false;
-  private permitReleased = false;
   private processingTerminal = false;
-  private detachedForHandlerTurn = false;
-  private jobReleased = false;
+  detachedForHandlerTurn = false;
 
   constructor(
     private readonly shared: SharedIngressRecordState,
-    private readonly permit: ApplicationJobPermitPort
+    private permit: ApplicationJobPermitPort | undefined
   ) {}
 
+  get origin(): ApplicationJobOrigin {
+    return this.shared.origin;
+  }
+
   markApplicationQueued(): void {
     // The owner classifies and marks the child atomically when it is created;
     // downstream dispatch must not mutate queue accounting a second time.
@@ -95,12 +119,12 @@ export class ApplicationJobRecordLease implements ApplicationJobPermitPort {
   }
 
   releaseBeforeHandler(): void {
-    this.releasePermit(() => this.permit.releaseBeforeHandler());
+    this.permit?.releaseBeforeHandler();
   }
 
   releaseAfterInternalProcessing(): void {
     this.processingTerminal = true;
-    this.releasePermit(() => this.permit.releaseAfterInternalProcessing());
+    this.permit?.releaseAfterInternalProcessing();
     this.releaseJobIfTerminal();
   }
 
@@ -114,16 +138,15 @@ export class ApplicationJobRecordLease implements ApplicationJobPermitPort {
     this.releaseJobIfTerminal();
   }
 
-  private releasePermit(release: () => void): void {
-    if (this.permitReleased) return;
-    this.permitReleased = true;
-    release();
-  }
-
   private releaseJobIfTerminal(): void {
-    if (this.jobReleased || !this.ingressClosed || !this.processingTerminal) return;
-    this.jobReleased = true;
-    this.shared.releaseJob();
+    const permit = this.permit;
+    if (permit === undefined || !this.ingressClosed || !this.processingTerminal) return;
+    this.permit = undefined;
+    try {
+      this.shared.releaseJob();
+    } finally {
+      permit.releaseStorage?.();
+    }
   }
 }
 
@@ -132,12 +155,14 @@ class SharedIngressRecordState {
   private jobCount = 0;
   private initialPermit?: ApplicationJobPermitPort;
   private recordClosed = false;
+  readonly origin: ApplicationJobOrigin;
 
   constructor(
     private readonly queue: ApplicationJobQueuePort,
     initialPermit: ApplicationJobPermitPort,
     private readonly record: IngressRecordPort
   ) {
+    this.origin = initialPermit.origin;
     this.initialPermit = initialPermit;
   }
 
@@ -160,7 +185,7 @@ class SharedIngressRecordState {
   }
 
   acquirePermit(signal: AbortSignal): Promise<ApplicationJobPermitPort> {
-    return this.queue.acquire(signal);
+    return this.queue.acquire(signal, this.origin);
   }
 
   createJob(
@@ -193,6 +218,7 @@ class SharedIngressRecordState {
     try {
       this.initialPermit?.releaseAfterInternalProcessing();
     } finally {
+      this.initialPermit?.releaseStorage?.();
       this.initialPermit = undefined;
       this.record.close();
     }

package/src/runtime/application-jobs/application-job-queue-scope.ts

@@ -1,40 +1,70 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-import type { ApplicationJobPermitPort } from './contracts';
+import type { ApplicationJobOrigin, ApplicationJobPermitPort } from './contracts';
 
-interface ApplicationJobPermitScope {
-  readonly permit: ApplicationJobPermitPort;
-  detached: boolean;
+const applicationJobPermitScope = new AsyncLocalStorage<ApplicationJobPermitPort | undefined>();
+
+function releasePermitTurn(): void {
+  const permit = applicationJobPermitScope.getStore();
+  if (permit !== undefined && !permit.detachedForHandlerTurn)
+    permit.releaseAfterInternalProcessing();
 }
 
-const applicationJobPermitScope = new AsyncLocalStorage<ApplicationJobPermitScope>();
+function releasePermitSuccess<TResult>(value: TResult): TResult {
+  releasePermitTurn();
+  return value;
+}
+
+function releasePermitFailure(error: unknown): never {
+  releasePermitTurn();
+  throw error;
+}
 
 /**
  * Carries the host-owned queue permit through internal async dispatch without
  * leaking capacity ownership into public handler contracts.
  */
-export async function runWithApplicationJobPermit<TResult>(
+export function runWithApplicationJobPermit<TResult>(
+  permit: ApplicationJobPermitPort,
+  callback: () => Promise<TResult>
+): Promise<TResult>;
+export function runWithApplicationJobPermit<TResult, TFirst = undefined, TSecond = undefined>(
   permit: ApplicationJobPermitPort,
-  callback: () => Promise<TResult> | TResult
-): Promise<TResult> {
-  const scope: ApplicationJobPermitScope = { permit, detached: false };
-  return applicationJobPermitScope.run(scope, async () => {
-    try {
-      return await callback();
-    } finally {
-      if (!scope.detached) permit.releaseAfterInternalProcessing();
+  callback: (first: TFirst, second: TSecond) => Promise<TResult> | TResult,
+  first?: TFirst,
+  second?: TSecond
+): TResult | Promise<TResult>;
+export function runWithApplicationJobPermit<TResult, TFirst, TSecond>(
+  permit: ApplicationJobPermitPort,
+  callback: (first: TFirst, second: TSecond) => Promise<TResult> | TResult,
+  first?: TFirst,
+  second?: TSecond
+): TResult | Promise<TResult> {
+  const previous = applicationJobPermitScope.getStore();
+  applicationJobPermitScope.enterWith(permit);
+  try {
+    const result = callback(first as TFirst, second as TSecond);
+    if (result !== null && (typeof result === 'object' || typeof result === 'function')) {
+      return Promise.resolve(result).then(releasePermitSuccess, releasePermitFailure);
     }
-  });
+    releasePermitTurn();
+    return result;
+  } catch (error) {
+    releasePermitTurn();
+    return Promise.reject(error);
+  } finally {
+    applicationJobPermitScope.enterWith(previous);
+  }
 }
 
 /** Releases the current job permit immediately before the first user callback. */
 export function releaseApplicationJobPermitBeforeHandler(): void {
-  applicationJobPermitScope.getStore()?.permit.releaseBeforeHandler();
+  applicationJobPermitScope.getStore()?.releaseBeforeHandler();
 }
 
 /** @internal Returns an ingress permit after a durable queue takes record ownership. */
 export function releaseApplicationJobPermitForDurableHandoff(): void {
-  applicationJobPermitScope.getStore()?.permit.releaseAfterInternalProcessing();
+  applicationJobPermitScope.getStore()?.releaseAfterInternalProcessing();
 }
 
 /** True while dispatch already owns the host-wide application job permit. */
@@ -42,6 +72,11 @@ export function hasApplicationJobPermit(): boolean {
   return applicationJobPermitScope.getStore() !== undefined;
 }
 
+/** Keeps the ingress origin when a durable record later reacquires its permit. */
+export function currentApplicationJobOrigin(): ApplicationJobOrigin {
+  return applicationJobPermitScope.getStore()!.origin;
+}
+
 /** Re-enters the captured permit scope when a serial executor runs later. */
 export function bindApplicationJobPermit<TResult, TArgument>(
   callback: (argument?: TArgument) => Promise<TResult> | TResult
@@ -56,9 +91,8 @@ export function bindApplicationJobPermit<TResult, TArgument>(
  * detached owner must release it at handler entry or at a pre-start terminal.
  */
 export function detachApplicationJobPermit(): ApplicationJobPermitPort | undefined {
-  const scope = applicationJobPermitScope.getStore();
-  if (scope === undefined) return undefined;
-  scope.permit.detachForHandlerTurn?.();
-  scope.detached = true;
-  return scope.permit;
+  const permit = applicationJobPermitScope.getStore();
+  if (permit === undefined) return undefined;
+  permit.detachForHandlerTurn();
+  return permit;
 }

package/src/runtime/application-jobs/contracts.ts

@@ -1,13 +1,39 @@
+export type ApplicationJobOrigin = 'local' | 'remote';
+
 export interface ApplicationJobPermitPort {
+  readonly origin: ApplicationJobOrigin;
+  readonly detachedForHandlerTurn: boolean;
   markApplicationQueued(): void;
   /** Transfers ingress-record cleanup to a detached exact-target handler turn. */
-  detachForHandlerTurn?(): void;
+  detachForHandlerTurn(): void;
   releaseBeforeHandler(): void;
   releaseAfterInternalProcessing(): void;
+  /** Returns reusable reservation storage only after its ingress lifetime ends. */
+  releaseStorage?(): void;
+}
+
+export interface ApplicationJobReceiveRotationPort {
+  reserve(): void;
+  take(): ApplicationJobPermitPort | undefined;
+  releaseUnused(): void;
 }
 
 export interface ApplicationJobQueuePort {
-  acquire(signal?: AbortSignal): Promise<ApplicationJobPermitPort>;
+  createReceiveRotation(
+    capacity: number,
+    origin: ApplicationJobOrigin
+  ): ApplicationJobReceiveRotationPort;
+  acquire(
+    signal: AbortSignal | undefined,
+    origin: ApplicationJobOrigin
+  ): Promise<ApplicationJobPermitPort>;
+  /** Returns a grant now, or registers one FIFO waiter that later calls resume. */
+  acquireOrResume(
+    resume: (permit: ApplicationJobPermitPort) => void,
+    reject: (reason: unknown) => void,
+    signal: AbortSignal | undefined,
+    origin: ApplicationJobOrigin
+  ): ApplicationJobPermitPort | undefined;
   registerReceiveFlowTarget?(
     identity: object,
     applyState: (state: 'running' | 'paused') => void,