@nextrush/core 3.0.6 → 4.0.0-beta.0

package/dist/index.js

@@ -1,7 +1,14 @@
-export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError, createError as createHttpError } from '@nextrush/errors';
+import { getErrorStatus, NextRushError, getHttpStatusMessage } from '@nextrush/errors';
+export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError } from '@nextrush/errors';
 export { ContentType, HttpStatus } from '@nextrush/types';
 
 // src/middleware.ts
+var MULTIPLE_NEXT_MESSAGE = "next() called multiple times";
+function emitDoubleResponseWarning(index) {
+  console.warn(
+    `[nextrush] Middleware at index ${String(index)} called next() after the response was already committed. Downstream middleware may attempt to write to an already-finished response. Either await next() to delegate downstream, or send a response without calling next().`
+  );
+}
 function compose(middleware, options) {
   if (!Array.isArray(middleware)) {
     throw new TypeError("Middleware stack must be an array");
@@ -11,7 +18,7 @@ function compose(middleware, options) {
       throw new TypeError("Middleware must be a function");
     }
   }
-  const warnDoubleResponse = options?.warnDoubleResponse ?? process.env.NODE_ENV !== "production";
+  const warnDoubleResponse = options?.warnDoubleResponse ?? false;
   const stack = [...middleware];
   const len = stack.length;
   if (len === 0) {
@@ -19,11 +26,37 @@ function compose(middleware, options) {
       return next ? next() : Promise.resolve();
     };
   }
+  if (len === 1) {
+    const only = stack[0];
+    if (only) {
+      return function composedSingle(ctx, next) {
+        let called = false;
+        const nextFn = () => {
+          if (called) {
+            return Promise.reject(new Error(MULTIPLE_NEXT_MESSAGE));
+          }
+          called = true;
+          if (warnDoubleResponse && ctx.responded) {
+            emitDoubleResponseWarning(0);
+          }
+          return next ? next() : Promise.resolve();
+        };
+        if (ctx.setNext) {
+          ctx.setNext(nextFn);
+        }
+        try {
+          return Promise.resolve(only(ctx, nextFn));
+        } catch (err) {
+          return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      };
+    }
+  }
   return function composedMiddleware(ctx, next) {
     let index = -1;
     function dispatch(i) {
       if (i <= index) {
-        return Promise.reject(new Error("next() called multiple times"));
+        return Promise.reject(new Error(MULTIPLE_NEXT_MESSAGE));
       }
       index = i;
       let fn;
@@ -35,27 +68,17 @@ function compose(middleware, options) {
       if (!fn) {
         return Promise.resolve();
       }
-      const respondedBefore = warnDoubleResponse ? ctx.responded : false;
-      let nextCalled = false;
       const nextFn = () => {
-        nextCalled = true;
+        if (warnDoubleResponse && ctx.responded) {
+          emitDoubleResponseWarning(i);
+        }
         return dispatch(i + 1);
       };
       if (ctx.setNext) {
         ctx.setNext(nextFn);
       }
       try {
-        const result = Promise.resolve(fn(ctx, nextFn));
-        if (warnDoubleResponse) {
-          return result.then(() => {
-            if (!respondedBefore && ctx.responded && nextCalled) {
-              console.warn(
-                `[nextrush] Middleware at index ${String(i)} sent a response and called next(). Downstream middleware may attempt to write to an already-finished response. Either send a response OR call next(), not both.`
-              );
-            }
-          });
-        }
-        return result;
+        return Promise.resolve(fn(ctx, nextFn));
       } catch (err) {
         return Promise.reject(err instanceof Error ? err : new Error(String(err)));
       }
@@ -75,10 +98,81 @@ function flattenMiddleware(arr) {
   }
   return flattened;
 }
+function writeDefaultErrorResponse(error, ctx, opts) {
+  const status = getErrorStatus(error);
+  if (status >= 500 || !opts.isProduction) {
+    opts.logger.error("Request error:", error);
+  }
+  ctx.status = status;
+  if (error instanceof NextRushError) {
+    ctx.json(error.toJSON());
+    return;
+  }
+  const expose = status < 500;
+  ctx.json({
+    error: expose ? error.name : getHttpStatusMessage(status),
+    message: expose ? error.message : "Internal Server Error",
+    code: "INTERNAL_ERROR",
+    status
+  });
+}
 
-// src/application.ts
+// src/route-mount.ts
 var ORIGINAL_PATH = /* @__PURE__ */ Symbol.for("nextrush.originalPath");
 var ROUTE_PREFIX = /* @__PURE__ */ Symbol.for("nextrush.routePrefix");
+function createPrefixMount(normalizedPrefix, routerMiddleware) {
+  const prefixLen = normalizedPrefix.length;
+  return async (ctx, next) => {
+    const currentPath = ctx.path;
+    if (!currentPath.startsWith(normalizedPrefix)) {
+      return next();
+    }
+    const hasCharAfterPrefix = prefixLen < currentPath.length;
+    if (hasCharAfterPrefix && currentPath.charCodeAt(prefixLen) !== 47) {
+      return next();
+    }
+    const adjustedPath = currentPath.slice(prefixLen) || "/";
+    ctx.path = adjustedPath;
+    ctx.state[ORIGINAL_PATH] = currentPath;
+    ctx.state[ROUTE_PREFIX] = normalizedPrefix;
+    try {
+      await routerMiddleware(ctx, async () => {
+        ctx.path = currentPath;
+        await next();
+        ctx.path = adjustedPath;
+      });
+    } finally {
+      ctx.path = currentPath;
+      ctx.state[ORIGINAL_PATH] = void 0;
+      ctx.state[ROUTE_PREFIX] = void 0;
+    }
+  };
+}
+
+// src/application.ts
+var TeardownTimeoutError = class extends Error {
+  constructor(unitName, timeoutMs) {
+    super(`Teardown unit "${unitName}" did not complete within ${String(timeoutMs)}ms`);
+    this.name = "TeardownTimeoutError";
+  }
+};
+async function runTeardownUnit(unit, timeoutMs) {
+  const settle = Promise.resolve().then(() => unit.run()).then(() => null).catch((err) => err instanceof Error ? err : new Error(String(err)));
+  if (timeoutMs === void 0) {
+    return settle;
+  }
+  let timer;
+  const timedOut = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      resolve(new TeardownTimeoutError(unit.name, timeoutMs));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([settle, timedOut]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 var NOOP_LOGGER = {
   error(..._args) {
   },
@@ -90,62 +184,92 @@ var NOOP_LOGGER = {
   }
 };
 var Application = class {
-  /**
-   * Middleware stack
-   */
+  /** Middleware stack */
   middlewareStack = [];
+  /** Registered extensions, in registration order (setup runs at ready()) */
+  extensions = [];
+  /** Registered extension names — enforces uniqueness */
+  extensionNames = /* @__PURE__ */ new Set();
   /**
-   * Installed plugins
-   */
-  plugins = /* @__PURE__ */ new Map();
-  /**
-   * Custom error handler
+   * Combined teardown-unit registration order: extension `destroy()`s and
+   * {@link onClose} hooks interleaved in the exact order they were registered,
+   * so `_shutdown()` can run the whole set in one reverse-of-registration pass
+   * (RFC-022 §7.3 — "teardown becomes a flat list of independently-isolated,
+   * budget-raced units"). Populated lazily by {@link extend} (for extensions
+   * declaring `destroy()`) and {@link onClose}.
    */
+  teardownUnits = [];
+  /** Whether {@link close} has started — {@link onClose} is a pre-shutdown-only registration point (RFC-022 §8.6). */
+  _closeStarted = false;
+  /** Names decorated onto the app — enforces collision detection */
+  decorations = /* @__PURE__ */ new Set();
+  /** Custom error handler */
   _errorHandler = null;
-  /**
-   * Pluggable logger
-   */
+  /** Pluggable logger */
   logger;
-  /**
-   * Application options
-   */
+  /** Application options */
   options;
-  /**
-   * Whether the app is running
-   */
+  /** Whether the app is running (server listening) */
   _isRunning = false;
+  /** Whether the app has been booted (extensions set up, config frozen) */
+  _isReady = false;
+  /** Whether ready() mounted the app-owned router (so close() can undo it) */
+  _routerMounted = false;
+  /** In-flight boot promise — memoized so concurrent ready() calls share one boot (H-1) */
+  _readyPromise = null;
+  /** In-flight shutdown promise — memoized so concurrent close() calls share one (H-3) */
+  _closePromise = null;
+  /** The app-owned router (optional). Route methods delegate to it. */
+  router;
+  /** The app-owned DI container (optional). Exposed to extensions and registrars. */
+  container;
   constructor(options = {}) {
     this.options = {
       env: options.env ?? "development",
       proxy: options.proxy ?? false
     };
     this.logger = options.logger ?? NOOP_LOGGER;
+    this.router = options.router;
+    this.container = options.container;
   }
-  /**
-   * Check if running in production
-   */
+  /** Check if running in production */
   get isProduction() {
     return this.options.env === "production";
   }
-  /**
-   * Check if app is running
-   */
+  /** Check if app is running */
   get isRunning() {
     return this._isRunning;
   }
   /**
-   * Get middleware count
+   * Whether a graceful shutdown is currently in progress — `true` from the
+   * moment {@link close} begins tearing down until it completes (F-12:
+   * shutdown observability, RFC-022). A readiness check or operator tooling
+   * can read this to reflect an in-progress drain.
    */
+  get isDraining() {
+    return this._closeStarted;
+  }
+  /** Check if app has been booted via ready() */
+  get isReady() {
+    return this._isReady;
+  }
+  /** Get middleware count */
   get middlewareCount() {
     return this.middlewareStack.length;
   }
+  /** Get registered extension count */
+  get extensionCount() {
+    return this.extensions.length;
+  }
   /**
-   * Throws if the app is already running.
-   * Prevents configuration mutations after start().
+   * Throws if the app configuration is frozen (after ready() or start()).
+   * Prevents unsafe mutations once the app has booted or is serving traffic.
    */
-  assertNotRunning(method) {
-    if (this._isRunning) {
-      throw new Error(`Cannot call ${method}() after the application has started`);
+  assertConfigurable(method) {
+    if (this._isReady || this._isRunning) {
+      throw new Error(
+        `Cannot call ${method}() after the app has booted (ready()) or started \u2014 configuration is frozen`
+      );
     }
   }
   // ===========================================================================
@@ -154,23 +278,11 @@ var Application = class {
   /**
    * Register middleware function(s)
    *
-   * @param middleware - Middleware function or array of middleware
+   * @param middleware - Middleware function(s)
    * @returns this for chaining
-   *
-   * @example
-   * ```typescript
-   * // Single middleware
-   * app.use(async (ctx) => {
-   *   console.log(ctx.method, ctx.path);
-   *   await ctx.next();
-   * });
-   *
-   * // Multiple middleware
-   * app.use(cors(), helmet(), json());
-   * ```
    */
   use(...middleware) {
-    this.assertNotRunning("use");
+    this.assertConfigurable("use");
     for (const mw of middleware) {
       if (typeof mw !== "function") {
         throw new TypeError("Middleware must be a function");
@@ -183,37 +295,14 @@ var Application = class {
   // Router Mounting (Hono-style)
   // ===========================================================================
   /**
-   * Mount a router at a path prefix
+   * Mount a router at a path prefix.
    *
-   * This is the Hono-style API for mounting routers directly on the app.
-   * The router's routes will only match requests that start with the given prefix.
-   *
-   * @param path - Path prefix for the router (e.g., '/api/users')
+   * @param path - Path prefix (e.g. '/api/users')
    * @param router - Router instance to mount
    * @returns this for chaining
-   *
-   * @example
-   * ```typescript
-   * // Create modular routers
-   * const users = createRouter();
-   * users.get('/', listUsers);
-   * users.get('/:id', getUser);
-   * users.post('/', createUser);
-   *
-   * const posts = createRouter();
-   * posts.get('/', listPosts);
-   * posts.get('/:id', getPost);
-   *
-   * // Mount directly on app - clean like Hono!
-   * const app = createApp();
-   * app.route('/api/users', users);
-   * app.route('/api/posts', posts);
-   *
-   * listen(app, 3000);
-   * ```
    */
   route(path, router) {
-    this.assertNotRunning("route");
+    this.assertConfigurable("route");
     if (path === "/" || path === "") {
       this.middlewareStack.push(router.routes());
       return this;
@@ -223,226 +312,251 @@ var Application = class {
     if (!normalizedPrefix.startsWith("/")) {
       normalizedPrefix = "/" + normalizedPrefix;
     }
-    const prefixLen = normalizedPrefix.length;
-    const mountedMiddleware = async (ctx, next) => {
-      const currentPath = ctx.path;
-      if (!currentPath.startsWith(normalizedPrefix)) {
-        return next();
-      }
-      const hasCharAfterPrefix = prefixLen < currentPath.length;
-      if (hasCharAfterPrefix && currentPath.charCodeAt(prefixLen) !== 47) {
-        return next();
-      }
-      const adjustedPath = currentPath.slice(prefixLen) || "/";
-      ctx.path = adjustedPath;
-      ctx.state[ORIGINAL_PATH] = currentPath;
-      ctx.state[ROUTE_PREFIX] = normalizedPrefix;
-      try {
-        await routerMiddleware(ctx, async () => {
-          ctx.path = currentPath;
-          await next();
-          ctx.path = adjustedPath;
-        });
-      } finally {
-        ctx.path = currentPath;
-        ctx.state[ORIGINAL_PATH] = void 0;
-        ctx.state[ROUTE_PREFIX] = void 0;
-      }
-    };
-    this.middlewareStack.push(mountedMiddleware);
+    this.middlewareStack.push(createPrefixMount(normalizedPrefix, routerMiddleware));
     return this;
   }
   // ===========================================================================
-  // Error Handling
+  // Routing (delegates to the app-owned router)
   // ===========================================================================
+  requireRouter() {
+    if (!this.router) {
+      throw new Error(
+        "No router configured. Create your app with `createApp()` from `nextrush` (batteries-included), or pass one: `createApp({ router: createRouter() })`."
+      );
+    }
+    return this.router;
+  }
+  /** Register a GET route on the app-owned router. */
+  get(path, ...entries) {
+    this.assertConfigurable("get");
+    this.requireRouter().get(path, ...entries);
+    return this;
+  }
+  /** Register a POST route on the app-owned router. */
+  post(path, ...entries) {
+    this.assertConfigurable("post");
+    this.requireRouter().post(path, ...entries);
+    return this;
+  }
+  /** Register a PUT route on the app-owned router. */
+  put(path, ...entries) {
+    this.assertConfigurable("put");
+    this.requireRouter().put(path, ...entries);
+    return this;
+  }
+  /** Register a PATCH route on the app-owned router. */
+  patch(path, ...entries) {
+    this.assertConfigurable("patch");
+    this.requireRouter().patch(path, ...entries);
+    return this;
+  }
+  /** Register a DELETE route on the app-owned router. */
+  delete(path, ...entries) {
+    this.assertConfigurable("delete");
+    this.requireRouter().delete(path, ...entries);
+    return this;
+  }
+  /** Register a HEAD route on the app-owned router. */
+  head(path, ...entries) {
+    this.assertConfigurable("head");
+    this.requireRouter().head(path, ...entries);
+    return this;
+  }
   /**
-   * Set the application error handler.
+   * Register a route for all HTTP methods on the app-owned router.
    *
-   * Replaces any previously set handler. Only one error handler is active
-   * at a time. For additive error handling, compose logic within a single
-   * handler or use the `errorHandler()` middleware from `@nextrush/errors`.
-   *
-   * @param handler - Error handler function
-   * @returns this for chaining
-   *
-   * @example
-   * ```typescript
-   * app.setErrorHandler((error, ctx) => {
-   *   console.error('Request failed:', error);
-   *
-   *   if (error instanceof ValidationError) {
-   *     ctx.status = 400;
-   *     ctx.json({ error: error.message, details: error.details });
-   *     return;
-   *   }
-   *
-   *   ctx.status = 500;
-   *   ctx.json({ error: 'Internal Server Error' });
-   * });
-   * ```
+   * @remarks
+   * There is intentionally no `app.options()` verb method — it would collide
+   * with the `app.options` configuration property. Register OPTIONS routes via
+   * `app.all()`, the router directly, or let CORS middleware handle preflight.
    */
-  setErrorHandler(handler) {
-    this._errorHandler = handler;
+  all(path, ...entries) {
+    this.assertConfigurable("all");
+    this.requireRouter().all(path, ...entries);
     return this;
   }
+  // ===========================================================================
+  // Error Handling
+  // ===========================================================================
   /**
-   * Set custom error handler.
+   * Set the application error handler. Replaces any previously set handler.
    *
    * @param handler - Error handler function
    * @returns this for chaining
-   *
-   * @deprecated Use `setErrorHandler()` instead — `onError()` implies
-   * event subscription (additive), but this is a setter (replaces).
    */
-  onError(handler) {
-    return this.setErrorHandler(handler);
+  setErrorHandler(handler) {
+    this.assertConfigurable("setErrorHandler");
+    this._errorHandler = handler;
+    return this;
   }
   // ===========================================================================
-  // Plugin System
+  // Extension System (see RFC-NEXTRUSH-PLUGIN-SYSTEM)
   // ===========================================================================
   /**
-   * Install a plugin.
+   * Register an extension. Queues it — `setup()` runs later, at `ready()`,
+   * in registration order. Synchronous and chainable.
    *
-   * Handles both sync and async `install()` methods automatically.
-   * Returns `this` for sync plugins and `Promise<this>` for async ones.
-   *
-   * @param plugin - Plugin to install
-   * @returns this (sync) or Promise<this> (async)
+   * @param extension - Extension to register. If it declares a decorated
+   * shape via `Extension<TDecorated>`, the return type carries that shape —
+   * `app.extend(events<MyEvents>()).events` is statically known, no
+   * `declare module` augmentation required.
+   * @returns this, intersected with the extension's declared decorated shape
    *
    * @example
    * ```typescript
-   * // Sync plugin
-   * app.plugin(loggerPlugin({ level: 'info' }));
-   *
-   * // Async plugin — just await it
-   * await app.plugin(databasePlugin({ uri: '...' }));
+   * const extended = app.extend(events<MyEvents>());
+   * await app.ready(); // adapters call this automatically — runs setup()/decorate()
+   * extended.events.emit('user:created', { id: '1' }); // available only AFTER ready()
    * ```
    */
-  plugin(plugin) {
-    this.assertNotRunning("plugin");
-    if (this.plugins.has(plugin.name)) {
-      throw new Error(`Plugin "${plugin.name}" is already installed`);
+  extend(extension) {
+    this.assertConfigurable("extend");
+    if (!extension || typeof extension.setup !== "function") {
+      throw new TypeError("Extension must have a setup() method");
     }
-    const result = plugin.install(this);
-    if (result instanceof Promise) {
-      return result.then(() => {
-        this.plugins.set(plugin.name, plugin);
-        return this;
+    if (this.extensionNames.has(extension.name)) {
+      throw new Error(
+        `Extension "${extension.name}" is already registered. Use a different extension name, or check for a duplicate app.extend() call.`
+      );
+    }
+    this.extensionNames.add(extension.name);
+    this.extensions.push(extension);
+    if (typeof extension.destroy === "function") {
+      const destroyableExtension = extension;
+      this.teardownUnits.push({
+        name: extension.name,
+        run: () => destroyableExtension.destroy()
       });
     }
-    this.plugins.set(plugin.name, plugin);
     return this;
   }
   /**
-   * Install a plugin asynchronously.
-   *
-   * @param plugin - Plugin to install
-   * @returns Promise that resolves when plugin is installed
+   * Boot the application: run every registered extension's `setup()` once, in
+   * registration order, awaiting async setups. Idempotent — safe to call twice.
+   * Adapters call this automatically before `start()`.
    *
-   * @deprecated Use `plugin()` instead — it handles both sync and async
-   * plugins automatically.
+   * After `ready()` resolves, the configuration is frozen (`use`/`route`/`extend`
+   * throw).
    *
-   * @example
-   * ```typescript
-   * await app.plugin(new DatabasePlugin({ connectionString: '...' }));
-   * ```
+   * @returns this
+   * @throws if an extension declares a `needs` dependency not yet registered
    */
-  async pluginAsync(plugin) {
-    const result = this.plugin(plugin);
-    return result instanceof Promise ? result : Promise.resolve(result);
+  async ready() {
+    if (this._isReady) {
+      return this;
+    }
+    this._readyPromise ??= this._boot().catch((err) => {
+      this._readyPromise = null;
+      throw err;
+    });
+    return this._readyPromise;
+  }
+  /**
+   * Run the boot sequence once (extension setup + router mount). Guarded and
+   * memoized by {@link ready}.
+   */
+  async _boot() {
+    const allNames = new Set(this.extensions.map((e) => e.name));
+    for (const extension of this.extensions) {
+      if (extension.needs) {
+        for (const dep of extension.needs) {
+          if (!allNames.has(dep)) {
+            throw new Error(
+              `Extension "${extension.name}" needs "${dep}", but no extension named "${dep}" was ever registered.`
+            );
+          }
+        }
+      }
+    }
+    const setupDone = /* @__PURE__ */ new Set();
+    for (const extension of this.extensions) {
+      if (extension.needs) {
+        for (const dep of extension.needs) {
+          if (!setupDone.has(dep)) {
+            throw new Error(
+              `Extension "${extension.name}" needs "${dep}", but "${dep}" was not registered before it. Register the "${dep}" extension before "${extension.name}".`
+            );
+          }
+        }
+      }
+      const ctx = {
+        app: this,
+        logger: this.logger,
+        container: this.container,
+        env: this.options.env ?? "development",
+        name: extension.name,
+        decorate: (name, value) => {
+          this.decorate(name, value);
+        }
+      };
+      await extension.setup(ctx);
+      setupDone.add(extension.name);
+    }
+    if (this.router) {
+      this.middlewareStack.push(this.router.routes());
+      this._routerMounted = true;
+    }
+    this._isReady = true;
+    return this;
   }
   /**
-   * Get an installed plugin by name
+   * Attach a value to the app under `name`. Extension-author primitive, invoked
+   * through {@link ExtensionContext.decorate} — there is intentionally no public
+   * `app.decorate()` (RFC §6.1). Throws on collision.
    *
-   * @param name - Plugin name
-   * @returns Plugin instance or undefined
+   * @internal
    */
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-  getPlugin(name) {
-    return this.plugins.get(name);
+  decorate(name, value) {
+    if (this.decorations.has(name)) {
+      throw new Error(
+        `Decoration "${name}" already exists on the application. Choose a different name, or check for a duplicate ctx.decorate() call across your extensions.`
+      );
+    }
+    if (name in this) {
+      throw new Error(
+        `Decoration "${name}" collides with an existing Application member \u2014 choose another name`
+      );
+    }
+    Object.defineProperty(this, name, {
+      value,
+      enumerable: true,
+      writable: false,
+      configurable: true
+      // allow close() to clean up
+    });
+    this.decorations.add(name);
   }
   /**
-   * Check if a plugin is installed
+   * Whether a decoration already occupies `name`.
    */
-  hasPlugin(name) {
-    return this.plugins.has(name);
+  hasDecorator(name) {
+    return this.decorations.has(name);
   }
   // ===========================================================================
   // Request Handler
   // ===========================================================================
   /**
-   * Create the request handler callback
-   *
-   * This is the function that adapters call to handle each request.
-   * It composes all middleware and returns a function that processes context.
+   * Create the request handler callback.
    *
-   * **Important:** The middleware stack is snapshot at call time.
-   * Middleware or plugins added after `callback()` will NOT take effect
-   * on the returned handler. Call `callback()` again to get a
-   * handler that includes subsequent registrations.
+   * The middleware stack is snapshot at call time — call `ready()` before
+   * `callback()` so extension-registered middleware is included. Adapters do
+   * this automatically.
    *
    * @returns Request handler function
    */
   callback() {
-    const fn = compose(this.middlewareStack);
-    const hookPlugins = Array.from(this.plugins.values()).filter((p) => {
-      const hasHook = "onRequest" in p || "onResponse" in p || "onError" in p || "extendContext" in p;
-      if (!hasHook) return false;
-      if ("onRequest" in p && typeof p.onRequest !== "function") {
-        throw new TypeError(
-          `Plugin "${p.name}": onRequest must be a function, got ${typeof p.onRequest}`
-        );
-      }
-      if ("onResponse" in p && typeof p.onResponse !== "function") {
-        throw new TypeError(
-          `Plugin "${p.name}": onResponse must be a function, got ${typeof p.onResponse}`
-        );
-      }
-      if ("onError" in p && typeof p.onError !== "function") {
-        throw new TypeError(
-          `Plugin "${p.name}": onError must be a function, got ${typeof p.onError}`
-        );
-      }
-      if ("extendContext" in p && typeof p.extendContext !== "function") {
-        throw new TypeError(
-          `Plugin "${p.name}": extendContext must be a function, got ${typeof p.extendContext}`
-        );
-      }
-      return true;
+    if (!this._isReady && this.extensions.length > 0) {
+      this.logger.warn(
+        `callback() was called before ready(), but ${String(this.extensions.length)} extension(s) were registered via extend() \u2014 their setup() will NOT run, and anything they would decorate (e.g. app.events) will be missing. Call \`await app.ready()\` before \`callback()\`. Adapters (listen/serve) do this automatically.`
+      );
+    }
+    const fn = compose(this.middlewareStack, {
+      warnDoubleResponse: !this.isProduction
     });
     return async (ctx) => {
       try {
-        for (const p of hookPlugins) {
-          if (p.extendContext) p.extendContext(ctx);
-          if (p.onRequest) await p.onRequest(ctx);
-        }
         await fn(ctx);
-        for (const p of hookPlugins) {
-          if (p.onResponse) {
-            try {
-              await p.onResponse(ctx);
-            } catch (hookError) {
-              this.logger.warn("Plugin onResponse hook threw:", {
-                plugin: p.name,
-                error: hookError
-              });
-            }
-          }
-        }
       } catch (error) {
-        const err = error instanceof Error ? error : new Error(String(error));
-        for (const p of hookPlugins) {
-          if (p.onError) {
-            try {
-              await p.onError(err, ctx);
-            } catch (hookError) {
-              this.logger.warn("Plugin onError hook threw:", {
-                plugin: p.name,
-                error: hookError
-              });
-            }
-          }
-        }
         await this.handleError(error, ctx);
       }
     };
@@ -460,31 +574,21 @@ var Application = class {
         this.logger.error("Error handler threw:", handlerError);
       }
     }
-    this.defaultErrorHandler(err, ctx);
+    try {
+      this.defaultErrorHandler(err, ctx);
+    } catch (fatal) {
+      this.logger.error("Default error handler threw:", fatal);
+    }
   }
   /**
-   * Default error handler
-   *
-   * Uses the `expose` flag on errors (set by HttpError/NextRushError)
-   * to decide whether to include the error message in the response.
-   * 4xx errors expose messages by default; 5xx errors never do.
-   * This prevents leaking internal details (paths, SQL, stack info)
-   * regardless of environment.
+   * Default error handler — delegates to the shared error serializer so the
+   * default response matches `@nextrush/errors`' `errorHandler()` (audit C-1).
    */
   defaultErrorHandler(error, ctx) {
-    if (!this.isProduction) {
-      this.logger.error("Request error:", error);
-    }
-    const errorMeta = error;
-    let status = 500;
-    if (typeof errorMeta.status === "number") {
-      const raw = errorMeta.status;
-      status = raw >= 400 && raw < 600 ? raw : 500;
-    }
-    ctx.status = status;
-    const expose = errorMeta.expose === true;
-    const message = expose ? error.message : "Internal Server Error";
-    ctx.json({ error: message });
+    writeDefaultErrorResponse(error, ctx, {
+      logger: this.logger,
+      isProduction: this.isProduction
+    });
   }
   // ===========================================================================
   // Lifecycle
@@ -492,37 +596,85 @@ var Application = class {
   /**
    * Mark app as running and freeze configuration.
    *
-   * Called by adapters when the server starts listening. After this call,
-   * `use()`, `route()`, `plugin()`, and `pluginAsync()` will throw.
-   * This prevents unsafe middleware mutations while requests are in flight.
-   *
-   * To re-enable registration (e.g. for testing), call `close()` first.
+   * Called by adapters when the server starts listening (after `ready()`).
    */
   start() {
     this._isRunning = true;
   }
   /**
-   * Graceful shutdown
-   * Destroys all plugins that have a destroy method.
-   * Uses Promise.allSettled to ensure all plugins are destroyed
-   * even if some throw errors.
+   * Register a teardown hook for a resource outside the extension system
+   * (stateful middleware, a manually-attached service, …). Run during
+   * {@link close} under the SAME bounded/isolated guarantee as extension
+   * `destroy()` — one throwing/hanging hook never strands the others — in one
+   * combined reverse-of-registration order together with every `extend()`ed
+   * extension's `destroy()` (RFC-022 §8.1/§8.2).
+   *
+   * @param hook - Teardown callback. May be sync or async; a thrown/rejected
+   * hook is isolated and its error collected in {@link close}'s returned array.
    *
-   * @returns Array of errors from plugins that failed to destroy (empty on success)
+   * @remarks Registration is pre-shutdown only: a hook registered after
+   * `close()` has already started is not run in that shutdown (RFC-022 §8.6).
+   *
+   * @example
+   * ```typescript
+   * const store = new MemoryStore(options);
+   * app.onClose(() => store.shutdown());
+   * ```
    */
-  async close() {
+  onClose(hook) {
+    if (this._closeStarted) {
+      return;
+    }
+    this.teardownUnits.push({ name: "onClose hook", run: hook });
+  }
+  /**
+   * Graceful shutdown. Destroys extensions in reverse registration order,
+   * each isolated from the others' failures — one failing/hanging `destroy()`
+   * never strands the rest (RFC-022 / ADR-0012).
+   *
+   * @param options - Optional teardown budget. Omitted = unbounded, byte-identical
+   * to today's behavior (`Promise.allSettled`, no timeout). When `timeout` is
+   * given, every teardown unit races against it independently; a unit that
+   * does not finish in time is reported as a {@link TeardownTimeoutError} in
+   * the returned array instead of blocking `close()` past the budget.
+   * @returns Array of errors from units that failed or timed out (empty on success)
+   */
+  async close(options) {
+    this._closePromise ??= this._shutdown(options);
+    return this._closePromise;
+  }
+  /** Run the shutdown sequence once. Guarded and memoized by {@link close}. */
+  async _shutdown(options) {
     this._isRunning = false;
-    const pluginArray = Array.from(this.plugins.values()).reverse();
-    const destroyablePlugins = pluginArray.filter(
-      (p) => typeof p.destroy === "function"
-    );
-    const destroyPromises = destroyablePlugins.map(
-      (p) => Promise.resolve().then(() => p.destroy()).catch((err) => {
-        throw err instanceof Error ? err : new Error(String(err));
-      })
-    );
-    const results = await Promise.allSettled(destroyPromises);
-    this.plugins.clear();
-    return results.filter((r) => r.status === "rejected").map((r) => r.reason instanceof Error ? r.reason : new Error(String(r.reason)));
+    this._closeStarted = true;
+    this.logger.info("Application is draining: graceful shutdown starting");
+    if (!this._isReady && this.extensions.length > 0) {
+      this.logger.warn(
+        `close() was called before ready(), but ${String(this.extensions.length)} extension(s) were registered via extend() \u2014 their setup() never ran, yet destroy() will still be called on them now. If destroy() assumes setup()-established state, this may throw or behave incorrectly. Call \`await app.ready()\` before \`close()\`.`
+      );
+    }
+    const timeoutMs = options?.timeout;
+    const units = [...this.teardownUnits].reverse();
+    const errors = (await Promise.all(units.map((unit) => runTeardownUnit(unit, timeoutMs)))).filter((e) => e !== null);
+    for (const error of errors) {
+      this.logger.error("Teardown unit failed during shutdown:", error);
+    }
+    for (const name of this.decorations) {
+      Reflect.deleteProperty(this, name);
+    }
+    this.decorations.clear();
+    this.extensions.length = 0;
+    this.extensionNames.clear();
+    this.teardownUnits.length = 0;
+    this._isReady = false;
+    this._readyPromise = null;
+    this._closePromise = null;
+    this._closeStarted = false;
+    if (this._routerMounted) {
+      this.middlewareStack.pop();
+      this._routerMounted = false;
+    }
+    return errors;
   }
 };
 function createApp(options) {