express-fastify-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 express-fastify-runtime contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,326 @@
+# express-fastify-runtime
+
+> Your Express app. Fastify's speed. One line. No rewrite.
+
+```ts
+import { fast } from "express-fastify-runtime";
+import express from "express";
+
+const app = express();
+app.get("/", (req, res) => res.json({ hello: "world" }));
+
+fast(app).listen({ port: 3000 });   // 👈 that's the whole trick
+```
+
+---
+
+## A short, slightly emotional story
+
+I love Express. I love it the way you love a comfortable pair of shoes — `req`, `res`,
+`next`, a thousand middlewares on npm, and muscle memory built over years. Express is *home*.
+
+Then one day someone showed me a Fastify benchmark and my coffee went cold. "Two-ish times the
+throughput," they said, smiling like they'd discovered fire. And I thought: do I really have to
+abandon my comfortable shoes and rewrite everything in a new framework just to go faster?
+
+So I went looking for a shortcut. I found tools that "run Express on Fastify" — and many of them
+do *exactly* one thing: they hand your Express app to Fastify and let Fastify… call Express for
+every request. Your app technically runs "on Fastify." It is not one bit faster. It's a very
+polite handshake between two frameworks where nothing actually changes. Cool sticker, no engine.
+
+**`express-fastify-runtime` is the engine.** It doesn't just *expose* your Express app to
+Fastify — it **compiles** your safe routes and middleware onto Fastify's real request pipeline,
+and only falls back to actual Express for the things that genuinely need it (multipart uploads,
+`res.render`, streaming bodies, anything unusual). You keep writing Express. It actually gets
+fast.
+
+You don't rewrite a thing. You wrap one line. Your shoes stay on.
+
+---
+
+## What you get
+
+- **It's still Express.** `app.use`, `app.get`, `req`, `res`, `next`, your middleware, your
+  routers, your error handlers. Nothing to relearn. **Express 4 and 5 both welcome.**
+- **It's actually fast.** Safe routes run compiled on Fastify — faster than plain Express across
+  the board, and matching or beating Fastify on middleware-heavy and small-payload workloads
+  (see [Benchmarks](#benchmarks)).
+- **Nothing breaks.** Anything that can't safely run on Fastify is transparently handled by a
+  real embedded `express()` instance. No silent behavior changes; morgan logs, helmet headers,
+  auth, cookies, JSON parsing, streaming/SSE, and error middleware all behave like Express.
+- **It's a real Fastify instance.** `fast(app)` returns a `FastifyInstance`, so Fastify fans get
+  their plugins, hooks, and the raw Node server for WebSockets/Socket.IO.
+
+---
+
+## Install
+
+```bash
+npm install express-fastify-runtime
+```
+
+`express` is a **peer dependency** — bring your own (`^4.18` or `^5`). `fast()` uses whatever
+Express you already have.
+
+> **One rule:** import `express-fastify-runtime` **before** you create your Express app or any
+> `express.Router()`. It patches the router layer at load time so middleware mounted with a path
+> (`app.use('/api', mw)`, `router.use('/x', mw)`) can be compiled onto the Fastify lane. Import it
+> late and those bits still work — they just fall back to the (slower) Express lane.
+
+---
+
+## For Express fans — wrap what you already have
+
+You wrote a normal Express app. Wrap it. Done.
+
+```ts
+import "express-fastify-runtime";        // load first (the one rule)
+import express from "express";
+import morgan from "morgan";
+import helmet from "helmet";
+import { fast } from "express-fastify-runtime";
+
+const app = express();
+app.use(morgan("tiny"));                 // logs, correctly, per request
+app.use(helmet());                       // security headers, intact
+app.use(express.json());                 // parsed by Fastify's fast parser under the hood
+
+app.get("/users/:id", (req, res) => {
+  res.json({ id: req.params.id });
+});
+
+app.use((err, req, res, next) => {       // your error middleware still works
+  res.status(500).json({ error: err.message });
+});
+
+const fastApp = fast(app);               // returns a Fastify instance
+fastApp.listen({ port: 3000 });
+```
+
+Routers, controllers, `req.body`, `req.query`, `req.params`, `res.status().json()`,
+`res.redirect()`, `res.cookie()`, async handlers, `next(err)` — all the Express you already
+write. No changes.
+
+## For Fastify fans — it's a real Fastify instance
+
+`fast(app)` hands you back a genuine `FastifyInstance`. Add plugins, register hooks, use the
+Fastify ecosystem — your Express routes just ride along on the Fastify lane.
+
+```ts
+import "express-fastify-runtime";
+import express from "express";
+import rateLimit from "@fastify/rate-limit";
+import { fast } from "express-fastify-runtime";
+
+const app = express();
+app.get("/", (req, res) => res.json({ ok: true }));
+
+const fastApp = fast(app, { fastify: { logger: true } });   // pass Fastify options through
+await fastApp.register(rateLimit, { max: 100 });            // real Fastify plugins
+await fastApp.ready();                                       // let plugins load before listen
+await fastApp.listen({ port: 3000 });
+```
+
+## Plain Node `http`
+
+`fastApp.server` is the real Node HTTP server, and `server.listen(...)` is wired to run
+Fastify's full lifecycle (so 404s and internals work):
+
+```ts
+const fastApp = fast(app);
+const server = fastApp.server;            // http.Server
+server.listen(3000, () => console.log("up on 3000"));
+```
+
+## Socket.IO / WebSockets
+
+Because you can reach the underlying HTTP server, real-time works exactly like it does in any
+Node app — attach your socket server to `fastApp.server`:
+
+```ts
+import { Server as IOServer } from "socket.io";
+
+const fastApp = fast(app);
+const io = new IOServer(fastApp.server);  // share the same HTTP server
+io.on("connection", (socket) => socket.emit("hello", "from express-fastify-runtime"));
+
+fastApp.server.listen(3000);
+```
+
+The same pattern works for `ws`, `@fastify/websocket`, or anything that takes an
+`http.Server`.
+
+## Controlling which lane a route runs on
+
+Every request runs on one of two lanes ([how it works](#how-it-works-30-seconds)):
+
+- **Fastify lane (default, fast)** — safe routes and middleware are compiled onto Fastify
+  automatically. You don't annotate anything for the common case.
+- **Express lane (real Express)** — anything unsafe (multipart/uploads, `res.render`, `res.sendFile`,
+  stream-piping middleware) is detected and transparently handled by the embedded real Express app.
+
+When detection can't be sure, it already errs toward the Express lane. The two helpers below let you
+**force the Express lane** for a specific route when you want Express-only behavior guaranteed
+(e.g. a view engine) without relying on detection.
+
+### `expressLane(fn)` — force the Express lane (works anywhere)
+
+Wrap the handler/middleware. Works with plain functions and arrow functions:
+
+```ts
+import { expressLane } from "express-fastify-runtime";
+
+app.get("/page", expressLane((req, res) => res.render("index", { title: "Hi" })));
+```
+
+### `@ExpressLane` — decorator form (class-method controllers)
+
+Requires `"experimentalDecorators": true` in your `tsconfig.json`. The Express-lane marker lives on
+the decorated method itself — register that method **directly** as the handler; don't `.bind()` it
+or wrap it in an arrow first (that creates a new function and drops the marker — use `expressLane()`
+for those cases).
+
+```ts
+import { ExpressLane } from "express-fastify-runtime";
+
+class PageController {
+  @ExpressLane
+  page(req, res) {
+    res.render("index", { title: "Hi" });
+  }
+}
+
+const pages = new PageController();
+app.get("/page", pages.page); // the decorated method carries the Express-lane marker
+```
+
+Everything else stays on the fast lane.
+
+---
+
+## How it works (30 seconds)
+
+```
+            your Express app (unchanged)
+                      │  compiled once, at startup
+        ┌─────────────┴──────────────┐
+        ▼                            ▼
+  Fastify lane                 Embedded Express lane
+  (safe routes & middleware    (real express() instance —
+   compiled onto Fastify)       uploads, res.render, streams…)
+```
+
+A request is matched by Fastify. If it's a compiled (safe) route, it runs on Fastify's pipeline
+with a thin Express-compatible `req`/`res`. If it isn't, Fastify hands the raw request to the
+embedded real Express app. **When in doubt, it uses real Express** — it never guesses and
+silently changes behavior.
+
+Lane classification, body parsing (`express.json()` → Fastify's parser), router flattening, and
+error-handler wiring all happen **once at startup**. There's no per-request framework juggling.
+
+---
+
+## Benchmarks
+
+Numbers are req/s, **median of repeated runs with warmup** (single-shot HTTP benchmarks swing
+20–30%, so don't trust one sample — including ours; reproduce with `npm run benchmark:table`).
+10 connections, Node on an Apple-silicon laptop. Higher is better.
+
+| Scenario | Express | Fastify | **fast()** | fast/Express | fast/Fastify |
+|---|--:|--:|--:|--:|--:|
+| Plain JSON route (5 middleware) | 39,976 | 68,112 | **50,552** | **1.26×** | 0.74× |
+| JSON DB read | 41,848 | 68,624 | **50,584** | **1.21×** | 0.74× |
+| Middleware stack (helmet+morgan+json+custom) | 29,424 | 32,736 | **40,184** | **1.37×** | **1.23×** |
+| POST 1KB JSON | 33,018 | 46,752 | **46,696** | **1.41×** | **1.00×** |
+| Auth (JWT verify) | 17,636 | 33,976 | **19,360** | **1.10×** | 0.57× |
+
+**Reading the table:**
+
+- `fast()` is **faster than plain Express** across the board — same code, more throughput.
+- It **matches or beats Fastify** on middleware-heavy and small-payload workloads.
+- On a tight pure-JSON hot path it trails raw Fastify a little — that's the unavoidable cost of
+  presenting a real Express `req`/`res`, and it's still well ahead of Express.
+- **Auth (JWT):** the gap there isn't the adapter — it's the *library*. Fastify's benchmark uses
+  `@fastify/jwt` (built on `fast-jwt`), which is simply faster than `jsonwebtoken`. Want that
+  speed in your Express app? Use `fast-jwt` directly in your auth middleware — it's
+  framework-agnostic.
+- **Uploads** (multipart) run on the Express lane by design (multer), so Fastify's native
+  `@fastify/multipart` wins there — expected, not a regression.
+
+Run them yourself:
+
+```bash
+npm run benchmark:table          # the table above (warmup + median)
+npm run benchmark:fast-vs-fastify   # fast() vs plain Fastify, MW=0 and MW=5
+npm run benchmark                 # full suite: express / fastify / node-http / runtime
+```
+
+---
+
+## Compatibility & guarantees
+
+- **Express 4 → 5 upward.** Legacy apps and modern apps. The goal is that adding `fast()`
+  changes your throughput, not your behavior.
+- **Concurrency-safe.** Every in-flight request gets its own `req`/`res` — heavily tested under
+  concurrent async load (no cross-talk, correct morgan logs per request).
+- **Supported:** `app.use` / `app.METHOD` / `app.all`, `express.Router()` (flattened when safe),
+  `req.body|query|params|headers|cookies`, `res.status|json|send|sendStatus|set|get|redirect|cookie|type|end`,
+  streaming via `res.write`/`res.end`, async handlers, global `(err, req, res, next)` error
+  middleware, `express.json()`/`urlencoded`.
+- **Express lane (real Express):** multipart/uploads, `res.render` + view engines,
+  `res.sendFile`, stream-based middleware, RegExp route paths — or anything you mark with
+  `expressLane()`.
+
+**Middleware semantics:** the chain is continuation-based, exactly like Express's router —
+`next()` advances the chain however it's called: synchronously, from an `async/await` handler,
+or from a detached callback / `setTimeout` / promise (classic callback-style middleware). A
+middleware that ends the response without calling `next()` stops the chain. The only thing that
+"hangs" is a handler that never calls `next()` and never responds — which hangs in real Express
+too.
+
+---
+
+## Contributing
+
+PRs welcome — the bar is "it stays Express-correct **and** fast."
+
+```bash
+npm install
+npm run build         # tsc → dist (CommonJS)
+npm test              # unit + integration (incl. concurrency / parity / error-handling)
+npm run benchmark:table
+```
+
+Rules of the road:
+
+1. **Correctness beats speed, always.** Adding `fast()` must never change Express behavior. If a
+   perf idea risks that, it doesn't ship.
+2. **No shared per-request state.** Each request gets its own `req`/`res`. Never reintroduce a
+   single mutated adapter object — it corrupts concurrent async requests. Validate every
+   perf change with concurrent **async** handlers (`test/integration/concurrency.test.js`).
+3. **Imports are CommonJS, no file extensions** (matches the current `tsconfig`).
+4. **Add a test** for any behavior you touch; keep the full suite green (`npm test`).
+5. **Measure with `npm run benchmark:table`** (warmup + median), not single-shot runs.
+6. Update `docs/` and `changelog/log-YYYY-MM-DD.md` for notable changes.
+
+See `docs/` for deeper notes: `SPEC.md`, `HOW_EXPRESS_LANE_WORKS.md`,
+`FAST_PRODUCTION_CHECKLIST.md`, `OPTIMIZATION.md`, `EXPRESS_FEATURES.md`.
+
+## Reporting issues
+
+Found a bug or have a feature request? Open an issue on
+**[GitHub Issues](https://github.com/John-Daniels/express-fastify-runtime/issues)**.
+
+To help us reproduce quickly, please include:
+
+- **Versions** — `express-fastify-runtime`, `express` (4 or 5), `fastify`, and Node.
+- **Lane** — run `fast(app, { experimental: { diagnostics: true } })` and note whether the failing
+  request logs `Fastify lane` or `Express lane`.
+- **A minimal repro** — the smallest app/route that triggers it, plus the full error stack (not just
+  the message) and the request (method, path, content-type, body).
+
+Security issue? Please report it privately to the maintainer rather than opening a public issue.
+
+## License
+
+MIT

package/changelog/README.md

@@ -0,0 +1,5 @@
+# Changelog
+
+One log file per day worked on the project. Format: `log-YYYY-MM-DD.md` (human and AI friendly).
+
+- **log-YYYY-MM-DD.md** — Short bullet list of changes that day.

package/changelog/log-2025-02-07.md

@@ -0,0 +1,10 @@
+# 2025-02-07
+
+- Dev fallback logger: warn when Router falls back to Express lane (middleware/RegExp path). `createApp({ dev: true })` or `NODE_ENV !== 'production'`.
+- Changelog folder: `changelog/log-YYYY-MM-DD.md` per day.
+- NPM publish prep: repository, license, keywords, files in package.json.
+- compile.ts: kept current version (nextCalled for error/flow clarity); removed compile.old.ts.
+- EXPRESS_FEATURES.md: added Fallback behavior section, createApp(options), clarified supported vs not yet.
+- docs/EDGE_CASES.md: added edge-case checklist (Tier 1–3, production guarantees, benchmark ideas).
+- **fast(app, ops):** New API to compile an existing Express app onto Fastify. Introspects `app.router.stack`, classifies and registers safe routes on Fastify, mounts Express for fallback. Returns real Fastify instance. Requires loading express-fastify-runtime before creating the app (for Layer _path). See `src/runtime/fast.ts`, `src/app/introspectExpress.ts`.
+- **Benchmark notes:** Documented in benchmarks/README.md why Fastify wins on uploads (multer vs native multipart) and auth (native JWT plugin vs userland); payloads and CRUD are within target.

package/changelog/log-2026-06-25.md

@@ -0,0 +1,151 @@
+# 2026-06-25
+
+## Publish prep
+
+- **Fastify upgraded to 5.8.5** (latest; includes the recent security/CVE fixes). Dependency floor
+  raised to `^5.8.5`. We use only stable Fastify-5 APIs and the one 5.x behavior change (stricter
+  RFC-9110 content-type parsing, 5.7.2) predates our prior 5.7.4 — full test suite stays green on
+  **Express 4 and 5** after the bump.
+- **Single self-discovering test command**: `npm test` now runs `node --test test/*/*.test.js`
+  (shell-expanded; works on every Node version) instead of a hand-maintained file list; added
+  `test:compat`. New `test/<category>/*.test.js` files are picked up automatically.
+- **Packaging**: added `publishConfig.access = "public"`; verified `npm pack` (64 kB, dist + README
+  + LICENSE + changelog) consumes cleanly from CJS (`require`) and ESM (`import`), Express not
+  bundled (peer dep). `npm publish` is run by the maintainer (`npm login` required).
+
+## Fix: APM-instrumented apps (Sentry/OpenTelemetry), string ports, wrapped body parsers
+
+Found while running a real Express 4 app (Sentry + helmet + morgan + hpp) through `fast()`:
+
+- **`server.listen(process.env.PORT, cb)` bound a random port.** `process.env.PORT` is a string;
+  our wrapper coerced non-numbers to 0 (OS-assigned), so the server logged the intended port but
+  was unreachable. `runtime/fast.ts` now coerces string ports (and `{ port: "3000" }`) like
+  Node/Express.
+- **Helmet crashed with "Cannot set properties of undefined (setting 'content-security-policy')".**
+  Sentry's OpenTelemetry instrumentation wraps Express handlers, so Express 4's `expressInit` (which
+  reassigns req/res prototypes) had `handle.name === "patched"` and slipped past our skip — it ran
+  on the Fastify lane and broke the response object. We now skip `query`/`expressInit` by
+  **`layer.name`** (Express preserves it through APM wrapping), in `app/flattenRouter.ts`.
+- **`express.json()` crashed with "argument stream must be a stream" on POST routes.** The wrapped
+  `jsonParser` wasn't recognized (so it wasn't mapped to Fastify's parser) and tried to read the
+  already-consumed request stream. We now identify `express.json` by `layer.name` and replace it
+  with a no-op on the Fastify lane (Fastify provides `req.body`); `utils/detect.ts` and
+  `express/middleware.ts` also unwrap APM wrappers (`__original`) as a secondary safety. New
+  `test/integration/instrumentation.test.js` simulates the wrapping.
+- `express.urlencoded()`/`raw()`/`text()` continue to route to the Express lane (Fastify has no
+  parser for them); `express.json()` stays fast on Fastify. Verified end-to-end against the real
+  Express 4 app: `GET /`, `POST /v1/user/login` (JSON), and a duplicate urlencoded webhook route
+  all work, no crashes.
+
+## Fix: repeated route registrations + stream body parsers
+
+- **"Method 'POST' already declared" crash fixed.** Declaring the same method+path more than once
+  is valid Express (`router.post('/x', parser); router.post('/x', handler)` — the layers chain via
+  `next()`), but Fastify forbids duplicate method+path, so we crashed at startup. `compile.ts` now
+  counts route entries per concrete method+path (across both lanes, expanding `all`) and registers
+  a method on the Fastify lane only when it's declared exactly once; any method+path declared >1
+  time (incl. `all`+method overlaps, or a same-path Express-lane entry) defers entirely to the real
+  embedded Express app, which runs every layer in order. Single-route hot path unchanged.
+- **Stream body parsers routed to the Express lane.** `detect.ts` now treats `express.urlencoded`
+  (`urlencodedParser`), `express.raw` (`rawParser`), and `express.text` (`textParser`) as
+  Express-required — they consume the raw request stream, which Fastify has already drained and has
+  no parser for, so `req.body` would be empty on the Fastify lane. (`express.json` is unchanged: it
+  stays mapped to Fastify's native JSON parser.) Fixes both the duplicate case and a single inline
+  `app.post('/x', express.urlencoded(...), handler)`.
+- New `test/integration/duplicate-routes.test.js` (incl. the exact reported WhatsApp pattern);
+  verified against a real Express 4 consumer: no crash, 200, body parsed.
+
+## Production-readiness pass (npm-ready, Express 4→5, freaking fast)
+
+- **`fast()` no longer couples its types to a specific `@types/express`.** Its parameter is now a
+  structural `ExpressApp` type (a request-handler function with Express's methods), exported from
+  the package, instead of `Application` from `@types/express`. A host project on Express 4 (or any
+  @types/express version that differs from the one this package was built with) previously got
+  `TS2345: 'Express' is not assignable to 'Application'` (PathParams/RegExp vs string). Verified:
+  `fast(express())` type-checks under a real Express-4 (`@types/express@4`) consumer.
+
+- **Express 4 support.** `fast()` previously crashed on Express 4 (its `app.router` getter
+  throws; the router is `app._router`) and Express 4 injects `query`/`expressInit` middleware
+  into the app router stack — `expressInit` reassigns `req`/`res` prototypes and broke our
+  adapter. Fixes: `introspectExpress.ts` reads `app._router` first (guarded), `patchRouterLayer.ts`
+  also patches Express 4's bundled `express/lib/router/layer`, and `flattenRouter.ts` skips the
+  `query`/`expressInit` built-ins. **The full test suite passes under Express 4.22 and Express 5.2.**
+- **`express` is now a peerDependency** (`^4.18 || ^5`) instead of a hard dependency — consumers
+  bring their own Express; nothing is bundled/forced.
+- **Error handling parity.** Un-skipped the Fastify-lane error test; `next(err)`/throw/async
+  rejection reach Express 4-arg error middleware on both `fast()` and `createApp()`
+  (`createApp` now wires `setErrorHandler`). 4-arg error middleware is excluded from the normal
+  chain. New `test/integration/error-handling.test.js`.
+- **Streaming / SSE.** Added `res.write`/`res.writeHead`/`res.flushHeaders` (and hijack-aware
+  `res.end`) to the response adapter via `reply.hijack()`, so streaming and Server-Sent Events
+  work on the Fastify lane. Covered (incl. under concurrency) in new
+  `test/integration/parity.test.js` alongside redirect, send variants, 204, 404 fall-through,
+  and 1MB echo.
+- **npm packaging:** added an `exports` map (types/require/import); verified `npm pack` consumes
+  cleanly from both CJS (`require`) and ESM (`import`) apps, with Express not bundled.
+- **Benchmarks:** new `benchmark:table` (warmup + interleaved median, Markdown output). Median
+  numbers: fast() is ~1.2–1.5× plain Express across the board and ~1.1–1.3× Fastify on
+  middleware-heavy / small-payload workloads; ~0.7× Fastify on a pure-JSON hot path (the cost of
+  a real Express req/res). README rewritten (story-driven) with the table and Socket.IO/http/
+  Fastify-plugin examples.
+- **Continuation-based middleware chain (correctness, kept fast).** Replaced the
+  "advance synchronously or await the returned promise" runner with a continuation runner that
+  matches Express's router: `next()` advances the chain however it's called — sync, `async/await`,
+  or a **detached callback / setTimeout / microtask** (classic callback-style middleware, e.g.
+  `db.query(..., () => next())`). Previously such middleware silently broke the chain on the fast
+  lane. A handler that ends the response without `next()` stops the chain; errors (sync throw,
+  `next(err)`, async rejection) reach Fastify's error handler. The runner is **sync-first** — it
+  returns synchronously (no Promise) when the chain settles synchronously, and the single
+  no-`next` handler hot path bypasses it entirely — so the benchmarks held (fast() stays
+  ~1.1–1.4× Express on every scenario and ≥1.0× Fastify on middleware-stack and payloads). New
+  `test/integration/middleware-chain.test.js`. This removes the previously-documented
+  "detached next()" limitation.
+- **CI:** GitHub Actions matrix (Node 18/20/22 × Express 4/5) + benchmark smoke.
+- **Deferred (deliberately):** decorating Fastify's own `request`/`reply` for pure-JSON parity —
+  it would override Fastify's reply API (`send`/`type`/`header`/`status`/`code`/`getHeader`) with
+  Express semantics and break Fastify internals. Correctness ("nothing breaks") outranks that
+  win; the safe separate-`res` design stays. Tracked in `docs/PLAN_FASTIFY_CLOSER.md`.
+
+## Correctness (release blocker fixed)
+
+- **Per-request state isolation in the Fastify lane.** The previous adapter reused ONE `req`
+  and ONE `res` object app-wide (`createRequestAdapter`/`createResponseAdapter`). That only
+  held for synchronous handlers; under concurrent **async** handlers (or morgan's deferred
+  finish listener) later requests overwrote earlier ones. Repro: 29/30 concurrent async
+  `GET /echo/:id` returned empty/scrambled bodies. Fixed with a shared method prototype + a
+  small per-request instance (`Object.create`). `src/fastify/adapters/{request,response}.ts`.
+- **Morgan logs now correct under concurrency.** Lifecycle events (finish/end/close) are
+  delegated to the real `reply.raw` response, so morgan/on-finished fire on the actual
+  response finish (status, headers, `res._startAt` all set). Removed the synthetic
+  double-`setImmediate` finish emit that raced under load and produced "- - ms - -".
+- New regression tests: `test/integration/concurrency.test.js` (async echo, distinct
+  status/headers/body, res.locals isolation, morgan under concurrent load) and
+  `test/integration/middleware-parity.test.js` (auth `req.user` isolation, helmet,
+  express.json, cookies). Wired into `npm test`.
+
+## Performance (Fastify lane)
+
+- compile.ts: one `next()` per chain (not per handler); `baseUrl` precomputed at registration;
+  zero-middleware routes folded into a single Fastify handler (no preHandler stage); handler
+  returns the user handler's promise directly (no extra async frame). `res.locals` is lazy.
+- Removed the per-request `reply.raw.writeHead` morgan patch; `res._startAt` is recorded in
+  `res.json/send` instead.
+- `benchmarks/fast-vs-fastify/run.js`: warmup + interleaved median over N rounds (env `ROUNDS`,
+  `WARMUP`) for trustworthy numbers.
+- Baseline after fixes: fast() ≈ 0.72× Fastify (MW=0 and MW=5), stable; fast() **beats** plain
+  Express on most scenarios and **beats** Fastify on middleware-stack. CPU profile shows ~84%
+  of time in Node's C++ HTTP layer and our own JS <1% — remaining gap is per-request Express
+  req/res allocation over Fastify. Auth gap vs Fastify is the JWT library (jsonwebtoken vs
+  @fastify/jwt), not the adapter (fast() ≈ Express there).
+
+## Next step (documented, not yet done)
+
+- Path to ~parity: decorate Fastify's own `request`/`reply` (`decorateRequest`/`decorateReply`)
+  so no extra per-request objects are allocated. See `docs/PLAN_FASTIFY_CLOSER.md` status note.
+
+## Known limitation — RESOLVED
+
+- The previously-noted "detached `next()` skips subsequent middleware" limitation is **fixed** by
+  the continuation-based middleware chain (see above). All middleware styles now behave as in
+  Express. The only thing that hangs is a handler that never calls `next()` and never responds —
+  which hangs in real Express too.

package/dist/app/ExpressLikeApp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Express-like app stub: app.use, app.get, app.listen.
+ * Routes are immutable after listen(). Full Router handling is in lifecycle.ts.
+ */
+import type { ExpressLikeApp as IExpressLikeApp } from '../types/internal';
+export declare function createExpressLikeApp(routeStore: import('./RouteStore').RouteStore, locked: {
+    current: boolean;
+}): IExpressLikeApp;
+//# sourceMappingURL=ExpressLikeApp.d.ts.map

package/dist/app/ExpressLikeApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressLikeApp.d.ts","sourceRoot":"","sources":["../../src/app/ExpressLikeApp.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,cAAc,IAAI,eAAe,EAA0B,MAAM,mBAAmB,CAAC;AAGnG,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,OAAO,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,mBAqE/G"}

package/dist/app/ExpressLikeApp.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Express-like app stub: app.use, app.get, app.listen.
+ * Routes are immutable after listen(). Full Router handling is in lifecycle.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createExpressLikeApp = createExpressLikeApp;
+const assert_1 = require("../utils/assert");
+function createExpressLikeApp(routeStore, locked) {
+    const app = {
+        use(pathOrHandler, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            const path = typeof pathOrHandler === 'string' ? pathOrHandler : '/';
+            const allHandlers = typeof pathOrHandler === 'string' ? handlers : [pathOrHandler, ...handlers];
+            routeStore.addMiddleware(path, ...allHandlers);
+            return app;
+        },
+        get(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('get', path, ...handlers);
+            return app;
+        },
+        post(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('post', path, ...handlers);
+            return app;
+        },
+        put(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('put', path, ...handlers);
+            return app;
+        },
+        patch(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('patch', path, ...handlers);
+            return app;
+        },
+        delete(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('delete', path, ...handlers);
+            return app;
+        },
+        head(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('head', path, ...handlers);
+            return app;
+        },
+        options(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('options', path, ...handlers);
+            return app;
+        },
+        all(path, ...handlers) {
+            (0, assert_1.assertNotLocked)(locked.current);
+            routeStore.addRoute('all', path, ...handlers);
+            return app;
+        },
+        listen(_port, _host, _callback) {
+            throw new Error('Use createApp() from the main entry; listen() is implemented there.');
+        },
+    };
+    return app;
+}
+//# sourceMappingURL=ExpressLikeApp.js.map

package/dist/app/ExpressLikeApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExpressLikeApp.js","sourceRoot":"","sources":["../../src/app/ExpressLikeApp.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAMH,oDAqEC;AAvED,4CAAkD;AAElD,SAAgB,oBAAoB,CAAC,UAA6C,EAAE,MAA4B;IAC9G,MAAM,GAAG,GAAoB;QAC3B,GAAG,CAAC,aAAkC,EAAE,GAAG,QAAsB;YAC/D,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,MAAM,IAAI,GAAG,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC;YACrE,MAAM,WAAW,GACf,OAAO,aAAa,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,aAAa,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC9E,UAAU,CAAC,aAAa,CAAC,IAAI,EAAE,GAAI,WAAgC,CAAC,CAAC;YACrE,OAAO,GAAG,CAAC;QACb,CAAC;QAED,GAAG,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC7C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC9C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC9C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC/C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,GAAG,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC7C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC9C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,KAAK,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC/C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAChD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,MAAM,CAAC,IAAY,EAAE,GAAG,QAA0B;YAChD,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YACjD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC9C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC/C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,OAAO,CAAC,IAAY,EAAE,GAAG,QAA0B;YACjD,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAClD,OAAO,GAAG,CAAC;QACb,CAAC;QAED,GAAG,CAAC,IAAY,EAAE,GAAG,QAA0B;YAC7C,IAAA,wBAAe,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAChC,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,CAAC;YAC9C,OAAO,GAAG,CAAC;QACb,CAAC;QAED,MAAM,CACJ,KAAwC,EACxC,KAAwC,EACxC,SAAiC;YAEjC,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAC;QACzF,CAAC;KACF,CAAC;IAEF,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/app/RouteStore.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Stores routes and middleware before compile. Immutable after listen().
+ */
+import type { RouteEntry } from '../types/internal';
+import type { ExpressHandler } from '../types/express';
+export declare class RouteStore {
+    private entries;
+    addMiddleware(path: string, ...handlers: ExpressHandler[]): void;
+    addRoute(method: string, path: string, ...handlers: ExpressHandler[]): void;
+    /** Add a single entry (used when flattening Router). */
+    addEntry(entry: RouteEntry): void;
+    /** Add multiple entries (used when flattening Router). */
+    addEntries(entries: readonly RouteEntry[]): void;
+    getAll(): readonly RouteEntry[];
+    clear(): void;
+}
+//# sourceMappingURL=RouteStore.d.ts.map

package/dist/app/RouteStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteStore.d.ts","sourceRoot":"","sources":["../../src/app/RouteStore.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGvD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAoB;IAEnC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,GAAG,IAAI;IAIhE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,cAAc,EAAE,GAAG,IAAI;IAQ3E,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAQjC,0DAA0D;IAC1D,UAAU,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI;IAMhD,MAAM,IAAI,SAAS,UAAU,EAAE;IAI/B,KAAK,IAAI,IAAI;CAGd"}