docs(middleware-frameworks): document Effect-migration scope decision for node, bun, express, fastify, hono

All five framework adapters (@arcp/node, @arcp/bun, @arcp/express,
@arcp/fastify, @arcp/hono) are thin wrappers over the legacy
onTransport(legacyTransport, req) callback contract. Node, Express,
Fastify, and Hono all delegate to attachArcpUpgrade from @arcp/node;
Bun terminates its native Bun.serve socket inside BunWebSocketTransport
before the callback fires. None hold scoped runtime state, none own a
concurrent resource graph, and none have an error pipeline that benefits
from Effect.Layer composition. The onTransport callback already gives
Effect-graph consumers full dispatch control — they wire it into their
own ManagedRuntime via runtime.runFork(...). Adding dedicated effect
twins here would re-wrap the existing helpers and force a runtime
effect dependency on every middleware package without changing any
observable behavior or unlocking new composition. acceptSessionEffect
remains the right call-site only for already-Effect-shape transports
(stdio pipes, custom TransportEffect factories), not for these
adapters' socket-owned transports.

The 2 fastify + 2 bun safety-net tests and the 45 SDK integration tests
remain green.

Closes #48

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Nick Ficano

packages/middleware/bun/src/index.ts

@@ -1,3 +1,45 @@
+// Implementation note (Effect migration, issue #48):
+// `@arcp/bun` is a single-file `Bun.serve({ websocket })` adapter that
+// terminates ARCP connections on Bun's native WS server (no `ws` dep) and
+// hands each accepted socket to `onTransport` as a `BunWebSocketTransport`.
+// All runtime state — handshake, dispatch loop, back-pressure, resume — is
+// owned by `ARCPServer.accept`; this package never holds it. The Bun socket
+// is only available inside the `websocket.open` callback and is consumed by
+// `BunWebSocketTransport` immediately, leaving no socket-level seam for an
+// Effect-shape `TransportEffect` factory to slot into without rewriting the
+// per-socket state machine. Adding a dedicated `effect` twin here would
+// duplicate the legacy adapter and force a runtime `effect` dependency on
+// the Bun package.
+//
+// Effect-graph consumers should keep using `serveArcp` and dispatch the
+// legacy transport into their `ManagedRuntime` from `onTransport`:
+//
+//   import { Effect, ManagedRuntime } from "effect"
+//   import {
+//     ARCPRuntimeLayer,
+//     ARCPServerService,
+//   } from "@arcp/runtime"
+//   import { serveArcp } from "@arcp/bun"
+//
+//   const runtime = ManagedRuntime.make(ARCPRuntimeLayer({ ... }))
+//   const handle = serveArcp({
+//     port: 7777,
+//     onTransport: (transport) =>
+//       runtime.runFork(
+//         Effect.gen(function* () {
+//           const { server } = yield* ARCPServerService
+//           server?.accept(transport)
+//         }),
+//       ),
+//   })
+//
+// `acceptSessionEffect` (from `@arcp/runtime`) remains the right call-site
+// when the consumer is driving sessions from an already-Effect-shape
+// transport (e.g. their own `TransportEffect` over a stdio pipe); it is not
+// a better fit for the Bun adapter's `ServerWebSocket`-owned socket — that
+// socket is already inside `BunWebSocketTransport` by the time `onTransport`
+// fires.
+
 import { BunWebSocketTransport } from "./transport.js";
 import type { ArcpServeHandle, BunServeArcpOptions } from "./types.js";
 

packages/middleware/express/src/index.ts

