@schmock/core 2.4.1 → 2.6.0

package/dist/builder.js

@@ -1,190 +1,53 @@
 import { awaitWithAbort, throwIfAborted } from "./abort.js";
-import { isBinaryBody } from "./binary.js";
-import { canonicalizePath, markResponseException, markRouteNotFound, normalizePath, toHttpMethod, } from "./constants.js";
-import { errorMessage, RouteDefinitionError, RouteNotFoundError, SchmockError, } from "./errors.js";
-import { collectBody, HttpIngressError, parseNodeHeaders, parseNodeQuery, writeRejectedSchmockResponse, writeSchmockResponse, } from "./http-helpers.js";
-import { createFetchInterceptor } from "./interceptor.js";
-import { parseRouteKey } from "./parser.js";
+import { canonicalizePath, markResponseException, markRouteNotFound, matchPathPrefix, normalizePath, parsePathPrefix, } from "./constants.js";
+import { DebugLogger } from "./debug-logger.js";
+import { applyResponseDelay } from "./delay.js";
+import { errorMessage, RouteNotFoundError, SchmockError } from "./errors.js";
+import { MockEvents } from "./events.js";
+import { RequestGenerations } from "./generations.js";
+import { redactHeaders } from "./headers.js";
+import { RequestHistory } from "./history.js";
+import { createFetchLease, NORMALIZED_ADMISSION_KEY, } from "./interceptor.js";
+import { NodeServerController } from "./node-server.js";
+import { assertValidPlugin, hasExchangeObserver, runExchangeHooks, runInstallHook, runUninstallHooks, } from "./plugin-hooks.js";
 import { recoverGeneratorError, runPluginBeforeRequest, runPluginPipeline, } from "./plugin-pipeline.js";
-import { normalizeResponse } from "./response-normalizer.js";
+import { buildJsonErrorResponse, normalizeResponse, } from "./response-normalizer.js";
 import { parseResponse } from "./response-parser.js";
 import { extractParams, findRoute, isGeneratorFunction, } from "./route-matcher.js";
