@webpieces/core-util 0.4.879 → 0.4.880

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/core-util",
-  "version": "0.4.879",
+  "version": "0.4.880",
   "description": "Utility functions for WebPieces - works in browser and Node.js",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/errors/ApiError.d.ts

@@ -146,4 +146,42 @@ export declare class ApiCodedError extends ApiError {
     /** True when the status describes the caller's mistake rather than a fault on the serving side. */
     isCallerError(): boolean;
 }
+/**
+ * The CALLER's build is too old for this server: HTTP **426 Upgrade Required**, errorCode
+ * {@link ApiClientTooOldError.CODE}. It means "upgrade", never "bug".
+ *
+ * WHO THROWS IT: a server gate that compares the build the caller DECLARED (a header, a version in
+ * the request) against the minimum this server still supports. Every webpieces client and server
+ * deployed separately hits this skew (a browser tab left open across a release, a mobile WebView
+ * pinned to an old bundle), and only the SERVER can tell that its caller is too old.
+ *
+ * WHY 426 AND NOT 266: a 266 means "the user must fix something" and its message is shown verbatim,
+ * so a bundle built before the gate existed would print the server's developer text as a user
+ * instruction. A non-266 status reaches every bundle already in the field as a non-user failure.
+ *
+ * WHAT RECEIVERS DO: `ReceivedApiErrorRule` decodes it back into THIS type on every hop
+ * (server-to-server and browser, HTTP and IPC) instead of the `ApiImplementationError` an ordinary
+ * received 4xx becomes. A client treats it as "reload / install the new build", never as a red bug
+ * dialog. It pairs with `allowUpgradeInFlight` (`HttpEndpointOptions`), which declares which calls
+ * an upgrade may cut off: that flag is the client deciding WHEN it may upgrade, this error is the
+ * server saying that it MUST.
+ *
+ * NO user-facing copy: `message` is developer text like every non-end-user kind (it is not published
+ * across the wire), and the receiving client owns the wording it shows. The status and the code are
+ * FIXED here, so a throw site cannot send a 426 that the receivers would not recognise.
+ *
+ * It is an {@link ApiCodedError} on purpose: the wire form is exactly `kind: 'coded'`,
+ * `statusCode: 426`, `errorCode: 'client-too-old'`, which is what an app's own hand-rolled
+ * client-too-old error already publishes, so a bundle in the field and a server on the new release
+ * agree without either side changing its payload.
+ */
+export declare class ApiClientTooOldError extends ApiCodedError {
+    /** The fixed `errorCode`; together with status 426 it is what a receiver matches on. */
+    static readonly CODE = "client-too-old";
+    /** HTTP 426 Upgrade Required. */
+    static readonly STATUS_CODE = 426;
+    constructor(message: string, cause?: Error);
+    /** True when a coded failure's status and code are this error's wire identity. */
+    static matches(statusCode: number, errorCode: string | undefined): boolean;
+}
 export {};

package/src/errors/ApiError.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ApiCodedError = exports.ApiNotImplementedError = exports.ApiUnsupportedMediaTypeError = exports.ApiPreconditionFailedError = exports.ApiUnprocessableError = exports.ApiConflictError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiBadGatewayError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = void 0;
+exports.ApiClientTooOldError = exports.ApiCodedError = exports.ApiNotImplementedError = exports.ApiUnsupportedMediaTypeError = exports.ApiPreconditionFailedError = exports.ApiUnprocessableError = exports.ApiConflictError = exports.ApiDependencyBackoffError = exports.ApiUnauthorizedError = exports.ApiBadRequestError = exports.ApiEndUserError = exports.ApiEndpointNotFoundError = exports.ApiConnectionError = exports.ApiRequestTimeoutError = exports.ApiForbiddenError = exports.ApiRateLimitedError = exports.ApiImplementationError = exports.ApiDependencyTimeoutError = exports.ApiUnavailableError = exports.ApiBadGatewayError = exports.ApiDependencyError = exports.ApiNotFoundError = exports.ApiError = void 0;
 /** Category for portable API failures. Concrete subclasses alone define protocol mappings. */
 class ApiError extends Error {
     subType;
@@ -188,4 +188,49 @@ class ApiCodedError extends ApiError {
     }
 }
 exports.ApiCodedError = ApiCodedError;
+/**
+ * The CALLER's build is too old for this server: HTTP **426 Upgrade Required**, errorCode
+ * {@link ApiClientTooOldError.CODE}. It means "upgrade", never "bug".
+ *
+ * WHO THROWS IT: a server gate that compares the build the caller DECLARED (a header, a version in
+ * the request) against the minimum this server still supports. Every webpieces client and server
+ * deployed separately hits this skew (a browser tab left open across a release, a mobile WebView
+ * pinned to an old bundle), and only the SERVER can tell that its caller is too old.
+ *
+ * WHY 426 AND NOT 266: a 266 means "the user must fix something" and its message is shown verbatim,
+ * so a bundle built before the gate existed would print the server's developer text as a user
+ * instruction. A non-266 status reaches every bundle already in the field as a non-user failure.
+ *
+ * WHAT RECEIVERS DO: `ReceivedApiErrorRule` decodes it back into THIS type on every hop
+ * (server-to-server and browser, HTTP and IPC) instead of the `ApiImplementationError` an ordinary
+ * received 4xx becomes. A client treats it as "reload / install the new build", never as a red bug
+ * dialog. It pairs with `allowUpgradeInFlight` (`HttpEndpointOptions`), which declares which calls
+ * an upgrade may cut off: that flag is the client deciding WHEN it may upgrade, this error is the
+ * server saying that it MUST.
+ *
+ * NO user-facing copy: `message` is developer text like every non-end-user kind (it is not published
+ * across the wire), and the receiving client owns the wording it shows. The status and the code are
+ * FIXED here, so a throw site cannot send a 426 that the receivers would not recognise.
+ *
+ * It is an {@link ApiCodedError} on purpose: the wire form is exactly `kind: 'coded'`,
+ * `statusCode: 426`, `errorCode: 'client-too-old'`, which is what an app's own hand-rolled
+ * client-too-old error already publishes, so a bundle in the field and a server on the new release
+ * agree without either side changing its payload.
+ */
+class ApiClientTooOldError extends ApiCodedError {
+    /** The fixed `errorCode`; together with status 426 it is what a receiver matches on. */
+    static CODE = 'client-too-old';
+    /** HTTP 426 Upgrade Required. */
+    static STATUS_CODE = 426;
+    constructor(message, cause) {
+        super(message, ApiClientTooOldError.STATUS_CODE, ApiClientTooOldError.CODE, cause);
+    }
+    /** True when a coded failure's status and code are this error's wire identity. */
+    // webpieces-disable no-function-outside-class -- stateless wire-identity predicate
+    static matches(statusCode, errorCode) {
+        return (statusCode === ApiClientTooOldError.STATUS_CODE &&
+            errorCode === ApiClientTooOldError.CODE);
+    }
+}
+exports.ApiClientTooOldError = ApiClientTooOldError;
 //# sourceMappingURL=ApiError.js.map

