@webpieces/core-util 0.4.963 → 0.4.964

package/package.json

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

package/src/http/ApiCallInfo.d.ts

@@ -44,7 +44,7 @@ import { MaskSpec } from './LogFieldMask';
 export type ApiCallDirection = 'request' | 'response';
 /**
  * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully
- * handled "you made a mistake"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ClientRegistry.classify}.
+ * handled "you made a mistake"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ApiRegistry.classify}.
  */
 export type ApiResult = 'success' | 'failure';
 /** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */
@@ -104,7 +104,7 @@ export declare class ApiCallInfo {
      * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
      * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
      * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
-     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * is the transport-neutral outcome, exactly as {@link ApiRegistry.classify} (a {@link CallOutcome}) classifies by
      * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
      * client's status lives in the optional, nested {@link http} — present only where there IS an
      * HTTP exchange, so nothing transport-neutral ever reads it.
@@ -146,7 +146,7 @@ export declare class ApiCallInfo {
      * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
      * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
      * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
-     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * is the transport-neutral outcome, exactly as {@link ApiRegistry.classify} (a {@link CallOutcome}) classifies by
      * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
      * client's status lives in the optional, nested {@link http} — present only where there IS an
      * HTTP exchange, so nothing transport-neutral ever reads it.

package/src/http/ApiCallInfo.js

@@ -87,7 +87,7 @@ class ApiCallInfo {
      * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the
      * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have
      * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})
-     * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by
+     * is the transport-neutral outcome, exactly as {@link ApiRegistry.classify} (a {@link CallOutcome}) classifies by
      * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP
      * client's status lives in the optional, nested {@link http} — present only where there IS an
      * HTTP exchange, so nothing transport-neutral ever reads it.

package/src/http/ApiCallInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AAwDA;;;;;;;;GAQG;AACH,MAAa,aAAa;IAGT;IAEA;IAEA;IANb;IACI,iCAAiC;IACxB,MAAc;IACvB,sGAAsG;IAC7F,GAAW;IACpB,gDAAgD;IACvC,MAAc;QAJd,WAAM,GAAN,MAAM,CAAQ;QAEd,QAAG,GAAH,GAAG,CAAQ;QAEX,WAAM,GAAN,MAAM,CAAQ;IACxB,CAAC;IAEJ;;;;OAIG;IACH,8FAA8F;IAC9F,MAAM,CAAC,OAAO,CAAC,GAAW,EAAE,IAA0B;QAClD,MAAM,eAAe,GAAG,GAAG,CAAC,OAAO,CAAC,qCAAqC,EAAE,IAAI,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,OAAO,GAAG,CAAC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC;QAC9D,MAAM,KAAK,GAAG,eAAe;aACxB,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;aAClB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,IAAY,EAAE,EAAE;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC;QACzF,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC;IAC3D,CAAC;IAED,8FAA8F;IACtF,MAAM,CAAC,MAAM,CAAC,GAAW;QAC7B,uFAAuF;QACvF,OAAO,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;CACJ;AArCD,sCAqCC;AAED;;;;;GAKG;AACH,MAAa,mBAAmB;IAC5B,KAAK,GAA8B,SAAS,CAAC;CAChD;AAFD,kDAEC;AAED,MAAa,WAAW;IAIP;IACA;IAEA;IAcA;IAUA;IAGA;IAEA;IAOA;IA1Cb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAsB;IAC/B,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;;;OAYG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;IAC9B,4FAA4F;IACnF,aAAsB;IAC/B;;;;;OAKG;IACM,IAAoB;QAvCpB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAkB;QAEtB,WAAM,GAAN,MAAM,CAAY;QAclB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;QAErB,kBAAa,GAAb,aAAa,CAAS;QAOtB,SAAI,GAAJ,IAAI,CAAgB;IAC9B,CAAC;CACP;AA7CD,kCA6CC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\nimport { MaskSpec } from './LogFieldMask';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api.responseCount>100`         — responses containing many logical items\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n * - `jsonPayload.api.http.status=404`            — an HTTP client call the vendor answered 404 (#1339)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\n/**\n * Which HALF of one api call a log line describes.\n *\n * Renamed from `ApiType`, which collided with the `@ApiType(...)` CONTRACT decorator and read as if\n * it were about the kind of API rather than the direction of one line. Per\n * `.claude/rules/no-backwards-compat.md` the old spelling is deleted rather than aliased, so a caller\n * on the old name stops compiling and the error names this one.\n */\nexport type ApiCallDirection = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ClientRegistry.classify}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\n/**\n * The HTTP facts of ONE client call's last transmission — surfaces as `jsonPayload.api.http.*`.\n * Filled ONLY by the HTTP client (node and browser), which is the one layer that has a verb, a url\n * and a status; in-process, pubsub and cloud-task calls leave {@link ApiCallInfo.http} unset. It\n * exists because a vendor's 404 and its 500 were indistinguishable in the logs when only the DTOs\n * were recorded.\n *\n * Never headers or tokens: the url is MASKED ({@link maskUrl}) before it gets here.\n */\nexport class HttpCallFacts {\n    constructor(\n        /** The HTTP verb, e.g. `GET`. */\n        readonly method: string,\n        /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */\n        readonly url: string,\n        /** The status of the last response received. */\n        readonly status: number,\n    ) {}\n\n    /**\n     * The url as it may be logged: any `user:password@` userinfo is dropped, and the value of every\n     * query key the endpoint's `@MaskLog` names is replaced with `*****` (a `?token=` the DTO mask\n     * already hides must not reappear in the url).\n     */\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    static maskUrl(url: string, mask: MaskSpec | undefined): string {\n        const withoutUserInfo = url.replace(/^([a-z][a-z0-9+.-]*:\\/\\/)[^/@?#]*@/i, '$1');\n        const queryAt = withoutUserInfo.indexOf('?');\n        if (queryAt < 0 || mask === undefined) return withoutUserInfo;\n        const query = withoutUserInfo\n            .slice(queryAt + 1)\n            .split('&')\n            .map((pair: string) => {\n                const equals = pair.indexOf('=');\n                const key = equals < 0 ? pair : pair.slice(0, equals);\n                return mask.modeFor(HttpCallFacts.decode(key)) === undefined ? pair : `${key}=*****`;\n            })\n            .join('&');\n        return `${withoutUserInfo.slice(0, queryAt)}?${query}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    private static decode(key: string): string {\n        // A malformed escape is logged as written; it can never be a masked field name anyway.\n        return /%(?![0-9a-f]{2})/i.test(key) ? key : decodeURIComponent(key);\n    }\n}\n\n/**\n * The per-call slot the HTTP client fills with {@link HttpCallFacts} as each response arrives, and\n * {@link LogApiCallImpl} reads when it stamps the response tag. A holder rather than a return value\n * because the facts are known DEEP in the transport while the tag is written at the top of the call;\n * the last transmission (after redirects, a 401 refresh or a retry) wins.\n */\nexport class HttpCallFactsHolder {\n    facts: HttpCallFacts | undefined = undefined;\n}\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiCallDirection,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the\n         * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have\n         * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})\n         * is the transport-neutral outcome, exactly as {@link ClientRegistry.classify} (a {@link CallOutcome}) classifies by\n         * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP\n         * client's status lives in the optional, nested {@link http} — present only where there IS an\n         * HTTP exchange, so nothing transport-neutral ever reads it.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n        /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */\n        readonly responseCount?: number,\n        /**\n         * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.\n         * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so\n         * `api.result=\"failure\" AND api.http.status=429` finds a vendor throttling us). Unset for\n         * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.\n         */\n        readonly http?: HttpCallFacts,\n    ) {}\n}\n"]}
+{"version":3,"file":"ApiCallInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiCallInfo.ts"],"names":[],"mappings":";;;AAwDA;;;;;;;;GAQG;AACH,MAAa,aAAa;IAGT;IAEA;IAEA;IANb;IACI,iCAAiC;IACxB,MAAc;IACvB,sGAAsG;IAC7F,GAAW;IACpB,gDAAgD;IACvC,MAAc;QAJd,WAAM,GAAN,MAAM,CAAQ;QAEd,QAAG,GAAH,GAAG,CAAQ;QAEX,WAAM,GAAN,MAAM,CAAQ;IACxB,CAAC;IAEJ;;;;OAIG;IACH,8FAA8F;IAC9F,MAAM,CAAC,OAAO,CAAC,GAAW,EAAE,IAA0B;QAClD,MAAM,eAAe,GAAG,GAAG,CAAC,OAAO,CAAC,qCAAqC,EAAE,IAAI,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,OAAO,GAAG,CAAC,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,eAAe,CAAC;QAC9D,MAAM,KAAK,GAAG,eAAe;aACxB,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;aAClB,KAAK,CAAC,GAAG,CAAC;aACV,GAAG,CAAC,CAAC,IAAY,EAAE,EAAE;YAClB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YACtD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,QAAQ,CAAC;QACzF,CAAC,CAAC;aACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC;IAC3D,CAAC;IAED,8FAA8F;IACtF,MAAM,CAAC,MAAM,CAAC,GAAW;QAC7B,uFAAuF;QACvF,OAAO,mBAAmB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACzE,CAAC;CACJ;AArCD,sCAqCC;AAED;;;;;GAKG;AACH,MAAa,mBAAmB;IAC5B,KAAK,GAA8B,SAAS,CAAC;CAChD;AAFD,kDAEC;AAED,MAAa,WAAW;IAIP;IACA;IAEA;IAcA;IAUA;IAGA;IAEA;IAOA;IA1Cb;IACI;oCACgC;IACvB,MAAqB,EACrB,IAAsB;IAC/B,sDAAsD;IAC7C,MAAkB;IAC3B;;;;;;;;;;;;OAYG;IACM,UAAmB;IAC5B;;;;;;;;OAQG;IACM,WAAoB;IAC7B;yFACqF;IAC5E,YAAqB;IAC9B,4FAA4F;IACnF,aAAsB;IAC/B;;;;;OAKG;IACM,IAAoB;QAvCpB,WAAM,GAAN,MAAM,CAAe;QACrB,SAAI,GAAJ,IAAI,CAAkB;QAEtB,WAAM,GAAN,MAAM,CAAY;QAclB,eAAU,GAAV,UAAU,CAAS;QAUnB,gBAAW,GAAX,WAAW,CAAS;QAGpB,iBAAY,GAAZ,YAAY,CAAS;QAErB,kBAAa,GAAb,aAAa,CAAS;QAOtB,SAAI,GAAJ,IAAI,CAAgB;IAC9B,CAAC;CACP;AA7CD,kCA6CC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\nimport { MaskSpec } from './LogFieldMask';\n\n/**\n * ApiCallInfo - the structured tag stamped into RequestContext around every API call\n * (by {@link LogApiCallImpl}), so ANY log line emitted during the call inherits a filterable\n * `api` object rather than only the req/resp text lines.\n *\n * The node logging backends (winston/bunyan) read this struct out of context via\n * `RequestContext.buildStructuredLogFields()` and emit it AS AN OBJECT under `jsonPayload.api`,\n * which unlocks GCP Cloud Logging filters like:\n * - `jsonPayload.api.method.side=\"client\"`     — every outbound call this process made\n * - `jsonPayload.api.method.side=\"server\"`      — every inbound call it handled\n * - `jsonPayload.api.method.apiClass=\"SaveApi\"` — one logical method, BOTH sides (client + server)\n * - `jsonPayload.api.result=\"failure\"`          — failed exchanges only\n * - `jsonPayload.api.durationMs>1000`           — slow calls, either side\n * - `jsonPayload.api.responseSize>100000`       — the fat responses (the ones that get chunked)\n * - `jsonPayload.api.responseCount>100`         — responses containing many logical items\n * - `jsonPayload.api:*`                          — \"API traffic only\" (tracing + the recorder)\n * - `jsonPayload.api.http.status=404`            — an HTTP client call the vendor answered 404 (#1339)\n *\n * IMPORTANT: the field names here (and on the nested {@link ApiMethodInfo}) ARE the GCP field names —\n * rename a field and the filter renames with it. The identity lives NESTED under `api.method`\n * (`api.method.{side,apiClass,methodName,controllerName}`); `api.type` and `api.result` sit at the top.\n *\n * NOTE: the request `httpMethod`/`path` are NOT here — an inbound request stamps them as the separate\n * top-level logged keys `jsonPayload.httpMethod` / `jsonPayload.requestPath` (see\n * {@link WebpiecesCoreHeaders} + `RequestContextHeaders.fillFromRequest`). Outbound client calls have\n * no inbound path, so they carry only the `api` identity.\n *\n * Per-hop only: the underlying `API_CALL_INFO` ContextKey is NOT transferred over the wire, so a\n * downstream server stamps its own `side:'server'` rather than inheriting the caller's `side:'client'`.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\n/** Which half of the exchange this tag describes: the outgoing 'request' or the returning 'response'. */\n/**\n * Which HALF of one api call a log line describes.\n *\n * Renamed from `ApiType`, which collided with the `@ApiType(...)` CONTRACT decorator and read as if\n * it were about the kind of API rather than the direction of one line. Per\n * `.claude/rules/no-backwards-compat.md` the old spelling is deleted rather than aliased, so a caller\n * on the old name stops compiling and the error names this one.\n */\nexport type ApiCallDirection = 'request' | 'response';\n\n/**\n * Response outcome. 'success' covers 2xx AND user errors (400/401/403/404/266 — a successfully\n * handled \"you made a mistake\"); 'failure' is a genuine server error. `success` = {@link CallOutcome.EXPECTED} from {@link ApiRegistry.classify}.\n */\nexport type ApiResult = 'success' | 'failure';\n\n/** Re-exported from {@link ApiMethodInfo} (its true home) so existing `ApiSide` imports keep working. */\nexport type { ApiSide } from './ApiMethodInfo';\n\n/**\n * The HTTP facts of ONE client call's last transmission — surfaces as `jsonPayload.api.http.*`.\n * Filled ONLY by the HTTP client (node and browser), which is the one layer that has a verb, a url\n * and a status; in-process, pubsub and cloud-task calls leave {@link ApiCallInfo.http} unset. It\n * exists because a vendor's 404 and its 500 were indistinguishable in the logs when only the DTOs\n * were recorded.\n *\n * Never headers or tokens: the url is MASKED ({@link maskUrl}) before it gets here.\n */\nexport class HttpCallFacts {\n    constructor(\n        /** The HTTP verb, e.g. `GET`. */\n        readonly method: string,\n        /** The final absolute url, masked: no userinfo, and `@MaskLog` field names' query values redacted. */\n        readonly url: string,\n        /** The status of the last response received. */\n        readonly status: number,\n    ) {}\n\n    /**\n     * The url as it may be logged: any `user:password@` userinfo is dropped, and the value of every\n     * query key the endpoint's `@MaskLog` names is replaced with `*****` (a `?token=` the DTO mask\n     * already hides must not reappear in the url).\n     */\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    static maskUrl(url: string, mask: MaskSpec | undefined): string {\n        const withoutUserInfo = url.replace(/^([a-z][a-z0-9+.-]*:\\/\\/)[^/@?#]*@/i, '$1');\n        const queryAt = withoutUserInfo.indexOf('?');\n        if (queryAt < 0 || mask === undefined) return withoutUserInfo;\n        const query = withoutUserInfo\n            .slice(queryAt + 1)\n            .split('&')\n            .map((pair: string) => {\n                const equals = pair.indexOf('=');\n                const key = equals < 0 ? pair : pair.slice(0, equals);\n                return mask.modeFor(HttpCallFacts.decode(key)) === undefined ? pair : `${key}=*****`;\n            })\n            .join('&');\n        return `${withoutUserInfo.slice(0, queryAt)}?${query}`;\n    }\n\n    // webpieces-disable no-function-outside-class -- pure static helper beside the data it builds\n    private static decode(key: string): string {\n        // A malformed escape is logged as written; it can never be a masked field name anyway.\n        return /%(?![0-9a-f]{2})/i.test(key) ? key : decodeURIComponent(key);\n    }\n}\n\n/**\n * The per-call slot the HTTP client fills with {@link HttpCallFacts} as each response arrives, and\n * {@link LogApiCallImpl} reads when it stamps the response tag. A holder rather than a return value\n * because the facts are known DEEP in the transport while the tag is written at the top of the call;\n * the last transmission (after redirects, a 401 refresh or a retry) wins.\n */\nexport class HttpCallFactsHolder {\n    facts: HttpCallFacts | undefined = undefined;\n}\n\nexport class ApiCallInfo {\n    constructor(\n        /** The call identity (side, apiClass, methodName, controllerName) — surfaces nested under\n         *  `jsonPayload.api.method`. */\n        readonly method: ApiMethodInfo,\n        readonly type: ApiCallDirection,\n        /** Response only — undefined on the 'request' tag. */\n        readonly result?: ApiResult,\n        /**\n         * Wall-clock milliseconds the call took. RESPONSE tag only (undefined on 'request') — a\n         * request has no duration yet. Present on BOTH the success and failure paths, so\n         * `jsonPayload.api.durationMs>1000 AND api.result=\"failure\"` finds slow failures.\n         *\n         * There is deliberately no top-level `statusCode` beside this. LogApiCall runs deep in the\n         * stack over in-process calls, pubsub handlers, and cloud-task enqueues — none of which have\n         * an HTTP status — and business logic must not know about HTTP. `result` (see {@link ApiResult})\n         * is the transport-neutral outcome, exactly as {@link ApiRegistry.classify} (a {@link CallOutcome}) classifies by\n         * portable Error TYPE rather than by status code. That decision STANDS (#1339): the HTTP\n         * client's status lives in the optional, nested {@link http} — present only where there IS an\n         * HTTP exchange, so nothing transport-neutral ever reads it.\n         */\n        readonly durationMs?: number,\n        /**\n         * Bytes of the serialized request DTO. Stamped on BOTH tags: the 'request' tag reports it as\n         * soon as it is known, and the 'response' tag repeats it so one record shows the whole\n         * exchange (`api.requestSize` + `api.responseSize` without a join).\n         *\n         * This is the TOTAL size of the body, measured BEFORE any log chunking — chunking is a\n         * transport concern handled by the GCP backends, and a body split across 3 records still\n         * reports its one true size here.\n         */\n        readonly requestSize?: number,\n        /** Bytes of the serialized response. RESPONSE tag only, and only when the call succeeded —\n         *  a thrown error produced no response body to measure. Total size, pre-chunking. */\n        readonly responseSize?: number,\n        /** Number of logical items in a successful response. RESPONSE tag only, opt-in per call. */\n        readonly responseCount?: number,\n        /**\n         * The HTTP verb, masked url and status of the call's last transmission — `jsonPayload.api.http.*`.\n         * RESPONSE tag only, and only for a call made by the HTTP client (success AND failure, so\n         * `api.result=\"failure\" AND api.http.status=429` finds a vendor throttling us). Unset for\n         * in-process, pubsub and cloud-task calls. See {@link HttpCallFacts}.\n         */\n        readonly http?: HttpCallFacts,\n    ) {}\n}\n"]}

