ts-procedures 8.5.0 → 9.0.0

package/src/{stack-utils.ts → core/definition-site.ts}

@@ -1,6 +1,10 @@
 /**
- * Represents a specific location in source code where a procedure was defined.
+ * Captures WHERE a procedure was defined (file:line:column) at registration
+ * time, so every error a procedure ever throws can point back to its
+ * definition site — not just the call site.
  */
+
+/** A specific location in source code where a procedure was defined. */
 export type DefinitionLocation = {
   file: string
   line: number
@@ -8,21 +12,19 @@ export type DefinitionLocation = {
   raw: string
 }
 
-/**
- * Contains information about where a procedure was defined.
- */
+/** Definition-site info attached to registrations and errors. */
 export type DefinitionInfo = {
   definedAt?: DefinitionLocation
   definitionStack?: string
 }
 
 /**
- * Internal ts-procedures files that should be skipped when finding user code.
- * Only skip the core library files, not test files or user code.
+ * Library-internal files skipped when walking the stack for the user's frame.
+ * Only core library files — never test files or user code.
  */
 const INTERNAL_FILES = [
-  '/index.ts',
-  '/index.js',
+  '/procedures.ts',
+  '/procedures.js',
   '/create.ts',
   '/create.js',
   '/create-stream.ts',
@@ -31,19 +33,21 @@ const INTERNAL_FILES = [
   '/create-http.js',
   '/create-http-stream.ts',
   '/create-http-stream.js',
+  '/internal.ts',
+  '/internal.js',
   '/errors.ts',
   '/errors.js',
-  '/stack-utils.ts',
-  '/stack-utils.js',
+  '/definition-site.ts',
+  '/definition-site.js',
   '/compute-schema.ts',
   '/compute-schema.js',
-  '/parser.ts',
-  '/parser.js',
+  '/compile.ts',
+  '/compile.js',
 ]
 
 /**
- * Captures the stack trace at the call site and extracts the definition location.
- * Finds the first stack frame outside of ts-procedures internal files.
+ * Captures the stack trace at the call site and extracts the definition
+ * location: the first stack frame outside ts-procedures internals.
  */
 export function captureDefinitionInfo(): DefinitionInfo {
   const err = new Error()
@@ -55,8 +59,6 @@ export function captureDefinitionInfo(): DefinitionInfo {
 
   const lines = stack.split('\n')
 
-  // Find the first frame that's not from ts-procedures internals
-  // Skip the first line (Error message) and frames from this module
   let userFrame: string | undefined
 
   for (let i = 1; i < lines.length; i++) {
@@ -64,13 +66,11 @@ export function captureDefinitionInfo(): DefinitionInfo {
     if (!rawLine) continue
     const line = rawLine.trim()
 
-    // Skip empty or invalid frames
     if (!line.startsWith('at ')) {
       continue
     }
 
-    // Skip frames from ts-procedures internal source files
-    const isInternalFile = INTERNAL_FILES.some(file => line.includes(file))
+    const isInternalFile = INTERNAL_FILES.some((file) => line.includes(file))
     if (isInternalFile) {
       continue
     }
@@ -109,7 +109,6 @@ export function captureDefinitionInfo(): DefinitionInfo {
  * - "at /path/to/file.ts:10:5"
  */
 function parseStackFrame(frame: string): DefinitionLocation | undefined {
-  // Match patterns like "(path:line:column)" or just "path:line:column"
   const match = frame.match(/\(([^)]+):(\d+):(\d+)\)$/) || frame.match(/at ([^:]+):(\d+):(\d+)$/)
 
   if (match && match[1] && match[2] && match[3]) {
@@ -124,9 +123,7 @@ function parseStackFrame(frame: string): DefinitionLocation | undefined {
   return undefined
 }
 
-/**
- * Formats definition info for appending to error stacks.
- */
+/** Formats definition info for appending to error stacks. */
 export function formatDefinitionInfo(info: DefinitionInfo, procedureName: string): string | undefined {
   if (!info.definedAt) {
     return undefined

package/src/{errors.test.ts → core/errors.test.ts}

@@ -4,7 +4,7 @@ import {
   ProcedureValidationError,
   ProcedureRegistrationError,
 } from './errors.js'
-import type { DefinitionInfo } from './stack-utils.js'
+import type { DefinitionInfo } from './definition-site.js'
 
 describe('Error Classes', () => {
   test('ProcedureError has correct properties', () => {

package/src/{errors.ts → core/errors.ts}

@@ -1,9 +1,19 @@
-import type { TSchemaValidationError } from './schema/parser.js'
-import type { DefinitionInfo, DefinitionLocation} from './stack-utils.js';
-import { formatDefinitionInfo } from './stack-utils.js'
 import { kebabCase } from 'es-toolkit/string'
+import type { TSchemaValidationError } from '../schema/compile.js'
+import type { DefinitionInfo, DefinitionLocation } from './definition-site.js'
+import { formatDefinitionInfo } from './definition-site.js'
 
+/** Discriminant carried by every framework error (alternative to `instanceof`). */
+export type ProcedureErrorKind = 'procedure' | 'validation' | 'yield-validation' | 'registration'
+
+/**
+ * Base error for everything the framework throws. Produced by `ctx.error()`
+ * in handlers, and used to box non-ProcedureError throws (with the original
+ * error as `cause`). Carries the procedure's definition site so stack traces
+ * point at the definition, not just the call.
+ */
 export class ProcedureError extends Error {
+  readonly kind: ProcedureErrorKind = 'procedure'
   cause?: unknown
   readonly definedAt?: DefinitionLocation
   readonly definitionStack?: string
@@ -12,8 +22,7 @@ export class ProcedureError extends Error {
     readonly procedureName: string,
     readonly message: string,
     readonly meta?: object,
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
+    definitionInfo?: DefinitionInfo,
   ) {
     super(message)
     this.name = 'ProcedureError'
@@ -25,12 +34,10 @@ export class ProcedureError extends Error {
     }
 
     // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureError.prototype)
+    Object.setPrototypeOf(this, new.target.prototype)
   }
 
-  /**
-   * Returns a formatted string showing where the procedure was defined.
-   */
+  /** Returns `file:line:column` of the procedure definition, when captured. */
   getDefinitionLocation(): string | undefined {
     if (!this.definedAt) {
       return undefined
@@ -38,9 +45,7 @@ export class ProcedureError extends Error {
     return `${this.definedAt.file}:${this.definedAt.line}:${this.definedAt.column}`
   }
 
-  /**
-   * Enhances the error stack with definition location information.
-   */
+  /** Appends the definition-site section to the error stack. */
   private enhanceStack(): void {
     if (!this.stack || !this.definedAt) {
       return
@@ -48,7 +53,7 @@ export class ProcedureError extends Error {
 
     const definitionSection = formatDefinitionInfo(
       { definedAt: this.definedAt, definitionStack: this.definitionStack },
-      this.procedureName
+      this.procedureName,
     )
 
     if (definitionSection) {
@@ -57,52 +62,49 @@ export class ProcedureError extends Error {
   }
 }
 
+/** Schema validation failure for params / req channels (400 in the default taxonomy). */
 export class ProcedureValidationError extends ProcedureError {
+  override readonly kind = 'validation'
+
   constructor(
     readonly procedureName: string,
     message: string,
     readonly errors?: TSchemaValidationError[],
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
+    definitionInfo?: DefinitionInfo,
   ) {
     const readableErrors = errors
       ?.map((err) => `- ${kebabCase(err.instancePath).replace('-', '.')} ${err.message}`)
       .join(', ')
     super(procedureName, message + ' ' + readableErrors, { errors }, definitionInfo)
     this.name = 'ProcedureValidationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureValidationError.prototype)
   }
 }
 
+/** Invalid registration: bad schema, duplicate name, misplaced config fields. */
 export class ProcedureRegistrationError extends ProcedureError {
+  override readonly kind = 'registration'
+
   constructor(
     readonly procedureName: string,
     message: string,
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
+    definitionInfo?: DefinitionInfo,
   ) {
     super(procedureName, message, undefined, definitionInfo)
     this.name = 'ProcedureRegistrationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureRegistrationError.prototype)
   }
 }
 
+/** Stream yield failed schema validation (only with `validateYields: true`). */
 export class ProcedureYieldValidationError extends ProcedureError {
+  override readonly kind = 'yield-validation'
+
   constructor(
     readonly procedureName: string,
     message: string,
     readonly errors?: TSchemaValidationError[],
-    // Used for error stack trace details
-    definitionInfo?: DefinitionInfo
+    definitionInfo?: DefinitionInfo,
   ) {
     super(procedureName, message, undefined, definitionInfo)
     this.name = 'ProcedureYieldValidationError'
-
-    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
-    Object.setPrototypeOf(this, ProcedureYieldValidationError.prototype)
   }
 }

package/src/core/factory-options.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from './procedures.js'
+import { ProcedureValidationError } from './errors.js'
+import type { SchemaAdapter } from '../schema/adapter.js'
+
+describe('Procedures factory options (new in v9)', () => {
+  describe('schema.adapters', () => {
+    // A minimal stand-in for a zod/valibot-style adapter: schema objects carry
+    // their JSON Schema under a custom marker key.
+    const fakeLibAdapter: SchemaAdapter = {
+      name: 'fake-lib',
+      detect: (s): boolean =>
+        typeof s === 'object' && s !== null && '__fakeJsonSchema' in s,
+      toJsonSchema: (s) => (s as { __fakeJsonSchema: Record<string, any> }).__fakeJsonSchema,
+    }
+    const fakeSchema = {
+      __fakeJsonSchema: {
+        type: 'object',
+        properties: { id: { type: 'string' } },
+        required: ['id'],
+      },
+    }
+
+    it('registers and validates with a custom schema adapter', async () => {
+      const { Create } = Procedures({ schema: { adapters: [fakeLibAdapter] } })
+      const { GetThing } = Create('GetThing', { schema: { params: fakeSchema } }, async (_ctx, params) => params)
+
+      await expect(GetThing({}, { id: 'a' } as never)).resolves.toEqual({ id: 'a' })
+      await expect(GetThing({}, {} as never)).rejects.toThrow(ProcedureValidationError)
+    })
+
+    it('custom adapters take precedence over the built-in TypeBox adapter', () => {
+      // An adapter that recognizes EVERYTHING and maps to a permissive schema —
+      // if it runs first, a TypeBox schema never reaches the typebox adapter.
+      const greedy: SchemaAdapter = {
+        name: 'greedy',
+        detect: () => true,
+        toJsonSchema: () => ({ type: 'object' }),
+      }
+      const { Create } = Procedures({ schema: { adapters: [greedy] } })
+      const { Info } = { Info: Create('Info', { schema: { params: Type.Object({ n: Type.Number() }) } }, async () => 'ok') }
+      expect(Info.info.schema.params).toEqual({ type: 'object' })
+    })
+
+    it('TypeBox keeps working with custom adapters present', async () => {
+      const { Create } = Procedures({ schema: { adapters: [fakeLibAdapter] } })
+      const { Echo } = Create('Echo', { schema: { params: Type.Object({ n: Type.Number() }) } }, async (_ctx, p) => p)
+      await expect(Echo({}, { n: 1 })).resolves.toEqual({ n: 1 })
+    })
+  })
+
+  describe('validation.ajv', () => {
+    it('merges custom AJV options over the defaults', async () => {
+      const { Create } = Procedures({ validation: { ajv: { coerceTypes: false } } })
+      const { Strict } = Create('Strict', { schema: { params: Type.Object({ n: Type.Number() }) } }, async (_ctx, p) => p)
+
+      // Default config would coerce '1' → 1; with coerceTypes off it must fail.
+      await expect(Strict({}, { n: '1' } as never)).rejects.toThrow(ProcedureValidationError)
+      await expect(Strict({}, { n: 1 })).resolves.toEqual({ n: 1 })
+    })
+  })
+
+  describe('http defaults', () => {
+    const reqId = { req: { pathParams: Type.Object({ id: Type.String() }) } }
+
+    it('applies pathPrefix and scope to CreateHttp routes', () => {
+      const { CreateHttp } = Procedures({ http: { pathPrefix: '/v1', scope: 'billing' } })
+      const { info } = CreateHttp(
+        'GetInvoice',
+        { path: '/invoices/:id', method: 'get', schema: reqId },
+        async () => undefined,
+      )
+      expect(info.path).toBe('/v1/invoices/:id')
+      expect(info.scope).toBe('billing')
+    })
+
+    it('per-route scope wins over the factory default', () => {
+      const { CreateHttp } = Procedures({ http: { scope: 'billing' } })
+      const { info } = CreateHttp(
+        'GetReport',
+        { path: '/reports', method: 'get', scope: 'reports', schema: {} },
+        async () => undefined,
+      )
+      expect(info.scope).toBe('reports')
+      expect(info.path).toBe('/reports')
+    })
+
+    it('applies pathPrefix to CreateHttpStream routes', () => {
+      const { CreateHttpStream } = Procedures({ http: { pathPrefix: 'v1' } })
+      const { info } = CreateHttpStream(
+        'Watch',
+        { path: 'watch', method: 'get', schema: {} },
+        // eslint-disable-next-line require-yield
+        async function* () { return undefined },
+      )
+      // both prefix and path get normalized to a single joining slash
+      expect(info.path).toBe('/v1/watch')
+    })
+
+    it('path-param consistency is checked against the prefixed path', () => {
+      const { CreateHttp } = Procedures({ http: { pathPrefix: '/v1' } })
+      expect(() =>
+        CreateHttp(
+          'Bad',
+          { path: '/things/:id', method: 'get', schema: {} },
+          async () => undefined,
+        ),
+      ).toThrow(/path parameters \[id\] but schema\.req\.pathParams is not defined/)
+    })
+  })
+})

package/src/core/http-route.ts

@@ -0,0 +1,73 @@
+/**
+ * Route-shape helpers shared by CreateHttp and CreateHttpStream.
+ */
+import { ProcedureRegistrationError } from './errors.js'
+import type { DefinitionInfo } from './definition-site.js'
+
+const PATH_PARAM_RE = /:([a-zA-Z_][a-zA-Z0-9_]*)/g
+
+export function extractPathParamNames(path: string): string[] {
+  const matches = path.match(PATH_PARAM_RE)
+  return matches ? matches.map((m) => m.slice(1)) : []
+}
+
+/**
+ * Applies the factory-level `http.pathPrefix` default to a route path.
+ * Both sides are normalized to exactly one joining `/`.
+ */
+export function applyPathPrefix(prefix: string | undefined, path: string): string {
+  if (!prefix) return path
+  const normalizedPrefix = prefix.startsWith('/') ? prefix : `/${prefix}`
+  const trimmedPrefix = normalizedPrefix.endsWith('/') ? normalizedPrefix.slice(0, -1) : normalizedPrefix
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`
+  return `${trimmedPrefix}${normalizedPath}`
+}
+
+/**
+ * Registration-time guard: the `:params` in the path and the keys of
+ * `schema.req.pathParams` must agree exactly. Catches typos where a handler
+ * would silently receive `undefined` for a misspelled param.
+ */
+export function checkPathParamConsistency(
+  procedureName: string,
+  path: string,
+  pathParamsSchema: Record<string, unknown> | undefined,
+  definitionInfo: DefinitionInfo,
+): void {
+  const pathParamNames = extractPathParamNames(path)
+  const hasPathParams = pathParamNames.length > 0
+  const hasSchema = pathParamsSchema !== undefined
+
+  if (hasPathParams && !hasSchema) {
+    throw new ProcedureRegistrationError(
+      procedureName,
+      `Path "${path}" has path parameters [${pathParamNames.join(', ')}] but schema.req.pathParams is not defined.`,
+      definitionInfo,
+    )
+  }
+  if (!hasPathParams && hasSchema) {
+    throw new ProcedureRegistrationError(
+      procedureName,
+      `schema.req.pathParams is defined but path "${path}" has no path parameters.`,
+      definitionInfo,
+    )
+  }
+  if (hasPathParams && hasSchema) {
+    const schemaProperties = (pathParamsSchema as { properties?: Record<string, unknown> }).properties
+    if (schemaProperties) {
+      const schemaKeys = Object.keys(schemaProperties)
+      const missing = pathParamNames.filter((p) => !schemaKeys.includes(p))
+      const extra = schemaKeys.filter((k) => !pathParamNames.includes(k))
+      if (missing.length > 0 || extra.length > 0) {
+        const parts: string[] = []
+        if (missing.length > 0) parts.push(`path has [${missing.join(', ')}] missing from schema`)
+        if (extra.length > 0) parts.push(`schema has [${extra.join(', ')}] not in path`)
+        throw new ProcedureRegistrationError(
+          procedureName,
+          `Path param mismatch for "${procedureName}": ${parts.join('; ')}.`,
+          definitionInfo,
+        )
+      }
+    }
+  }
+}

package/src/core/internal.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared machinery for the four creators. Everything here is package-private:
+ * the public API is `Procedures()` and the creators it returns.
+ */
+import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
+import type { DefinitionInfo } from './definition-site.js'
+import type { AnyProcedureRegistration } from './types.js'
+import type { SchemaAdapter } from '../schema/adapter.js'
+import type { Validate, ValidatorCompiler } from '../schema/compile.js'
+
+/**
+ * Everything a creator needs from its owning factory, resolved once in
+ * `Procedures()`.
+ */
+export type FactoryRuntime<TContext, TExtendedConfig> = {
+  registry: Map<string, AnyProcedureRegistration<TContext, TExtendedConfig>>
+  onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
+  /** True when the factory was created with `validation: false`. */
+  skipValidation: boolean
+  adapters: readonly SchemaAdapter[]
+  compile: ValidatorCompiler
+  httpDefaults?: { pathPrefix?: string; scope?: string }
+}
+
+const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
+
+/** Create/CreateStream reject HTTP-only config fields with a pointer to CreateHttp. */
+export function assertNoHttpFields(
+  creatorName: 'Create' | 'CreateStream',
+  procedureName: string,
+  config: Record<string, unknown>,
+  definitionInfo: DefinitionInfo,
+): void {
+  const presentHttpFields = HTTP_FIELDS.filter((f) => config[f] !== undefined)
+  if (presentHttpFields.length > 0) {
+    throw new ProcedureRegistrationError(
+      procedureName,
+      `HTTP fields require CreateHttp / CreateHttpStream. Procedure "${procedureName}" has [${presentHttpFields.join(', ')}] which are not valid on ${creatorName}.`,
+      definitionInfo,
+    )
+  }
+}
+
+/** Duplicate names fail fast, BEFORE schema computation. */
+export function assertNotDuplicate(
+  registry: Map<string, unknown>,
+  name: string,
+  definitionInfo: DefinitionInfo,
+): void {
+  if (registry.has(name)) {
+    throw new ProcedureRegistrationError(
+      name,
+      `Procedure with name ${name} is already registered`,
+      definitionInfo,
+    )
+  }
+}
+
+/**
+ * Should this call skip runtime validation? Either the caller already
+ * validated (`ctx.isPrevalidated`, set by HTTP builders) or the whole factory
+ * opted out (`validation: false`).
+ */
+export function shouldSkipValidation(ctx: unknown, runtime: { skipValidation: boolean }): boolean {
+  return Boolean((ctx as { isPrevalidated?: boolean })?.isPrevalidated) || runtime.skipValidation
+}
+
+/** Validates RPC params; throws `ProcedureValidationError` on failure. */
+export function validateParams(
+  name: string,
+  validate: Validate | undefined,
+  params: unknown,
+  definitionInfo: DefinitionInfo,
+): void {
+  if (!validate) return
+  const { errors } = validate(params)
+  if (errors) {
+    throw new ProcedureValidationError(name, `Validation error for ${name}`, errors, definitionInfo)
+  }
+}
+
+/** Validates each HTTP req channel independently; error messages name the channel. */
+export function validateReqChannels(
+  name: string,
+  validators: Record<string, Validate> | undefined,
+  req: unknown,
+  definitionInfo: DefinitionInfo,
+): void {
+  if (!validators) return
+  for (const [channel, validate] of Object.entries(validators)) {
+    const channelValue = (req as Record<string, unknown> | undefined)?.[channel]
+    const { errors } = validate(channelValue)
+    if (errors) {
+      throw new ProcedureValidationError(
+        name,
+        `Validation error for ${name} in req.${channel}`,
+        errors,
+        definitionInfo,
+      )
+    }
+  }
+}
+
+/**
+ * Boxes a non-ProcedureError thrown by a unary handler into a ProcedureError
+ * (original error as `cause`), preserving the original stack and appending
+ * the definition site. ProcedureErrors pass through untouched.
+ */
+export function toProcedureError(
+  name: string,
+  definitionInfo: DefinitionInfo,
+  error: any,
+): ProcedureError {
+  if (error instanceof ProcedureError) return error
+  const err = new ProcedureError(
+    name,
+    `Error in handler for ${name} - ${error?.message}`,
+    undefined,
+    definitionInfo,
+  )
+  err.cause = error
+  if (error?.stack && definitionInfo.definedAt) {
+    const { file, line, column } = definitionInfo.definedAt
+    err.stack =
+      error.stack + `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+  } else if (error?.stack) {
+    err.stack = error.stack
+  }
+  return err
+}
+
+/** Appends the definition site to a thrown error's stack, in place. */
+export function appendDefinitionSite(error: any, name: string, definitionInfo: DefinitionInfo): void {
+  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}`
+  }
+}
+
+/** Combines an incoming (e.g. HTTP request) signal with the stream's own controller. */
+export function combineSignals(incoming: AbortSignal | undefined, own: AbortSignal): AbortSignal {
+  return incoming ? AbortSignal.any([incoming, own]) : own
+}
+
+/**
+ * Drives a user stream iterator with the framework guarantees shared by
+ * CreateStream and CreateHttpStream:
+ * - optional per-yield validation (`validateYields: true`)
+ * - errors get the definition site appended to their stack — but keep their
+ *   original class, so HTTP taxonomies and typed-error dispatch see the real
+ *   thrown value
+ * - on ANY exit, the user iterator's `return()` runs (its `finally` blocks
+ *   fire on early consumer close) and the controller aborts with reason
+ *   `'stream-completed'` so handlers can distinguish completion from client
+ *   disconnect
+ * - the user generator's return value is propagated (becomes the
+ *   `event: 'return'` SSE payload downstream)
+ */
+export async function* iterateWithGuards(
+  userIterator: AsyncIterator<any, any, unknown>,
+  options: {
+    name: string
+    validateYields: boolean
+    validateYield: Validate | undefined
+    abortController: AbortController
+    definitionInfo: DefinitionInfo
+  },
+): AsyncGenerator<any, any, unknown> {
+  const { name, validateYields, validateYield, abortController, definitionInfo } = options
+  try {
+    let result = await userIterator.next()
+    while (!result.done) {
+      const value = result.value
+      if (validateYields && validateYield) {
+        const { errors } = validateYield(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) {
+    appendDefinitionSite(error, name, definitionInfo)
+    throw error
+  } finally {
+    // Propagate `.return()` to the user generator so its `finally` blocks run
+    // when the consumer closes the stream early. No-op when iteration already
+    // completed.
+    try {
+      await userIterator.return?.(undefined)
+    } catch {
+      // Swallow — cleanup must not mask the primary error path
+    }
+    abortController.abort('stream-completed')
+  }
+}

package/src/{migration.test.ts → core/migration.test.ts}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { Procedures } from './index.js'
+import { Procedures } from './procedures.js'
 import { ProcedureRegistrationError } from './errors.js'
 import { Type } from 'typebox'
 
@@ -24,6 +24,28 @@ describe('v7 → v8 migration errors', () => {
   })
 })
 
+describe('schema.params rejected on HTTP creators', () => {
+  it('CreateHttp rejects schema.params with migration message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttp('LegacyHttp', {
+        path: '/x', method: 'get',
+        schema: { params: Type.Object({}) } as any,
+      }, async () => undefined)
+    ).toThrow(/Use schema.req.body \(or schema.req.query\) instead of schema.params/)
+  })
+
+  it('CreateHttpStream rejects schema.params with migration message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttpStream('LegacyHttpStream', {
+        path: '/x', method: 'get',
+        schema: { params: Type.Object({}), yield: Type.Number() } as any,
+      }, async function* () {})
+    ).toThrow(/Use schema.req.body \(or schema.req.query\) instead of schema.params/)
+  })
+})
+
 describe('HTTP fields rejected on RPC creators', () => {
   const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const