@owlmeans/server-api 0.1.18-rc.25 → 0.1.18-rc.26

package/README.md

@@ -1,78 +1,212 @@
 # @owlmeans/server-api
 
-Fastify-based HTTP/WebSocket server with typed handler factories for the OwlMeans entrypoint system.
-
-## Overview
-
-- `handlers<Context>()` creates protocol-bound `body()`, `params()`, `request()` and upload handlers
-- Built on [Fastify](https://fastify.dev/) — registered entrypoints become Fastify routes automatically
-- `createApiServer` / `appendApiServer` initialize the HTTP server in a context
-- Not typically used directly — import handlers from `@owlmeans/server-app`
+The Fastify HTTP server of an OwlMeans backend and the protocol-bound handler factories that serve
+it. An application imports `handlers<Context>()` in every HTTP handler module (often through the
+`@owlmeans/server-app` re-export) and `holdApiPort` for a guarded boot. The server itself —
+`appendApiServer` — is already added by `@owlmeans/server-app`'s `makeContext`; call it directly
+only when composing a context without that package. WebSocket routes belong to
+`@owlmeans/server-socket`, and calls to other services go through the `@owlmeans/api` client.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-api@^0.1.18-rc.16
+bun add @owlmeans/server-api@^0.1.18-rc.25
 ```
 
+## Concepts
+
+- **API server** — the `api-server` service (`context.getApiServer()`), holding a `FastifyInstance`
+  and `listen()`. At context init it builds its route table from the registered entrypoints: backend
+  routes of this `cfg.service` only, excluding socket and queue protocols.
+- **Request pipeline** — intermediates run first; then the protocol's guards (the first guard whose
+  `match` hits handles the request and sets `request.auth`, and the organization entity is attached);
+  then its gates (`gate.assert`); then the handler.
+- **Protocol-bound handler** — `handlers<Context>().body / .params / .request` infer the request
+  sections and the response type from the declaration. A returned value resolves the entrypoint with
+  `EntrypointOutcome.Ok` (HTTP 200); a thrown error rejects it.
+- **Validation** — the contract's schemas are compiled with AJV (`removeAdditional`, `useDefaults`,
+  `coerceTypes`), so a handler receives cleaned, coerced input.
+- **Error mapping** — `AuthForbidden` / `AccessError` answer 403, `AuthorizationError` /
+  `AuthFailedError` answer 401, anything else 500, with the marshalled `ResilientError` as the body.
+
 ## Usage
 
-Handlers are derived from the shared protocol and attached with `bind()`:
+### Body, params and request handlers
 
-```typescript
+```ts
 import { handlers } from '@owlmeans/server-api'
 import { bind } from '@owlmeans/server-entrypoint'
-import { projectEntrypoints } from 'project-common/entrypoints'
+import { requireEntityKey } from '@owlmeans/auth-common'
+import { projectProtocols } from 'my-app-common'
+import type { Context } from './context.js'
 
 const api = handlers<Context>()
 
-// Body handler: receives parsed + validated body as first arg
-const create = api.body(projectEntrypoints.create, async (payload, context, req) => {
-  const ctx = context as Context
-  return await ctx.project().create({ ...payload, entityId: req.entity!.id })
-})
+// body: the validated body first, then context and the full request
+const create = api.body(projectProtocols.create, async (payload, context, request) =>
+  context.project().create({ ...payload, entityId: requireEntityKey(request) }))
 
-// Params handler: receives validated URL params as first arg
-const get = api.params(projectEntrypoints.get, async (params, context, req) => {
-  return await (context as Context).project().get(params.id)
-})
+// params: the validated URL params first
+const get = api.params(projectProtocols.get, async ({ id }, context, request) =>
+  context.project().load({ id, entityId: requireEntityKey(request) }))
 
-// Request handler: receives the full AbstractRequest
-const health = api.request(projectEntrypoints.health, async (req, context) => {
-  return { status: 'ok' }
-})
+// request: every typed section plus request metadata (auth, entity, headers)
+const search = api.request(projectProtocols.search, async (request, context) =>
+  context.project().list({ entityId: requireEntityKey(request), ...request.query }))
 
-export const entrypoints = [
-  bind(projectEntrypoints.create, create),
-  bind(projectEntrypoints.get, get),
-  bind(projectEntrypoints.health, health),
+export const serverBindings = [
+  bind(projectProtocols.base),
+  bind(projectProtocols.create, create),
+  bind(projectProtocols.get, get),
+  bind(projectProtocols.search, search),
 ]
 ```
 
-## API
+### Refusing a request
+
+Guards and gates run before the handler; a handler still checks ownership and throws a typed error,
+which the server maps onto a status.
+
+```ts
+import { AuthForbidden } from '@owlmeans/auth'
+
+// the protocol declares both `params` and `body`
+export const rename = api.body(projectProtocols.rename, async ({ name }, context, request) => {
+  const entityId = requireEntityKey(request)
+  const project = await context.project().load({ id: request.params.id, entityId })
+  if (project == null) {
+    throw new AuthForbidden('project') // 403
+  }
+
+  return context.project().update({ ...project, name })
+})
+```
+
+### File upload
 
-### `handlers<Context>()`
+`uploadedFile(request)` is the only place a handler touches the Fastify multipart API. The protocol
+must declare a `body` section.
 
-Creates factories whose first argument is the protocol declaration, coupling the callback to its
-request and response contract.
-```typescript
-handlers<Context>().body(protocol, handler)
-handlers<Context>().params(protocol, handler)
-handlers<Context>().request(protocol, handler)
+```ts
+import { handlers, NoFileError, uploadedFile } from '@owlmeans/server-api'
+
+export const upload = api.request(invoiceProtocols.attach, async (request, context) => {
+  const file = await uploadedFile(request)
+  if (file == null) {
+    throw new NoFileError()
+  }
+
+  const content = await file.toBuffer()
+
+  return context.attachment().create({
+    entityId: requireEntityKey(request),
+    name: file.filename,
+    mimetype: file.mimetype,
+    size: content.length,
+  })
+})
+```
+
+### Holding the port during boot
+
+```ts
+import { holdApiPort } from '@owlmeans/server-api'
+
+const hold = await holdApiPort(cfg, { okPath: '/healthz' }) // 200 on /healthz, 503 elsewhere
+await context.configure().init()
+await hold.release()
+await context.getApiServer().listen()
 ```
 
-Each callback returns the response value; thrown `ResilientError` subclasses are mapped by the
-server. `uploadedFile(request)` remains the multipart boundary.
+### A context without `@owlmeans/server-app`
+
+```ts
+import { makeServerContext } from '@owlmeans/server-context'
+import { appendApiServer } from '@owlmeans/server-api'
 
-### `extractUploadedFile(req, fieldName): UploadedFile | null`
+const context = appendApiServer(makeServerContext(cfg))
+context.registerEntrypoints(serverBindings)
+await context.configure().init()
+
+// the Fastify instance, for plugins the framework does not register
+context.getApiServer().server.addHook('onResponse', async (request, reply) => {
+  console.log(request.url, reply.statusCode)
+})
 
-Extract a multipart-uploaded file from the request.
+await context.getApiServer().listen()
+```
+
+## API
 
-## Related Packages
+### Root export
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `handlers<Context>()` | function | Factories `body(protocol, fn)`, `params(protocol, fn)`, `request(protocol, fn)` returning `BoundEntrypointHandler<Protocol>` |
+| `uploadedFile(request)` | function | The multipart file of a request, or `undefined` |
+| `extractUploadedFile(req)` | function | Same boundary for an untyped `AbstractRequest`; returns `Promise<UploadedFile \| undefined>` |
+| `holdApiPort(cfg, opts?)` | function | Bind the service port before init; returns `ApiPortHold` with `release()` |
+| `createApiServer(alias)` | function | Create the Fastify API server service |
+| `appendApiServer(ctx, alias = DEFAULT_ALIAS)` | function | Register the API server and `context.getApiServer()` |
+| `handleBody`, `handleParams`, `handleRequest`, `handleIntermediate` | function | Unbound compatibility wrappers returning `RefedEntrypointHandler` |
+| `AuthFailedError`, `AccessError`, `NoFileError` | class | Registered `ResilientError` subclasses (401, 403, 500) |
+| `DEFAULT_ALIAS` | const | `'api-server'` |
+| `PORT` | const | `80`, used when the service route declares no port |
+| `CLOSED_HOST`, `OPENED_HOST` | const | `'127.0.0.1'` and `'0.0.0.0'`; a service with `opened: true` listens on the second |
+| `ApiServer`, `ApiServerAppend` | type | The server service and its context mixin |
+| `ApiPortHold`, `ApiPortHoldOptions` | type | `holdApiPort` result and options (`okPath?`, `payload?`) |
+| `Config`, `Context` | type | `ServerConfig` and `ServerContext & ApiServerAppend` |
+| `Request`, `Response` | type | Fastify request and reply |
+| `UploadedFile` | type | Fastify `MultipartFile` |
+
+### `./utils` subpath
+
+For transport packages (such as `@owlmeans/server-socket`) that reuse the HTTP pipeline; application
+code does not need it.
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `authorize(context, module, req, reply)` | function | Run guards, set `auth`, call `attachEntity` |
+| `createServerHandler(module, location)` | function | The Fastify handler: authorize, gates, handle, respond |
+| `canServeModule(context, module)` | function | Whether an entrypoint belongs on this HTTP server |
+| `provideRequest(alias, req, provision?)` | function | Build an `AbstractRequest` from a Fastify request |
+| `executeResponse(response, reply, throwOnError?)` | function | Send an `AbstractResponse` onto a reply |
+| `handleError(error, reply)` | function | Map an error onto 401 / 403 / 500 |
+| `fixFormatDates(schema)` | function | Rewrite `date-time` object schemas as strings |
+| `populateContext(req, context)`, `extractContext(req, ctx?, location?)` | function | Carry the request-scoped context on the raw request |
+
+## Common pitfalls
+
+- `.body` and `.params` exist only for a protocol that declares that section; for anything else use
+  `.request`.
+- Do not reach into `request.original` from application code — `uploadedFile(request)` is the
+  multipart boundary.
+- Prefer `handlers<Context>()` over the unbound `handle*` wrappers, and never hand-write a
+  `RefedEntrypointHandler` for an HTTP route.
+- A handler is wrapped by `handlers<Context>()` **exactly once**: wrap a plain function where it is
+  bound (`bind(p, api.body(p, create))`), or bind the already-bound export directly
+  (`const create = api.body(p, ...)` then `bind(p, create)`) — never both. `tsc` rejects a double
+  wrap (`TS2345 "BoundEntrypointHandler<…> is not assignable"`); at runtime a handler already bound
+  to the SAME protocol is returned unchanged with a one-time console warning, and anything else that
+  is not a plain function fails that one route with `HandlerMisconfiguredError` instead of the
+  opaque `TypeError: handler is not a function`.
+- A guard only authenticates. Gates authorize, and the handler keeps its organization check keyed on
+  `requireEntityKey(request)` — never an id read from the token.
+- `request.entity` is absent when no entity resolver is registered; `requireEntityKey` falls back to
+  the slug there, `requireEntity` throws.
+- A handler always answers 200 on success. The port comes from `cfg.services[cfg.service]`
+  (`internalPort ?? port ?? 80`).
+- A `holdApiPort` bind failure must end the process with a non-zero exit.
+- WebSocket routes use `connection(protocol, callback)` from `@owlmeans/server-socket`.
+
+## Related packages
 
-- [`@owlmeans/server-app`](../server-app) — application bootstrap and convenience re-exports
 - [`@owlmeans/server-entrypoint`](../server-entrypoint) — `bind()` attaches handlers to protocols
-- [`@owlmeans/server-socket`](../server-socket) — WebSocket `connection` counterpart
+- [`@owlmeans/server-app`](../server-app) — application bootstrap and re-exports
+- [`@owlmeans/server-socket`](../server-socket) — the WebSocket counterpart of `handlers`
+- [`@owlmeans/entrypoint`](../entrypoint) — `contract`, `typed`, request/response types
+- [`@owlmeans/auth-common`](../auth-common) — `requireEntityKey`, `attachEntity`, guard aliases
+- [`@owlmeans/api`](../api) — the client that calls these endpoints from other services
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -82,7 +216,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.21
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-api",
-  "version": "0.1.18-rc.25",
-  "generatedAt": "2026-09-12T14:18:54.778Z",
+  "version": "0.1.18-rc.26",
+  "generatedAt": "2026-09-15T12:21:31.872Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-api/SKILL.md

@@ -7,7 +7,7 @@ user-invocable: false
 
 # @owlmeans/server-api
 
-**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.23`
+**Install:** `bun add @owlmeans/server-api@^0.1.18-rc.25`
 
 Make handlers from the protocol declaration so input and output types stay coupled to the shared
 contract:
@@ -15,22 +15,22 @@ contract:
 ```ts
 const api = handlers<AppContext>()
 
-const create = api.body(projectEntrypoints.create, async (body, context, request) =>
+const create = api.body(projectProtocols.create, async (body, context, request) =>
   context.projects.create(body, request.auth)
 )
 
-const get = api.params(projectEntrypoints.get, async ({ id }, context) =>
+const get = api.params(projectProtocols.get, async ({ id }, context) =>
   context.projects.get(id)
 )
 
-const search = api.request(projectEntrypoints.search, async (request, context) =>
+const search = api.request(projectProtocols.search, async (request, context) =>
   context.projects.search(request.query)
 )
 
-export const entrypoints = [
-  bind(projectEntrypoints.create, create),
-  bind(projectEntrypoints.get, get),
-  bind(projectEntrypoints.search, search),
+export const serverBindings = [
+  bind(projectProtocols.create, create),
+  bind(projectProtocols.get, get),
+  bind(projectProtocols.search, search),
 ]
 ```
 
@@ -38,6 +38,24 @@ export const entrypoints = [
 any protocol and receives all its typed sections plus request metadata. A successful callback
 return resolves the entrypoint with `EntrypointOutcome.Ok`; a thrown error rejects it.
 
+## Wrap exactly once
+
+A handler is wrapped by `handlers<Context>()` exactly once — either shape above (create the bound
+handler and bind it directly) is correct on its own. Never combine them: a handler module that
+already exports a bound handler must be bound directly, not wrapped again where it is bound.
+
+```ts
+// WRONG — bound once in the handler module, wrapped a second time here
+export const create = api.body(projectProtocols.create, async (body, context) => ...)
+bind(projectProtocols.create, api.body(projectProtocols.create, create))
+```
+
+`tsc` rejects the double wrap (`TS2345 "Argument of type 'BoundEntrypointHandler<…>' is not
+assignable"`). At runtime, `body`/`params`/`request` return an already-bound handler for the SAME
+protocol unchanged, with a one-time warning; anything else that is not a plain function fails only
+that one route with `HandlerMisconfiguredError`, instead of the opaque
+`TypeError: handler is not a function`.
+
 `uploadedFile(request)` is the Fastify multipart boundary. Keep raw Fastify access there rather
 than reaching through `request.original` in application code.
 

package/build/errors.d.ts

@@ -11,4 +11,16 @@ export declare class NoFileError extends ApiError {
     static typeName: string;
     constructor();
 }
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export declare class HandlerMisconfiguredError extends ApiError {
+    static typeName: string;
+    constructor(message?: string);
+}
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,OAAuB,QAAQ,SAAoB;IAEnD,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAgB;IAE/C,cAGC;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,OAAuB,QAAQ,SAAoB;IAEnD,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAsC;IAErE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,WAAY,SAAQ,QAAQ;IACvC,OAAuB,QAAQ,SAAgB;IAE/C,cAGC;CACF;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,QAAQ;IACrD,OAAuB,QAAQ,SAA8B;IAE7D,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}

package/build/errors.js

@@ -21,7 +21,23 @@ export class NoFileError extends ApiError {
         this.type = NoFileError.typeName;
     }
 }
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export class HandlerMisconfiguredError extends ApiError {
+    static typeName = 'HandlerMisconfiguredError';
+    constructor(message = 'error') {
+        super(`handler:misconfigured:${message}`);
+        this.type = HandlerMisconfiguredError.typeName;
+    }
+}
 ResilientError.registerErrorClass(AuthFailedError);
 ResilientError.registerErrorClass(AccessError);
 ResilientError.registerErrorClass(NoFileError);
