@benjavicente/start-client-core 1.167.9 → 1.168.3

package/skills/start-core/middleware/SKILL.md

@@ -21,7 +21,7 @@ sources:
 Middleware customizes the behavior of server functions and server routes. It is composable — middleware can depend on other middleware to form a chain.
 
 > **CRITICAL**: TypeScript enforces method order: `middleware()` → `inputValidator()` → `client()` → `server()`. Wrong order causes type errors.
-> **CRITICAL**: Client context sent via `sendContext` is NOT validated by default. If you send dynamic user-generated data, validate it in server-side middleware before use.
+> **CRITICAL**: Validating the _shape_ of `sendContext` (e.g. `z.string().uuid().parse(...)`) is NOT authorization. A parsed identifier is a well-formed identifier, not an authorized one. Always re-check access against the session principal before using a client-sent ID as a query key, filter, or path parameter.
 
 ## Two Types of Middleware
 
@@ -40,7 +40,7 @@ Request middleware cannot depend on server function middleware. Server function
 Runs on ALL server requests (SSR, server routes, server functions):
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createMiddleware } from '@benjavicente/react-start'
 
 const loggingMiddleware = createMiddleware().server(
@@ -57,7 +57,7 @@ const loggingMiddleware = createMiddleware().server(
 Has both client and server phases:
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createMiddleware } from '@benjavicente/react-start'
 
 const authMiddleware = createMiddleware({ type: 'function' })
@@ -78,7 +78,7 @@ const authMiddleware = createMiddleware({ type: 'function' })
 ## Attaching Middleware to Server Functions
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createServerFn } from '@benjavicente/react-start'
 
 const fn = createServerFn()
@@ -173,7 +173,7 @@ Create `src/start.ts` to configure global middleware:
 
 ```tsx
 // src/start.ts
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import { createStart, createMiddleware } from '@benjavicente/react-start'
 
 const requestLogger = createMiddleware().server(async ({ next, request }) => {
@@ -241,7 +241,11 @@ const authMiddleware = createMiddleware().server(async ({ next, request }) => {
   if (!session) throw new Error('Unauthorized')
   return next({ context: { session } })
 })
+```
+
+> **Attach `authMiddleware` to every `createServerFn` that needs auth.** Server functions are RPC endpoints — a route `beforeLoad` does NOT protect the RPC, only the route's UI. Pair every protected route with handler-level enforcement here. See [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) and [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).
 
+```tsx
 type Permissions = Record<string, string[]>
 
 function authorizationMiddleware(permissions: Permissions) {
@@ -281,7 +285,7 @@ Headers merge across middleware. Later middleware overrides earlier. Call-site h
 ### Custom fetch
 
 ```tsx
-// Use @tanstack/<framework>-start for your framework (react, solid, vue)
+// Use @benjavicente/<framework>-start for your framework (react, solid, vue)
 import type { CustomFetch } from '@benjavicente/react-start'
 
 const loggingMiddleware = createMiddleware({ type: 'function' }).client(
@@ -299,23 +303,50 @@ Fetch precedence (highest to lowest): call site → later middleware → earlier
 
 ## Common Mistakes
 
-### 1. HIGH: Trusting client sendContext without validation
+### 1. CRITICAL: Trusting client sendContext — shape check is not access check
+
+`sendContext` from a client middleware arrives on the server as untrusted client input. Most agents stop after parsing the shape with Zod and assume the value is safe. It isn't: a parsed UUID is _some_ workspace, not the requesting user's workspace. Without a membership check against the session principal, you've built a tenant-walking endpoint.
+
+**Layer 1 — WRONG (no validation):**
 
 ```tsx
-// WRONG — client can send arbitrary data
 .server(async ({ next, context }) => {
+  // SQL-injectable AND tenant-walkable
   await db.query(`SELECT * FROM workspace_${context.workspaceId}`)
   return next()
 })
+```
+
+**Layer 2 — STILL WRONG (shape only):**
 
-// CORRECT — validate before use
+```tsx
 .server(async ({ next, context }) => {
+  // Looks safe, isn't. UUID is well-formed but the user may not be a member.
   const workspaceId = z.string().uuid().parse(context.workspaceId)
   await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
   return next()
 })
 ```
 
+**Layer 3 — CORRECT (shape AND access):**
+
+```tsx
+.middleware([authMiddleware]) // session loaded from cookie, NOT from sendContext
+.server(async ({ next, context }) => {
+  const workspaceId = z.string().uuid().parse(context.workspaceId)
+  // Verify the session principal can access this workspace.
+  const member = await db.memberships.find({
+    userId: context.session.userId,
+    workspaceId,
+  })
+  if (!member) throw new Error('Not a member of this workspace')
+  await db.query('SELECT * FROM workspaces WHERE id = $1', [workspaceId])
+  return next({ context: { workspaceId } })
+})
+```
+
+The session itself must come from a server-trusted source (the cookie + DB lookup in `authMiddleware`), never from `sendContext` — anything the client can send, the client can lie about. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md).
+
 ### 2. MEDIUM: Confusing request vs server function middleware
 
 Request middleware runs on ALL requests (SSR, routes, functions). Server function middleware runs only for `createServerFn` calls and has `.client()` method.