package/src/errors/ApiError.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":"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","sourcesContent":["export type ApiErrorKind =\n    | 'end-user'\n    | 'bad-request'\n    | 'unauthorized'\n    | 'forbidden'\n    | 'not-found'\n    | 'endpoint-not-found'\n    | 'request-timeout'\n    | 'rate-limited'\n    | 'conflict'\n    | 'unprocessable'\n    | 'precondition-failed'\n    | 'unsupported-media-type'\n    | 'not-implemented'\n    | 'coded'\n    | 'implementation'\n    | 'dependency'\n    | 'bad-gateway'\n    | 'unavailable'\n    | 'dependency-timeout'\n    | 'dependency-backoff'\n    | 'connection';\n\n/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */\nexport abstract class ApiError extends Error {\n    abstract readonly kind: ApiErrorKind;\n    public subType?: string;\n\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\nexport class ApiNotFoundError extends ApiError {\n    override readonly kind: ApiErrorKind = 'not-found';\n}\nexport class ApiDependencyError extends ApiError {\n    override readonly kind: ApiErrorKind = 'dependency';\n}\n/** A retry-eligible HTTP 502/proxy failure, distinct from a generic dependency defect. */\nexport class ApiBadGatewayError extends ApiDependencyError {\n    override readonly kind = 'bad-gateway' as const;\n}\nexport class ApiUnavailableError extends ApiDependencyError {\n    override readonly kind = 'unavailable' as const;\n}\nexport class ApiDependencyTimeoutError extends ApiDependencyError {\n    override readonly kind = 'dependency-timeout' as const;\n}\n\n/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */\nexport class ApiImplementationError extends ApiError {\n    override readonly kind = 'implementation' as const;\n\n    constructor(\n        message: string,\n        cause?: Error,\n        public readonly serverError = false,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiRateLimitedError extends ApiError {\n    override readonly kind = 'rate-limited' as const;\n}\nexport class ApiForbiddenError extends ApiError {\n    override readonly kind = 'forbidden' as const;\n}\nexport class ApiRequestTimeoutError extends ApiError {\n    override readonly kind = 'request-timeout' as const;\n}\n\n/**\n * A caller-local connection failure. HTTP servers normalize this to ApiImplementationError.\n *\n * `message` is the developer text (it names the url and the transport's own reason); `userMessage`\n * is the stable text an app renders verbatim to an end user, matching `ApiCallTimeoutError.userMessage`\n * so the two transport failures read consistently.\n */\nexport class ApiConnectionError extends ApiError {\n    static readonly USER_MESSAGE =\n        \"We couldn't reach the server. Please check your network connection and try again.\";\n\n    override readonly kind = 'connection' as const;\n    /** End-user text; `message` stays the developer text. */\n    readonly userMessage: string = ApiConnectionError.USER_MESSAGE;\n}\n\n/** The API operation is missing, distinct from an absent domain entity. */\nexport class ApiEndpointNotFoundError extends ApiNotFoundError {\n    override readonly kind = 'endpoint-not-found' as const;\n}\n\n/**\n * The HTTP status an API EDGE answers for an {@link ApiEndUserError}. End-user outcomes only, so\n * nobody tunnels a 5xx/401/403/429 through the end-user channel (auth, rate limiting and dependency\n * failure keep their own types). Extend deliberately.\n */\nexport type EdgeHttpStatus = 400 | 404 | 409 | 422;\n\n/**\n * Expected mistake by the ACTOR driving the call: the input was well-formed but wrong in a way the actor\n * must fix (for example \"the two passwords you entered do not match\"). The actor may be a human user in\n * a GUI OR an LLM calling an MCP tool; the same class serves both. Its message is deliberately\n * caller-safe and is the only ApiError message published verbatim: `ApiErrorCodec` keeps it (and\n * `errorCode`) across every remote hop, so a downstream service's text reaches the GUI or the model\n * byte-for-byte.\n *\n * `edgeHttpStatus` travels the same way. It is what a partner-facing API edge (an http-server router\n * in `'edge'` end-user-status mode) answers instead of 266, so one throw site serves both a GUI and a\n * published REST contract: `throw new ApiEndUserError('That report does not exist', 'report_not_found', 404)`.\n * GUI edges ignore it and keep answering 266.\n */\nexport class ApiEndUserError extends ApiError {\n    override readonly kind = 'end-user' as const;\n\n    constructor(\n        message: string,\n        public errorCode?: string,\n        public edgeHttpStatus?: EdgeHttpStatus,\n        cause?: Error,\n    ) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n\n    /** Narrows a dynamic value (for example one read off the wire) to a legal {@link EdgeHttpStatus}. */\n    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire values are narrowed here\n    static isEdgeHttpStatus(value: unknown): value is EdgeHttpStatus {\n        return value === 400 || value === 404 || value === 409 || value === 422;\n    }\n}\n\n/**\n * Invalid API caller input (malformed, or failed validation). `message` is operator-only diagnostic\n * text and may name internals; it is never published. `callerMessage` (plus `field`) is what a GUI OR\n * an MCP model is shown so it can correct its input, so throw sites that want the caller to\n * self-correct MUST set it.\n */\nexport class ApiBadRequestError extends ApiError {\n    override readonly kind = 'bad-request' as const;\n\n    constructor(\n        message: string,\n        public field?: string,\n        public callerMessage?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiUnauthorizedError extends ApiError {\n    override readonly kind = 'unauthorized' as const;\n\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n\nexport class ApiDependencyBackoffError extends ApiDependencyError {\n    override readonly kind = 'dependency-backoff' as const;\n\n    constructor(\n        message: string,\n        public retryAfterSeconds = 30,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\n/** The request conflicts with the current state of the target resource (HTTP 409). */\nexport class ApiConflictError extends ApiError {\n    override readonly kind = 'conflict' as const;\n}\n\n/** The request was well-formed but semantically unprocessable (HTTP 422). */\nexport class ApiUnprocessableError extends ApiError {\n    override readonly kind = 'unprocessable' as const;\n}\n\n/** A caller-supplied precondition (for example If-Match) did not hold (HTTP 412). */\nexport class ApiPreconditionFailedError extends ApiError {\n    override readonly kind = 'precondition-failed' as const;\n}\n\n/** The request body is in a media type this operation does not accept (HTTP 415). */\nexport class ApiUnsupportedMediaTypeError extends ApiError {\n    override readonly kind = 'unsupported-media-type' as const;\n}\n\n/** The operation exists in the contract but this server does not implement it (HTTP 501). */\nexport class ApiNotImplementedError extends ApiError {\n    override readonly kind = 'not-implemented' as const;\n}\n\n/** Builds the tuple [0, 1, ..., N-1]; tail-recursive so TypeScript can reach 600. */\ntype StatusRange<N extends number, Acc extends number[] = []> = Acc['length'] extends N\n    ? Acc\n    : StatusRange<N, [...Acc, Acc['length']]>;\n\n/**\n * Every integer from 100 through 599 as a literal union. `new ApiCodedError(msg, 600)`,\n * `new ApiCodedError(msg, 99)` and `new ApiCodedError(msg, 404.5)` do not compile; a dynamic\n * `number` must be narrowed with {@link ApiCodedError.isStatusCode} first.\n */\nexport type ApiStatusCode = Exclude<StatusRange<600>[number], StatusRange<100>[number]>;\n\n/**\n * Catch-all carrying an explicit protocol status for outcomes no named ApiError covers. Any code in\n * 100-599 is accepted, including one a named class already owns. `statusCode` and `errorCode` survive\n * every remote hop through `ApiErrorCodec`; `message` stays operator-only like every other non\n * end-user kind. A status below 500 is a caller outcome (except 408 and 429, which mirror\n * `ApiRequestTimeoutError` and `ApiRateLimitedError`); 500 and above is a server/dependency fault.\n */\nexport class ApiCodedError extends ApiError {\n    override readonly kind = 'coded' as const;\n\n    constructor(\n        message: string,\n        public readonly statusCode: ApiStatusCode,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n\n    /** Narrows a dynamic number (for example one read off the wire) to a legal status code. */\n    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire and app values are narrowed here\n    static isStatusCode(value: unknown): value is ApiStatusCode {\n        return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599;\n    }\n\n    /** True when the status describes the caller's mistake rather than a fault on the serving side. */\n    isCallerError(): boolean {\n        return this.statusCode < 500 && this.statusCode !== 408 && this.statusCode !== 429;\n    }\n}\n"]}
+{"version":3,"file":"ApiError.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiError.ts"],"names":[],"mappings":"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","sourcesContent":["export type ApiErrorKind =\n    | 'end-user'\n    | 'bad-request'\n    | 'unauthorized'\n    | 'forbidden'\n    | 'not-found'\n    | 'endpoint-not-found'\n    | 'request-timeout'\n    | 'rate-limited'\n    | 'conflict'\n    | 'unprocessable'\n    | 'precondition-failed'\n    | 'unsupported-media-type'\n    | 'not-implemented'\n    | 'coded'\n    | 'implementation'\n    | 'dependency'\n    | 'bad-gateway'\n    | 'unavailable'\n    | 'dependency-timeout'\n    | 'dependency-backoff'\n    | 'connection';\n\n/** Category for portable API failures. Concrete subclasses alone define protocol mappings. */\nexport abstract class ApiError extends Error {\n    abstract readonly kind: ApiErrorKind;\n    public subType?: string;\n\n    constructor(message: string, cause?: Error) {\n        super(message, { cause });\n        this.name = new.target.name;\n    }\n}\n\nexport class ApiNotFoundError extends ApiError {\n    override readonly kind: ApiErrorKind = 'not-found';\n}\nexport class ApiDependencyError extends ApiError {\n    override readonly kind: ApiErrorKind = 'dependency';\n}\n/** A retry-eligible HTTP 502/proxy failure, distinct from a generic dependency defect. */\nexport class ApiBadGatewayError extends ApiDependencyError {\n    override readonly kind = 'bad-gateway' as const;\n}\nexport class ApiUnavailableError extends ApiDependencyError {\n    override readonly kind = 'unavailable' as const;\n}\nexport class ApiDependencyTimeoutError extends ApiDependencyError {\n    override readonly kind = 'dependency-timeout' as const;\n}\n\n/** A bug or invalid implementation state. Local errors become server errors only after a remote decode. */\nexport class ApiImplementationError extends ApiError {\n    override readonly kind = 'implementation' as const;\n\n    constructor(\n        message: string,\n        cause?: Error,\n        public readonly serverError = false,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiRateLimitedError extends ApiError {\n    override readonly kind = 'rate-limited' as const;\n}\nexport class ApiForbiddenError extends ApiError {\n    override readonly kind = 'forbidden' as const;\n}\nexport class ApiRequestTimeoutError extends ApiError {\n    override readonly kind = 'request-timeout' as const;\n}\n\n/**\n * A caller-local connection failure. HTTP servers normalize this to ApiImplementationError.\n *\n * `message` is the developer text (it names the url and the transport's own reason); `userMessage`\n * is the stable text an app renders verbatim to an end user, matching `ApiCallTimeoutError.userMessage`\n * so the two transport failures read consistently.\n */\nexport class ApiConnectionError extends ApiError {\n    static readonly USER_MESSAGE =\n        \"We couldn't reach the server. Please check your network connection and try again.\";\n\n    override readonly kind = 'connection' as const;\n    /** End-user text; `message` stays the developer text. */\n    readonly userMessage: string = ApiConnectionError.USER_MESSAGE;\n}\n\n/** The API operation is missing, distinct from an absent domain entity. */\nexport class ApiEndpointNotFoundError extends ApiNotFoundError {\n    override readonly kind = 'endpoint-not-found' as const;\n}\n\n/**\n * The HTTP status an API EDGE answers for an {@link ApiEndUserError}. End-user outcomes only, so\n * nobody tunnels a 5xx/401/403/429 through the end-user channel (auth, rate limiting and dependency\n * failure keep their own types). Extend deliberately.\n */\nexport type EdgeHttpStatus = 400 | 404 | 409 | 422;\n\n/**\n * Expected mistake by the ACTOR driving the call: the input was well-formed but wrong in a way the actor\n * must fix (for example \"the two passwords you entered do not match\"). The actor may be a human user in\n * a GUI OR an LLM calling an MCP tool; the same class serves both. Its message is deliberately\n * caller-safe and is the only ApiError message published verbatim: `ApiErrorCodec` keeps it (and\n * `errorCode`) across every remote hop, so a downstream service's text reaches the GUI or the model\n * byte-for-byte.\n *\n * `edgeHttpStatus` travels the same way. It is what a partner-facing API edge (an http-server router\n * in `'edge'` end-user-status mode) answers instead of 266, so one throw site serves both a GUI and a\n * published REST contract: `throw new ApiEndUserError('That report does not exist', 'report_not_found', 404)`.\n * GUI edges ignore it and keep answering 266.\n */\nexport class ApiEndUserError extends ApiError {\n    override readonly kind = 'end-user' as const;\n\n    constructor(\n        message: string,\n        public errorCode?: string,\n        public edgeHttpStatus?: EdgeHttpStatus,\n        cause?: Error,\n    ) {\n        super(message, cause);\n        this.subType = 'USER_ERROR';\n    }\n\n    /** Narrows a dynamic value (for example one read off the wire) to a legal {@link EdgeHttpStatus}. */\n    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire values are narrowed here\n    static isEdgeHttpStatus(value: unknown): value is EdgeHttpStatus {\n        return value === 400 || value === 404 || value === 409 || value === 422;\n    }\n}\n\n/**\n * Invalid API caller input (malformed, or failed validation). `message` is operator-only diagnostic\n * text and may name internals; it is never published. `callerMessage` (plus `field`) is what a GUI OR\n * an MCP model is shown so it can correct its input, so throw sites that want the caller to\n * self-correct MUST set it.\n */\nexport class ApiBadRequestError extends ApiError {\n    override readonly kind = 'bad-request' as const;\n\n    constructor(\n        message: string,\n        public field?: string,\n        public callerMessage?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\nexport class ApiUnauthorizedError extends ApiError {\n    override readonly kind = 'unauthorized' as const;\n\n    constructor(message: string, subType?: string, cause?: Error) {\n        super(message, cause);\n        this.subType = subType;\n    }\n}\n\nexport class ApiDependencyBackoffError extends ApiDependencyError {\n    override readonly kind = 'dependency-backoff' as const;\n\n    constructor(\n        message: string,\n        public retryAfterSeconds = 30,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n}\n\n/** The request conflicts with the current state of the target resource (HTTP 409). */\nexport class ApiConflictError extends ApiError {\n    override readonly kind = 'conflict' as const;\n}\n\n/** The request was well-formed but semantically unprocessable (HTTP 422). */\nexport class ApiUnprocessableError extends ApiError {\n    override readonly kind = 'unprocessable' as const;\n}\n\n/** A caller-supplied precondition (for example If-Match) did not hold (HTTP 412). */\nexport class ApiPreconditionFailedError extends ApiError {\n    override readonly kind = 'precondition-failed' as const;\n}\n\n/** The request body is in a media type this operation does not accept (HTTP 415). */\nexport class ApiUnsupportedMediaTypeError extends ApiError {\n    override readonly kind = 'unsupported-media-type' as const;\n}\n\n/** The operation exists in the contract but this server does not implement it (HTTP 501). */\nexport class ApiNotImplementedError extends ApiError {\n    override readonly kind = 'not-implemented' as const;\n}\n\n/** Builds the tuple [0, 1, ..., N-1]; tail-recursive so TypeScript can reach 600. */\ntype StatusRange<N extends number, Acc extends number[] = []> = Acc['length'] extends N\n    ? Acc\n    : StatusRange<N, [...Acc, Acc['length']]>;\n\n/**\n * Every integer from 100 through 599 as a literal union. `new ApiCodedError(msg, 600)`,\n * `new ApiCodedError(msg, 99)` and `new ApiCodedError(msg, 404.5)` do not compile; a dynamic\n * `number` must be narrowed with {@link ApiCodedError.isStatusCode} first.\n */\nexport type ApiStatusCode = Exclude<StatusRange<600>[number], StatusRange<100>[number]>;\n\n/**\n * Catch-all carrying an explicit protocol status for outcomes no named ApiError covers. Any code in\n * 100-599 is accepted, including one a named class already owns. `statusCode` and `errorCode` survive\n * every remote hop through `ApiErrorCodec`; `message` stays operator-only like every other non\n * end-user kind. A status below 500 is a caller outcome (except 408 and 429, which mirror\n * `ApiRequestTimeoutError` and `ApiRateLimitedError`); 500 and above is a server/dependency fault.\n */\nexport class ApiCodedError extends ApiError {\n    override readonly kind = 'coded' as const;\n\n    constructor(\n        message: string,\n        public readonly statusCode: ApiStatusCode,\n        public errorCode?: string,\n        cause?: Error,\n    ) {\n        super(message, cause);\n    }\n\n    /** Narrows a dynamic number (for example one read off the wire) to a legal status code. */\n    // webpieces-disable no-function-outside-class -- stateless status guard; webpieces-disable no-any-unknown -- wire and app values are narrowed here\n    static isStatusCode(value: unknown): value is ApiStatusCode {\n        return typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599;\n    }\n\n    /** True when the status describes the caller's mistake rather than a fault on the serving side. */\n    isCallerError(): boolean {\n        return this.statusCode < 500 && this.statusCode !== 408 && this.statusCode !== 429;\n    }\n}\n\n/**\n * The CALLER's build is too old for this server: HTTP **426 Upgrade Required**, errorCode\n * {@link ApiClientTooOldError.CODE}. It means \"upgrade\", never \"bug\".\n *\n * WHO THROWS IT: a server gate that compares the build the caller DECLARED (a header, a version in\n * the request) against the minimum this server still supports. Every webpieces client and server\n * deployed separately hits this skew (a browser tab left open across a release, a mobile WebView\n * pinned to an old bundle), and only the SERVER can tell that its caller is too old.\n *\n * WHY 426 AND NOT 266: a 266 means \"the user must fix something\" and its message is shown verbatim,\n * so a bundle built before the gate existed would print the server's developer text as a user\n * instruction. A non-266 status reaches every bundle already in the field as a non-user failure.\n *\n * WHAT RECEIVERS DO: `ReceivedApiErrorRule` decodes it back into THIS type on every hop\n * (server-to-server and browser, HTTP and IPC) instead of the `ApiImplementationError` an ordinary\n * received 4xx becomes. A client treats it as \"reload / install the new build\", never as a red bug\n * dialog. It pairs with `allowUpgradeInFlight` (`HttpEndpointOptions`), which declares which calls\n * an upgrade may cut off: that flag is the client deciding WHEN it may upgrade, this error is the\n * server saying that it MUST.\n *\n * NO user-facing copy: `message` is developer text like every non-end-user kind (it is not published\n * across the wire), and the receiving client owns the wording it shows. The status and the code are\n * FIXED here, so a throw site cannot send a 426 that the receivers would not recognise.\n *\n * It is an {@link ApiCodedError} on purpose: the wire form is exactly `kind: 'coded'`,\n * `statusCode: 426`, `errorCode: 'client-too-old'`, which is what an app's own hand-rolled\n * client-too-old error already publishes, so a bundle in the field and a server on the new release\n * agree without either side changing its payload.\n */\nexport class ApiClientTooOldError extends ApiCodedError {\n    /** The fixed `errorCode`; together with status 426 it is what a receiver matches on. */\n    static readonly CODE = 'client-too-old';\n    /** HTTP 426 Upgrade Required. */\n    static readonly STATUS_CODE = 426;\n\n    constructor(message: string, cause?: Error) {\n        super(message, ApiClientTooOldError.STATUS_CODE, ApiClientTooOldError.CODE, cause);\n    }\n\n    /** True when a coded failure's status and code are this error's wire identity. */\n    // webpieces-disable no-function-outside-class -- stateless wire-identity predicate\n    static matches(statusCode: number, errorCode: string | undefined): boolean {\n        return (\n            statusCode === ApiClientTooOldError.STATUS_CODE &&\n            errorCode === ApiClientTooOldError.CODE\n        );\n    }\n}\n"]}

package/src/errors/ApiErrorCodec.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ApiErrorCodec = exports.ApiErrorPayload = void 0;
 const ApiError_1 = require("./ApiError");
 const errorUtils_1 = require("../lib/errorUtils");
+const EndUserErrorRegistry_1 = require("./EndUserErrorRegistry");
 /** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */
 class ApiErrorPayload {
     kind;
@@ -108,7 +109,8 @@ class ApiErrorCodec {
         const message = this.text(field('message')) ?? this.message(kind);
         switch (kind) {
             case 'end-user':
-                return new ApiError_1.ApiEndUserError(message, this.text(field('errorCode')), this.edgeStatus(field('edgeHttpStatus')));
+                // The registered SUBCLASS for this errorCode, else the base type with the code intact.
+                return EndUserErrorRegistry_1.EndUserErrorRegistry.create(message, this.text(field('errorCode')), this.edgeStatus(field('edgeHttpStatus')));
             case 'bad-request':
                 return new ApiError_1.ApiBadRequestError(message, this.text(field('field')), this.text(field('callerMessage')));
             case 'unauthorized':
@@ -157,7 +159,12 @@ class ApiErrorCodec {
     static coded(message, statusCode, errorCode) {
         if (!ApiError_1.ApiCodedError.isStatusCode(statusCode))
             return this.remoteImplementationError();
-        return new ApiError_1.ApiCodedError(message, statusCode, this.text(errorCode));
+        const code = this.text(errorCode);
+        // The one coded failure webpieces names: rebuilt as its own type so a receiver sees
+        // "upgrade", never a generic coded 4xx (issue #1172).
+        if (ApiError_1.ApiClientTooOldError.matches(statusCode, code))
+            return new ApiError_1.ApiClientTooOldError(message);
+        return new ApiError_1.ApiCodedError(message, statusCode, code);
     }
     // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors
     static remoteImplementationError() {

package/src/errors/ApiErrorCodec.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiErrorCodec.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorCodec.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiBadGatewayError,\n    ApiCodedError,\n    ApiConflictError,\n    ApiConnectionError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiError,\n    ApiErrorKind,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiNotImplementedError,\n    ApiPreconditionFailedError,\n    ApiRateLimitedError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n    ApiUnavailableError,\n    ApiUnprocessableError,\n    ApiUnsupportedMediaTypeError,\n    EdgeHttpStatus,\n} from './ApiError';\nimport { toError } from '../lib/errorUtils';\n\n/** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */\nexport class ApiErrorPayload {\n    public cause?: ApiErrorPayload;\n    public subType?: string;\n    public field?: string;\n    public callerMessage?: string;\n    public errorCode?: string;\n    public retryAfterSeconds?: number;\n    public statusCode?: number;\n    /** {@link ApiEndUserError.edgeHttpStatus}; absent when the thrower (or an older peer) set none. */\n    public edgeHttpStatus?: number;\n\n    constructor(\n        public kind: string = 'implementation',\n        public message: string = 'Internal Error',\n    ) {}\n}\n\n/** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */\nexport class ApiErrorCodec {\n    /**\n     * Encode a thrown error faithfully. The input is an `Error`, never `unknown`: every caller in\n     * the framework has already narrowed with `toError` at its catch, and the `unknown` this used to\n     * advertise leaked out of the PRIVATE `.cause` recursion below (`Error.cause` is typed `unknown`\n     * in TypeScript), which is an internal concern.\n     *\n     * This is the FAITHFUL encode: it publishes `kind` exactly as the error declares it. The\n     * boundary rule that a caller-local `ApiConnectionError` publishes as `implementation` belongs\n     * to {@link ApiErrorBoundary}, which every protocol edge uses instead of calling this directly.\n     */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec\n    static encode(error: Error): ApiErrorPayload {\n        return this.encodeDepth(error, 0);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec\n    private static encodeDepth(error: Error, depth: number): ApiErrorPayload {\n        const kind = error instanceof ApiError ? error.kind : 'implementation';\n        const payload = new ApiErrorPayload(kind, this.publicMessage(error, kind));\n        if (error instanceof ApiError) payload.subType = this.text(error.subType);\n        if (error instanceof ApiEndUserError) {\n            payload.errorCode = this.text(error.errorCode);\n            payload.edgeHttpStatus = error.edgeHttpStatus;\n        }\n        if (error instanceof ApiCodedError) {\n            payload.statusCode = error.statusCode;\n            payload.errorCode = this.text(error.errorCode);\n        }\n        if (error instanceof ApiBadRequestError) {\n            payload.field = this.text(error.field);\n            payload.callerMessage = this.text(error.callerMessage);\n        }\n        if (error instanceof ApiDependencyBackoffError) {\n            payload.retryAfterSeconds = this.wait(error.retryAfterSeconds);\n        }\n        if (depth < 3) {\n            // `Error.cause` is `unknown` by construction, so the recursion narrows it with `toError`\n            // exactly as a catch block would — and then deals only in `Error` like everything else.\n            const cause = Object.getOwnPropertyDescriptor(error, 'cause')?.value;\n            if (cause !== undefined && cause !== null) {\n                payload.cause = this.encodeDepth(toError(cause), depth + 1);\n            }\n        }\n        return payload;\n    }\n\n    /** Decode a value received from another process. Implementation failures are marked remote. */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- wire values require validation\n    static decode(value: unknown): ApiError {\n        return this.decodeDepth(value, 0);\n    }\n\n    /** Whether a body carries a recognized Webpieces semantic discriminator. */\n    // webpieces-disable no-function-outside-class -- stateless wire discriminator check; webpieces-disable no-any-unknown -- wire values require validation\n    static isPayload(value: unknown): boolean {\n        if (typeof value !== 'object' || value === null) return false;\n        const kind = Object.getOwnPropertyDescriptor(value, 'kind')?.value;\n        return typeof kind === 'string' && this.kinds.has(kind as ApiErrorKind);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- remote causes require validation\n    private static decodeDepth(value: unknown, depth: number): ApiError {\n        const error = this.decodeOne(value);\n        if (typeof value === 'object' && value !== null && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(value, 'cause')?.value;\n            if (typeof cause === 'object' && cause !== null) {\n                // webpieces-disable no-anonymous-object-literals -- standard descriptor preserves Error.cause semantics\n                Object.defineProperty(error, 'cause', {\n                    value: this.decodeDepth(cause, depth + 1),\n                    configurable: true,\n                    writable: true,\n                });\n            }\n        }\n        return error;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted wire codec; webpieces-disable no-any-unknown -- wire fields require validation\n    private static decodeOne(value: unknown): ApiError {\n        if (typeof value !== 'object' || value === null) return this.remoteImplementationError();\n        // webpieces-disable no-any-unknown -- own wire fields remain untrusted until narrowed\n        const field = (key: string): unknown => Object.getOwnPropertyDescriptor(value, key)?.value;\n        const kind = field('kind');\n        const message = this.text(field('message')) ?? this.message(kind);\n        switch (kind) {\n            case 'end-user':\n                return new ApiEndUserError(\n                    message,\n                    this.text(field('errorCode')),\n                    this.edgeStatus(field('edgeHttpStatus')),\n                );\n            case 'bad-request':\n                return new ApiBadRequestError(\n                    message,\n                    this.text(field('field')),\n                    this.text(field('callerMessage')),\n                );\n            case 'unauthorized':\n                return new ApiUnauthorizedError(message, this.text(field('subType')));\n            case 'forbidden':\n                return new ApiForbiddenError(message);\n            case 'not-found':\n                return new ApiNotFoundError(message);\n            case 'endpoint-not-found':\n                return new ApiEndpointNotFoundError(message);\n            case 'request-timeout':\n                return new ApiRequestTimeoutError(message);\n            case 'rate-limited':\n                return new ApiRateLimitedError(message);\n            case 'conflict':\n                return new ApiConflictError(message);\n            case 'unprocessable':\n                return new ApiUnprocessableError(message);\n            case 'precondition-failed':\n                return new ApiPreconditionFailedError(message);\n            case 'unsupported-media-type':\n                return new ApiUnsupportedMediaTypeError(message);\n            case 'not-implemented':\n                return new ApiNotImplementedError(message);\n            case 'coded':\n                return this.coded(message, field('statusCode'), field('errorCode'));\n            case 'dependency':\n                return new ApiDependencyError(message);\n            case 'bad-gateway':\n                return new ApiBadGatewayError(message);\n            case 'unavailable':\n                return new ApiUnavailableError(message);\n            case 'dependency-timeout':\n                return new ApiDependencyTimeoutError(message);\n            case 'dependency-backoff':\n                return new ApiDependencyBackoffError(\n                    message,\n                    this.wait(field('retryAfterSeconds')),\n                );\n            case 'connection':\n                return new ApiConnectionError(message);\n            case 'implementation':\n                return new ApiImplementationError(message, undefined, true);\n            default:\n                return this.remoteImplementationError();\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- coded wire decode; webpieces-disable no-any-unknown -- wire fields require validation\n    private static coded(message: string, statusCode: unknown, errorCode: unknown): ApiError {\n        if (!ApiCodedError.isStatusCode(statusCode)) return this.remoteImplementationError();\n        return new ApiCodedError(message, statusCode, this.text(errorCode));\n    }\n\n    // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors\n    private static remoteImplementationError(): ApiImplementationError {\n        return new ApiImplementationError('Internal Error', undefined, true);\n    }\n\n    // webpieces-disable no-function-outside-class -- caller-safe message selection\n    private static publicMessage(error: Error, kind: ApiErrorKind): string {\n        if (error instanceof ApiEndUserError) return error.message.slice(0, 4096);\n        return this.message(kind);\n    }\n\n    // webpieces-disable no-function-outside-class -- wire string bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static text(value: unknown): string | undefined {\n        return typeof value === 'string' ? value.slice(0, 4096) : undefined;\n    }\n\n    /** Tolerant: a peer that sends nothing, or a status outside {@link EdgeHttpStatus}, decodes as undefined. */\n    // webpieces-disable no-function-outside-class -- wire status bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static edgeStatus(value: unknown): EdgeHttpStatus | undefined {\n        return ApiEndUserError.isEdgeHttpStatus(value) ? value : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- wire number bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static wait(value: unknown): number | undefined {\n        return typeof value === 'number' && Number.isFinite(value) && value >= 0\n            ? Math.min(value, 86400)\n            : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted generic messages; webpieces-disable no-any-unknown -- discriminator is validated by switch\n    private static message(kind: unknown): string {\n        switch (kind) {\n            case 'end-user':\n                return 'End User Error';\n            case 'bad-request':\n                return 'Bad Request';\n            case 'unauthorized':\n                return 'Unauthorized';\n            case 'forbidden':\n                return 'Forbidden';\n            case 'not-found':\n                return 'Not Found';\n            case 'endpoint-not-found':\n                return 'Endpoint Not Found';\n            case 'request-timeout':\n                return 'Request Timeout';\n            case 'rate-limited':\n                return 'Rate Limited';\n            case 'conflict':\n                return 'Conflict';\n            case 'unprocessable':\n                return 'Unprocessable Content';\n            case 'precondition-failed':\n                return 'Precondition Failed';\n            case 'unsupported-media-type':\n                return 'Unsupported Media Type';\n            case 'not-implemented':\n                return 'Not Implemented';\n            case 'coded':\n                return 'Request Failed';\n            case 'dependency':\n                return 'Dependency Error';\n            case 'bad-gateway':\n                return 'Bad Gateway';\n            case 'unavailable':\n                return 'Service Unavailable';\n            case 'dependency-timeout':\n                return 'Dependency Timeout';\n            case 'dependency-backoff':\n                return 'Dependency Unavailable';\n            case 'connection':\n                return 'Connection Error';\n            default:\n                return 'Internal Error';\n        }\n    }\n\n    private static readonly kinds: ReadonlySet<ApiErrorKind> = new Set<ApiErrorKind>([\n        'end-user',\n        'bad-request',\n        'unauthorized',\n        'forbidden',\n        'not-found',\n        'endpoint-not-found',\n        'request-timeout',\n        'rate-limited',\n        'conflict',\n        'unprocessable',\n        'precondition-failed',\n        'unsupported-media-type',\n        'not-implemented',\n        'coded',\n        'implementation',\n        'dependency',\n        'bad-gateway',\n        'unavailable',\n        'dependency-timeout',\n        'dependency-backoff',\n        'connection',\n    ]);\n}\n"]}
+{"version":3,"file":"ApiErrorCodec.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ApiErrorCodec.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n    ApiBadRequestError,\n    ApiBadGatewayError,\n    ApiClientTooOldError,\n    ApiCodedError,\n    ApiConflictError,\n    ApiConnectionError,\n    ApiDependencyBackoffError,\n    ApiDependencyError,\n    ApiDependencyTimeoutError,\n    ApiEndpointNotFoundError,\n    ApiEndUserError,\n    ApiError,\n    ApiErrorKind,\n    ApiForbiddenError,\n    ApiImplementationError,\n    ApiNotFoundError,\n    ApiNotImplementedError,\n    ApiPreconditionFailedError,\n    ApiRateLimitedError,\n    ApiRequestTimeoutError,\n    ApiUnauthorizedError,\n    ApiUnavailableError,\n    ApiUnprocessableError,\n    ApiUnsupportedMediaTypeError,\n    EdgeHttpStatus,\n} from './ApiError';\nimport { toError } from '../lib/errorUtils';\nimport { EndUserErrorRegistry } from './EndUserErrorRegistry';\n\n/** Allowlisted transport-neutral envelope. It never contains stacks or arbitrary properties. */\nexport class ApiErrorPayload {\n    public cause?: ApiErrorPayload;\n    public subType?: string;\n    public field?: string;\n    public callerMessage?: string;\n    public errorCode?: string;\n    public retryAfterSeconds?: number;\n    public statusCode?: number;\n    /** {@link ApiEndUserError.edgeHttpStatus}; absent when the thrower (or an older peer) set none. */\n    public edgeHttpStatus?: number;\n\n    constructor(\n        public kind: string = 'implementation',\n        public message: string = 'Internal Error',\n    ) {}\n}\n\n/** Bounded safe codec shared by HTTP, IPC, and other remote adapters. */\nexport class ApiErrorCodec {\n    /**\n     * Encode a thrown error faithfully. The input is an `Error`, never `unknown`: every caller in\n     * the framework has already narrowed with `toError` at its catch, and the `unknown` this used to\n     * advertise leaked out of the PRIVATE `.cause` recursion below (`Error.cause` is typed `unknown`\n     * in TypeScript), which is an internal concern.\n     *\n     * This is the FAITHFUL encode: it publishes `kind` exactly as the error declares it. The\n     * boundary rule that a caller-local `ApiConnectionError` publishes as `implementation` belongs\n     * to {@link ApiErrorBoundary}, which every protocol edge uses instead of calling this directly.\n     */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec\n    static encode(error: Error): ApiErrorPayload {\n        return this.encodeDepth(error, 0);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec\n    private static encodeDepth(error: Error, depth: number): ApiErrorPayload {\n        const kind = error instanceof ApiError ? error.kind : 'implementation';\n        const payload = new ApiErrorPayload(kind, this.publicMessage(error, kind));\n        if (error instanceof ApiError) payload.subType = this.text(error.subType);\n        if (error instanceof ApiEndUserError) {\n            payload.errorCode = this.text(error.errorCode);\n            payload.edgeHttpStatus = error.edgeHttpStatus;\n        }\n        if (error instanceof ApiCodedError) {\n            payload.statusCode = error.statusCode;\n            payload.errorCode = this.text(error.errorCode);\n        }\n        if (error instanceof ApiBadRequestError) {\n            payload.field = this.text(error.field);\n            payload.callerMessage = this.text(error.callerMessage);\n        }\n        if (error instanceof ApiDependencyBackoffError) {\n            payload.retryAfterSeconds = this.wait(error.retryAfterSeconds);\n        }\n        if (depth < 3) {\n            // `Error.cause` is `unknown` by construction, so the recursion narrows it with `toError`\n            // exactly as a catch block would — and then deals only in `Error` like everything else.\n            const cause = Object.getOwnPropertyDescriptor(error, 'cause')?.value;\n            if (cause !== undefined && cause !== null) {\n                payload.cause = this.encodeDepth(toError(cause), depth + 1);\n            }\n        }\n        return payload;\n    }\n\n    /** Decode a value received from another process. Implementation failures are marked remote. */\n    // webpieces-disable no-function-outside-class -- stateless public transport codec; webpieces-disable no-any-unknown -- wire values require validation\n    static decode(value: unknown): ApiError {\n        return this.decodeDepth(value, 0);\n    }\n\n    /** Whether a body carries a recognized Webpieces semantic discriminator. */\n    // webpieces-disable no-function-outside-class -- stateless wire discriminator check; webpieces-disable no-any-unknown -- wire values require validation\n    static isPayload(value: unknown): boolean {\n        if (typeof value !== 'object' || value === null) return false;\n        const kind = Object.getOwnPropertyDescriptor(value, 'kind')?.value;\n        return typeof kind === 'string' && this.kinds.has(kind as ApiErrorKind);\n    }\n\n    // webpieces-disable no-function-outside-class -- recursive bounded transport codec; webpieces-disable no-any-unknown -- remote causes require validation\n    private static decodeDepth(value: unknown, depth: number): ApiError {\n        const error = this.decodeOne(value);\n        if (typeof value === 'object' && value !== null && depth < 3) {\n            const cause = Object.getOwnPropertyDescriptor(value, 'cause')?.value;\n            if (typeof cause === 'object' && cause !== null) {\n                // webpieces-disable no-anonymous-object-literals -- standard descriptor preserves Error.cause semantics\n                Object.defineProperty(error, 'cause', {\n                    value: this.decodeDepth(cause, depth + 1),\n                    configurable: true,\n                    writable: true,\n                });\n            }\n        }\n        return error;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted wire codec; webpieces-disable no-any-unknown -- wire fields require validation\n    private static decodeOne(value: unknown): ApiError {\n        if (typeof value !== 'object' || value === null) return this.remoteImplementationError();\n        // webpieces-disable no-any-unknown -- own wire fields remain untrusted until narrowed\n        const field = (key: string): unknown => Object.getOwnPropertyDescriptor(value, key)?.value;\n        const kind = field('kind');\n        const message = this.text(field('message')) ?? this.message(kind);\n        switch (kind) {\n            case 'end-user':\n                // The registered SUBCLASS for this errorCode, else the base type with the code intact.\n                return EndUserErrorRegistry.create(\n                    message,\n                    this.text(field('errorCode')),\n                    this.edgeStatus(field('edgeHttpStatus')),\n                );\n            case 'bad-request':\n                return new ApiBadRequestError(\n                    message,\n                    this.text(field('field')),\n                    this.text(field('callerMessage')),\n                );\n            case 'unauthorized':\n                return new ApiUnauthorizedError(message, this.text(field('subType')));\n            case 'forbidden':\n                return new ApiForbiddenError(message);\n            case 'not-found':\n                return new ApiNotFoundError(message);\n            case 'endpoint-not-found':\n                return new ApiEndpointNotFoundError(message);\n            case 'request-timeout':\n                return new ApiRequestTimeoutError(message);\n            case 'rate-limited':\n                return new ApiRateLimitedError(message);\n            case 'conflict':\n                return new ApiConflictError(message);\n            case 'unprocessable':\n                return new ApiUnprocessableError(message);\n            case 'precondition-failed':\n                return new ApiPreconditionFailedError(message);\n            case 'unsupported-media-type':\n                return new ApiUnsupportedMediaTypeError(message);\n            case 'not-implemented':\n                return new ApiNotImplementedError(message);\n            case 'coded':\n                return this.coded(message, field('statusCode'), field('errorCode'));\n            case 'dependency':\n                return new ApiDependencyError(message);\n            case 'bad-gateway':\n                return new ApiBadGatewayError(message);\n            case 'unavailable':\n                return new ApiUnavailableError(message);\n            case 'dependency-timeout':\n                return new ApiDependencyTimeoutError(message);\n            case 'dependency-backoff':\n                return new ApiDependencyBackoffError(\n                    message,\n                    this.wait(field('retryAfterSeconds')),\n                );\n            case 'connection':\n                return new ApiConnectionError(message);\n            case 'implementation':\n                return new ApiImplementationError(message, undefined, true);\n            default:\n                return this.remoteImplementationError();\n        }\n    }\n\n    // webpieces-disable no-function-outside-class -- coded wire decode; webpieces-disable no-any-unknown -- wire fields require validation\n    private static coded(message: string, statusCode: unknown, errorCode: unknown): ApiError {\n        if (!ApiCodedError.isStatusCode(statusCode)) return this.remoteImplementationError();\n        const code = this.text(errorCode);\n        // The one coded failure webpieces names: rebuilt as its own type so a receiver sees\n        // \"upgrade\", never a generic coded 4xx (issue #1172).\n        if (ApiClientTooOldError.matches(statusCode, code))\n            return new ApiClientTooOldError(message);\n        return new ApiCodedError(message, statusCode, code);\n    }\n\n    // webpieces-disable no-function-outside-class -- concrete normalization for malformed remote errors\n    private static remoteImplementationError(): ApiImplementationError {\n        return new ApiImplementationError('Internal Error', undefined, true);\n    }\n\n    // webpieces-disable no-function-outside-class -- caller-safe message selection\n    private static publicMessage(error: Error, kind: ApiErrorKind): string {\n        if (error instanceof ApiEndUserError) return error.message.slice(0, 4096);\n        return this.message(kind);\n    }\n\n    // webpieces-disable no-function-outside-class -- wire string bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static text(value: unknown): string | undefined {\n        return typeof value === 'string' ? value.slice(0, 4096) : undefined;\n    }\n\n    /** Tolerant: a peer that sends nothing, or a status outside {@link EdgeHttpStatus}, decodes as undefined. */\n    // webpieces-disable no-function-outside-class -- wire status bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static edgeStatus(value: unknown): EdgeHttpStatus | undefined {\n        return ApiEndUserError.isEdgeHttpStatus(value) ? value : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- wire number bound; webpieces-disable no-any-unknown -- wire values require validation\n    private static wait(value: unknown): number | undefined {\n        return typeof value === 'number' && Number.isFinite(value) && value >= 0\n            ? Math.min(value, 86400)\n            : undefined;\n    }\n\n    // webpieces-disable no-function-outside-class -- allowlisted generic messages; webpieces-disable no-any-unknown -- discriminator is validated by switch\n    private static message(kind: unknown): string {\n        switch (kind) {\n            case 'end-user':\n                return 'End User Error';\n            case 'bad-request':\n                return 'Bad Request';\n            case 'unauthorized':\n                return 'Unauthorized';\n            case 'forbidden':\n                return 'Forbidden';\n            case 'not-found':\n                return 'Not Found';\n            case 'endpoint-not-found':\n                return 'Endpoint Not Found';\n            case 'request-timeout':\n                return 'Request Timeout';\n            case 'rate-limited':\n                return 'Rate Limited';\n            case 'conflict':\n                return 'Conflict';\n            case 'unprocessable':\n                return 'Unprocessable Content';\n            case 'precondition-failed':\n                return 'Precondition Failed';\n            case 'unsupported-media-type':\n                return 'Unsupported Media Type';\n            case 'not-implemented':\n                return 'Not Implemented';\n            case 'coded':\n                return 'Request Failed';\n            case 'dependency':\n                return 'Dependency Error';\n            case 'bad-gateway':\n                return 'Bad Gateway';\n            case 'unavailable':\n                return 'Service Unavailable';\n            case 'dependency-timeout':\n                return 'Dependency Timeout';\n            case 'dependency-backoff':\n                return 'Dependency Unavailable';\n            case 'connection':\n                return 'Connection Error';\n            default:\n                return 'Internal Error';\n        }\n    }\n\n    private static readonly kinds: ReadonlySet<ApiErrorKind> = new Set<ApiErrorKind>([\n        'end-user',\n        'bad-request',\n        'unauthorized',\n        'forbidden',\n        'not-found',\n        'endpoint-not-found',\n        'request-timeout',\n        'rate-limited',\n        'conflict',\n        'unprocessable',\n        'precondition-failed',\n        'unsupported-media-type',\n        'not-implemented',\n        'coded',\n        'implementation',\n        'dependency',\n        'bad-gateway',\n        'unavailable',\n        'dependency-timeout',\n        'dependency-backoff',\n        'connection',\n    ]);\n}\n"]}

package/src/errors/ClientRole.d.ts

@@ -0,0 +1,27 @@
+/**
+ * WHO is receiving an error: the one fact {@link ReceivedApiErrorRule} cannot read off the wire.
+ *
+ * Every client declares it at SETUP, explicitly, and there is no default (issue #1173): a node
+ * `ClientConfig`, a browser `ClientConfig`, an `IpcClientFactory`. It decides exactly one thing today,
+ * what a received **401 Unauthorized** means, and the two answers have opposite owners:
+ *
+ * - {@link ClientRole.END_USER_CLIENT} — a browser bundle, an Expo shell, a remote MCP client. The
+ *   credential it presented IS the user's session, so a 401 means "log in again": it is decoded as
+ *   `ApiUnauthorizedError`, the type the app's re-login path catches.
+ * - {@link ClientRole.SERVER} — a server calling another server. The credential it presented is ITS
+ *   OWN (a service token, a shared secret), so a 401 is this service's credential or configuration
+ *   bug: `ApiImplementationError`, a 500 to its own caller. Relaying the 401 would tell the browser
+ *   "your session expired", log the user out for a backend misconfiguration, and stop paging the team
+ *   that owns the broken credential.
+ *
+ * A server that rejects the INCOMING user's token throws `ApiUnauthorizedError` itself; that is a 401
+ * it ORIGINATES, and the end-user client then decodes it typed.
+ *
+ * Why no default: the safe-looking choice is different for each half of the estate (SERVER is right
+ * for a backend, wrong for a browser), so any default would be silently wrong for one of them. Stating
+ * it costs one argument at each client's setup.
+ */
+export declare enum ClientRole {
+    END_USER_CLIENT = "end-user-client",
+    SERVER = "server"
+}

package/src/errors/ClientRole.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientRole = void 0;
+/**
+ * WHO is receiving an error: the one fact {@link ReceivedApiErrorRule} cannot read off the wire.
+ *
+ * Every client declares it at SETUP, explicitly, and there is no default (issue #1173): a node
+ * `ClientConfig`, a browser `ClientConfig`, an `IpcClientFactory`. It decides exactly one thing today,
+ * what a received **401 Unauthorized** means, and the two answers have opposite owners:
+ *
+ * - {@link ClientRole.END_USER_CLIENT} — a browser bundle, an Expo shell, a remote MCP client. The
+ *   credential it presented IS the user's session, so a 401 means "log in again": it is decoded as
+ *   `ApiUnauthorizedError`, the type the app's re-login path catches.
+ * - {@link ClientRole.SERVER} — a server calling another server. The credential it presented is ITS
+ *   OWN (a service token, a shared secret), so a 401 is this service's credential or configuration
+ *   bug: `ApiImplementationError`, a 500 to its own caller. Relaying the 401 would tell the browser
+ *   "your session expired", log the user out for a backend misconfiguration, and stop paging the team
+ *   that owns the broken credential.
+ *
+ * A server that rejects the INCOMING user's token throws `ApiUnauthorizedError` itself; that is a 401
+ * it ORIGINATES, and the end-user client then decodes it typed.
+ *
+ * Why no default: the safe-looking choice is different for each half of the estate (SERVER is right
+ * for a backend, wrong for a browser), so any default would be silently wrong for one of them. Stating
+ * it costs one argument at each client's setup.
+ */
+var ClientRole;
+(function (ClientRole) {
+    ClientRole["END_USER_CLIENT"] = "end-user-client";
+    ClientRole["SERVER"] = "server";
+})(ClientRole || (exports.ClientRole = ClientRole = {}));
+//# sourceMappingURL=ClientRole.js.map

package/src/errors/ClientRole.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientRole.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/ClientRole.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,IAAY,UAGX;AAHD,WAAY,UAAU;IAClB,iDAAmC,CAAA;IACnC,+BAAiB,CAAA;AACrB,CAAC,EAHW,UAAU,0BAAV,UAAU,QAGrB","sourcesContent":["/**\n * WHO is receiving an error: the one fact {@link ReceivedApiErrorRule} cannot read off the wire.\n *\n * Every client declares it at SETUP, explicitly, and there is no default (issue #1173): a node\n * `ClientConfig`, a browser `ClientConfig`, an `IpcClientFactory`. It decides exactly one thing today,\n * what a received **401 Unauthorized** means, and the two answers have opposite owners:\n *\n * - {@link ClientRole.END_USER_CLIENT} — a browser bundle, an Expo shell, a remote MCP client. The\n *   credential it presented IS the user's session, so a 401 means \"log in again\": it is decoded as\n *   `ApiUnauthorizedError`, the type the app's re-login path catches.\n * - {@link ClientRole.SERVER} — a server calling another server. The credential it presented is ITS\n *   OWN (a service token, a shared secret), so a 401 is this service's credential or configuration\n *   bug: `ApiImplementationError`, a 500 to its own caller. Relaying the 401 would tell the browser\n *   \"your session expired\", log the user out for a backend misconfiguration, and stop paging the team\n *   that owns the broken credential.\n *\n * A server that rejects the INCOMING user's token throws `ApiUnauthorizedError` itself; that is a 401\n * it ORIGINATES, and the end-user client then decodes it typed.\n *\n * Why no default: the safe-looking choice is different for each half of the estate (SERVER is right\n * for a backend, wrong for a browser), so any default would be silently wrong for one of them. Stating\n * it costs one argument at each client's setup.\n */\nexport enum ClientRole {\n    END_USER_CLIENT = 'end-user-client',\n    SERVER = 'server',\n}\n"]}

package/src/errors/EndUserErrorCode.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The grammar of `ApiEndUserError.errorCode`: `<code>[:<detail>]`.
+ *
+ * - `<code>` names WHICH mistake it was (`user-not-found`, `terms-not-accepted`). It is what
+ *   {@link EndUserErrorRegistry} matches on to rebuild the subclass on the receiving side, so it must
+ *   not itself contain a `:`.
+ * - `<detail>` is optional DATA the client acts on (the id that was not found, the terms version to
+ *   accept), never prose: prose belongs in the message. Everything after the FIRST `:` is the detail,
+ *   so a detail may itself contain colons.
+ *
+ * Kept as one tiny stateless class so a throw site, the registry and an app's own client code all
+ * split the string the same way.
+ */
+export declare class EndUserErrorCode {
+    static readonly SEPARATOR = ":";
+    /** `code` alone, or `code:detail` when a detail is given. */
+    static format(code: string, detail?: string): string;
+    /** The `<code>` part: everything before the first `:`, or the whole string when there is none. */
+    static codeOf(errorCode: string): string;
+    /** The `<detail>` part: everything after the first `:`, or undefined when there is none. */
+    static detailOf(errorCode: string): string | undefined;
+}

package/src/errors/EndUserErrorCode.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EndUserErrorCode = void 0;
+/**
+ * The grammar of `ApiEndUserError.errorCode`: `<code>[:<detail>]`.
+ *
+ * - `<code>` names WHICH mistake it was (`user-not-found`, `terms-not-accepted`). It is what
+ *   {@link EndUserErrorRegistry} matches on to rebuild the subclass on the receiving side, so it must
+ *   not itself contain a `:`.
+ * - `<detail>` is optional DATA the client acts on (the id that was not found, the terms version to
+ *   accept), never prose: prose belongs in the message. Everything after the FIRST `:` is the detail,
+ *   so a detail may itself contain colons.
+ *
+ * Kept as one tiny stateless class so a throw site, the registry and an app's own client code all
+ * split the string the same way.
+ */
+class EndUserErrorCode {
+    static SEPARATOR = ':';
+    /** `code` alone, or `code:detail` when a detail is given. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static format(code, detail) {
+        return detail === undefined ? code : `${code}${EndUserErrorCode.SEPARATOR}${detail}`;
+    }
+    /** The `<code>` part: everything before the first `:`, or the whole string when there is none. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static codeOf(errorCode) {
+        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);
+        return at < 0 ? errorCode : errorCode.slice(0, at);
+    }
+    /** The `<detail>` part: everything after the first `:`, or undefined when there is none. */
+    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server
+    static detailOf(errorCode) {
+        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);
+        return at < 0 ? undefined : errorCode.slice(at + 1);
+    }
+}
+exports.EndUserErrorCode = EndUserErrorCode;
+//# sourceMappingURL=EndUserErrorCode.js.map

package/src/errors/EndUserErrorCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EndUserErrorCode.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/errors/EndUserErrorCode.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;GAYG;AACH,MAAa,gBAAgB;IACzB,MAAM,CAAU,SAAS,GAAG,GAAG,CAAC;IAEhC,6DAA6D;IAC7D,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,IAAY,EAAE,MAAe;QACvC,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,gBAAgB,CAAC,SAAS,GAAG,MAAM,EAAE,CAAC;IACzF,CAAC;IAED,kGAAkG;IAClG,uGAAuG;IACvG,MAAM,CAAC,MAAM,CAAC,SAAiB;QAC3B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,4FAA4F;IAC5F,uGAAuG;IACvG,MAAM,CAAC,QAAQ,CAAC,SAAiB;QAC7B,MAAM,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACzD,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC;;AArBL,4CAsBC","sourcesContent":["/**\n * The grammar of `ApiEndUserError.errorCode`: `<code>[:<detail>]`.\n *\n * - `<code>` names WHICH mistake it was (`user-not-found`, `terms-not-accepted`). It is what\n *   {@link EndUserErrorRegistry} matches on to rebuild the subclass on the receiving side, so it must\n *   not itself contain a `:`.\n * - `<detail>` is optional DATA the client acts on (the id that was not found, the terms version to\n *   accept), never prose: prose belongs in the message. Everything after the FIRST `:` is the detail,\n *   so a detail may itself contain colons.\n *\n * Kept as one tiny stateless class so a throw site, the registry and an app's own client code all\n * split the string the same way.\n */\nexport class EndUserErrorCode {\n    static readonly SEPARATOR = ':';\n\n    /** `code` alone, or `code:detail` when a detail is given. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static format(code: string, detail?: string): string {\n        return detail === undefined ? code : `${code}${EndUserErrorCode.SEPARATOR}${detail}`;\n    }\n\n    /** The `<code>` part: everything before the first `:`, or the whole string when there is none. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static codeOf(errorCode: string): string {\n        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);\n        return at < 0 ? errorCode : errorCode.slice(0, at);\n    }\n\n    /** The `<detail>` part: everything after the first `:`, or undefined when there is none. */\n    // webpieces-disable no-function-outside-class -- stateless grammar helper shared by browser and server\n    static detailOf(errorCode: string): string | undefined {\n        const at = errorCode.indexOf(EndUserErrorCode.SEPARATOR);\n        return at < 0 ? undefined : errorCode.slice(at + 1);\n    }\n}\n"]}

package/src/errors/EndUserErrorRegistry.d.ts

@@ -0,0 +1,61 @@
+import { ApiEndUserError, EdgeHttpStatus } from './ApiError';
+/**
+ * Rebuilds one registered {@link ApiEndUserError} subclass from what crossed the wire. It receives
+ * the published message and the `<detail>` half of `errorCode` (see {@link EndUserErrorCode}); the
+ * subclass's constructor fixes the `<code>` half itself.
+ */
+export type EndUserErrorFactory = (message: string, detail: string | undefined) => ApiEndUserError;
+/**
+ * errorCode -> {@link ApiEndUserError} SUBCLASS, so the receiving side of a 266 can `instanceof` WHICH
+ * mistake it was (send the person to the Terms page, treat a missing item as "it was deleted")
+ * instead of string-matching `errorCode` at every catch site.
+ *
+ * `ApiErrorCodec` consults it for every decoded `end-user` payload, which is the one decode HTTP
+ * (`WebpiecesDefaultErrorTranslator.fromWire`), IPC and JSONL streams all share, so a registration
+ * covers every protocol at once. Matching is on the `<code>` half of the `<code>[:<detail>]` grammar.
+ * An UNKNOWN code decodes to the base `ApiEndUserError` with `errorCode` and `edgeHttpStatus` intact:
+ * forward compatible, an old client receiving a new code still shows the message.
+ *
+ * REGISTER ONCE AT STARTUP, in EVERY process that may receive the error: the browser bundle, the
+ * Expo shell and every server. A server needs it too, because a server that receives a 266 from a
+ * peer rethrows the decoded error to its own caller, and only a decoded subclass is still that
+ * subclass when the next hop catches it.
+ *
+ * ```ts
+ * export class TermsNotAcceptedError extends ApiEndUserError {
+ *     static readonly CODE = 'terms-not-accepted';
+ *     constructor(message: string, detail?: string, cause?: Error) {
+ *         super(message, EndUserErrorCode.format(TermsNotAcceptedError.CODE, detail), undefined, cause);
+ *     }
+ * }
+ *
+ * // startup, ONCE per process (browser AND server)
+ * EndUserErrorRegistry.register(TermsNotAcceptedError.CODE,
+ *     (message: string, detail: string | undefined) => new TermsNotAcceptedError(message, detail));
+ * ```
+ *
+ * The webpieces generics ({@link ApiEndUserNotFoundError}, {@link ApiEndUserForbiddenError},
+ * {@link ApiEndUserBadRequestError}) are PRE-REGISTERED here, so they decode typed with no setup.
+ * App-specific subclasses stay in the app.
+ *
+ * Process-global and static, like `ClientRegistry` / `HeaderRegistry`: the codec that consults it is
+ * a static, protocol-neutral decoder reached from the browser, node and IPC alike, and a registration
+ * is a fact about the PROCESS's error taxonomy, not about any one client.
+ */
+export declare class EndUserErrorRegistry {
+    private static readonly factories;
+    /**
+     * Register the subclass for `code`. `code` is the bare `<code>` (no `:`), normally the subclass's
+     * static `CODE`. Registering a code twice THROWS: two classes claiming one code is a collision
+     * that would otherwise decode to whichever registered last, depending on startup order.
+     */
+    static register(code: string, factory: EndUserErrorFactory): void;
+    /**
+     * The decoded end-user error for a received payload: the registered subclass for `errorCode`'s
+     * `<code>`, else the base {@link ApiEndUserError} carrying everything the wire sent.
+     */
+    static create(message: string, errorCode?: string, edgeHttpStatus?: EdgeHttpStatus): ApiEndUserError;
+    /** Back to a fresh process: the webpieces built-ins only. For TESTS, so specs cannot leak. */
+    static resetForTests(): void;
+    private static builtIns;
+}