ts-procedures 6.2.0 → 7.0.0-beta.1

package/src/client/index.ts

@@ -1,4 +1,4 @@
-import { executeCall } from './call.js'
+import { executeCall, executeSafeCall } from './call.js'
 import { executeStream, createTypedStream } from './stream.js'
 import type {
   CreateClientConfig,
@@ -7,6 +7,8 @@ import type {
   StreamDescriptor,
   ProcedureCallOptions,
   TypedStream,
+  Result,
+  ResultNoTyped,
 } from './types.js'
 
 // ── createClient ──────────────────────────────────────────
@@ -56,6 +58,41 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
       })
     },
 
+    safeCall<TResponse, ETyped = never>(
+      descriptor: CallDescriptor,
+      options?: ProcedureCallOptions,
+    ): Promise<Result<TResponse, ETyped>> {
+      return executeSafeCall<TResponse, ETyped>({
+        descriptor,
+        basePath,
+        adapter,
+        hooks: globalHooks,
+        defaults: globalDefaults,
+        options,
+        errorRegistry,
+      })
+    },
+
+    bindCallable<TParams, TResponse>(descriptor: Omit<CallDescriptor, 'params'>) {
+      const call = (params: TParams, options?: ProcedureCallOptions) =>
+        instance.call<TResponse>({ ...descriptor, params }, options)
+      Object.defineProperty(call, 'name', { value: descriptor.name, configurable: true })
+      return Object.assign(call, {
+        safe: (params: TParams, options?: ProcedureCallOptions) =>
+          instance.safeCall<TResponse>({ ...descriptor, params }, options) as Promise<ResultNoTyped<TResponse>>,
+      })
+    },
+
+    bindCallableTyped<TParams, TResponse, ETyped>(descriptor: Omit<CallDescriptor, 'params'>) {
+      const call = (params: TParams, options?: ProcedureCallOptions) =>
+        instance.call<TResponse>({ ...descriptor, params }, options)
+      Object.defineProperty(call, 'name', { value: descriptor.name, configurable: true })
+      return Object.assign(call, {
+        safe: (params: TParams, options?: ProcedureCallOptions) =>
+          instance.safeCall<TResponse, ETyped>({ ...descriptor, params }, options),
+      })
+    },
+
     stream<TYield, TReturn>(
       descriptor: StreamDescriptor,
       options?: ProcedureCallOptions,
@@ -133,15 +170,35 @@ export type {
   ErrorRegistry,
   ErrorFactory,
   ErrorResponseMeta,
+  ClientErrorMap,
+  FrameworkFailure,
+  Result,
+  ResultNoTyped,
 } from './types.js'
 
 export { dispatchTypedError } from './error-dispatch.js'
 
-export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
+export {
+  ClientHttpError,
+  ClientRequestError,
+  ClientPathParamError,
+  ClientStreamError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+} from './errors.js'
 
 export { createTypedStream } from './stream.js'
-export { executeCall } from './call.js'
+export { executeCall, executeSafeCall } from './call.js'
 export { executeStream } from './stream.js'
 
 export { createFetchAdapter } from './fetch-adapter.js'
 export type { FetchAdapterConfig } from './fetch-adapter.js'
+
+export { defaultClassifyError } from './classify-error.js'
+export type {
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
+} from './types.js'

package/src/client/resolve-options.test.ts

@@ -5,6 +5,7 @@ import {
   resolveHeaders,
   resolveMeta,
   resolveSignal,
+  resolveSignalSources,
 } from './resolve-options.js'
 import type { AdapterRequest, ProcedureCallDefaults, ProcedureCallOptions } from './types.js'
 
@@ -141,8 +142,72 @@ describe('resolveSignal', () => {
   })
 })
 