package/src/http/ApiMethodInfo.d.ts

@@ -50,7 +50,7 @@ export declare class ApiMethodInfo {
     readonly allowUpgradeInFlight: boolean;
     /**
      * The contract CLASS (the `@ApiPath` contract, or an SDK-wrapping api-client's abstract
-     * `XxxApi`) — the key {@link ClientRegistry.classify} resolves the `CallScope` ladder on
+     * `XxxApi`) — the key {@link ApiRegistry.classify} resolves the `CallScope` ladder on
      * (method -> API -> ALL). {@link apiClass} stays the LOGGED name. REQUIRED as a constructor
      * argument so every caller states it, and never `undefined`: an SDK-wrapping client passes its
      * abstract `XxxApi`, an IPC hop its `@WpInternal` class, and an MCP protocol step (which has no

package/src/http/ApiMethodInfo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAgBT;IAGA;IAEA;IAKA;IAMA;IAKA;IAIA;IAIA;IA9Bb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B,yEAAyE;IACzE,QAAkB;IAClB;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;IACxB;;;sGAGkG;IACzF,YAAqB,KAAK;IACnC;;+BAE2B;IAClB,eAAwB,KAAK;IACtC;;qCAEiC;IACxB,uBAAgC,KAAK;QA7BrC,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAKlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;QAKf,cAAS,GAAT,SAAS,CAAiB;QAI1B,iBAAY,GAAZ,YAAY,CAAiB;QAI7B,yBAAoB,GAApB,oBAAoB,CAAiB;QAE9C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;CACJ;AAjDD,sCAiDC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    /**\n     * The contract CLASS (the `@ApiPath` contract, or an SDK-wrapping api-client's abstract\n     * `XxxApi`) — the key {@link ClientRegistry.classify} resolves the `CallScope` ladder on\n     * (method -> API -> ALL). {@link apiClass} stays the LOGGED name. REQUIRED as a constructor\n     * argument so every caller states it, and never `undefined`: an SDK-wrapping client passes its\n     * abstract `XxxApi`, an IPC hop its `@WpInternal` class, and an MCP protocol step (which has no\n     * user contract) the framework-owned `McpProtocol` class — which reaches the ALL rung unless\n     * somebody registers for that class.\n     *\n     * NON-enumerable on purpose: this object is nested into every `[API-*]` log record as\n     * `jsonPayload.api.method`, and a class reference is not log data.\n     */\n    declare readonly contract: Function;\n\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** REQUIRED — the contract CLASS; see {@link ApiMethodInfo.contract}. */\n        contract: Function,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n        /** OPTIONAL — true when the route declared `@Endpoint(..., { noLogging: true })` (a log\n         *  shipper, a log-ingest endpoint): {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]`\n         *  line and stamps no {@link ApiCallInfo} tag for it. Read once at route-build time and handed\n         *  here, exactly as {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */\n        readonly noLogging: boolean = false,\n        /** OPTIONAL — `@Endpoint(..., { hideProgress: true })`, carried from the route so the whole\n         *  call identity travels together. webpieces itself does not act on it; an app's progress UI\n         *  does. Default false. */\n        readonly hideProgress: boolean = false,\n        /** OPTIONAL — `@Endpoint(..., { allowUpgradeInFlight: true })`, carried from the route so the\n         *  whole call identity travels together. webpieces itself does not act on it; an app's upgrade\n         *  logic does. Default false. */\n        readonly allowUpgradeInFlight: boolean = false,\n    ) {\n        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });\n    }\n}\n"]}
+{"version":3,"file":"ApiMethodInfo.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiMethodInfo.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAOH,MAAa,aAAa;IAgBT;IAGA;IAEA;IAKA;IAMA;IAKA;IAIA;IAIA;IA9Bb,YACa,IAAa;IACtB;2FACuF;IAC9E,QAAgB;IACzB,2DAA2D;IAClD,UAAkB;IAC3B,yEAAyE;IACzE,QAAkB;IAClB;gGAC4F;IACnF,cAAuB;IAChC;;;;wGAIoG;IAC3F,IAAe;IACxB;;;sGAGkG;IACzF,YAAqB,KAAK;IACnC;;+BAE2B;IAClB,eAAwB,KAAK;IACtC;;qCAEiC;IACxB,uBAAgC,KAAK;QA7BrC,SAAI,GAAJ,IAAI,CAAS;QAGb,aAAQ,GAAR,QAAQ,CAAQ;QAEhB,eAAU,GAAV,UAAU,CAAQ;QAKlB,mBAAc,GAAd,cAAc,CAAS;QAMvB,SAAI,GAAJ,IAAI,CAAW;QAKf,cAAS,GAAT,SAAS,CAAiB;QAI1B,iBAAY,GAAZ,YAAY,CAAiB;QAI7B,yBAAoB,GAApB,oBAAoB,CAAiB;QAE9C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;CACJ;AAjDD,sCAiDC","sourcesContent":["/**\n * ApiMethodInfo - the transport-neutral identity of a single API method call, handed to\n * {@link LogApiCallImpl.execute} by every caller (server inbound, http/in-process clients, cloud tasks,\n * and external wrapped clients like the firestore admin client).\n *\n * WHY generic (not RouteMetadata): LogApiCall runs deep in the stack over MANY shapes — HTTP routes,\n * pubsub/queue enqueues, and multi-param external clients returning Promise<void>/Promise<unknown>.\n * None of those own an `httpMethod`/`path`, so LogApiCall must not depend on the HTTP-shaped\n * `RouteMetadata`. This carries only what identifies the call.\n *\n * MATCHING is the point of {@link apiClass}: a CLIENT call and the SERVER handler for the same logical\n * method must log the SAME identity so `jsonPayload.api.method.apiClass=\"SaveApi\"` filters both sides\n * together. The API CONTRACT class name (e.g. 'SaveApi') is available on both sides — the client only\n * ever knows it, and the server carries it alongside its impl name — so it, not the server's impl\n * class, is the required key.\n *\n * Per CLAUDE.md: data-only structures are classes, not interfaces.\n */\n\nimport {MaskSpec} from \"./LogFieldMask\";\n\n/** Which end of the exchange this process is: the caller ('client') or the handler ('server'). */\nexport type ApiSide = 'client' | 'server';\n\nexport class ApiMethodInfo {\n    /**\n     * The contract CLASS (the `@ApiPath` contract, or an SDK-wrapping api-client's abstract\n     * `XxxApi`) — the key {@link ApiRegistry.classify} resolves the `CallScope` ladder on\n     * (method -> API -> ALL). {@link apiClass} stays the LOGGED name. REQUIRED as a constructor\n     * argument so every caller states it, and never `undefined`: an SDK-wrapping client passes its\n     * abstract `XxxApi`, an IPC hop its `@WpInternal` class, and an MCP protocol step (which has no\n     * user contract) the framework-owned `McpProtocol` class — which reaches the ALL rung unless\n     * somebody registers for that class.\n     *\n     * NON-enumerable on purpose: this object is nested into every `[API-*]` log record as\n     * `jsonPayload.api.method`, and a class reference is not log data.\n     */\n    declare readonly contract: Function;\n\n    constructor(\n        readonly side: ApiSide,\n        /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both\n         *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */\n        readonly apiClass: string,\n        /** REQUIRED — the method on the contract (e.g. 'save'). */\n        readonly methodName: string,\n        /** REQUIRED — the contract CLASS; see {@link ApiMethodInfo.contract}. */\n        contract: Function,\n        /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no\n         *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */\n        readonly controllerName?: string,\n        /** OPTIONAL — which DTO fields to mask in the log lines, and how. Absent = log the DTO\n         *  verbatim exactly as before (the fast path, no per-field walk). Present = {@link LogApiCallImpl}\n         *  runs {@link maskedStringify} so a declared-sensitive field (an OAuth refresh token, an\n         *  id-token JWT) is masked in the log while the REAL value still travels on the wire untouched.\n         *  Rides the call identity so the spec travels with the api definition, not a global app config. */\n        readonly mask?: MaskSpec,\n        /** OPTIONAL — true when the route declared `@Endpoint(..., { noLogging: true })` (a log\n         *  shipper, a log-ingest endpoint): {@link LogApiCallImpl} emits NO `[API-*-req]`/`[API-*-resp-*]`\n         *  line and stamps no {@link ApiCallInfo} tag for it. Read once at route-build time and handed\n         *  here, exactly as {@link mask} is. Default (absent/false) = the ordinary, fully-logged call. */\n        readonly noLogging: boolean = false,\n        /** OPTIONAL — `@Endpoint(..., { hideProgress: true })`, carried from the route so the whole\n         *  call identity travels together. webpieces itself does not act on it; an app's progress UI\n         *  does. Default false. */\n        readonly hideProgress: boolean = false,\n        /** OPTIONAL — `@Endpoint(..., { allowUpgradeInFlight: true })`, carried from the route so the\n         *  whole call identity travels together. webpieces itself does not act on it; an app's upgrade\n         *  logic does. Default false. */\n        readonly allowUpgradeInFlight: boolean = false,\n    ) {\n        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });\n    }\n}\n"]}