@@ -363,3 +394,5 @@ createMiddleware({ type: 'function' })
 
 - [start-core/server-functions](../server-functions/SKILL.md) — what middleware wraps
 - [start-core/server-routes](../server-routes/SKILL.md) — middleware on API endpoints
+- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — building the `authMiddleware` factory itself: session cookie reads, OAuth state, CSRF
+- [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) — routing-side guards (route `beforeLoad` does NOT protect server functions; pair guards with `authMiddleware` on every protected RPC)

package/skills/start-core/server-functions/SKILL.md

@@ -19,6 +19,7 @@ sources:
 
 Server functions are type-safe RPCs created with `createServerFn`. They run exclusively on the server but can be called from anywhere — loaders, components, hooks, event handlers, or other server functions.
 
+> **CRITICAL**: Server functions are RPC endpoints. They are reachable by direct POST regardless of which route renders the calling UI. **Auth must be enforced inside the handler (or via middleware) — a route `beforeLoad` does NOT protect the RPC.** See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the session/middleware pattern.
 > **CRITICAL**: Loaders are ISOMORPHIC — they run on BOTH client and server. Database queries, file system access, and secret API keys MUST go inside `createServerFn`, NOT in loaders directly.
 > **CRITICAL**: Do not use `"use server"` directives, `getServerSideProps`, or any Next.js/Remix server patterns. TanStack Start uses `createServerFn` exclusively.
 
@@ -199,16 +200,29 @@ import {
   setResponseStatus,
 } from '@benjavicente/react-start/server'
 
-const getCachedData = createServerFn({ method: 'GET' }).handler(async () => {
-  const request = getRequest()
-  const authHeader = getRequestHeader('Authorization')
-
+// Public, non-personalized data — safe to cache shared across users.
+const getPublicData = createServerFn({ method: 'GET' }).handler(async () => {
   setResponseHeaders({
+    // 'public' is correct ONLY when the response does not depend on identity.
+    // For anything tied to a session/user/tenant, use 'private' or 'no-store'.
     'Cache-Control': 'public, max-age=300',
   })
   setResponseStatus(200)
+  return fetchPublicData()
+})
 
-  return fetchData()
+// Authenticated data — must NOT be 'public'.
+const getMyData = createServerFn({ method: 'GET' }).handler(async () => {
+  const authHeader = getRequestHeader('Authorization')
+  // ... auth check ...
+
+  setResponseHeaders({
+    // 'private' = only the user-agent may cache. Vary by Cookie/Authorization
+    // so any intermediary that does cache keys by identity, not URL alone.
+    'Cache-Control': 'private, max-age=60',
+    Vary: 'Cookie, Authorization',
+  })
+  return fetchPersonalizedData()
 })
 ```
 
@@ -254,7 +268,33 @@ Static imports of server functions are safe — the build replaces implementatio
 
 ## Common Mistakes
 
-### 1. CRITICAL: Putting server-only code in loaders
+### 1. CRITICAL: Relying on a route guard to protect a server function
+
+A `beforeLoad` redirect protects the **route's UI**, not the **RPC**. `createServerFn` exposes a callable endpoint that an attacker can hit directly — no need to load the route at all. Auth on the route is necessary but not sufficient.
+
+```tsx
+// WRONG — the route guard doesn't reach the handler
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  return db.orders.findMany() // ← anyone can call the RPC
+})
+export const Route = createFileRoute('/_authenticated/orders')({
+  beforeLoad: ({ context }) => {
+    if (!context.auth.isAuthenticated) throw redirect({ to: '/login' })
+  },
+  loader: () => getMyOrders(),
+})
+
+// CORRECT — auth enforced on the handler itself
+const getMyOrders = createServerFn({ method: 'GET' })
+  .middleware([authMiddleware])
+  .handler(async ({ context }) => {
+    return db.orders.findMany({ where: { userId: context.session.userId } })
+  })
+```
+
+Apply `authMiddleware` (or an equivalent in-handler check) to **every** `createServerFn` that needs auth. See [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) for the full session/middleware pattern and [start-core/middleware](../middleware/SKILL.md) for composing the factory.
+
+### 2. CRITICAL: Putting server-only code in loaders
 
 ```tsx
 // WRONG — loader is ISOMORPHIC, runs on BOTH client and server
