ts-procedures 7.3.0 → 8.0.0

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

@@ -28,23 +28,20 @@ const envelope: DocEnvelope = {
       method: 'get',
       path: '/things/:id',
       fullPath: '/things/:id',
-      jsonSchema: {},
-      // The swift route emitter reads `route.schema.input.*` and
-      // `route.schema.returnType` directly; mirror what the codegen
-      // pipeline downstream expects rather than the doc-builder
-      // `jsonSchema` shape.
-      schema: {
-        input: {
+      jsonSchema: {
+        req: {
           pathParams: {
             type: 'object',
             properties: { id: { type: 'string' } },
             required: ['id'],
           },
         },
-        returnType: {
-          type: 'object',
-          properties: { id: { type: 'string' } },
-          required: ['id'],
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
         },
       },
       errors: [],

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

@@ -34,11 +34,9 @@ describe('emitSwiftRoute', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: {
-        input: {
-          pathParams: { type: 'object' },
-        },
-        returnType: { type: 'object' },
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: { body: { type: 'object' } },
       },
       errors: [],
     } as unknown as AnyHttpRouteDoc
@@ -64,7 +62,10 @@ describe('emitSwiftRoute', () => {
       name: 'CreateUser',
       method: 'POST',
       fullPath: '/users',
-      schema: { input: { body: { type: 'object' } }, returnType: { type: 'object' } },
+      jsonSchema: {
+        req: { body: { type: 'object' } },
+        res: { body: { type: 'object' } },
+      },
       errors: [],
     } as unknown as AnyHttpRouteDoc
 
@@ -84,7 +85,10 @@ describe('emitSwiftRoute', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: { body: { type: 'object' } },
+      },
       errors: ['NotFound'],
     } as unknown as AnyHttpRouteDoc
 
@@ -103,14 +107,14 @@ describe('emitSwiftRoute', () => {
   it('silently skips error keys with no schema in the envelope map', () => {
     const route = {
       kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users',
-      schema: {}, errors: ['UnknownTaxonomyKey'],
+      jsonSchema: {}, errors: ['UnknownTaxonomyKey'],
     } as unknown as AnyHttpRouteDoc
     const result = emitSwiftRoute(route, createStubSwiftEmitter({}), new Map())
     expect(result.code).not.toContain('enum Errors {')
   })
 
   it('returns skipped:true for stream routes', () => {
-    const route = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/users/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/users/stream', jsonSchema: {}, errors: [] } as unknown as AnyHttpRouteDoc
     const result = emitSwiftRoute(route, createStubSwiftEmitter({}), noErrors)
     expect(result.code).toBe('')
     expect(result.skipped).toBe(true)
@@ -122,9 +126,9 @@ describe('emitSwiftRoute', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: {
-        input: { pathParams: { type: 'object' } },
-        returnType: { type: 'object' },
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: { body: { type: 'object' } },
       },
       errors: ['NotFound'],
     } as unknown as AnyHttpRouteDoc
@@ -157,13 +161,13 @@ describe('emitSwiftRoute', () => {
       name: 'X',
       method: 'POST',
       fullPath: '/x/:id',
-      schema: {
-        input: {
+      jsonSchema: {
+        req: {
           pathParams: { type: 'object' },
           query: { type: 'object' },
           body: { type: 'object' },
         },
-        returnType: { type: 'object' },
+        res: { body: { type: 'object' } },
       },
       errors: ['Z'],
     } as unknown as AnyHttpRouteDoc
@@ -189,7 +193,7 @@ describe('emitSwiftRoute', () => {
       name: 'X',
       method: 'GET',
       fullPath: '/x',
-      schema: { returnType: { type: 'object' } },
+      jsonSchema: { res: { body: { type: 'object' } } },
       errors: [],
     } as unknown as AnyHttpRouteDoc
 
@@ -209,13 +213,92 @@ describe('emitSwiftRoute', () => {
     expect(calls[0]!.opts.uncountableWords).toEqual(['data', 'metadata'])
   })
 
+  it('emits ResponseHeaders slot when res.headers is declared on an api route', () => {
+    const route = {
+      kind: 'api',
+      name: 'DownloadUser',
+      method: 'GET',
+      fullPath: '/users/:id/download',
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: {
+          body: { type: 'object' },
+          headers: { type: 'object' },
+        },
+      },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      PathParams: ok('public struct PathParams: Codable { public let id: String }', 'PathParams'),
+      Response: ok('public struct Response: Codable { public let url: String }', 'Response'),
+      ResponseHeaders: ok(
+        'public struct ResponseHeaders: Codable { public let xDownloadToken: String }',
+        'ResponseHeaders',
+      ),
+    })
+
+    const result = emitSwiftRoute(route, emitter, noErrors)
+    expect(calls.map((c) => c.opts.rootTypeName)).toEqual(['PathParams', 'Response', 'ResponseHeaders'])
+    expect(result.code).toContain('public struct ResponseHeaders: Codable { public let xDownloadToken: String }')
+  })
+
+  it('does not emit ResponseHeaders when res.headers is absent', () => {
+    const route = {
+      kind: 'api',
+      name: 'GetUser',
+      method: 'GET',
+      fullPath: '/users/:id',
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: { body: { type: 'object' } },
+      },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      PathParams: ok('public struct PathParams: Codable { public let id: String }', 'PathParams'),
+      Response: ok('public struct Response: Codable { public let id: String }', 'Response'),
+    })
+
+    emitSwiftRoute(route, emitter, noErrors)
+    expect(calls.map((c) => c.opts.rootTypeName)).not.toContain('ResponseHeaders')
+  })
+
+  it('processes http-stream routes (not skipped) and emits Yield/ReturnType slots', () => {
+    const route = {
+      kind: 'http-stream',
+      name: 'TailLogs',
+      method: 'GET',
+      fullPath: '/logs/tail',
+      jsonSchema: {
+        req: { query: { type: 'object' } },
+        yield: { type: 'object' },
+        returnType: { type: 'object' },
+      },
+      errors: [],
+    } as unknown as AnyHttpRouteDoc
+
+    const { emitter, calls } = makeSpyEmitter({
+      Query: ok('public struct Query: Codable { public let filter: String? }', 'Query'),
+      Yield: ok('public struct Yield: Codable { public let line: String }', 'Yield'),
+      ReturnType: ok('public struct ReturnType: Codable { public let count: Int }', 'ReturnType'),
+    })
+
+    const result = emitSwiftRoute(route, emitter, noErrors)
+    expect(result.skipped).toBeFalsy()
+    expect(calls.map((c) => c.opts.rootTypeName)).toEqual(['Query', 'Yield', 'ReturnType'])
+    expect(result.code).toContain('public static let method = "GET"')
+    expect(result.code).toContain('public static let path = "/logs/tail"')
+  })
+
   it('does not include passthrough keys when caller omits them', () => {
     const route = {
       kind: 'api',
       name: 'X',
       method: 'GET',
       fullPath: '/x',
-      schema: { returnType: { type: 'object' } },
+      jsonSchema: { res: { body: { type: 'object' } } },
       errors: [],
     } as unknown as AnyHttpRouteDoc
 
@@ -246,7 +329,7 @@ describe('emitSwiftRoute', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: { input: { pathParams: { type: 'object' } } },
+      jsonSchema: { req: { pathParams: { type: 'object' } } },
       errors: [],
     } as unknown as AnyHttpRouteDoc
 
@@ -265,7 +348,7 @@ describe('emitSwiftRoute', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: { input: { pathParams: { type: 'object' } } },
+      jsonSchema: { req: { pathParams: { type: 'object' } } },
       errors: ['NotFound'],
     } as unknown as AnyHttpRouteDoc
 
@@ -291,7 +374,7 @@ describe('emitSwiftRoute', () => {
       name: 'CreateUser',
       method: 'POST',
       fullPath: '/users',
-      schema: {},
+      jsonSchema: {},
       errors: [],
     } as unknown as AnyHttpRouteDoc
     const result = emitSwiftRoute(route, createStubSwiftEmitter({}), noErrors, { accessLevel: 'internal' })

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

@@ -18,7 +18,10 @@ describe('emitSwiftScope', () => {
       name: 'GetUser',
       method: 'GET',
       fullPath: '/users/:id',
-      schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+      jsonSchema: {
+        req: { pathParams: { type: 'object' } },
+        res: { body: { type: 'object' } },
+      },
       errors: [],
     } as unknown as AnyHttpRouteDoc
 
@@ -41,8 +44,8 @@ describe('emitSwiftScope', () => {
   })
 
   it('joins multiple routes inside one scope enum, separated by a blank line', () => {
-    const route1 = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users/:id', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
-    const route2 = { kind: 'api', name: 'CreateUser', method: 'POST', fullPath: '/users', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route1 = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users/:id', jsonSchema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route2 = { kind: 'api', name: 'CreateUser', method: 'POST', fullPath: '/users', jsonSchema: {}, errors: [] } as unknown as AnyHttpRouteDoc
     const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route1, route2] }
     const emitter = createStubSwiftEmitter({})
 
@@ -74,8 +77,8 @@ describe('emitSwiftScope', () => {
   })
 
   it('dedupes and sorts imports across all routes in the scope', () => {
-    const route1 = { kind: 'api', name: 'A', method: 'GET', fullPath: '/a', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
-    const route2 = { kind: 'api', name: 'B', method: 'GET', fullPath: '/b', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const route1 = { kind: 'api', name: 'A', method: 'GET', fullPath: '/a', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const route2 = { kind: 'api', name: 'B', method: 'GET', fullPath: '/b', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] } as unknown as AnyHttpRouteDoc
     const group: ScopeGroup = { scopeKey: 'multi', camelCase: 'multi', routes: [route1, route2] }
     const emitter = {
       emit(_s: unknown, opts: SwiftEmitOptions): SwiftEmitResult {
@@ -93,7 +96,7 @@ describe('emitSwiftScope', () => {
   })
 
   it('threads all 6 passthrough opts to every emitter call', () => {
-    const route = { kind: 'api', name: 'X', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const route = { kind: 'api', name: 'X', method: 'GET', fullPath: '/x', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] } as unknown as AnyHttpRouteDoc
     const group: ScopeGroup = { scopeKey: 'x', camelCase: 'x', routes: [route] }
 
     const calls: SwiftEmitOptions[] = []
@@ -130,7 +133,7 @@ describe('emitSwiftScope', () => {
   })
 
   it('applies accessLevel to the outer scope enum and the route enum wrappers', () => {
-    const route = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const route = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users', jsonSchema: {}, errors: [] } as unknown as AnyHttpRouteDoc
     const group: ScopeGroup = { scopeKey: 'users', camelCase: 'users', routes: [route] }
     const emitter = createStubSwiftEmitter({})
 
@@ -142,8 +145,8 @@ describe('emitSwiftScope', () => {
   })
 
   it('collects skipped stream-route names', () => {
-    const stream = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/u/stream', schema: {}, errors: [] } as unknown as AnyHttpRouteDoc
-    const api = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] } as unknown as AnyHttpRouteDoc
+    const stream = { kind: 'stream', name: 'WatchUsers', method: 'GET', path: '/u/stream', jsonSchema: {}, errors: [] } as unknown as AnyHttpRouteDoc
+    const api = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/u', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] } as unknown as AnyHttpRouteDoc
     const group: ScopeGroup = { scopeKey: 'u', camelCase: 'u', routes: [stream, api] }
 
     const emitter = createStubSwiftEmitter({

package/src/codegen/targets/swift/integration.test.ts

@@ -62,6 +62,23 @@ describe('swift codegen — integration', () => {
         'public struct Query: Codable {\n    public let status: Status?\n    public let limit: Int64?\n\n    public enum Status: String, Codable {\n        case active\n        case inactive\n    }\n}',
         'Query',
       ),
+
+      // DownloadUser
+      ResponseHeaders: ok(
+        'public struct ResponseHeaders: Codable {\n    public let xDownloadToken: String\n    public let contentDisposition: String?\n\n    enum CodingKeys: String, CodingKey {\n        case xDownloadToken = "x-download-token"\n        case contentDisposition = "content-disposition"\n    }\n}',
+        'ResponseHeaders',
+      ),
+
+      // WatchUsers (http-stream) — reuses Query and ResponseHeaders stubs from above;
+      // adds Yield and ReturnType which are unique to the stream route.
+      Yield: ok(
+        'public struct Yield: Codable {\n    public let id: String\n    public let event: Event\n\n    public enum Event: String, Codable {\n        case created\n        case updated\n        case deleted\n    }\n}',
+        'Yield',
+      ),
+      ReturnType: ok(
+        'public struct ReturnType: Codable {\n    public let count: Int64\n}',
+        'ReturnType',
+      ),
     })
 
     const files = await runPipeline({

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

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest'
+import { Procedures } from './index.js'
+import { Type } from 'typebox'
+import { ProcedureValidationError } from './errors.js'
+
+describe('CreateHttpStream basic generator', () => {
+  it('registers with kind: http-stream', () => {
+    const procs = Procedures()
+    procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+      },
+    }, async function* () { yield { line: 'a' } })
+
+    expect(procs.getProcedure('Tail')?.kind).toBe('http-stream')
+  })
+
+  it('yields and returns', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+        returnType: Type.Object({ totalLines: Type.Number() }),
+      },
+    }, async function* (_, { query }) {
+      yield { line: `from-${query.source}-1` }
+      yield { line: `from-${query.source}-2` }
+      return { totalLines: 2 }
+    })
+
+    const lines: string[] = []
+    let returnVal: unknown
+    const { stream } = await Tail({} as any, { query: { source: 'app' } })
+    let result = await stream.next()
+    while (!result.done) {
+      lines.push(result.value.line)
+      result = await stream.next()
+    }
+    returnVal = result.value
+    expect(lines).toEqual(['from-app-1', 'from-app-2'])
+    expect(returnVal).toEqual({ totalLines: 2 })
+  })
+
+  it('rejects req.query validation error before opening stream', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+      },
+    }, async function* () { yield { line: 'should not run' } })
+
+    // Two independent async calls — each rejects before a stream is produced.
+    await expect(Tail({} as any, { query: {} as any })).rejects.toThrow(ProcedureValidationError)
+    await expect(Tail({} as any, { query: {} as any })).rejects.toThrow(/req\.query/)
+  })
+})
+
+describe('CreateHttpStream async-preamble shape (res.headers)', () => {
+  it('handler returning Promise<{ headers, stream }> surfaces headers in initialHeaders', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+        res: { headers: Type.Object({ 'x-stream-id': Type.String() }) },
+      },
+    }, async (_, { query }) => ({
+      headers: { 'x-stream-id': `id-${query.source}` },
+      stream: (async function* () { yield { line: 'a' } })(),
+    }))
+
+    const { stream, initialHeaders } = await Tail({} as any, { query: { source: 'app' } })
+    expect(initialHeaders).toEqual({ 'x-stream-id': 'id-app' })
+    const first = await stream.next()
+    expect(first.value).toEqual({ line: 'a' })
+  })
+
+  it('throws when handler returns malformed shape', async () => {
+    const procs = Procedures()
+    const { Bad } = procs.CreateHttpStream('Bad', {
+      path: '/streams', method: 'get',
+      schema: {
+        yield: Type.Number(),
+        res: { headers: Type.Object({}) },
+      },
+    }, (async () => 'not-a-shape') as any)
+
+    await expect(Bad({} as any, undefined)).rejects.toThrow(/did not resolve to/)
+  })
+})

package/src/create-http-stream.ts

@@ -0,0 +1,191 @@
+import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  HttpMethod, TBuilderConfig, TStreamContext,
+  THttpStreamProcedureRegistration, TProcedureRegistration, TStreamProcedureRegistration, THttpProcedureRegistration,
+} from './types.js'
+import { checkPathParamConsistency } from './create-http.js'
+
+/**
+ * Wraps a user's AsyncIterator in a generator that:
+ * - optionally validates each yielded value
+ * - augments error stack traces with the procedure definition site
+ * - aborts the stream controller on completion
+ */
+async function* yieldingWrapper(
+  userIterator: AsyncIterator<any, any, unknown>,
+  validateYields: boolean,
+  validations: { yield?: (value: any) => { errors?: any[] } },
+  abortController: AbortController,
+  definitionInfo: ReturnType<typeof captureDefinitionInfo>,
+  name: string,
+): AsyncGenerator<any, any, unknown> {
+  try {
+    let result = await userIterator.next()
+    while (!result.done) {
+      const value = result.value
+      if (validateYields && validations.yield) {
+        const { errors } = validations.yield(value)
+        if (errors) throw new ProcedureYieldValidationError(name, `Yield validation error for ${name}`, errors, definitionInfo)
+      }
+      yield value
+      result = await userIterator.next()
+    }
+    return result.value
+  } catch (error: any) {
+    if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
+      const { file, line, column } = definitionInfo.definedAt
+      error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+    }
+    throw error
+  } finally {
+    try { await userIterator.return?.(undefined) } catch { /* swallow */ }
+    abortController.abort('stream-completed')
+  }
+}
+
+export function makeCreateHttpStream<TContext>(
+  procedures: Map<string, TProcedureRegistration<TContext, any> | TStreamProcedureRegistration<TContext, any> | THttpProcedureRegistration<TContext> | THttpStreamProcedureRegistration<TContext>>,
+  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
+) {
+  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: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+        ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+      : (
+          ctx: Prettify<TContext & TStreamContext>,
+          req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+        ) => Promise<{ headers: TSchemaLib<TResHeaders>; stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown> }>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    if (procedures.has(name)) throw new Error(`Procedure with name ${name} is already registered`)
+    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,
+    }, definitionInfo)
+
+    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
+    checkPathParamConsistency(name, config.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()
+      const skipValidation = (ctx as { isPrevalidated?: boolean }).isPrevalidated || builder?.config?.noRuntimeValidation
+
+      if (validations?.req && !skipValidation) {
+        for (const [channel, validator] of Object.entries(validations.req)) {
+          const channelValue = (req as Record<string, unknown>)?.[channel]
+          const { errors } = validator(channelValue)
+          if (errors) {
+            throw new ProcedureValidationError(name, `Validation error for ${name} in req.${channel}`, errors, definitionInfo)
+          }
+        }
+      }
+
+      const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+      const signal = incomingSignal ? AbortSignal.any([incomingSignal, abortController.signal]) : abortController.signal
+      const streamCtx: TStreamContext = { error: errorFactory, signal }
+
+      const handlerResult: any = (handler as any)({ ...ctx, ...streamCtx }, req)
+
+      if (typeof handlerResult?.[Symbol.asyncIterator] === 'function') {
+        // Plain async generator from user
+        const userIterator = (handlerResult as AsyncGenerator<any, any, unknown>)[Symbol.asyncIterator]()
+        return { stream: yieldingWrapper(userIterator, validateYields, validations, abortController, definitionInfo, name) }
+      } 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: yieldingWrapper(userIterator, validateYields, validations, abortController, definitionInfo, name),
+          initialHeaders: resolved.headers,
+        }
+      } else {
+        throw new ProcedureError(name, `CreateHttpStream handler must return an AsyncGenerator or Promise<{ headers, stream }>.`, undefined, definitionInfo)
+      }
+    }
+
+    const registeredProcedure: THttpStreamProcedureRegistration<TContext> = {
+      name,
+      kind: 'http-stream',
+      config: {
+        path: config.path,
+        method: config.method,
+        scope: config.scope,
+        errors: config.errors as string[] | undefined,
+        description: config.description,
+        schema: jsonSchema as any,
+        validation: { req: validations.req, yield: validations.yield },
+        validateYields,
+      },
+      handler: wrappedHandler as any,
+    }
+
+    procedures.set(name, registeredProcedure as any)
+    builder?.onCreate?.(registeredProcedure)
+
+    const info = { name, kind: 'http-stream' as const, ...registeredProcedure.config }
+
+    // Explicit return type — preserves TReq/TYieldType/TReturnType through the public callable.
+    // Do NOT use `typeof registeredProcedure.handler` — that erases generics to `any`.
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as {
+      [K in TName]: (
+        ctx: Prettify<TContext>,
+        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+      ) => Promise<{
+        stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+        initialHeaders?: Record<string, string>
+      }>
+    } & {
+      procedure: (
+        ctx: Prettify<TContext>,
+        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+      ) => Promise<{
+        stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+        initialHeaders?: Record<string, string>
+      }>
+      info: typeof info
+    }
+  }
+}