ts-procedures 7.0.0 → 7.1.1

package/src/codegen/emit-types.ts

@@ -133,13 +133,16 @@ export async function jsonSchemaToExtractedTypes(
   const declarations: string[] = []
   let body = ''
 
+  // Match `export type Root =` strictly — `Root` must be followed by `=` (with
+  // optional whitespace), so sibling extracted names like `RootType` (which
+  // ajsc emits for an `Array<RootType>` root schema) fall through to the
+  // declarations branch instead of being eaten as the body.
+  const rootDeclPattern = /^export\s+type\s+Root\s*=\s*/
+
   for (const block of blocks) {
-    if (block.startsWith('export type Root')) {
+    if (rootDeclPattern.test(block)) {
       // Strip "export type Root = " prefix and trailing ";"
-      body = block
-        .replace(/^export\s+type\s+Root\s*=\s*/, '')
-        .replace(/;\s*$/, '')
-        .trim()
+      body = block.replace(rootDeclPattern, '').replace(/;\s*$/, '').trim()
     } else {
       // Sub-type or enum declaration — remove trailing ";" for consistency
       declarations.push(block.replace(/;\s*$/, ''))
@@ -156,3 +159,78 @@ export async function jsonSchemaToExtractedTypes(
 
   return { declarations, body }
 }
+
+/**
+ * Returns the declared name of an `export type|enum|interface X = …` block,
+ * or `undefined` if none can be parsed. Used by `renameExtractedTypes` to
+ * detect collisions between ajsc-extracted sub-types and reserved identifiers.
+ */
+export function extractedDeclName(decl: string): string | undefined {
+  const m = decl.match(/^export\s+(?:type|enum|interface)\s+(\w+)/)
+  return m?.[1]
+}
+
+/**
+ * Rewrites an {@link ExtractedTypeOutput} to avoid identifier collisions.
+ *
+ * ajsc with `inlineTypes: false` derives sub-type names from the parent
+ * property's name — so a schema property literally called `params` produces
+ * `export type Params = {…}`. When that collides with the route's own
+ * `Params` shortName (or any other reserved name), the resulting namespace
+ * has duplicate `export type Params` declarations and won't compile.
+ *
+ * This helper takes:
+ *   - `result`: the raw ajsc output for one schema
+ *   - `taken`: a set of names that are NOT free to use (mutated as renames
+ *     are applied so subsequent calls share the same allocation map)
+ *
+ * For every extracted declaration whose name is already in `taken`, a unique
+ * alias is generated (`Params` → `ParamsInner`, then `ParamsInner2`, …) so
+ * the renamed type reads like a real, intentional name (not a placeholder).
+ * The declaration is rewritten with the new name and every word-boundary
+ * occurrence in `result.body` is substituted so the body keeps referencing
+ * the renamed type.
+ */
+export function renameExtractedTypes(
+  result: ExtractedTypeOutput,
+  taken: Set<string>,
+): ExtractedTypeOutput {
+  let body = result.body
+  const declarations: string[] = []
+
+  for (const decl of result.declarations) {
+    const name = extractedDeclName(decl)
+    if (name == null) {
+      declarations.push(decl)
+      continue
+    }
+    if (!taken.has(name)) {
+      taken.add(name)
+      declarations.push(decl)
+      continue
+    }
+
+    // Allocate a unique alias. `Inner` reads as an intentional name (the
+    // sub-type referenced *by* the conflicting outer type) rather than the
+    // `_` suffix which looks like a forgotten placeholder.
+    let alias = `${name}Inner`
+    let suffix = 2
+    while (taken.has(alias)) {
+      alias = `${name}Inner${suffix}`
+      suffix += 1
+    }
+    taken.add(alias)
+
+    // Rewrite the declaration's leading identifier.
+    const renamedDecl = decl.replace(
+      new RegExp(`^(export\\s+(?:type|enum|interface)\\s+)${name}\\b`),
+      `$1${alias}`,
+    )
+    declarations.push(renamedDecl)
+
+    // Patch every word-boundary occurrence of the old name in the body.
+    body = body.replace(new RegExp(`\\b${name}\\b`, 'g'), alias)
+  }
+
+  return { declarations, body }
+}

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

@@ -53,6 +53,17 @@ describe('resolveEnvelope', () => {
     await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow(/routes/)
   })
 
+  // Defensive (downstream bug repro): forgetting `builder.build()` is a common
+  // cause of an empty routes array because hono-rpc/hono-api/hono-stream/express-rpc
+  // builders only populate their `_docs` array inside `build()`. The current
+  // error message says "Register at least one procedure", which led the
+  // downstream dev to look in the wrong place. The message should mention
+  // `.build()` as a likely cause so the next person hits the right fix faster.
+  it('empty-routes error message mentions builder.build() as a likely cause', async () => {
+    const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
+    await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow(/\.build\(\)/)
+  })
+
   it('throws when routes array is empty (file input)', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'ts-proc-test-'))
     const filePath = join(dir, 'empty.json')

package/src/codegen/resolve-envelope.ts

@@ -53,7 +53,10 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
 
   if (envelope.routes.length === 0) {
     throw new Error(
-      '[ts-procedures-codegen] DocEnvelope has an empty "routes" array. Register at least one procedure before generating.'
+      '[ts-procedures-codegen] DocEnvelope has an empty "routes" array. ' +
+      'Common causes: (1) you forgot to call `builder.build()` before passing ' +
+      'the builder to `DocRegistry.from(...)` — hono/express builders only populate ' +
+      '`docs` inside `build()`; (2) no procedures registered with the builder.'
     )
   }
 

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

@@ -0,0 +1,56 @@
+import { execSync } from 'node:child_process'
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Default tsconfig used by codegen e2e tests when none is supplied.
+ * Mirrors what consumers running `tsc --strict` typically use, plus the
+ * codegen output's expected module/target settings.
+ */
+export const DEFAULT_E2E_TSCONFIG = {
+  compilerOptions: {
+    strict: true,
+    target: 'ES2022',
+    module: 'ES2022',
+    moduleResolution: 'bundler',
+    noEmit: true,
+    skipLibCheck: true,
+  },
+  include: ['**/*.ts'],
+} as const
+
+/**
+ * Runs `tsc --noEmit` on the given tsconfig and throws an `AssertionError`-style
+ * message that includes captured stderr/stdout when compilation fails. Returns
+ * silently on success.
+ *
+ * Replaces the previously-duplicated try/execSync/stderr-format dance that
+ * appeared in 5+ places in `e2e.test.ts` — keeps tests focused on what they
+ * generated, not how they shell out to tsc.
+ *
+ * `tsconfigInline` is written to `tmpDir/tsconfig.json` automatically; pass
+ * `tsconfigPath` instead to point at an existing file.
+ */
+export function runTsc(args: {
+  tmpDir: string
+  tsconfigInline?: Record<string, unknown>
+  tsconfigPath?: string
+}): void {
+  const tsconfigPath = args.tsconfigPath ?? join(args.tmpDir, 'tsconfig.json')
+  if (args.tsconfigInline != null) {
+    writeFileSync(tsconfigPath, JSON.stringify(args.tsconfigInline))
+  }
+
+  const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
+  try {
+    execSync(`${tscPath} --noEmit --project ${tsconfigPath}`, { stdio: 'pipe' })
+  } catch (err) {
+    const e = err as { stdout?: Buffer; stderr?: Buffer; message?: string }
+    const stdout = e.stdout?.toString() ?? ''
+    const stderr = e.stderr?.toString() ?? ''
+    const combined = [stdout, stderr].filter(Boolean).join('\n').trim()
+    throw new Error(
+      `[runTsc] tsc failed for ${tsconfigPath}:\n${combined || (e.message ?? '(no output)')}`,
+    )
+  }
+}

package/src/implementations/http/doc-registry.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it, test } from 'vitest'
+import { describe, expect, it, test, vi, afterEach } from 'vitest'
 import { v } from 'suretype'
 import { Procedures } from '../../index.js'
 import { HonoRPCAppBuilder } from './hono-rpc/index.js'
@@ -538,6 +538,48 @@ describe('DocRegistry', () => {
       expect(parsed.routes[0].name).toBe('Echo')
     })
 
+    describe('coverage warnings via skippedProcedures', () => {
+      afterEach(() => {
+        vi.restoreAllMocks()
+        delete process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS
+      })
+
+      test('warns when sources expose skippedProcedures entries', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+        const sourceWithSkipped: DocSource<RPCHttpRouteDoc> = {
+          docs: [rpcDoc],
+          skippedProcedures: [
+            { name: 'StreamProc', reason: 'wrong builder' },
+          ],
+        }
+
+        new DocRegistry().from(sourceWithSkipped).toJSON()
+
+        expect(warnSpy).toHaveBeenCalledOnce()
+        const message = warnSpy.mock.calls[0]![0] as string
+        expect(message).toContain('1 procedure(s)')
+        expect(message).toContain('StreamProc')
+        expect(message).toContain('wrong builder')
+      })
+
+      test('does not warn when sources have no skippedProcedures', () => {
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+        new DocRegistry().from(makeSource([rpcDoc])).toJSON()
+        expect(warnSpy).not.toHaveBeenCalled()
+      })
+
+      test('TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS=1 silences the warning', () => {
+        process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS = '1'
+        const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+        const source: DocSource<RPCHttpRouteDoc> = {
+          docs: [rpcDoc],
+          skippedProcedures: [{ name: 'X', reason: 'y' }],
+        }
+        new DocRegistry().from(source).toJSON()
+        expect(warnSpy).not.toHaveBeenCalled()
+      })
+    })
+
     test('accepts a real HonoRPCAppBuilder as source', () => {
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 

package/src/implementations/http/doc-registry.ts

@@ -88,6 +88,25 @@ export class DocRegistry {
       routes = routes.filter(options.filter)
     }
 
+    // Surface coverage gaps — when a builder skipped procedures (e.g. a
+    // streaming procedure registered with HonoRPCAppBuilder), the per-builder
+    // warning fires once at `build()` time, but consumers who only call
+    // `registry.toJSON()` (e.g. to dump the envelope to disk for codegen)
+    // wouldn't see it without this aggregate. Single warning per call,
+    // suppressed when the env var is set so CI pipelines stay quiet.
+    if (process.env.TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS !== '1') {
+      const skipped = this.sources.flatMap((source) => source.skippedProcedures ?? [])
+      if (skipped.length > 0) {
+        const lines = skipped.map(
+          ({ name, reason }) => `  - "${name}": ${reason}`
+        )
+        console.warn(
+          `[ts-procedures DocRegistry] ${skipped.length} procedure(s) registered with a builder but not served — they will be missing from the doc envelope:\n${lines.join('\n')}\n` +
+          `(Suppress with TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS=1)`
+        )
+      }
+    }
+
     const envelope: DocEnvelope = {
       basePath: this.basePath,
       headers: [...this.headers],

package/src/implementations/http/hono-rpc/index.test.ts

@@ -598,6 +598,38 @@ describe('HonoRPCAppBuilder', () => {
 
       expect(res.status).toBe(404)
     })
+
+    test('skips streaming procedures and tracks them in skippedProcedures', async () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+      try {
+        const builder = new HonoRPCAppBuilder()
+        const RPC = Procedures<{}, RPCConfig>()
+
+        RPC.Create('RegularProc', { scope: 'test', version: 1 }, async () => ({ ok: true }))
+        RPC.CreateStream('StreamProc', { scope: 'test', version: 1 }, async function* () {
+          yield { msg: 'stream' }
+        })
+
+        builder.register(RPC, () => ({}))
+        builder.build()
+
+        // Only the regular procedure makes it into docs
+        expect(builder.docs).toHaveLength(1)
+        expect(builder.docs[0]!.name).toBe('RegularProc')
+
+        // Stream proc surfaces via skippedProcedures
+        expect(builder.skippedProcedures).toHaveLength(1)
+        expect(builder.skippedProcedures[0]!.name).toBe('StreamProc')
+        expect(builder.skippedProcedures[0]!.reason).toMatch(/HonoStreamAppBuilder/)
+
+        // And we logged a warning so devs aren't blindsided
+        expect(warnSpy).toHaveBeenCalledWith(
+          expect.stringContaining('Skipping procedure "StreamProc"')
+        )
+      } finally {
+        warnSpy.mockRestore()
+      }
+    })
   })
 
   // --------------------------------------------------------------------------

package/src/implementations/http/hono-rpc/index.ts

@@ -151,6 +151,7 @@ export class HonoRPCAppBuilder {
 
   private _app: Hono = new Hono()
   private _docs: (RPCHttpRouteDoc & object)[] = []
+  private _skipped: { name: string; reason: string }[] = []
 
   get app(): Hono {
     return this._app
@@ -160,6 +161,16 @@ export class HonoRPCAppBuilder {
     return this._docs
   }
 
+  /**
+   * Procedures that were skipped at `build()` time because they don't fit
+   * this builder (e.g. streaming procedures registered against an RPC
+   * builder). Surfaced via `DocSource.skippedProcedures` so DocRegistry can
+   * warn about coverage gaps.
+   */
+  get skippedProcedures(): { name: string; reason: string }[] {
+    return this._skipped
+  }
+
   /**
    * Registers a procedure factory with its context.
    * @param factory - The procedure factory created by Procedures<Context, RPCConfig>()
@@ -189,7 +200,22 @@ export class HonoRPCAppBuilder {
    */
   build(): Hono {
     this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
-      factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
+      factory.getProcedures().forEach((procedure: TProcedureRegistration<any, RPCConfig>) => {
+        // Skip streaming procedures — RPC builder cannot serve them. Without
+        // this guard, the procedure would silently get a POST route that
+        // returns its async generator object as a JSON response, which is not
+        // a useful failure mode. Procedures meant to stream should be
+        // registered with HonoStreamAppBuilder.
+        if ((procedure as { isStream?: boolean }).isStream === true) {
+          const reason =
+            'Streaming procedure registered with HonoRPCAppBuilder — register it with HonoStreamAppBuilder instead.'
+          this._skipped.push({ name: procedure.name, reason })
+          console.warn(
+            `[ts-procedures hono-rpc] Skipping procedure "${procedure.name}": ${reason}`
+          )
+          return
+        }
+
         const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
 
         this._docs.push(route)

package/src/implementations/http/hono-stream/error-taxonomy.test.ts

@@ -96,3 +96,83 @@ describe('HonoStreamAppBuilder — error taxonomy (pre-stream)', () => {
     expect(await res.json()).toEqual({ name: 'ServiceUnavailable' })
   })
 })
+
+describe('HonoStreamAppBuilder — error taxonomy (mid-stream)', () => {
+  test('taxonomy resolves the body for a typed error thrown mid-stream (SSE)', async () => {
+    const errors = defineErrorTaxonomy({
+      AuthError: {
+        class: AuthError,
+        statusCode: 403,
+        toResponse: (err) => ({ name: 'AuthError', reason: err.reason }),
+      },
+    })
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new AuthError('forbidden')
+    })
+
+    const app = new HonoStreamAppBuilder({ errors })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    expect(res.status).toBe(200) // status committed before error
+    const text = await res.text()
+    // Last event is the error event with the resolved body shape
+    expect(text).toContain('event: error')
+    expect(text).toContain('"name":"AuthError"')
+    expect(text).toContain('"reason":"forbidden"')
+  })
+
+  test('onMidStreamError still runs as fallback when taxonomy does not match', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new TypeError('mid-stream boom')
+    })
+
+    const app = new HonoStreamAppBuilder({
+      errors: {
+        AuthError: {
+          class: AuthError,
+          statusCode: 403,
+          toResponse: () => ({ name: 'AuthError', reason: 'forbidden' }),
+        },
+      },
+      onMidStreamError: (_p, _c, err) => ({ data: { name: 'FallbackError', message: err.message } }),
+    })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    const text = await res.text()
+    expect(text).toContain('"name":"FallbackError"')
+    expect(text).toContain('mid-stream boom')
+  })
+
+  test('mid-stream typed body falls through to text mode', async () => {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { msg: 'first' }
+      throw new AuthError('forbidden')
+    })
+    const app = new HonoStreamAppBuilder({
+      defaultStreamMode: 'text',
+      errors: {
+        AuthError: {
+          class: AuthError,
+          statusCode: 403,
+          toResponse: () => ({ name: 'AuthError', reason: 'forbidden' }),
+        },
+      },
+    })
+      .register(RPC, () => ({}))
+      .build()
+
+    const res = await app.request('/test/stream/1', { method: 'POST' })
+    const text = await res.text()
+    expect(text).toContain('"name":"AuthError"')
+    expect(text).toContain('"reason":"forbidden"')
+  })
+})

