@webpieces/core-util 0.4.955 → 0.4.957

package/src/http/ClientRegistry.d.ts

@@ -1,5 +1,6 @@
 import { ErrorTranslator } from './ErrorTranslator';
-import { CallOutcome, ErrorClassifier, KeyedErrorClassifier } from './ErrorClassifier';
+import { CallOutcome, ErrorClassifier } from './ErrorClassifier';
+import { CallScope } from './CallScope';
 import { ApiMethodInfo } from './ApiMethodInfo';
 /**
  * Derives a base URL for a service name that has NO registered mapping — the pluggable half of
@@ -54,35 +55,26 @@ export declare class ClientRegistry {
     /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
     private static deriver;
     /**
-     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding
-     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}
-     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same
-     * no-DI pattern as {@link ClientRegistry.mappings} above.
+     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ClientRegistry.getErrorTranslator} is
+     * never undefined. Process-global, set once at startup on the SERVER and in the BROWSER — the
+     * same no-DI pattern as {@link ClientRegistry.mappings} above.
      *
-     * There is no "did anyone register one" question anywhere in the framework because this field
-     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an
-     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.
-     *
-     * ONE, not a list, on purpose: an app that has several layers of error policy composes them
-     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit
-     * in the order two unrelated startup paths happened to register.
-     */
-    private static errorTranslator;
-    /**
-     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it
-     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and
-     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the
-     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
+     * 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 appDefaultErrorClassifier;
+    private static readonly errorTranslators;
     /**
-     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
-     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external
-     * client overrides the default for its own apiClass only. Internal clients / the server register
-     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.
+     * 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 ClientRegistry.classify}.
      */
-    private static readonly errorClassifiersByApiClass;
+    private static readonly errorClassifiers;
     /** Map a service name to `http://localhost:<port>`. */
     static addMapping(svcName: string, port: number): void;
     /**
@@ -120,42 +112,46 @@ export declare class ClientRegistry {
      */
     static resolve(svcName: string): Promise<string>;
     /**
-     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for
-     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping
-     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring
-     * {@link ClientRegistry.addMapping}.
+     * Install an {@link ErrorTranslator} for one {@link CallScope}: `'ALL'` (the app's translator,
+     * server side AND every client side), one contract CLASS, or one method of one contract. The
+     * scope is REQUIRED — there is no unscoped spelling. Call at startup, on the server AND in the
+     * browser, mirroring {@link ClientRegistry.addMapping}.
      *
-     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.
-     */
-    static setErrorTranslator(translator: ErrorTranslator): void;
-    /**
-     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.
+     * ```ts
+     * ClientRegistry.setErrorTranslator(new AppErrorTranslator(), 'ALL');
+     * ClientRegistry.setErrorTranslator(new VendorErrorTranslator(), VendorApi);        // one contract
+     * ClientRegistry.setErrorTranslator(new LegacyErrorTranslator(), VendorApi, 'sync'); // one method
+     * ```
      *
-     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is
-     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and
-     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),
-     * so every call site in the framework is one unconditional line.
+     * `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 — exactly as before.
      */
-    static getErrorTranslator(): ErrorTranslator;
+    static setErrorTranslator(translator: ErrorTranslator, ...scope: CallScope): void;
     /**
-     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and
-     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the
-     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier
-     * claims. See {@link ErrorClassifier}.
+     * 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 setDefaultErrorClassifier(classifier: ErrorClassifier): void;
+    static getErrorTranslator(api: Function | undefined, methodName: string | undefined): ErrorTranslator;
     /**
-     * Register a per-EXTERNAL-client error classifier, keyed by its
-     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the
-     * default tier for calls with that apiClass. Call ONCE at startup. See {@link ErrorClassifier}.
+     * Install an {@link ErrorClassifier} for one {@link CallScope}: `'ALL'` (the app/company
+     * classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router and every
+     * internal client), one contract CLASS (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 addErrorClassifier(keyed: KeyedErrorClassifier): void;
+    static setErrorClassifier(classifier: ErrorClassifier, ...scope: CallScope): void;
     /**
-     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS
-     * definitive:
-     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;
-     *   2. else the app default classifier — unless it defers;
-     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     * 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), `CallRegistry`'s per-attempt
      * log line, `LogApiCall` (EXPECTED → OTHER, else FAIL) and the MCP renderer's retry advice.
@@ -165,10 +161,10 @@ export declare class ClientRegistry {
      * 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 RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
-     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error
-     * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
-     * webpieces' own behaviour back asks for exactly that.
+     * 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. A spec that wants webpieces' own behaviour back asks for
+     * exactly that.
      */
     static resetForTests(): void;
 }

package/src/http/ClientRegistry.js

@@ -1,8 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientRegistry = 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;
+}
 /**
  * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every
  * environment. A client is built once but a URL is per-environment, so the URL belongs here rather
@@ -43,35 +52,26 @@ class ClientRegistry {
     /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */
     static deriver;
     /**
-     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding
-     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}
-     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same
-     * no-DI pattern as {@link ClientRegistry.mappings} above.
-     *
-     * There is no "did anyone register one" question anywhere in the framework because this field
-     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an
-     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.
+     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung
+     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ClientRegistry.getErrorTranslator} is
+     * never undefined. Process-global, set once at startup on the SERVER and in the BROWSER — the
+     * same no-DI pattern as {@link ClientRegistry.mappings} above.
      *
-     * ONE, not a list, on purpose: an app that has several layers of error policy composes them
-     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit
-     * in the order two unrelated startup paths happened to register.
+     * 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 errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
+    static errorTranslators = new CallScope_1.CallScopeLadder(() => new TranslatorSlot());
     /**
-     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}
-     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it
-     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and
-     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the
-     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.
+     * 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 ClientRegistry.classify}.
      */