+ResilientError.registerErrorClass(HandlerMisconfiguredError);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACpC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,CAAA;IAEnD,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,SAAS,eAAe,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,aAAa,CAAA;IAE/C;QACE,KAAK,CAAC,SAAS,CAAC,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,eAAgB,SAAQ,QAAQ;IACpC,MAAM,CAAU,QAAQ,GAAG,iBAAiB,CAAA;IAEnD,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,SAAS,eAAe,CAAC,QAAQ,EAAE,CAAA;IAErE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,QAAQ;IAChC,MAAM,CAAU,QAAQ,GAAG,aAAa,CAAA;IAE/C;QACE,KAAK,CAAC,SAAS,CAAC,CAAA;QAChB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,yBAA0B,SAAQ,QAAQ;IAC9C,MAAM,CAAU,QAAQ,GAAG,2BAA2B,CAAA;IAE7D,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAA;QACzC,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC,QAAQ,CAAA;IAChD,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA;AAClD,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,WAAW,CAAC,CAAA;AAC9C,cAAc,CAAC,kBAAkB,CAAC,yBAAyB,CAAC,CAAA"}

package/build/protocol.d.ts

@@ -1,7 +1,26 @@
 import type { BasicConfig, BasicContext } from '@owlmeans/context';
 import type { BodyOf, EntrypointProtocolDeclaration, HandlerRequest, OpenValue, ParamsOf, RequestOf, ResponseOf } from '@owlmeans/entrypoint';
 import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint';
