feat: Introduce middleware priority system with a default of 100 and range validation, updating related classes and tests.

Author: tercel

CHANGELOG.md

@@ -5,10 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.13.2] - 2026-03-24
+## [0.14.0] - 2026-03-24
+
+### Breaking Changes
+- Middleware default priority changed from `0` to `100` per PROTOCOL_SPEC §11.2. Middleware without explicit priority will now execute before priority-0 middleware.
 
 ### Added
 - **Middleware priority** — `Middleware` base class now accepts `priority: number` (default 0). Higher priority executes first; equal priority preserves registration order. `BeforeMiddleware` and `AfterMiddleware` adapters also accept `priority`.
+- **Priority range validation** — `RangeError` thrown for values outside 0-1000
 
 ## [0.13.1] - 2026-03-22
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "AI-Perceivable Core — schema-driven module standard",
   "type": "module",
   "main": "./dist/index.js",

src/index.ts

@@ -160,4 +160,4 @@ export type { UsageRecord, CallerUsageSummary, HourlyBucket, ModuleUsageSummary,
 export { TraceContext } from './trace-context.js';
 export type { TraceParent } from './trace-context.js';
 
-export const VERSION = '0.13.2';
+export const VERSION = '0.14.0';

src/middleware/adapters.ts

@@ -21,7 +21,7 @@ export type AfterCallback = (
 export class BeforeMiddleware extends Middleware {
   private _callback: BeforeCallback;
 
-  constructor(callback: BeforeCallback, priority: number = 0) {
+  constructor(callback: BeforeCallback, priority: number = 100) {
     super(priority);
     this._callback = callback;
   }
@@ -38,7 +38,7 @@ export class BeforeMiddleware extends Middleware {
 export class AfterMiddleware extends Middleware {
   private _callback: AfterCallback;
 
-  constructor(callback: AfterCallback, priority: number = 0) {
+  constructor(callback: AfterCallback, priority: number = 100) {
     super(priority);
     this._callback = callback;
   }

src/middleware/base.ts

@@ -11,7 +11,12 @@ export class Middleware {
    */
   readonly priority: number;
 
-  constructor(priority: number = 0) {
+  constructor(priority: number = 100) {
+    if (priority < 0 || priority > 1000) {
+      throw new RangeError(
+        `priority must be between 0 and 1000, got ${priority}`,
+      );
+    }
     this.priority = priority;
   }
 

src/middleware/logging.ts

@@ -31,7 +31,7 @@ export class LoggingMiddleware extends Middleware {
     logOutputs?: boolean;
     logErrors?: boolean;
   }) {
-    super();
+    super(700);
     this._logger = options?.logger ?? defaultLogger;
     this._logInputs = options?.logInputs ?? true;
     this._logOutputs = options?.logOutputs ?? true;

tests/test-logging-middleware.test.ts

@@ -128,6 +128,13 @@ describe('LoggingMiddleware', () => {
     });
   });
 
+  describe('priority', () => {
+    it('has priority 700 (logging range)', () => {
+      const mw = new LoggingMiddleware();
+      expect(mw.priority).toBe(700);
+    });
+  });
+
   describe('defaults', () => {
     it('uses default logger when none provided', () => {
       const mw = new LoggingMiddleware();

tests/test-middleware-manager.test.ts

@@ -10,7 +10,7 @@ function makeContext(): Context {
 class TaggingMiddleware extends Middleware {
   readonly tag: string;
 
-  constructor(tag: string, priority: number = 0) {
+  constructor(tag: string, priority: number = 100) {
     super(priority);
     this.tag = tag;
   }
@@ -205,10 +205,10 @@ describe('MiddlewareManager', () => {
       expect(result['trail']).toBe('FirstSecondThird');
     });
 
-    it('default priority (0) middleware is ordered after explicit priority', () => {
+    it('lower priority middleware is ordered after higher priority', () => {
       const mgr = new MiddlewareManager();
-      mgr.add(new TaggingMiddleware('Default'));
-      mgr.add(new TaggingMiddleware('Prioritized', 1));
+      mgr.add(new TaggingMiddleware('Default', 100));
+      mgr.add(new TaggingMiddleware('Prioritized', 101));
       const ctx = makeContext();
       const [result] = mgr.executeBefore('mod.test', { trail: '' }, ctx);
       expect(result['trail']).toBe('PrioritizedDefault');
@@ -225,9 +225,19 @@ describe('MiddlewareManager', () => {
       expect(result['trail']).toBe('LowMidHigh');
     });
 
-    it('Middleware base class defaults to priority 0', () => {
+    it('Middleware base class defaults to priority 100', () => {
       const mw = new Middleware();
-      expect(mw.priority).toBe(0);
+      expect(mw.priority).toBe(100);
+    });
+
+    it('throws RangeError for priority below 0', () => {
+      expect(() => new Middleware(-1)).toThrow(RangeError);
+      expect(() => new Middleware(-1)).toThrow('priority must be between 0 and 1000');
+    });
+
+    it('throws RangeError for priority above 1000', () => {
+      expect(() => new Middleware(1001)).toThrow(RangeError);
+      expect(() => new Middleware(1001)).toThrow('priority must be between 0 and 1000');
     });
 
     it('snapshot reflects priority-sorted order', () => {