-function isThenable(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        "then" in value &&
-        typeof value.then === "function");
-}
-function unavailableHistoryValue(value) {
-    let type = typeof value;
-    if (typeof value === "object" && value !== null) {
-        try {
-            type = Object.prototype.toString.call(value);
-        }
-        catch {
-            type = "object";
-        }
-    }
-    return {
-        kind: "unavailable",
-        reason: "not-structured-cloneable",
-        type,
-    };
-}
-function removeSharedMemory(value, seen = new WeakMap()) {
-    if (typeof value !== "object" || value === null)
-        return value;
-    const existing = seen.get(value);
-    if (existing !== undefined)
-        return existing;
-    if (typeof SharedArrayBuffer !== "undefined" &&
-        value instanceof SharedArrayBuffer) {
-        const copy = Uint8Array.from(new Uint8Array(value)).buffer;
-        seen.set(value, copy);
-        return copy;
-    }
-    if (ArrayBuffer.isView(value) &&
-        typeof SharedArrayBuffer !== "undefined" &&
-        value.buffer instanceof SharedArrayBuffer) {
-        const copy = Uint8Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength));
-        seen.set(value, copy);
-        return copy;
-    }
-    seen.set(value, value);
-    if (value instanceof Map) {
-        const entries = [...value.entries()];
-        value.clear();
-        for (const [key, entryValue] of entries) {
-            value.set(removeSharedMemory(key, seen), removeSharedMemory(entryValue, seen));
-        }
-        return value;
-    }
-    if (value instanceof Set) {
-        const entries = [...value.values()];
-        value.clear();
-        for (const entryValue of entries) {
-            value.add(removeSharedMemory(entryValue, seen));
-        }
-        return value;
-    }
-    for (const key of Reflect.ownKeys(value)) {
-        Reflect.set(value, key, removeSharedMemory(Reflect.get(value, key), seen));
-    }
-    return value;
-}
-/**
- * Reject a history limit that cannot bound anything.
- *
- * A negative limit used to read as "unbounded" and a fractional one evicted a
- * fractional number of records, so a typo silently disabled the cap instead of
- * failing. `Number.isInteger` also rejects NaN and Infinity. `0` stays valid
- * and keeps meaning "history disabled".
- */
-function assertValidHistoryLimit(limit) {
-    if (limit === undefined)
-        return;
-    if (!Number.isInteger(limit) || limit < 0) {
-        throw new SchmockError(`Invalid maxHistorySize: ${String(limit)}. Expected a non-negative integer (0 disables history).`, "INVALID_CONFIG", { maxHistorySize: limit });
-    }
-}
-/**
- * Header names whose VALUE is replaced in debug logs. The name is kept so a log
- * still shows the header was present; only the credential is hidden. Matches
- * the set the CLI already masks.
- */
-const REDACTED_HEADER_NAMES = new Set([
-    "authorization",
-    "proxy-authorization",
-    "cookie",
-    "set-cookie",
-    "x-api-key",
-    "x-auth-token",
-    "x-schmock-admin-token",
-]);
-const REDACTED_HEADER_VALUE = "[redacted]";
-/**
- * Copy-on-write redaction: the input record is handed on to plugins, history
- * and transports, so it must never be mutated. When nothing is sensitive the
- * original object is returned unchanged.
- */
-function redactSensitiveHeaders(headers) {
-    let redacted;
-    for (const name of Object.keys(headers)) {
-        if (!REDACTED_HEADER_NAMES.has(name.toLowerCase()))
-            continue;
-        redacted ??= { ...headers };
-        redacted[name] = REDACTED_HEADER_VALUE;
-    }
-    return redacted ?? headers;
-}
-function snapshotHistoryValue(value) {
-    try {
-        return removeSharedMemory(structuredClone(value));
-    }
-    catch {
-        return unavailableHistoryValue(value);
-    }
-}
-/**
- * Debug logger that respects debug mode configuration
- */
-class DebugLogger {
-    enabled;
-    constructor(enabled = false) {
-        this.enabled = enabled;
-    }
-    log(category, message, data) {
-        if (!this.enabled)
-            return;
-        const timestamp = new Date().toISOString();
-        const prefix = `[${timestamp}] [SCHMOCK:${category.toUpperCase()}]`;
-        if (data) {
-            console.log(`${prefix} ${message}`, data);
-        }
-        else {
-            console.log(`${prefix} ${message}`);
-        }
-    }
-    time(label) {
-        if (!this.enabled)
-            return;
-        console.time(`[SCHMOCK] ${label}`);
-    }
-    timeEnd(label) {
-        if (!this.enabled)
-            return;
-        console.timeEnd(`[SCHMOCK] ${label}`);
-    }
-}
+import { copyRouteConfig, copyStaticData, RouteTable } from "./route-table.js";
+/** `request:end` status for a request its caller cancelled. */
+const ABORTED_REQUEST_STATUS = 499;
 /**
  * Callable mock instance that implements the new API.
  *
  * @internal
  */
 export class CallableMockInstance {
-    routes = [];
-    staticRoutes = new Map();
+    routeTable = new RouteTable();
     plugins = [];
     logger;
-    requestHistory = [];
+    requestHistory;
+    nodeServer;
     callableRef;
-    server;
-    pendingServerStart;
-    serverCloseBarrier;
     interceptHandles = new Set();
-    requestGeneration = { activeAdmissions: 0 };
-    historyGeneration = Symbol("schmock.history.generation");
+    generations = new RequestGenerations((plugins) => this.uninstallPlugins(plugins));
     interceptOwner = Symbol("schmock.intercept.owner");
     globalConfig;
-    // biome-ignore lint/complexity/noBannedTypes: internal storage for event listeners with varying signatures
-    listeners = new Map();
+    events;
+    namespaceCache;
     constructor(globalConfig = {}) {
-        assertValidHistoryLimit(globalConfig.maxHistorySize);
+        // First: an invalid maxHistorySize throws before anything else is built.
+        this.requestHistory = new RequestHistory(globalConfig.maxHistorySize);
         this.globalConfig = {
             ...globalConfig,
             state: globalConfig.state ?? {},
         };
         this.logger = new DebugLogger(globalConfig.debug || false);
+        this.events = new MockEvents(this.logger);
+        this.nodeServer = new NodeServerController({
+            admitRequest: () => this.createRequestAdmission(),
+            logger: this.logger,
+        });
         if (globalConfig.debug) {
             this.logger.log("config", "Debug mode enabled");
         }
@@ -196,153 +59,44 @@ export class CallableMockInstance {
     }
     // Method for defining routes (called when instance is invoked)
     defineRoute(route, generator, config) {
-        // FIX 1.2: shallow-clone the caller's config so mutations below stay private
-        const routeConfig = { ...config };
-        // Auto-detect contentType if not provided
-        if (!routeConfig.contentType) {
-            if (typeof generator === "function") {
-                // Default to JSON for function generators
-                routeConfig.contentType = "application/json";
-            }
-            else if (typeof generator === "string" ||
-                typeof generator === "number" ||
-                typeof generator === "boolean") {
-                // Default to plain text for primitives
-                routeConfig.contentType = "text/plain";
-            }
-            else if (isBinaryBody(generator)) {
-                // Default to octet-stream for browser and Node binary values
-                routeConfig.contentType = "application/octet-stream";
-            }
-            else {
-                // Default to JSON for objects/arrays
-                routeConfig.contentType = "application/json";
-            }
-        }
-        // Validate generator matches contentType if it's static data
-        if (typeof generator !== "function" &&
-            routeConfig.contentType === "application/json") {
-            try {
-                JSON.stringify(generator);
-            }
-            catch (_error) {
-                throw new RouteDefinitionError(route, "Generator data is not valid JSON but contentType is application/json");
-            }
-        }
-        // Parse the route key to create pattern and extract parameters
-        const parsed = parseRouteKey(route);
-        // FIX 2.2: normalize paths before duplicate check so /users and /users/ are
-        // treated as the same route (consistent with the static-route Map key below)
-        const normalizedParsedPath = normalizePath(parsed.path);
-        const existing = this.routes.find((r) => r.method === parsed.method &&
-            normalizePath(r.path) === normalizedParsedPath);
-        if (existing) {
-            this.logger.log("warning", `Duplicate route: ${route} — first registration wins`);
-            return this;
-        }
-        // Compile the route
-        const compiledRoute = {
-            pattern: parsed.pattern,
-            params: parsed.params,
-            method: parsed.method,
-            path: parsed.path,
-            generator,
-            config: routeConfig,
-        };
-        this.routes.push(compiledRoute);
-        // Store static routes (no params) in Map for O(1) lookup
-        if (parsed.params.length === 0) {
-            const key = `${parsed.method} ${normalizePath(parsed.path)}`;
-            this.staticRoutes.set(key, compiledRoute);
-        }
-        this.logger.log("route", `Route defined: ${route}`, {
-            contentType: routeConfig.contentType,
-            generatorType: typeof generator,
-            hasParams: parsed.params.length > 0,
-        });
+        this.routeTable.define({ route, generator, config, logger: this.logger });
         return this;
     }
     setCallableRef(ref) {
         this.callableRef = ref;
     }
     pipe(plugin) {
+        assertValidPlugin(plugin);
+        if (this.plugins.includes(plugin)) {
+            // Piping one object twice used to run install() twice and process()
+            // twice per request. It is a no-op rather than an error because the
+            // pattern is common and was silently accepted: `.pipe(p)` chained after
+            // every route definition, or a beforeEach that pipes without a reset.
+            // Distinct objects that share a name (two openapi() specs) still stack.
+            this.logger.log("warning", `Plugin ${plugin.name} is already piped into this mock — ignored`);
+            return this;
+        }
+        this.generations.uninstallBeforeReinstall(plugin);
         if (plugin.install && this.callableRef) {
-            const previousRoutes = this.routes;
-            const previousStaticRoutes = this.staticRoutes;
-            this.routes = previousRoutes.slice();
-            this.staticRoutes = new Map(previousStaticRoutes);
-            let installActive = true;
-            let installFacade;
-            const requireInstallScope = () => {
-                if (installActive)
-                    return;
-                throw new SchmockError(`Plugin "${plugin.name}" used its install instance outside install()`, "PLUGIN_INSTALL_SCOPE_EXPIRED", { plugin: plugin.name });
-            };
-            const rejectInstallOperation = (operation) => {
-                requireInstallScope();
-                throw new SchmockError(`Plugin "${plugin.name}" cannot call ${operation} during install()`, "PLUGIN_INSTALL_OPERATION_UNSUPPORTED", { operation, plugin: plugin.name });
-            };
-            const registerRoute = (route, generator, config = {}) => {
-                requireInstallScope();
-                this.defineRoute(route, generator, config);
-                return installFacade;
-            };
-            installFacade = Object.assign(registerRoute, {
-                pipe: () => rejectInstallOperation("pipe()"),
-                handle: () => rejectInstallOperation("handle()"),
-                history: (method, path) => {
-                    requireInstallScope();
-                    return this.history(method, path);
-                },
-                called: (method, path) => {
-                    requireInstallScope();
-                    return this.called(method, path);
-                },
-                callCount: (method, path) => {
-                    requireInstallScope();
-                    return this.callCount(method, path);
-                },
-                lastRequest: (method, path) => {
-                    requireInstallScope();
-                    return this.lastRequest(method, path);
-                },
-                reset: () => rejectInstallOperation("reset()"),
-                resetHistory: () => rejectInstallOperation("resetHistory()"),
-                resetState: () => rejectInstallOperation("resetState()"),
-                on: () => rejectInstallOperation("on()"),
-                off: () => rejectInstallOperation("off()"),
-                getRoutes: () => {
-                    requireInstallScope();
-                    return this.getRoutes();
-                },
-                getState: () => {
-                    requireInstallScope();
-                    return this.getState();
-                },
-                listen: () => rejectInstallOperation("listen()"),
-                close: () => rejectInstallOperation("close()"),
-                intercept: () => rejectInstallOperation("intercept()"),
-            });
+            // Routes the hook registers before it fails are rolled back with it.
+            const checkpoint = this.routeTable.checkpoint();
             try {
-                const installResult = plugin.install(installFacade);
-                installActive = false;
-                if (isThenable(installResult)) {
-                    void Promise.resolve(installResult).catch((error) => {
-                        this.logger.log("plugin", `Rejected async install for ${plugin.name}: ${errorMessage(error)}`);
-                    });
-                    throw new SchmockError(`Plugin "${plugin.name}" returned a Promise from install()`, "PLUGIN_ASYNC_INSTALL_UNSUPPORTED", { plugin: plugin.name });
-                }
+                runInstallHook({
+                    plugin,
+                    reads: this,
+                    registerRoute: (route, generator, config) => {
+                        this.defineRoute(route, generator, config);
+                    },
+                    logger: this.logger,
+                });
             }
             catch (error) {
-                this.routes = previousRoutes;
-                this.staticRoutes = previousStaticRoutes;
+                this.routeTable.rollback(checkpoint);
                 throw error;
             }
-            finally {
-                installActive = false;
-            }
         }
-        this.plugins.push(plugin);
+        // Replaced, never pushed into: in-flight admissions hold the old array.
+        this.plugins = [...this.plugins, plugin];
         this.logger.log("plugin", `Registered plugin: ${plugin.name}@${plugin.version || "unknown"}`, {
             name: plugin.name,
             version: plugin.version,
@@ -352,154 +106,58 @@ export class CallableMockInstance {
         return this;
     }
     uninstallPlugins(plugins) {
-        for (let index = plugins.length - 1; index >= 0; index -= 1) {
-            const plugin = plugins[index];
-            if (!plugin.uninstall || !this.callableRef)
-                continue;
-            try {
-                const uninstallResult = plugin.uninstall(this.callableRef);
-                if (isThenable(uninstallResult)) {
-                    void Promise.resolve(uninstallResult).catch((error) => {
-                        this.logger.log("plugin", `Async uninstall for ${plugin.name} failed: ${errorMessage(error)}`);
-                    });
-                    this.logger.log("plugin", `Plugin ${plugin.name} returned an unsupported Promise from uninstall()`);
-                }
-            }
-            catch (error) {
-                this.logger.log("plugin", `Plugin ${plugin.name} uninstall failed: ${errorMessage(error)}`);
-            }
-        }
+        if (!this.callableRef)
+            return;
+        runUninstallHooks({ plugins, reads: this, logger: this.logger });
     }
     // ===== Request Spy / History API =====
-    cloneRecord(r) {
-        return {
-            method: r.method,
-            path: r.path,
-            params: { ...r.params },
-            query: { ...r.query },
-            headers: { ...r.headers },
-            body: snapshotHistoryValue(r.body),
-            timestamp: r.timestamp,
-            response: {
-                status: r.response.status,
-                body: snapshotHistoryValue(r.response.body),
-            },
-        };
-    }
-    /**
-     * History stores the canonical request path — percent-encoded and
-     * trailing-slash-normalized exactly as `handle()` produced it — so a spy
-     * filter must be put into the same form before it is compared, or the very
-     * string the caller passed to `handle()` would not match its own record.
-     * `canonicalizePath` is idempotent, so an already-encoded filter keeps
-     * matching and both spellings work.
-     */
-    #historyMatcher(method, path) {
-        const wanted = path === undefined ? undefined : normalizePath(canonicalizePath(path));
-        return (r) => (!method || r.method === method) && (!wanted || r.path === wanted);
-    }
     history(method, path) {
-        if (method || path) {
-            return this.requestHistory
-                .filter(this.#historyMatcher(method, path))
-                .map((r) => this.cloneRecord(r));
-        }
-        return this.requestHistory.map((r) => this.cloneRecord(r));
+        return this.requestHistory.history(method, path);
     }
     called(method, path) {
-        if (method || path) {
-            return this.requestHistory.some(this.#historyMatcher(method, path));
-        }
-        return this.requestHistory.length > 0;
+        return this.requestHistory.called(method, path);
     }
     callCount(method, path) {
-        if (method || path) {
-            return this.requestHistory.filter(this.#historyMatcher(method, path))
-                .length;
-        }
-        return this.requestHistory.length;
+        return this.requestHistory.callCount(method, path);
     }
     lastRequest(method, path) {
-        if (method || path) {
-            const filtered = this.requestHistory.filter(this.#historyMatcher(method, path));
-            const last = filtered[filtered.length - 1];
-            // FIX 2.3: return a deep clone so callers cannot corrupt internal history
-            return last ? this.cloneRecord(last) : undefined;
-        }
-        const last = this.requestHistory[this.requestHistory.length - 1];
-        // FIX 2.3: return a deep clone so callers cannot corrupt internal history
-        return last ? this.cloneRecord(last) : undefined;
+        return this.requestHistory.lastRequest(method, path);
     }
     // ===== Introspection =====
     getRoutes() {
-        return this.routes.map((r) => ({
-            method: r.method,
-            path: r.path,
-            hasParams: r.params.length > 0,
-        }));
+        return this.routeTable.list();
     }
     getState() {
         return { ...(this.globalConfig.state || {}) };
     }
     // ===== Lifecycle Events =====
     on(event, listener) {
-        let set = this.listeners.get(event);
-        if (!set) {
-            set = new Set();
-            this.listeners.set(event, set);
-        }
-        set.add(listener);
+        this.events.on(event, listener);
         return this;
     }
     off(event, listener) {
-        this.listeners.get(event)?.delete(listener);
+        this.events.off(event, listener);
         return this;
     }
-    emit(event, data) {
-        const set = this.listeners.get(event);
-        if (!set)
-            return;
-        const snapshot = { ...data };
-        if ("headers" in data) {
-            snapshot.headers = Object.freeze({ ...data.headers });
-        }
-        if ("params" in data) {
-            snapshot.params = Object.freeze({ ...data.params });
-        }
-        const eventData = Object.freeze(snapshot);
-        for (const listener of [...set]) {
-            try {
-                const listenerResult = listener(eventData);
-                if (isThenable(listenerResult)) {
-                    void Promise.resolve(listenerResult).catch((error) => {
-                        this.logger.log("event", `${event} listener rejected: ${errorMessage(error)}`);
-                    });
-                }
-            }
-            catch (error) {
-                this.logger.log("event", `${event} listener failed: ${errorMessage(error)}`);
-            }
-        }
-    }
     // ===== Reset / Lifecycle =====
     reset() {
-        const retiredGeneration = this.requestGeneration;
-        this.requestGeneration = { activeAdmissions: 0 };
-        this.historyGeneration = Symbol("schmock.history.generation");
+        const retiredGeneration = this.generations.advance();
+        this.requestHistory.startGeneration();
         this.close();
         const installedPlugins = this.plugins;
         this.plugins = [];
-        this.#retireRequestGeneration(retiredGeneration, installedPlugins);
-        this.routes = [];
-        this.staticRoutes.clear();
-        this.requestHistory = [];
-        this.listeners.clear();
+        this.generations.retire(retiredGeneration, installedPlugins);
+        // Replaced, never cleared in place: in-flight admissions still route with
+        // the old containers.
+        this.routeTable.clear();
+        this.requestHistory.clear();
+        this.events.clear();
         this.globalConfig.state = {};
         this.logger.log("lifecycle", "Mock fully reset");
     }
     resetHistory() {
-        this.historyGeneration = Symbol("schmock.history.generation");
-        this.requestHistory = [];
+        this.requestHistory.startGeneration();
+        this.requestHistory.clear();
         this.logger.log("lifecycle", "Request history cleared");
     }
     resetState() {
@@ -507,18 +165,17 @@ export class CallableMockInstance {
         this.logger.log("lifecycle", "State cleared");
     }
     #captureRequestAdmission() {
-        const requestGeneration = this.requestGeneration;
-        requestGeneration.activeAdmissions += 1;
+        const requestGeneration = this.generations.admit();
+        // O(1) snapshot: the containers are captured by reference. `plugins` is
+        // only ever replaced, and the route tables are copy-on-write.
         return {
             requestGeneration,
-            historyGeneration: this.historyGeneration,
-            plugins: this.plugins.slice(),
-            routes: this.routes.slice(),
-            staticRoutes: new Map(this.staticRoutes),
+            historyGeneration: this.requestHistory.generation,
+            plugins: this.plugins,
+            routes: this.routeTable.share(),
             state: this.globalConfig.state,
             namespace: this.globalConfig.namespace,
             globalDelay: this.globalConfig.delay,
-            maxHistorySize: this.globalConfig.maxHistorySize,
             released: false,
         };
     }
@@ -526,221 +183,39 @@ export class CallableMockInstance {
         if (admission.released)
             return;
         admission.released = true;
-        const generation = admission.requestGeneration;
-        generation.activeAdmissions -= 1;
-        if (generation.activeAdmissions === 0 &&
-            generation.retiredPlugins !== undefined) {
-            const plugins = generation.retiredPlugins;
-            generation.retiredPlugins = undefined;
-            this.uninstallPlugins(plugins);
-        }
-    }
-    #retireRequestGeneration(generation, plugins) {
-        generation.retiredPlugins = plugins;
-        if (generation.activeAdmissions === 0) {
-            generation.retiredPlugins = undefined;
-            this.uninstallPlugins(plugins);
-        }
+        this.generations.release(admission.requestGeneration);
     }
     createRequestAdmission() {
         const admission = this.#captureRequestAdmission();
-        return {
+        const admitted = {
             handle: (method, path, options) => this.handle(method, path, options, admission),
             release: () => this.#releaseRequestAdmission(admission),
-        };
-    }
-    // ===== Standalone Server =====
-    listen(port = 0, hostname = "127.0.0.1") {
-        if (this.server || this.pendingServerStart) {
-            throw new SchmockError("Server is already running", "SERVER_ALREADY_RUNNING");
-        }
-        let resolveStart = (_info) => { };
-        let rejectStart = (_error) => { };
-        const startPromise = new Promise((resolve, reject) => {
-            resolveStart = resolve;
-            rejectStart = reject;
-        });
-        const operation = {
-            token: Symbol("schmock.server.start"),
-            port,
-            hostname,
-            resolve: resolveStart,
-            reject: rejectStart,
-            settled: false,
-        };
-        this.pendingServerStart = operation;
-        const closeBarrier = this.serverCloseBarrier ?? Promise.resolve();
-        void closeBarrier
-            // Lazy-load node:http so browser bundles never pull it in. See issue #395.
-            .then(() => import("node:http"))
-            .then(({ createServer }) => {
-            if (!this.#ownsServerStart(operation))
-                return;
-            this.#startHttpServer(operation, createServer);
-        })
-            .catch((error) => {
-            this.#rejectServerStart(operation, error);
-        });
-        return startPromise;
-    }
-    #ownsServerStart(operation) {
-        return this.pendingServerStart === operation && !operation.settled;
-    }
-    #startHttpServer(operation, createServer) {
-        const httpServer = createServer((req, res) => {
-            const admittedRequest = this.createRequestAdmission();
-            const abortController = new AbortController();
-            const abortRequest = () => abortController.abort();
-            req.once("aborted", abortRequest);
-            res.once("close", abortRequest);
-            let requestMethod = req.method?.toUpperCase() === "HEAD" ? "HEAD" : "GET";
-            const handleRequest = async () => {
+            // Whether handle(method, path) would reach a route, answered from this
+            // admission's own snapshot by the resolver handle() itself uses, so a
+            // miss is never a false negative. The interceptor asks it to skip
+            // reading the body of a request that will pass through anyway.
+            hasRoute: (method, path) => {
                 try {
-                    const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
-                    const method = toHttpMethod(req.method ?? "GET");
-                    requestMethod = method;
-                    const path = url.pathname;
-                    const headers = parseNodeHeaders(req);
-                    const query = parseNodeQuery(url);
-                    const body = await collectBody(req, headers);
-                    const schmockResponse = await admittedRequest.handle(method, path, {
-                        headers,
-                        body,
-                        query,
-                        signal: abortController.signal,
-                    });
-                    writeSchmockResponse(res, schmockResponse);
-                }
-                finally {
-                    req.off("aborted", abortRequest);
-                    res.off("close", abortRequest);
-                    admittedRequest.release();
-                }
-            };
-            handleRequest().catch((error) => {
-                // A failing error-response write must never escape this handler as an
-                // unhandled rejection: destroy the socket so the client is not left
-                // hanging on a response that will never arrive.
-                try {
-                    const ingressError = error instanceof HttpIngressError ? error : undefined;
-                    const status = ingressError?.status ?? 500;
-                    const code = ingressError?.code ?? "SERVER_ERROR";
-                    if (!res.headersSent && !res.writableEnded) {
-                        if (ingressError)
-                            res.shouldKeepAlive = false;
-                        // `shouldKeepAlive = false` alone emits no Connection header when
-                        // writeHead is given a header object, so the announcement has to be
-                        // explicit. It travels on the transport's own header channel rather
-                        // than on the response: normalizeResponse strips hop-by-hop headers
-                        // from everything a route produces.
-                        const transportHeaders = ingressError
-                            ? { connection: "close" }
-                            : undefined;
-                        const response = normalizeResponse({
-                            status,
-                            body: {
-                                error: error instanceof Error
-                                    ? error.message
-                                    : "Internal Server Error",
-                                code,
-                            },
-                            headers: { "content-type": "application/json" },
-                        }, requestMethod);
-                        if (ingressError?.status === 413) {
-                            writeRejectedSchmockResponse(req, res, response, transportHeaders);
-                        }
-                        else {
-                            writeSchmockResponse(res, response, transportHeaders);
-                        }
-                    }
-                    else if (!res.writableEnded) {
-                        res.end();
-                    }
+                    const resolution = this.#resolveRoute(method, canonicalizePath(path), admission);
+                    return resolution.kind === "match";
                 }
                 catch {
-                    res.destroy();
+                    // Whatever made the resolver throw, handle() must answer it.
+                    return true;
                 }
-            });
-        });
-        operation.server = httpServer;
-        const handleStartupError = (error) => {
-            this.#rejectServerStart(operation, error);
+            },
+            // handle() above normalizes every response for its method, so the
+            // interceptor may send one on without a second normalizing pass.
+            [NORMALIZED_ADMISSION_KEY]: true,
         };
-        httpServer.once("error", handleStartupError);
-        try {
-            httpServer.listen(operation.port, operation.hostname, () => {
-                httpServer.off("error", handleStartupError);
-                if (!this.#ownsServerStart(operation)) {
-                    this.#beginServerClose(httpServer);
-                    return;
-                }
-                const addr = httpServer.address();
-                const actualPort = addr !== null && typeof addr === "object"
-                    ? addr.port
-                    : operation.port;
-                const info = { port: actualPort, hostname: operation.hostname };
-                operation.settled = true;
-                this.pendingServerStart = undefined;
-                this.server = httpServer;
-                this.logger.log("server", `Listening on ${operation.hostname}:${actualPort}`);
-                operation.resolve(info);
-            });
-        }
-        catch (error) {
-            httpServer.off("error", handleStartupError);
-            this.#rejectServerStart(operation, error);
-        }
+        return admitted;
     }
-    #rejectServerStart(operation, error) {
-        if (operation.settled)
-            return;
-        operation.settled = true;
-        if (this.pendingServerStart === operation) {
-            this.pendingServerStart = undefined;
-        }
-        if (operation.server) {
-            this.#beginServerClose(operation.server);
-        }
-        operation.reject(error);
-    }
-    #cancelServerStart() {
-        const operation = this.pendingServerStart;
-        if (!operation)
-            return;
-        this.#rejectServerStart(operation, new SchmockError("Server start was cancelled", "SERVER_START_CANCELLED"));
-    }
-    #beginServerClose(server) {
-        const closePromise = new Promise((resolve) => {
-            try {
-                server.close(() => resolve());
-            }
-            catch {
-                resolve();
-            }
-        });
-        try {
-            server.closeAllConnections();
-        }
-        catch {
-            // A not-yet-listening server has no connections to close.
-        }
-        const previousBarrier = this.serverCloseBarrier ?? Promise.resolve();
-        const combinedBarrier = Promise.all([previousBarrier, closePromise]).then(() => undefined);
-        this.serverCloseBarrier = combinedBarrier;
-        void combinedBarrier.finally(() => {
-            if (this.serverCloseBarrier === combinedBarrier) {
-                this.serverCloseBarrier = undefined;
-            }
-        });
+    // ===== Standalone Server =====
+    listen(port = 0, hostname = "127.0.0.1") {
+        return this.nodeServer.listen(port, hostname);
     }
     close() {
-        this.#cancelServerStart();
-        const server = this.server;
-        if (!server)
-            return;
-        this.server = undefined;
-        this.#beginServerClose(server);
-        this.logger.log("server", "Server stopped");
+        this.nodeServer.close();
     }
     // ===== Fetch Interceptor =====
     intercept(options) {
@@ -749,7 +224,13 @@ export class CallableMockInstance {
         // slot with their own options, released independently. The owner symbol
         // keeps them one mock for dispatch, so a single request reaches handle()
         // once no matter how many leases this instance holds.
-        const lease = createFetchInterceptor((method, path, opts) => this.handle(method, path, opts), options, () => this.createRequestAdmission(), this.interceptOwner);
+        const lease = createFetchLease({
+            handle: (method, path, opts) => this.handle(method, path, opts),
+            options,
+            admitRequest: () => this.createRequestAdmission(),
+            owner: this.interceptOwner,
+            observe: () => this.#openExchangeObservation(),
+        });
         const handle = {
             restore: () => {
                 lease.restore();
@@ -768,6 +249,28 @@ export class CallableMockInstance {
         this.logger.log("lifecycle", `Interception lease acquired (${this.interceptHandles.size} held)`);
         return handle;
     }
+    /**
+     * Called by the lease right before it consults this mock about one request.
+     * It captures the plugins and the generation the request is admitted under,
+     * so observers piped later, or retired by reset(), never see it.
+     */
+    #openExchangeObservation() {
+        const plugins = this.plugins; // replaced, never mutated
+        if (!hasExchangeObserver(plugins))
+            return undefined; // no exchange is built
+        const generation = this.generations.current;
+        // Same gate as events and history, checked before each observer: one
+        // observer may reset() the mock and uninstall the ones after it.
+        return (exchange) => {
+            runExchangeHooks({
+                plugins,
+                exchange,
+                logger: this.logger,
+                isLive: () => this.generations.isCurrent(generation),
+            });
+        };
+    }
+    // ===== Request Handling =====
     async handle(method, path, options, admission) {
         const requestAdmission = admission ?? this.#captureRequestAdmission();
         try {
@@ -783,342 +286,360 @@ export class CallableMockInstance {
         // literal unicode, and every lifecycle event, log line and 404 message must
         // report the same spelling.
         const path = canonicalizePath(requestedPath);
-        const requestGeneration = admission.requestGeneration;
-        const historyGeneration = admission.historyGeneration;
-        const requestPlugins = admission.plugins;
-        const requestRoutes = admission.routes;
-        const requestStaticRoutes = admission.staticRoutes;
-        const requestState = admission.state;
-        const namespace = admission.namespace;
-        const globalDelay = admission.globalDelay;
-        const maxHistorySize = admission.maxHistorySize;
         const signal = options?.signal;
         throwIfAborted(signal);
-        const handleStart = performance.now();
-        const requestId = this.globalConfig.debug ? crypto.randomUUID() : "";
-        const reqQuery = { ...(options?.query ?? {}) };
-        const reqHeaders = { ...(options?.headers ?? {}) };
-        const requestBody = options?.body;
+        const scope = {
+            method,
+            path,
+            admission,
+            signal,
+            handleStart: performance.now(),
+            requestId: this.globalConfig.debug ? crypto.randomUUID() : "",
+            query: { ...(options?.query ?? {}) },
+            headers: { ...(options?.headers ?? {}) },
+            body: options?.body,
+        };
+        const { requestId } = scope;
         this.logger.log("request", `[${requestId}] ${method} ${path}`, {
-            headers: redactSensitiveHeaders(reqHeaders),
-            query: reqQuery,
+            headers: redactHeaders(scope.headers),
+            query: scope.query,
             // Presence, not truthiness: "", 0 and false are bodies too.
             bodyType: options !== undefined && "body" in options && options.body !== undefined
                 ? typeof options.body
                 : "none",
         });
         this.logger.time(`request-${requestId}`);
-        if (this.requestGeneration === requestGeneration) {
-            this.emit("request:start", {
+        if (this.generations.isCurrent(admission.requestGeneration)) {
+            this.events.emit("request:start", {
                 method,
                 path,
-                headers: reqHeaders,
+                headers: scope.headers,
             });
         }
-        // Hoisted so the catch block can finalize a matched request the same way
-        // the success path does — same delay override, same history record.
-        let requestPath = path;
-        let matchedRoute;
-        let params = {};
         try {
-            // Apply namespace if configured
-            if (namespace && namespace !== "/") {
-                const normalizedNamespace = canonicalizePath(namespace.startsWith("/") ? namespace : `/${namespace}`);
-                const pathToCheck = path.startsWith("/") ? path : `/${path}`;
-                // Check if path starts with namespace
-                // handle both "/api/users" (starts with /api) and "/api" (exact match)
-                // but NOT "/apiv2" (prefix match but wrong segment)
-                const isMatch = pathToCheck === normalizedNamespace ||
-                    pathToCheck.startsWith(normalizedNamespace.endsWith("/")
-                        ? normalizedNamespace
-                        : `${normalizedNamespace}/`);
-                if (!isMatch) {
-                    this.logger.log("route", `[${requestId}] Path doesn't match namespace ${normalizedNamespace}`);
-                    // A request outside the namespace is a route miss like any other, so
-                    // it reports one instead of silently ending.
-                    return this.#finalizeMiss({
-                        method,
-                        path,
-                        requestId,
-                        handleStart,
-                        requestGeneration,
-                    });
-                }
-                // Remove namespace prefix, ensuring we always start with /
-                const stripped = pathToCheck.slice(normalizedNamespace.length);
-                requestPath = stripped.startsWith("/") ? stripped : `/${stripped}`;
+            const resolution = this.#resolveRoute(method, path, admission);
+            if (resolution.kind !== "match") {
+                this.logger.log("route", resolution.kind === "outside-namespace"
+                    ? `[${requestId}] Path doesn't match namespace ${resolution.namespacePath}`
+                    : `[${requestId}] No route found for ${method} ${resolution.requestPath}`);
+                // A request outside the namespace is a route miss like any other, so
+                // it reports one instead of silently ending.
+                return this.#finalizeMiss(scope);
             }
-            // One trailing-slash normalization for the whole request: route lookup
-            // and parameter extraction must see the identical string, or a request
-            // could match a route and then capture no parameters.
-            requestPath = normalizePath(requestPath);
-            // Find matching route
-            matchedRoute = findRoute(method, requestPath, requestStaticRoutes, requestRoutes);
-            if (!matchedRoute) {
-                this.logger.log("route", `[${requestId}] No route found for ${method} ${requestPath}`);
-                return this.#finalizeMiss({
-                    method,
-                    path,
-                    requestId,
-                    handleStart,
-                    requestGeneration,
-                });
-            }
-            this.logger.log("route", `[${requestId}] Matched route: ${method} ${matchedRoute.path}`);
-            // Extract parameters from the matched route
-            params = extractParams(matchedRoute, requestPath);
-            if (this.requestGeneration === requestGeneration) {
-                this.emit("request:match", {
+            const match = this.#bindRoute(scope, resolution);
+            scope.match = match;
+            if (this.generations.isCurrent(admission.requestGeneration)) {
+                this.events.emit("request:match", {
                     method,
                     // Every lifecycle event carries the ORIGINAL request path; the
                     // namespace-stripped route form is exposed as routePath.
                     path,
-                    routePath: matchedRoute.path,
-                    params,
+                    routePath: match.route.path,
+                    params: match.params,
                 });
             }
             throwIfAborted(signal);
-            // Build plugin context before route code so request guards can reject
-            // invalid or unauthorized requests without triggering side effects.
-            let pluginContext = {
-                path: requestPath,
-                route: matchedRoute.config,
-                method,
-                params,
-                query: reqQuery,
-                headers: reqHeaders,
-                body: requestBody,
-                state: new Map(),
-                routeState: requestState,
-                signal,
-            };
-            const preflightResult = await runPluginBeforeRequest(requestPlugins, pluginContext, this.logger, signal);
-            throwIfAborted(signal);
-            pluginContext = preflightResult.context;
-            if (preflightResult.requestShortCircuited === true) {
-                pluginContext = { ...pluginContext, requestShortCircuited: true };
+            let draft = await this.#runPreflight(scope, match);
+            if (draft.result === undefined) {
+                draft = await this.#runGenerator(scope, match, draft);
             }
-            let result = preflightResult.response;
-            let skipPostProcessing = preflightResult.recoveredFromError === true;
-            if (result === undefined) {
-                const context = {
-                    method: pluginContext.method,
-                    path: pluginContext.path,
-                    params: pluginContext.params,
-                    query: pluginContext.query,
-                    headers: pluginContext.headers,
-                    body: pluginContext.body,
-                    state: pluginContext.routeState ?? requestState,
-                    pluginState: pluginContext.state,
-                    signal,
+            const response = await this.#runResponsePipeline(scope, match, draft);
+            await this.#finalizeMatchedRequest(scope, response);
+            return response;
+        }
+        catch (error) {
+            return await this.#answerFailedRequest(scope, error);
+        }
+    }
+    /**
+     * Where a request path lands in the admission's route table: outside the
+     * namespace, on no route, or on a route. It only resolves — no logs, no
+     * events — so `handle()` and the admission's route probe share it and can
+     * never disagree. `path` must already be canonical.
+     */
+    #resolveRoute(method, path, admission) {
+        let requestPath = path;
+        // Apply namespace if configured. A root namespace ("/") parses to the
+        // empty prefix and strips nothing.
+        const namespacePrefix = admission.namespace
+            ? this.#namespacePrefix(admission.namespace)
+            : undefined;
+        if (namespacePrefix !== undefined && namespacePrefix.path !== "") {
+            const pathToCheck = path.startsWith("/") ? path : `/${path}`;
+            // Segment-boundary match: "/api" serves "/api" and "/api/users" but
+            // not "/apiv2". The trailing-slash rule is parsePathPrefix's, shared
+            // with intercept({ baseUrl }): "/api/" is the same namespace as "/api".
+            if (!matchPathPrefix(namespacePrefix, pathToCheck)) {
+                return {
+                    kind: "outside-namespace",
+                    namespacePath: namespacePrefix.path,
                 };
-                try {
-                    if (isGeneratorFunction(matchedRoute.generator)) {
-                        result = await awaitWithAbort(matchedRoute.generator(context), signal);
-                    }
-                    else {
-                        result = matchedRoute.generator;
-                    }
-                    throwIfAborted(signal);
-                }
-                catch (error) {
-                    throwIfAborted(signal);
-                    const recovery = await recoverGeneratorError(requestPlugins, pluginContext, error, this.logger, signal);
-                    throwIfAborted(signal);
-                    pluginContext = recovery.context;
-                    result = recovery.response;
-                    skipPostProcessing = recovery.recoveredFromError === true;
-                }
             }
-            // Run plugin pipeline to transform the response
-            try {
-                if (skipPostProcessing) {
-                    this.logger.log("pipeline", "Skipping response processors after error recovery");
-                }
-                else {
-                    const pipelineResult = await runPluginPipeline(requestPlugins, pluginContext, result, this.logger, signal);
-                    throwIfAborted(signal);
-                    pluginContext = pipelineResult.context;
-                    result = pipelineResult.response;
-                }
+            // Remove namespace prefix, ensuring we always start with /
+            const stripped = pathToCheck.slice(namespacePrefix.path.length);
+            requestPath = stripped.startsWith("/") ? stripped : `/${stripped}`;
+        }
+        // One trailing-slash normalization for the whole request: route lookup
+        // and parameter extraction must see the identical string, or a request
+        // could match a route and then capture no parameters.
+        requestPath = normalizePath(requestPath);
+        const route = findRoute(method, requestPath, admission.routes.staticRoutes, admission.routes.routes);
+        return route
+            ? { kind: "match", route, requestPath }
+            : { kind: "no-route", requestPath };
+    }
+    /**
+     * Bind a request to the route it matched: its parameters, what history
+     * will record, and its own copy of the route config.
+     */
+    #bindRoute(scope, resolution) {
+        const { route, requestPath } = resolution;
+        this.logger.log("route", `[${scope.requestId}] Matched route: ${scope.method} ${route.path}`);
+        const params = extractParams(route, requestPath);
+        return {
+            route,
+            requestPath,
+            params,
+            // History reports what the CLIENT sent, so it is captured here, before
+            // any plugin or the generator gets the live objects and can edit them.
+            historyParams: { ...params },
+            historySnapshot: this.requestHistory.snapshotRequest(scope),
+            // A per-request copy: a plugin that edits `context.route` in place
+            // changes this request only, never the registered route.
+            routeConfig: copyRouteConfig(route.config),
+        };
+    }
+    /**
+     * Build the plugin context and run the plugins' `beforeRequest` guards, so
+     * they can reject invalid or unauthorized requests before any route code
+     * runs.
+     */
+    async #runPreflight(scope, match) {
+        const { signal } = scope;
+        const pluginContext = {
+            path: match.requestPath,
+            route: match.routeConfig,
+            method: scope.method,
+            params: match.params,
+            query: scope.query,
+            headers: scope.headers,
+            body: scope.body,
+            state: new Map(),
+            routeState: scope.admission.state,
+            signal,
+        };
+        const preflight = await runPluginBeforeRequest(scope.admission.plugins, pluginContext, this.logger, signal);
+        throwIfAborted(signal);
+        return {
+            context: preflight.requestShortCircuited === true
+                ? { ...preflight.context, requestShortCircuited: true }
+                : preflight.context,
+            result: preflight.response,
+            recovered: preflight.recoveredFromError === true,
+        };
+    }
+    /**
+     * Produce the route's response, and give the plugins' `onError` hooks the
+     * chance to recover when the generator throws.
+     */
+    async #runGenerator(scope, match, draft) {
+        const { signal } = scope;
+        const { context: pluginContext } = draft;
+        const plugins = scope.admission.plugins;
+        const context = {
+            method: pluginContext.method,
+            path: pluginContext.path,
+            params: pluginContext.params,
+            query: pluginContext.query,
+            headers: pluginContext.headers,
+            body: pluginContext.body,
+            state: pluginContext.routeState ?? scope.admission.state,
+            pluginState: pluginContext.state,
+            signal,
+        };
+        try {
+            let result;
+            if (isGeneratorFunction(match.route.generator)) {
+                result = await awaitWithAbort(match.route.generator(context), signal);
             }
-            catch (error) {
-                this.logger.log("error", `[${requestId}] Plugin pipeline error: ${errorMessage(error)}`);
-                throw error;
+            else {
+                // Static data is one object shared by every request; plugins get
+                // their own copy so an in-place edit cannot leak into the next
+                // response (or back into the caller's object).
+                result =
+                    plugins.length > 0
+                        ? copyStaticData(match.route.generator)
+                        : match.route.generator;
             }
-            // Parse and prepare response
-            const response = normalizeResponse(parseResponse(result, matchedRoute.config), method);
-            await this.#finalizeMatchedRequest({
-                method,
-                path,
-                requestPath,
-                params,
-                reqQuery,
-                reqHeaders,
-                requestBody,
-                response,
-                routeDelay: matchedRoute.config.delay,
-                globalDelay,
-                record: true,
-                signal,
-                requestGeneration,
-                historyGeneration,
-                maxHistorySize,
-                requestId,
-                handleStart,
-            });
-            return response;
+            throwIfAborted(signal);
+            return { ...draft, result };
         }
         catch (error) {
             throwIfAborted(signal);
-            this.logger.log("error", `[${requestId}] Error processing request: ${errorMessage(error)}`, error);
-            // Return error response
-            const responseError = error instanceof Error ? error : new Error(errorMessage(error));
-            const errorResponse = markResponseException(normalizeResponse({
-                status: 500,
-                body: {
-                    error: responseError.message,
-                    code: error instanceof SchmockError ? error.code : "INTERNAL_ERROR",
-                },
-                headers: { "content-type": "application/json" },
-            }, method), responseError);
-            // A request that matched a route did happen: it is finalized exactly like
-            // a successful one — its own delay override, and a history record.
-            await this.#finalizeMatchedRequest({
-                method,
-                path,
-                requestPath,
-                params,
-                reqQuery,
-                reqHeaders,
-                requestBody,
-                response: errorResponse,
-                routeDelay: matchedRoute?.config.delay,
-                globalDelay,
-                record: matchedRoute !== undefined,
-                signal,
-                requestGeneration,
-                historyGeneration,
-                maxHistorySize,
-                requestId,
-                handleStart,
-            });
-            return errorResponse;
+            const recovery = await recoverGeneratorError(plugins, pluginContext, error, this.logger, signal);
+            throwIfAborted(signal);
+            return {
+                context: recovery.context,
+                result: recovery.response,
+                recovered: recovery.recoveredFromError === true,
+            };
         }
     }
     /**
-     * Finish a request that matched a route.
+     * Run the plugins' response processors (skipped after an error recovery)
+     * and turn the result into the normalized response.
+     */
+    async #runResponsePipeline(scope, match, draft) {
+        let result = draft.result;
+        try {
+            if (draft.recovered) {
+                this.logger.log("pipeline", "Skipping response processors after error recovery");
+            }
+            else {
+                const pipelineResult = await runPluginPipeline(scope.admission.plugins, draft.context, result, this.logger, scope.signal);
+                throwIfAborted(scope.signal);
+                result = pipelineResult.response;
+            }
+        }
+        catch (error) {
+            this.logger.log("error", `[${scope.requestId}] Plugin pipeline error: ${errorMessage(error)}`);
+            throw error;
+        }
+        return normalizeResponse(parseResponse(result, match.routeConfig), scope.method);
+    }
+    /**
+     * Answer a request that failed after `request:start` with a marked 500.
+     * Every such exit ends with exactly one `request:end`; a cancelled request
+     * reports 499 (client closed request) before its abort reason propagates.
+     */
+    async #answerFailedRequest(scope, error) {
+        this.#throwIfRequestAborted(scope);
+        this.logger.log("error", `[${scope.requestId}] Error processing request: ${errorMessage(error)}`, error);
+        const responseError = error instanceof Error ? error : new Error(errorMessage(error));
+        const errorResponse = markResponseException(buildJsonErrorResponse({
+            status: 500,
+            error: responseError.message,
+            code: error instanceof SchmockError ? error.code : "INTERNAL_ERROR",
+            method: scope.method,
+        }), responseError);
+        // A request that matched a route did happen: it is finalized exactly like
+        // a successful one — its own delay override, and a history record.
+        try {
+            await this.#finalizeMatchedRequest(scope, errorResponse);
+        }
+        catch (finalizeError) {
+            // Only the delay can reject here, and only with the abort reason.
+            this.#throwIfRequestAborted(scope);
+            throw finalizeError;
+        }
+        return errorResponse;
+    }
+    /**
+     * Finish a request after `request:start`, matched or failed.
      *
      * Order matters: delay first (an abort during it must escape before anything
      * is committed), then the history record, then `request:end`, then the logs.
      */
-    async #finalizeMatchedRequest(input) {
-        const { response, maxHistorySize } = input;
+    async #finalizeMatchedRequest(scope, response) {
+        const { admission, match, signal } = scope;
         // Apply delay (route-level overrides global)
-        await this.applyDelay(input.routeDelay, input.globalDelay, input.signal);
-        throwIfAborted(input.signal);
+        await applyResponseDelay({
+            routeDelay: match?.routeConfig.delay,
+            globalDelay: admission.globalDelay,
+            signal,
+        });
+        throwIfAborted(signal);
         // Record request in history (FIFO-bounded when maxHistorySize is set)
-        if (input.record &&
-            this.requestGeneration === input.requestGeneration &&
-            this.historyGeneration === input.historyGeneration &&
-            maxHistorySize !== 0) {
-            this.requestHistory.push({
-                method: input.method,
-                path: input.requestPath,
-                params: { ...input.params },
-                query: { ...input.reqQuery },
-                headers: { ...input.reqHeaders },
-                body: snapshotHistoryValue(input.requestBody),
-                timestamp: Date.now(),
-                response: {
-                    status: response.status,
-                    body: snapshotHistoryValue(response.body),
-                },
+        const historySnapshot = match?.historySnapshot;
+        if (match !== undefined &&
+            historySnapshot !== undefined &&
+            this.generations.isCurrent(admission.requestGeneration)) {
+            this.requestHistory.record({
+                generation: admission.historyGeneration,
+                method: scope.method,
+                path: match.requestPath,
+                params: match.historyParams,
+                snapshot: historySnapshot,
+                response,
             });
-            // The constructor already rejected a limit that is not a non-negative
-            // integer, so a plain comparison is enough here.
-            if (maxHistorySize !== undefined &&
-                this.requestHistory.length > maxHistorySize) {
-                this.requestHistory.splice(0, this.requestHistory.length - maxHistorySize);
-            }
         }
-        if (this.requestGeneration === input.requestGeneration) {
-            this.emit("request:end", {
-                method: input.method,
-                path: input.path,
+        if (this.generations.isCurrent(admission.requestGeneration)) {
+            this.events.emit("request:end", {
+                method: scope.method,
+                path: scope.path,
                 status: response.status,
-                duration: performance.now() - input.handleStart,
+                duration: performance.now() - scope.handleStart,
             });
         }
-        this.logger.log("response", `[${input.requestId}] Sending response ${response.status}`, {
+        this.logger.log("response", `[${scope.requestId}] Sending response ${response.status}`, {
             status: response.status,
-            headers: redactSensitiveHeaders(response.headers),
+            headers: redactHeaders(response.headers),
             bodyType: typeof response.body,
         });
-        this.logger.timeEnd(`request-${input.requestId}`);
+        this.logger.timeEnd(`request-${scope.requestId}`);
+    }
+    /**
+     * Rethrow a cancellation after reporting it as the request's terminal
+     * event, so a `request:start` listener always sees exactly one
+     * `request:end`. 499 is the de facto "client closed request" status.
+     */
+    #throwIfRequestAborted(scope) {
+        const { signal } = scope;
+        if (!signal?.aborted)
+            return;
+        if (this.generations.isCurrent(scope.admission.requestGeneration)) {
+            this.events.emit("request:end", {
+                method: scope.method,
+                path: scope.path,
+                status: ABORTED_REQUEST_STATUS,
+                duration: performance.now() - scope.handleStart,
+            });
+        }
+        throwIfAborted(signal);
+    }
+    /**
+     * The namespace as the path prefix request paths are compared with:
+     * percent-encoded, with a leading slash and without a trailing one, so
+     * `"/api/"` and `"/api"` behave identically (both serve `/api`, neither
+     * serves `/api//users`). `""` for a root namespace. Only the path of an
+     * origin-form namespace is used. Cached per namespace string instead of
+     * re-parsed per request.
+     */
+    #namespacePrefix(namespace) {
+        const cached = this.namespaceCache;
+        if (cached?.raw === namespace)
+            return cached.prefix;
+        const prefix = parsePathPrefix(namespace);
+        this.namespaceCache = { raw: namespace, prefix };
+        return prefix;
     }
     /**
      * Finish a request that matched no route — an unknown path or one outside the
      * configured namespace. Misses stay delay-free and out of history: nothing
      * ran, so there is nothing to record.
      */
-    #finalizeMiss(input) {
-        if (this.requestGeneration === input.requestGeneration) {
-            this.emit("request:notfound", {
-                method: input.method,
-                path: input.path,
-            });
-        }
-        const error = new RouteNotFoundError(input.method, input.path);
-        const response = markRouteNotFound(normalizeResponse({
+    #finalizeMiss(scope) {
+        const { method, path } = scope;
+        // Checked before each event: a listener may reset the mock in between.
+        if (this.generations.isCurrent(scope.admission.requestGeneration)) {
+            this.events.emit("request:notfound", { method, path });
+        }
+        const error = new RouteNotFoundError(method, path);
+        const response = markRouteNotFound(buildJsonErrorResponse({
             status: 404,
-            body: { error: error.message, code: error.code },
-            headers: { "content-type": "application/json" },
-        }, input.method));
-        if (this.requestGeneration === input.requestGeneration) {
-            this.emit("request:end", {
-                method: input.method,
-                path: input.path,
+            error: error.message,
+            code: error.code,
+            method,
+        }));
+        if (this.generations.isCurrent(scope.admission.requestGeneration)) {
+            this.events.emit("request:end", {
+                method,
+                path,
                 status: 404,
-                duration: performance.now() - input.handleStart,
+                duration: performance.now() - scope.handleStart,
             });
         }
-        this.logger.timeEnd(`request-${input.requestId}`);
+        this.logger.timeEnd(`request-${scope.requestId}`);
         return response;
     }
-    /**
-     * Apply configured response delay
-     * Supports both fixed delays and random delays within a range
-     * @private
-     */
-    async applyDelay(routeDelay, globalDelay, signal) {
-        const effectiveDelay = routeDelay ?? globalDelay;
-        if (!effectiveDelay) {
-            throwIfAborted(signal);
-            return;
-        }
-        const configuredMs = Array.isArray(effectiveDelay)
-            ? Math.random() * (effectiveDelay[1] - effectiveDelay[0]) +
-                effectiveDelay[0]
-            : effectiveDelay;
-        const ms = Math.max(0, configuredMs);
-        throwIfAborted(signal);
-        await new Promise((resolve, reject) => {
-            const finish = () => {
-                signal?.removeEventListener("abort", abort);
-                resolve();
-            };
-            const abort = () => {
-                clearTimeout(timer);
-                try {
-                    throwIfAborted(signal);
-                }
-                catch (error) {
-                    reject(error);
-                }
-            };
-            const timer = setTimeout(finish, ms);
-            signal?.addEventListener("abort", abort, { once: true });
-        });
-    }
 }