@@ -276,22 +316,47 @@ export const Route = createFileRoute('/posts')({
 })
 ```
 
-### 2. CRITICAL: Using Next.js/Remix server patterns
+### 3. CRITICAL: Using Next.js / Remix / React Router DOM patterns
+
+If the file lives at `src/pages/`, `app/layout.tsx`, `_app/`, or imports anything from `react-router-dom` or `next/`, it is wrong-framework code. TanStack Start uses `src/routes/` + `createFileRoute` + `createServerFn`.
 
 ```tsx
 // WRONG — "use server" is a React directive, not used in TanStack Start
 'use server'
 export async function getUser() { ... }
 
-// WRONG — getServerSideProps is Next.js
+// WRONG — getServerSideProps is Next.js Pages Router
 export async function getServerSideProps() { ... }
 
-// CORRECT — TanStack Start uses createServerFn
+// WRONG — Next.js App Router server component data fetching
+export default async function Page() {
+  const data = await fetch(...).then(r => r.json())
+  return <div>{data}</div>
+}
+
+// WRONG — Remix
+export async function loader({ request }) { ... }
+export async function action({ request }) { ... }
+
+// WRONG — react-router-dom (a different library)
+import { Link, useNavigate } from 'react-router-dom'
+
+// CORRECT — TanStack Start
+import { createServerFn } from '@benjavicente/react-start'
+import { Link, useNavigate, createFileRoute } from '@benjavicente/react-router'
+
 const getUser = createServerFn({ method: 'GET' })
   .handler(async () => { ... })
+
+export const Route = createFileRoute('/users/$id')({
+  loader: ({ params }) => getUser({ data: { id: params.id } }),
+  component: UserPage,
+})
 ```
 
-### 3. HIGH: Dynamic imports for server functions
+If you see `src/pages/`, `app/layout.tsx`, or `react-router-dom` in agent output, the agent is generating for the wrong framework. Build will fail or routes will conflict at runtime.
+
+### 4. HIGH: Dynamic imports for server functions
 
 ```tsx
 // WRONG — can cause bundler issues
@@ -301,7 +366,7 @@ const { getUser } = await import('~/utils/users.functions')
 import { getUser } from '~/utils/users.functions'
 ```
 
-### 4. HIGH: Awaiting server function without calling it
+### 5. HIGH: Awaiting server function without calling it
 
 `createServerFn` returns a function — it must be invoked with `()`:
 
@@ -316,20 +381,53 @@ const data = await getItems()
 const data = await getItems({ data: { id: '1' } })
 ```
 
-### 5. MEDIUM: Not using useServerFn for component calls
+### 6. CRITICAL: Caching authenticated responses with `Cache-Control: public`
+
+`Cache-Control: public, max-age=N` tells every CDN, proxy, and shared cache between you and the user that this response can be served to anyone. If the response depends on the session (user, tenant, role), the first user's response gets cached and replayed to the next user — a cross-tenant data leak.
+
+```tsx
+// WRONG — auth'd response, public cache, leaks to next user via CDN
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  const session = await requireSession() // identity-dependent
+  setResponseHeaders({ 'Cache-Control': 'public, max-age=300' })
+  return db.orders.findMany({ where: { userId: session.userId } })
+})
+
+// CORRECT — private + Vary so any cache that does store it keys by identity
+const getMyOrders = createServerFn({ method: 'GET' }).handler(async () => {
+  const session = await requireSession()
+  setResponseHeaders({
+    'Cache-Control': 'private, max-age=60',
+    Vary: 'Cookie, Authorization',
+  })
+  return db.orders.findMany({ where: { userId: session.userId } })
+})
+
+// ALSO CORRECT — opt out entirely for sensitive data
+setResponseHeaders({ 'Cache-Control': 'no-store' })
+```
+
+Rule of thumb: if the handler reads a session/cookie/auth header or branches on identity, the response is **not** `public`. Default to `private` (or `no-store` for sensitive data); reach for `public` only on responses that are byte-for-byte identical regardless of who asks. See also [start-core/deployment](../deployment/SKILL.md) for ISR/Cache-Control on full pages.
 
