@pikku/core 0.12.15 → 0.12.16

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## 0.12.4
 
+## 0.12.16
+
+### Patch Changes
+
+- fbcf5b9: Add middleware priority system, telemetry middleware, and statusCode getter. Middleware now supports named priority levels (highest, high, medium, low, lowest) that control execution order regardless of registration order. Includes telemetryOuter and telemetryInner middleware for observability instrumentation via structured console.log output. PikkuHTTPResponse now exposes a readonly `statusCode` getter across all response implementations.
+
 ## 0.12.15
 
 ### Patch Changes

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module @pikku/core
  */
-export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
+export type { CommonWireMeta, CoreConfig, CorePikkuMiddleware, CorePikkuMiddlewareConfig, CorePikkuMiddlewareFactory, CorePikkuMiddlewareGroup, CoreServices, CoreSingletonServices, CoreUserSession, CreateConfig, FunctionMeta, FunctionRuntimeMeta, FunctionServicesMeta, FunctionWiresMeta, FunctionsMeta, FunctionsRuntimeMeta, JSONPrimitive, JSONValue, MakeRequired, MiddlewareMetadata, MiddlewarePriority, PermissionMetadata, PickOptional, PickRequired, PikkuAIMiddlewareHooks, PikkuWire, PikkuWiringTypes, RequireAtLeastOne, SerializedError, WireServices, } from './types/core.types.js';
 export { pikkuAIMiddleware, pikkuChannelMiddleware, pikkuChannelMiddlewareFactory, pikkuMiddleware, pikkuMiddlewareFactory, } from './types/core.types.js';
 export type { CorePikkuAuth, CorePikkuAuthConfig, CorePikkuFunction, CorePikkuFunctionConfig, CorePikkuPermission, CorePikkuPermissionConfig, CorePikkuPermissionFactory, CorePikkuApprovalDescription, CorePermissionGroup, ZodLike, } from './function/functions.types.js';
 export { pikkuAuth, pikkuPermission, pikkuPermissionFactory, pikkuApprovalDescription, } from './function/functions.types.js';

package/dist/middleware/index.d.ts

@@ -3,5 +3,6 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
+export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addMiddleware, runMiddleware } from '../middleware-runner.js';
 export { addPermission } from '../permissions.js';

package/dist/middleware/index.js

@@ -3,5 +3,6 @@ export { authCookie } from './auth-cookie.js';
 export { authBearer } from './auth-bearer.js';
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js';
 export { cors } from './cors.js';
+export { telemetryOuter, telemetryInner } from './telemetry.js';
 export { addMiddleware, runMiddleware } from '../middleware-runner.js';
 export { addPermission } from '../permissions.js';

package/dist/middleware/telemetry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Outer telemetry middleware that captures total request duration and outcome.
+ * Runs at `highest` priority (outermost in the middleware chain).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Total duration (including all middleware)
+ * - Outcome (ok/error)
+ * - Wire metadata (wireType, wireId, traceId)
+ * - HTTP details (method, path, status) if applicable
+ *
+ * @example
+ * ```typescript
+ * import { telemetryOuter } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryOuter()])
+ * ```
+ */
+export declare const telemetryOuter: import("../types/core.types.js").CorePikkuMiddlewareFactory<void | {
+    environmentId?: string;
+    orgId?: string;
+}, import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../services/logger.js").LogLevel;
+    secrets?: {};
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+}>, import("../types/core.types.js").CoreUserSession>;
+/**
+ * Inner telemetry middleware that captures function execution duration and user context.
+ * Runs at `lowest` priority (innermost, closest to the function).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Function-only duration (excluding outer middleware like auth)
+ * - User identity (pikkuUserId) if authenticated
+ * - Wire metadata (wireType, wireId, traceId)
+ *
+ * @example
+ * ```typescript
+ * import { telemetryInner } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryInner()])
+ * ```
+ */
+export declare const telemetryInner: import("../types/core.types.js").CorePikkuMiddlewareFactory<void | {
+    environmentId?: string;
+    orgId?: string;
+}, import("../types/core.types.js").CoreSingletonServices<{
+    logLevel?: import("../services/logger.js").LogLevel;
+    secrets?: {};
+    workflow?: import("../wirings/workflow/workflow.types.js").WorkflowServiceConfig;
+}>, import("../types/core.types.js").CoreUserSession>;

package/dist/middleware/telemetry.js