+// ── resolveSignalSources ──────────────────────────────────
+
+describe('resolveSignalSources', () => {
+  it('returns timeout signal alongside combined', () => {
+    const result = resolveSignalSources(undefined, { timeout: 100 })
+    expect(result.timeoutSignal).toBeInstanceOf(AbortSignal)
+    expect(result.timeoutMs).toBe(100)
+    expect(result.combined).toBeInstanceOf(AbortSignal)
+    expect(result.userSignal).toBeUndefined()
+  })
+
+  it('returns user signal alongside combined', () => {
+    const ctrl = new AbortController()
+    const result = resolveSignalSources(undefined, { signal: ctrl.signal })
+    expect(result.userSignal).toBe(ctrl.signal)
+    expect(result.timeoutSignal).toBeUndefined()
+  })
+
+  it('combines both via AbortSignal.any', () => {
+    const ctrl = new AbortController()
+    const result = resolveSignalSources(undefined, { signal: ctrl.signal, timeout: 100 })
+    expect(result.timeoutSignal).toBeInstanceOf(AbortSignal)
+    expect(result.userSignal).toBe(ctrl.signal)
+    expect(result.combined).toBeInstanceOf(AbortSignal)
+  })
+
+  it('returns undefined combined when no signals', () => {
+    const result = resolveSignalSources(undefined, undefined)
+    expect(result.combined).toBeUndefined()
+  })
+
+  it('per-call timeout: 0 disables inherited default timeout', () => {
+    const result = resolveSignalSources({ timeout: 1000 }, { timeout: 0 })
+    expect(result.timeoutSignal).toBeUndefined()
+    expect(result.timeoutMs).toBe(0)
+    expect(result.combined).toBeUndefined()
+  })
+
+  it('merges default signal with per-call signal', () => {
+    const defaultCtrl = new AbortController()
+    const callCtrl = new AbortController()
+    const result = resolveSignalSources(
+      { signal: defaultCtrl.signal },
+      { signal: callCtrl.signal },
+    )
+    // userSignal is the per-call signal (takes precedence)
+    expect(result.userSignal).toBe(callCtrl.signal)
+    // combined should be a new AbortSignal.any
+    expect(result.combined).toBeInstanceOf(AbortSignal)
+    expect(result.combined).not.toBe(callCtrl.signal)
+    expect(result.combined).not.toBe(defaultCtrl.signal)
+    // aborting either source aborts the combined signal
+    defaultCtrl.abort()
+    expect(result.combined!.aborted).toBe(true)
+  })
+})
+
 // ── applyRequestOptions ───────────────────────────────────
 
