@webpieces/core-util 0.4.956 → 0.4.957

package/package.json

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

package/src/http/ApiMethodInfo.d.ts

@@ -48,12 +48,26 @@ export declare class ApiMethodInfo {
      *  whole call identity travels together. webpieces itself does not act on it; an app's upgrade
      *  logic does. Default false. */
     readonly allowUpgradeInFlight: boolean;
+    /**
+     * The contract CLASS (the `@ApiPath` contract, or an SDK-wrapping api-client's abstract
+     * `XxxApi`) — the key {@link ClientRegistry.classify} resolves the `CallScope` ladder on
+     * (method -> API -> ALL). {@link apiClass} stays the LOGGED name. REQUIRED as a constructor
+     * argument so every caller states it: an SDK-wrapping client passes its abstract `XxxApi`, and
+     * only a call with no contract class at all (an IPC hop, an MCP protocol step) passes an explicit
+     * `undefined`, which reaches only the ALL rung.
+     *
+     * NON-enumerable on purpose: this object is nested into every `[API-*]` log record as
+     * `jsonPayload.api.method`, and a class reference is not log data.
+     */
+    readonly contract: Function | undefined;
     constructor(side: ApiSide, 
     /** REQUIRED — the API CONTRACT class name (e.g. 'SaveApi'). Matches client + server so both
      *  sides of one logical call filter together via `jsonPayload.api.method.apiClass`. */
     apiClass: string, 
     /** REQUIRED — the method on the contract (e.g. 'save'). */
     methodName: string, 
+    /** REQUIRED — the contract CLASS, or explicit `undefined`; see {@link ApiMethodInfo.contract}. */
+    contract: Function | undefined, 
     /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no
      *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */
     controllerName?: string | undefined, 

package/src/http/ApiMethodInfo.js

@@ -34,6 +34,8 @@ class ApiMethodInfo {
     apiClass, 
     /** REQUIRED — the method on the contract (e.g. 'save'). */
     methodName, 
+    /** REQUIRED — the contract CLASS, or explicit `undefined`; see {@link ApiMethodInfo.contract}. */
+    contract, 
     /** OPTIONAL — server-side impl class (e.g. 'SaveController'). Absent on clients, which have no
      *  impl. Surfaces as `jsonPayload.api.method.controllerName` for server-only drill-down. */
     controllerName, 
@@ -64,6 +66,7 @@ class ApiMethodInfo {
         this.noLogging = noLogging;
         this.hideProgress = hideProgress;
         this.allowUpgradeInFlight = allowUpgradeInFlight;
+        Object.defineProperty(this, 'contract', { value: contract, enumerable: false });
     }
 }
 exports.ApiMethodInfo = ApiMethodInfo;

package/src/http/ApiMethodInfo.js.map

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

package/src/http/CallRegistry.d.ts

@@ -1,11 +1,6 @@
 import { Attempt, CallContext, CallStrategy } from './CallStrategy';
 import { TransportDefault } from './TransportDefault';
-/**
- * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method
- * of one contract. Exported so other per-call registries (e.g. cloudtasks-client's `GcpTaskRegistry`)
- * scope their settings with the SAME ladder.
- */
-export type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];
+import { CallScope } from './CallScope';
 /**
  * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,
  * every transport calls {@link CallRegistry.execute}.
@@ -22,14 +17,15 @@ export type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];
  * retries a `WRITE`, even registered at ALL.
  */
 export declare class CallRegistry {
-    private static all;
-    private static readonly apis;
+    private static readonly ladder;
     static setTimeout(timeoutMs: number | undefined, ...scope: CallScope): void;
     static setStrategy(strategy: CallStrategy<unknown> | undefined, ...scope: CallScope): void;
     /**
      * Run one call under its registered policy. `context` names the method (its `methodName` selects
      * the per-method policy) and carries the endpoint's declared operation, so the SAME context a
-     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.
+     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`. The context
+     * a strategy sees always carries `api` as its {@link CallContext.contract}, so the error
+     * classification inside a strategy resolves on the same ladder.
      *
      * Every attempt is wrapped so a retried TRANSIENT failure logs one
      * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).
@@ -43,5 +39,4 @@ export declare class CallRegistry {
      */
     static resolveTimeout(api: Function, methodName: string, defaultMs: number): number;
     static clear(): void;
-    private static policy;
 }

package/src/http/CallRegistry.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CallRegistry = void 0;
+const CallStrategy_1 = require("./CallStrategy");
 const CallDeadline_1 = require("./CallDeadline");
 const ClientRegistry_1 = require("./ClientRegistry");
 const ErrorClassifier_1 = require("./ErrorClassifier");
@@ -8,6 +9,7 @@ const ApiMethodInfo_1 = require("./ApiMethodInfo");
 const LogManager_1 = require("../logging/LogManager");
 const ApiCallLogName_1 = require("./ApiCallLogName");
 const errorUtils_1 = require("../lib/errorUtils");
+const CallScope_1 = require("./CallScope");
 // The same logger LogApiCall writes its [API-*] lines to, so an attempt line sits beside the final one.
 const log = LogManager_1.LogManager.getLogger(ApiCallLogName_1.LOG_API_CALL_LOGGER_NAME);
 class CallPolicy {
@@ -15,10 +17,6 @@ class CallPolicy {
     // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs
     strategy;
 }
-class ApiCallPolicies {
-    policy = new CallPolicy();
-    methods = new Map();
-}
 /**
  * Counts the attempts of ONE call and logs each retried TRANSIENT failure. It wraps the attempt
  * BEFORE any strategy sees it, so an app-written strategy gets the same lines as `RetryStrategy`.
@@ -48,7 +46,7 @@ class LoggedAttempts {
         }
         catch (err) {
             const error = (0, errorUtils_1.toError)(err);
-            const methodInfo = new ApiMethodInfo_1.ApiMethodInfo('client', this.context.apiName, this.context.methodName);
+            const methodInfo = new ApiMethodInfo_1.ApiMethodInfo('client', this.context.apiName, this.context.methodName, this.context.contract);
             this.pendingTransient =
                 ClientRegistry_1.ClientRegistry.classify(error, methodInfo) === ErrorClassifier_1.CallOutcome.TRANSIENT_FAILURE
                     ? error
@@ -82,43 +80,46 @@ class LoggedAttempts {
  * retries a `WRITE`, even registered at ALL.
  */
 class CallRegistry {
-    static all = new CallPolicy();
-    static apis = new Map();
+    static ladder = new CallScope_1.CallScopeLadder(() => new CallPolicy());
     // webpieces-disable no-function-outside-class -- process-global startup registry
     static setTimeout(timeoutMs, ...scope) {
         if (timeoutMs !== undefined)
             CallDeadline_1.CallDeadline.validate(timeoutMs);
-        CallRegistry.policy(scope[0], scope[1]).timeoutMs = timeoutMs;
+        CallRegistry.ladder.at(...scope).timeoutMs = timeoutMs;
     }
     // webpieces-disable no-function-outside-class -- process-global startup registry
     static setStrategy(
     // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs
     strategy, ...scope) {
-        CallRegistry.policy(scope[0], scope[1]).strategy = strategy;
+        CallRegistry.ladder.at(...scope).strategy = strategy;
     }
     /**
      * Run one call under its registered policy. `context` names the method (its `methodName` selects
      * the per-method policy) and carries the endpoint's declared operation, so the SAME context a
-     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.
+     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`. The context
+     * a strategy sees always carries `api` as its {@link CallContext.contract}, so the error
+     * classification inside a strategy resolves on the same ladder.
      *
      * Every attempt is wrapped so a retried TRANSIENT failure logs one
      * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).
      */
     // webpieces-disable no-function-outside-class -- transport-independent policy execution
     static async execute(api, context, attempt, fallback) {
-        const logged = new LoggedAttempts(context, attempt).run;
-        const policies = CallRegistry.apis.get(api);
-        const method = policies?.methods.get(context.methodName);
-        const strategy = method?.strategy ?? policies?.policy.strategy ?? CallRegistry.all.strategy;
+        const scoped = context.contract === api
+            ? context
+            : new CallStrategy_1.CallContext(context.apiName, context.methodName, context.operation, api);
+        const logged = new LoggedAttempts(scoped, attempt).run;
+        const rungs = CallRegistry.ladder.rungs(api, scoped.methodName);
+        const strategy = rungs.find((p) => p.strategy !== undefined)?.strategy;
         if (strategy !== undefined) {
-            return (await strategy(logged, context));
+            return (await strategy(logged, scoped));
         }
-        const timeoutMs = method?.timeoutMs ?? policies?.policy.timeoutMs ?? CallRegistry.all.timeoutMs;
+        const timeoutMs = rungs.find((p) => p.timeoutMs !== undefined)?.timeoutMs;
         if (timeoutMs !== undefined) {
             return logged(timeoutMs);
         }
         if (fallback.strategy !== undefined) {
-            return (await fallback.strategy(logged, context));
+            return (await fallback.strategy(logged, scoped));
         }
         return logged(fallback.timeoutMs);
     }
@@ -130,35 +131,12 @@ class CallRegistry {
      */
     // webpieces-disable no-function-outside-class -- process-global registry lookup
     static resolveTimeout(api, methodName, defaultMs) {
-        const policies = CallRegistry.apis.get(api);
-        return (policies?.methods.get(methodName)?.timeoutMs ??
-            policies?.policy.timeoutMs ??
-            CallRegistry.all.timeoutMs ??
-            defaultMs);
+        const rungs = CallRegistry.ladder.rungs(api, methodName);
+        return rungs.find((p) => p.timeoutMs !== undefined)?.timeoutMs ?? defaultMs;
     }
     // webpieces-disable no-function-outside-class -- process-global registry reset for tests
     static clear() {
-        CallRegistry.all = new CallPolicy();
-        CallRegistry.apis.clear();
-    }
-    // webpieces-disable no-function-outside-class -- process-global registry storage
-    static policy(api, methodName) {
-        if (api === 'ALL') {
-            return CallRegistry.all;
-        }
-        let policies = CallRegistry.apis.get(api);
-        if (!policies) {
-            policies = new ApiCallPolicies();
-            CallRegistry.apis.set(api, policies);
-        }
-        if (methodName === undefined)
-            return policies.policy;
-        let policy = policies.methods.get(methodName);
-        if (!policy) {
-            policy = new CallPolicy();
-            policies.methods.set(methodName, policy);
-        }
-        return policy;
+        CallRegistry.ladder.clear();
     }
 }
 exports.CallRegistry = CallRegistry;

package/src/http/CallRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { Attempt, CallContext, CallStrategy } from './CallStrategy';\nimport { CallDeadline } from './CallDeadline';\nimport { TransportDefault } from './TransportDefault';\nimport { ClientRegistry } from './ClientRegistry';\nimport { CallOutcome } from './ErrorClassifier';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { LogManager } from '../logging/LogManager';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { toError } from '../lib/errorUtils';\n\n// The same logger LogApiCall writes its [API-*] lines to, so an attempt line sits beside the final one.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\n/**\n * Where a policy applies: every contract (`'ALL'`, which has no method), one contract, or one method\n * of one contract. Exported so other per-call registries (e.g. cloudtasks-client's `GcpTaskRegistry`)\n * scope their settings with the SAME ladder.\n */\nexport type CallScope = [api: 'ALL'] | [api: Function, methodName?: string];\n\nclass CallPolicy {\n    timeoutMs?: number;\n    // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs\n    strategy?: CallStrategy<unknown>;\n}\n\nclass ApiCallPolicies {\n    readonly policy = new CallPolicy();\n    readonly methods = new Map<string, CallPolicy>();\n}\n\n/**\n * Counts the attempts of ONE call and logs each retried TRANSIENT failure. It wraps the attempt\n * BEFORE any strategy sees it, so an app-written strategy gets the same lines as `RetryStrategy`.\n *\n * The line for attempt N is written when attempt N+1 STARTS — i.e. only for an attempt that was\n * actually retried. The last attempt's failure is what escapes, and `LogApiCall`'s final\n * `[API-client-resp-FAIL]` line covers it, so a call that gave up after 4 attempts logs 3 attempt\n * lines and 1 FAIL line, never the last failure twice. An EXPECTED or FAILURE attempt is not logged\n * here either; the final line covers it.\n */\nclass LoggedAttempts<T> {\n    private attempts = 0;\n    private pendingTransient?: Error;\n\n    constructor(\n        private readonly context: CallContext,\n        private readonly attempt: Attempt<T>,\n    ) {}\n\n    readonly run: Attempt<T> = async (timeoutMs: number): Promise<T> => {\n        this.flushRetried();\n        this.attempts += 1;\n        // webpieces-disable no-unmanaged-exceptions -- observe the attempt's failure, rethrow it unchanged\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.attempt(timeoutMs);\n        } catch (err: unknown) {\n            const error = toError(err);\n            const methodInfo = new ApiMethodInfo('client', this.context.apiName, this.context.methodName);\n            this.pendingTransient =\n                ClientRegistry.classify(error, methodInfo) === CallOutcome.TRANSIENT_FAILURE\n                    ? error\n                    : undefined;\n            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the attempt's own failure unchanged\n            throw err;\n        }\n    };\n\n    private flushRetried(): void {\n        const error = this.pendingTransient;\n        if (error === undefined) return;\n        this.pendingTransient = undefined;\n        log.warn(\n            `[API-client-attempt-TRANSIENT] ${this.context.apiName}.${this.context.methodName} ` +\n                `attempt ${this.attempts} errorType=${error.constructor.name} error=${error.message}`,\n        );\n    }\n}\n\n/**\n * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,\n * every transport calls {@link CallRegistry.execute}.\n *\n * Ladder: strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.\n * Otherwise timeout method -> API -> ALL. Otherwise the transport's {@link TransportDefault} (its\n * timeout, and its strategy if it has one). A registered TIMEOUT is therefore a decision for a single\n * attempt and also replaces a transport's default strategy; to keep retrying with a different attempt\n * deadline, register a `RetryStrategy` instead.\n *\n * RPC has no default retry (only the application knows whether repeating a POST is safe); Cloud Tasks\n * enqueue does (see `TransportDefault`). An app opts RPC in with\n * `CallRegistry.setStrategy(new RetryStrategy(...).run, CatalogApi)` — and `RetryStrategy` never\n * retries a `WRITE`, even registered at ALL.\n */\nexport class CallRegistry {\n    private static all = new CallPolicy();\n    private static readonly apis = new Map<Function, ApiCallPolicies>();\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setTimeout(timeoutMs: number | undefined, ...scope: CallScope): void {\n        if (timeoutMs !== undefined) CallDeadline.validate(timeoutMs);\n        CallRegistry.policy(scope[0], scope[1]).timeoutMs = timeoutMs;\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setStrategy(\n        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n        strategy: CallStrategy<unknown> | undefined,\n        ...scope: CallScope\n    ): void {\n        CallRegistry.policy(scope[0], scope[1]).strategy = strategy;\n    }\n\n    /**\n     * Run one call under its registered policy. `context` names the method (its `methodName` selects\n     * the per-method policy) and carries the endpoint's declared operation, so the SAME context a\n     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`.\n     *\n     * Every attempt is wrapped so a retried TRANSIENT failure logs one\n     * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).\n     */\n    // webpieces-disable no-function-outside-class -- transport-independent policy execution\n    static async execute<T>(\n        api: Function,\n        context: CallContext,\n        attempt: Attempt<T>,\n        fallback: TransportDefault,\n    ): Promise<T> {\n        const logged = new LoggedAttempts<T>(context, attempt).run;\n        const policies = CallRegistry.apis.get(api);\n        const method = policies?.methods.get(context.methodName);\n        const strategy = method?.strategy ?? policies?.policy.strategy ?? CallRegistry.all.strategy;\n        if (strategy !== undefined) {\n            return (await strategy(logged, context)) as T;\n        }\n        const timeoutMs = method?.timeoutMs ?? policies?.policy.timeoutMs ?? CallRegistry.all.timeoutMs;\n        if (timeoutMs !== undefined) {\n            return logged(timeoutMs);\n        }\n        if (fallback.strategy !== undefined) {\n            return (await fallback.strategy(logged, context)) as T;\n        }\n        return logged(fallback.timeoutMs);\n    }\n\n    /**\n     * The registered TIMEOUT for a call — method -> API -> ALL -> `defaultMs` — ignoring every\n     * strategy. For a transport that hands timing to someone else for this call (Cloud Tasks enqueue\n     * with caller-supplied gax `CallOptions`) and still needs ONE safety cap so a hung channel cannot\n     * block forever. Raise it with {@link CallRegistry.setTimeout}.\n     */\n    // webpieces-disable no-function-outside-class -- process-global registry lookup\n    static resolveTimeout(api: Function, methodName: string, defaultMs: number): number {\n        const policies = CallRegistry.apis.get(api);\n        return (\n            policies?.methods.get(methodName)?.timeoutMs ??\n            policies?.policy.timeoutMs ??\n            CallRegistry.all.timeoutMs ??\n            defaultMs\n        );\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry reset for tests\n    static clear(): void {\n        CallRegistry.all = new CallPolicy();\n        CallRegistry.apis.clear();\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry storage\n    private static policy(api: Function | 'ALL', methodName?: string): CallPolicy {\n        if (api === 'ALL') {\n            return CallRegistry.all;\n        }\n        let policies = CallRegistry.apis.get(api);\n        if (!policies) {\n            policies = new ApiCallPolicies();\n            CallRegistry.apis.set(api, policies);\n        }\n        if (methodName === undefined) return policies.policy;\n        let policy = policies.methods.get(methodName);\n        if (!policy) {\n            policy = new CallPolicy();\n            policies.methods.set(methodName, policy);\n        }\n        return policy;\n    }\n}\n"]}
+{"version":3,"file":"CallRegistry.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistry.ts"],"names":[],"mappings":"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","sourcesContent":["import { Attempt, CallContext, CallStrategy } from './CallStrategy';\nimport { CallDeadline } from './CallDeadline';\nimport { TransportDefault } from './TransportDefault';\nimport { ClientRegistry } from './ClientRegistry';\nimport { CallOutcome } from './ErrorClassifier';\nimport { ApiMethodInfo } from './ApiMethodInfo';\nimport { LogManager } from '../logging/LogManager';\nimport { LOG_API_CALL_LOGGER_NAME } from './ApiCallLogName';\nimport { toError } from '../lib/errorUtils';\nimport { CallScope, CallScopeLadder } from './CallScope';\n\n// The same logger LogApiCall writes its [API-*] lines to, so an attempt line sits beside the final one.\nconst log = LogManager.getLogger(LOG_API_CALL_LOGGER_NAME);\n\nclass CallPolicy {\n    timeoutMs?: number;\n    // webpieces-disable no-any-unknown -- global policy spans heterogeneous response DTOs\n    strategy?: CallStrategy<unknown>;\n}\n\n/**\n * Counts the attempts of ONE call and logs each retried TRANSIENT failure. It wraps the attempt\n * BEFORE any strategy sees it, so an app-written strategy gets the same lines as `RetryStrategy`.\n *\n * The line for attempt N is written when attempt N+1 STARTS — i.e. only for an attempt that was\n * actually retried. The last attempt's failure is what escapes, and `LogApiCall`'s final\n * `[API-client-resp-FAIL]` line covers it, so a call that gave up after 4 attempts logs 3 attempt\n * lines and 1 FAIL line, never the last failure twice. An EXPECTED or FAILURE attempt is not logged\n * here either; the final line covers it.\n */\nclass LoggedAttempts<T> {\n    private attempts = 0;\n    private pendingTransient?: Error;\n\n    constructor(\n        private readonly context: CallContext,\n        private readonly attempt: Attempt<T>,\n    ) {}\n\n    readonly run: Attempt<T> = async (timeoutMs: number): Promise<T> => {\n        this.flushRetried();\n        this.attempts += 1;\n        // webpieces-disable no-unmanaged-exceptions -- observe the attempt's failure, rethrow it unchanged\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return await this.attempt(timeoutMs);\n        } catch (err: unknown) {\n            const error = toError(err);\n            const methodInfo = new ApiMethodInfo(\n                'client',\n                this.context.apiName,\n                this.context.methodName,\n                this.context.contract,\n            );\n            this.pendingTransient =\n                ClientRegistry.classify(error, methodInfo) === CallOutcome.TRANSIENT_FAILURE\n                    ? error\n                    : undefined;\n            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions -- rethrows the attempt's own failure unchanged\n            throw err;\n        }\n    };\n\n    private flushRetried(): void {\n        const error = this.pendingTransient;\n        if (error === undefined) return;\n        this.pendingTransient = undefined;\n        log.warn(\n            `[API-client-attempt-TRANSIENT] ${this.context.apiName}.${this.context.methodName} ` +\n                `attempt ${this.attempts} errorType=${error.constructor.name} error=${error.message}`,\n        );\n    }\n}\n\n/**\n * Shared startup registry for browser RPC, node RPC, and Cloud Tasks ENQUEUE — ONE implementation,\n * every transport calls {@link CallRegistry.execute}.\n *\n * Ladder: strategy method -> API -> ALL first; ANY strategy replaces the ENTIRE timeout ladder.\n * Otherwise timeout method -> API -> ALL. Otherwise the transport's {@link TransportDefault} (its\n * timeout, and its strategy if it has one). A registered TIMEOUT is therefore a decision for a single\n * attempt and also replaces a transport's default strategy; to keep retrying with a different attempt\n * deadline, register a `RetryStrategy` instead.\n *\n * RPC has no default retry (only the application knows whether repeating a POST is safe); Cloud Tasks\n * enqueue does (see `TransportDefault`). An app opts RPC in with\n * `CallRegistry.setStrategy(new RetryStrategy(...).run, CatalogApi)` — and `RetryStrategy` never\n * retries a `WRITE`, even registered at ALL.\n */\nexport class CallRegistry {\n    private static readonly ladder = new CallScopeLadder<CallPolicy>(() => new CallPolicy());\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setTimeout(timeoutMs: number | undefined, ...scope: CallScope): void {\n        if (timeoutMs !== undefined) CallDeadline.validate(timeoutMs);\n        CallRegistry.ladder.at(...scope).timeoutMs = timeoutMs;\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global startup registry\n    static setStrategy(\n        // webpieces-disable no-any-unknown -- registry strategies span heterogeneous response DTOs\n        strategy: CallStrategy<unknown> | undefined,\n        ...scope: CallScope\n    ): void {\n        CallRegistry.ladder.at(...scope).strategy = strategy;\n    }\n\n    /**\n     * Run one call under its registered policy. `context` names the method (its `methodName` selects\n     * the per-method policy) and carries the endpoint's declared operation, so the SAME context a\n     * strategy sees is the one the transport's deadline puts on an `ApiCallTimeoutError`. The context\n     * a strategy sees always carries `api` as its {@link CallContext.contract}, so the error\n     * classification inside a strategy resolves on the same ladder.\n     *\n     * Every attempt is wrapped so a retried TRANSIENT failure logs one\n     * `WARN [API-client-attempt-TRANSIENT]` line (see {@link LoggedAttempts}).\n     */\n    // webpieces-disable no-function-outside-class -- transport-independent policy execution\n    static async execute<T>(\n        api: Function,\n        context: CallContext,\n        attempt: Attempt<T>,\n        fallback: TransportDefault,\n    ): Promise<T> {\n        const scoped =\n            context.contract === api\n                ? context\n                : new CallContext(context.apiName, context.methodName, context.operation, api);\n        const logged = new LoggedAttempts<T>(scoped, attempt).run;\n        const rungs = CallRegistry.ladder.rungs(api, scoped.methodName);\n        const strategy = rungs.find((p: CallPolicy) => p.strategy !== undefined)?.strategy;\n        if (strategy !== undefined) {\n            return (await strategy(logged, scoped)) as T;\n        }\n        const timeoutMs = rungs.find((p: CallPolicy) => p.timeoutMs !== undefined)?.timeoutMs;\n        if (timeoutMs !== undefined) {\n            return logged(timeoutMs);\n        }\n        if (fallback.strategy !== undefined) {\n            return (await fallback.strategy(logged, scoped)) as T;\n        }\n        return logged(fallback.timeoutMs);\n    }\n\n    /**\n     * The registered TIMEOUT for a call — method -> API -> ALL -> `defaultMs` — ignoring every\n     * strategy. For a transport that hands timing to someone else for this call (Cloud Tasks enqueue\n     * with caller-supplied gax `CallOptions`) and still needs ONE safety cap so a hung channel cannot\n     * block forever. Raise it with {@link CallRegistry.setTimeout}.\n     */\n    // webpieces-disable no-function-outside-class -- process-global registry lookup\n    static resolveTimeout(api: Function, methodName: string, defaultMs: number): number {\n        const rungs = CallRegistry.ladder.rungs(api, methodName);\n        return rungs.find((p: CallPolicy) => p.timeoutMs !== undefined)?.timeoutMs ?? defaultMs;\n    }\n\n    // webpieces-disable no-function-outside-class -- process-global registry reset for tests\n    static clear(): void {\n        CallRegistry.ladder.clear();\n    }\n}\n"]}

package/src/http/CallRegistryCompileAssertions.js

@@ -13,7 +13,7 @@ class CallRegistryCompileAssertions {
     }
     /** The transport fallback is a TransportDefault (timeout + optional strategy), never a bare number. */
     fallbackIsATransportDefault() {
-        const context = new CallStrategy_1.CallContext('Api', 'work', HttpEndpointOptions_1.WRITE);
+        const context = new CallStrategy_1.CallContext('Api', 'work', HttpEndpointOptions_1.WRITE, undefined);
         void CallRegistry_1.CallRegistry.execute(CallRegistryCompileAssertions, context, (ms) => Promise.resolve(ms), 
         // @ts-expect-error execute(..., defaultMs: number) became execute(..., fallback: TransportDefault)
         30_000);

package/src/http/CallRegistryCompileAssertions.js.map

@@ -1 +1 @@
-{"version":3,"file":"CallRegistryCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistryCompileAssertions.ts"],"names":[],"mappings":";;AAAA,iDAA8C;AAC9C,iDAA6C;AAC7C,+DAA8C;AAE9C,4DAA4D;AAC5D,MAAM,6BAA6B;IAC/B,KAAK;QACD,8CAA8C;QAC9C,2BAAY,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC5C,8CAA8C;QAC9C,2BAAY,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,uGAAuG;IACvG,2BAA2B;QACvB,MAAM,OAAO,GAAG,IAAI,0BAAW,CAAC,KAAK,EAAE,MAAM,EAAE,2BAAK,CAAC,CAAC;QACtD,KAAK,2BAAY,CAAC,OAAO,CACrB,6BAA6B,EAC7B,OAAO,EACP,CAAC,EAAU,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,mGAAmG;QACnG,MAAM,CACT,CAAC;IACN,CAAC;CACJ","sourcesContent":["import { CallRegistry } from './CallRegistry';\nimport { CallContext } from './CallStrategy';\nimport { WRITE } from './HttpEndpointOptions';\n\n/** Compiled by tsc (spec files are not), never executed. */\nclass CallRegistryCompileAssertions {\n    check(): void {\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setTimeout(100, 'ALL', 'work');\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setStrategy(undefined, 'ALL', 'work');\n    }\n\n    /** The transport fallback is a TransportDefault (timeout + optional strategy), never a bare number. */\n    fallbackIsATransportDefault(): void {\n        const context = new CallContext('Api', 'work', WRITE);\n        void CallRegistry.execute(\n            CallRegistryCompileAssertions,\n            context,\n            (ms: number) => Promise.resolve(ms),\n            // @ts-expect-error execute(..., defaultMs: number) became execute(..., fallback: TransportDefault)\n            30_000,\n        );\n    }\n}\n"]}
+{"version":3,"file":"CallRegistryCompileAssertions.js","sourceRoot":"","sources":["../../../../../../packages/core/core-util/src/http/CallRegistryCompileAssertions.ts"],"names":[],"mappings":";;AAAA,iDAA8C;AAC9C,iDAA6C;AAC7C,+DAA8C;AAE9C,4DAA4D;AAC5D,MAAM,6BAA6B;IAC/B,KAAK;QACD,8CAA8C;QAC9C,2BAAY,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAC5C,8CAA8C;QAC9C,2BAAY,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,uGAAuG;IACvG,2BAA2B;QACvB,MAAM,OAAO,GAAG,IAAI,0BAAW,CAAC,KAAK,EAAE,MAAM,EAAE,2BAAK,EAAE,SAAS,CAAC,CAAC;QACjE,KAAK,2BAAY,CAAC,OAAO,CACrB,6BAA6B,EAC7B,OAAO,EACP,CAAC,EAAU,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,mGAAmG;QACnG,MAAM,CACT,CAAC;IACN,CAAC;CACJ","sourcesContent":["import { CallRegistry } from './CallRegistry';\nimport { CallContext } from './CallStrategy';\nimport { WRITE } from './HttpEndpointOptions';\n\n/** Compiled by tsc (spec files are not), never executed. */\nclass CallRegistryCompileAssertions {\n    check(): void {\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setTimeout(100, 'ALL', 'work');\n        // @ts-expect-error ALL cannot select a method\n        CallRegistry.setStrategy(undefined, 'ALL', 'work');\n    }\n\n    /** The transport fallback is a TransportDefault (timeout + optional strategy), never a bare number. */\n    fallbackIsATransportDefault(): void {\n        const context = new CallContext('Api', 'work', WRITE, undefined);\n        void CallRegistry.execute(\n            CallRegistryCompileAssertions,\n            context,\n            (ms: number) => Promise.resolve(ms),\n            // @ts-expect-error execute(..., defaultMs: number) became execute(..., fallback: TransportDefault)\n            30_000,\n        );\n    }\n}\n"]}

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"]}