@owlmeans/server-api 0.1.18-rc.17 → 0.1.18-rc.18

package/README.md

@@ -84,7 +84,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.12
+npx @owlmeans/agent-skills@^0.1.18-rc.13
 ```
 
 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.17",
-  "generatedAt": "2026-09-04T22:43:25.433Z",
+  "version": "0.1.18-rc.18",
+  "generatedAt": "2026-09-10T18:54:42.484Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

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

@@ -1,6 +1,6 @@
 ---
 name: server-api
-description: How to use @owlmeans/server-api — the Fastify-based API server factory, what it mounts and validates, the request pipeline (intermediates, guards, gates, handlers), holdApiPort() for the boot window, and the error-to-status mapping. Auto-invoked when importing server-api types, extending the server middleware stack, or working out why a request answered the status it did.
+description: How to use @owlmeans/server-api — typed protocol handlers, the Fastify-based API server factory, request pipeline, validation, holdApiPort() boot window, and error-to-status mapping. Auto-invoked when importing server-api types, writing protocol handlers, extending the middleware stack, or working out why a request answered the status it did.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,12 +8,14 @@ user-invocable: false
 # @owlmeans/server-api
 
 **Layer:** Server
-**Install:** `"@owlmeans/server-api": "^0.1.18-rc.17"` in `dependencies`
+**Install:** `"@owlmeans/server-api": "^0.1.18-rc.18"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
+| `handlers<Context>()` | Build `body`, `params`, and `request` handlers inferred from an immutable protocol |
+| `uploadedFile(request)` | Read Fastify multipart through the typed handler boundary |
 | `createApiServer(alias)` | Factory for the Fastify-based API server |
 | `appendApiServer(ctx, alias?)` | Register it and expose `ctx.getApiServer()` |
 | `handleRequest` / `handleBody` / `handleParams` / `handleIntermediate` | Wrap an async function as an entrypoint handler |
@@ -42,9 +44,30 @@ appendApiServer(context)
 
 ## Writing handlers
 
-`handleRequest(fn)` gives the whole request, `handleBody<T>(fn)` the validated body, `handleParams<T>(fn)`
-the validated URL params, and `handleIntermediate(fn)` a function that returns a context (or `null`
-to leave the chain unchanged) instead of a value. All four resolve the handler's context the same
+For a typed protocol, pass the declaration once and let `handlers<Context>()` infer every request
+section and the response. `body` and `params` are available only when the protocol contract
+declares that section; `request` receives the complete typed request plus alias/auth/entity/path
+metadata.
+
+```typescript
+const handle = handlers<Context>()
+
+export const create = handle.body(item.create, async (payload, context, request) => {
+  const owner = request.entity?.id
+  return await context.resource<ItemResource>('item').create({ ...payload, owner })
+})
+```
+
+The result is a protocol-bound implementation consumed by `bind(protocol, implementation)` from
+`@owlmeans/server-entrypoint` (both exports are available from `@owlmeans/server-app`). Throwing is
+still the failure path; the wrapper resolves successful returns with `EntrypointOutcome.Ok`.
+Use `uploadedFile(request)` when the protocol handler needs the Fastify multipart object.
+
+For a legacy entrypoint, `handleRequest(fn)` gives the whole request, `handleBody<T>(fn)` the
+validated body, `handleParams<T>(fn)` the validated URL params, and `handleIntermediate(fn)` a
+function that returns a context (or `null` to leave the chain unchanged) instead of a value.
+
+All handler forms resolve the handler's context the same
 way: from the request when it arrived over HTTP, and from the entrypoint's own context otherwise —
 the same handler runs unchanged when a queued job or a socket frame reaches it, and only the way it
 was reached differs.

package/build/index.d.ts

@@ -4,4 +4,5 @@ export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
 export * from './hold.js';
+export * from './protocol.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/build/index.js

@@ -3,4 +3,5 @@ export * from './consts.js';
 export * from './errors.js';
 export * from './helper.js';
 export * from './hold.js';