@@ -0,0 +1,106 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js';
+/**
+ * Outer telemetry middleware that captures total request duration and outcome.
+ * Runs at `highest` priority (outermost in the middleware chain).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Total duration (including all middleware)
+ * - Outcome (ok/error)
+ * - Wire metadata (wireType, wireId, traceId)
+ * - HTTP details (method, path, status) if applicable
+ *
+ * @example
+ * ```typescript
+ * import { telemetryOuter } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryOuter()])
+ * ```
+ */
+export const telemetryOuter = pikkuMiddlewareFactory(({ environmentId, orgId } = {}) => {
+    return pikkuMiddleware({
+        name: 'telemetry-outer',
+        priority: 'highest',
+        func: async (services, wire, next) => {
+            const start = performance.now();
+            let outcome = 'ok';
+            let errorMessage;
+            try {
+                await next();
+            }
+            catch (e) {
+                outcome = 'error';
+                errorMessage = e instanceof Error ? e.message : String(e);
+                throw e;
+            }
+            finally {
+                services.logger.info({
+                    __pikku_telemetry: 'end',
+                    __pikku_layer: 'outer',
+                    traceId: wire.traceId,
+                    wireType: wire.wireType,
+                    wireId: wire.wireId,
+                    totalDuration: Math.round(performance.now() - start),
+                    outcome,
+                    ...(errorMessage ? { errorMessage } : {}),
+                    ...(wire.http
+                        ? {
+                            httpStatus: wire.http.response?.statusCode,
+                            httpMethod: wire.http.request?.method(),
+                            httpPath: wire.http.request?.path(),
+                        }
+                        : {}),
+                    ...(environmentId ? { environmentId } : {}),
+                    ...(orgId ? { orgId } : {}),
+                });
+            }
+        },
+    });
+});
+/**
+ * Inner telemetry middleware that captures function execution duration and user context.
+ * Runs at `lowest` priority (innermost, closest to the function).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Function-only duration (excluding outer middleware like auth)
+ * - User identity (pikkuUserId) if authenticated
+ * - Wire metadata (wireType, wireId, traceId)
+ *
+ * @example
+ * ```typescript
+ * import { telemetryInner } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryInner()])
+ * ```
+ */
+export const telemetryInner = pikkuMiddlewareFactory(({ environmentId, orgId } = {}) => {
+    return pikkuMiddleware({
+        name: 'telemetry-inner',
+        priority: 'lowest',
+        func: async (services, wire, next) => {
+            const start = performance.now();
+            let outcome = 'ok';
+            let errorMessage;
+            try {
+                await next();
+            }
+            catch (e) {
+                outcome = 'error';
+                errorMessage = e instanceof Error ? e.message : String(e);
+                throw e;
+            }
+            finally {
+                services.logger.info({
+                    __pikku_telemetry: 'end',
+                    __pikku_layer: 'inner',
+                    traceId: wire.traceId,
+                    wireType: wire.wireType,
+                    wireId: wire.wireId,
+                    functionDuration: Math.round(performance.now() - start),
+                    outcome,
+                    pikkuUserId: wire.pikkuUserId,
+                    ...(errorMessage ? { errorMessage } : {}),
+                    ...(environmentId ? { environmentId } : {}),
+                    ...(orgId ? { orgId } : {}),
+                });
+            }
+        },
+    });
+});

package/dist/middleware-runner.js

@@ -1,5 +1,19 @@
 import { pikkuState } from './pikku-state.js';
 import { freezeDedupe, getTagGroups } from './utils.js';