package/src/http/ApiRegistry.d.ts

@@ -0,0 +1,91 @@
+import { ErrorTranslator } from './ErrorTranslator';
+import { CallOutcome, ErrorClassifier } from './ErrorClassifier';
+import { CallScope } from './CallScope';
+import { ApiMethodInfo } from './ApiMethodInfo';
+/**
+ * ApiRegistry - the startup settings BOTH sides of an API call read: the {@link ErrorTranslator}
+ * (the server's `toWire`, every client's `fromWire`, IPC and MCP) and the {@link ErrorClassifier}
+ * (the server's `LogApiFilter`, `LogApiCall`, `RetryStrategy`, the MCP renderer, Cloud Tasks). What
+ * only an OUTBOUND call reads — URLs, timeouts, strategies — lives on `ClientRegistry` instead.
+ *
+ * Every setting is scoped by a {@link CallScope} and resolved method -> API -> ALL -> the webpieces
+ * default. Process-global, populated once at startup on the SERVER and in the BROWSER, with no DI
+ * wiring (like `HeaderRegistry` / `LogManager`).
+ *
+ * ```ts
+ * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());
+ * ApiRegistry.setErrorTranslator(new VendorErrorTranslator(), CallScope.api(VendorApi));
+ * ApiRegistry.setErrorClassifier(new CompanyClassifier(), CallScope.all());
+ * ```
+ */
+export declare class ApiRegistry {
+    /**
+     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ApiRegistry.getErrorTranslator} is never
+     * undefined.
+     *
+     * ONE translator per scope, not a list, on purpose: an app that has several layers of error
+     * policy for one scope composes them INSIDE its own `toWire`, where the precedence is written
+     * down. The ladder exists because vendors put their errors on the wire in their OWN formats — a
+     * per-API translator reads one vendor's 4xx body (`fromWire`), or writes the error body an
+     * inbound vendor expects back (`toWire`), while every other contract keeps the app's ALL one.
+     */
+    private static readonly errorTranslators;
+    /**
+     * The {@link ErrorClassifier} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}. A classifier that DEFERS (`undefined`) falls through
+     * to the next rung. The ALL classifier reads {@link ApiMethodInfo.side}, so one classifier covers
+     * the server router AND every internal client; an SDK-wrapping api-client registers its own at
+     * its abstract `XxxApi` class. See {@link ApiRegistry.classify}.
+     */
+    private static readonly errorClassifiers;
+    /**
+     * Install an {@link ErrorTranslator} for one {@link CallScope}: `CallScope.all()` (the app's
+     * translator, server side AND every client side), one contract (`CallScope.api(VendorApi)`), or
+     * one method of one contract (`CallScope.method(VendorApi, 'sync')`). The scope is REQUIRED —
+     * there is no unscoped spelling. Call at startup, on the server AND in the browser.
+     *
+     * `set`, not `add`: see the field doc above for why a per-scope LIST is not wanted. A translator
+     * declines an error by DELEGATING to {@link WebpiecesDefaultErrorTranslator} — not to the next
+     * rung.
+     */
+    static setErrorTranslator(translator: ErrorTranslator, scope: CallScope): void;
+    /**
+     * THE {@link ErrorTranslator} for one call — method -> API -> ALL ->
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, never `undefined`, so a caller never branches.
+     *
+     * Both arguments are required so every call site states what it knows: the client and the server
+     * pass the route's contract class and method; a failure with no route (an unmatched request, a
+     * failure before routing) passes `undefined, undefined` and reaches the ALL rung alone.
+     */
+    static getErrorTranslator(api: Function | undefined, methodName: string | undefined): ErrorTranslator;
+    /**
+     * Install an {@link ErrorClassifier} for one {@link CallScope}: `CallScope.all()` (the
+     * app/company classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router
+     * and every internal client), one contract (an SDK-wrapping api-client keys by its abstract
+     * `XxxApi`), or one method of one contract. The scope is REQUIRED. Call at startup, on the server
+     * AND in the browser. See {@link ErrorClassifier}.
+     */
+    static setErrorClassifier(classifier: ErrorClassifier, scope: CallScope): void;
+    /**
+     * The {@link CallOutcome} of a thrown API-call error. Resolved on the {@link CallScope} ladder of
+     * `methodInfo.contract` / `methodInfo.methodName`, most specific first, and ALWAYS definitive:
+     *   1. the method classifier — unless it defers;
+     *   2. else the API classifier — unless it defers;
+     *   3. else the ALL classifier — unless it defers;
+     *   4. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     *
+     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `ClientRegistry`'s per-attempt
+     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.
+     */
+    static classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome;
+    /**
+     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
+     * cannot leak its registrations into the next.
+     *
+     * It empties every translator and classifier rung, which RESTORES the webpieces defaults:
+     * `getErrorTranslator(...)` and `classify(...)` fall through to them below every rung, so
+     * "cleared" is not a state they have.
+     */
+    static resetForTests(): void;
+}

