@webpieces/core-util 0.4.956 → 0.4.958

package/src/http/CallScope.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * Every per-call startup registry scopes its settings with this ONE ladder: `CallRegistry`
+ * (strategy, timeout), `ClientRegistry` (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];
+/**
+ * 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
+ * rung's slot holds and how a rung "answers" (first value present, or first verdict that does not
+ * defer).
+ */
+export declare class CallScopeLadder<T> {
+    private readonly create;
+    private all;
+    private readonly apis;
+    constructor(create: () => T);
+    /** The slot for `scope`, created on first use. Registries write their setting into it. */
+    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 call with no contract class — an IPC hop, an MCP protocol
+     * step, a failure before routing) reaches only the ALL rung.
+     */
+    rungs(api: Function | undefined, methodName: string | undefined): T[];
+    clear(): void;
+}

package/src/http/CallScope.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallScopeLadder = void 0;
+class ApiRungs {
+    api;
+    methods = new Map();
+}
+/**
+ * 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
+ * rung's slot holds and how a rung "answers" (first value present, or first verdict that does not
+ * defer).
+ */
+class CallScopeLadder {
+    create;
+    all;
+    apis = new Map();
+    constructor(create) {
+        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') {
+            if (this.all === undefined)
+                this.all = this.create();
+            return this.all;
+        }
+        let rungs = this.apis.get(api);
+        if (!rungs) {
+            rungs = new ApiRungs();
+            this.apis.set(api, rungs);
+        }
+        const methodName = scope[1];
+        if (methodName === undefined) {
+            if (rungs.api === undefined)
+                rungs.api = this.create();
+            return rungs.api;
+        }
+        let slot = rungs.methods.get(methodName);
+        if (slot === undefined) {
+            slot = this.create();
+            rungs.methods.set(methodName, slot);
+        }
+        return slot;
+    }
+    /**
+     * The registered slots for one call, most specific first: method, then API, then ALL. A rung with
+     * no slot is skipped. `api` undefined (a call with no contract class — an IPC hop, an MCP protocol
+     * step, a failure before routing) reaches only the ALL rung.
+     */
+    rungs(api, methodName) {
+        const found = [];
+        const rungs = api === undefined ? undefined : this.apis.get(api);
+        const method = methodName === undefined ? undefined : rungs?.methods.get(methodName);
+        if (method !== undefined)
+            found.push(method);
+        if (rungs?.api !== undefined)
+            found.push(rungs.api);
+        if (this.all !== undefined)
+            found.push(this.all);
+        return found;
+    }
+    clear() {
+        this.all = undefined;
+        this.apis.clear();
+    }
+}
+exports.CallScopeLadder = CallScopeLadder;
+//# sourceMappingURL=CallScope.js.map

package/src/http/CallScope.js.map

@@ -0,0 +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 call with no contract class — an IPC hop, an MCP protocol\n     * step, a failure before routing) 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

@@ -14,7 +14,19 @@ export declare class CallContext {
     readonly apiName: string;
     readonly methodName: string;
     readonly operation: EndpointOperation;
-    constructor(apiName: string, methodName: string, operation: EndpointOperation);
+    /**
+     * The contract CLASS the call belongs to — the key of the `CallScope` ladder, so a strategy's
+     * per-attempt error classification resolves the classifier registered for THIS contract.
+     * `CallRegistry.execute` guarantees it on the context a strategy sees; undefined only for a
+     * transport with no contract class (an IPC deadline), which reaches the ALL rung alone.
+     *
+     * NON-enumerable on purpose: this context rides on `ApiCallTimeoutError`, which is logged and
+     * compared as data, and a class reference is not data.
+     */
+    readonly contract: Function | undefined;
+    constructor(apiName: string, methodName: string, operation: EndpointOperation, 
+    /** REQUIRED — the contract CLASS, or explicit `undefined`; see {@link CallContext.contract}. */
+    contract: Function | undefined);
 }
 /** Owns all timing and retry decisions. No public cancellation signal. */
 export type CallStrategy<T> = (call: Attempt<T>, ctx: CallContext) => Promise<T>;

package/src/http/CallStrategy.js

@@ -14,10 +14,13 @@ class CallContext {
     apiName;
     methodName;
     operation;
-    constructor(apiName, methodName, operation) {
+    constructor(apiName, methodName, operation, 
+    /** REQUIRED — the contract CLASS, or explicit `undefined`; see {@link CallContext.contract}. */
+    contract) {
         this.apiName = apiName;
         this.methodName = methodName;
         this.operation = operation;
+        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });
     }
 }
 exports.CallContext = CallContext;

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;IAEA;IACA;IACA;IAHpB,YACoB,OAAe,EACf,UAAkB,EAClB,SAA4B;QAF5B,YAAO,GAAP,OAAO,CAAQ;QACf,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAmB;IAC7C,CAAC;CACP;AAND,kCAMC","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    constructor(\n        public readonly apiName: string,\n        public readonly methodName: string,\n        public readonly operation: EndpointOperation,\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;IAaA;IACA;IACA;IAHpB,YACoB,OAAe,EACf,UAAkB,EAClB,SAA4B;IAC5C,gGAAgG;IAChG,QAA8B;QAJd,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;AArBD,kCAqBC","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     * `CallRegistry.execute` guarantees it on the context a strategy sees; undefined only for a\n     * transport with no contract class (an IPC deadline), which reaches the ALL rung alone.\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 | undefined;\n\n    constructor(\n        public readonly apiName: string,\n        public readonly methodName: string,\n        public readonly operation: EndpointOperation,\n        /** REQUIRED — the contract CLASS, or explicit `undefined`; see {@link CallContext.contract}. */\n        contract: Function | undefined,\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"]}

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;