-type HandlerResponse<Response> = [Response] extends [undefined] ? void | undefined : Response;
+/**
+ * True for a response the declaration left with no compile-time contract: `typed<any>()` (an
+ * `[any] extends [X]` conditional does not produce `any`'s usual both-branches union once the
+ * checked type is wrapped in a tuple, so it resolves to a single branch like any other type) and
+ * a response inferred as bare `typed()` with nothing to infer from, which resolves to `undefined`
+ * with no shape to validate a handler's return against — the same signal a zero-argument
+ * `contract()` produces for a genuinely response-less route. Neither means "this handler must
+ * return void": it means the declaration did not constrain the response, so the handler is free to
+ * return whatever its route actually sends.
+ */
+type IsUntypedResponse<T> = 0 extends (1 & T) ? true : [T] extends [undefined] ? true : false;
+/**
+ * The type a bound handler is allowed to return for a given protocol response.
+ *
+ * A concretely typed or schema-backed `Response` is returned unchanged — the handler must produce
+ * exactly that shape. An untyped one (see `IsUntypedResponse` above) relaxes to `any`: the
+ * declaration made no promise about the response, so nothing here should force a handler bound to
+ * it into returning `void`.
+ */
+type HandlerResponse<Response> = IsUntypedResponse<Response> extends true ? any : Response;
 type MaybePromise<Value> = Value | Promise<Value>;
 type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
     body: OpenValue;