+// Helper so existing tests can destructure .request without boilerplate
+const apply = (
+  req: AdapterRequest,
+  d: ProcedureCallDefaults | undefined,
+  o: ProcedureCallOptions | undefined,
+) => applyRequestOptions(req, d, o).request
+
 describe('applyRequestOptions', () => {
   const baseRequest: AdapterRequest = {
     url: 'https://api.example.com/foo',
@@ -151,7 +216,7 @@ describe('applyRequestOptions', () => {
   }
 
   it('returns the request unchanged when nothing is provided', () => {
-    const result = applyRequestOptions(baseRequest, undefined, undefined)
+    const result = apply(baseRequest, undefined, undefined)
     expect(result.url).toBe(baseRequest.url)
     expect(result.body).toEqual({ hello: 'world' })
     expect(result.headers).toBeUndefined()
@@ -164,7 +229,7 @@ describe('applyRequestOptions', () => {
       ...baseRequest,
       headers: { 'content-type': 'application/json', 'x-route': 'declared' },
     }
-    const result = applyRequestOptions(
+    const result = apply(
       reqWithHeaders,
       { headers: { 'x-default': 'd', 'x-route': 'from-default' } },
       { headers: { 'x-call': 'c', 'x-route': 'from-call' } },
@@ -179,7 +244,7 @@ describe('applyRequestOptions', () => {
   })
 
   it('attaches meta to the request when provided', () => {
-    const result = applyRequestOptions(baseRequest, undefined, {
+    const result = apply(baseRequest, undefined, {
       meta: { traceId: 'abc' } as never,
     })
     expect(result.meta).toEqual({ traceId: 'abc' })
@@ -187,14 +252,14 @@ describe('applyRequestOptions', () => {
 
   it('passes per-call signal through', () => {
     const controller = new AbortController()
-    const result = applyRequestOptions(baseRequest, undefined, { signal: controller.signal })
+    const result = apply(baseRequest, undefined, { signal: controller.signal })
     expect(result.signal).toBe(controller.signal)
   })
 
   it('attaches a signal when per-call timeout is set', () => {
     const spy = vi.spyOn(AbortSignal, 'timeout')
     try {
-      const result = applyRequestOptions(baseRequest, undefined, { timeout: 100 })
+      const result = apply(baseRequest, undefined, { timeout: 100 })
       expect(spy).toHaveBeenCalledWith(100)
       expect(result.signal).toBeDefined()
       expect(result.signal?.aborted).toBe(false)
@@ -202,4 +267,17 @@ describe('applyRequestOptions', () => {
       spy.mockRestore()
     }
   })
+
+  it('exposes signalSources alongside the request', () => {
+    const ctrl = new AbortController()
+    const { request, signalSources } = applyRequestOptions(baseRequest, undefined, {
+      signal: ctrl.signal,
+      timeout: 500,
+    })
+    expect(request.signal).toBeInstanceOf(AbortSignal)
+    expect(signalSources.userSignal).toBe(ctrl.signal)
+    expect(signalSources.timeoutSignal).toBeInstanceOf(AbortSignal)
+    expect(signalSources.timeoutMs).toBe(500)
+    expect(signalSources.combined).toBe(request.signal)
+  })
 })

package/src/client/resolve-options.ts

@@ -17,6 +17,48 @@ export function resolveBasePath(
   return options?.basePath ?? defaults?.basePath ?? fallback
 }
 
+/**
+ * Resolves signal sources individually so callers can distinguish which
+ * underlying signal fired (e.g. timeout vs user abort in the error classifier).
+ *
+ * - `userSignal`: the per-call signal (if any); separate from the default signal
+ * - `timeoutSignal`: created via `AbortSignal.timeout(timeoutMs)` when timeout > 0
+ * - `timeoutMs`: the resolved timeout value (may be 0 if per-call explicitly disables)
+ * - `combined`: `AbortSignal.any([...])` of all active signals, or undefined if none
+ *
+ * Per-call `timeout: 0` disables an inherited default timeout (same as `resolveSignal`).
+ * Both `defaults.signal` and `options.signal` are included in `combined` when present.
+ */
+export interface SignalSources {
+  combined?: AbortSignal
+  timeoutSignal?: AbortSignal
+  /** The per-call signal, if provided. Separate from the default signal. */
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+export function resolveSignalSources(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): SignalSources {
+  const userSignal = options?.signal
+  // Use explicit undefined check so timeout: 0 overrides defaults (not just nullish)
+  const timeoutMs = options?.timeout !== undefined ? options.timeout : defaults?.timeout
+  const timeoutSignal =
+    timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined
+
+  const signals: AbortSignal[] = []
+  if (defaults?.signal) signals.push(defaults.signal)
+  if (userSignal) signals.push(userSignal)
+  if (timeoutSignal) signals.push(timeoutSignal)
+
+  let combined: AbortSignal | undefined
+  if (signals.length === 1) combined = signals[0]
+  else if (signals.length > 1) combined = AbortSignal.any(signals)
+
+  return { combined, timeoutSignal, userSignal, timeoutMs }
+}
+
 /**
  * Resolves the effective AbortSignal by combining (via `AbortSignal.any`):
  *   - default signal (if any)
@@ -25,24 +67,15 @@ export function resolveBasePath(
  *
  * Returns undefined when none apply. Per-call `timeout: 0` disables an
  * inherited default timeout.
+ *
+ * @deprecated Prefer `resolveSignalSources` when you need access to individual
+ * signal references (e.g. for abort-cause classification).
  */
 export function resolveSignal(
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
 ): AbortSignal | undefined {
-  const signals: AbortSignal[] = []
-
-  if (defaults?.signal) signals.push(defaults.signal)
-  if (options?.signal) signals.push(options.signal)
-
-  const timeout = options?.timeout ?? defaults?.timeout
-  if (timeout != null && timeout > 0) {
-    signals.push(AbortSignal.timeout(timeout))
-  }
-
-  if (signals.length === 0) return undefined
-  if (signals.length === 1) return signals[0]
-  return AbortSignal.any(signals)
+  return resolveSignalSources(defaults, options).combined
 }
 
 /**
@@ -84,6 +117,11 @@ export function resolveMeta(
   return { ...defaultMeta, ...callMeta } as RequestMeta
 }
 
+export interface ApplyRequestOptionsResult {
+  request: AdapterRequest
+  signalSources: SignalSources
+}
+
 /**
  * Applies resolved default + per-call options to an AdapterRequest.
  *
@@ -94,13 +132,17 @@ export function resolveMeta(
  * API routes) are preserved; resolved headers merge underneath them so the
  * route-declared headers win, matching the adapter.config → defaults → call
  * → route-declared → hooks precedence chain documented in the types.
+ *
+ * Returns both the merged request and the raw `signalSources` so callers (e.g.
+ * the error classifier in Task 6) can distinguish timeout from user abort without
+ * losing provenance after `AbortSignal.any` collapses the originals.
  */
 export function applyRequestOptions(
   request: AdapterRequest,
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
-): AdapterRequest {
-  const signal = resolveSignal(defaults, options)
+): ApplyRequestOptionsResult {
+  const signalSources = resolveSignalSources(defaults, options)
   const resolvedHeaders = resolveHeaders(defaults, options)
   const meta = resolveMeta(defaults, options)
 
@@ -109,5 +151,8 @@ export function applyRequestOptions(
       ? { ...resolvedHeaders, ...request.headers }
       : undefined
 
-  return { ...request, headers, signal, meta }
+  return {
+    request: { ...request, headers, signal: signalSources.combined, meta },
+    signalSources,
+  }
 }

package/src/client/result-type.test-d.ts

@@ -0,0 +1,51 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import type {
+  Result,
+  ResultNoTyped,
+  ClientErrorMap,
+} from './types.js'
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+describe('Result type', () => {
+  it('includes ok=true with value', () => {
+    type R = Result<number, Error>
+    type Ok = Extract<R, { ok: true }>
+    expectTypeOf<Ok['value']>().toEqualTypeOf<number>()
+  })
+
+  it('includes typed kind with ETyped error', () => {
+    class MyTyped extends Error {}
+    type R = Result<number, MyTyped>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed['error']>().toEqualTypeOf<MyTyped>()
+  })
+
+  it('includes every default framework kind', () => {
+    type R = Result<number, Error>
+    expectTypeOf<Extract<R, { kind: 'http' }>['error']>().toEqualTypeOf<ClientHttpError>()
+    expectTypeOf<Extract<R, { kind: 'network' }>['error']>().toEqualTypeOf<ClientNetworkError>()
+    expectTypeOf<Extract<R, { kind: 'timeout' }>['error']>().toEqualTypeOf<ClientTimeoutError>()
+    expectTypeOf<Extract<R, { kind: 'aborted' }>['error']>().toEqualTypeOf<ClientAbortError>()
+    expectTypeOf<Extract<R, { kind: 'parse' }>['error']>().toEqualTypeOf<ClientParseError>()
+    expectTypeOf<Extract<R, { kind: 'usage' }>['error']>().toEqualTypeOf<ClientPathParamError>()
+    expectTypeOf<Extract<R, { kind: 'unknown' }>['error']>().toEqualTypeOf<unknown>()
+  })
+})
+
+describe('ResultNoTyped', () => {
+  it('omits the typed arm', () => {
+    type R = ResultNoTyped<number>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed>().toEqualTypeOf<never>()
+  })
+})
+
+// Suppress unused-var warnings on imports we use only for types
+void (null as unknown as ClientErrorMap)

package/src/client/safe-call.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest'
+import { executeSafeCall } from './call.js'
+import {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientPathParamError,
+} from './errors.js'
+import type { ClientAdapter, CallDescriptor } from './types.js'
+
+const baseDescriptor: CallDescriptor = {
+  name: 'GetUser', scope: 'users', path: '/users/:id', method: 'GET',
+  kind: 'rpc', params: { id: '42' },
+}
+
+const ok = (body: unknown): ClientAdapter => ({
+  request: vi.fn(async () => ({ status: 200, headers: {}, body })),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+const failWith = (err: unknown): ClientAdapter => ({
+  request: vi.fn(async () => { throw err }),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+describe('executeSafeCall', () => {
+  it('returns ok=true with value on success', async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: ok({ id: '42' }),
+      hooks: {},
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.value).toEqual({ id: '42' })
+  })
+
+  it("returns kind='http' on non-2xx without registry match", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: {
+        request: vi.fn(async () => ({ status: 500, headers: {}, body: { msg: 'oops' } })),
+        stream: vi.fn(async () => { throw new Error('n/a') }),
+      },
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('http')
+      expect(r.error).toBeInstanceOf(ClientHttpError)
+    }
+  })
+
+  it("returns kind='network' on TypeError", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('Failed to fetch')),
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('network')
+      expect(r.error).toBeInstanceOf(ClientNetworkError)
+    }
+  })
+
+  it("returns kind='timeout' when timeout fires", async () => {
+    // Simulate fetch-style abort wait, mirroring Task 6's fix
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: {
+        request: vi.fn(async (req) => {
+          await new Promise<void>((_resolve, reject) => {
+            req.signal?.addEventListener(
+              'abort',
+              () => reject(new DOMException('aborted', 'AbortError')),
+              { once: true },
+            )
+          })
+          throw new Error('unreachable')
+        }),
+        stream: vi.fn(async () => { throw new Error('n/a') }),
+      },
+      hooks: {},
+      options: { timeout: 1 },
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('timeout')
+      expect(r.error).toBeInstanceOf(ClientTimeoutError)
+    }
+  })
+
+  it("returns kind='aborted' when user signal fires", async () => {
+    const ctrl = new AbortController()
+    ctrl.abort('user')
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new DOMException('aborted', 'AbortError')),
+      hooks: {},
+      options: { signal: ctrl.signal },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('aborted')
+      expect(r.error).toBeInstanceOf(ClientAbortError)
+    }
+  })
+
+  it("returns kind='usage' on pre-adapter ClientPathParamError, does NOT invoke onError", async () => {
+    // Spec contract: pre-adapter usage errors bypass the classifier AND the
+    // onError hook entirely. Path 1 of the three failure-source paths.
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      // path requires :id but params don't supply it
+      descriptor: { ...baseDescriptor, params: {} },
+      basePath: 'https://api.x',
+      adapter: ok({}),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('usage')
+      expect(r.error).toBeInstanceOf(ClientPathParamError)
+    }
+    // onError must NOT fire — by design (per spec architectural decision #1).
+    expect(seen).toEqual([])
+  })
+
+  it("returns kind='unknown' for unrecognized throws", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith('weird-string-throw'),
+      hooks: {},
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('unknown')
+      expect(r.error).toBe('weird-string-throw')
+    }
+  })
+
+  it('invokes onError hook on failure (cross-cutting telemetry)', async () => {
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('x')),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    expect(r.ok).toBe(false)
+    expect(seen[0]).toBeInstanceOf(ClientNetworkError)
+  })
+})

package/src/client/stream.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { createTypedStream, executeStream } from './stream.js'
-import { ClientRequestError } from './errors.js'
+import { ClientRequestError, ClientNetworkError } from './errors.js'
 import type {
   ClientAdapter,
   AdapterRequest,
@@ -354,3 +354,15 @@ describe('executeStream', () => {
     expect(observedMeta).toEqual({ traceId: 'stream-trace' })
   })
 })
+
+// ── executeStream classifier integration ──────────────────
+
+describe('executeStream classifier integration', () => {
+  it('classifies pre-stream TypeError as ClientNetworkError', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new Error('n/a') }),
+      stream: vi.fn(async () => { throw new TypeError('Failed to fetch') }),
+    }
+    await expect(run({ adapter })).rejects.toBeInstanceOf(ClientNetworkError)
+  })
+})

package/src/client/stream.ts

@@ -1,11 +1,13 @@
 import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
 import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
-import { ClientRequestError } from './errors.js'
+import { ClientHttpError } from './errors.js'
 import { dispatchTypedError } from './error-dispatch.js'
+import { defaultClassifyError } from './classify-error.js'
 import type {
   ClientAdapter,
   ClientHooks,
+  ClassifyErrorContext,
   ErrorRegistry,
   StreamDescriptor,
   TypedStream,
@@ -115,7 +117,7 @@ export interface ExecuteStreamConfig {
  * 4. Call adapter.stream()
  * 5. On adapter error: run onError hooks, re-throw
  * 6. Run onAfterResponse immediately (before iteration), body is null
- * 7. If non-2xx: throw ClientRequestError
+ * 7. If non-2xx: throw ClientHttpError
  * 8. Return createTypedStream(streamResponse.body, descriptor.streamMode)
  */
 export async function executeStream<TYield, TReturn = void>(
@@ -128,7 +130,9 @@ export async function executeStream<TYield, TReturn = void>(
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  request = applyRequestOptions(request, defaults, options)
+  const applied = applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
 
   // 3. Run before-request hooks
   const beforeCtx = await runBeforeRequest(
@@ -142,14 +146,27 @@ export async function executeStream<TYield, TReturn = void>(
   let streamResponse
   try {
     streamResponse = await adapter.stream(request)
-  } catch (err) {
-    // 5. On adapter error: run error hooks, re-throw
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    const finalError = classified?.error ?? rawErr
+
     await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
       hooks,
       options,
     )
-    throw err
+    throw finalError
   }
 
   // Build an AdapterResponse shape for the hooks. For success the body is null
@@ -176,7 +193,7 @@ export async function executeStream<TYield, TReturn = void>(
       scope: descriptor.scope,
     })
     if (typed) throw typed
-    throw new ClientRequestError({
+    throw new ClientHttpError({
       status: responseForHooks.status,
       headers: responseForHooks.headers,
       body: responseForHooks.body,