-    static appDefaultErrorClassifier = WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER;
-    /**
-     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}
-     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external
-     * client overrides the default for its own apiClass only. Internal clients / the server register
-     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.
-     */
-    static errorClassifiersByApiClass = new Map();
+    static errorClassifiers = new CallScope_1.CallScopeLadder(() => new ClassifierSlot());
     /** Map a service name to `http://localhost:<port>`. */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static addMapping(svcName, port) {
@@ -153,89 +153,88 @@ class ClientRegistry {
         return url;
     }
     /**
-     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for
-     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping
-     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring
-     * {@link ClientRegistry.addMapping}.
+     * Install an {@link ErrorTranslator} for one {@link CallScope}: `'ALL'` (the app's translator,
+     * server side AND every client side), one contract CLASS, or one method of one contract. The
+     * scope is REQUIRED — there is no unscoped spelling. Call at startup, on the server AND in the
+     * browser, mirroring {@link ClientRegistry.addMapping}.
      *
-     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.
-     */
-    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static setErrorTranslator(translator) {
-        ClientRegistry.errorTranslator = translator;
-    }
-    /**
-     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.
+     * ```ts
+     * ClientRegistry.setErrorTranslator(new AppErrorTranslator(), 'ALL');
+     * ClientRegistry.setErrorTranslator(new VendorErrorTranslator(), VendorApi);        // one contract
+     * ClientRegistry.setErrorTranslator(new LegacyErrorTranslator(), VendorApi, 'sync'); // one method
+     * ```
      *
-     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is
-     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and
-     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),
-     * so every call site in the framework is one unconditional line.
+     * `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 — exactly as before.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
-    static getErrorTranslator() {
-        return ClientRegistry.errorTranslator;
+    static setErrorTranslator(translator, ...scope) {
+        ClientRegistry.errorTranslators.at(...scope).translator = translator;
     }
     /**
-     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and
-     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the
-     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier
-     * claims. See {@link ErrorClassifier}.
+     * 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 setDefaultErrorClassifier(classifier) {
-        ClientRegistry.appDefaultErrorClassifier = classifier;
+    static getErrorTranslator(api, methodName) {
+        const registered = ClientRegistry.errorTranslators
+            .rungs(api, methodName)
+            .find((slot) => slot.translator !== undefined)?.translator;
+        return registered ?? WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
     }
     /**
-     * Register a per-EXTERNAL-client error classifier, keyed by its
-     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the
-     * default tier for calls with that apiClass. Call ONCE at startup. See {@link ErrorClassifier}.
+     * Install an {@link ErrorClassifier} for one {@link CallScope}: `'ALL'` (the app/company
+     * classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router and every
+     * internal client), one contract CLASS (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 addErrorClassifier(keyed) {
-        ClientRegistry.errorClassifiersByApiClass.set(keyed.apiClass, keyed.classifier);
+    static setErrorClassifier(classifier, ...scope) {
+        ClientRegistry.errorClassifiers.at(...scope).classifier = classifier;
     }
     /**
-     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS
-     * definitive:
-     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;
-     *   2. else the app default classifier — unless it defers;
-     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.
+     * 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), `CallRegistry`'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 perClient = ClientRegistry.errorClassifiersByApiClass.get(methodInfo.apiClass);
-        if (perClient !== undefined) {
-            const verdict = perClient.classify(error, methodInfo);
+        const rungs = ClientRegistry.errorClassifiers.rungs(methodInfo.contract, methodInfo.methodName);
+        for (const slot of rungs) {
+            const verdict = slot.classifier?.classify(error, methodInfo);
             if (verdict !== undefined) {
                 return verdict;
             }
         }
-        const verdict = ClientRegistry.appDefaultErrorClassifier.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 RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole
-     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error
-     * classifier are non-optional now, so "cleared" is not a state they have. A spec that wants
-     * webpieces' own behaviour back asks for exactly that.
+     * 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. A spec that wants webpieces' own behaviour back asks for
+     * exactly that.
      */
     // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected
     static resetForTests() {
         ClientRegistry.mappings.clear();
         ClientRegistry.deriver = undefined;
-        ClientRegistry.errorTranslator = WebpiecesDefaultErrorTranslator_1.WEBPIECES_DEFAULT_ERROR_TRANSLATOR;
-        ClientRegistry.appDefaultErrorClassifier = WebpiecesDefaultErrorClassifier_1.WEBPIECES_DEFAULT_ERROR_CLASSIFIER;
-        ClientRegistry.errorClassifiersByApiClass.clear();
+        ClientRegistry.errorTranslators.clear();
+        ClientRegistry.errorClassifiers.clear();
     }
 }
 exports.ClientRegistry = ClientRegistry;