package/build/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,KAAK,EACV,MAAM,EAAE,6BAA6B,EAAE,cAAc,EAAe,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAC/G,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAEzE,KAAK,eAAe,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAA;AAC7F,KAAK,YAAY,CAAC,KAAK,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;AACjD,KAAK,YAAY,CAAC,QAAQ,SAAS,6BAA6B,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAC/G,QAAQ,GAAG,KAAK,CAAA;AACpB,KAAK,cAAc,CAAC,QAAQ,SAAS,6BAA6B,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAChH,QAAQ,GAAG,KAAK,CAAA;AAyCpB;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,YAAY,CAAC,WAAW,CAAC;IAChE,IAAI,GAAG,QAAQ,SAAS,6BAA6B,YACzC,QAAQ,WACT,QAAQ,SAAS,YAAY,CAAC,QAAQ,CAAC,GAAG,CAC/C,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,KACzC,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GACtD,KAAK,KACR,sBAAsB,CAAC,QAAQ,CAAC;IAKnC,MAAM,GAAG,QAAQ,SAAS,6BAA6B,YAC3C,QAAQ,WACT,QAAQ,SAAS,cAAc,CAAC,QAAQ,CAAC,GAAG,CACjD,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC3B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,KACzC,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GACtD,KAAK,KACR,sBAAsB,CAAC,QAAQ,CAAC;IAKnC,OAAO,GAAG,QAAQ,SAAS,6BAA6B,YAC5C,QAAQ,WACT,CACP,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAC5C,OAAO,EAAE,OAAO,KACb,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvD,sBAAsB,CAAC,QAAQ,CAAC;CACnC,CAAA;AAEF,sGAAsG;AACtG,eAAO,MAAM,YAAY,YACd,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,KACxC,OAAO,CAAC,OAAO,oBAAoB,EAAE,aAAa,GAAG,SAAS,CAKhE,CAAA"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAElE,OAAO,KAAK,EACV,MAAM,EAAE,6BAA6B,EAAE,cAAc,EAAe,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAC/G,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAA;AAGzE;;;;;;;;;GASG;AACH,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,KAAK,CAAA;AAE7F;;;;;;;GAOG;AACH,KAAK,eAAe,CAAC,QAAQ,IAAI,iBAAiB,CAAC,QAAQ,CAAC,SAAS,IAAI,GAAG,GAAG,GAAG,QAAQ,CAAA;AAC1F,KAAK,YAAY,CAAC,KAAK,IAAI,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;AACjD,KAAK,YAAY,CAAC,QAAQ,SAAS,6BAA6B,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAC/G,QAAQ,GAAG,KAAK,CAAA;AACpB,KAAK,cAAc,CAAC,QAAQ,SAAS,6BAA6B,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAChH,QAAQ,GAAG,KAAK,CAAA;AAqGpB;;;GAGG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,SAAS,YAAY,CAAC,WAAW,CAAC;IAChE,IAAI,GAAG,QAAQ,SAAS,6BAA6B,YACzC,QAAQ,WACT,QAAQ,SAAS,YAAY,CAAC,QAAQ,CAAC,GAAG,CAC/C,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,KACzC,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GACtD,KAAK,KACR,sBAAsB,CAAC,QAAQ,CAAC;IAKnC,MAAM,GAAG,QAAQ,SAAS,6BAA6B,YAC3C,QAAQ,WACT,QAAQ,SAAS,cAAc,CAAC,QAAQ,CAAC,GAAG,CACjD,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC3B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,KACzC,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,GACtD,KAAK,KACR,sBAAsB,CAAC,QAAQ,CAAC;IAKnC,OAAO,GAAG,QAAQ,SAAS,6BAA6B,YAC5C,QAAQ,WACT,CACP,OAAO,EAAE,cAAc,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,EAC5C,OAAO,EAAE,OAAO,KACb,YAAY,CAAC,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,KACvD,sBAAsB,CAAC,QAAQ,CAAC;CACnC,CAAA;AAEF,sGAAsG;AACtG,eAAO,MAAM,YAAY,YACd,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,KACxC,OAAO,CAAC,OAAO,oBAAoB,EAAE,aAAa,GAAG,SAAS,CAKhE,CAAA"}

