@zlink-systems/framework 0.30.1 → 0.30.2

package/src/runtime/actors/actor-mailbox.ts

@@ -8,8 +8,10 @@ import {
 import { runZLinkActorExecution } from './actor-execution-context';
 import {
   bindApplicationJobPermit,
-  hasApplicationJobPermit
+  currentApplicationJobPermit,
+  runWithApplicationJobPermit
 } from '../application-jobs/application-job-queue-scope';
+import type { ApplicationJobPermitPort } from '../application-jobs/contracts';
 
 export class ZLinkActorSerialExecutor {
   private readonly scheduler: ZLinkSerialExecutionQueue;
@@ -28,10 +30,46 @@ export class ZLinkActorSerialExecutor {
   }
 
   execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
+    const initial = currentApplicationJobPermit();
+    if (
+      initial !== undefined &&
+      workOptions?.lane !== 'lifecycle' &&
+      this.scheduler.hasPendingDurableApplication
+    ) {
+      let prepared: ApplicationJobPermitPort | undefined;
+      const cancel = (): void => {
+        prepared?.releaseAfterInternalProcessing();
+        prepared = undefined;
+      };
+      const terminal = this.scheduler.admitDurablePrefix(
+        () =>
+          runWithApplicationJobPermit(prepared!, () =>
+            runZLinkActorExecution(this.actorId, this.sourceSpotId, operation)
+          ),
+        workOptions,
+        undefined,
+        {
+          prepare: async (signal) => {
+            if (initial.reacquire === undefined) {
+              throw new Error('Durable Actor ingress requires its host permit source.');
+            }
+            prepared = await initial.reacquire(signal);
+            if (signal.aborted) {
+              cancel();
+              throw signal.reason;
+            }
+            prepared.markApplicationQueued();
+          },
+          cancel
+        }
+      );
+      initial.releaseAfterInternalProcessing();
+      return terminal;
+    }
     const boundOperation = bindApplicationJobPermit(() =>
       runZLinkActorExecution(this.actorId, this.sourceSpotId, operation)
     );
-    return hasApplicationJobPermit()
+    return initial !== undefined
       ? this.scheduler.submitPreAdmitted(boundOperation, workOptions)
       : this.scheduler.submit(boundOperation, workOptions);
   }

package/src/runtime/actors/actor-remote-joiner.ts

@@ -164,7 +164,12 @@ export class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCoordinato
     result: ZLinkActorJoinRuntimeResult<Message>,
     operationId: import('../../contracts').ZLinkActorJoinOperationId | undefined
   ): ZLinkActorJoinRuntimeResult<Message> {
-    if (operationId === undefined || this.options.sourceTransfer === undefined) return result;
+    if (
+      result.sourceCleanup !== undefined ||
+      operationId === undefined ||
+      this.options.sourceTransfer === undefined
+    )
+      return result;
     return {
       ...result,
       finalizeDeferredJoin: async () => {

package/src/runtime/actors/actor-reply.ts

@@ -0,0 +1,42 @@
+import { encodeFrameworkPayload } from '../messaging/payload-codec';
+import {
+  decodeStreamHeader,
+  encodeStreamFrame,
+  streamCodecForContentType,
+  ZLinkStreamHeaderFlags,
+  ZLinkStreamMessageKind
+} from '../streams/protocol';
+
+/** Ordinary dispatch and relocation use the same typed Actor reply envelope. */
+export function encodeActorReply(
+  requestHeaderBytes: Uint8Array,
+  kind: ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error,
+  payload: unknown,
+  serializers: Parameters<typeof encodeFrameworkPayload>[1],
+  flowEnabled: boolean
+): readonly Buffer[] {
+  const requestHeader = decodeStreamHeader(requestHeaderBytes, flowEnabled);
+  const encoded =
+    kind === ZLinkStreamMessageKind.Response
+      ? encodeFrameworkPayload(payload, serializers, requestHeader.name, 'reply')
+      : encodeFrameworkPayload(payload);
+  try {
+    const frame = encodeStreamFrame(
+      {
+        kind,
+        codec: streamCodecForContentType(encoded.contentType),
+        flags: ZLinkStreamHeaderFlags.None,
+        requestSeq: requestHeader.requestSeq,
+        name: '',
+        metadata: new Map(),
+        correlationId: requestHeader.correlationId,
+        flowId: requestHeader.flowId,
+        flowOrigin: requestHeader.flowOrigin
+      },
+      encoded.message.data()
+    );
+    return [Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength)];
+  } finally {
+    encoded.message.close();
+  }
+}

package/src/runtime/actors/actor-runtime-contracts.ts

@@ -19,6 +19,8 @@ import type { ZLinkRuntimeAdmissionGate } from '../admission';
 import type { ZLinkActivationAdmission } from '../activation-admission';
 
 export interface ZLinkActorJoinRuntimeResult<TReply> {
+  /** Relay-ready transferred completion; this continuation only releases source work. */
+  readonly sourceCleanup?: () => Promise<void>;
   readonly accepted: boolean;
   readonly actor?: import('../../contracts').ActorRef;
   readonly reply?: TReply;

package/src/runtime/actors/actor-runtime-state.ts

@@ -94,14 +94,8 @@ function sameRemoteSessionOwnerLifecycle(
     right.sessionNodeRid !== undefined &&
     left.sessionOwnerNodeGeneration !== undefined &&
     right.sessionOwnerNodeGeneration !== undefined &&
-    left.sessionOwnerId !== undefined &&
-    right.sessionOwnerId !== undefined &&
-    left.sessionOwnerLeaseGeneration !== undefined &&
-    right.sessionOwnerLeaseGeneration !== undefined &&
     routingIdsEqual(left.sessionNodeRid, right.sessionNodeRid) &&
-    left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration &&
-    left.sessionOwnerId === right.sessionOwnerId &&
-    left.sessionOwnerLeaseGeneration === right.sessionOwnerLeaseGeneration
+    left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration
   );
 }
 
@@ -495,19 +489,7 @@ export class ZLinkActorRuntimeState {
     ) {
       throw new TypeError('An installed bound Session target requires its binding identity.');
     }
-    const current = this.boundSessionValue;
-    if (current !== undefined && sameRemoteSessionOwnerLifecycle(current, target)) {
-      // A duplicate or late older command for the exact physical Session
-      // leaves the current binding; a newer generation of the same Session
-      // replaces it. A different Session in the same owner lifecycle must
-      // advance that lifecycle's generation; a late equal/lower one is stale.
-      const advances =
-        current.bindingGeneration === undefined ||
-        target.bindingGeneration > current.bindingGeneration;
-      if (!advances) return sameRemoteSessionOwner(current, target);
-    }
-    // Binding generations are scoped to a Session-owner lifecycle. A restarted
-    // owner can legitimately reset its counter below the predecessor value.
+    // The service registry accepted this identity in the Actor owner turn.
     this.boundSessionValue = boundSessionIdentity(target);
     return true;
   }

package/src/runtime/actors/actor-source-transfer.ts

@@ -1,35 +1,10 @@
-import type { ActorRef, ZLinkActor, ZLinkMessage } from '../../contracts';
+import type { ActorRef, ZLinkActor } from '../../contracts';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from './actor-handoff';
-import type { ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
-
-export interface ZLinkPreparedActorSource {
-  readonly adapterKey?: string;
-  readonly state: ZLinkMessage;
-  readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
-  readonly sourceLeaveCompletion?: Promise<void>;
-  readonly sourceLeaveSubmitted?: Promise<void>;
-  onSourceLeaveSubmitted(notify: () => Promise<void>): void;
-  observeTargetAuthority(
-    target: ZLinkSpotRouteTarget,
-    targetActorRef: ActorRef,
-    signal?: AbortSignal
-  ): Promise<void>;
-  commit(
-    target: ZLinkSpotRouteTarget,
-    targetActorRef: ActorRef,
-    results: readonly ZLinkActorHandoffResult[],
-    releaseLocation?: boolean
-  ): void;
-  rollback(): Promise<void>;
-}
 
 export interface ZLinkActorSourceTransfer {
   /** Starts the ingress handoff before target route lookup. */
   beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
-  /** Changes a provisional ingress fence into a relocation handoff. */
-  promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
   /** Finishes a same-node deferred Join handoff after completion callback. */
   completeDeferredActorHandoff?(
     actor: ZLinkActor,
@@ -38,12 +13,4 @@ export interface ZLinkActorSourceTransfer {
   ): Promise<void>;
   /** Releases an early handoff when Join cannot commit. */
   cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
-  prepareSource(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    signal?: AbortSignal,
-    lifecycleAuthority?: 'framework' | 'core',
-    deferredJoin?: boolean,
-    relocation?: ServiceWireOperationId
-  ): Promise<ZLinkPreparedActorSource>;
 }

package/src/runtime/actors/index.ts

@@ -42,11 +42,7 @@ import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-ro
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
 const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 
-export {
-  DefaultZLinkActorClient,
-  forwardEncodedActorPacket,
-  type ZLinkActorClientOptions
-} from './actor-client';
+export { DefaultZLinkActorClient, type ZLinkActorClientOptions } from './actor-client';
 export { DefaultZLinkActorContext, ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME } from './actor-context';
 export { ZLinkActorSerialExecutor } from './actor-mailbox';
 export {
@@ -400,6 +396,11 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
 
   async findActor(actorId: string, signal?: AbortSignal): Promise<ZLinkActor | undefined> {
     throwIfAborted(signal);
+    return this.resolveLocalActor(actorId);
+  }
+
+  /** @internal Uses the relocation owner's publication boundary for local dispatch. */
+  resolveLocalActor(actorId: string): ZLinkActor | undefined {
     if (this.relocationStaged.has(actorId)) return undefined;
     return this.states.get(actorId)?.actor;
   }
@@ -474,7 +475,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       if (nativeRef !== undefined) node.discardRelocatedActor?.(nativeRef);
       this.relocationStaged.delete(actorId);
       const failedState = this.states.get(actorId);
-      await this.finalizeActorState(actorId, failedState);
+      await this.finalizeActorState(failedState);
       throw error;
     }
   }
@@ -497,6 +498,13 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     await this.releaseLocalActor(actorId, sourceActorRef);
   }
 
+  /** Commit removes current ownership; a Join profile may still own its leave callback. */
+  detachRelocationSource(state: ZLinkActorRuntimeState): void {
+    if (this.detachActorStateRegistration(state)) {
+      this.discardNativeRelocationSource(state.nativeActorRef);
+    }
+  }
+
   async releaseSpotActorMembers(meshName: string, spotId?: RoutingId): Promise<void> {
     const results = await Promise.allSettled(
       [...this.states.values()]
@@ -515,18 +523,15 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     exactNativeActorRef?: ZLinkBackendActorRef
   ): Promise<void> {
     const state = this.states.get(actorId);
-    const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
-    const nativeActorRef = exactNativeActorRef ?? state?.nativeActorRef;
+    if (state === undefined) return;
     const failures: unknown[] = [];
     try {
-      if (nativeActorRef !== undefined) {
-        node?.discardRelocatedActor?.(nativeActorRef);
-      }
+      this.discardNativeRelocationSource(exactNativeActorRef ?? state.nativeActorRef);
     } catch (error) {
       failures.push(error);
     }
     try {
-      await this.completeCoreRelocationSource(actorId);
+      await this.completeCoreRelocationSource(actorId, state);
     } catch (error) {
       failures.push(error);
     }
@@ -537,29 +542,38 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     }
   }
 
-  async completeCoreRelocationSource(actorId: string): Promise<void> {
-    const state = this.states.get(actorId);
-    await this.finalizeActorState(actorId, state);
-  }
-
-  private async finalizeActorState(
+  async completeCoreRelocationSource(
     actorId: string,
-    state: ZLinkActorRuntimeState | undefined
+    state = this.states.get(actorId)
   ): Promise<void> {
-    if (state === undefined || this.states.get(actorId) !== state) return;
+    await this.finalizeActorState(state);
+  }
+
+  private discardNativeRelocationSource(nativeActorRef: ZLinkBackendActorRef | undefined): void {
+    if (nativeActorRef === undefined) return;
+    const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
+    node?.discardRelocatedActor?.(nativeActorRef);
+  }
+
+  private async finalizeActorState(state: ZLinkActorRuntimeState | undefined): Promise<void> {
+    if (state === undefined) return;
     try {
       if (state.actor !== undefined)
         await disposeLifecycleHandlers(state.actor, this.detachedTaskRunner);
     } finally {
       state.clearAfterDestroy();
-      if (this.states.get(actorId) === state) {
-        this.states.delete(actorId);
-        this.actorMeshNames.delete(actorId);
-        this.relocationStaged.delete(actorId);
-      }
+      this.detachActorStateRegistration(state);
     }
   }
 
+  private detachActorStateRegistration(state: ZLinkActorRuntimeState): boolean {
+    if (this.states.get(state.actorId) !== state) return false;
+    this.states.delete(state.actorId);
+    this.actorMeshNames.delete(state.actorId);
+    this.relocationStaged.delete(state.actorId);
+    return true;
+  }
+
   private async finalizeDestroyedActor(
     actorId: string,
     state: ZLinkActorRuntimeState
@@ -568,7 +582,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     try {
       this.options.actorDestroyedCleanup?.(actorId);
     } finally {
-      await this.finalizeActorState(actorId, state);
+      await this.finalizeActorState(state);
       this.options.metrics?.change(METRIC_NAMES.ActorCount, -1);
     }
   }
@@ -944,7 +958,7 @@ class ZLinkActorCreateCallRuntime implements ZLinkActorCreateCall {
   yield(signal?: AbortSignal): Promise<ZLinkActorCreateResult> {
     const turn = requireZLinkYieldTurn(this.turn);
     const pending = this.executeOnce(signal);
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 
   private executeOnce(signal?: AbortSignal): Promise<ZLinkActorCreateResult> {

package/src/runtime/actors/session-disconnected-wire.ts

@@ -0,0 +1,66 @@
+import type { RoutingId } from '../../contracts';
+import { ZLINK_MAX_ROUTING_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
+import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
+
+const RID_LENGTH_BYTES = 1;
+const GENERATION_BYTES = 8;
+const GENERATIONS_BYTES = GENERATION_BYTES * 2;
+
+export interface SessionDisconnectedIdentity {
+  readonly sessionOwnerNodeRid: RoutingId;
+  readonly sessionOwnerNodeGeneration: bigint;
+  readonly bindingGeneration: bigint;
+}
+
+export function encodeSessionDisconnected(
+  sessionOwnerNodeRid: RoutingId | undefined,
+  sessionOwnerNodeGeneration: bigint | undefined,
+  bindingGeneration: bigint | undefined
+): Buffer {
+  if (
+    sessionOwnerNodeRid === undefined ||
+    sessionOwnerNodeGeneration === undefined ||
+    sessionOwnerNodeGeneration === 0n ||
+    bindingGeneration === undefined ||
+    bindingGeneration === 0n
+  ) {
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.ProtocolError,
+      'Session disconnect requires an exact binding identity.'
+    );
+  }
+  const rid = Buffer.from(encodeRoutingIdStorageHex(sessionOwnerNodeRid), 'hex');
+  if (rid.length === 0 || rid.length > ZLINK_MAX_ROUTING_ID_BYTES) {
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.ProtocolError,
+      'Invalid Session owner Node RID length.'
+    );
+  }
+  const payload = Buffer.allocUnsafe(RID_LENGTH_BYTES + rid.length + GENERATIONS_BYTES);
+  payload[0] = rid.length;
+  rid.copy(payload, RID_LENGTH_BYTES);
+  payload.writeBigUInt64BE(sessionOwnerNodeGeneration, RID_LENGTH_BYTES + rid.length);
+  payload.writeBigUInt64BE(bindingGeneration, RID_LENGTH_BYTES + rid.length + GENERATION_BYTES);
+  return payload;
+}
+
+export function decodeSessionDisconnected(
+  bytes: Uint8Array
+): SessionDisconnectedIdentity | undefined {
+  const payload = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (payload.length < RID_LENGTH_BYTES + 1 + GENERATIONS_BYTES) return undefined;
+  const ridLength = payload[0];
+  if (ridLength === 0 || payload.length !== RID_LENGTH_BYTES + ridLength + GENERATIONS_BYTES)
+    return undefined;
+  const offset = RID_LENGTH_BYTES + ridLength;
+  const sessionOwnerNodeGeneration = payload.readBigUInt64BE(offset);
+  const bindingGeneration = payload.readBigUInt64BE(offset + GENERATION_BYTES);
+  if (sessionOwnerNodeGeneration === 0n || bindingGeneration === 0n) return undefined;
+  const hex = payload.subarray(RID_LENGTH_BYTES, offset).toString('hex');
+  return {
+    sessionOwnerNodeRid: decodeRoutingId(hex, hex),
+    sessionOwnerNodeGeneration,
+    bindingGeneration
+  };
+}

package/src/runtime/admission.ts

@@ -2,8 +2,15 @@ import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
 } from './framework-errors-internal';
+import { isPromiseLike } from './abort';
 const BACKING_ARRAY_COMPACTION_MIN_HEAD = 1024;
 
+/** Runs host admission inside the domain's request completion boundary. */
+export type ZLinkMeshDispatchAdmission = (
+  dispatch: () => void | Promise<void>,
+  onRejected?: (error: unknown) => void | Promise<void>
+) => void | Promise<void>;
+
 /** 소비한 배열 prefix가 정리 조건에 도달했는지 판정합니다. */
 export function shouldCompactBackingArray(head: number, length: number): boolean {
   return head >= BACKING_ARRAY_COMPACTION_MIN_HEAD && head * 2 >= length;
@@ -64,21 +71,63 @@ export class ZLinkRuntimeAdmissionGate {
   }
 
   claim(meshName: string, operation: string): ZLinkApplicationWorkClaim {
+    const state = this.enter(meshName, operation);
+    let closed = false;
+    return {
+      close: () => {
+        if (closed) return;
+        closed = true;
+        exitAdmission(state);
+      }
+    };
+  }
+
+  /**
+   * Runs one admitted unit of work. Work that completes synchronously leaves
+   * admission in the same turn; asynchronous work leaves it from the single
+   * continuation on its result.
+   */
+  run<T>(
+    meshName: string,
+    operation: string,
+    work: () => T | Promise<T>,
+    onRejected?: (error: unknown) => T | Promise<T>
+  ): T | Promise<T> {
+    let state: ZLinkMeshAdmissionState;
+    let result: T | Promise<T>;
+    try {
+      state = this.enter(meshName, operation);
+    } catch (error) {
+      // The domain owns admission rejection completion, just as it owns handler failure.
+      return onRejected === undefined ? Promise.reject(error) : onRejected(error);
+    }
+    try {
+      result = work();
+    } catch (error) {
+      exitAdmission(state);
+      return Promise.reject(error);
+    }
+    if (!isPromiseLike(result)) {
+      exitAdmission(state);
+      return result;
+    }
+    return Promise.resolve(result).then(
+      (value) => {
+        exitAdmission(state);
+        return value;
+      },
+      (error: unknown) => {
+        exitAdmission(state);
+        throw error;
+      }
+    );
+  }
+
+  private enter(meshName: string, operation: string): ZLinkMeshAdmissionState {
     const state = this.requireState(meshName);
     if (this.ownerAdmissionOpen() && !state.sealed) {
       state.active += 1;
-      let closed = false;
-      return {
-        close: () => {
-          if (closed) return;
-          closed = true;
-          state.active -= 1;
-          if (state.active === 0) {
-            let resolve: (() => void) | undefined;
-            while ((resolve = takeWaiter(state)) !== undefined) resolve();
-          }
-        }
-      };
+      return state;
     }
     throw createInternalFrameworkException(
       state.sealedReason,
@@ -86,28 +135,6 @@ export class ZLinkRuntimeAdmissionGate {
     );
   }
 
-  run<T>(meshName: string, operation: string, work: () => T | Promise<T>): Promise<T> {
-    let claim: ZLinkApplicationWorkClaim | undefined;
-    try {
-      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);
-    }
-  }
-
   awaitZero(meshName: string, signal?: AbortSignal): Promise<void> {
     const state = this.requireState(meshName);
     if (state.active === 0) return Promise.resolve();
@@ -191,6 +218,14 @@ interface ZLinkMeshAdmissionState {
   waiterCount: number;
 }
 
+function exitAdmission(state: ZLinkMeshAdmissionState): void {
+  state.active -= 1;
+  if (state.active === 0) {
+    let resolve: (() => void) | undefined;
+    while ((resolve = takeWaiter(state)) !== undefined) resolve();
+  }
+}
+
 function takeWaiter(state: ZLinkMeshAdmissionState): (() => void) | undefined {
   advanceWaiterHead(state);
   const waiter = state.waiters[state.waiterHead];

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

@@ -5,11 +5,38 @@ import type { ApplicationJobOrigin, ApplicationJobPermitPort } from './contracts
 const applicationJobPermitScope = new AsyncLocalStorage<ApplicationJobPermitPort | undefined>();
 
 function releasePermitTurn(): void {
-  const permit = applicationJobPermitScope.getStore();
+  releaseApplicationJobPermitTurn(applicationJobPermitScope.getStore());
+}
+
+/** Ends the internal processing of one record turn unless its handler detached the permit. */
+export function releaseApplicationJobPermitTurn(
+  permit: ApplicationJobPermitPort | undefined
+): void {
   if (permit !== undefined && !permit.detachedForHandlerTurn)
     permit.releaseAfterInternalProcessing();
 }
 
+/**
+ * Makes `permit` the current record's permit for the synchronous part of a
+ * dispatch. The caller restores the returned previous scope with
+ * {@link leaveApplicationJobPermitScope} and releases the turn itself, so a
+ * dispatcher that already continues on the handler result needs no second
+ * continuation here.
+ */
+export function enterApplicationJobPermitScope(
+  permit: ApplicationJobPermitPort
+): ApplicationJobPermitPort | undefined {
+  const previous = applicationJobPermitScope.getStore();
+  applicationJobPermitScope.enterWith(permit);
+  return previous;
+}
+
+export function leaveApplicationJobPermitScope(
+  previous: ApplicationJobPermitPort | undefined
+): void {
+  applicationJobPermitScope.enterWith(previous);
+}
+
 function releasePermitSuccess<TResult>(value: TResult): TResult {
   releasePermitTurn();
   return value;
@@ -72,6 +99,11 @@ export function hasApplicationJobPermit(): boolean {
   return applicationJobPermitScope.getStore() !== undefined;
 }
 
+/** The current ingress reservation; capacity remains owned by its host queue. */
+export function currentApplicationJobPermit(): ApplicationJobPermitPort | undefined {
+  return applicationJobPermitScope.getStore();
+}
+
 /** Keeps the ingress origin when a durable record later reacquires its permit. */
 export function currentApplicationJobOrigin(): ApplicationJobOrigin {
   return applicationJobPermitScope.getStore()!.origin;

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

@@ -1,6 +1,8 @@
 export type ApplicationJobOrigin = 'local' | 'remote';
 
 export interface ApplicationJobPermitPort {
+  /** Reacquires this record's host supply after durable FIFO ownership. */
+  reacquire?(signal: AbortSignal): Promise<ApplicationJobPermitPort>;
   readonly origin: ApplicationJobOrigin;
   readonly detachedForHandlerTurn: boolean;
   markApplicationQueued(): void;