docs(core): qualify ResourceNotFoundError fromError reconstruction; fix cross-bundle example

- JSDoc / changeset / migration.md now state that ProtocolError.fromError
  reconstructs ResourceNotFoundError for either code only when error.data
  carries `uri`; a bare -32002 without data.uri stays a generic
  ProtocolError.
- migration.md example: drop the outer `instanceof ProtocolError` gate
  (it defeats the cross-bundle case the prose describes); the example now
  feeds code+data straight into fromError and tests the locally-created
  result.

Author: felixweinberger

.changeset/resource-not-found-32602.md

@@ -11,11 +11,14 @@ emitted `-32602` on earlier revisions, so v1.x peers see no change.
 
 This supersedes an interim `-32002` emission that shipped in earlier v2 alphas. The
 era-aware encode seam (`WireCodec.encodeErrorCode`) maps any handler-thrown `-32002`
-to `-32602` on the wire, so a handler written against the older alpha behaves
-identically without changes.
+to `-32602` on the wire; note that a `-32002` thrown without `data.uri` is emitted as
+a bare `-32602` and is no longer recognizable as resource-not-found — throw
+`ResourceNotFoundError` (or include `data: { uri }`) to preserve the classification.
 
 `ProtocolErrorCode.ResourceNotFound` (`-32002`) remains importable as receive-tolerated
 vocabulary; clients should accept both `-32602` and `-32002` from peers (the
 specification's backwards-compatibility clause). The new typed `ResourceNotFoundError`
-class carries `data.uri`, and `ProtocolError.fromError` recognises both codes by the
-`data.uri` shape.
+class carries `data.uri`, and `ProtocolError.fromError` reconstructs it from a `-32602`
+only when `error.data` is exactly `{ uri: string }` (and nothing else), and from a
+legacy `-32002` whenever `data.uri` is a string; a bare `-32002` without `data.uri`
+stays a generic `ProtocolError`.

docs/migration.md

@@ -1287,21 +1287,24 @@ with the `allowInputRequired: true` request option plus the `withInputRequired()
 ### Resource not found is `-32602` on every revision; typed `ResourceNotFoundError`
 
 `resources/read` for an unknown URI now answers with JSON-RPC error code **`-32602` (Invalid Params)** on every protocol revision, with `error.data.uri` echoing the requested URI. The 2026-07-28 specification requires `-32602`; the v1.x SDK already emitted `-32602` on earlier
-revisions, so v1.x peers see no change. An interim `-32002` emission that shipped in earlier v2 alphas is reverted: the era encode seam maps any handler-thrown `-32002` to `-32602` on the wire, so a handler written against the older alpha behaves identically without changes.
+revisions, so v1.x peers see no change. An interim `-32002` emission that shipped in earlier v2 alphas is reverted: the era encode seam maps any handler-thrown `-32002` to `-32602` on the wire; note that a `-32002` thrown without `data.uri` is emitted as a bare `-32602` and is no longer recognizable as resource-not-found — throw `ResourceNotFoundError` (or include `data: { uri }`) to preserve the classification.
 
 `ProtocolErrorCode.ResourceNotFound` (`-32002`) **remains importable** as receive-tolerated vocabulary: clients should accept both `-32602` and `-32002` from peers (the specification's backwards-compatibility clause). The new typed `ResourceNotFoundError` class carries the URI on
-`.uri`, and `ProtocolError.fromError` recognizes both codes by the `data.uri` shape — recognize peers' errors by their code and `error.data`, not by `instanceof`, which does not survive bundling. Servers must not return an empty `contents` array for a non-existent resource (an
-empty array is ambiguous between "exists but empty" and "does not exist").
+`.uri`, and `ProtocolError.fromError` reconstructs it from a `-32602` only when `error.data` is exactly `{ uri: string }` (and nothing else), and from a legacy `-32002` whenever `data.uri` is a string (a bare `-32002` without `data.uri` stays a generic `ProtocolError`) — recognize peers' errors by their code and `error.data`, not by `instanceof`, which does not survive
+bundling. Servers must not return an empty `contents` array for a non-existent resource (an empty array is ambiguous between "exists but empty" and "does not exist").
 
 ```typescript
 import { ProtocolError, ResourceNotFoundError } from '@modelcontextprotocol/client';
 
 try {
     await client.readResource({ uri: 'file:///nope' });
 } catch (error) {
-    const typed = error instanceof ProtocolError ? ProtocolError.fromError(error.code, error.message, error.data) : undefined;
-    if (typed instanceof ResourceNotFoundError) {
-        console.log('not found:', typed.uri);
+    // fromError reconstructs the typed class from code + data alone, so this
+    // works even when `error` crossed a bundle boundary and `instanceof` on
+    // the thrown object would not match.
+    const e = error as ProtocolError;
+    if (ProtocolError.fromError(e.code, e.message, e.data) instanceof ResourceNotFoundError) {
+        console.log('not found:', (e.data as { uri: string }).uri);
     }
 }
 ```

packages/core/src/types/errors.ts

@@ -80,12 +80,14 @@ export class ProtocolError extends Error {
  * SDK has always emitted on earlier revisions. The error data echoes the
  * requested URI.
  *
- * Recognise this error by checking `error.data.uri` is a string (a
- * `-32602` with `data.uri` is resource-not-found; any other `-32602` is an
- * ordinary Invalid Params). For backwards compatibility, clients should also
+ * Recognise this error by checking `error.data` is exactly `{ uri: string }`
+ * (a `-32602` whose data carries `uri` and nothing else is resource-not-found;
+ * any other `-32602` is an ordinary Invalid Params). For backwards compatibility, clients should also
  * accept `-32002` as resource not found — earlier SDK builds emitted that
- * code, and {@linkcode ProtocolError.fromError} recognises both. Do not rely
- * on `instanceof` — it does not work across separately bundled copies of the
+ * code, and {@linkcode ProtocolError.fromError} reconstructs this class for
+ * either code **when `error.data` carries `uri`** (a bare `-32002` without
+ * `data.uri` stays a generic {@linkcode ProtocolError}). Do not rely on
+ * `instanceof` — it does not work across separately bundled copies of the
  * SDK.
  */
 export class ResourceNotFoundError extends ProtocolError {