package/build/protocol.js

@@ -1,5 +1,6 @@
 import { assertContext } from '@owlmeans/context';
 import { EntrypointOutcome } from '@owlmeans/entrypoint';
+import { HandlerMisconfiguredError } from './errors.js';
 const contextFor = (request, fallback) => {
     const original = request.original;
     if (original != null && typeof original === 'object' && '_ctx' in original) {
@@ -22,14 +23,58 @@ const bind = (protocol, execute) => ({
         return response.value;
     },
 });
+/**
+ * `value` is shaped like a `BoundEntrypointHandler` — never a plain function, which also carries
+ * its own `.bind` and would otherwise pass a `typeof value.bind === 'function'` check alone.
+ */
+const isBoundHandler = (value) => typeof value === 'object' && value != null
+    && typeof value.bind === 'function'
+    && value.protocol != null;
+const warnedAliases = new Set();
+/**
+ * What `body`/`params`/`request` do with something that is not the plain callback they declare —
+ * the shape a handler module wraps its own export in when it is bound TWICE. `null` means the
+ * second argument really is a callback and the caller should wrap it as usual.
+ *
+ * A handler bound to THIS protocol is returned unchanged, with a one-time warning: the module
+ * already produced a working `BoundEntrypointHandler`, and re-wrapping it here would only wrap it
+ * again — returning it as-is is what makes `bind(protocol, api.body(protocol, alreadyBound))`
+ * behave exactly like `bind(protocol, alreadyBound)`, which is what a wrap-once file looks like at
+ * this call site. Anything else — a handler bound to a DIFFERENT protocol, or a value that is
+ * neither a function nor a bound handler at all — answers every request on this route with
+ * {@link HandlerMisconfiguredError} instead of throwing `TypeError: handler is not a function`
+ * out of the request pipeline's own `try`, where the type name and the alias it happened on are
+ * both lost.
+ */
+const toleratedHandler = (protocol, handler) => {
+    if (typeof handler === 'function')
+        return null;
+    if (isBoundHandler(handler)) {
+        if (handler.protocol.alias === protocol.alias) {
+            if (!warnedAliases.has(protocol.alias)) {
+                warnedAliases.add(protocol.alias);
+                console.warn(`[server-api] ${protocol.alias}: handler is already bound — pass it to bind() directly; `
+                    + 'wrapping it again here is a type error (TS2345 "BoundEntrypointHandler<…> is not '
+                    + 'assignable"), tolerated at runtime for a project generated before the wrap-once rule.');
+            }
+            return handler;
+        }
+        return bind(protocol, () => {
+            throw new HandlerMisconfiguredError(`${protocol.alias}: handler is bound to a different protocol ('${handler.protocol.alias}')`);
+        });
+    }
+    return bind(protocol, () => {
+        throw new HandlerMisconfiguredError(`${protocol.alias}: handler is not a function`);
+    });
+};
 /**
  * Make server handlers that infer request sections and response values from their protocol.
  * The protocol is passed once; application callbacks never name request or reply generics.
  */
 export const handlers = () => ({
-    body: (protocol, handler) => bind(protocol, (request, context) => handler(request.body, context, request)),
-    params: (protocol, handler) => bind(protocol, (request, context) => handler(request.params, context, request)),
-    request: (protocol, handler) => bind(protocol, handler),
+    body: (protocol, handler) => toleratedHandler(protocol, handler) ?? bind(protocol, (request, context) => handler(request.body, context, request)),
+    params: (protocol, handler) => toleratedHandler(protocol, handler) ?? bind(protocol, (request, context) => handler(request.params, context, request)),
+    request: (protocol, handler) => toleratedHandler(protocol, handler) ?? bind(protocol, handler),
 });
 /** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
 export const uploadedFile = async (request) => {

package/build/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAkBxD,MAAM,UAAU,GAAG,CACjB,OAAwB,EACxB,QAAiB,EACR,EAAE;IACX,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;IACjC,IAAI,QAAQ,IAAI,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC3E,OAAQ,QAAoC,CAAC,IAAI,IAAI,QAAQ,CAAA;IAC/D,CAAC;IAED,OAAO,QAAQ,CAAA;AACjB,CAAC,CAAA;AAED,MAAM,IAAI,GAAG,CACX,QAAkB,EAClB,OAAgI,EAC9F,EAAE,CAAC,CAAC;IACtC,QAAQ;IACR,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;QACvC,MAAM,QAAQ,GAAG,aAAa,CAAuB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAA;QAElF,IAAI,CAAC;YACH,MAAM,YAAY,GAAI,OAA8E,CAAA;YACpG,MAAM,KAAK,GAAG,MAAM,OAAO,CACzB,YAAY,EACZ,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAC9B,CAAA;YACD,QAAQ,CAAC,OAAO,CAAC,KAA6B,EAAE,iBAAiB,CAAC,EAAE,CAAC,CAAA;QACvE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,QAAQ,CAAC,MAAM,CAAC,KAAc,CAAC,CAAA;QACjC,CAAC;QAED,OAAO,QAAQ,CAAC,KAAK,CAAA;IACvB,CAAC;CACF,CAAC,CAAA;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,GAA8C,EAAE,CAAC,CAAC;IACxE,IAAI,EAAE,CACJ,QAAkB,EAClB,OAKS,EACyB,EAAE,CAAC,IAAI,CAAoB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAC3F,OAEwD,CAAC,OAAO,CAAC,IAAwB,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEhH,MAAM,EAAE,CACN,QAAkB,EAClB,OAKS,EACyB,EAAE,CAAC,IAAI,CAAoB,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAC3F,OAEwD,CAAC,OAAO,CAAC,MAA4B,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAEpH,OAAO,EAAE,CACP,QAAkB,EAClB,OAGwD,EACtB,EAAE,CAAC,IAAI,CAAoB,QAAQ,EAAE,OAAO,CAAC;CAClF,CAAC,CAAA;AAEF,sGAAsG;AACtG,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,OAAyC,EACwB,EAAE;IACnE,MAAM,QAAQ,GAAI,OAA2B,CAAC,QAAQ,CAAA;IACtD,IAAI,QAAQ,IAAI,IAAI,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAA;IAE/F,OAAQ,QAA6C,CAAC,IAAI,EAAE,CAAA;AAC9D,CAAC,CAAA"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.25",
+  "version": "0.1.18-rc.26",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 264 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -32,15 +33,15 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.21",
-    "@owlmeans/auth": "^0.1.18-rc.17",
-    "@owlmeans/auth-common": "^0.1.18-rc.21",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/error": "^0.1.18-rc.16",
-    "@owlmeans/entrypoint": "^0.1.18-rc.19",
-    "@owlmeans/route": "^0.1.18-rc.17",
-    "@owlmeans/server-context": "^0.1.18-rc.20",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.19",
+    "@owlmeans/api": "^0.1.18-rc.22",
+    "@owlmeans/auth": "^0.1.18-rc.18",
+    "@owlmeans/auth-common": "^0.1.18-rc.22",
+    "@owlmeans/context": "^0.1.18-rc.17",
+    "@owlmeans/error": "^0.1.18-rc.17",
+    "@owlmeans/entrypoint": "^0.1.18-rc.20",
+    "@owlmeans/route": "^0.1.18-rc.18",
+    "@owlmeans/server-context": "^0.1.18-rc.21",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.20",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
     "fastify-raw-body": "^5.0.0",
@@ -52,6 +53,7 @@
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
     "@types/node": "^26.1.0",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"

package/src/errors.ts

@@ -29,7 +29,25 @@ export class NoFileError extends ApiError {
   }
 }
 
+/**
+ * `handlers().body/params/request` was handed something it cannot serve — not a plain callback,
+ * and not a `BoundEntrypointHandler` bound to the SAME protocol it is being wrapped for. Thrown
+ * from inside the bound handler's own request path, so the module still loads and every OTHER
+ * route on it still answers; only the misconfigured one reports why, as a 500 rather than the
+ * opaque `TypeError: handler is not a function` a double wrap used to fail with. See
+ * `handlers()` in `protocol.ts` for what does and does not reach here.
+ */
+export class HandlerMisconfiguredError extends ApiError {
+  public static override typeName = 'HandlerMisconfiguredError'
+
+  constructor(message: string = 'error') {
+    super(`handler:misconfigured:${message}`)
+    this.type = HandlerMisconfiguredError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(AuthFailedError)
 ResilientError.registerErrorClass(AccessError)
 ResilientError.registerErrorClass(NoFileError)
+ResilientError.registerErrorClass(HandlerMisconfiguredError)
 

package/src/protocol.ts

@@ -6,8 +6,29 @@ import type {
 } from '@owlmeans/entrypoint'
 import type { AbstractRequest } from '@owlmeans/entrypoint'
 import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+import { HandlerMisconfiguredError } from './errors.js'
 
-type HandlerResponse<Response> = [Response] extends [undefined] ? void | undefined : Response
+/**
+ * True for a response the declaration left with no compile-time contract: `typed<any>()` (an
+ * `[any] extends [X]` conditional does not produce `any`'s usual both-branches union once the
+ * checked type is wrapped in a tuple, so it resolves to a single branch like any other type) and
+ * a response inferred as bare `typed()` with nothing to infer from, which resolves to `undefined`
+ * with no shape to validate a handler's return against — the same signal a zero-argument
+ * `contract()` produces for a genuinely response-less route. Neither means "this handler must
+ * return void": it means the declaration did not constrain the response, so the handler is free to
+ * return whatever its route actually sends.
+ */
+type IsUntypedResponse<T> = 0 extends (1 & T) ? true : [T] extends [undefined] ? true : false
+
+/**
+ * The type a bound handler is allowed to return for a given protocol response.
+ *
+ * A concretely typed or schema-backed `Response` is returned unchanged — the handler must produce
+ * exactly that shape. An untyped one (see `IsUntypedResponse` above) relaxes to `any`: the
+ * declaration made no promise about the response, so nothing here should force a handler bound to
+ * it into returning `void`.
+ */
+type HandlerResponse<Response> = IsUntypedResponse<Response> extends true ? any : Response
 type MaybePromise<Value> = Value | Promise<Value>
 type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: OpenValue }
   ? Protocol : never
@@ -53,6 +74,66 @@ const bind = <Protocol extends EntrypointProtocolDeclaration, Context extends Ba
   },
 })
 
