@zlink-systems/framework 0.30.2 → 0.30.3

package/dist/runtime/execution/index.js

@@ -192,6 +192,11 @@ function isCurrentZLinkSpotSerialTurn(executor) {
         current.executor === executor &&
         executor.isActiveTurn(current.turn, current.turnId));
 }
+function createExecutionBarrierAdmissionException(seal, message) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(seal.kind === 'close'
+        ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+        : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, message);
+}
 /**
  * Seals application-lane admission and waits for every active Promise turn to
  * finish. A seal generation prevents a stale abort from reopening a newer
@@ -215,14 +220,9 @@ class ZLinkExecutionBarrier {
     }
     enter() {
         if (this.committedSeal !== undefined) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(this.committedSeal.kind === 'close'
-                ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected
-                : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'ZLink execution barrier is committed.');
+            throw createExecutionBarrierAdmissionException(this.committedSeal, 'ZLink execution barrier is committed.');
         }
         if (this.currentSeal !== undefined) {
-            if (this.currentSeal.kind === 'close') {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'ZLink execution barrier is sealed for Close.');
-            }
             return new Promise((resolve, reject) => {
                 this.admissionWaiters.push({ resolve, reject });
             });
@@ -302,9 +302,7 @@ class ZLinkExecutionBarrier {
             return false;
         this.currentSeal = undefined;
         this.committedSeal = seal;
-        const error = (0, framework_errors_internal_1.createInternalFrameworkException)(seal.kind === 'close'
-            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected
-            : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'ZLink execution barrier is committed.');
+        const error = createExecutionBarrierAdmissionException(seal, 'ZLink execution barrier is committed.');
         for (const waiter of this.admissionWaiters)
             waiter.reject(error);
         this.admissionWaiters.length = 0;

package/dist/runtime/execution/state-lane.js

@@ -18,6 +18,10 @@ function startOutsideStateLane(work) {
 }
 const currentLaneStorage = new node_async_hooks_1.AsyncLocalStorage();
 const diagnosticPending = isStructuralGuardEnabled() ? new Map() : undefined;
+const diagnosticLaneIds = isStructuralGuardEnabled()
+    ? new WeakMap()
+    : undefined;
+let nextDiagnosticLane = 0;
 let nextDiagnosticWork = 0;
 const diagnosticTurnStorage = diagnosticPending === undefined ? undefined : new node_async_hooks_1.AsyncLocalStorage();
 /**
@@ -132,15 +136,24 @@ if (isStructuralGuardEnabled()) {
     });
     const run = ZLinkStateLane.prototype.run;
     ZLinkStateLane.prototype.run = function (work) {
-        const completion = run.call(this, () => runDiagnosticTurn(this, work));
-        return guardStateLaneCompletion(trackDiagnosticCompletion(completion, `state lane ${diagnosticWorkName(work)}`), 'another state lane completion', this);
+        const release = registerDiagnosticWork(`${diagnosticLaneName(this)} ${diagnosticWorkName(work)}`);
+        let completion;
+        try {
+            completion = run.call(this, () => runDiagnosticTurn(this, work, release.description));
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+        void completion.then(release, release);
+        return guardStateLaneCompletion(completion, `another state lane completion [${release.description}]`, this);
     };
     const tryPost = ZLinkStateLane.prototype.tryPost;
     ZLinkStateLane.prototype.tryPost = function (work) {
-        const release = registerDiagnosticWork(`state lane post ${diagnosticWorkName(work)}`);
+        const release = registerDiagnosticWork(`${diagnosticLaneName(this)} post ${diagnosticWorkName(work)}`);
         const accepted = tryPost.call(this, () => {
             try {
-                const result = runDiagnosticTurn(this, work);
+                const result = runDiagnosticTurn(this, work, release.description);
                 if (result instanceof Promise)
                     return result.finally(release);
                 release();
@@ -156,8 +169,8 @@ if (isStructuralGuardEnabled()) {
         return accepted;
     };
 }
-function runDiagnosticTurn(lane, work) {
-    const turn = { lane, active: true };
+function runDiagnosticTurn(lane, work, description) {
+    const turn = { lane, description, active: true };
     return diagnosticTurnStorage.run(turn, () => {
         try {
             const result = work();
@@ -183,7 +196,8 @@ function guardStateLaneCompletion(completion, label, owner) {
                 return (onFulfilled, onRejected) => {
                     const current = ZLinkStateLane.current;
                     if (current !== undefined && current !== owner) {
-                        throw new Error(`A state lane turn cannot wait for ${label}.`);
+                        throw new Error(`A state lane turn cannot wait for ${label}. ` +
+                            `current turn: ${diagnosticTurnStorage?.getStore()?.description ?? UNKNOWN_DIAGNOSTIC_CALLER}`);
                     }
                     return target.then(onFulfilled, onRejected);
                 };
@@ -210,16 +224,25 @@ function debugPendingWorkNames() {
 function diagnosticWorkName(work) {
     return work.name.length > 0 ? work.name : '<anonymous>';
 }
+function diagnosticLaneName(lane) {
+    let id = diagnosticLaneIds.get(lane);
+    if (id === undefined) {
+        id = ++nextDiagnosticLane;
+        diagnosticLaneIds.set(lane, id);
+    }
+    return `state lane #${id}`;
+}
 function registerDiagnosticWork(name) {
     if (diagnosticPending === undefined)
-        return () => undefined;
+        return Object.assign(() => undefined, { description: name });
     const id = ++nextDiagnosticWork;
     const frames = new Error().stack?.split('\n').slice(2) ?? [];
     const caller = frames
         .find((frame) => !frame.includes('state-lane.') && !frame.includes('serial-execution-queue.'))
         ?.trim() ?? UNKNOWN_DIAGNOSTIC_CALLER;
-    diagnosticPending.set(id, `${name} ${caller}`);
-    return () => {
+    const description = `${name} ${caller}`;
+    diagnosticPending.set(id, description);
+    return Object.assign(() => {
         diagnosticPending.delete(id);
-    };
+    }, { description });
 }

package/dist/runtime/locations/auto-connect-loop.d.ts

@@ -26,6 +26,7 @@ export declare class ZLinkAutoConnectLoop {
     private lastStamp?;
     private lastLiveOwnerSetVersion?;
     private lastTickFailed;
+    private inFlightTick;
     constructor(options: ZLinkAutoConnectLoopOptions);
     start(signal?: AbortSignal): Promise<void>;
     requestPeerReconcile(meshName: string, _peerRid: string): Promise<void>;
@@ -33,6 +34,7 @@ export declare class ZLinkAutoConnectLoop {
     prepareTransportShutdown(): Promise<void>;
     finishTransportShutdown(signal?: AbortSignal): Promise<void>;
     tick(signal?: AbortSignal): Promise<void>;
+    private enqueueTick;
     private tickCore;
     private runReconcile;
     private scheduleNext;

package/dist/runtime/locations/auto-connect-loop.js

@@ -17,6 +17,8 @@ class ZLinkAutoConnectLoop {
     lastStamp;
     lastLiveOwnerSetVersion;
     lastTickFailed = false;
+    // This settled tail orders whole operations. The tick fields below are touched only inside it.
+    inFlightTick = Promise.resolve();
     constructor(options) {
         this.reconciler = options.reconciler;
         this.options = { ...Options_1.zlinkRuntimeDefaultLocationOptions, ...options.options };
@@ -45,7 +47,7 @@ class ZLinkAutoConnectLoop {
         if (meshName !== this.meshName || controller === undefined)
             return;
         // A fresh descriptor scan uses the same RID ordering and connection owner as a periodic tick.
-        await this.lane.run(async () => {
+        await this.enqueueTick(async () => {
             if (!controller.signal.aborted)
                 await this.runReconcile(controller.signal);
         });
@@ -64,13 +66,24 @@ class ZLinkAutoConnectLoop {
             this.clearTimer(this.timer);
             this.timer = undefined;
         }
+        await this.inFlightTick;
         this.reconciler.disconnectPeers();
     }
     async finishTransportShutdown(signal) {
         await this.reconciler.unpublishLocal(signal);
     }
     async tick(signal) {
-        await this.lane.run(() => this.tickCore(signal));
+        const controller = this.controller;
+        await this.enqueueTick(async () => {
+            if (controller?.signal.aborted !== true)
+                await this.tickCore(signal ?? controller?.signal);
+        });
+    }
+    enqueueTick(operation) {
+        const completion = this.inFlightTick.then(operation);
+        // The caller receives the failure; the successor still owns its place in the order.
+        this.inFlightTick = completion.then(() => undefined, () => undefined);
+        return completion;
     }
     async tickCore(signal) {
         const lastTickFailed = this.lastTickFailed;

package/dist/runtime/spots/index.js

@@ -874,9 +874,6 @@ class DefaultZLinkSpotManager {
     async admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType = 'application/json') {
         const meshName = this.activations.resolveUnique(spotId)?.meshName;
         this.options.admission?.requireRequest('Actor join admission', meshName);
-        if (meshName !== undefined && this.isSpotClosing(meshName, spotId)) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `Spot '${String(spotId)}' is closing.`);
-        }
         return await this.actorMembership.admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType);
     }
     async leaveActor(spotId, actor, signal) {

package/dist/runtime/spots/spot-serial-turn-executor.js

@@ -146,11 +146,14 @@ class ZLinkSpotSerialTurnExecutor {
     }
     /** Admits membership work and holds the lifecycle FIFO until its result settles. */
     executeLifecycleOperation(operation) {
-        let entry;
-        try {
+        const requireAdmission = () => {
             if (this.lifecycleAdmissionClosed) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'Spot lifecycle admission is closed by a committed Close.');
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, 'Spot incarnation is closing (committed Close).');
             }
