ts-procedures 8.5.0 → 9.0.0

package/src/codegen/goldens.test.ts

@@ -0,0 +1,89 @@
+import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, describe, expect, it } from 'vitest'
+import { generateClient } from './index.js'
+import { resolveProductionKotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
+import { resolveProductionSwiftEmitter } from './targets/swift/ajsc-adapter.js'
+
+/**
+ * THE acceptance gate for v9 codegen: every generated file must be
+ * byte-identical to the v8.6.0 baselines captured by
+ * `tools/capture-goldens.mjs` into `__goldens__/`.
+ *
+ * The case matrix is read from `__goldens__/MANIFEST.json`, which the capture
+ * script writes alongside the baselines — one source of truth for both sides.
+ * (Kotlin/Swift emitters can't be serialized; they are re-resolved here from
+ * each case's `target`.)
+ *
+ * The only normalization applied on both sides is the package version inside
+ * the TS `CODEGEN_HEADER` line (`ts-procedures-codegen (v8.6.0)` vs `(v9.x)`),
+ * because the header intentionally records the producing version. Everything
+ * else — including the envelope-hash line — must match exactly (both sides
+ * hash the same fixture envelopes).
+ */
+const here = dirname(fileURLToPath(import.meta.url))
+const fixturesDir = resolve(here, '__fixtures__')
+const goldensDir = resolve(here, '__goldens__')
+
+type Manifest = {
+  capturedFrom: string
+  cases: Array<{ name: string; envelopes: string[]; options: Record<string, unknown> }>
+  cliDefaults: Record<string, unknown>
+}
+
+const manifest: Manifest = JSON.parse(await readFile(resolve(goldensDir, 'MANIFEST.json'), 'utf-8'))
+
+function normalizeVersion(content: string): string {
+  return content.replace(
+    /ts-procedures-codegen \(v[^)]+\)/,
+    'ts-procedures-codegen (<VERSION>)',
+  )
+}
+
+const tempDirs: string[] = []
+afterAll(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })))
+})
+
+describe(`codegen golden parity with ${manifest.capturedFrom}`, () => {
+  for (const c of manifest.cases) {
+    for (const envelopeName of c.envelopes) {
+      it(`${c.name}--${envelopeName} is byte-identical`, async () => {
+        const envelope = JSON.parse(
+          await readFile(resolve(fixturesDir, `${envelopeName}-envelope.json`), 'utf-8'),
+        )
+        const outDir = await mkdtemp(join(tmpdir(), 'v9-goldens-'))
+        tempDirs.push(outDir)
+
+        const options: Record<string, unknown> = {
+          envelope,
+          outDir,
+          ...manifest.cliDefaults,
+          ...c.options,
+        }
+        if (options.target === 'kotlin') {
+          options.kotlinEmitter = await resolveProductionKotlinEmitter()
+        }
+        if (options.target === 'swift') {
+          options.swiftEmitter = await resolveProductionSwiftEmitter()
+        }
+        await generateClient(options as unknown as Parameters<typeof generateClient>[0])
+
+        const goldenCaseDir = resolve(goldensDir, `${c.name}--${envelopeName}`)
+        const goldenFiles = (await readdir(goldenCaseDir)).sort()
+        const actualFiles = (await readdir(outDir)).sort()
+        expect(actualFiles, 'generated file set must match the v8 baseline').toEqual(goldenFiles)
+
+        for (const file of goldenFiles) {
+          const golden = await readFile(resolve(goldenCaseDir, file), 'utf-8')
+          const actual = await readFile(resolve(outDir, file), 'utf-8')
+          expect(normalizeVersion(actual), `${c.name}--${envelopeName}/${file}`).toBe(
+            normalizeVersion(golden),
+          )
+        }
+      })
+    }
+  }
+})

package/src/codegen/group-routes.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest'
 import { normalizeScope, scopeToCamelCase, groupRoutesByScope } from './group-routes.js'