package/src/http/ApiRegistry.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiRegistry = void 0;
+const CallScope_1 = require("./CallScope");
+const WebpiecesDefaultErrorClassifier_1 = require("./WebpiecesDefaultErrorClassifier");
+const WebpiecesDefaultErrorTranslator_1 = require("./WebpiecesDefaultErrorTranslator");
+/** One {@link CallScope} rung of the error-translator ladder. Data only, so a class. */
+class TranslatorSlot {
+    translator;
+}
+/** One {@link CallScope} rung of the error-classifier ladder. Data only, so a class. */
+class ClassifierSlot {
+    classifier;
+}
+/**
+ * ApiRegistry - the startup settings BOTH sides of an API call read: the {@link ErrorTranslator}
+ * (the server's `toWire`, every client's `fromWire`, IPC and MCP) and the {@link ErrorClassifier}
+ * (the server's `LogApiFilter`, `LogApiCall`, `RetryStrategy`, the MCP renderer, Cloud Tasks). What
+ * only an OUTBOUND call reads — URLs, timeouts, strategies — lives on `ClientRegistry` instead.
+ *
+ * Every setting is scoped by a {@link CallScope} and resolved method -> API -> ALL -> the webpieces
+ * default. Process-global, populated once at startup on the SERVER and in the BROWSER, with no DI
+ * wiring (like `HeaderRegistry` / `LogManager`).
+ *
+ * ```ts
+ * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());
+ * ApiRegistry.setErrorTranslator(new VendorErrorTranslator(), CallScope.api(VendorApi));
+ * ApiRegistry.setErrorClassifier(new CompanyClassifier(), CallScope.all());
+ * ```
+ */
+class ApiRegistry {
+    /**
+     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ApiRegistry.getErrorTranslator} is never
+     * undefined.
+     *
+     * ONE translator per scope, not a list, on purpose: an app that has several layers of error
+     * policy for one scope composes them INSIDE its own `toWire`, where the precedence is written
+     * down. The ladder exists because vendors put their errors on the wire in their OWN formats — a
+     * per-API translator reads one vendor's 4xx body (`fromWire`), or writes the error body an
+     * inbound vendor expects back (`toWire`), while every other contract keeps the app's ALL one.
+     */
+    static errorTranslators = new CallScope_1.CallScopeLadder(() => new TranslatorSlot());
+    /**
+     * The {@link ErrorClassifier} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}. A classifier that DEFERS (`undefined`) falls through
+     * to the next rung. The ALL classifier reads {@link ApiMethodInfo.side}, so one classifier covers
+     * the server router AND every internal client; an SDK-wrapping api-client registers its own at
+     * its abstract `XxxApi` class. See {@link ApiRegistry.classify}.
+     */
+    static errorClassifiers = new CallScope_1.CallScopeLadder(() => new ClassifierSlot());
+    /**
+     * Install an {@link ErrorTranslator} for one {@link CallScope}: `CallScope.all()` (the app's
+     * translator, server side AND every client side), one contract (`CallScope.api(VendorApi)`), or
+     * one method of one contract (`CallScope.method(VendorApi, 'sync')`). The scope is REQUIRED —
+     * there is no unscoped spelling. Call at startup, on the server AND in the browser.
+     *
+     * `set`, not `add`: see the field doc above for why a per-scope LIST is not wanted. A translator
+     * declines an error by DELEGATING to {@link WebpiecesDefaultErrorTranslator} — not to the next
+     * rung.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static setErrorTranslator(translator, scope) {
+        ApiRegistry.errorTranslators.at(scope).translator = translator;
+    }
+    /**
+     * THE {@link ErrorTranslator} for one call — method -> API -> ALL ->
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, never `undefined`, so a caller never branches.
+     *
+     * Both arguments are required so every call site states what it knows: the client and the server
+     * pass the route's contract class and method; a failure with no route (an unmatched request, a
+     * failure before routing) passes `undefined, undefined` and reaches the ALL rung alone.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static getErrorTranslator(api, methodName) {
+        const registered = ApiRegistry.errorTranslators
+            .rungs(api, methodName)
+            .find((slot) => slot.translator !== undefined)?.translator;
+        return registered ?? WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
+    }
+    /**
+     * Install an {@link ErrorClassifier} for one {@link CallScope}: `CallScope.all()` (the
+     * app/company classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router
+     * and every internal client), one contract (an SDK-wrapping api-client keys by its abstract
+     * `XxxApi`), or one method of one contract. The scope is REQUIRED. Call at startup, on the server
+     * AND in the browser. See {@link ErrorClassifier}.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static setErrorClassifier(classifier, scope) {
+        ApiRegistry.errorClassifiers.at(scope).classifier = classifier;
+    }
+    /**
+     * The {@link CallOutcome} of a thrown API-call error. Resolved on the {@link CallScope} ladder of
+     * `methodInfo.contract` / `methodInfo.methodName`, most specific first, and ALWAYS definitive:
+     *   1. the method classifier — unless it defers;
+     *   2. else the API classifier — unless it defers;
+     *   3. else the ALL classifier — unless it defers;
+     *   4. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     *
+     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `ClientRegistry`'s per-attempt
+     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static classify(error, methodInfo) {
+        const rungs = ApiRegistry.errorClassifiers.rungs(methodInfo.contract, methodInfo.methodName);
+        for (const slot of rungs) {
+            const verdict = slot.classifier?.classify(error, methodInfo);
+            if (verdict !== undefined) {
+                return verdict;
+            }
+        }
+        return WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER.classify(error, methodInfo);
+    }
+    /**
+     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec
+     * cannot leak its registrations into the next.
+     *
+     * It empties every translator and classifier rung, which RESTORES the webpieces defaults:
+     * `getErrorTranslator(...)` and `classify(...)` fall through to them below every rung, so
+     * "cleared" is not a state they have.
+     */
+    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
+    static resetForTests() {
+        ApiRegistry.errorTranslators.clear();
+        ApiRegistry.errorClassifiers.clear();
+    }
+}
+exports.ApiRegistry = ApiRegistry;
+//# sourceMappingURL=ApiRegistry.js.map

