docs,test: reconcile stale cross-bundle instanceof notes; fix vacuous brand-leak assertion

Now that the error classes brand-match under instanceof, several comments
and doc passages still taught the pre-branding contract ("instanceof breaks
across bundled copies") — soften them to the precise post-change contract:
brand matching needs both copies at a brand-aware release, and data-parse
recognition stays the version-agnostic path for plain wire shapes and
pre-brand copies. Also replace the enumeration-leak assertion that used an
asymmetric matcher inside toContain (vacuously passing) with a real check,
plus an explicit non-enumerability assertion on the brand symbol.

Author: felixweinberger

docs/migration/upgrade-to-v2.md

@@ -984,7 +984,8 @@ peers as `-32602` — a server can no longer emit `-32002` on the wire.
 `ProtocolErrorCode.ResourceNotFound` (`-32002`) stays importable as
 receive-tolerated vocabulary — accept both `-32602` and `-32002` from peers.
 `ProtocolError.fromError(code, message, data)` reconstructs the typed subclass from
-code + data alone, so it works across bundle boundaries where `instanceof` doesn't.
+code + data alone — the version-agnostic path: it also works on plain wire shapes and
+against SDK copies that predate brand-matched `instanceof`.
 The default message text changed alongside: v1's unknown-resource error read
 `Resource <uri> not found`; v2's `ResourceNotFoundError` default is
 `Resource not found: <uri>` (the code is unchanged). Tests pinning the exact string

docs/servers/errors.md

@@ -179,7 +179,7 @@ Three more subclasses cover the other structured protocol errors:
 - `UnsupportedProtocolVersionError({ supported, requested })` — `-32022`; `data.supported` lets the peer pick a version and retry.
 - `MissingRequiredClientCapabilityError({ requiredCapabilities })` — `-32021`; `data.requiredCapabilities` names exactly what the client must declare.
 
-Match these by `code` and `data` shape, not by `instanceof` — `instanceof` fails across separately bundled copies of the SDK.
+Match these by `code` and `data` shape when peers may run pre-brand SDK copies or hand you plain wire shapes; on brand-aware releases `instanceof` also matches across separately bundled copies of the SDK.
 
 ## Look up a protocol error code
 

packages/core-internal/test/errors/crossBundleBrand.test.ts

@@ -112,7 +112,9 @@ describe('cross-bundle error instanceof (branded)', () => {
 
     it('does not leak the brand through enumeration or serialization', () => {
         const err = new SdkHttpError(SdkErrorCode.ClientHttpForbidden, 'nope', { status: 403 });
-        expect(Object.keys(err)).not.toContain(expect.stringContaining('mcp'));
+        expect(Object.keys(err).some(k => k.includes('mcp'))).toBe(false);
+        const brandKey = Symbol.for('mcp.sdk.errorBrands');
+        expect(Object.prototype.propertyIsEnumerable.call(err, brandKey)).toBe(false);
         const json = JSON.stringify({ ...err });
         expect(json).not.toContain('mcp.Sdk');
     });

packages/core-internal/test/types/errorSurfacePins.test.ts

@@ -2,8 +2,9 @@
  * Behavior-surface pins: error codes, error classes, and version constants.
  *
  * Consumers match SDK errors by literal numeric code, `error.name`, and message
- * text — not only by enum member or `instanceof` (which breaks across bundled
- * package boundaries). These tests pin the literal values so that a renumber,
+ * text — not only by enum member or `instanceof` (brand-matched `instanceof`
+ * needs both bundled copies at a brand-aware release; the literal values are
+ * the version-agnostic contract). These tests pin the literal values so that a renumber,
  * rename, or membership change turns CI red instead of landing silently. A
  * failing pin here means the change is deliberate: update the pin in the same
  * change, together with a changeset and a migration-doc entry.
@@ -92,9 +93,9 @@ describe('SdkErrorCode', () => {
 
 describe('ProtocolError', () => {
     test('sets error.name, carries code/data, and leaves the message verbatim', () => {
-        // Consumers classify errors via err.name (instanceof breaks when core is
-        // bundled into both the client and server dists), and read .code/.data as
-        // a duck shape. The constructor must not decorate the message.
+        // Consumers classify errors via err.name (`instanceof` brand-matches
+        // across bundles only when both copies are brand-aware), and read
+        // .code/.data as a duck shape. The constructor must not decorate the message.
         const error = new ProtocolError(ProtocolErrorCode.InvalidParams, 'oops', { extra: 1 });
         expect(error.name).toBe('ProtocolError');
         expect(error.code).toBe(-32602);

packages/core-internal/test/types/missingClientCapabilityError.test.ts

@@ -2,8 +2,9 @@
  * The `-32021` MissingRequiredClientCapability typed error.
  *
  * Recognition is data-parse based: a peer (or another bundled copy of the SDK)
- * is recognized by the error code plus the `data.requiredCapabilities` shape,
- * never by `instanceof` across bundles.
+ * is recognized by the error code plus the `data.requiredCapabilities` shape —
+ * the version-agnostic path that also covers plain wire shapes and pre-brand
+ * SDK copies (branded `instanceof` needs both copies brand-aware).
  */
 import { describe, expect, test } from 'vitest';