package/src/http/ClientRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":";;;AAEA,uFAAuF;AACvF,uFAAuF;AAiBvF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAa,cAAc;IACvB,0FAA0F;IAClF,MAAM,CAAU,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE7D,gGAAgG;IACxF,MAAM,CAAC,OAAO,CAAgC;IAEtD;;;;;;;;;;;;;OAaG;IACK,MAAM,CAAC,eAAe,GAAoB,oEAAkC,CAAC;IAErF;;;;;;OAMG;IACK,MAAM,CAAC,yBAAyB,GAAoB,oEAAkC,CAAC;IAE/F;;;;;OAKG;IACK,MAAM,CAAU,0BAA0B,GAAG,IAAI,GAAG,EAA2B,CAAC;IAExF,uDAAuD;IACvD,wJAAwJ;IACxJ,MAAM,CAAC,UAAU,CAAC,OAAe,EAAE,IAAY;QAC3C,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,oBAAoB,IAAI,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;;;OAKG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,aAAa,CAAC,OAAe,EAAE,GAAW;QAC7C,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9C,CAAC;IAED;;;OAGG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,UAAU,CAAC,EAAqB;QACnC,cAAc,CAAC,OAAO,GAAG,EAAE,CAAC;IAChC,CAAC;IAED,kGAAkG;IAClG,wJAAwJ;IACxJ,MAAM,CAAC,SAAS,CAAC,OAAe;QAC5B,OAAO,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAChD,CAAC;IAED;;;OAGG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,MAAM,CAAC,OAAe;QACzB,MAAM,GAAG,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACX,kCAAkC,OAAO,6BAA6B;gBAClE,oEAAoE;gBACpE,iEAAiE,CACxE,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,UAAU,CAAC,OAAe;QAC7B,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QACD,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,OAAe;QAChC,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACX,uBAAuB,OAAO,MAAM;gBAChC,iDAAiD,OAAO,YAAY;gBACpE,oDAAoD,OAAO,qBAAqB;gBAChF,gFAAgF;gBAChF,2FAA2F;gBAC3F,yFAAyF;gBACzF,2FAA2F,CAClG,CAAC;QACN,CAAC;QACD,OAAO,GAAG,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB,CAAC,UAA2B;QACjD,cAAc,CAAC,eAAe,GAAG,UAAU,CAAC;IAChD,CAAC;IAED;;;;;;;OAOG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB;QACrB,OAAO,cAAc,CAAC,eAAe,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,yBAAyB,CAAC,UAA2B;QACxD,cAAc,CAAC,yBAAyB,GAAG,UAAU,CAAC;IAC1D,CAAC;IAED;;;;OAIG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,kBAAkB,CAAC,KAA2B;QACjD,cAAc,CAAC,0BAA0B,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;OASG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,QAAQ,CAAC,KAAY,EAAE,UAAyB;QACnD,MAAM,SAAS,GAAG,cAAc,CAAC,0BAA0B,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QACrF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;YACtD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,OAAO,CAAC;YACnB,CAAC;QACL,CAAC;QACD,MAAM,OAAO,GAAG,cAAc,CAAC,yBAAyB,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;QACrF,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,OAAO,CAAC;QACnB,CAAC;QACD,OAAO,oEAAkC,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC1E,CAAC;IAED;;;;;;;;OAQG;IACH,wJAAwJ;IACxJ,MAAM,CAAC,aAAa;QAChB,cAAc,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;QAChC,cAAc,CAAC,OAAO,GAAG,SAAS,CAAC;QACnC,cAAc,CAAC,eAAe,GAAG,oEAAkC,CAAC;QACpE,cAAc,CAAC,yBAAyB,GAAG,oEAAkC,CAAC;QAC9E,cAAc,CAAC,0BAA0B,CAAC,KAAK,EAAE,CAAC;IACtD,CAAC;;AA5NL,wCA6NC","sourcesContent":["import { ErrorTranslator } from './ErrorTranslator';\nimport { CallOutcome, ErrorClassifier, KeyedErrorClassifier } from './ErrorClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_CLASSIFIER } from './WebpiecesDefaultErrorClassifier';\nimport { WEBPIECES_DEFAULT_ERROR_TRANSLATOR } from './WebpiecesDefaultErrorTranslator';\nimport { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * Derives a base URL for a service name that has NO registered mapping — the pluggable half of\n * {@link ClientRegistry} resolution. One per environment, installed once at startup:\n *\n * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata\n *   server. For code running ON GCP.\n * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the\n *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).\n * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or\n *   anything else with predictable DNS.\n * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.\n */\nexport type ServiceUrlDeriver = (svcName: string) => Promise<string>;\n\n/**\n * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every\n * environment. A client is built once but a URL is per-environment, so the URL belongs here rather\n * than on the client: clients carry ONLY a svcName.\n *\n * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:\n *\n *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region\n *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.\n *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or\n *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,\n *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on\n *      their own.\n *   3. else the caller's fallback: the BROWSER goes relative (same origin — see\n *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),\n *      because a server has no \"own origin\" and an unresolvable peer is a setup bug.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\n *\n * ```ts\n * // startup, from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */\n    private static deriver: ServiceUrlDeriver | undefined;\n\n    /**\n     * The process's ONE {@link ErrorTranslator}. NEVER undefined — it starts life holding\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, and {@link ClientRegistry.setErrorTranslator}\n     * REPLACES it. Process-global, set once at startup on the SERVER and in the BROWSER — the same\n     * no-DI pattern as {@link ClientRegistry.mappings} above.\n     *\n     * There is no \"did anyone register one\" question anywhere in the framework because this field\n     * cannot be empty: every caller makes ONE unconditional call, and an app translator declines an\n     * error by DELEGATING to {@link WebpiecesDefaultErrorTranslator}.\n     *\n     * ONE, not a list, on purpose: an app that has several layers of error policy composes them\n     * INSIDE its own `toWire`, where the precedence is written down, instead of leaving it implicit\n     * in the order two unrelated startup paths happened to register.\n     */\n    private static errorTranslator: ErrorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n\n    /**\n     * The app/company DEFAULT {@link ErrorClassifier} — ONE per process, reads {@link ApiMethodInfo.side}\n     * so a single classifier covers the server router AND all internal clients. NEVER undefined: it\n     * starts life holding the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}) and\n     * {@link ClientRegistry.setDefaultErrorClassifier} replaces it. Populated once at startup on the\n     * SERVER and in the BROWSER — same no-DI pattern as {@link ClientRegistry.mappings}.\n     */\n    private static appDefaultErrorClassifier: ErrorClassifier = WEBPIECES_DEFAULT_ERROR_CLASSIFIER;\n\n    /**\n     * Per-EXTERNAL-client {@link ErrorClassifier}s, keyed by {@link ApiMethodInfo.apiClass}\n     * ('FirestoreAdminClient', 'ClaudeApi', ...). Consulted BEFORE the default tier, so an external\n     * client overrides the default for its own apiClass only. Internal clients / the server register\n     * nothing here and fall through to the default. See {@link ClientRegistry.classify}.\n     */\n    private static readonly errorClassifiersByApiClass = new Map<string, ErrorClassifier>();\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /**\n     * Map a service name to an explicit base URL (any host / any environment).\n     *\n     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.\n     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /**\n     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO\n     * mapping. Optional: an environment that registers every svcName it calls needs none.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDeriver(fn: ServiceUrlDeriver): void {\n        ClientRegistry.deriver = fn;\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.\n     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                    `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                    `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.\n     * Non-throwing — the BROWSER uses this and treats undefined as \"\" (relative → same origin),\n     * which is what a browser app calling the backend it was served from wants by default.\n     *\n     * Note the `!== undefined` guard: an empty-string mapping is a legal answer (\"this service is\n     * same-origin\"), so it must NOT fall through to derivation.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryResolve(svcName: string): Promise<string | undefined> {\n        const override = ClientRegistry.tryLookup(svcName);\n        if (override !== undefined) {\n            return Promise.resolve(override);\n        }\n        if (!ClientRegistry.deriver) {\n            return Promise.resolve(undefined);\n        }\n        return ClientRegistry.deriver(svcName);\n    }\n\n    /**\n     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no \"own\n     * origin\" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and\n     * say how to fix it.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static async resolve(svcName: string): Promise<string> {\n        const url = await ClientRegistry.tryResolve(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL for service \"${svcName}\".\\n` +\n                    `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\\n` +\n                    `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\\n` +\n                    `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\\n` +\n                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install the app's {@link ErrorTranslator} — the ONE symmetric owner of error translation for\n     * this process, server side AND every client side. Consulted BEFORE webpieces' built-in mapping\n     * in both directions. Call ONCE at startup, on the server AND in the browser, mirroring\n     * {@link ClientRegistry.addMapping}.\n     *\n     * `set`, not `add`: see the field doc above for why a registry LIST is not wanted.\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): void {\n        ClientRegistry.errorTranslator = translator;\n    }\n\n    /**\n     * THE {@link ErrorTranslator} for this process — never `undefined`, so a caller never branches.\n     *\n     * Until an app calls {@link ClientRegistry.setErrorTranslator} this is\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}. A registered translator answers EVERY error and\n     * EVERY response, declining by delegating to the webpieces default (see {@link ErrorTranslator}),\n     * so every call site in the framework is one unconditional line.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static getErrorTranslator(): ErrorTranslator {\n        return ClientRegistry.errorTranslator;\n    }\n\n    /**\n     * Set the app/company DEFAULT error classifier — ONE per process, covering the server router and\n     * all internal clients (it branches on {@link ApiMethodInfo.side}). Call ONCE at startup, on the\n     * server AND in the browser. Overrides the webpieces built-in for calls no per-apiClass classifier\n     * claims. 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 setDefaultErrorClassifier(classifier: ErrorClassifier): void {\n        ClientRegistry.appDefaultErrorClassifier = classifier;\n    }\n\n    /**\n     * Register a per-EXTERNAL-client error classifier, keyed by its\n     * {@link KeyedErrorClassifier.apiClass} (e.g. 'FirestoreAdminClient'). Consulted BEFORE the\n     * default tier for calls with that apiClass. Call ONCE at startup. 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 addErrorClassifier(keyed: KeyedErrorClassifier): void {\n        ClientRegistry.errorClassifiersByApiClass.set(keyed.apiClass, keyed.classifier);\n    }\n\n    /**\n     * The {@link CallOutcome} of a thrown API-call error. Resolved most-specific-first, and ALWAYS\n     * definitive:\n     *   1. the per-apiClass classifier, if one is registered for `methodInfo.apiClass` — unless it defers;\n     *   2. else the app default classifier — unless it defers;\n     *   3. else the webpieces built-in ({@link WEBPIECES_DEFAULT_ERROR_CLASSIFIER}), which never defers.\n     *\n     * The ONE verdict read by `RetryStrategy` (retry only TRANSIENT), `CallRegistry`'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 perClient = ClientRegistry.errorClassifiersByApiClass.get(methodInfo.apiClass);\n        if (perClient !== undefined) {\n            const verdict = perClient.classify(error, methodInfo);\n            if (verdict !== undefined) {\n                return verdict;\n            }\n        }\n        const verdict = ClientRegistry.appDefaultErrorClassifier.classify(error, methodInfo);\n        if (verdict !== undefined) {\n            return verdict;\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 RESTORES the webpieces defaults rather than emptying the pluggable slots, which is the whole\n     * reason it is not called `clear()` any more: `getErrorTranslator()` and the default error\n     * classifier are non-optional now, so \"cleared\" is not a state they have. A spec that wants\n     * webpieces' own behaviour back asks for exactly that.\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        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslator = WEBPIECES_DEFAULT_ERROR_TRANSLATOR;\n        ClientRegistry.appDefaultErrorClassifier = WEBPIECES_DEFAULT_ERROR_CLASSIFIER;\n        ClientRegistry.errorClassifiersByApiClass.clear();\n    }\n}\n"]}
+{"version":3,"file":"ClientRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ClientRegistry.ts"],"names":[],"mappings":"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","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 * Derives a base URL for a service name that has NO registered mapping — the pluggable half of\n * {@link ClientRegistry} resolution. One per environment, installed once at startup:\n *\n * - `gcpCloudRunDeriver()` (@webpieces/gcp-identity) — the Cloud Run formula, read from the metadata\n *   server. For code running ON GCP.\n * - `gcpCloudRunDeriver(new GcpCloudRunTarget(projectNumber, region))` — the SAME formula with the\n *   values supplied from config, for code running OFF GCP that still calls Cloud Run (a CLI, CI).\n * - {@link templateDeriver} (this package, browser-safe) — pure string substitution, for AWS or\n *   anything else with predictable DNS.\n * - none at all — a browser goes same-origin, and localhost/tests hand-register their mappings.\n */\nexport type ServiceUrlDeriver = (svcName: string) => Promise<string>;\n\n/**\n * ClientRegistry - the ONE place a `svcName` becomes a base URL, for every outbound client in every\n * environment. A client is built once but a URL is per-environment, so the URL belongs here rather\n * than on the client: clients carry ONLY a svcName.\n *\n * Resolution is one precedence chain, identical in the browser, in node, and in Cloud Tasks:\n *\n *   1. a registered mapping wins — the localhost port table, AWS, an external API, another region\n *      or project, a host that is not Cloud Run at all. Populated at startup from per-env config.\n *   2. else the installed {@link ServiceUrlDeriver}, if any — GCP's built-in, a DNS template, or\n *      your own. OPTIONAL on purpose: localhost is inherently a TABLE (helper-fsdb -> :8401,\n *      helper-portal -> :8201 have per-service ports), so explicit mappings must stay sufficient on\n *      their own.\n *   3. else the caller's fallback: the BROWSER goes relative (same origin — see\n *      {@link ClientRegistry.tryResolve}), while node THROWS (see {@link ClientRegistry.resolve}),\n *      because a server has no \"own origin\" and an unresolvable peer is a setup bug.\n *\n * Configured like {@link HeaderRegistry} / LogManager — populated once at startup, then globally\n * accessible with NO DI wiring. It is browser-safe (no `process.env`, no node-only deps), which is\n * why it lives in core-util rather than gcp-identity.\n *\n * A `svcName` should be the nx MODULE name of the service you are calling — that is the one name\n * `architecture:validate-runtime-architecture` can verify actually exists, so a typo or a rename\n * fails the build instead of failing in production. When the DEPLOYED name differs (an environment\n * prefix like `tf-`, or a Cloud Run service named unlike its module), translate it in ONE place —\n * the deriver below, or a `serviceName` alias in the module's project.json — never at the call site.\n *\n * ```ts\n * // startup, from the current environment's config:\n * ClientRegistry.addMapping('server2', 8202);                       // -> http://localhost:8202\n * ClientRegistry.addUrlMapping('email', 'https://email.other-region.example');\n * ClientRegistry.setDeriver(gcpCloudRunDeriver());                  // everything else, on GCP\n * ```\n */\nexport class ClientRegistry {\n    /** svcName -> resolved base URL. Process-global; populated at startup per environment. */\n    private static readonly mappings = new Map<string, string>();\n\n    /** The fallback for svcNames with no mapping. Undefined = no derivation in this environment. */\n    private static deriver: ServiceUrlDeriver | undefined;\n\n    /**\n     * The {@link ErrorTranslator} per {@link CallScope} — method -> API -> ALL, and below every rung\n     * {@link WEBPIECES_DEFAULT_ERROR_TRANSLATOR}, so {@link ClientRegistry.getErrorTranslator} is\n     * never undefined. Process-global, set once at startup on the SERVER and in the BROWSER — the\n     * same no-DI pattern as {@link ClientRegistry.mappings} above.\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 ClientRegistry.classify}.\n     */\n    private static readonly errorClassifiers = new CallScopeLadder<ClassifierSlot>(\n        () => new ClassifierSlot(),\n    );\n\n    /** Map a service name to `http://localhost:<port>`. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addMapping(svcName: string, port: number): void {\n        ClientRegistry.mappings.set(svcName, `http://localhost:${port}`);\n    }\n\n    /**\n     * Map a service name to an explicit base URL (any host / any environment).\n     *\n     * The EMPTY STRING is a legal, meaningful mapping: it makes the service relative, i.e.\n     * same-origin, because the client builds its URL as `${baseUrl}${route.path}`.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static addUrlMapping(svcName: string, url: string): void {\n        ClientRegistry.mappings.set(svcName, url);\n    }\n\n    /**\n     * Install the environment's {@link ServiceUrlDeriver} — how to resolve a svcName that has NO\n     * mapping. Optional: an environment that registers every svcName it calls needs none.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static setDeriver(fn: ServiceUrlDeriver): void {\n        ClientRegistry.deriver = fn;\n    }\n\n    /** The registered override for `svcName`, or undefined if none. Registry only — no derivation. */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryLookup(svcName: string): string | undefined {\n        return ClientRegistry.mappings.get(svcName);\n    }\n\n    /**\n     * Resolve `svcName` to its registered base URL. THROWS if the service was never registered.\n     * Registry only — it does NOT consult the deriver; prefer {@link ClientRegistry.resolve}.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static lookup(svcName: string): string {\n        const url = ClientRegistry.tryLookup(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL registered for service \"${svcName}\". Register it at startup: ` +\n                    `ClientRegistry.addMapping(svcName, port) for a localhost port, or ` +\n                    `ClientRegistry.addUrlMapping(svcName, url) for an explicit URL.`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Steps 1 + 2 of the chain: the registered mapping, else the installed deriver, else undefined.\n     * Non-throwing — the BROWSER uses this and treats undefined as \"\" (relative → same origin),\n     * which is what a browser app calling the backend it was served from wants by default.\n     *\n     * Note the `!== undefined` guard: an empty-string mapping is a legal answer (\"this service is\n     * same-origin\"), so it must NOT fall through to derivation.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static tryResolve(svcName: string): Promise<string | undefined> {\n        const override = ClientRegistry.tryLookup(svcName);\n        if (override !== undefined) {\n            return Promise.resolve(override);\n        }\n        if (!ClientRegistry.deriver) {\n            return Promise.resolve(undefined);\n        }\n        return ClientRegistry.deriver(svcName);\n    }\n\n    /**\n     * The full chain, with node's fallback: mapping, else deriver, else THROW. A server has no \"own\n     * origin\" to go relative to, so an unresolvable peer is a setup bug and must fail loudly — and\n     * say how to fix it.\n     */\n    // webpieces-disable no-function-outside-class -- static global singleton (like HeaderRegistry/LogManager); populated once at startup, never DI-injected\n    static async resolve(svcName: string): Promise<string> {\n        const url = await ClientRegistry.tryResolve(svcName);\n        if (url === undefined) {\n            throw new Error(\n                `No URL for service \"${svcName}\".\\n` +\n                    `  - localhost/AWS: ClientRegistry.addMapping('${svcName}', 8401)\\n` +\n                    `                or ClientRegistry.addUrlMapping('${svcName}', 'https://...')\\n` +\n                    `  - GCP: install a deriver — ClientRegistry.setDeriver(gcpCloudRunDeriver())\\n` +\n                    `  - deployed name differs from the module name (e.g. a 'tf-' prefix)? Translate it ONCE\\n` +\n                    `    in the deriver — setDeriver(s => gcpCloudRunDeriver()('tf-' + s)) — so every call\\n` +\n                    `    site keeps naming the MODULE, which architecture:validate-runtime-architecture checks`,\n            );\n        }\n        return url;\n    }\n\n    /**\n     * Install an {@link ErrorTranslator} for one {@link CallScope}: `'ALL'` (the app's translator,\n     * server side AND every client side), one contract CLASS, or one method of one contract. The\n     * scope is REQUIRED — there is no unscoped spelling. Call at startup, on the server AND in the\n     * browser, mirroring {@link ClientRegistry.addMapping}.\n     *\n     * ```ts\n     * ClientRegistry.setErrorTranslator(new AppErrorTranslator(), 'ALL');\n     * ClientRegistry.setErrorTranslator(new VendorErrorTranslator(), VendorApi);        // one contract\n     * ClientRegistry.setErrorTranslator(new LegacyErrorTranslator(), VendorApi, 'sync'); // one method\n     * ```\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 — exactly as before.\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        ClientRegistry.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 = ClientRegistry.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}: `'ALL'` (the app/company\n     * classifier — it reads {@link ApiMethodInfo.side}, so it covers the server router and every\n     * internal client), one contract CLASS (an SDK-wrapping api-client keys by its abstract `XxxApi`),\n     * or one method of one contract. The scope is REQUIRED. Call at startup, on the server AND in the\n     * 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        ClientRegistry.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), `CallRegistry`'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 = ClientRegistry.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. A spec that wants webpieces' own behaviour back asks for\n     * exactly that.\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        ClientRegistry.mappings.clear();\n        ClientRegistry.deriver = undefined;\n        ClientRegistry.errorTranslators.clear();\n        ClientRegistry.errorClassifiers.clear();\n    }\n}\n"]}