package/src/http/ApiRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ApiRegistry.ts"],"names":[],"mappings":";;;AAEA,2CAAyD;AACzD,uFAAuF;AACvF,uFAAuF;AAGvF,wFAAwF;AACxF,MAAM,cAAc;IAChB,UAAU,CAAmB;CAChC;AAED,wFAAwF;AACxF,MAAM,cAAc;IAChB,UAAU,CAAmB;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAa,WAAW;IACpB;;;;;;;;;;OAUG;IACK,MAAM,CAAU,gBAAgB,GAAG,IAAI,2BAAe,CAC1D,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE,CAC7B,CAAC;IAEF;;;;;;OAMG;IACK,MAAM,CAAU,gBAAgB,GAAG,IAAI,2BAAe,CAC1D,GAAG,EAAE,CAAC,IAAI,cAAc,EAAE,CAC7B,CAAC;IAEF;;;;;;;;;OASG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB,CAAC,UAA2B,EAAE,KAAgB;QACnE,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,UAAU,CAAC;IACnE,CAAC;IAED;;;;;;;OAOG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB,CAAC,GAAyB,EAAE,UAA8B;QAC/E,MAAM,UAAU,GAAG,WAAW,CAAC,gBAAgB;aAC1C,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC;aACtB,IAAI,CAAC,CAAC,IAAoB,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,EAAE,UAAU,CAAC;QAC/E,OAAO,UAAU,IAAI,oEAAkC,CAAC;IAC5D,CAAC;IAED;;;;;;OAMG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB,CAAC,UAA2B,EAAE,KAAgB;QACnE,WAAW,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,UAAU,CAAC;IACnE,CAAC;IAED;;;;;;;;;;OAUG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,QAAQ,CAAC,KAAY,EAAE,UAAyB;QACnD,MAAM,KAAK,GAAG,WAAW,CAAC,gBAAgB,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;QAC7F,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YAC7D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,OAAO,CAAC;YACnB,CAAC;QACL,CAAC;QACD,OAAO,oEAAkC,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;OAOG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,aAAa;QAChB,WAAW,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;QACrC,WAAW,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC;IACzC,CAAC;;AAzGL,kCA0GC","sourcesContent":["import { ErrorTranslator } from './ErrorTranslator';\nimport { CallOutcome, ErrorClassifier } from './ErrorClassifier';\nimport { CallScope, CallScopeLadder } from './CallScope';\nimport { WEBPIECES_DEFAULT_ERROR_CLASSIFIER } from './WebpiecesDefaultErrorClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\n\n/** One {@link CallScope} rung of the error-translator ladder. Data only, so a class. */\nclass TranslatorSlot {\n    translator?: ErrorTranslator;\n}\n\n/** One {@link CallScope} rung of the error-classifier ladder. Data only, so a class. */\nclass ClassifierSlot {\n    classifier?: ErrorClassifier;\n}\n\n/**\n * ApiRegistry - the startup settings BOTH sides of an API call read: the {@link ErrorTranslator}\n * (the server's `toWire`, every client's `fromWire`, IPC and MCP) and the {@link ErrorClassifier}\n * (the server's `LogApiFilter`, `LogApiCall`, `RetryStrategy`, the MCP renderer, Cloud Tasks). What\n * only an OUTBOUND call reads — URLs, timeouts, strategies — lives on `ClientRegistry` instead.\n *\n * Every setting is scoped by a {@link CallScope} and resolved method -> API -> ALL -> the webpieces\n * default. Process-global, populated once at startup on the SERVER and in the BROWSER, with no DI\n * wiring (like `HeaderRegistry` / `LogManager`).\n *\n * ```ts\n * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());\n * ApiRegistry.setErrorTranslator(new VendorErrorTranslator(), CallScope.api(VendorApi));\n * ApiRegistry.setErrorClassifier(new CompanyClassifier(), CallScope.all());\n * ```\n */\nexport class ApiRegistry {\n    /**\n     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ApiRegistry.getErrorTranslator} is never\n     * undefined.\n     *\n     * ONE translator per scope, not a list, on purpose: an app that has several layers of error\n     * policy for one scope composes them INSIDE its own `toWire`, where the precedence is written\n     * down. The ladder exists because vendors put their errors on the wire in their OWN formats — a\n     * per-API translator reads one vendor's 4xx body (`fromWire`), or writes the error body an\n     * inbound vendor expects back (`toWire`), while every other contract keeps the app's ALL one.\n     */\n    private static readonly errorTranslators = new CallScopeLadder<TranslatorSlot>(\n        () => new TranslatorSlot(),\n    );\n\n    /**\n     * The {@link ErrorClassifier} per {@link CallScope} — method -> API -> ALL, and below every rung\n     * {@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}. A classifier that DEFERS (`undefined`) falls through\n     * to the next rung. The ALL classifier reads {@link ApiMethodInfo.side}, so one classifier covers\n     * the server router AND every internal client; an SDK-wrapping api-client registers its own at\n     * its abstract `XxxApi` class. See {@link ApiRegistry.classify}.\n     */\n    private static readonly errorClassifiers = new CallScopeLadder<ClassifierSlot>(\n        () => new ClassifierSlot(),\n    );\n\n    /**\n     * Install an {@link ErrorTranslator} for one {@link CallScope}: `CallScope.all()` (the app's\n     * translator, server side AND every client side), one contract (`CallScope.api(VendorApi)`), or\n     * one method of one contract (`CallScope.method(VendorApi, 'sync')`). The scope is REQUIRED —\n     * there is no unscoped spelling. Call at startup, on the server AND in the browser.\n     *\n     * `set`, not `add`: see the field doc above for why a per-scope LIST is not wanted. A translator\n     * declines an error by DELEGATING to {@link WebpiecesDefaultErrorTranslator} — not to the next\n     * rung.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorTranslator(translator: ErrorTranslator, scope: CallScope): void {\n        ApiRegistry.errorTranslators.at(scope).translator = translator;\n    }\n\n    /**\n     * THE {@link ErrorTranslator} for one call — method -> API -> ALL ->\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, never `undefined`, so a caller never branches.\n     *\n     * Both arguments are required so every call site states what it knows: the client and the server\n     * pass the route's contract class and method; a failure with no route (an unmatched request, a\n     * failure before routing) passes `undefined, undefined` and reaches the ALL rung alone.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslator(api: Function | undefined, methodName: string | undefined): ErrorTranslator {\n        const registered = ApiRegistry.errorTranslators\n            .rungs(api, methodName)\n            .find((slot: TranslatorSlot) => slot.translator !== undefined)?.translator;\n        return registered ?? WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n    }\n\n    /**\n     * Install an {@link ErrorClassifier} for one {@link CallScope}: `CallScope.all()` (the\n     * app/company classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router\n     * and every internal client), one contract (an SDK-wrapping api-client keys by its abstract\n     * `XxxApi`), or one method of one contract. The scope is REQUIRED. Call at startup, on the server\n     * AND in the browser. See {@link ErrorClassifier}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setErrorClassifier(classifier: ErrorClassifier, scope: CallScope): void {\n        ApiRegistry.errorClassifiers.at(scope).classifier = classifier;\n    }\n\n    /**\n     * The {@link CallOutcome} of a thrown API-call error. Resolved on the {@link CallScope} ladder of\n     * `methodInfo.contract` / `methodInfo.methodName`, most specific first, and ALWAYS definitive:\n     *   1. the method classifier — unless it defers;\n     *   2. else the API classifier — unless it defers;\n     *   3. else the ALL classifier — unless it defers;\n     *   4. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.\n     *\n     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `ClientRegistry`'s per-attempt\n     * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome {\n        const rungs = ApiRegistry.errorClassifiers.rungs(methodInfo.contract, methodInfo.methodName);\n        for (const slot of rungs) {\n            const verdict = slot.classifier?.classify(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        return WEBPIECES_DEFAULT_ERROR_CLASSIFIER.classify(error, methodInfo);\n    }\n\n    /**\n     * Put the process-globals back to the state a fresh process starts in. For TESTS, so one spec\n     * cannot leak its registrations into the next.\n     *\n     * It empties every translator and classifier rung, which RESTORES the webpieces defaults:\n     * `getErrorTranslator(...)` and `classify(...)` fall through to them below every rung, so\n     * \"cleared\" is not a state they have.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static resetForTests(): void {\n        ApiRegistry.errorTranslators.clear();\n        ApiRegistry.errorClassifiers.clear();\n    }\n}\n"]}

package/src/http/CallScope.d.ts

@@ -1,15 +1,42 @@
 /**
- * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method
- * of one contract. The contract is always the CLASS (the `@ApiPath` contract, or an SDK-wrapping
- * api-client's abstract `XxxApi`), never its name — a string key is one typo away from silently
- * matching nothing.
+ * Where a policy applies: every contract ({@link CallScope.all}), one contract ({@link CallScope.api}),
+ * or one method of one contract ({@link CallScope.method}). The contract is always the CLASS (the
+ * `@ApiPath` contract, or an SDK-wrapping api-client's abstract `XxxApi`), never its name — a string
+ * key is one typo away from silently matching nothing — and `method` checks the method name against
+ * that class, so a misspelled method does not compile either.
  *
- * Every per-call startup registry scopes its settings with this ONE ladder: `CallRegistry`
- * (strategy, timeout), `ClientRegistry` (error translator, error classifier) and cloudtasks-client's
+ * The constructor is private: the three factories are the ONLY way to get one, so a string, `{}` or a
+ * bare class is not a scope. `grep -rn 'CallScope.all('` lists every app-wide policy.
+ *
+ * ```ts
+ * ClientRegistry.setTimeout(5_000, CallScope.api(VendorApi));
+ * ClientRegistry.setStrategy(retry, CallScope.method(VendorApi, 'sync'));
+ * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());
+ * ```
+ *
+ * Every per-call startup registry scopes its settings with this ONE ladder: `ClientRegistry`
+ * (strategy, timeout), `ApiRegistry` (error translator, error classifier) and cloudtasks-client's
  * `GcpTaskRegistry` (customizer, gax). Resolution is always method -> API -> ALL -> the registry's
  * own webpieces default.
  */
-export type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];
+export declare class CallScope {
+    /** The contract CLASS, or `undefined` for every contract. */
+    readonly api: Function | undefined;
+    /** One method of {@link CallScope.api}, or `undefined` for the whole contract. */
+    readonly methodName: string | undefined;
+    /**
+     * A private member makes the type NOMINAL: without it an object literal `{ api, methodName }`
+     * would satisfy `CallScope` structurally and skip the factories.
+     */
+    private readonly nominal;
+    private constructor();
+    /** Every contract — the app's (or company's) one policy. Has no method. */
+    static all(): CallScope;
+    /** One contract, keyed by its CLASS. */
+    static api(api: Function): CallScope;
+    /** One method of one contract; `methodName` must be a member the contract declares. */
+    static method<T>(api: abstract new (...args: never[]) => T, methodName: keyof T & string): CallScope;
+}
 /**
  * The ONE implementation of the {@link CallScope} ladder. It stores one slot per scope (created on
  * first use by `create`) and answers a call's rungs most-specific-first; each registry decides what a
@@ -22,7 +49,7 @@ export declare class CallScopeLadder<T> {
     private readonly apis;
     constructor(create: () => T);
     /** The slot for `scope`, created on first use. Registries write their setting into it. */
