ts-procedures 10.1.2 → 10.2.1

package/src/adapters/hono/handlers/stream.ts

@@ -7,9 +7,9 @@ import { dispatchMidStreamError, dispatchPreStreamError } from '../../../server/
 import { buildStreamRouteDoc } from '../../../server/docs/stream-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
 import { SseEventSequencer } from '../../../server/sse.js'
-import { respondToDispatch } from '../request.js'
+import { respondToDispatch, runMiddlewareList } from '../request.js'
 import { midStreamErrorConfig, preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installRpcStreamRoute(params: {
   app: Hono
@@ -18,8 +18,9 @@ export function installRpcStreamRoute(params: {
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
   streamMode: StreamMode
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs, streamMode } = params
+  const { app, procedure, factoryItem, cfg, docs, streamMode, builderMiddleware } = params
 
   const route = buildStreamRouteDoc(
     procedure,
@@ -29,8 +30,16 @@ export function installRpcStreamRoute(params: {
   )
   docs.push(route)
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   const handler = async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams =

package/src/adapters/hono/index.test.ts

@@ -325,3 +325,73 @@ describe('HonoAppBuilder — per-factory streamMode override', () => {
     await res.text()
   })
 })
+
+describe('HonoAppBuilder — middleware (new)', () => {
+  test('builder config.middleware and per-register middleware both run; register ones after builder ones', async () => {
+    const order: string[] = []
+    const builderMw = vi.fn(async (_c: any, next: any) => { order.push('builder'); await next() })
+    const regMw = vi.fn(async (_c: any, next: any) => { order.push('register'); await next() })
+
+    const P = Procedures<object, RPCConfig>()
+    P.Create('Ping', { scope: 'p', version: 1 }, async () => ({ ok: true }))
+
+    const app = new HonoAppBuilder({ middleware: [builderMw] })
+      .register(P, () => ({}), { middleware: [regMw] })
+      .build()
+
+    const res = await app.request('/p/ping/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(res.status).toBe(200)
+    expect(order).toEqual(['builder', 'register'])
+  })
+
+  test('middleware can short-circuit by throwing (flows to dispatch + onRequestError)', async () => {
+    const onRequestError = vi.fn()
+    const P = Procedures<object, RPCConfig>()
+    P.Create('Secret', { scope: 's', version: 1 }, async () => ({ secret: true }))
+
+    const app = new HonoAppBuilder({ onRequestError })
+      .register(P, () => ({}), {
+        middleware: [async () => { throw Object.assign(new Error('nope'), { status: 401 }) }],
+      })
+      .build()
+
+    const res = await app.request('/s/secret/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(res.status).toBe(500) // default path since no taxonomy matched the thrown Error
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+  })
+
+  test('register options.context layers are composed with main factoryContext (later wins)', async () => {
+    const P = Procedures<{ tenant?: string; uid: string }, RPCConfig>()
+    P.Create('WhoAmI', { scope: 'w', version: 1 }, async (ctx) => ({ tenant: ctx.tenant, uid: ctx.uid }))
+
+    const base = (c: any) => ({ uid: c.req.header('x-uid') || 'u0' })
+    const tenantLayer = { tenant: 't-from-layer' }
+
+    const app = new HonoAppBuilder()
+      .register(P, base, { context: tenantLayer as any })
+      .build()
+
+    const res = await app.request('/w/who-am-i/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-uid': 'user-xyz' },
+      body: '{}',
+    })
+    expect(await res.json()).toEqual({ tenant: 't-from-layer', uid: 'user-xyz' })
+  })
+
+  test('chainable .use() installs and runs for procedures', async () => {
+    const calls: string[] = []
+    const mw = async (_c: any, next: any) => { calls.push('used'); await next() }
+
+    const P = Procedures<object, RPCConfig>()
+    P.Create('X', { scope: 'x', version: 1 }, async () => ({}))
+
+    const b = new HonoAppBuilder()
+    b.use(mw)
+    b.register(P, () => ({}))
+    const app = b.build()
+
+    await app.request('/x/x/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(calls).toContain('used')
+  })
+})

package/src/adapters/hono/index.ts

@@ -21,10 +21,11 @@ import { installRpcRoute } from './handlers/rpc.js'
 import { installRpcStreamRoute } from './handlers/stream.js'
 import { installHttpRoute } from './handlers/http.js'
 import { installHttpStreamRoute } from './handlers/http-stream.js'
+import { runMiddlewareList } from './request.js'
 import type { Context } from 'hono'
-import type { HonoAppBuilderConfig, HonoFactoryItem, ExtendProcedureDoc } from './types.js'
+import type { HonoAppBuilderConfig, HonoFactoryItem, ExtendProcedureDoc, HonoRequestMiddleware, RegisterOptions } from './types.js'
 
-export type { HonoAppBuilderConfig, ExtendProcedureDoc, QueryParser } from './types.js'
+export type { HonoAppBuilderConfig, ExtendProcedureDoc, QueryParser, HonoRequestMiddleware, RegisterOptions } from './types.js'
 export type { OnRequestErrorContext } from './types.js'
 export { sse } from '../../server/sse.js'
 export type { SSEOptions } from '../../server/sse.js'
@@ -46,6 +47,7 @@ export { DocRegistry } from '../../server/doc-registry.js'
 export class HonoAppBuilder<TStreamErrorData = unknown> {
   private readonly _app: Hono
   private readonly factories: HonoFactoryItem<any>[] = []
+  private readonly builderMiddleware: HonoRequestMiddleware[] = []
   private _docs: AnyHttpRouteDoc[] | null = null
   private _skipped: { name: string; reason: string }[] = []
   private _built = false
@@ -53,6 +55,10 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
   constructor(readonly config?: HonoAppBuilderConfig<TStreamErrorData>) {
     this._app = config?.app ?? new Hono()
 
+    if (config?.middleware?.length) {
+      this.builderMiddleware.push(...config.middleware)
+    }
+
     if (config?.onRequestStart) {
       this._app.use('*', async (c, next) => {
         config.onRequestStart!(c)
@@ -67,6 +73,36 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
     }
   }
 
+  /**
+   * Register Hono middleware to run for routes on this builder.
+   * If no pattern is provided, uses the builder's pathPrefix (or '*').
+   *
+   * The middleware is installed on the underlying Hono app immediately
+   * (classic Hono behavior) and is also available for per-procedure
+   * sequencing inside handlers.
+   */
+  use(patternOrMw?: string | HonoRequestMiddleware, maybeMw?: HonoRequestMiddleware): this {
+    let pattern: string | undefined
+    let mw: HonoRequestMiddleware
+    if (typeof patternOrMw === 'function') {
+      mw = patternOrMw
+    } else {
+      pattern = patternOrMw
+      mw = maybeMw!
+    }
+    if (!mw) return this
+
+    this.builderMiddleware.push(mw)
+
+    const effective = pattern ?? (this.config?.pathPrefix ? `${this.config.pathPrefix.replace(/\/$/, '')}/*` : '*')
+    this._app.use(effective as any, async (c, next) => {
+      const res = await mw(c, async () => { await next() })
+      if (res instanceof Response) return res
+    })
+
+    return this
+  }
+
   static makeRoutePath = _makeRoutePath
 
   get app(): Hono {
@@ -89,16 +125,20 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
   register<TFactory extends ProceduresFactory>(
     factory: TFactory,
     factoryContext: FactoryContextInit<ExtractContext<TFactory>, Context>,
-    options?: {
-      streamMode?: StreamMode
-      extendProcedureDoc?: ExtendProcedureDoc
-    },
+    options?: RegisterOptions<TFactory>,
   ): this {
+    // Compose contexts if options.context provided: [base, extra]
+    const effectiveContext: FactoryContextInit<ExtractContext<TFactory>, Context> =
+      options?.context
+        ? [factoryContext, options.context] as any
+        : factoryContext
+
     this.factories.push({
       factory,
-      factoryContext,
+      factoryContext: effectiveContext,
       streamMode: options?.streamMode,
       extendProcedureDoc: options?.extendProcedureDoc,
+      middleware: options?.middleware,
     } as HonoFactoryItem<any>)
     // Invalidate docs cache so the next read recomputes.
     this._docs = null
@@ -154,22 +194,24 @@ export class HonoAppBuilder<TStreamErrorData = unknown> {
     const skipped: { name: string; reason: string }[] = []
     const cfg = this.config ?? {}
 
+    const builderMw = this.builderMiddleware
+
     for (const item of this.factories) {
       for (const procedure of item.factory.getProcedures().values() as Iterable<AnyProcedureRegistration<any, any>>) {
         switch (procedure.kind) {
           case 'rpc':
-            installRpcRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            installRpcRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, builderMiddleware: builderMw })
             break
           case 'rpc-stream': {
             const streamMode = item.streamMode ?? cfg.stream?.defaultStreamMode ?? 'sse'
-            installRpcStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, streamMode })
+            installRpcStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, streamMode, builderMiddleware: builderMw })
             break
           }
           case 'http':
-            installHttpRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            installHttpRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, builderMiddleware: builderMw })
             break
           case 'http-stream':
-            installHttpStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs })
+            installHttpStreamRoute({ app: this._app, procedure: procedure as any, factoryItem: item, cfg, docs, builderMiddleware: builderMw })
             break
           default: {
             const reason = `Unknown procedure kind "${(procedure as any).kind}"`

package/src/adapters/hono/request.ts

@@ -1,6 +1,7 @@
 import type { Context } from 'hono'
 import type { RequestSource } from '../../server/request/params.js'
 import type { PreStreamDispatchResult } from '../../server/errors/dispatch.js'
+import type { HonoRequestMiddleware } from './types.js'
 
 /** Adapts a Hono `Context` to the server layer's {@link RequestSource}. */
 export function honoRequestSource(c: Context): RequestSource {
@@ -26,3 +27,20 @@ export function respondToDispatch(
   if (result.type === 'response') return result.response
   return c.json(result.body, result.statusCode as never)
 }
+
+/**
+ * Run a list of middleware (builder + per-item) for the current request.
+ * Returns a Response if a middleware short-circuited (or threw — caller should treat throw as error).
+ * Otherwise returns undefined to continue to normal procedure handling.
+ */
+export async function runMiddlewareList(
+  c: Context,
+  middleware: HonoRequestMiddleware[] | undefined,
+): Promise<Response | undefined> {
+  if (!middleware || middleware.length === 0) return undefined
+  for (const mw of middleware) {
+    const maybe = await mw(c, async () => { /* continue to next in list */ })
+    if (maybe instanceof Response) return maybe
+  }
+  return undefined
+}

package/src/adapters/hono/types.ts

@@ -40,11 +40,41 @@ export type ExtendProcedureDoc = (params: {
   procedure: AnyProcedureRegistration<any, any>
 }) => Record<string, unknown>
 
+/**
+ * Middleware that can run before procedure handlers on a HonoAppBuilder.
+ * Similar to Hono middleware but integrated with ts-procedures dispatch.
+ *
+ * - Throw an error → routes through normal error dispatch (taxonomy, onError, 500).
+ * - Return a Response → sent verbatim (early exit, e.g. redirect or custom 401).
+ * - Call next() to continue to the procedure (or next middleware).
+ *
+ * Use for auth, tenancy, rate limiting, request ID injection, etc.
+ */
+export type HonoRequestMiddleware = (
+  c: Context,
+  next: () => Promise<void> | void,
+) => Response | Promise<Response | void> | void
+
+/**
+ * Optional per-registration middleware and context overrides.
+ * `middleware` runs before the factoryContext for these procedures.
+ * `factoryContext` (when provided here) is composed with the register arg via array semantics.
+ */
+export type RegisterOptions<TFactory extends ProceduresFactory = ProceduresFactory> = {
+  streamMode?: StreamMode
+  extendProcedureDoc?: ExtendProcedureDoc
+  /** Per-slice middleware (run for routes from this factory only). */
+  middleware?: HonoRequestMiddleware[]
+  /** Additional context layer composed (left-to-right) with the main factoryContext. */
+  context?: FactoryContextInit<ExtractContext<TFactory>, Context>
+}
+
 export type HonoFactoryItem<TFactory extends ProceduresFactory = ProceduresFactory> = {
   factory: TFactory
   factoryContext: FactoryContextInit<ExtractContext<TFactory>, Context>
   streamMode?: StreamMode
   extendProcedureDoc?: ExtendProcedureDoc
+  middleware?: HonoRequestMiddleware[]
 }
 
 export type HonoAppBuilderConfig<TStreamErrorData = unknown> = {
@@ -64,6 +94,13 @@ export type HonoAppBuilderConfig<TStreamErrorData = unknown> = {
   onRequestStart?: (c: Context) => void
   onRequestEnd?: (c: Context) => void
 
+  /**
+   * Builder-wide middleware run (via internal wrapping) for every procedure
+   * registered on this builder. Runs before per-registration middleware and
+   * before the factoryContext.
+   */
+  middleware?: HonoRequestMiddleware[]
+
   // Kind-specific blocks
   rpc?: {
     onSuccess?: (procedure: TProcedureRegistration<any, any>, c: Context) => void

package/src/codegen/bin/cli.ts

@@ -79,7 +79,7 @@ export async function loadConfigFile(configPath?: string): Promise<CodegenConfig
   } catch (err) {
     if (configPath !== undefined) {
       // Explicit path — always throw
-      throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`, { cause: err })
+      throw new Error(`[ts-procedures-codegen] Failed to load config from ${filePath}: ${err instanceof Error ? err.message : err}`)
     }
     // Default path — silently ignore if not found
     return undefined

package/src/codegen/constants.ts

@@ -1,4 +1,4 @@
-import { PACKAGE_VERSION } from '../version.js'
+import pkg from '../../package.json' with { type: 'json' }
 
 /**
  * Stable, version-agnostic token embedded in every generated file (across all
@@ -7,4 +7,4 @@ import { PACKAGE_VERSION } from '../version.js'
  * the package version (an orphan left by an older release must still match).
  */
 export const CODEGEN_SIGNATURE = 'ts-procedures-codegen'
-export const CODEGEN_HEADER = `// Auto-generated by ${CODEGEN_SIGNATURE} (v${PACKAGE_VERSION}) — do not edit`
+export const CODEGEN_HEADER = `// Auto-generated by ${CODEGEN_SIGNATURE} (v${pkg.version}) — do not edit`

package/src/codegen/emit/api-route.ts

@@ -62,7 +62,7 @@ export async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext
 
   const declarations: string[] = []
   let paramsTypeName = 'void'
-  let returnTypeName: string
+  let returnTypeName = 'void'
 
   // Track reserved names across all sub-namespaces. Model names are reserved
   // so an ajsc-extracted sub-type can't silently merge with a referenced model.

package/src/codegen/emit/scope-file.ts

@@ -132,8 +132,7 @@ export async function emitScopeFile(
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
       throw new Error(
-        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`,
-        { cause: err }
+        `[ts-procedures-codegen] Failed to emit route "${route.name}" (kind: ${kind}, scope: ${group.scopeKey}): ${msg}`
       )
     }
 

package/src/codegen/emit-errors.integration.test.ts

@@ -91,7 +91,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
       }
 
       // Dynamic import of the compiled output.
@@ -164,7 +164,7 @@ describe('generated _errors.ts — runtime behavior', () => {
         const err = e as { stdout?: Buffer; stderr?: Buffer }
         const stdout = err.stdout?.toString() ?? ''
         const stderr = err.stderr?.toString() ?? ''
-        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`, { cause: e })
+        throw new Error(`tsc failed in ${outDir}:\nSTDOUT:\n${stdout}\nSTDERR:\n${stderr}`)
       }
 
       const errorsUrl = `file://${join(outDir, 'out', '_errors.js')}`

package/src/codegen/resolve-envelope.ts

@@ -21,7 +21,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
       response = await fetch(input.url)
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err)
-      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`, { cause: err })
+      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`)
     }
     if (!response.ok) {
       throw new Error(`[ts-procedures-codegen] ${input.url} returned HTTP ${response.status} ${response.statusText}`)

package/src/codegen/test-helpers/run-tsc.ts

@@ -51,7 +51,6 @@ export function runTsc(args: {
     const combined = [stdout, stderr].filter(Boolean).join('\n').trim()
     throw new Error(
       `[runTsc] tsc failed for ${tsconfigPath}:\n${combined || (e.message ?? '(no output)')}`,
-      { cause: err },
     )
   }
 }

package/src/core/create-http-stream.ts

@@ -7,15 +7,20 @@ import {
   assertNotDuplicate,
   combineSignals,
   iterateWithGuards,
+  runWithMiddlewares,
   shouldSkipValidation,
   validateReqChannels,
 } from './internal.js'
 import type { FactoryRuntime } from './internal.js'
-import type { HttpMethod, ProcedureResult, TStreamContext, THttpStreamProcedureRegistration } from './types.js'
-
-type HttpReq<TReq> = TReq extends Record<string, unknown>
-  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
-  : undefined
+import type {
+  HttpMethod,
+  HttpReq,
+  ProcedureResult,
+  THttpReqInput,
+  THttpStreamSchema,
+  TStreamContext,
+  THttpStreamProcedureRegistration,
+} from './types.js'
 
 export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext, any>) {
   /**
@@ -29,7 +34,7 @@ export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext,
    */
   return function CreateHttpStream<
     TName extends string,
-    TReq extends Record<string, unknown> | undefined,
+    TReq extends THttpReqInput | undefined,
     TYieldType,
     TReturnType = void,
     TResHeaders = undefined,
@@ -42,12 +47,7 @@ export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext,
       scope?: string
       errors?: TErrorKey[]
       description?: string
-      schema: {
-        req?: TReq
-        yield?: TYieldType
-        returnType?: TReturnType
-        res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
-      }
+      schema: THttpStreamSchema<TReq, TYieldType, TReturnType, TResHeaders>
       validateYields?: boolean
     },
     handler: TResHeaders extends undefined
@@ -116,7 +116,14 @@ export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext,
         signal: combineSignals(incomingSignal, abortController.signal),
       }
 
-      const handlerResult: any = (handler as any)({ ...ctx, ...streamCtx }, req)
+      const fullCtx = { ...ctx, ...streamCtx }
+      // Factory middleware wraps obtaining the stream result (generator or {stream, headers}).
+      const handlerResult: any = runWithMiddlewares(
+        runtime.middlewares,
+        fullCtx,
+        req,
+        (c, r) => (handler as any)(c, r)
+      )
       const guardOptions = {
         name,
         validateYields,

package/src/core/create-http.test-d.ts

@@ -0,0 +1,154 @@
+import { Type } from 'typebox'
+import { describe, expectTypeOf, test } from 'vitest'
+
+import { Procedures } from './procedures.js'
+import type { HttpReturn } from './create-http.js'
+import type {
+  HttpReq,
+  HttpSchemaInput,
+  TCreateHttpConfig,
+  THttpReqInput,
+  THttpResInput,
+} from './types.js'
+import type { APIInput } from '../server/types.js'
+
+// ---------------------------------------------------------------------------
+// Type tests for HTTP input shape autocomplete / DX contract
+// These guard the shapes that power IDE autocomplete for schema.req / schema.res.
+// ---------------------------------------------------------------------------
+
+describe('THttpReqInput / THttpResInput / APIInput', () => {
+  test('APIInput accepts only the four known channels', () => {
+    // Valid
+    const good: APIInput = {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({}),
+      body: Type.Object({}),
+      headers: Type.Object({}),
+    }
+    expectTypeOf(good).toEqualTypeOf<APIInput>()
+
+    // Invalid channel should not be assignable
+    // @ts-expect-error - unknown channel name
+    const _bad: APIInput = { wrong: Type.Object({}) as any }
+  })
+
+  test('THttpResInput shape', () => {
+    const resShape: THttpResInput = {
+      body: Type.Object({ ok: Type.Boolean() }),
+      headers: Type.Object({ 'x-foo': Type.String() }),
+    }
+    expectTypeOf(resShape).toEqualTypeOf<THttpResInput>()
+  })
+})
+
+describe('TCreateHttpConfig shapes for literals', () => {
+  test('config literal gets the channel keys from the shape (autocomplete contract)', () => {
+    const cfg: TCreateHttpConfig = {
+      path: '/x',
+      method: 'get',
+      schema: {
+        req: {
+          // These keys should be suggested by the IDE
+          pathParams: Type.Object({ id: Type.String() }),
+          query: undefined,
+        },
+        res: {
+          body: Type.Object({}),
+        },
+      },
+    }
+    expectTypeOf(cfg).toEqualTypeOf<TCreateHttpConfig>()
+  })
+
+  test('using satisfies APIInput on req is valid and preserves specific types', () => {
+    const req = {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({ q: Type.Optional(Type.String()) }),
+    } satisfies APIInput
+
+    const cfg: TCreateHttpConfig<typeof req> = {
+      path: '/y',
+      method: 'get',
+      schema: { req },
+    }
+
+    // The assignment succeeded, proving the shape accepted the keys
+    // (specific inference of TReq from literal is a bonus)
+  })
+})
+
+describe('handler inference via HttpReq / HttpReturn', () => {
+  const procs = Procedures()
+
+  test('full req shape produces correctly typed handler param', () => {
+    const { Get } = procs.CreateHttp(
+      'Get',
+      {
+        path: '/u/:id',
+        method: 'get',
+        schema: {
+          req: {
+            pathParams: Type.Object({ id: Type.String() }),
+            query: Type.Object({ verbose: Type.Optional(Type.Boolean()) }),
+          },
+        },
+      },
+      async (_ctx, req) => {
+        expectTypeOf(req).toEqualTypeOf<{
+          pathParams: { id: string }
+          query: { verbose?: boolean }
+        }>()
+        // no res schema => void
+        return undefined
+      }
+    )
+
+    type Handler = typeof Get
+    expectTypeOf<Parameters<Handler>[1]>().toEqualTypeOf<{
+      pathParams: { id: string }
+      query: { verbose?: boolean }
+    }>()
+  })
+
+  test('res with headers produces { body, headers } return shape', () => {
+    const { WithHeaders } = procs.CreateHttp(
+      'WithHeaders',
+      {
+        path: '/h',
+        method: 'get',
+        schema: {
+          res: {
+            body: Type.Object({ data: Type.String() }),
+            headers: Type.Object({ 'x-trace': Type.String() }),
+          },
+        },
+      },
+      async () => ({ body: { data: 'hi' }, headers: { 'x-trace': 'abc' } })
+    )
+
+    type R = Awaited<ReturnType<typeof WithHeaders>>
+    expectTypeOf<R>().toEqualTypeOf<{ body: { data: string }; headers: { 'x-trace': string } }>()
+  })
+
+  test('no schema.res yields void (204-style)', () => {
+    const { Logout } = procs.CreateHttp(
+      'Logout',
+      { path: '/logout', method: 'post' },
+      async () => undefined
+    )
+
+    type R = Awaited<ReturnType<typeof Logout>>
+    expectTypeOf<R>().toEqualTypeOf<void>()
+  })
+})
+
+// Smoke test that HttpReq and HttpSchemaInput are exported and usable
+test('HttpReq and HttpSchemaInput are exported and usable', () => {
+  type ExampleReq = HttpSchemaInput<THttpReqInput, { pathParams: { id: string } }>
+  expectTypeOf<ExampleReq>().toHaveProperty('pathParams')
+
+  // HttpReq resolves through Infer; we just check it doesn't error and has shape
+  type H = HttpReq<{ query: { q?: string } }>
+  expectTypeOf<H>().toHaveProperty('query')
+})