package/src/implementations/http/hono-stream/index.test.ts

@@ -890,7 +890,7 @@ describe('HonoStreamAppBuilder', () => {
 
       const doc = builder.docs[0]!
       expect(doc.path).toBe('/messages/stream-messages/1')
-      expect(doc.methods).toEqual(['get', 'post'])
+      expect(doc.methods).toEqual(['post', 'get'])
       expect(doc.streamMode).toBe('sse')
       expect(doc.jsonSchema.params).toBeDefined()
       expect(doc.jsonSchema.returnType).toBeDefined()
@@ -1111,7 +1111,7 @@ describe('HonoStreamAppBuilder', () => {
       // Base properties should NOT be overridden
       expect(doc.name).toBe('Test')
       expect(doc.path).toBe('/test/test/1')
-      expect(doc.methods).toEqual(['get', 'post'])
+      expect(doc.methods).toEqual(['post', 'get'])
       // Custom field should be present
       expect(doc).toHaveProperty('customField', 'custom-value')
     })
@@ -1779,7 +1779,7 @@ describe('HonoStreamAppBuilder', () => {
       // Only streaming procedure should be registered
       expect(builder.docs).toHaveLength(1)
       expect(builder.docs[0]!.name).toBe('WatchNotifications')
-      expect(builder.docs[0]!.methods).toEqual(['get', 'post'])
+      expect(builder.docs[0]!.methods).toEqual(['post', 'get'])
 
       // Test streaming
       const res = await app.request('/user/notifications/watch-notifications/1?limit=2', {

package/src/implementations/http/hono-stream/index.ts

@@ -75,10 +75,13 @@ export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
   onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   /**
    * Declarative error-to-response mapping (one of the two peer error modes).
-   * Thrown error classes map to status codes + bodies declaratively. Mid-stream
-   * errors still go through `onMidStreamError` — the HTTP status is already
-   * committed once streaming starts. See hono-api for the full taxonomy
-   * contract.
+   * Thrown error classes map to status codes + bodies declaratively. The
+   * taxonomy applies to BOTH pre-stream errors (where the status code is
+   * honored) AND mid-stream errors (where only the body shape is honored —
+   * the HTTP status is already committed once streaming starts; the body is
+   * written as the SSE `event: 'error'` data, or a JSON line in text mode,
+   * for the client's error registry to dispatch). See hono-api for the full
+   * taxonomy contract.
    */
   errors?: ErrorTaxonomy
   /**
@@ -185,6 +188,7 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
 
   private _app: Hono = new Hono()
   private _docs: (StreamHttpRouteDoc & object)[] = []
+  private _skipped: { name: string; reason: string }[] = []
 
   get app(): Hono {
     return this._app
@@ -194,6 +198,16 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
     return this._docs
   }
 
+  /**
+   * Procedures that were skipped at `build()` time because they don't fit
+   * this builder (e.g. non-streaming procedures registered against the
+   * stream builder). Surfaced via `DocSource.skippedProcedures` so
+   * DocRegistry can warn about coverage gaps.
+   */
+  get skippedProcedures(): { name: string; reason: string }[] {
+    return this._skipped
+  }
+
   /**
    * Registers a procedure factory with its context.
    * Only streaming procedures (created with CreateStream) will be registered.
@@ -355,24 +369,61 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           })
         }
       } catch (error) {
-        // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+        // Dispatch order mirrors hono-rpc: taxonomy → onMidStreamError → default.
+        // The HTTP status is already committed (200 OK headers were sent the
+        // moment streaming started), so the taxonomy here only drives the
+        // wire-protocol body shape — clients dispatch through the same error
+        // registry as RPC/API responses by reading `data.name`.
+        let errorData: unknown
+        let sseEventOverride: string | undefined
+        let sseIdOverride: string | undefined
+        let sseRetryOverride: number | undefined
+        let runOnCatch: (() => Promise<void>) | undefined
 
-        if (this.config?.onMidStreamError) {
-          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        if (this.config?.errors || this.config?.unknownError) {
+          const resolved = resolveErrorResponse({
+            err: error,
+            userTaxonomy: this.config.errors,
+            unknownError: this.config.unknownError,
+            procedure,
+            raw: c,
+          })
+          if (resolved) {
+            errorData = resolved.body
+            sseEventOverride = 'error'
+            runOnCatch = resolved.runOnCatch
+          }
+        }
+
+        if (errorData === undefined && this.config?.onMidStreamError) {
+          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
+            this.config.onMidStreamError(procedure, c, error as Error)
+          if (errorResult?.data !== undefined) {
+            errorData = errorResult.data
+            sseEventOverride = procedure.name
+          }
+        }
+
+        if (errorData === undefined) {
+          errorData = { error: (error as Error).message }
+          sseEventOverride = 'error'
         }
 
-        // Write error value to stream
-        const errorData = errorResult?.data ?? { error: (error as Error).message }
         const sseMeta = getSSEMeta(errorData)
 
         await stream.writeSSE({
           data: typeof errorData === 'string' ? errorData : JSON.stringify(errorData),
-          event: sseMeta?.event ?? (errorResult?.data !== undefined ? procedure.name : 'error'),
-          id: sseMeta?.id ?? String(eventId++),
-          ...(sseMeta?.retry !== undefined && { retry: sseMeta.retry }),
+          event: sseMeta?.event ?? sseEventOverride ?? 'error',
+          id: sseMeta?.id ?? sseIdOverride ?? String(eventId++),
+          ...((sseMeta?.retry ?? sseRetryOverride) !== undefined && {
+            retry: (sseMeta?.retry ?? sseRetryOverride) as number,
+          }),
         })
 
+        if (runOnCatch) {
+          await runOnCatch()
+        }
+
         // closeStream defaults to true if not specified
         // (stream closes naturally after this handler completes)
       } finally {
@@ -408,16 +459,43 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           await stream.writeln(JSON.stringify(value))
         }
       } catch (error) {
-        // Get error yield value from callback (onMidStreamError)
-        let errorResult: MidStreamErrorResult<TErrorData> | undefined
+        // Same dispatch order as SSE — taxonomy first, onMidStreamError next,
+        // hard default last. Text streams have no event/id metadata, so we
+        // only forward the body bytes.
+        let errorData: unknown
+        let runOnCatch: (() => Promise<void>) | undefined
 
-        if (this.config?.onMidStreamError) {
-          errorResult = this.config.onMidStreamError(procedure, c, error as Error)
+        if (this.config?.errors || this.config?.unknownError) {
+          const resolved = resolveErrorResponse({
+            err: error,
+            userTaxonomy: this.config.errors,
+            unknownError: this.config.unknownError,
+            procedure,
+            raw: c,
+          })
+          if (resolved) {
+            errorData = resolved.body
+            runOnCatch = resolved.runOnCatch
+          }
+        }
+
+        if (errorData === undefined && this.config?.onMidStreamError) {
+          const errorResult: MidStreamErrorResult<TErrorData> | undefined =
+            this.config.onMidStreamError(procedure, c, error as Error)
+          if (errorResult?.data !== undefined) {
+            errorData = errorResult.data
+          }
+        }
+
+        if (errorData === undefined) {
+          errorData = { error: (error as Error).message }
         }
 
-        // Write error value to stream
-        const errorData = errorResult?.data ?? { error: (error as Error).message }
         await stream.writeln(JSON.stringify(errorData))
+
+        if (runOnCatch) {
+          await runOnCatch()
+        }
       } finally {
         if (this.config?.onStreamEnd) {
           this.config.onStreamEnd(procedure, c, 'text')
@@ -436,8 +514,23 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
     this.factories.forEach(({ factory, factoryContext, streamMode, extendProcedureDoc }) => {
       const mode = streamMode ?? this.config?.defaultStreamMode ?? 'sse'
 
-      factory
-        .getProcedures()
+      const procedures = factory.getProcedures()
+
+      // Track non-streaming procedures so DocRegistry can warn about coverage
+      // gaps (e.g. a regular procedure registered with this builder will get
+      // dropped here and needs to be registered with HonoRPCAppBuilder).
+      for (const p of procedures as { name: string; isStream?: boolean }[]) {
+        if (p.isStream !== true) {
+          const reason =
+            'Non-streaming procedure registered with HonoStreamAppBuilder — register it with HonoRPCAppBuilder (or HonoApiAppBuilder) instead.'
+          this._skipped.push({ name: p.name, reason })
+          console.warn(
+            `[ts-procedures hono-stream] Skipping procedure "${p.name}": ${reason}`
+          )
+        }
+      }
+
+      procedures
         .filter(
           (p: { isStream?: boolean }): p is TStreamProcedureRegistration => p.isStream === true
         )
@@ -471,7 +564,10 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
       config,
       prefix: this.config?.pathPrefix,
     })
-    const methods = ['get', 'post'] as const
+    // POST first so codegen (which uses `methods[0]`) defaults to POST. POST is
+    // the canonical method for streaming procedures because it can carry a body
+    // for params; GET is the supplementary method for query-string callers.
+    const methods = ['post', 'get'] as const
     const jsonSchema: { params?: Record<string, unknown>; yieldType?: Record<string, unknown>; returnType?: Record<string, unknown> } = {}
 
     if (config.schema?.params) {