-    at(...scope: CallScope): T;
+    at(scope: CallScope): T;
     /**
      * The registered slots for one call, most specific first: method, then API, then ALL. A rung with
      * no slot is skipped. `api` undefined (a failure before routing, which has no route and so no

package/src/http/CallScope.js

@@ -1,6 +1,60 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CallScopeLadder = void 0;
+exports.CallScopeLadder = exports.CallScope = void 0;
+/**
+ * Where a policy applies: every contract ({@link CallScope.all}), one contract ({@link CallScope.api}),
+ * or one method of one contract ({@link CallScope.method}). The contract is always the CLASS (the
+ * `@ApiPath` contract, or an SDK-wrapping api-client's abstract `XxxApi`), never its name — a string
+ * key is one typo away from silently matching nothing — and `method` checks the method name against
+ * that class, so a misspelled method does not compile either.
+ *
+ * The constructor is private: the three factories are the ONLY way to get one, so a string, `{}` or a
+ * bare class is not a scope. `grep -rn 'CallScope.all('` lists every app-wide policy.
+ *
+ * ```ts
+ * ClientRegistry.setTimeout(5_000, CallScope.api(VendorApi));
+ * ClientRegistry.setStrategy(retry, CallScope.method(VendorApi, 'sync'));
+ * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());
+ * ```
+ *
+ * Every per-call startup registry scopes its settings with this ONE ladder: `ClientRegistry`
+ * (strategy, timeout), `ApiRegistry` (error translator, error classifier) and cloudtasks-client's
+ * `GcpTaskRegistry` (customizer, gax). Resolution is always method -> API -> ALL -> the registry's
+ * own webpieces default.
+ */
+class CallScope {
+    api;
+    methodName;
+    /**
+     * A private member makes the type NOMINAL: without it an object literal `{ api, methodName }`
+     * would satisfy `CallScope` structurally and skip the factories.
+     */
+    nominal = true;
+    constructor(
+    /** The contract CLASS, or `undefined` for every contract. */
+    api, 
+    /** One method of {@link CallScope.api}, or `undefined` for the whole contract. */
+    methodName) {
+        this.api = api;
+        this.methodName = methodName;
+    }
+    /** Every contract — the app's (or company's) one policy. Has no method. */
+    // webpieces-disable no-function-outside-class -- static factory of the scope value class
+    static all() {
+        return new CallScope(undefined, undefined);
+    }
+    /** One contract, keyed by its CLASS. */
+    // webpieces-disable no-function-outside-class -- static factory of the scope value class
+    static api(api) {
+        return new CallScope(api, undefined);
+    }
+    /** One method of one contract; `methodName` must be a member the contract declares. */
+    // webpieces-disable no-function-outside-class -- static factory of the scope value class
+    static method(api, methodName) {
+        return new CallScope(api, methodName);
+    }
+}
+exports.CallScope = CallScope;
 class ApiRungs {
     api;
     methods = new Map();
@@ -19,9 +73,9 @@ class CallScopeLadder {
         this.create = create;
     }
     /** The slot for `scope`, created on first use. Registries write their setting into it. */
-    at(...scope) {
-        const api = scope[0];
-        if (api === 'ALL') {
+    at(scope) {
+        const api = scope.api;
+        if (api === undefined) {
             if (this.all === undefined)
                 this.all = this.create();
             return this.all;
@@ -31,7 +85,7 @@ class CallScopeLadder {
             rungs = new ApiRungs();
             this.apis.set(api, rungs);
         }
-        const methodName = scope[1];
+        const methodName = scope.methodName;
         if (methodName === undefined) {
             if (rungs.api === undefined)
                 rungs.api = this.create();

package/src/http/CallScope.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallScope.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallScope.ts"],"names":[],"mappings":";;;AAaA,MAAM,QAAQ;IACV,GAAG,CAAK;IACC,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAa,eAAe;IAIK;IAHrB,GAAG,CAAgB;IACV,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEzD,YAA6B,MAAe;QAAf,WAAM,GAAN,MAAM,CAAS;IAAG,CAAC;IAEhD,0FAA0F;IAC1F,EAAE,CAAC,GAAG,KAAgB;QAClB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;YAChB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;gBAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC,GAAG,CAAC;QACpB,CAAC;QACD,IAAI,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,KAAK,GAAG,IAAI,QAAQ,EAAK,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;gBAAE,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvD,OAAO,KAAK,CAAC,GAAG,CAAC;QACrB,CAAC;QACD,IAAI,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACrB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAyB,EAAE,UAA8B;QAC3D,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrF,IAAI,MAAM,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,KAAK,EAAE,GAAG,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,KAAK;QACD,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACJ;AAlDD,0CAkDC","sourcesContent":["/**\n * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method\n * of one contract. The contract is always the CLASS (the `@ApiPath` contract, or an SDK-wrapping\n * api-client's abstract `XxxApi`), never its name — a string key is one typo away from silently\n * matching nothing.\n *\n * Every per-call startup registry scopes its settings with this ONE ladder: `CallRegistry`\n * (strategy, timeout), `ClientRegistry` (error translator, error classifier) and cloudtasks-client's\n * `GcpTaskRegistry` (customizer, gax). Resolution is always method -> API -> ALL -> the registry's\n * own webpieces default.\n */\nexport type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];\n\nclass ApiRungs<T> {\n    api?: T;\n    readonly methods = new Map<string, T>();\n}\n\n/**\n * The ONE implementation of the {@link CallScope} ladder. It stores one slot per scope (created on\n * first use by `create`) and answers a call's rungs most-specific-first; each registry decides what a\n * rung's slot holds and how a rung \"answers\" (first value present, or first verdict that does not\n * defer).\n */\nexport class CallScopeLadder<T> {\n    private all: T | undefined;\n    private readonly apis = new Map<Function, ApiRungs<T>>();\n\n    constructor(private readonly create: () => T) {}\n\n    /** The slot for `scope`, created on first use. Registries write their setting into it. */\n    at(...scope: CallScope): T {\n        const api = scope[0];\n        if (api === 'ALL') {\n            if (this.all === undefined) this.all = this.create();\n            return this.all;\n        }\n        let rungs = this.apis.get(api);\n        if (!rungs) {\n            rungs = new ApiRungs<T>();\n            this.apis.set(api, rungs);\n        }\n        const methodName = scope[1];\n        if (methodName === undefined) {\n            if (rungs.api === undefined) rungs.api = this.create();\n            return rungs.api;\n        }\n        let slot = rungs.methods.get(methodName);\n        if (slot === undefined) {\n            slot = this.create();\n            rungs.methods.set(methodName, slot);\n        }\n        return slot;\n    }\n\n    /**\n     * The registered slots for one call, most specific first: method, then API, then ALL. A rung with\n     * no slot is skipped. `api` undefined (a failure before routing, which has no route and so no\n     * contract class) reaches only the ALL rung.\n     */\n    rungs(api: Function | undefined, methodName: string | undefined): T[] {\n        const found: T[] = [];\n        const rungs = api === undefined ? undefined : this.apis.get(api);\n        const method = methodName === undefined ? undefined : rungs?.methods.get(methodName);\n        if (method !== undefined) found.push(method);\n        if (rungs?.api !== undefined) found.push(rungs.api);\n        if (this.all !== undefined) found.push(this.all);\n        return found;\n    }\n\n    clear(): void {\n        this.all = undefined;\n        this.apis.clear();\n    }\n}\n"]}
+{"version":3,"file":"CallScope.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallScope.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,SAAS;IASL;IAEA;IAVb;;;OAGG;IACc,OAAO,GAAG,IAAI,CAAC;IAEhC;IACI,6DAA6D;IACpD,GAAyB;IAClC,kFAAkF;IACzE,UAA8B;QAF9B,QAAG,GAAH,GAAG,CAAsB;QAEzB,eAAU,GAAV,UAAU,CAAoB;IACxC,CAAC;IAEJ,2EAA2E;IAC3E,yFAAyF;IACzF,MAAM,CAAC,GAAG;QACN,OAAO,IAAI,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,wCAAwC;IACxC,yFAAyF;IACzF,MAAM,CAAC,GAAG,CAAC,GAAa;QACpB,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;IACzC,CAAC;IAED,uFAAuF;IACvF,yFAAyF;IACzF,MAAM,CAAC,MAAM,CAAI,GAAyC,EAAE,UAA4B;QACpF,OAAO,IAAI,SAAS,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;CACJ;AA/BD,8BA+BC;AAED,MAAM,QAAQ;IACV,GAAG,CAAK;IACC,OAAO,GAAG,IAAI,GAAG,EAAa,CAAC;CAC3C;AAED;;;;;GAKG;AACH,MAAa,eAAe;IAIK;IAHrB,GAAG,CAAgB;IACV,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEzD,YAA6B,MAAe;QAAf,WAAM,GAAN,MAAM,CAAS;IAAG,CAAC;IAEhD,0FAA0F;IAC1F,EAAE,CAAC,KAAgB;QACf,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;QACtB,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;gBAAE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC,GAAG,CAAC;QACpB,CAAC;QACD,IAAI,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,EAAE,CAAC;YACT,KAAK,GAAG,IAAI,QAAQ,EAAK,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;QACpC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;gBAAE,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvD,OAAO,KAAK,CAAC,GAAG,CAAC;QACrB,CAAC;QACD,IAAI,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACrB,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACrB,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAyB,EAAE,UAA8B;QAC3D,MAAM,KAAK,GAAQ,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrF,IAAI,MAAM,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,KAAK,EAAE,GAAG,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,KAAK;QACD,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACJ;AAlDD,0CAkDC","sourcesContent":["/**\n * Where a policy applies: every contract ({@link CallScope.all}), one contract ({@link CallScope.api}),\n * or one method of one contract ({@link CallScope.method}). The contract is always the CLASS (the\n * `@ApiPath` contract, or an SDK-wrapping api-client's abstract `XxxApi`), never its name — a string\n * key is one typo away from silently matching nothing — and `method` checks the method name against\n * that class, so a misspelled method does not compile either.\n *\n * The constructor is private: the three factories are the ONLY way to get one, so a string, `{}` or a\n * bare class is not a scope. `grep -rn 'CallScope.all('` lists every app-wide policy.\n *\n * ```ts\n * ClientRegistry.setTimeout(5_000, CallScope.api(VendorApi));\n * ClientRegistry.setStrategy(retry, CallScope.method(VendorApi, 'sync'));\n * ApiRegistry.setErrorTranslator(new AppErrorTranslator(), CallScope.all());\n * ```\n *\n * Every per-call startup registry scopes its settings with this ONE ladder: `ClientRegistry`\n * (strategy, timeout), `ApiRegistry` (error translator, error classifier) and cloudtasks-client's\n * `GcpTaskRegistry` (customizer, gax). Resolution is always method -> API -> ALL -> the registry's\n * own webpieces default.\n */\nexport class CallScope {\n    /**\n     * A private member makes the type NOMINAL: without it an object literal `{ api, methodName }`\n     * would satisfy `CallScope` structurally and skip the factories.\n     */\n    private readonly nominal = true;\n\n    private constructor(\n        /** The contract CLASS, or `undefined` for every contract. */\n        readonly api: Function | undefined,\n        /** One method of {@link CallScope.api}, or `undefined` for the whole contract. */\n        readonly methodName: string | undefined,\n    ) {}\n\n    /** Every contract — the app's (or company's) one policy. Has no method. */\n    // webpieces-disable no-function-outside-class -- static factory of the scope value class\n    static all(): CallScope {\n        return new CallScope(undefined, undefined);\n    }\n\n    /** One contract, keyed by its CLASS. */\n    // webpieces-disable no-function-outside-class -- static factory of the scope value class\n    static api(api: Function): CallScope {\n        return new CallScope(api, undefined);\n    }\n\n    /** One method of one contract; `methodName` must be a member the contract declares. */\n    // webpieces-disable no-function-outside-class -- static factory of the scope value class\n    static method<T>(api: abstract new (...args: never[]) => T, methodName: keyof T & string): CallScope {\n        return new CallScope(api, methodName);\n    }\n}\n\nclass ApiRungs<T> {\n    api?: T;\n    readonly methods = new Map<string, T>();\n}\n\n/**\n * The ONE implementation of the {@link CallScope} ladder. It stores one slot per scope (created on\n * first use by `create`) and answers a call's rungs most-specific-first; each registry decides what a\n * rung's slot holds and how a rung \"answers\" (first value present, or first verdict that does not\n * defer).\n */\nexport class CallScopeLadder<T> {\n    private all: T | undefined;\n    private readonly apis = new Map<Function, ApiRungs<T>>();\n\n    constructor(private readonly create: () => T) {}\n\n    /** The slot for `scope`, created on first use. Registries write their setting into it. */\n    at(scope: CallScope): T {\n        const api = scope.api;\n        if (api === undefined) {\n            if (this.all === undefined) this.all = this.create();\n            return this.all;\n        }\n        let rungs = this.apis.get(api);\n        if (!rungs) {\n            rungs = new ApiRungs<T>();\n            this.apis.set(api, rungs);\n        }\n        const methodName = scope.methodName;\n        if (methodName === undefined) {\n            if (rungs.api === undefined) rungs.api = this.create();\n            return rungs.api;\n        }\n        let slot = rungs.methods.get(methodName);\n        if (slot === undefined) {\n            slot = this.create();\n            rungs.methods.set(methodName, slot);\n        }\n        return slot;\n    }\n\n    /**\n     * The registered slots for one call, most specific first: method, then API, then ALL. A rung with\n     * no slot is skipped. `api` undefined (a failure before routing, which has no route and so no\n     * contract class) reaches only the ALL rung.\n     */\n    rungs(api: Function | undefined, methodName: string | undefined): T[] {\n        const found: T[] = [];\n        const rungs = api === undefined ? undefined : this.apis.get(api);\n        const method = methodName === undefined ? undefined : rungs?.methods.get(methodName);\n        if (method !== undefined) found.push(method);\n        if (rungs?.api !== undefined) found.push(rungs.api);\n        if (this.all !== undefined) found.push(this.all);\n        return found;\n    }\n\n    clear(): void {\n        this.all = undefined;\n        this.apis.clear();\n    }\n}\n"]}

package/src/http/CallStrategy.d.ts

@@ -19,7 +19,7 @@ export declare class CallContext {
      * per-attempt error classification resolves the classifier registered for THIS contract.
      * REQUIRED and never `undefined`: every transport knows its contract class (HTTP and Cloud Tasks
      * clients hold it, the IPC client proxy holds its `@WpInternal` class), and
-     * `CallRegistry.execute` re-keys the context a strategy sees onto the class it was given.
+     * `ClientRegistry.execute` re-keys the context a strategy sees onto the class it was given.
      *
      * NON-enumerable on purpose: this context rides on `ApiCallTimeoutError`, which is logged and
      * compared as data, and a class reference is not data.

package/src/http/CallStrategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallStrategy.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallStrategy.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;GAQG;AACH,MAAa,WAAW;IAcA;IACA;IACA;IAHpB,YACoB,OAAe,EACf,UAAkB,EAClB,SAA4B;IAC5C,uEAAuE;IACvE,QAAkB;QAJF,YAAO,GAAP,OAAO,CAAQ;QACf,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAmB;QAI5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;CACJ;AAtBD,kCAsBC","sourcesContent":["import { EndpointOperation } from './HttpEndpointOptions';\n\n/** One bounded attempt. Only an explicitly registered strategy may retry it. */\nexport type Attempt<T> = (timeoutMs: number) => Promise<T>;\n\n/**\n * Contract identity for diagnostics; registry keys use the class itself.\n *\n * `operation` is the endpoint's declared `@Endpoint` side-effect contract (`READ`,\n * `WRITE_IDEMPOTENT` or `WRITE`). A {@link CallStrategy} reads it to decide whether a retry is safe,\n * and `ApiCallTimeoutError` reads it to choose the text it shows an end user. A transport with\n * no declared operation (IPC contracts declare none) passes `WRITE`: the conservative answer, since\n * it never invites a blind retry of something that may already have happened.\n */\nexport class CallContext {\n    /**\n     * The contract CLASS the call belongs to — the key of the `CallScope` ladder, so a strategy's\n     * per-attempt error classification resolves the classifier registered for THIS contract.\n     * REQUIRED and never `undefined`: every transport knows its contract class (HTTP and Cloud Tasks\n     * clients hold it, the IPC client proxy holds its `@WpInternal` class), and\n     * `CallRegistry.execute` re-keys the context a strategy sees onto the class it was given.\n     *\n     * NON-enumerable on purpose: this context rides on `ApiCallTimeoutError`, which is logged and\n     * compared as data, and a class reference is not data.\n     */\n    declare readonly contract: Function;\n\n    constructor(\n        public readonly apiName: string,\n        public readonly methodName: string,\n        public readonly operation: EndpointOperation,\n        /** REQUIRED — the contract CLASS; see {@link CallContext.contract}. */\n        contract: Function,\n    ) {\n        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });\n    }\n}\n\n/** Owns all timing and retry decisions. No public cancellation signal. */\nexport type CallStrategy<T> = (call: Attempt<T>, ctx: CallContext) => Promise<T>;\n"]}
+{"version":3,"file":"CallStrategy.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallStrategy.ts"],"names":[],"mappings":";;;AAKA;;;;;;;;GAQG;AACH,MAAa,WAAW;IAcA;IACA;IACA;IAHpB,YACoB,OAAe,EACf,UAAkB,EAClB,SAA4B;IAC5C,uEAAuE;IACvE,QAAkB;QAJF,YAAO,GAAP,OAAO,CAAQ;QACf,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAmB;QAI5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IACpF,CAAC;CACJ;AAtBD,kCAsBC","sourcesContent":["import { EndpointOperation } from './HttpEndpointOptions';\n\n/** One bounded attempt. Only an explicitly registered strategy may retry it. */\nexport type Attempt<T> = (timeoutMs: number) => Promise<T>;\n\n/**\n * Contract identity for diagnostics; registry keys use the class itself.\n *\n * `operation` is the endpoint's declared `@Endpoint` side-effect contract (`READ`,\n * `WRITE_IDEMPOTENT` or `WRITE`). A {@link CallStrategy} reads it to decide whether a retry is safe,\n * and `ApiCallTimeoutError` reads it to choose the text it shows an end user. A transport with\n * no declared operation (IPC contracts declare none) passes `WRITE`: the conservative answer, since\n * it never invites a blind retry of something that may already have happened.\n */\nexport class CallContext {\n    /**\n     * The contract CLASS the call belongs to — the key of the `CallScope` ladder, so a strategy's\n     * per-attempt error classification resolves the classifier registered for THIS contract.\n     * REQUIRED and never `undefined`: every transport knows its contract class (HTTP and Cloud Tasks\n     * clients hold it, the IPC client proxy holds its `@WpInternal` class), and\n     * `ClientRegistry.execute` re-keys the context a strategy sees onto the class it was given.\n     *\n     * NON-enumerable on purpose: this context rides on `ApiCallTimeoutError`, which is logged and\n     * compared as data, and a class reference is not data.\n     */\n    declare readonly contract: Function;\n\n    constructor(\n        public readonly apiName: string,\n        public readonly methodName: string,\n        public readonly operation: EndpointOperation,\n        /** REQUIRED — the contract CLASS; see {@link CallContext.contract}. */\n        contract: Function,\n    ) {\n        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });\n    }\n}\n\n/** Owns all timing and retry decisions. No public cancellation signal. */\nexport type CallStrategy<T> = (call: Attempt<T>, ctx: CallContext) => Promise<T>;\n"]}