@zlink-systems/framework 0.30.0 → 0.30.1

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

@@ -16,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) {}
@@ -46,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();
@@ -67,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();
   }
 
@@ -79,14 +97,12 @@ 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 {
@@ -103,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();
   }
 
@@ -122,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?.();
+    }
   }
 }
 
@@ -203,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

@@ -2,39 +2,69 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 
 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();
+}
+
+function releasePermitSuccess<TResult>(value: TResult): TResult {
+  releasePermitTurn();
+  return value;
 }
 
-const applicationJobPermitScope = new AsyncLocalStorage<ApplicationJobPermitScope>();
+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> | 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: () => Promise<TResult>
+): Promise<TResult>;
+export function runWithApplicationJobPermit<TResult, TFirst = undefined, TSecond = undefined>(
+  permit: ApplicationJobPermitPort,
+  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. */
@@ -44,7 +74,7 @@ export function hasApplicationJobPermit(): boolean {
 
 /** Keeps the ingress origin when a durable record later reacquires its permit. */
 export function currentApplicationJobOrigin(): ApplicationJobOrigin {
-  return applicationJobPermitScope.getStore()!.permit.origin;
+  return applicationJobPermitScope.getStore()!.origin;
 }
 
 /** Re-enters the captured permit scope when a serial executor runs later. */
@@ -61,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

@@ -2,14 +2,27 @@ 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 {
+  createReceiveRotation(
+    capacity: number,
+    origin: ApplicationJobOrigin
+  ): ApplicationJobReceiveRotationPort;
   acquire(
     signal: AbortSignal | undefined,
     origin: ApplicationJobOrigin

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

@@ -62,6 +62,7 @@ export type ZLinkBackendObjectPlacement =
   | { readonly kind: 'unavailable' };
 
 export interface ZLinkBackendMeshNode {
+  readonly routingId?: RoutingId;
   completeClosedInstance?(spotId: string, objectGeneration: bigint): void;
   setDispatchErrorReporter?(
     reporter: import('../../channels/dispatch-error-reporter').ZLinkDispatchErrorReporter,
@@ -125,7 +126,8 @@ export interface ZLinkBackendMeshNode {
     parts: ZLinkBackendMessageLike | readonly ZLinkBackendMessageLike[],
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): MeshOperationId;
   sendToInstanceSpot(
     route: ServiceInstanceRouteFence,
@@ -140,7 +142,8 @@ export interface ZLinkBackendMeshNode {
     timeoutMs?: number,
     sourceSpotId?: string,
     metadata?: ReadonlyMap<string, string>,
-    instanceIntent?: boolean
+    instanceIntent?: boolean,
+    onAdmitted?: () => void
   ): MeshOperationId;
   registerUserSpotOperationHandler(handler: ServiceUserSpotOperationHandler): void;
   requestUserSpotCreate(
@@ -182,12 +185,16 @@ export interface ZLinkBackendMeshNode {
     readonly lifecycleGeneration: bigint;
   }): 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;
   sendToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
     options?: { flags?: number }
-  ): Promise<SubmitResult>;
+  ): SubmitResult | Promise<SubmitResult>;
   /**
    * Sends service-wire infrastructure frames directly to a peer. Relocation
    * Prepare may add NODE-INTERNAL sideband frames after its canonical frame.
@@ -208,12 +215,21 @@ export interface ZLinkBackendMeshNode {
   requestInfrastructureControlFrames?(
     targetRid: unknown,
     frames: readonly Uint8Array[],
-    options?: { readonly timeoutMs?: number }
+    options?: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onSubmitted?: (signal: AbortSignal) => Promise<void>;
+    }
   ): Promise<readonly Uint8Array[]>;
   requestToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendToChannel(
     channelName: string,
@@ -223,7 +239,12 @@ export interface ZLinkBackendMeshNode {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   status(): MeshNodeStatus;
   peers(): MeshPeerEntry[];
@@ -349,7 +370,12 @@ export interface ZLinkBackendMeshNode {
   requestToActor(
     actor: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   actorSendToActor(
     source: ZLinkBackendActorRef,
@@ -361,7 +387,12 @@ export interface ZLinkBackendMeshNode {
     source: ZLinkBackendActorRef,
     target: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { flags?: number; timeoutMs?: number; applicationMetadata?: Buffer }
+    options?: {
+      flags?: number;
+      timeoutMs?: number;
+      applicationMetadata?: Buffer;
+      onAdmitted?: () => void;
+    }
   ): MeshOperationId;
   sendActorBoundSession(
     actor: ZLinkBackendActorRef,
@@ -484,7 +515,11 @@ export interface ZLinkBackendDealerSocket extends ZLinkBackendConnectableSocket
   receiveTimeoutMs: number;
   maxMessageSize: number;
   send(message: Message | readonly Message[]): Promise<void>;
-  request(message: Message | readonly Message[], timeoutMs?: number): Promise<readonly Message[]>;
+  request(
+    message: Message | readonly Message[],
+    timeoutMs?: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Message[]>;
   recv(flags?: ZLinkBackendRecvFlags): Received | undefined;
 }
 
@@ -501,7 +536,7 @@ export interface ZLinkBackendSendOperation {
 export interface ZLinkBackendRequestOperation {
   message(message: MessageLike): ZLinkBackendRequestOperation;
   timeout(timeoutMs: number): ZLinkBackendRequestOperation;
-  submit(): Promise<readonly Message[]>;
+  submit(onAdmitted?: () => void): Promise<readonly Message[]>;
 }
 
 export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket {
@@ -519,7 +554,8 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
   request(
     routingId: RoutingId,
     message: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   sendToSpot(
     targetNodeRid: RoutingId,
@@ -531,7 +567,8 @@ export interface ZLinkBackendRouterSocket extends ZLinkBackendConnectableSocket
     targetNodeRid: RoutingId,
     targetSpotId: RoutingId,
     parts: readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   disconnectPeer(routingId: RoutingId): void;
   reply(routingId: RoutingId, replyToken: unknown): ZLinkBackendReplyOperation;
@@ -688,7 +725,8 @@ export interface ZLinkBackendSpot extends ZLinkBackendObject {
   requestToChannel(
     channelName: string,
     payload: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   sendToChannel(channelName: string, payload: Message | readonly Message[]): Promise<void>;
   publish(
@@ -705,7 +743,8 @@ export interface ZLinkBackendSpot extends ZLinkBackendObject {
     targetRid: RoutingId,
     spotId: RoutingId,
     payload: Message | readonly Message[],
-    timeoutMs?: number
+    timeoutMs?: number,
+    onAdmitted?: () => void
   ): Promise<readonly Message[]>;
   dispose(): Promise<void>;
 }