+const PRIORITY_ORDER = {
+    highest: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    lowest: 4,
+};
+const getMiddlewarePriority = (fn) => {
+    const priority = fn.__priority;
+    return PRIORITY_ORDER[priority ?? 'medium'];
+};
+const sortByPriority = (middlewares) => {
+    return middlewares.sort((a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b));
+};
 /**
  * Runs a chain of middleware functions in sequence before executing the main function.
  *
@@ -18,11 +32,14 @@ import { freezeDedupe, getTagGroups } from './utils.js';
  * );
  */
 export const runMiddleware = async (services, wire, middlewares, main) => {
-    // Deduplicate middleware using Set to avoid running the same middleware multiple times
+    // Sort by priority if not already sorted (cached middleware is pre-sorted)
+    const sorted = isSortedByPriority(middlewares)
+        ? middlewares
+        : [...middlewares].sort((a, b) => getMiddlewarePriority(a) - getMiddlewarePriority(b));
     let result;
     const dispatch = async (index) => {
-        if (middlewares && index < middlewares.length) {
-            return await middlewares[index](services, wire, () => dispatch(index + 1));
+        if (sorted && index < sorted.length) {
+            return await sorted[index](services, wire, () => dispatch(index + 1));
         }
         else if (main) {
             result = await main();
@@ -31,6 +48,15 @@ export const runMiddleware = async (services, wire, middlewares, main) => {
     await dispatch(0);
     return result;
 };
+const isSortedByPriority = (middlewares) => {
+    for (let i = 1; i < middlewares.length; i++) {
+        if (getMiddlewarePriority(middlewares[i]) <
+            getMiddlewarePriority(middlewares[i - 1])) {
+            return false;
+        }
+    }
+    return true;
+};
 /**
  * Registers global middleware for a specific tag.
  *
@@ -176,7 +202,8 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
     if (funcMiddleware) {
         resolved.push(...funcMiddleware);
     }
-    // Deduplicate and freeze
+    // Sort by priority, deduplicate, and freeze
+    sortByPriority(resolved);
     middlewareCache[wireType][uid] = freezeDedupe(resolved);
     return middlewareCache[wireType][uid];
 };

package/dist/types/core.types.d.ts

@@ -224,6 +224,17 @@ export type PikkuWire<In = unknown, Out = unknown, HasInitialSession extends boo
  * A function that can wrap an wire and be called before or after
  */
 export type CorePikkuMiddleware<SingletonServices extends CoreSingletonServices = CoreSingletonServices, UserSession extends CoreUserSession = CoreUserSession> = (services: SingletonServices, wires: PikkuWire<unknown, unknown, false, UserSession>, next: () => Promise<void>) => Promise<void>;
+/**
+ * Priority levels for middleware execution order.
+ * Lower priority runs first (outermost in the onion model).
+ *
+ * - `highest` — Runs first (outermost). Use for telemetry, request tracing.
+ * - `high` — Runs early. Use for CORS, rate limiting.
+ * - `medium` — Default. Use for auth, most user middleware.
+ * - `low` — Runs late. Use for post-auth processing.
+ * - `lowest` — Runs last (innermost, closest to function). Use for inner telemetry.
+ */
+export type MiddlewarePriority = 'highest' | 'high' | 'medium' | 'low' | 'lowest';
 /**
  * Configuration object for creating middleware with metadata
  *
@@ -237,6 +248,8 @@ export type CorePikkuMiddlewareConfig<SingletonServices extends CoreSingletonSer
     name?: string;
     /** Optional description of what the middleware does */
     description?: string;
+    /** Execution priority. Lower runs first (outermost). Defaults to 'medium'. */
+    priority?: MiddlewarePriority;
 };
 /**
  * A factory function that takes input and returns middleware

package/dist/types/core.types.js

@@ -24,7 +24,13 @@
  * ```
  */
 export const pikkuMiddleware = (middleware) => {
-    return typeof middleware === 'function' ? middleware : middleware.func;
+    if (typeof middleware === 'function')
+        return middleware;
+    const func = middleware.func;
+    if (middleware.priority) {
+        func.__priority = middleware.priority;
+    }
+    return func;
 };
 /**
  * Factory function for creating middleware factories

package/dist/wirings/cli/cli-runner.js

@@ -323,8 +323,9 @@ export async function executeCLI({ programName, args, createConfig, createSingle
         const config = createConfig
             ? await createConfig(new LocalVariablesService(), data)
             : {};
-        // Create services with config
+        // Create services with config and register in global state
         const singletonServices = await createSingletonServices(config);
+        pikkuState(null, 'package', 'singletonServices', singletonServices);
         // Execute the command
         await runCLICommand({
             program: programName,

package/dist/wirings/http/http.types.d.ts

@@ -167,6 +167,7 @@ export interface PikkuHTTPRequest<In = unknown> {
     query(): PikkuQuery;
 }
 export interface PikkuHTTPResponse<Out = unknown> {
+    readonly statusCode: number;
     status(code: number): this;
     cookie(name: string, value: string | null, options: SerializeOptions): this;
     header(name: string, value: string | string[]): this;

package/dist/wirings/http/pikku-fetch-http-response.d.ts

@@ -3,6 +3,7 @@ import type { SerializeOptions as CookieSerializeOptions } from 'cookie';
 export declare class PikkuFetchHTTPResponse implements PikkuHTTPResponse {
     #private;
     setMode(mode: 'stream'): void;
+    get statusCode(): number;
     status(code: number): this;
     cookie(name: string, value: string, flags: CookieSerializeOptions): this;
     header(name: string, value: string | string[]): this;

package/dist/wirings/http/pikku-fetch-http-response.js

@@ -13,6 +13,9 @@ export class PikkuFetchHTTPResponse {
             this.#body = this.createStream();
         }
     }
+    get statusCode() {
+        return this.#statusCode;
+    }
     status(code) {
         this.#statusCode = code;
         return this;

package/dist/wirings/mcp/mcp.types.d.ts

@@ -80,7 +80,7 @@ export type CoreMCPResource<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePi
 export type CoreMCPTool<PikkuFunctionConfig = CorePikkuFunctionConfig<CorePikkuFunctionSessionless<any, any>>, PikkuPermission = CorePikkuPermission<any, any>, PikkuMiddleware = CorePikkuMiddleware<any>> = {
     name: string;
     title?: string;
-    description: string;
+    description?: string;
     summary?: string;
     errors?: string[];
     func: PikkuFunctionConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.15",
+  "version": "0.12.16",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/index.ts

@@ -22,6 +22,7 @@ export type {
   JSONValue,
   MakeRequired,
   MiddlewareMetadata,
+  MiddlewarePriority,
   PermissionMetadata,
   PickOptional,
   PickRequired,

package/src/middleware/index.ts

@@ -3,5 +3,6 @@ export { authCookie } from './auth-cookie.js'
 export { authBearer } from './auth-bearer.js'
 export { pikkuRemoteAuthMiddleware } from './remote-auth.js'
 export { cors } from './cors.js'
+export { telemetryOuter, telemetryInner } from './telemetry.js'
 export { addMiddleware, runMiddleware } from '../middleware-runner.js'
 export { addPermission } from '../permissions.js'

package/src/middleware/telemetry.ts

@@ -0,0 +1,110 @@
+import { pikkuMiddleware, pikkuMiddlewareFactory } from '../types/core.types.js'
+
+/**
+ * Outer telemetry middleware that captures total request duration and outcome.
+ * Runs at `highest` priority (outermost in the middleware chain).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Total duration (including all middleware)
+ * - Outcome (ok/error)
+ * - Wire metadata (wireType, wireId, traceId)
+ * - HTTP details (method, path, status) if applicable
+ *
+ * @example
+ * ```typescript
+ * import { telemetryOuter } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryOuter()])
+ * ```
+ */
+export const telemetryOuter = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-outer',
+    priority: 'highest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'outer',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          totalDuration: Math.round(performance.now() - start),
+          outcome,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(wire.http
+            ? {
+                httpStatus: wire.http.response?.statusCode,
+                httpMethod: wire.http.request?.method(),
+                httpPath: wire.http.request?.path(),
+              }
+            : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})
+
+/**
+ * Inner telemetry middleware that captures function execution duration and user context.
+ * Runs at `lowest` priority (innermost, closest to the function).
+ *
+ * Emits a structured JSON log entry with `__pikku_telemetry: 'end'` containing:
+ * - Function-only duration (excluding outer middleware like auth)
+ * - User identity (pikkuUserId) if authenticated
+ * - Wire metadata (wireType, wireId, traceId)
+ *
+ * @example
+ * ```typescript
+ * import { telemetryInner } from '@pikku/core/middleware'
+ * addMiddleware('myTag', [telemetryInner()])
+ * ```
+ */
+export const telemetryInner = pikkuMiddlewareFactory<{
+  environmentId?: string
+  orgId?: string
+} | void>(({ environmentId, orgId } = {}) => {
+  return pikkuMiddleware({
+    name: 'telemetry-inner',
+    priority: 'lowest',
+    func: async (services, wire, next) => {
+      const start = performance.now()
+      let outcome = 'ok'
+      let errorMessage: string | undefined
+      try {
+        await next()
+      } catch (e) {
+        outcome = 'error'
+        errorMessage = e instanceof Error ? e.message : String(e)
+        throw e
+      } finally {
+        services.logger.info({
+          __pikku_telemetry: 'end',
+          __pikku_layer: 'inner',
+          traceId: wire.traceId,
+          wireType: wire.wireType,
+          wireId: wire.wireId,
+          functionDuration: Math.round(performance.now() - start),
+          outcome,
+          pikkuUserId: wire.pikkuUserId,
+          ...(errorMessage ? { errorMessage } : {}),
+          ...(environmentId ? { environmentId } : {}),
+          ...(orgId ? { orgId } : {}),
+        })
+      }
+    },
+  })
+})

package/src/middleware-runner.test.ts

@@ -6,7 +6,27 @@ import {
   runMiddleware,
 } from './middleware-runner.js'
 import { resetPikkuState } from './pikku-state.js'
-import type { CorePikkuMiddleware } from './types/core.types.js'
+import type {
+  CorePikkuMiddleware,
+  MiddlewarePriority,
+} from './types/core.types.js'
+import { pikkuMiddleware } from './types/core.types.js'
+
+const withPriority = (
+  name: string,
+  priority: MiddlewarePriority,
+  log: string[]
+): CorePikkuMiddleware => {
+  return pikkuMiddleware({
+    name,
+    priority,
+    func: async (_services, _wire, next) => {
+      log.push(`start:${name}`)
+      await next()
+      log.push(`end:${name}`)
+    },
+  })
+}
 
 beforeEach(() => {
   resetPikkuState()
@@ -329,6 +349,56 @@ describe('combineMiddleware', () => {
     assert.equal(result.length, 1)
     assert.equal(result[0], middleware)
   })
+
+  test('should sort middleware by priority', () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [low, highest, medium],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], medium)
+    assert.equal(result[2], low)
+  })
+
+  test('should default unprioritized middleware to medium', () => {
+    const log: string[] = []
+    const highest = withPriority('highest', 'highest', log)
+    const lowest = withPriority('lowest', 'lowest', log)
+    const noPriority: CorePikkuMiddleware = async (_services, _wire, next) => {
+      await next()
+    }
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [lowest, noPriority, highest],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], highest)
+    assert.equal(result[1], noPriority) // defaults to medium
+    assert.equal(result[2], lowest)
+  })
+
+  test('should preserve registration order within same priority', () => {
+    const log: string[] = []
+    const first = withPriority('first', 'medium', log)
+    const second = withPriority('second', 'medium', log)
+    const third = withPriority('third', 'medium', log)
+
+    const result = combineMiddleware('http', Math.random().toString(), {
+      wireMiddleware: [first, second, third],
+    })
+
+    assert.equal(result.length, 3)
+    assert.equal(result[0], first)
+    assert.equal(result[1], second)
+    assert.equal(result[2], third)
+  })
 })
 
 describe('runMiddleware', () => {
@@ -415,4 +485,82 @@ describe('runMiddleware', () => {
 
     assert.deepEqual(executionOrder, ['middleware'])
   })
+
+  test('should execute middleware in priority order (highest first, lowest last)', async () => {
+    const log: string[] = []
+    const low = withPriority('low', 'low', log)
+    const highest = withPriority('highest', 'highest', log)
+    const medium = withPriority('medium', 'medium', log)
+
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [low, highest, medium],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:medium',
+      'start:low',
+      'main',
+      'end:low',
+      'end:medium',
+      'end:highest',
+    ])
+  })
+
+  test('should sort unsorted middleware passed directly to runMiddleware', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    await runMiddleware({} as any, {} as any, [lowest, highest], async () => {
+      log.push('main')
+    })
+
+    // highest should run first (outermost), lowest last (innermost)
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:highest',
+    ])
+  })
+
+  test('should handle all five priority levels in correct order', async () => {
+    const log: string[] = []
+    const lowest = withPriority('lowest', 'lowest', log)
+    const low = withPriority('low', 'low', log)
+    const medium = withPriority('medium', 'medium', log)
+    const high = withPriority('high', 'high', log)
+    const highest = withPriority('highest', 'highest', log)
+
+    // Pass in reverse order to verify sorting
+    await runMiddleware(
+      {} as any,
+      {} as any,
+      [lowest, low, medium, high, highest],
+      async () => {
+        log.push('main')
+      }
+    )
+
+    assert.deepEqual(log, [
+      'start:highest',
+      'start:high',
+      'start:medium',
+      'start:low',
+      'start:lowest',
+      'main',
+      'end:lowest',
+      'end:low',
+      'end:medium',
+      'end:high',
+      'end:highest',
+    ])
+  })
 })