+/** Structural, not `instanceof`: a `BoundEntrypointHandler` crosses no class boundary a runtime check could use. */
+type AnyBoundHandler = BoundEntrypointHandler<EntrypointProtocolDeclaration>
+
+/**
+ * `value` is shaped like a `BoundEntrypointHandler` — never a plain function, which also carries
+ * its own `.bind` and would otherwise pass a `typeof value.bind === 'function'` check alone.
+ */
+const isBoundHandler = (value: unknown): value is AnyBoundHandler =>
+  typeof value === 'object' && value != null
+  && typeof (value as { bind?: unknown }).bind === 'function'
+  && (value as { protocol?: unknown }).protocol != null
+
+const warnedAliases = new Set<string>()
+
+/**
+ * What `body`/`params`/`request` do with something that is not the plain callback they declare —
+ * the shape a handler module wraps its own export in when it is bound TWICE. `null` means the
+ * second argument really is a callback and the caller should wrap it as usual.
+ *
+ * A handler bound to THIS protocol is returned unchanged, with a one-time warning: the module
+ * already produced a working `BoundEntrypointHandler`, and re-wrapping it here would only wrap it
+ * again — returning it as-is is what makes `bind(protocol, api.body(protocol, alreadyBound))`
+ * behave exactly like `bind(protocol, alreadyBound)`, which is what a wrap-once file looks like at
+ * this call site. Anything else — a handler bound to a DIFFERENT protocol, or a value that is
+ * neither a function nor a bound handler at all — answers every request on this route with
+ * {@link HandlerMisconfiguredError} instead of throwing `TypeError: handler is not a function`
+ * out of the request pipeline's own `try`, where the type name and the alias it happened on are
+ * both lost.
+ */
+const toleratedHandler = <Protocol extends EntrypointProtocolDeclaration>(
+  protocol: Protocol, handler: unknown
+): BoundEntrypointHandler<Protocol> | null => {
+  if (typeof handler === 'function') return null
+
+  if (isBoundHandler(handler)) {
+    if (handler.protocol.alias === protocol.alias) {
+      if (!warnedAliases.has(protocol.alias)) {
+        warnedAliases.add(protocol.alias)
+        console.warn(
+          `[server-api] ${protocol.alias}: handler is already bound — pass it to bind() directly; `
+          + 'wrapping it again here is a type error (TS2345 "BoundEntrypointHandler<…> is not '
+          + 'assignable"), tolerated at runtime for a project generated before the wrap-once rule.'
+        )
+      }
+
+      return handler as unknown as BoundEntrypointHandler<Protocol>
+    }
+
+    return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+      throw new HandlerMisconfiguredError(
+        `${protocol.alias}: handler is bound to a different protocol ('${handler.protocol.alias}')`
+      )
+    })
+  }
+
+  return bind<Protocol, BasicContext<BasicConfig>>(protocol, () => {
+    throw new HandlerMisconfiguredError(`${protocol.alias}: handler is not a function`)
+  })
+}
+
 /**
  * Make server handlers that infer request sections and response values from their protocol.
  * The protocol is passed once; application callbacks never name request or reply generics.
@@ -66,7 +147,7 @@ export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
         request: HandlerRequest<RequestOf<Protocol>>,
       ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
       : never,
-  ): BoundEntrypointHandler<Protocol> => bind<Protocol, Context>(protocol, (request, context) =>
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
     (handler as (
       payload: BodyOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
     ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.body as BodyOf<Protocol>, context, request)),
@@ -79,7 +160,7 @@ export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
         request: HandlerRequest<RequestOf<Protocol>>,
       ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
       : never,
-  ): BoundEntrypointHandler<Protocol> => bind<Protocol, Context>(protocol, (request, context) =>
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, (request, context) =>
     (handler as (
       payload: ParamsOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>,
     ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>)(request.params as ParamsOf<Protocol>, context, request)),
@@ -90,7 +171,7 @@ export const handlers = <Context extends BasicContext<BasicConfig>>() => ({
       request: HandlerRequest<RequestOf<Protocol>>,
       context: Context,
     ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
-  ): BoundEntrypointHandler<Protocol> => bind<Protocol, Context>(protocol, handler),
+  ): BoundEntrypointHandler<Protocol> => toleratedHandler(protocol, handler) ?? bind<Protocol, Context>(protocol, handler),
 })
 
 /** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */

package/tests/handlers.spec.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test'
+import type { EntrypointProtocolDeclaration } from '@owlmeans/entrypoint'
+import { handlers } from '../src/protocol.js'
+import { HandlerMisconfiguredError } from '../src/errors.js'
+
+/**
+ * A protocol-bound implementation is run with the smallest binding context the transport needs —
+ * same pattern as `@owlmeans/server-auth-token`'s own `handlers.spec.ts`.
+ */
+const invoke = async (handler: any, context: any, req: any = {}): Promise<any> => {
+  const res: any = { resolve: (value: unknown) => { res.value = value }, reject: (e: Error) => { res.error = e } }
+  await handler.bind({ ref: { ctx: context } })(req, res)
+  if (res.error != null) throw res.error
+
+  return res.value
+}
+
+const protocolFor = (alias: string): EntrypointProtocolDeclaration =>
+  ({ alias } as unknown as EntrypointProtocolDeclaration)
+
+const context = { alias: 'test-context' } as any
+const api = handlers<any>()
+
+describe('@owlmeans/server-api — handlers() wrap-once tolerance', () => {
+  test('a plain function is wrapped once and called with the context', async () => {
+    const protocol = protocolFor('api.thing.plain')
+    const handler = api.request(protocol, async (_req: any, ctx: any) => ({ ok: true, ctx }))
+
+    const result = await invoke(handler, context, {})
+    expect(result).toEqual({ ok: true, ctx: context })
+  })
+
+  test('a handler already bound to the SAME protocol is returned unchanged by body/params/request and still answers', async () => {
+    for (const method of ['body', 'params', 'request'] as const) {
+      const protocol = protocolFor(`api.thing.${method}`)
+      const bound = api.request(protocol, async () => ({ from: method }))
+
+      const wrapped = (api as any)[method](protocol, bound)
+      expect(wrapped).toBe(bound)
+
+      const result = await invoke(wrapped, context, {})
+      expect(result).toEqual({ from: method })
+    }
+  })
+
+  test('a handler bound to a DIFFERENT protocol answers with HandlerMisconfiguredError', async () => {
+    const protocolA = protocolFor('api.thing.mismatch-a')
+    const protocolB = protocolFor('api.thing.mismatch-b')
+    const boundToA = api.request(protocolA, async () => ({ from: 'a' }))
+
+    const wrapped = api.request(protocolB, boundToA as any)
+    expect(wrapped).not.toBe(boundToA)
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('a value that is neither a function nor a bound handler answers with HandlerMisconfiguredError', async () => {
+    const protocol = protocolFor('api.thing.not-a-function')
+    const wrapped = api.request(protocol, { not: 'a function' } as any)
+
+    await expect(invoke(wrapped, context, {})).rejects.toThrow(HandlerMisconfiguredError)
+  })
+
+  test('the double-wrap warning fires once per alias, not once per call', async () => {
+    const protocol = protocolFor('api.thing.warn-once')
+    const bound = api.request(protocol, async () => 'ok')
+
+    const warnings: unknown[][] = []
+    const original = console.warn
+    console.warn = (...args: unknown[]) => { warnings.push(args) }
+    try {
+      // Each call is a deliberate double wrap — the exact shape `tsc` rejects at the real call
+      // site (TS2345) — so it is exercised here through `any`, the same way `body`/`params`
+      // are reached dynamically above.
+      (api as any).request(protocol, bound);
+      (api as any).body(protocol, bound);
+      (api as any).params(protocol, bound)
+    } finally {
+      console.warn = original
+    }
+
+    expect(warnings.length).toBe(1)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -10,6 +10,7 @@
   "exclude": [
     "./dist/**/*",
     "./build/**/*",
+    "./tests/**/*",
     "./*.ts"
   ]
 }