+        };
+        let entry;
+        try {
+            requireAdmission();
             entry = this.executionBarrier?.enter();
         }
         catch (error) {
@@ -158,7 +161,10 @@ class ZLinkSpotSerialTurnExecutor {
         }
         const submit = (claim) => {
             try {
-                return this.scheduler.submitLifecycleOperation(operation);
+                return this.scheduler.submitLifecycleOperation(() => {
+                    requireAdmission();
+                    return operation();
+                });
             }
             catch (error) {
                 return Promise.reject(error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.30.2",
+  "version": "0.30.3",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.30.2",
+    "@zlink-systems/stream-wire": "0.30.3",
     "@zlink-systems/zlink": "1.20.0"
   }
 }

package/src/runtime/execution/index.ts

@@ -270,6 +270,18 @@ export interface ZLinkExecutionBarrierSeal {
   readonly kind: 'close' | 'relocation' | 'activation';
 }
 
+function createExecutionBarrierAdmissionException(
+  seal: ZLinkExecutionBarrierSeal,
+  message: string
+) {
+  return createInternalFrameworkException(
+    seal.kind === 'close'
+      ? ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+      : ZLinkFrameworkInternalErrorKind.SpotMoving,
+    message
+  );
+}
+
 export interface ZLinkExecutionBarrierClaim {
   release(): void;
   /** The turn yielded; it no longer runs until resume() admits it again. */
@@ -308,20 +320,12 @@ export class ZLinkExecutionBarrier {
 
   enter(): ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> {
     if (this.committedSeal !== undefined) {
-      throw createInternalFrameworkException(
-        this.committedSeal.kind === 'close'
-          ? ZLinkFrameworkInternalErrorKind.RequestRejected
-          : ZLinkFrameworkInternalErrorKind.SpotMoving,
+      throw createExecutionBarrierAdmissionException(
+        this.committedSeal,
         'ZLink execution barrier is committed.'
       );
     }
     if (this.currentSeal !== undefined) {
-      if (this.currentSeal.kind === 'close') {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestRejected,
-          'ZLink execution barrier is sealed for Close.'
-        );
-      }
       return new Promise<ZLinkExecutionBarrierClaim>((resolve, reject) => {
         this.admissionWaiters.push({ resolve, reject });
       });
@@ -400,10 +404,8 @@ export class ZLinkExecutionBarrier {
     if (!this.isCurrent(seal)) return false;
     this.currentSeal = undefined;
     this.committedSeal = seal;
-    const error = createInternalFrameworkException(
-      seal.kind === 'close'
-        ? ZLinkFrameworkInternalErrorKind.RequestRejected
-        : ZLinkFrameworkInternalErrorKind.SpotMoving,
+    const error = createExecutionBarrierAdmissionException(
+      seal,
       'ZLink execution barrier is committed.'
     );
     for (const waiter of this.admissionWaiters) waiter.reject(error);

package/src/runtime/execution/state-lane.ts

@@ -5,6 +5,7 @@ type ZLinkStateLaneWork<T> = () => Promise<T> | T;
 
 interface ZLinkStateLaneTurn {
   readonly lane: ZLinkStateLane;
+  readonly description: string;
   active: boolean;
 }
 
@@ -21,6 +22,10 @@ export function startOutsideStateLane<T>(work: () => T): T {
 
 const currentLaneStorage = new AsyncLocalStorage<ZLinkStateLane>();
 const diagnosticPending = isStructuralGuardEnabled() ? new Map<number, string>() : undefined;
+const diagnosticLaneIds = isStructuralGuardEnabled()
+  ? new WeakMap<ZLinkStateLane, number>()
+  : undefined;
+let nextDiagnosticLane = 0;
 let nextDiagnosticWork = 0;
 const diagnosticTurnStorage =
   diagnosticPending === undefined ? undefined : new AsyncLocalStorage<ZLinkStateLaneTurn>();
@@ -152,10 +157,22 @@ if (isStructuralGuardEnabled()) {
     this: ZLinkStateLane,
     work: ZLinkStateLaneWork<T>
   ): Promise<T> {
-    const completion = run.call(this, () => runDiagnosticTurn(this, work)) as Promise<T>;
+    const release = registerDiagnosticWork(
+      `${diagnosticLaneName(this)} ${diagnosticWorkName(work)}`
+    );
+    let completion: Promise<T>;
+    try {
+      completion = run.call(this, () =>
+        runDiagnosticTurn(this, work, release.description)
+      ) as Promise<T>;
+    } catch (error) {
+      release();
+      throw error;
+    }
+    void completion.then(release, release);
     return guardStateLaneCompletion(
-      trackDiagnosticCompletion(completion, `state lane ${diagnosticWorkName(work)}`),
-      'another state lane completion',
+      completion,
+      `another state lane completion [${release.description}]`,
       this
     );
   };
@@ -165,10 +182,12 @@ if (isStructuralGuardEnabled()) {
     this: ZLinkStateLane,
     work: ZLinkStateLaneWork<void>
   ): boolean {
-    const release = registerDiagnosticWork(`state lane post ${diagnosticWorkName(work)}`);
+    const release = registerDiagnosticWork(
+      `${diagnosticLaneName(this)} post ${diagnosticWorkName(work)}`
+    );
     const accepted = tryPost.call(this, () => {
       try {
-        const result = runDiagnosticTurn(this, work);
+        const result = runDiagnosticTurn(this, work, release.description);
         if (result instanceof Promise) return result.finally(release);
         release();
         return result;
@@ -182,8 +201,12 @@ if (isStructuralGuardEnabled()) {
   };
 }
 
-function runDiagnosticTurn<T>(lane: ZLinkStateLane, work: ZLinkStateLaneWork<T>): Promise<T> | T {
-  const turn: ZLinkStateLaneTurn = { lane, active: true };
+function runDiagnosticTurn<T>(
+  lane: ZLinkStateLane,
+  work: ZLinkStateLaneWork<T>,
+  description: string
+): Promise<T> | T {
+  const turn: ZLinkStateLaneTurn = { lane, description, active: true };
   return diagnosticTurnStorage!.run(turn, () => {
     try {
       const result = work();
@@ -213,7 +236,10 @@ export function guardStateLaneCompletion<T>(
         return (onFulfilled: (value: T) => unknown, onRejected: (error: unknown) => unknown) => {
           const current = ZLinkStateLane.current;
           if (current !== undefined && current !== owner) {
-            throw new Error(`A state lane turn cannot wait for ${label}.`);
+            throw new Error(
+              `A state lane turn cannot wait for ${label}. ` +
+                `current turn: ${diagnosticTurnStorage?.getStore()?.description ?? UNKNOWN_DIAGNOSTIC_CALLER}`
+            );
           }
           return target.then(onFulfilled, onRejected);
         };
@@ -246,16 +272,29 @@ export function diagnosticWorkName(work: { readonly name: string }): string {
   return work.name.length > 0 ? work.name : '<anonymous>';
 }
 
-function registerDiagnosticWork(name: string): () => void {
-  if (diagnosticPending === undefined) return () => undefined;
+function diagnosticLaneName(lane: ZLinkStateLane): string {
+  let id = diagnosticLaneIds!.get(lane);
+  if (id === undefined) {
+    id = ++nextDiagnosticLane;
+    diagnosticLaneIds!.set(lane, id);
+  }
+  return `state lane #${id}`;
+}
+
+function registerDiagnosticWork(name: string): (() => void) & { readonly description: string } {
+  if (diagnosticPending === undefined) return Object.assign(() => undefined, { description: name });
   const id = ++nextDiagnosticWork;
   const frames = new Error().stack?.split('\n').slice(2) ?? [];
   const caller =
     frames
       .find((frame) => !frame.includes('state-lane.') && !frame.includes('serial-execution-queue.'))
       ?.trim() ?? UNKNOWN_DIAGNOSTIC_CALLER;
-  diagnosticPending.set(id, `${name} ${caller}`);
-  return () => {
-    diagnosticPending.delete(id);
-  };
+  const description = `${name} ${caller}`;
+  diagnosticPending.set(id, description);
+  return Object.assign(
+    () => {
+      diagnosticPending.delete(id);
+    },
+    { description }
+  );
 }

package/src/runtime/locations/auto-connect-loop.ts

@@ -32,6 +32,8 @@ export class ZLinkAutoConnectLoop {
   private lastStamp?: bigint;
   private lastLiveOwnerSetVersion?: number;
   private lastTickFailed = false;
+  // This settled tail orders whole operations. The tick fields below are touched only inside it.
+  private inFlightTick: Promise<void> = Promise.resolve();
 
   constructor(options: ZLinkAutoConnectLoopOptions) {
     this.reconciler = options.reconciler;
@@ -59,7 +61,7 @@ export class ZLinkAutoConnectLoop {
     const controller = this.controller;
     if (meshName !== this.meshName || controller === undefined) return;
     // A fresh descriptor scan uses the same RID ordering and connection owner as a periodic tick.
-    await this.lane.run(async () => {
+    await this.enqueueTick(async () => {
       if (!controller.signal.aborted) await this.runReconcile(controller.signal);
     });
   }
@@ -79,6 +81,7 @@ export class ZLinkAutoConnectLoop {
       this.clearTimer(this.timer);
       this.timer = undefined;
     }
+    await this.inFlightTick;
     this.reconciler.disconnectPeers();
   }
 
@@ -87,7 +90,20 @@ export class ZLinkAutoConnectLoop {
   }
 
   async tick(signal?: AbortSignal): Promise<void> {
-    await this.lane.run(() => this.tickCore(signal));
+    const controller = this.controller;
+    await this.enqueueTick(async () => {
+      if (controller?.signal.aborted !== true) await this.tickCore(signal ?? controller?.signal);
+    });
+  }
+
+  private enqueueTick(operation: () => Promise<void>): Promise<void> {
+    const completion = this.inFlightTick.then(operation);
+    // The caller receives the failure; the successor still owns its place in the order.
+    this.inFlightTick = completion.then(
+      () => undefined,
+      () => undefined
+    );
+    return completion;
   }
 
   private async tickCore(signal?: AbortSignal): Promise<void> {

package/src/runtime/spots/index.ts

@@ -1521,12 +1521,6 @@ export class DefaultZLinkSpotManager {
   ): Promise<ZLinkSpotActorJoinResult> {
     const meshName = this.activations.resolveUnique(spotId)?.meshName;
     this.options.admission?.requireRequest('Actor join admission', meshName);
-    if (meshName !== undefined && this.isSpotClosing(meshName, spotId)) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestRejected,
-        `Spot '${String(spotId)}' is closing.`
-      );
-    }
     return await this.actorMembership.admitActorJoin(
       spotId,
       actor,

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

@@ -217,21 +217,27 @@ export class ZLinkSpotSerialTurnExecutor {
 
   /** Admits membership work and holds the lifecycle FIFO until its result settles. */
   executeLifecycleOperation<T>(operation: () => Promise<T> | T): Promise<T> {
-    let entry: ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> | undefined;
-    try {
+    const requireAdmission = (): void => {
       if (this.lifecycleAdmissionClosed) {
         throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestRejected,
-          'Spot lifecycle admission is closed by a committed Close.'
+          ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+          'Spot incarnation is closing (committed Close).'
         );
       }
+    };
+    let entry: ZLinkExecutionBarrierClaim | Promise<ZLinkExecutionBarrierClaim> | undefined;
+    try {
+      requireAdmission();
       entry = this.executionBarrier?.enter();
     } catch (error) {
       return Promise.reject(error);
     }
     const submit = (claim?: ZLinkExecutionBarrierClaim): Promise<T> => {
       try {
-        return this.scheduler.submitLifecycleOperation(operation);
+        return this.scheduler.submitLifecycleOperation(() => {
+          requireAdmission();
+          return operation();
+        });
       } catch (error) {
         return Promise.reject(error);
       } finally {