feat: introduce ecosystem interoperability layer with Express compatibility

## Feature request

Introduce a **NextRush Interop** architecture that allows applications to reuse mature external Node.js ecosystem packages without requiring NextRush to reimplement every framework-bound capability.

The first concrete implementation should be an **Express compatibility bridge**, but the long-term design should be capability/contract-oriented rather than tightly coupling NextRush to any specific external framework.

## Motivation

NextRush already has a growing first-party ecosystem with 30+ packages. That ecosystem should remain the preferred path for functionality that benefits from deep NextRush integration.

However, Express, NestJS, and the broader Node.js ecosystem have accumulated years of production packages covering middleware, security, parsing, authentication, uploads, sessions, logging, and many other concerns.

As a newer framework, rebuilding every mature package ourselves is neither practical nor a good use of limited engineering time.

The goal is therefore **ecosystem leverage**:

> Build what differentiates NextRush. Integrate what the ecosystem already does well. Bridge framework-bound capabilities when it is technically sound.

This should reduce adoption friction and allow users to choose NextRush without feeling blocked by ecosystem maturity.

## Proposed architecture

### 1. Keep NextRush core completely framework-independent

The NextRush core, router, runtime, and first-party packages should not depend on Express, NestJS, or any compatibility implementation.

Dependency direction should remain:

```text
@nextrush/core
↑
│
@nextrush/express-bridge
│
▼
Express middleware ecosystem
```

The bridge depends on NextRush; NextRush does not depend on the bridge.

### 2. Introduce a small interoperability foundation

Explore a reusable internal/public compatibility foundation around stable concerns such as:

- request adaptation
- response adaptation
- middleware lifecycle
- `next()` continuation
- error propagation
- shared request state
- capability detection

This should be a small kernel, not a universal framework emulator.

### 3. First implementation: Express bridge

Create a dedicated package such as:

- `@nextrush/express-bridge`

Proposed DX:

```ts
import { compat } from "@nextrush/express-bridge";
import cors from "cors";
import helmet from "helmet";

app.use(compat(cors()));
app.use(compat(helmet()));
```

The bridge should make supported Express/Connect-style middleware feel like a normal NextRush middleware while keeping translation logic isolated.

## Compatibility scope

Do **not** promise full Express compatibility initially.

Establish explicit compatibility levels, for example:

- Full: supported semantics and tested behavior
- Partial: supported with documented limitations
- Unsupported: package depends on Express internals or semantics that should not be emulated

Initial target categories should focus on middleware and libraries that primarily depend on the `req` / `res` / `next` execution contract.

Potential early candidates include:

- CORS
- security headers
- logging/request logging
- cookies
- compression
- simple request/response middleware
- multipart/file-upload middleware where feasible

More deeply Express-coupled features such as full `express.Router`, Express session internals, view engines, or packages depending on private Express behavior should not be forced into the first version.

## Important distinction: compatibility vs integration

This feature should not become a generic mechanism for wrapping every Node.js package.

Use the following strategy:

```text
Need capability
│
├── Native NextRush package exists
│ └── Prefer native implementation
│
├── Framework-bound external contract
│ └── Compatibility adapter
│
├── Protocol / infrastructure ecosystem
│ └── Dedicated NextRush integration
│
└── Framework-neutral library
└── Use directly
```

Examples:

- Express middleware → compatibility
- RabbitMQ/Kafka/NATS/gRPC → integration/wrapper around proven ecosystem tooling
- Prisma/Drizzle/Zod/Pino/OpenTelemetry → direct usage or targeted NextRush integration
- NestJS guards/interceptors/modules/DI → do not emulate as Express middleware

## NestJS considerations

NextRush already supports a class-based programming model, so a separate `@nextrush/nest-bridge` should **not** be created as part of the initial implementation merely to support Nest-style middleware.

NestJS middleware that uses the standard Express-style `req`, `res`, `next` contract may potentially work through the Express compatibility path.

NestJS-specific abstractions such as:

- Guards
- Interceptors
- Pipes
- Filters
- Modules
- Nest dependency injection/runtime semantics
- `ExecutionContext`

should not be emulated without a separate, concrete use case and architectural proposal.

## API / DX principles

The compatibility feature should preserve the original external package API wherever possible.

Good:

```ts
app.use(compat(cors({ origin: "https://example.com" })));
```

Avoid introducing unnecessary NextRush-specific configuration wrappers around the external library.

The bridge should also provide clear development-time errors when unsupported Express APIs are used rather than failing deep inside adapter code with opaque errors.

## Performance requirements

Compatibility must be isolated from the native path.

- Native NextRush middleware must not pay compatibility overhead when the bridge is not used.
- The bridge should minimize unnecessary object cloning and allocations.
- Prefer lazy/proxy-based adaptation where correct and maintainable.
- Benchmark native NextRush vs bridged middleware vs native Express for representative workloads.

Compatibility does not need to beat native NextRush performance, but it must be predictable and measured.

## Testing / compatibility registry

Create a dedicated compatibility test harness and maintain a living matrix for supported packages.

Example:

| Package | Status | Notes |
| --- | --- | --- |
| `cors` | Full | Request/response headers |
| `helmet` | Full | Header middleware |
| `morgan` | Full | Request logging |
| `cookie-parser` | Full | Request cookie parsing |
| `multer` | Partial | Multipart semantics |
| `passport` | Partial | Depends on request state |
| `express-session` | Unsupported initially | Deep lifecycle/session assumptions |
| `express.Router` | Unsupported initially | Framework-level routing semantics |

The test suite should be the source of truth for compatibility claims.

## Phased implementation

### Phase 0 — compatibility research / spike

Evaluate ~20 representative, popular Express packages across security, logging, parsing, cookies, uploads, compression, authentication, and other common production concerns.

Determine the minimum request/response/lifecycle surface required for meaningful compatibility.

### Phase 1 — interoperability foundation

Implement the smallest proven adapter contract:

- request
- response
- continuation
- error propagation
- shared request state
- lifecycle management

### Phase 2 — Express bridge

Introduce `@nextrush/express-bridge` and support the highest-value middleware first.

### Phase 3 — compatibility registry + documentation

Document full/partial/unsupported packages and their limitations.

### Phase 4 — ecosystem-driven expansion

Use real adoption data and user requests to determine whether to:

- improve bridge coverage
- create a native `@nextrush/*` implementation
- build a dedicated infrastructure integration

## Non-goals

- Reimplement Express
- Reimplement NestJS
- Create a universal framework compatibility emulator
- Make `@nextrush/core` depend on Express
- Promise that every Express/NestJS package will work
- Rebuild mature protocol/library ecosystems that NextRush can integrate instead

## Expected benefits

- Dramatically larger practical ecosystem reach for NextRush
- Lower migration/adoption friction
- Less pressure to recreate years of existing npm ecosystem work
- Better leverage of NextRush's limited engineering bandwidth
- Clear path from community demand → bridge support → first-class NextRush package
- Stronger production-readiness story without bloating the core framework

## Success criteria

The feature should be considered successful if a relatively small and well-defined compatibility surface enables a meaningful set of commonly used production Express middleware to run correctly in NextRush, while:

1. keeping NextRush core independent of Express,
2. preserving native NextRush performance when compatibility is unused,
3. providing clean, explicit DX,
4. documenting compatibility honestly, and
5. creating a foundation that can support future ecosystem interoperability without becoming a framework emulator.

## Discussion

This issue is primarily an architectural proposal. The first implementation should begin with a compatibility spike and measurements before committing to a broad API surface or long-term package matrix.