@pellux/goodvibes-errors 0.33.37 → 0.34.0

package/dist/index.d.ts

@@ -24,8 +24,106 @@ export type ErrorSource = DaemonErrorSource | 'contract';
  * }
  */
 export type SDKErrorKind = 'auth' | 'config' | 'contract' | 'network' | 'not-found' | 'protocol' | 'rate-limit' | 'service' | 'internal' | 'tool' | 'validation' | 'unknown';
+/**
+ * Exhaustive string-literal union of the canonical error codes produced by the
+ * GoodVibes SDK. Use this type when you need to pattern-match on `err.code`
+ * without losing exhaustiveness checking.
+ *
+ * The `code` field on {@link GoodVibesSdkError} is typed as
+ * `SDKErrorCode | (string & {})` so that:
+ * - SDK-produced errors surface as one of the known literals (IDE autocomplete
+ *   and exhaustive switches work).
+ * - Caller-supplied arbitrary string codes still type-check without casting.
+ *
+ * ### Consumer pattern
+ * ```ts
+ * import { isErrorCode, SDKErrorCodes } from '@pellux/goodvibes-errors';
+ *
+ * catch (err) {
+ *   if (err instanceof GoodVibesSdkError) {
+ *     if (isErrorCode(err, SDKErrorCodes.RATE_LIMITED)) {
+ *       await delay(err.retryAfterMs ?? 1000);
+ *     } else if (isErrorCode(err, SDKErrorCodes.AUTH_REQUIRED)) {
+ *       await refreshToken();
+ *     } else if (isErrorCode(err, SDKErrorCodes.TOKEN_EXPIRED)) {
+ *       await refreshToken();
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type SDKErrorCode = 'AUTH_REQUIRED' | 'TOKEN_EXPIRED' | 'PERMISSION_DENIED' | 'PAYMENT_REQUIRED' | 'RATE_LIMITED' | 'NETWORK_UNREACHABLE' | 'TIMEOUT' | 'CANCELLED' | 'NOT_FOUND' | 'CONFLICT' | 'VALIDATION_FAILED' | 'AGENT_TIMEOUT' | 'AGENT_FAILED' | 'TOOL_EXEC_FAILED' | 'SERVICE_UNAVAILABLE' | 'CONTRACT_MISMATCH' | 'PROTOCOL_ERROR' | 'INTERNAL_ERROR' | 'SDK_CONFIGURATION_ERROR' | 'SDK_CONTRACT_ERROR' | 'SDK_HTTP_STATUS_ERROR' | 'UNKNOWN';
+/**
+ * Runtime-accessible const object mirroring the {@link SDKErrorCode} union.
+ * Prefer referencing these constants over raw string literals for refactor safety.
+ *
+ * @example
+ * import { SDKErrorCodes } from '@pellux/goodvibes-errors';
+ *
+ * if (err.code === SDKErrorCodes.RATE_LIMITED) {
+ *   await delay(err.retryAfterMs ?? 1000);
+ * }
+ */
+export declare const SDKErrorCodes: {
+    readonly AUTH_REQUIRED: "AUTH_REQUIRED";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly PAYMENT_REQUIRED: "PAYMENT_REQUIRED";
+    readonly RATE_LIMITED: "RATE_LIMITED";
+    readonly NETWORK_UNREACHABLE: "NETWORK_UNREACHABLE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CANCELLED: "CANCELLED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly CONFLICT: "CONFLICT";
+    readonly VALIDATION_FAILED: "VALIDATION_FAILED";
+    readonly AGENT_TIMEOUT: "AGENT_TIMEOUT";
+    readonly AGENT_FAILED: "AGENT_FAILED";
+    readonly TOOL_EXEC_FAILED: "TOOL_EXEC_FAILED";
+    readonly SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE";
+    readonly CONTRACT_MISMATCH: "CONTRACT_MISMATCH";
+    readonly PROTOCOL_ERROR: "PROTOCOL_ERROR";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    readonly SDK_CONFIGURATION_ERROR: "SDK_CONFIGURATION_ERROR";
+    readonly SDK_CONTRACT_ERROR: "SDK_CONTRACT_ERROR";
+    readonly SDK_HTTP_STATUS_ERROR: "SDK_HTTP_STATUS_ERROR";
+    readonly UNKNOWN: "UNKNOWN";
+};
+/**
+ * Returns `true` when `err.code` equals the given {@link SDKErrorCode},
+ * narrowing the type of `err.code` to the specific literal.
+ *
+ * Works with any object that has a `code?: string` field — not limited to
+ * {@link GoodVibesSdkError} subclasses.
+ *
+ * @example
+ * import { isErrorCode, SDKErrorCodes, GoodVibesSdkError } from '@pellux/goodvibes-errors';
+ *
+ * if (err instanceof GoodVibesSdkError && isErrorCode(err, SDKErrorCodes.RATE_LIMITED)) {
+ *   console.log('retry after', err.retryAfterMs);
+ * }
+ *
+ * @param err - Any object with an optional `code` string field.
+ * @param code - The {@link SDKErrorCode} literal to match against.
+ */
+export declare function isErrorCode<C extends SDKErrorCode>(err: {
+    readonly code?: SDKErrorCode | (string & {}) | undefined;
+}, code: C): err is {
+    readonly code: C;
+};
+/**
+ * Returns `true` when `value` is a known {@link SDKErrorCode} string.
+ * Useful for discriminating structured errors received over the wire.
+ *
+ * @param value - The string to test.
+ */
+export declare function isKnownErrorCode(value: string): value is SDKErrorCode;
 export interface GoodVibesSdkErrorOptions {
-    readonly code?: string | undefined;
+    /**
+     * A typed error code for programmatic matching. May be an {@link SDKErrorCode}
+     * literal or any custom string for caller-supplied codes.
+     * When omitted, the SDK infers a code from `category` or `status`.
+     */
+    readonly code?: SDKErrorCode | (string & {}) | undefined;
     readonly category?: ErrorCategory | undefined;
     readonly source?: ErrorSource | undefined;
     readonly recoverable?: boolean | undefined;
@@ -47,10 +145,29 @@ export declare const RETRYABLE_STATUS_CODES: readonly number[];
 /**
  * Base error class for all errors thrown by the GoodVibes SDK.
  *
- * Every error carries a structured `category` and `source` that allow
+ * Every error carries a structured `category`, `source`, and `code` that allow
  * callers to handle specific failure modes without string-matching messages.
  *
- * ### Narrowing pattern
+ * The `code` field is typed as `SDKErrorCode | (string & {})` — SDK-produced
+ * errors always carry a known {@link SDKErrorCode}, while caller-supplied codes
+ * remain valid arbitrary strings.
+ *
+ * ### Narrowing by code
+ * ```ts
+ * import { GoodVibesSdkError, isErrorCode, SDKErrorCodes } from '@pellux/goodvibes-errors';
+ *
+ * catch (err) {
+ *   if (err instanceof GoodVibesSdkError) {
+ *     if (isErrorCode(err, SDKErrorCodes.RATE_LIMITED)) {
+ *       await delay(err.retryAfterMs ?? 1000);
+ *     } else if (isErrorCode(err, SDKErrorCodes.TOKEN_EXPIRED)) {
+ *       await refreshToken();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Narrowing by kind
  * ```ts
  * import { GoodVibesSdkError, HttpStatusError, ConfigurationError } from '@pellux/goodvibes-errors';
  *
@@ -69,7 +186,18 @@ export declare const RETRYABLE_STATUS_CODES: readonly number[];
  */
 export declare class GoodVibesSdkError extends Error {
     readonly kind: SDKErrorKind;
-    readonly code?: string | undefined;
+    /**
+     * Typed error code for programmatic matching. SDK-produced errors always set
+     * a {@link SDKErrorCode}; caller-supplied codes may be any string.
+     *
+     * **Note:** `code` and `category` are inferred independently and can diverge.
+     * For example, `new GoodVibesSdkError('…', { status: 409 })` yields
+     * `code === 'CONFLICT'` (from `inferCodeFromStatus`) while
+     * `category === 'unknown'` (because `inferCategory` intentionally returns
+     * `'unknown'` for 409 — the caller must supply `category` explicitly to get
+     * a meaningful category for conflict-style errors).
+     */
+    readonly code: SDKErrorCode | (string & {});
     readonly category: ErrorCategory;
     readonly source: ErrorSource;
     readonly recoverable: boolean;
@@ -95,7 +223,7 @@ export declare class GoodVibesSdkError extends Error {
  * implementation available, or calling a mutation on a read-only auth resolver).
  *
  * Always non-recoverable (`recoverable: false`).
- * Category: `'config'`. Kind: `'config'`.
+ * Category: `'config'`. Kind: `'config'`. Code: `'SDK_CONFIGURATION_ERROR'`.
  *
  * @example
  * import { ConfigurationError } from '@pellux/goodvibes-errors';
@@ -124,7 +252,7 @@ export declare class ConfigurationError extends GoodVibesSdkError {
  * (unexpected shape, missing required fields, etc.).
  *
  * Always non-recoverable (`recoverable: false`).
- * Category: `'contract'`. Kind: `'contract'`.
+ * Category: `'contract'`. Kind: `'contract'`. Code: `'SDK_CONTRACT_ERROR'`.
  *
  * @example
  * import { ContractError } from '@pellux/goodvibes-errors';
@@ -158,6 +286,17 @@ export declare class ContractError extends GoodVibesSdkError {
  * - `5xx` → `'service'`
  * - Any other status (or when constructed without a `status`) → `'unknown'`
  *
+ * The `code` field is inferred from `status` automatically:
+ * - `400` → `'VALIDATION_FAILED'`
+ * - `401` → `'AUTH_REQUIRED'`
+ * - `402` → `'PAYMENT_REQUIRED'`
+ * - `403` → `'PERMISSION_DENIED'`
+ * - `404` → `'NOT_FOUND'`
+ * - `408` → `'TIMEOUT'`
+ * - `409` → `'CONFLICT'`
+ * - `429` → `'RATE_LIMITED'`
+ * - `5xx` → `'SERVICE_UNAVAILABLE'`
+ *
  * When constructed without a `status` argument (e.g. as a typed
  * wrapper around a structured daemon error that provides its own `category`),
  * the category defaults to `'unknown'`. Callers relying on category-based
@@ -185,15 +324,36 @@ export declare class ContractError extends GoodVibesSdkError {
  */
 export declare class HttpStatusError extends GoodVibesSdkError {
     /**
-     * Brand contract — `code` is the source of truth, not the prototype chain.
+     * Brand contract: `instanceof HttpStatusError` relies on a dedicated Symbol
+     * brand stamped in the constructor, enabling cross-realm identity checks that
+     * are independent of the `code` field.
+     *
      * A `GoodVibesSdkError` constructed directly with `code: 'SDK_HTTP_STATUS_ERROR'`
-     * will pass `instanceof HttpStatusError` even if its prototype is only
-     * `GoodVibesSdkError`. Callers that need strict prototype checking should use
+     * will also pass `instanceof HttpStatusError` for backward compatibility with
+     * callers that serialise/deserialise errors by code. Callers that need strict
+     * prototype checking should use
      * `Object.getPrototypeOf(err) === HttpStatusError.prototype` instead.
      */
     static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string, options?: GoodVibesSdkErrorOptions);
 }
 export declare function isStructuredDaemonErrorBody(value: unknown): value is StructuredDaemonErrorBody;
+/**
+ * Creates an {@link HttpStatusError} from an HTTP response.
+ *
+ * When `body` is a {@link StructuredDaemonErrorBody}, its fields are used
+ * directly (including any explicit `code`). When the body is unstructured,
+ * the `code` is inferred from `status` via status-based inference (`inferCodeFromStatus`).
+ *
+ * The structured body path respects the body-supplied `code` over status
+ * inference, preserving full backward compatibility for callers that supply
+ * custom codes in the daemon response.
+ *
+ * @param status - HTTP status code.
+ * @param url - Request URL.
+ * @param method - HTTP method.
+ * @param body - Parsed response body (may be structured or unstructured).
+ * @param fallbackHint - Human-readable hint when the body provides none.
+ */
 export declare function createHttpStatusError(status: number, url: string, method: string, body: unknown, fallbackHint?: string): HttpStatusError;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,4 +1,73 @@
 export { DaemonErrorCategory } from './daemon-error-contract.js';
+/**
+ * Runtime-accessible const object mirroring the {@link SDKErrorCode} union.
+ * Prefer referencing these constants over raw string literals for refactor safety.
+ *
+ * @example
+ * import { SDKErrorCodes } from '@pellux/goodvibes-errors';
+ *
+ * if (err.code === SDKErrorCodes.RATE_LIMITED) {
+ *   await delay(err.retryAfterMs ?? 1000);
+ * }
+ */
+export const SDKErrorCodes = {
+    AUTH_REQUIRED: 'AUTH_REQUIRED',
+    TOKEN_EXPIRED: 'TOKEN_EXPIRED',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    PAYMENT_REQUIRED: 'PAYMENT_REQUIRED',
+    RATE_LIMITED: 'RATE_LIMITED',
+    NETWORK_UNREACHABLE: 'NETWORK_UNREACHABLE',
+    TIMEOUT: 'TIMEOUT',
+    CANCELLED: 'CANCELLED',
+    NOT_FOUND: 'NOT_FOUND',
+    CONFLICT: 'CONFLICT',
+    VALIDATION_FAILED: 'VALIDATION_FAILED',
+    AGENT_TIMEOUT: 'AGENT_TIMEOUT',
+    AGENT_FAILED: 'AGENT_FAILED',
+    TOOL_EXEC_FAILED: 'TOOL_EXEC_FAILED',
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+    CONTRACT_MISMATCH: 'CONTRACT_MISMATCH',
+    PROTOCOL_ERROR: 'PROTOCOL_ERROR',
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    SDK_CONFIGURATION_ERROR: 'SDK_CONFIGURATION_ERROR',
+    SDK_CONTRACT_ERROR: 'SDK_CONTRACT_ERROR',
+    SDK_HTTP_STATUS_ERROR: 'SDK_HTTP_STATUS_ERROR',
+    UNKNOWN: 'UNKNOWN',
+};
+/**
+ * The set of known {@link SDKErrorCode} values for runtime membership tests.
+ * @internal
+ */
+const SDK_ERROR_CODE_SET = new Set(Object.values(SDKErrorCodes));
+/**
+ * Returns `true` when `err.code` equals the given {@link SDKErrorCode},
+ * narrowing the type of `err.code` to the specific literal.
+ *
+ * Works with any object that has a `code?: string` field — not limited to
+ * {@link GoodVibesSdkError} subclasses.
+ *
+ * @example
+ * import { isErrorCode, SDKErrorCodes, GoodVibesSdkError } from '@pellux/goodvibes-errors';
+ *
+ * if (err instanceof GoodVibesSdkError && isErrorCode(err, SDKErrorCodes.RATE_LIMITED)) {
+ *   console.log('retry after', err.retryAfterMs);
+ * }
+ *
+ * @param err - Any object with an optional `code` string field.
+ * @param code - The {@link SDKErrorCode} literal to match against.
+ */
+export function isErrorCode(err, code) {
+    return err.code === code;
+}
+/**
+ * Returns `true` when `value` is a known {@link SDKErrorCode} string.
+ * Useful for discriminating structured errors received over the wire.
+ *
+ * @param value - The string to test.
+ */
+export function isKnownErrorCode(value) {
+    return SDK_ERROR_CODE_SET.has(value);
+}
 function inferKind(category) {
     switch (category) {
         case 'authentication':
@@ -32,6 +101,33 @@ function inferKind(category) {
             return 'unknown';
     }
 }
+/**
+ * Infers the canonical {@link SDKErrorCode} from an {@link ErrorCategory}.
+ * Used internally to populate `code` when no explicit code is provided.
+ * @internal
+ */
+function inferCodeFromCategory(category) {
+    switch (category) {
+        case 'authentication': return 'AUTH_REQUIRED';
+        case 'authorization': return 'PERMISSION_DENIED';
+        case 'billing': return 'PAYMENT_REQUIRED';
+        case 'permission': return 'PERMISSION_DENIED';
+        case 'config': return 'SDK_CONFIGURATION_ERROR';
+        case 'contract': return 'CONTRACT_MISMATCH';
+        case 'network': return 'NETWORK_UNREACHABLE';
+        case 'timeout': return 'TIMEOUT';
+        case 'not_found': return 'NOT_FOUND';
+        case 'rate_limit': return 'RATE_LIMITED';
+        case 'protocol': return 'PROTOCOL_ERROR';
+        case 'internal': return 'INTERNAL_ERROR';
+        case 'service': return 'SERVICE_UNAVAILABLE';
+        case 'bad_request': return 'VALIDATION_FAILED';
+        case 'tool': return 'TOOL_EXEC_FAILED';
+        case 'unknown':
+        default:
+            return 'UNKNOWN';
+    }
+}
 export const RETRYABLE_STATUS_CODES = [408, 429, 500, 502, 503, 504];
 function inferCategory(status) {
     if (status === 400)
@@ -46,12 +142,37 @@ function inferCategory(status) {
         return 'not_found';
     if (status === 408)
         return 'timeout';
+    if (status === 409)
+        return 'unknown'; // 409 Conflict — caller must supply category explicitly
     if (status === 429)
         return 'rate_limit';
     if (status !== undefined && status >= 500)
         return 'service';
     return 'unknown';
 }
+/**
+ * Infers the canonical {@link SDKErrorCode} for HTTP status codes that have a
+ * direct 1-to-1 mapping, used when no explicit code is present in the response
+ * body. Returns `undefined` when the code should fall through to category-based
+ * inference (e.g. for structured-body responses that supply their own category).
+ * @internal
+ */
+function inferCodeFromStatus(status) {
+    switch (status) {
+        case 400: return 'VALIDATION_FAILED';
+        case 401: return 'AUTH_REQUIRED';
+        case 402: return 'PAYMENT_REQUIRED';
+        case 403: return 'PERMISSION_DENIED';
+        case 404: return 'NOT_FOUND';
+        case 408: return 'TIMEOUT';
+        case 409: return 'CONFLICT';
+        case 429: return 'RATE_LIMITED';
+        default:
+            if (status >= 500)
+                return 'SERVICE_UNAVAILABLE';
+            return undefined;
+    }
+}
 const ERROR_CATEGORIES = new Set([
     'authentication',
     'authorization',
@@ -71,6 +192,7 @@ const ERROR_CATEGORIES = new Set([
     'unknown',
 ]);
 const GOODVIBES_SDK_ERROR_BRAND = Symbol.for('pellux.goodvibes.sdk.error');
+const HTTP_STATUS_ERROR_BRAND = Symbol.for('pellux.goodvibes.sdk.http-status-error');
 function readErrorCategory(value) {
     return typeof value === 'string' && ERROR_CATEGORIES.has(value)
         ? value
@@ -97,10 +219,29 @@ function inferCategoryFromCause(cause, seen = new Set(), depth = 0) {
 /**
  * Base error class for all errors thrown by the GoodVibes SDK.
  *
- * Every error carries a structured `category` and `source` that allow
+ * Every error carries a structured `category`, `source`, and `code` that allow
  * callers to handle specific failure modes without string-matching messages.
  *
- * ### Narrowing pattern
+ * The `code` field is typed as `SDKErrorCode | (string & {})` — SDK-produced
+ * errors always carry a known {@link SDKErrorCode}, while caller-supplied codes
+ * remain valid arbitrary strings.
+ *
+ * ### Narrowing by code
+ * ```ts
+ * import { GoodVibesSdkError, isErrorCode, SDKErrorCodes } from '@pellux/goodvibes-errors';
+ *
+ * catch (err) {
+ *   if (err instanceof GoodVibesSdkError) {
+ *     if (isErrorCode(err, SDKErrorCodes.RATE_LIMITED)) {
+ *       await delay(err.retryAfterMs ?? 1000);
+ *     } else if (isErrorCode(err, SDKErrorCodes.TOKEN_EXPIRED)) {
+ *       await refreshToken();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * ### Narrowing by kind
  * ```ts
  * import { GoodVibesSdkError, HttpStatusError, ConfigurationError } from '@pellux/goodvibes-errors';
  *
@@ -119,6 +260,17 @@ function inferCategoryFromCause(cause, seen = new Set(), depth = 0) {
  */
 export class GoodVibesSdkError extends Error {
     kind;
+    /**
+     * Typed error code for programmatic matching. SDK-produced errors always set
+     * a {@link SDKErrorCode}; caller-supplied codes may be any string.
+     *
+     * **Note:** `code` and `category` are inferred independently and can diverge.
+     * For example, `new GoodVibesSdkError('…', { status: 409 })` yields
+     * `code === 'CONFLICT'` (from `inferCodeFromStatus`) while
+     * `category === 'unknown'` (because `inferCategory` intentionally returns
+     * `'unknown'` for 409 — the caller must supply `category` explicitly to get
+     * a meaningful category for conflict-style errors).
+     */
     code;
     category;
     source;
@@ -158,7 +310,11 @@ export class GoodVibesSdkError extends Error {
             enumerable: false,
             configurable: false,
         });
-        this.code = options.code;
+        // Infer code from status first (most specific), then from category.
+        // Explicit caller-supplied code always wins.
+        this.code = options.code
+            ?? (options.status !== undefined ? inferCodeFromStatus(options.status) : undefined)
+            ?? inferCodeFromCategory(category);
         this.category = category;
         this.kind = inferKind(this.category);
         this.source = options.source ?? 'unknown';
@@ -238,7 +394,7 @@ function omitUndefined(record) {
  * implementation available, or calling a mutation on a read-only auth resolver).
  *
  * Always non-recoverable (`recoverable: false`).
- * Category: `'config'`. Kind: `'config'`.
+ * Category: `'config'`. Kind: `'config'`. Code: `'SDK_CONFIGURATION_ERROR'`.
  *
  * @example
  * import { ConfigurationError } from '@pellux/goodvibes-errors';
@@ -285,7 +441,7 @@ export class ConfigurationError extends GoodVibesSdkError {
  * (unexpected shape, missing required fields, etc.).
  *
  * Always non-recoverable (`recoverable: false`).
- * Category: `'contract'`. Kind: `'contract'`.
+ * Category: `'contract'`. Kind: `'contract'`. Code: `'SDK_CONTRACT_ERROR'`.
  *
  * @example
  * import { ContractError } from '@pellux/goodvibes-errors';
@@ -337,6 +493,17 @@ export class ContractError extends GoodVibesSdkError {
  * - `5xx` → `'service'`
  * - Any other status (or when constructed without a `status`) → `'unknown'`
  *
+ * The `code` field is inferred from `status` automatically:
+ * - `400` → `'VALIDATION_FAILED'`
+ * - `401` → `'AUTH_REQUIRED'`
+ * - `402` → `'PAYMENT_REQUIRED'`
+ * - `403` → `'PERMISSION_DENIED'`
+ * - `404` → `'NOT_FOUND'`
+ * - `408` → `'TIMEOUT'`
+ * - `409` → `'CONFLICT'`
+ * - `429` → `'RATE_LIMITED'`
+ * - `5xx` → `'SERVICE_UNAVAILABLE'`
+ *
  * When constructed without a `status` argument (e.g. as a typed
  * wrapper around a structured daemon error that provides its own `category`),
  * the category defaults to `'unknown'`. Callers relying on category-based
@@ -364,10 +531,14 @@ export class ContractError extends GoodVibesSdkError {
  */
 export class HttpStatusError extends GoodVibesSdkError {
     /**
-     * Brand contract — `code` is the source of truth, not the prototype chain.
+     * Brand contract: `instanceof HttpStatusError` relies on a dedicated Symbol
+     * brand stamped in the constructor, enabling cross-realm identity checks that
+     * are independent of the `code` field.
+     *
      * A `GoodVibesSdkError` constructed directly with `code: 'SDK_HTTP_STATUS_ERROR'`
-     * will pass `instanceof HttpStatusError` even if its prototype is only
-     * `GoodVibesSdkError`. Callers that need strict prototype checking should use
+     * will also pass `instanceof HttpStatusError` for backward compatibility with
+     * callers that serialise/deserialise errors by code. Callers that need strict
+     * prototype checking should use
      * `Object.getPrototypeOf(err) === HttpStatusError.prototype` instead.
      */
     static [Symbol.hasInstance](value) {
@@ -376,26 +547,65 @@ export class HttpStatusError extends GoodVibesSdkError {
                 && value !== null
                 && this.prototype.isPrototypeOf(value);
         }
-        // Require both the brand (real SDK error instance) and matching code
-        // to prevent plain objects like { code: 'SDK_HTTP_STATUS_ERROR' } from passing.
-        return GoodVibesSdkError[Symbol.hasInstance](value)
-            && value.code === 'SDK_HTTP_STATUS_ERROR';
+        if (!GoodVibesSdkError[Symbol.hasInstance](value))
+            return false;
+        const record = value;
+        // Primary: dedicated brand symbol (set in constructor — works in same realm).
+        if (record[HTTP_STATUS_ERROR_BRAND] === true)
+            return true;
+        // Fallback: code-based brand for cross-realm / serialised-error compat.
+        return record.code === 'SDK_HTTP_STATUS_ERROR';
     }
     constructor(message, options = {}) {
         super(message, {
             ...options,
+            // Default code retains 'SDK_HTTP_STATUS_ERROR' when no explicit code is
+            // supplied. Use createHttpStatusError() for status-specific semantic codes.
             code: options.code ?? 'SDK_HTTP_STATUS_ERROR',
             source: options.source ?? 'transport',
         });
+        // Stamp the brand AFTER super() so the symbol is always present on instances
+        // produced by this constructor (regardless of which code was stored).
+        Object.defineProperty(this, HTTP_STATUS_ERROR_BRAND, {
+            value: true,
+            enumerable: false,
+            configurable: false,
+        });
     }
 }
 export function isStructuredDaemonErrorBody(value) {
     return typeof value === 'object' && value !== null && typeof value.error === 'string';
 }
+/**
+ * Creates an {@link HttpStatusError} from an HTTP response.
+ *
+ * When `body` is a {@link StructuredDaemonErrorBody}, its fields are used
+ * directly (including any explicit `code`). When the body is unstructured,
+ * the `code` is inferred from `status` via status-based inference (`inferCodeFromStatus`).
+ *
+ * The structured body path respects the body-supplied `code` over status
+ * inference, preserving full backward compatibility for callers that supply
+ * custom codes in the daemon response.
+ *
+ * @param status - HTTP status code.
+ * @param url - Request URL.
+ * @param method - HTTP method.
+ * @param body - Parsed response body (may be structured or unstructured).
+ * @param fallbackHint - Human-readable hint when the body provides none.
+ */
 export function createHttpStatusError(status, url, method, body, fallbackHint) {
     if (isStructuredDaemonErrorBody(body)) {
+        // Code precedence (highest to lowest):
+        //   1. Explicit code in the body (daemon-supplied)
+        //   2. Category-derived code when body supplies a category (category is
+        //      more semantically specific than the HTTP status in this case)
+        //   3. Status-derived code as final fallback
+        const structuredCode = body.code
+            ?? (body.category !== undefined ? inferCodeFromCategory(body.category) : undefined)
+            ?? inferCodeFromStatus(status)
+            ?? 'UNKNOWN';
         return new HttpStatusError(body.error, {
-            code: body.code,
+            code: structuredCode,
             category: body.category,
             source: body.source ?? 'transport',
             recoverable: body.recoverable,
@@ -417,6 +627,9 @@ export function createHttpStatusError(status, url, method, body, fallbackHint) {
         ? body.trim()
         : `Request failed with status ${status}`;
     return new HttpStatusError(message, {
+        // Explicitly inject the status-inferred code so HttpStatusError's own
+        // default ('SDK_HTTP_STATUS_ERROR') does not suppress the specific code.
+        code: inferCodeFromStatus(status) ?? 'SDK_HTTP_STATUS_ERROR',
         status,
         url,
         method,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-errors",
-  "version": "0.33.37",
+  "version": "0.34.0",
   "engines": {
     "bun": "1.3.10",
     "node": ">=22.0.0"