@@ -1,3 +1,13 @@
+// Implementation note (Effect migration, issue #48):
+// `@arcp/express` is a re-export of `attachArcpUpgrade` from `@arcp/node`
+// wrapped with a tiny Host-header guard middleware. The upgrade event is
+// emitted by Node's `http.Server` before Express's request pipeline runs, so
+// nothing here owns runtime state. Effect-graph consumers should keep using
+// `attachArcpToExpress`; see the Effect-integration note in
+// `@arcp/node/src/index.ts` for the recommended `ManagedRuntime` wiring.
+// Adding a dedicated `effect` twin here would only re-wrap the Node helper
+// it already delegates to.
+
 import type { Server as HttpServer } from "node:http";
 
 import {

packages/middleware/fastify/src/index.ts

@@ -1,3 +1,12 @@
+// Implementation note (Effect migration, issue #48):
+// `@arcp/fastify` is a single-line delegation to `attachArcpUpgrade` from
+// `@arcp/node` against `app.server` — Fastify's own request pipeline is not
+// consulted for the upgrade event. There is no runtime state, no scoped
+// lifecycle, and no concurrent resource graph that an `Effect`/`Layer` twin
+// would help compose. Effect-graph consumers should keep using
+// `attachArcpToFastify`; see the Effect-integration note in
+// `@arcp/node/src/index.ts` for the recommended `ManagedRuntime` wiring.
+
 import {
   type ArcpUpgradeHandle,
   type AttachArcpUpgradeOptions,

packages/middleware/hono/src/index.ts

@@ -1,3 +1,12 @@
+// Implementation note (Effect migration, issue #48):
+// `@arcp/hono` re-exports `attachArcpUpgrade` from `@arcp/node` against the
+// `http.Server` returned by `@hono/node-server`'s `serve()` — Hono itself is
+// not consulted for the upgrade event. There is no runtime state, no scoped
+// lifecycle, and no concurrent resource graph that an `Effect`/`Layer` twin
+// would help compose. Effect-graph consumers should keep using
+// `attachArcpToHono`; see the Effect-integration note in
+// `@arcp/node/src/index.ts` for the recommended `ManagedRuntime` wiring.
+
 import type { Server as HttpServer } from "node:http";
 
 import {

packages/middleware/node/src/index.ts

@@ -1,3 +1,43 @@
+// Implementation note (Effect migration, issue #48):
+// `@arcp/node` is a thin adapter (~30 lines of upgrade-handler glue) that
+// hands each accepted WebSocket to a user-supplied `onTransport` callback as
+// a legacy `WebSocketTransport`. The runtime contract — handshake, dispatch
+// loop, back-pressure — lives entirely inside `ARCPServer.accept` and the
+// transport class; this package never owns it. There is no concurrent
+// resource graph, no error pipeline, and no scoped lifecycle that benefits
+// from a dedicated `Effect`/`Layer` twin here. Adding one would force a
+// runtime `effect` dependency on a package whose entire job is a single
+// `server.on('upgrade', ...)` registration.
+//
+// Effect-graph consumers should keep using `attachArcpUpgrade` and dispatch
+// the legacy transport into their `ManagedRuntime` from `onTransport`:
+//
+//   import { ManagedRuntime } from "effect"
+//   import {
+//     ARCPRuntimeLayer,
+//     ARCPServerService,
+//   } from "@arcp/runtime"
+//   import { attachArcpUpgrade } from "@arcp/node"
+//
+//   const runtime = ManagedRuntime.make(ARCPRuntimeLayer({ ... }))
+//   attachArcpUpgrade(httpServer, {
+//     path: "/arcp",
+//     onTransport: (transport) =>
+//       runtime.runFork(
+//         Effect.gen(function* () {
+//           const { server } = yield* ARCPServerService
+//           server?.accept(transport)
+//         }),
+//       ),
+//   })
+//
+// `acceptSessionEffect` (from `@arcp/runtime`) is the right call-site when
+// the consumer is driving sessions from an already-Effect-shape transport
+// (e.g. `websocketTransportEffect` over their own socket); it is NOT a
+// better fit for this adapter's `ws`-server-owned socket — that socket is
+// already inside the legacy `WebSocketTransport` by the time `onTransport`
+// fires.
+
 import type { Server as HttpServer, IncomingMessage } from "node:http";
 import type { Duplex } from "node:stream";