-import type { AnyHttpRouteDoc } from '../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../server/types.js'
 
 // ---------------------------------------------------------------------------
 // Fixtures

package/src/codegen/group-routes.ts

@@ -1,4 +1,4 @@
-import type { AnyHttpRouteDoc } from '../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../server/types.js'
 
 export interface ScopeGroup {
   scopeKey: string

package/src/codegen/pipeline.test.ts

@@ -6,7 +6,7 @@ import type { KotlinEmitOptions } from './targets/kotlin/ajsc-adapter.js'
 import { mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import type { DocEnvelope } from '../implementations/types.js'
+import type { DocEnvelope } from '../server/types.js'
 import { CODEGEN_HEADER } from './constants.js'
 
 // ---------------------------------------------------------------------------

package/src/codegen/pipeline.ts

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto'
-import type { DocEnvelope } from '../implementations/types.js'
+import type { DocEnvelope } from '../server/types.js'
 import type { AjscOptions } from './emit-types.js'
 import { groupRoutesByScope } from './group-routes.js'
 import type { SharedTypesImportMap } from './collect-models.js'

package/src/codegen/resolve-envelope.test.ts

@@ -3,7 +3,7 @@ import { writeFile, mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { resolveEnvelope } from './resolve-envelope.js'
-import type { DocEnvelope } from '../implementations/types.js'
+import type { DocEnvelope } from '../server/types.js'
 
 // ---------------------------------------------------------------------------
 // Fixtures

package/src/codegen/resolve-envelope.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import type { DocEnvelope } from '../implementations/types.js'
+import type { DocEnvelope } from '../server/types.js'
 
 export interface ResolveInput {
   url?: string

package/src/codegen/targets/_shared/error-schemas.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { buildErrorSchemasMap } from './error-schemas.js'
-import type { ErrorDoc } from '../../../implementations/types.js'
+import type { ErrorDoc } from '../../../server/types.js'
 
 describe('buildErrorSchemasMap', () => {
   it('returns an empty map when there are no errors', () => {

package/src/codegen/targets/_shared/error-schemas.ts

@@ -1,4 +1,4 @@
-import type { ErrorDoc } from '../../../implementations/types.js'
+import type { ErrorDoc } from '../../../server/types.js'
 
 /**
  * Builds a lookup map from a {@link DocEnvelope}'s top-level `errors` array

package/src/codegen/targets/_shared/route-slots.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { extractRouteSlots } from './route-slots.js'
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 
 // Helpers for constructing minimal route docs per kind
 function apiRoute(jsonSchema: Record<string, unknown>): AnyHttpRouteDoc {

package/src/codegen/targets/_shared/route-slots.ts

@@ -1,4 +1,4 @@
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 
 /**
  * A "slot" is one of the deterministic schema sources a route exposes.

package/src/codegen/targets/_shared/target-run.ts

@@ -1,4 +1,4 @@
-import type { DocEnvelope } from '../../../implementations/types.js'
+import type { DocEnvelope } from '../../../server/types.js'
 import type { ScopeGroup } from '../../group-routes.js'
 import type { AjscOptions } from '../../emit-types.js'
 import type { SharedTypesImportMap } from '../../collect-models.js'

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -192,4 +192,10 @@ object Users {
             val count: Long,
         )
     }
+
+    object Heartbeat {
+        const val method = "GET"
+        const val pathTemplate = "/users/heartbeat"
+        const val path = "/users/heartbeat"
+    }
 }

package/src/codegen/targets/kotlin/emit-route-kotlin.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import { emitKotlinRoute } from './emit-route-kotlin.js'
 import { createStubKotlinEmitter, type KotlinEmitOptions, type KotlinEmitResult } from './ajsc-adapter.js'
 

package/src/codegen/targets/kotlin/emit-route-kotlin.ts

@@ -1,4 +1,4 @@
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import type { KotlinEmitter, KotlinEmitOptions } from './ajsc-adapter.js'
 import { indent } from '../_shared/indent.js'
 import { pickDefined } from '../_shared/pick-defined.js'

package/src/codegen/targets/kotlin/emit-scope-kotlin.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import type { ScopeGroup } from '../../group-routes.js'
 import { emitKotlinScope } from './emit-scope-kotlin.js'
 import { createStubKotlinEmitter, type KotlinEmitOptions, type KotlinEmitResult } from './ajsc-adapter.js'

package/src/codegen/targets/swift/__fixtures__/users-golden.swift

@@ -199,4 +199,10 @@ public enum Users {
             public let count: Int64
         }
     }
+
+    public enum Heartbeat {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/heartbeat"
+        public static let path = "/users/heartbeat"
+    }
 }

package/src/codegen/targets/swift/access-level.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { DocEnvelope } from '../../../implementations/types.js'
+import type { DocEnvelope } from '../../../server/types.js'
 import { runPipeline } from '../../pipeline.js'
 import { resolveProductionSwiftEmitter } from './ajsc-adapter.js'
 

package/src/codegen/targets/swift/emit-route-swift.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import { emitSwiftRoute } from './emit-route-swift.js'
 import { createStubSwiftEmitter, type SwiftEmitOptions, type SwiftEmitResult } from './ajsc-adapter.js'
 

package/src/codegen/targets/swift/emit-route-swift.ts

@@ -1,4 +1,4 @@
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import type { SwiftEmitter, SwiftEmitOptions } from './ajsc-adapter.js'
 import { indent } from '../_shared/indent.js'
 import { pickDefined } from '../_shared/pick-defined.js'

package/src/codegen/targets/swift/emit-scope-swift.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../../../server/types.js'
 import type { ScopeGroup } from '../../group-routes.js'
 import { emitSwiftScope } from './emit-scope-swift.js'
 import { createStubSwiftEmitter, type SwiftEmitOptions, type SwiftEmitResult } from './ajsc-adapter.js'

package/src/codegen/targets/ts/shared-models.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { runPipeline } from '../../pipeline.js'
-import type { DocEnvelope } from '../../../implementations/types.js'
+import type { DocEnvelope } from '../../../server/types.js'
 import type { GeneratedFile } from '../_shared/write-files.js'
 import { makeApiRoute, makeEnvelope } from '../../__fixtures__/make-envelope.js'
 

package/src/{create-http-stream.test.ts → core/create-http-stream.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { Procedures } from './index.js'
+import { Procedures } from './procedures.js'
 import { Type } from 'typebox'
 import { ProcedureValidationError } from './errors.js'
 

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

@@ -0,0 +1,207 @@
+import { ProcedureError, ProcedureRegistrationError } from './errors.js'
+import { computeSchema } from '../schema/compute-schema.js'
+import type { Infer, Prettify } from '../schema/json-schema.js'
+import { captureDefinitionInfo } from './definition-site.js'
+import { applyPathPrefix, checkPathParamConsistency } from './http-route.js'
+import {
+  assertNotDuplicate,
+  combineSignals,
+  iterateWithGuards,
+  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
+
+export function makeCreateHttpStream<TContext>(runtime: FactoryRuntime<TContext, any>) {
+  /**
+   * Defines a streaming HTTP procedure (SSE over a REST-shaped route).
+   *
+   * The handler either:
+   * - returns an async generator directly, or
+   * - (with `schema.res.headers` declared) returns
+   *   `Promise<{ headers, stream }>` so initial response headers can be set
+   *   before the stream opens.
+   */
+  return function CreateHttpStream<
+    TName extends string,
+    TReq extends Record<string, unknown> | undefined,
+    TYieldType,
+    TReturnType = void,
+    TResHeaders = undefined,
+    TErrorKey extends string = string,
+  >(
+    name: TName,
+    config: {
+      path: string
+      method: HttpMethod
+      scope?: string
+      errors?: TErrorKey[]
+      description?: string
+      schema: {
+        req?: TReq
+        yield?: TYieldType
+        returnType?: TReturnType
+        res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
+      }
+      validateYields?: boolean
+    },
+    handler: TResHeaders extends undefined
+      ? (
+          ctx: Prettify<TContext & TStreamContext>,
+          req: HttpReq<TReq>,
+        ) => AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>
+      : (
+          ctx: Prettify<TContext & TStreamContext>,
+          req: HttpReq<TReq>,
+        ) => Promise<{
+          headers: Infer<TResHeaders>
+          stream: AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>
+        }>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    assertNotDuplicate(runtime.registry, name, definitionInfo)
+    if ((config.schema as any)?.params) {
+      throw new ProcedureRegistrationError(
+        name,
+        `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttpStream. Procedure: "${name}".`,
+        definitionInfo,
+      )
+    }
+
+    const { jsonSchema, validations } = computeSchema(
+      name,
+      {
+        req: config.schema.req as Record<string, unknown> | undefined,
+        yieldType: config.schema.yield,
+        returnType: config.schema.returnType,
+        res: config.schema.res as { headers?: unknown } | undefined,
+      },
+      { adapters: runtime.adapters, compile: runtime.compile, definitionInfo },
+    )
+
+    const path = applyPathPrefix(runtime.httpDefaults?.pathPrefix, config.path)
+    const scope = config.scope ?? runtime.httpDefaults?.scope
+
+    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
+    checkPathParamConsistency(
+      name,
+      path,
+      pathParamsSchema as Record<string, unknown> | undefined,
+      definitionInfo,
+    )
+
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+    const validateYields = config.validateYields ?? false
+
+    const wrappedHandler = async (
+      ctx: TContext,
+      req: any,
+    ): Promise<{ stream: AsyncGenerator<any, any, unknown>; initialHeaders?: Record<string, string> }> => {
+      const abortController = new AbortController()
+
+      if (!shouldSkipValidation(ctx, runtime)) {
+        validateReqChannels(name, validations.req, req, definitionInfo)
+      }
+
+      const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+      const streamCtx: TStreamContext = {
+        error: errorFactory,
+        signal: combineSignals(incomingSignal, abortController.signal),
+      }
+
+      const handlerResult: any = (handler as any)({ ...ctx, ...streamCtx }, req)
+      const guardOptions = {
+        name,
+        validateYields,
+        validateYield: validations.yield,
+        abortController,
+        definitionInfo,
+      }
+
+      if (typeof handlerResult?.[Symbol.asyncIterator] === 'function') {
+        // Plain async generator from user
+        const userIterator = (handlerResult as AsyncGenerator<any, any, unknown>)[Symbol.asyncIterator]()
+        return { stream: iterateWithGuards(userIterator, guardOptions) }
+      } else if (typeof handlerResult?.then === 'function') {
+        // Async preamble: Promise<{ headers, stream }>
+        const resolved = await handlerResult
+        if (!resolved || typeof resolved !== 'object' || !('stream' in resolved)) {
+          throw new ProcedureError(
+            name,
+            `CreateHttpStream handler returned a Promise that did not resolve to { headers, stream }. Got: ${JSON.stringify(resolved)}`,
+            undefined,
+            definitionInfo,
+          )
+        }
+        const userIterator = (resolved.stream as AsyncGenerator<any, any, unknown>)[Symbol.asyncIterator]()
+        return {
+          stream: iterateWithGuards(userIterator, guardOptions),
+          initialHeaders: resolved.headers,
+        }
+      } else {
+        throw new ProcedureError(
+          name,
+          `CreateHttpStream handler must return an AsyncGenerator or Promise<{ headers, stream }>.`,
+          undefined,
+          definitionInfo,
+        )
+      }
+    }
+
+    // The registration's schema uses the SAME keys the route-doc builder and
+    // THttpStreamProcedureRegistration declare (`yield`, `res.headers`) — v8
+    // stored computeSchema's `yieldType` key and omitted `res` entirely, so
+    // live envelopes silently dropped both from http-stream route docs.
+    const registrationSchema = {
+      ...(jsonSchema.req !== undefined && { req: jsonSchema.req }),
+      ...(jsonSchema.res?.headers !== undefined && { res: { headers: jsonSchema.res.headers } }),
+      ...(jsonSchema.yieldType !== undefined && { yield: jsonSchema.yieldType }),
+      ...(jsonSchema.returnType !== undefined && { returnType: jsonSchema.returnType }),
+    }
+
+    const registeredProcedure: THttpStreamProcedureRegistration<TContext> = {
+      name,
+      kind: 'http-stream',
+      config: {
+        path,
+        method: config.method,
+        scope,
+        errors: config.errors as string[] | undefined,
+        description: config.description,
+        schema: registrationSchema,
+        validation: { req: validations.req, yield: validations.yield },
+        validateYields,
+      },
+      handler: wrappedHandler as any,
+    }
+
+    runtime.registry.set(name, registeredProcedure as any)
+    runtime.onCreate?.(registeredProcedure as any)
+
+    const info = { name, kind: 'http-stream' as const, ...registeredProcedure.config }
+
+    // Explicit handler type — preserves TReq/TYieldType/TReturnType through the
+    // public callable. Do NOT use `typeof registeredProcedure.handler` — that
+    // erases generics to `any`.
+    type Handler = (
+      ctx: Prettify<TContext>,
+      req: HttpReq<TReq>,
+    ) => Promise<{
+      stream: AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>
+      initialHeaders?: Record<string, string>
+    }>
+
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as ProcedureResult<TName, Handler, typeof info>
+  }
+}

package/src/{create-http.test.ts → core/create-http.test.ts}

@@ -1,6 +1,6 @@
 import { describe, it, expect, expectTypeOf } from 'vitest'
-import { Procedures } from './index.js'
-import { ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
+import { Procedures } from './procedures.js'
+import { ProcedureValidationError } from './errors.js'
 import { Type } from 'typebox'
 
 describe('CreateHttp registration', () => {
@@ -101,10 +101,10 @@ describe('CreateHttp conditional return shape', () => {
       schema: {
         res: { headers: Type.Object({ 'x-version': Type.String() }) },
       },
-    }, async () => ({ headers: { 'x-version': '8.0.0' } }))
+    }, async () => ({ headers: { 'x-version': '9.0.0' } }))
 
     const result = await Healthcheck({} as any, undefined)
-    expect(result).toEqual({ headers: { 'x-version': '8.0.0' } })
+    expect(result).toEqual({ headers: { 'x-version': '9.0.0' } })
   })
 
   it('no res → returns void', async () => {
@@ -160,4 +160,15 @@ describe('CreateHttp req channel validation', () => {
       query: { limit: 'not-a-number' as any },
     })).rejects.toThrow(/req\.query/)
   })
+
+  it('skips req channel validation when factory has validation: false', async () => {
+    const procs = Procedures({ validation: false })
+    const { Echo } = procs.CreateHttp('Echo', {
+      path: '/echo', method: 'post',
+      schema: { req: { body: Type.Object({ name: Type.String() }) } },
+    }, async () => undefined)
+
+    // Missing required `name` would normally throw ProcedureValidationError
+    await expect(Echo({} as any, { body: {} as any })).resolves.toBeUndefined()
+  })
 })

package/src/core/create-http.ts

@@ -0,0 +1,126 @@
+import { ProcedureError, ProcedureRegistrationError } from './errors.js'
+import { computeSchema } from '../schema/compute-schema.js'
+import type { Infer, Prettify } from '../schema/json-schema.js'
+import { captureDefinitionInfo } from './definition-site.js'
+import { applyPathPrefix, checkPathParamConsistency } from './http-route.js'
+import {
+  assertNotDuplicate,
+  shouldSkipValidation,
+  toProcedureError,
+  validateReqChannels,
+} from './internal.js'
+import type { FactoryRuntime } from './internal.js'
+import type { ProcedureResult, TCreateHttpConfig, TLocalContext, THttpProcedureRegistration } from './types.js'
+
+/**
+ * The handler return shape is gated by the DECLARED response schema, not by
+ * duck-typing the returned value — so domain objects that happen to have
+ * `body`/`headers` keys round-trip unchanged:
+ * - `schema.res.headers` declared → handler returns `{ body?, headers }`
+ * - only `schema.res.body` declared → handler returns the body itself
+ * - no `schema.res` → `void` (204-style)
+ */
+export type HttpReturn<TRes> =
+  TRes extends { body: infer B; headers: infer H } ? { body: Infer<B>; headers: Infer<H> }
+  : TRes extends { headers: infer H }              ? { headers: Infer<H> }
+  : TRes extends { body: infer B }                 ? Infer<B>
+  : void
+
+type HttpReq<TReq> = TReq extends Record<string, unknown>
+  ? Prettify<{ [K in keyof TReq]: Infer<TReq[K]> }>
+  : undefined
+
+export function makeCreateHttp<TContext>(runtime: FactoryRuntime<TContext, any>) {
+  /**
+   * Defines a REST-shaped HTTP procedure with per-channel input validation
+   * (`schema.req.{pathParams,query,body,headers}`).
+   *
+   * Factory-level `http.pathPrefix` / `http.scope` defaults apply here;
+   * the per-route config always wins.
+   */
+  return function CreateHttp<
+    TName extends string,
+    TReq extends Record<string, unknown> | undefined,
+    TRes extends { body?: unknown; headers?: unknown } | undefined = undefined,
+    TErrorKey extends string = string,
+  >(
+    name: TName,
+    config: TCreateHttpConfig<TReq, TRes, TErrorKey>,
+    handler: (ctx: Prettify<TContext & TLocalContext>, req: HttpReq<TReq>) => Promise<HttpReturn<TRes>>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    assertNotDuplicate(runtime.registry, name, definitionInfo)
+
+    if ((config.schema as any)?.params) {
+      throw new ProcedureRegistrationError(
+        name,
+        `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttp. Procedure: "${name}".`,
+        definitionInfo,
+      )
+    }
+
+    const { jsonSchema, validations } = computeSchema(
+      name,
+      {
+        req: config.schema.req as Record<string, unknown> | undefined,
+        res: config.schema.res as { body?: unknown; headers?: unknown } | undefined,
+      },
+      { adapters: runtime.adapters, compile: runtime.compile, definitionInfo },
+    )
+
+    const path = applyPathPrefix(runtime.httpDefaults?.pathPrefix, config.path)
+    const scope = config.scope ?? runtime.httpDefaults?.scope
+
+    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
+    checkPathParamConsistency(
+      name,
+      path,
+      pathParamsSchema as Record<string, unknown> | undefined,
+      definitionInfo,
+    )
+
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+
+    const registeredProcedure: THttpProcedureRegistration<TContext> = {
+      name,
+      kind: 'http',
+      config: {
+        path,
+        method: config.method,
+        successStatus: config.successStatus,
+        scope,
+        errors: config.errors as string[] | undefined,
+        description: config.description,
+        schema: jsonSchema as any,
+        validation: { req: validations.req },
+      },
+      handler: async (ctx: TContext, req: any) => {
+        try {
+          if (!shouldSkipValidation(ctx, runtime)) {
+            validateReqChannels(name, validations.req, req, definitionInfo)
+          }
+
+          const localCtx: TLocalContext = { error: errorFactory }
+          return await handler({ ...ctx, ...localCtx } as any, req)
+        } catch (error: any) {
+          throw toProcedureError(name, definitionInfo, error)
+        }
+      },
+    }
+
+    runtime.registry.set(name, registeredProcedure as any)
+    runtime.onCreate?.(registeredProcedure as any)
+
+    const info = { name, kind: 'http' as const, ...registeredProcedure.config }
+
+    type Handler = (ctx: Prettify<TContext>, req: HttpReq<TReq>) => Promise<HttpReturn<TRes>>
+
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as ProcedureResult<TName, Handler, typeof info>
+  }
+}