package/src/http/ErrorClassifier.d.ts

@@ -26,39 +26,32 @@ export declare enum CallOutcome {
  * rather than a bare function — so "find usages" in an IDE lands on every implementation.
  *
  * Registered on {@link ClientRegistry} at startup — the same browser-safe, no-DI, populated-once
- * singleton that owns URL mappings and the {@link ErrorTranslator}. Resolved most-specific first by
- * {@link ClientRegistry.classify}:
+ * singleton that owns URL mappings and the {@link ErrorTranslator} — with
+ * `ClientRegistry.setErrorClassifier(c, ...scope)`, on the same `CallScope` ladder as
+ * `CallRegistry`'s strategy and timeout. {@link ClientRegistry.classify} resolves it most specific
+ * first:
  *
- * 1. `ClientRegistry.addErrorClassifier(new KeyedErrorClassifier(apiClass, c))` — per EXTERNAL
- *    client, keyed by {@link ApiMethodInfo.apiClass} ('FirestoreAdminClient', 'ClaudeApi',
- *    'TwilioApi'). Each external API qualifies its errors differently (a Firestore 404 miss is
- *    EXPECTED; a Twilio 429 is TRANSIENT), so it overrides the tiers below for that apiClass only.
- * 2. `ClientRegistry.setDefaultErrorClassifier(c)` — ONE per app/company. It reads
- *    {@link ApiMethodInfo.side}, so a single classifier covers the SERVER router AND every INTERNAL
- *    client (webpieces http client, cloud tasks).
- * 3. {@link WebpiecesDefaultErrorClassifier} — the terminal tier, which never defers.
+ * 1. `setErrorClassifier(c, XxxApi, 'method')` — one method of one contract.
+ * 2. `setErrorClassifier(c, XxxApi)` — one contract, keyed by its CLASS (never a name). An
+ *    SDK-wrapping api-client keys by its abstract `XxxApi`: each external API qualifies its errors
+ *    differently (a document store's 404 miss is EXPECTED; a messaging vendor's 429 is TRANSIENT),
+ *    so it overrides the rungs below for that contract only.
+ * 3. `setErrorClassifier(c, 'ALL')` — ONE per app/company. It reads {@link ApiMethodInfo.side}, so a
+ *    single classifier covers the SERVER router AND every INTERNAL client (webpieces http client,
+ *    cloud tasks).
+ * 4. {@link WebpiecesDefaultErrorClassifier} — the terminal rung, which never defers.
  *
- * Internal clients and the server register NOTHING — the ABSENCE of an apiClass entry is the signal.
- * An external client that forgets to register is FAIL-SAFE: it falls to the tiers below, where every
- * client-side error except a 266 is a failure.
+ * Internal clients and the server register NOTHING per contract — the ABSENCE of a contract rung is
+ * the signal. An external client that forgets to register is FAIL-SAFE: it falls to the rungs below,
+ * where every client-side error except a 266 is a failure.
  */
 export interface ErrorClassifier {
     /**
      * @param error - the already-normalized thrown error (callers pass `toError(err)`)
-     * @param methodInfo - the call identity; `side` distinguishes server/client, `apiClass` the client
-     * @returns the outcome, or `undefined` to DEFER to the next tier (a per-apiClass classifier defers
-     *   to the app default; the app default defers to the webpieces built-in). Deferring is what
-     *   makes classifiers additive AND override-capable.
+     * @param methodInfo - the call identity; `side` distinguishes server/client, `contract` the API
+     * @returns the outcome, or `undefined` to DEFER to the next rung (method defers to API, API to
+     *   ALL, ALL to the webpieces built-in). Deferring is what makes classifiers additive AND
+     *   override-capable.
      */
     classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome | undefined;
 }
-/**
- * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the
- * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),
- * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.
- */
-export declare class KeyedErrorClassifier {
-    readonly apiClass: string;
-    readonly classifier: ErrorClassifier;
-    constructor(apiClass: string, classifier: ErrorClassifier);
-}

package/src/http/ErrorClassifier.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeyedErrorClassifier = exports.CallOutcome = void 0;
+exports.CallOutcome = void 0;
 /**
  * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table
  * answering "is this error expected, and is it worth repeating?":
@@ -22,18 +22,4 @@ var CallOutcome;
     /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */
     CallOutcome["FAILURE"] = "failure";
 })(CallOutcome || (exports.CallOutcome = CallOutcome = {}));