+export * from './protocol.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA"}

package/build/protocol.d.ts

@@ -0,0 +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;
+type MaybePromise<Value> = Value | Promise<Value>;
+type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    body: OpenValue;
+} ? Protocol : never;
+type ParamsProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends {
+    params: object;
+} ? Protocol : never;
+/**
+ * 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 declare const handlers: <Context extends BasicContext<BasicConfig>>() => {
+    body: <Protocol extends EntrypointProtocolDeclaration>(protocol: Protocol, handler: Protocol extends BodyProtocol<Protocol> ? (payload: BodyOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>> : never) => BoundEntrypointHandler<Protocol>;
+    params: <Protocol extends EntrypointProtocolDeclaration>(protocol: Protocol, handler: Protocol extends ParamsProtocol<Protocol> ? (payload: ParamsOf<Protocol>, context: Context, request: HandlerRequest<RequestOf<Protocol>>) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>> : never) => BoundEntrypointHandler<Protocol>;
+    request: <Protocol extends EntrypointProtocolDeclaration>(protocol: Protocol, handler: (request: HandlerRequest<RequestOf<Protocol>>, context: Context) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>) => BoundEntrypointHandler<Protocol>;
+};
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export declare const uploadedFile: (request: HandlerRequest<{
+    body: object;
+}>) => Promise<import('@fastify/multipart').MultipartFile | undefined>;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/build/protocol.d.ts.map

@@ -0,0 +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"}

package/build/protocol.js

@@ -0,0 +1,41 @@
+import { assertContext } from '@owlmeans/context';
+import { EntrypointOutcome } from '@owlmeans/entrypoint';
+const contextFor = (request, fallback) => {
+    const original = request.original;
+    if (original != null && typeof original === 'object' && '_ctx' in original) {
+        return original._ctx ?? fallback;
+    }
+    return fallback;
+};
+const bind = (protocol, execute) => ({
+    protocol,
+    bind: ref => async (request, response) => {
+        const fallback = assertContext(ref.ref?.ctx, protocol.alias);
+        try {
+            const typedRequest = request;
+            const value = await execute(typedRequest, contextFor(request, fallback));
+            response.resolve(value, EntrypointOutcome.Ok);
+        }
+        catch (error) {
+            response.reject(error);
+        }
+        return response.value;
+    },
+});
+/**
+ * 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),
+});
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export const uploadedFile = async (request) => {
+    const original = request.original;
+    if (original == null || typeof original !== 'object' || !('file' in original))
+        return undefined;
+    return original.file();
+};
+//# sourceMappingURL=protocol.js.map

package/build/protocol.js.map

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-api",
-  "version": "0.1.18-rc.17",
+  "version": "0.1.18-rc.18",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -32,15 +32,15 @@
     "@fastify/helmet": "^13.1.0",
     "@fastify/middie": "^9.0.2",
     "@fastify/multipart": "^9.0.1",
-    "@owlmeans/api": "^0.1.18-rc.13",
-    "@owlmeans/auth": "^0.1.18-rc.9",
-    "@owlmeans/auth-common": "^0.1.18-rc.13",
-    "@owlmeans/context": "^0.1.18-rc.8",
-    "@owlmeans/error": "^0.1.18-rc.8",
-    "@owlmeans/entrypoint": "^0.1.18-rc.11",
-    "@owlmeans/route": "^0.1.18-rc.9",
-    "@owlmeans/server-context": "^0.1.18-rc.12",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.11",
+    "@owlmeans/api": "^0.1.18-rc.14",
+    "@owlmeans/auth": "^0.1.18-rc.10",
+    "@owlmeans/auth-common": "^0.1.18-rc.14",
+    "@owlmeans/context": "^0.1.18-rc.9",
+    "@owlmeans/error": "^0.1.18-rc.9",
+    "@owlmeans/entrypoint": "^0.1.18-rc.12",
+    "@owlmeans/route": "^0.1.18-rc.10",
+    "@owlmeans/server-context": "^0.1.18-rc.13",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.12",
     "ajv-errors": "^3.0.0",
     "fastify": "^5.0.0",
     "fastify-raw-body": "^5.0.0",

package/src/index.ts

@@ -5,3 +5,4 @@ export * from './consts.js'
 export * from './errors.js'
 export * from './helper.js'
 export * from './hold.js'
+export * from './protocol.js'

package/src/protocol.ts

@@ -0,0 +1,104 @@
+import { assertContext } from '@owlmeans/context'
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import type {
+  BodyOf, EntrypointProtocolDeclaration, HandlerRequest, OpenRequest, OpenValue, ParamsOf, RequestOf, ResponseOf,
+} from '@owlmeans/entrypoint'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import type { BoundEntrypointHandler } from '@owlmeans/server-entrypoint'
+
+type HandlerResponse<Response> = [Response] extends [undefined] ? void | undefined : Response
+type MaybePromise<Value> = Value | Promise<Value>
+type BodyProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { body: OpenValue }
+  ? Protocol : never
+type ParamsProtocol<Protocol extends EntrypointProtocolDeclaration> = RequestOf<Protocol> extends { params: object }
+  ? Protocol : never
+
+interface ContextCarrier<Context> {
+  _ctx?: Context
+}
+
+const contextFor = <Context extends BasicContext<BasicConfig>>(
+  request: AbstractRequest,
+  fallback: Context,
+): Context => {
+  const original = request.original
+  if (original != null && typeof original === 'object' && '_ctx' in original) {
+    return (original as ContextCarrier<Context>)._ctx ?? fallback
+  }
+
+  return fallback
+}
+
+const bind = <Protocol extends EntrypointProtocolDeclaration, Context extends BasicContext<BasicConfig>>(
+  protocol: Protocol,
+  execute: (request: HandlerRequest<RequestOf<Protocol>>, context: Context) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+): BoundEntrypointHandler<Protocol> => ({
+  protocol,
+  bind: ref => async (request, response) => {
+    const fallback = assertContext<BasicConfig, Context>(ref.ref?.ctx, protocol.alias)
+
+    try {
+      const typedRequest = (request as HandlerRequest<OpenRequest>) as HandlerRequest<RequestOf<Protocol>>
+      const value = await execute(
+        typedRequest,
+        contextFor(request, fallback),
+      )
+      response.resolve(value as ResponseOf<Protocol>, EntrypointOutcome.Ok)
+    } catch (error) {
+      response.reject(error as Error)
+    }
+
+    return response.value
+  },
+})
+
+/**
+ * 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 = <Context extends BasicContext<BasicConfig>>() => ({
+  body: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends BodyProtocol<Protocol> ? (
+        payload: BodyOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => 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)),
+
+  params: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: Protocol extends ParamsProtocol<Protocol> ? (
+        payload: ParamsOf<Protocol>,
+        context: Context,
+        request: HandlerRequest<RequestOf<Protocol>>,
+      ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>
+      : never,
+  ): BoundEntrypointHandler<Protocol> => 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)),
+
+  request: <Protocol extends EntrypointProtocolDeclaration>(
+    protocol: Protocol,
+    handler: (
+      request: HandlerRequest<RequestOf<Protocol>>,
+      context: Context,
+    ) => MaybePromise<HandlerResponse<ResponseOf<Protocol>>>,
+  ): BoundEntrypointHandler<Protocol> => bind<Protocol, Context>(protocol, handler),
+})
+
+/** Access a Fastify-specific upload through an explicit boundary helper, never `request.original`. */
+export const uploadedFile = async (
+  request: HandlerRequest<{ body: object }>,
+): Promise<import('@fastify/multipart').MultipartFile | undefined> => {
+  const original = (request as AbstractRequest).original
+  if (original == null || typeof original !== 'object' || !('file' in original)) return undefined
+
+  return (original as import('fastify').FastifyRequest).file()
+}