-When calling server functions from event handlers in components, use `useServerFn` to get proper React integration:
+### 7. MEDIUM: When to wrap with `useServerFn`
+
+`useServerFn` is **required** when the server function uses `throw redirect()` or `throw notFound()` — the hook wires the throw into the router so the redirect actually navigates. For server functions that just return data (call them directly or via `useMutation`/`useQuery`), the hook is optional.
 
 ```tsx
-// WRONG — direct call doesn't integrate with React lifecycle
+// Plain data — direct call is fine (also fine to pass to useMutation/useQuery)
 <button onClick={() => deletePost({ data: { id } })}>Delete</button>
+useMutation({ mutationFn: deletePost })
 
-// CORRECT — useServerFn integrates with React
-const deletePostFn = useServerFn(deletePost)
-<button onClick={() => deletePostFn({ data: { id } })}>Delete</button>
+// Throws redirect/notFound — MUST wrap with useServerFn so the router handles the throw
+const signupFn = useServerFn(signup) // signup throws redirect on success
+<button onClick={() => signupFn({ data: form })}>Sign up</button>
 ```
 
+If in doubt: wrap with `useServerFn`. It's a no-op for plain-data functions and the safe default when a function might later add a redirect.
+
 ## Cross-References
 
 - [start-core/execution-model](../execution-model/SKILL.md) — understanding where code runs
 - [start-core/middleware](../middleware/SKILL.md) — composing server functions with middleware
+- [start-core/auth-server-primitives](../auth-server-primitives/SKILL.md) — sessions, cookies, OAuth, CSRF, rate limiting (the server-side half of auth; `getCurrentUser`/`useSession`-style helpers belong here, not at module scope)
+- [router-core/auth-and-guards](../../../../router-core/skills/router-core/auth-and-guards/SKILL.md) — the routing side: route guards do NOT protect server functions, so always re-check auth in the handler or via middleware

package/src/client/hydrateStart.ts

@@ -1,12 +1,14 @@
 import { hydrate } from '@benjavicente/router-core/ssr/client'
 
+import { startInstance } from '#tanstack-start-entry'
+import {
+  hasPluginAdapters,
+  pluginSerializationAdapters,
+} from '#tanstack-start-plugin-adapters'
+import { getRouter } from '#tanstack-router-entry'
 import { ServerFunctionSerializationAdapter } from './ServerFunctionSerializationAdapter'
-import type { AnyStartInstanceOptions } from '../createStart'
 import type { AnyRouter, AnySerializationAdapter } from '@benjavicente/router-core'
-// eslint-disable-next-line import/no-duplicates,import/order
-import { getRouter } from '#tanstack-router-entry'
-// eslint-disable-next-line import/no-duplicates,import/order
-import { startInstance } from '#tanstack-start-entry'
+import type { AnyStartInstanceOptions } from '../createStart'
 
 export async function hydrateStart(): Promise<AnyRouter> {
   const router = await getRouter()
@@ -26,6 +28,10 @@ export async function hydrateStart(): Promise<AnyRouter> {
     } as AnyStartInstanceOptions
   }
 
+  // Only spread plugin adapters if any are configured (this will tree-shake away otherwise)
+  if (hasPluginAdapters) {
+    serializationAdapters.push(...pluginSerializationAdapters)
+  }
   serializationAdapters.push(ServerFunctionSerializationAdapter)
   if (router.options.serializationAdapters) {
     serializationAdapters.push(...router.options.serializationAdapters)
@@ -35,7 +41,7 @@ export async function hydrateStart(): Promise<AnyRouter> {
     basepath: process.env.TSS_ROUTER_BASEPATH,
     ...{ serializationAdapters },
   })