-/**
- * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the
- * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),
- * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.
- */
-class KeyedErrorClassifier {
-    apiClass;
-    classifier;
-    constructor(apiClass, classifier) {
-        this.apiClass = apiClass;
-        this.classifier = classifier;
-    }
-}
-exports.KeyedErrorClassifier = KeyedErrorClassifier;
 //# sourceMappingURL=ErrorClassifier.js.map

package/src/http/ErrorClassifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"ErrorClassifier.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorClassifier.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,IAAY,WAOX;AAPD,WAAY,WAAW;IACnB,qGAAqG;IACrG,oCAAqB,CAAA;IACrB,qGAAqG;IACrG,8CAA+B,CAAA;IAC/B,6GAA6G;IAC7G,kCAAmB,CAAA;AACvB,CAAC,EAPW,WAAW,2BAAX,WAAW,QAOtB;AAoCD;;;;GAIG;AACH,MAAa,oBAAoB;IAET;IACA;IAFpB,YACoB,QAAgB,EAChB,UAA2B;QAD3B,aAAQ,GAAR,QAAQ,CAAQ;QAChB,eAAU,GAAV,UAAU,CAAiB;IAC5C,CAAC;CACP;AALD,oDAKC","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table\n * answering \"is this error expected, and is it worth repeating?\":\n *\n * - `RetryStrategy` retries only {@link CallOutcome.TRANSIENT_FAILURE} (and only on a `READ` /\n *   `WRITE_IDEMPOTENT` endpoint — the ENDPOINT's safety is `CallContext.operation`'s question, never\n *   the classifier's);\n * - `LogApiCall` logs {@link CallOutcome.EXPECTED} as `[API-*-resp-OTHER]` (`result='success'`) and\n *   both failure outcomes as `[API-*-resp-FAIL]` (`result='failure'`);\n * - the MCP tool-call renderer derives its model-visible `retry` advice from the outcome plus the\n *   endpoint's operation.\n */\nexport enum CallOutcome {\n    /** It threw, but things are WORKING: a 266, a server-side 4xx, an external client's \"404 = miss\". */\n    EXPECTED = 'expected',\n    /** Broken NOW, may work if repeated: unavailable, connection, timeouts, 429/backoff, bad-gateway. */\n    TRANSIENT_FAILURE = 'transient',\n    /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */\n    FAILURE = 'failure',\n}\n\n/**\n * Classifies a thrown API-call error into a {@link CallOutcome}.\n *\n * This is BEHAVIOR, so it is an interface (per CLAUDE.md), passed as an object with a NAMED method\n * rather than a bare function — so \"find usages\" in an IDE lands on every implementation.\n *\n * Registered on {@link ClientRegistry} at startup — the same browser-safe, no-DI, populated-once\n * singleton that owns URL mappings and the {@link ErrorTranslator}. Resolved most-specific first by\n * {@link ClientRegistry.classify}:\n *\n * 1. `ClientRegistry.addErrorClassifier(new KeyedErrorClassifier(apiClass, c))` — per EXTERNAL\n *    client, keyed by {@link ApiMethodInfo.apiClass} ('FirestoreAdminClient', 'ClaudeApi',\n *    'TwilioApi'). Each external API qualifies its errors differently (a Firestore 404 miss is\n *    EXPECTED; a Twilio 429 is TRANSIENT), so it overrides the tiers below for that apiClass only.\n * 2. `ClientRegistry.setDefaultErrorClassifier(c)` — ONE per app/company. It reads\n *    {@link ApiMethodInfo.side}, so a single classifier covers the SERVER router AND every INTERNAL\n *    client (webpieces http client, cloud tasks).\n * 3. {@link WebpiecesDefaultErrorClassifier} — the terminal tier, which never defers.\n *\n * Internal clients and the server register NOTHING — the ABSENCE of an apiClass entry is the signal.\n * An external client that forgets to register is FAIL-SAFE: it falls to the tiers below, where every\n * client-side error except a 266 is a failure.\n */\nexport interface ErrorClassifier {\n    /**\n     * @param error - the already-normalized thrown error (callers pass `toError(err)`)\n     * @param methodInfo - the call identity; `side` distinguishes server/client, `apiClass` the client\n     * @returns the outcome, or `undefined` to DEFER to the next tier (a per-apiClass classifier defers\n     *   to the app default; the app default defers to the webpieces built-in). Deferring is what\n     *   makes classifiers additive AND override-capable.\n     */\n    classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome | undefined;\n}\n\n/**\n * A per-external-client registration pair: the {@link ApiMethodInfo.apiClass} to key on, and the\n * {@link ErrorClassifier} to apply for it. Data only, so it is a class (not an inline object literal),\n * per CLAUDE.md — handed to {@link ClientRegistry.addErrorClassifier}.\n */\nexport class KeyedErrorClassifier {\n    constructor(\n        public readonly apiClass: string,\n        public readonly classifier: ErrorClassifier,\n    ) {}\n}\n"]}
+{"version":3,"file":"ErrorClassifier.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/ErrorClassifier.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;GAWG;AACH,IAAY,WAOX;AAPD,WAAY,WAAW;IACnB,qGAAqG;IACrG,oCAAqB,CAAA;IACrB,qGAAqG;IACrG,8CAA+B,CAAA;IAC/B,6GAA6G;IAC7G,kCAAmB,CAAA;AACvB,CAAC,EAPW,WAAW,2BAAX,WAAW,QAOtB","sourcesContent":["import { ApiMethodInfo } from './ApiMethodInfo';\n\n/**\n * The ONE verdict on a thrown API-call error. Three readers share it, so there is exactly one table\n * answering \"is this error expected, and is it worth repeating?\":\n *\n * - `RetryStrategy` retries only {@link CallOutcome.TRANSIENT_FAILURE} (and only on a `READ` /\n *   `WRITE_IDEMPOTENT` endpoint — the ENDPOINT's safety is `CallContext.operation`'s question, never\n *   the classifier's);\n * - `LogApiCall` logs {@link CallOutcome.EXPECTED} as `[API-*-resp-OTHER]` (`result='success'`) and\n *   both failure outcomes as `[API-*-resp-FAIL]` (`result='failure'`);\n * - the MCP tool-call renderer derives its model-visible `retry` advice from the outcome plus the\n *   endpoint's operation.\n */\nexport enum CallOutcome {\n    /** It threw, but things are WORKING: a 266, a server-side 4xx, an external client's \"404 = miss\". */\n    EXPECTED = 'expected',\n    /** Broken NOW, may work if repeated: unavailable, connection, timeouts, 429/backoff, bad-gateway. */\n    TRANSIENT_FAILURE = 'transient',\n    /** Broken, and repeating will not help: a RECEIVED 4xx (our bug), implementation, 501, retries exhausted. */\n    FAILURE = 'failure',\n}\n\n/**\n * Classifies a thrown API-call error into a {@link CallOutcome}.\n *\n * This is BEHAVIOR, so it is an interface (per CLAUDE.md), passed as an object with a NAMED method\n * rather than a bare function — so \"find usages\" in an IDE lands on every implementation.\n *\n * Registered on {@link ClientRegistry} at startup — the same browser-safe, no-DI, populated-once\n * singleton that owns URL mappings and the {@link ErrorTranslator} — with\n * `ClientRegistry.setErrorClassifier(c, ...scope)`, on the same `CallScope` ladder as\n * `CallRegistry`'s strategy and timeout. {@link ClientRegistry.classify} resolves it most specific\n * first:\n *\n * 1. `setErrorClassifier(c, XxxApi, 'method')` — one method of one contract.\n * 2. `setErrorClassifier(c, XxxApi)` — one contract, keyed by its CLASS (never a name). An\n *    SDK-wrapping api-client keys by its abstract `XxxApi`: each external API qualifies its errors\n *    differently (a document store's 404 miss is EXPECTED; a messaging vendor's 429 is TRANSIENT),\n *    so it overrides the rungs below for that contract only.\n * 3. `setErrorClassifier(c, 'ALL')` — ONE per app/company. It reads {@link ApiMethodInfo.side}, so a\n *    single classifier covers the SERVER router AND every INTERNAL client (webpieces http client,\n *    cloud tasks).\n * 4. {@link WebpiecesDefaultErrorClassifier} — the terminal rung, which never defers.\n *\n * Internal clients and the server register NOTHING per contract — the ABSENCE of a contract rung is\n * the signal. An external client that forgets to register is FAIL-SAFE: it falls to the rungs below,\n * where every client-side error except a 266 is a failure.\n */\nexport interface ErrorClassifier {\n    /**\n     * @param error - the already-normalized thrown error (callers pass `toError(err)`)\n     * @param methodInfo - the call identity; `side` distinguishes server/client, `contract` the API\n     * @returns the outcome, or `undefined` to DEFER to the next rung (method defers to API, API to\n     *   ALL, ALL to the webpieces built-in). Deferring is what makes classifiers additive AND\n     *   override-capable.\n     */\n    classify(error: Error, methodInfo: ApiMethodInfo): CallOutcome | undefined;\n}\n\n"]}

package/src/http/ErrorLadderCompileAssertions.d.ts

@@ -0,0 +1 @@
+export {};