-  if (!router.stores.matchesId.state.length) {
+  if (!router.stores.matchesId.get().length) {
     await hydrate(router)
   }
 

package/src/client-rpc/serverFnFetcher.ts

@@ -20,6 +20,70 @@ import type { Plugin as SerovalPlugin } from 'seroval'
 
 let serovalPlugins: Array<SerovalPlugin<any, any>> | null = null
 
+/**
+ * Current async post-processing context for deserialization.
+ *
+ * Some deserializers need to perform async work after synchronous deserialization
+ * (e.g., decoding RSC payloads, fetching remote data). This context allows them
+ * to register promises that must complete before the deserialized value is used.
+ *
+ * This uses a synchronous execution context pattern:
+ * - Each call to `fromCrossJSON` is synchronous
+ * - Within that synchronous execution, all `fromSerializable` calls happen
+ * - We set the context before `fromCrossJSON`, clear it after
+ * - For streaming chunks, we set/clear context around each `onMessage` call
+ *
+ * Even with concurrent server function calls, each individual deserialization
+ * is atomic (synchronous), so promises are correctly scoped to their call.
+ */
+let currentPostProcessContext: Array<Promise<unknown>> | null = null
+
+/**
+ * Set the current post-processing context for async deserialization work.
+ * Called before deserialization starts.
+ *
+ * @param ctx - Array to collect async work promises, or null to clear
+ */
+export function setPostProcessContext(
+  ctx: Array<Promise<unknown>> | null,
+): void {
+  currentPostProcessContext = ctx
+}
+
+/**
+ * Get the current post-processing context.
+ * Returns null if no deserialization is in progress.
+ */
+export function getPostProcessContext(): Array<Promise<unknown>> | null {
+  return currentPostProcessContext
+}
+
+/**
+ * Track an async post-processing promise in the current deserialization context.
+ * Called by deserializers that need to perform async work after sync deserialization.
+ *
+ * If no context is active (e.g., on server), this is a no-op.
+ *
+ * @param promise - The async work promise to track
+ */
+export function trackPostProcessPromise(promise: Promise<unknown>): void {
+  if (currentPostProcessContext) {
+    currentPostProcessContext.push(promise)
+  }
+}
+
+/**
+ * Helper to await all post-processing promises.
+ * Uses Promise.allSettled to ensure all promises complete even if some reject.
+ */
+async function awaitPostProcessPromises(
+  promises: Array<Promise<unknown>>,
+): Promise<void> {
+  if (promises.length > 0) {
+    await Promise.allSettled(promises)
+  }
+}
+
 /**
  * Checks if an object has at least one own enumerable property.
  * More efficient than Object.keys(obj).length > 0 as it short-circuits on first property.
@@ -228,23 +292,19 @@ async function getResponse(fn: () => Promise<Response>) {
         },
       })
     }
-    // If it's a stream from the start serializer, process it as such
-    else if (contentType.includes('application/x-ndjson')) {
-      const refs = new Map()
-      result = await processServerFnResponse({
-        response,
-        onMessage: (msg) =>
-          fromCrossJSON(msg, { refs, plugins: serovalPlugins! }),
-        onError(msg, error) {
-          // TODO how could we notify consumer that an error occurred?
-          console.error(msg, error)
-        },
-      })
-    }
     // If it's a JSON response, it can be simpler
     else if (contentType.includes('application/json')) {
       const jsonPayload = await response.json()
-      result = fromCrossJSON(jsonPayload, { plugins: serovalPlugins! })
+      // Track async post-processing work for this deserialization
+      const postProcessPromises: Array<Promise<unknown>> = []
+      setPostProcessContext(postProcessPromises)
+      try {
+        result = fromCrossJSON(jsonPayload, { plugins: serovalPlugins! })
+      } finally {
+        setPostProcessContext(null)
+      }
+      // Await any async post-processing before returning
+      await awaitPostProcessPromises(postProcessPromises)
     }
 
     if (!result) {
@@ -284,93 +344,13 @@ async function getResponse(fn: () => Promise<Response>) {
   return response
 }
 
-async function processServerFnResponse({
-  response,
-  onMessage,
-  onError,
-}: {
-  response: Response
-  onMessage: (msg: any) => any
-  onError?: (msg: string, error?: any) => void
-}) {
-  if (!response.body) {
-    throw new Error('No response body')
-  }
-
-  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader()
-
-  let buffer = ''
-  let firstRead = false
-  let firstObject
-
-  while (!firstRead) {
-    const { value, done } = await reader.read()
-    if (value) buffer += value
-
-    if (buffer.length === 0 && done) {
-      throw new Error('Stream ended before first object')
-    }
-
-    // common case: buffer ends with newline
-    if (buffer.endsWith('\n')) {
-      const lines = buffer.split('\n').filter(Boolean)
-      const firstLine = lines[0]
-      if (!firstLine) throw new Error('No JSON line in the first chunk')
-      firstObject = JSON.parse(firstLine)
-      firstRead = true
-      buffer = lines.slice(1).join('\n')
-    } else {
-      // fallback: wait for a newline to parse first object safely
-      const newlineIndex = buffer.indexOf('\n')
-      if (newlineIndex >= 0) {
-        const line = buffer.slice(0, newlineIndex).trim()
-        buffer = buffer.slice(newlineIndex + 1)
-        if (line.length > 0) {
-          firstObject = JSON.parse(line)
-          firstRead = true
-        }
-      }
-    }
-  }
-
-  // process rest of the stream asynchronously
-  ;(async () => {
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      while (true) {
-        const { value, done } = await reader.read()
-        if (value) buffer += value
-
-        const lastNewline = buffer.lastIndexOf('\n')
-        if (lastNewline >= 0) {
-          const chunk = buffer.slice(0, lastNewline)
-          buffer = buffer.slice(lastNewline + 1)
-          const lines = chunk.split('\n').filter(Boolean)
-
-          for (const line of lines) {
-            try {
-              onMessage(JSON.parse(line))
-            } catch (e) {
-              onError?.(`Invalid JSON line: ${line}`, e)
-            }
-          }
-        }
-
-        if (done) {
-          break
-        }
-      }
-    } catch (err) {
-      onError?.('Stream processing error:', err)
-    }
-  })()
-
-  return onMessage(firstObject)
-}
-
 /**
  * Processes a framed response where each JSON chunk is a complete JSON string
  * (already decoded by frame decoder).
+ *
+ * Uses per-chunk post-processing context to ensure async deserialization work
+ * completes before the next chunk is processed. This prevents issues when
+ * streaming values require async post-processing (e.g., RSC decoding).
  */
 async function processFramedResponse({
   jsonStream,
@@ -392,8 +372,11 @@ async function processFramedResponse({
   // Each frame is a complete JSON string
   const firstObject = JSON.parse(firstValue)
 
-  // Process remaining frames asynchronously (for streaming refs like RawStream)
-  ;(async () => {
+  // Process remaining frames for streaming refs like RawStream.
+  // Keep draining until the server closes the stream.
+  // Each chunk gets its own post-processing context to properly scope async work.
+  let drainCancelled = false as boolean
+  const drain = (async () => {
     try {
       // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       while (true) {
@@ -401,16 +384,62 @@ async function processFramedResponse({
         if (done) break
         if (value) {
           try {
-            onMessage(JSON.parse(value))
+            // Set up post-processing context for this chunk
+            const chunkPostProcessPromises: Array<Promise<unknown>> = []
+            setPostProcessContext(chunkPostProcessPromises)
+            try {
+              onMessage(JSON.parse(value))
+            } finally {
+              setPostProcessContext(null)
+            }
+            // Await any async post-processing from this chunk before processing next.
+            // This ensures values requiring async work are ready before their
+            // containing Promise/Stream resolves/emits to consumers.
+            await awaitPostProcessPromises(chunkPostProcessPromises)
           } catch (e) {
             onError?.(`Invalid JSON: ${value}`, e)
           }
         }
       }
     } catch (err) {
-      onError?.('Stream processing error:', err)
+      if (!drainCancelled) {
+        onError?.('Stream processing error:', err)
+      }
     }
   })()
 
-  return onMessage(firstObject)
+  // Process first object with its own post-processing context
+  let result: any
+  const initialPostProcessPromises: Array<Promise<unknown>> = []
+  setPostProcessContext(initialPostProcessPromises)
+  try {
+    result = onMessage(firstObject)
+  } catch (err) {
+    setPostProcessContext(null)
+    drainCancelled = true
+    reader.cancel().catch(() => {})
+    throw err
+  }
+  setPostProcessContext(null)
+
+  // Await initial post-processing promises before returning result
+  await awaitPostProcessPromises(initialPostProcessPromises)
+
+  // If the initial decode fails async, stop draining to avoid holding
+  // onto the response body and raw stream buffers unnecessarily.
+  Promise.resolve(result).catch(() => {
+    drainCancelled = true
+    reader.cancel().catch(() => {})
+  })
+
+  // Detach reader once draining completes.
+  drain.finally(() => {
+    try {
+      reader.releaseLock()
+    } catch {
+      // Ignore
+    }
+  })
+
+  return result
 }