@cyanheads/pubmed-mcp-server 2.10.18 → 2.10.19

package/dist/services/error-contracts.d.ts

@@ -1,17 +1,22 @@
 /**
- * @fileoverview Canonical error contracts. Single source of truth for the
- * failure modes services throw and tools declare in `errors[]`, plus the
- * input rejections shared by the tools that forward a free-text query
- * upstream.
+ * @fileoverview Canonical error contracts: the failure modes the NCBI, Europe
+ * PMC, and OpenAlex services throw and tools declare in `errors[]`, plus the
+ * input rejections some tools raise before any upstream call. Unpaywall has no
+ * array here: its one caller, `pubmed_fetch_fulltext`, catches every Unpaywall
+ * failure and reports it as a tier outcome, so no Unpaywall reason reaches a
+ * caller as an error.
  *
- * Service-layer code can't reach `ctx.recoveryFor` (no Context), so it spreads
- * `recoveryFor(reason)` from this module into the error factory's `data` arg.
- * The framework mirrors `data.recovery.hint` into the wire payload's
- * `content[]` text, so clients get the same actionable hint they would from a
- * handler-level `ctx.fail`.
+ * Service-layer code stamps `data: { reason }` on its throws, adding its own
+ * `data.recovery` only where the hint depends on runtime detail. When a failure
+ * with no hint of its own reaches a tool or resource that declares the reason,
+ * the framework fills that entry's `recovery` in as `data.recovery.hint` — the
+ * same hint a handler-level `ctx.fail` gets. A tool's error also renders the
+ * hint as a `Recovery:` line in its `content[]` text (dropped when the message
+ * already contains it); a resource's carries it only in the JSON-RPC error's
+ * `data`.
  *
- * Tool definitions import the contract arrays directly and spread them into
- * their `errors: [...]` declarations to surface the failure modes to the LLM.
+ * Definitions import the contract arrays directly and spread them into their
+ * `errors: [...]` declarations to surface the failure modes to the LLM.
  * Every service-array entry carries `thrownBy: 'service'` so the linter's
  * `error-contract-unthrown` check skips it while still checking the handler's
  * own reasons. Spread a service array only into a tool whose handler lets that
@@ -36,15 +41,22 @@ export declare const NCBI_SERVICE_ERRORS: readonly [{
 }, {
     readonly reason: 'ncbi_unreachable';
     readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: 'NCBI E-utilities is unreachable after all retry attempts.';
-    readonly recovery: 'Retry after a brief delay; NCBI was unreachable across all retry attempts.';
+    readonly when: 'NCBI E-utilities failed on every attempt the retry budget allowed — retries ran out, or the next backoff would overrun the total deadline.';
+    readonly recovery: 'Retry after a brief delay; NCBI failed on every attempt this call made.';
+    readonly retryable: true;
+    readonly thrownBy: 'service';
+}, {
+    readonly reason: 'ncbi_rate_limited';
+    readonly code: JsonRpcErrorCode.RateLimited;
+    readonly when: 'NCBI answered HTTP 429 (too many requests) and the call stopped on it — retries ran out, the next backoff would overrun the total deadline, or the Retry-After NCBI named outlasts the time left or the 30-second backoff cap.';
+    readonly recovery: "Wait as long as `retryAfter` says when present (a number of seconds or an HTTP date), otherwise a few seconds, then retry; NCBI is throttling this server's requests. If the server runs without NCBI_API_KEY, setting it raises the E-utilities ceiling from about 3 to about 10 requests per second and shortens the default gap between requests — an operator setting in the server's environment, not a tool input.";
     readonly retryable: true;
     readonly thrownBy: 'service';
 }, {
     readonly reason: 'ncbi_deadline_exceeded';
     readonly code: JsonRpcErrorCode.Timeout;
-    readonly when: 'Total request deadline expired before NCBI returned a response.';
-    readonly recovery: 'Reduce batch size or retry; NCBI may be under temporary load.';
+    readonly when: 'The total NCBI request deadline expired before NCBI answered successfully — mid-request, while queued, or during a retry backoff.';
+    readonly recovery: 'Retry after a brief delay; NCBI may be under temporary load. For a large batch, split it into smaller calls.';
     readonly retryable: true;
     readonly thrownBy: 'service';
 }, {
@@ -63,32 +75,30 @@ export declare const NCBI_SERVICE_ERRORS: readonly [{
     readonly thrownBy: 'service';
 }];
 /**
- * Input failure the NCBI query tools reject before any call is made. Declared
- * here rather than inside `NCBI_SERVICE_ERRORS` so only the tools that actually
- * throw it advertise it — a tool that takes no free-text query can never
- * produce it, and declaring it there would advertise a failure mode that
- * cannot happen.
+ * Input failure the free-text query tools reject before any call is made —
+ * the NCBI query tools and `pubmed_europepmc_search` alike. Declared here
+ * rather than inside a service array so only the tools that actually throw it
+ * advertise it — a tool that takes no free-text query can never produce it,
+ * and declaring it there would advertise a failure mode that cannot happen.
  *
  * Unlike the service arrays in this module, this one is thrown from a tool
- * handler via `ctx.fail('blank_query', …)`, so its recovery hint resolves
- * through `ctx.recoveryFor` and it stays out of {@link ServiceErrorReason}.
+ * handler via `ctx.fail('blank_query', …)`, so its entry carries no `thrownBy`.
  */
-export declare const NCBI_QUERY_INPUT_ERRORS: readonly [{
+export declare const QUERY_INPUT_ERRORS: readonly [{
     readonly reason: 'blank_query';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: 'The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there.';
-    readonly recovery: 'Supply a nonblank search term — a bare field tag or empty parentheses carry none; NCBI cannot search a blank term and retrying the same input will not help.';
+    readonly when: 'The query contains no search term: nothing is left once whitespace and invisible characters such as a zero-width space are disregarded. pubmed_search_articles and pubmed_europepmc_search first decode HTML entities and also disregard markup and parentheses, so `()`, `<b></b>`, and `&nbsp;` hold no term there; pubmed_search_articles also disregards bracketed field tags such as `[pdat]`.';
+    readonly recovery: 'Supply a nonblank search term; retrying the same blank input will not help.';
     readonly retryable: false;
 }];
 /**
  * Input failure the identifier-conversion path rejects before any call is made.
- * Separate from {@link NCBI_QUERY_INPUT_ERRORS} for the same reason that array
+ * Separate from {@link QUERY_INPUT_ERRORS} for the same reason that array
  * is separate from the service contracts: only a tool that takes caller-supplied
  * identifiers can produce it.
  *
- * Thrown from a tool handler via `ctx.fail('malformed_id', …)`, so its recovery
- * hint resolves through `ctx.recoveryFor` and it stays out of
- * {@link ServiceErrorReason}.
+ * Thrown from a tool handler via `ctx.fail('malformed_id', …)`, so its entry
+ * carries no `thrownBy`.
  */
 export declare const NCBI_ID_INPUT_ERRORS: readonly [{
     readonly reason: 'malformed_id';
@@ -97,21 +107,6 @@ export declare const NCBI_ID_INPUT_ERRORS: readonly [{
     readonly recovery: 'Submit one identifier per `ids` element, in the declared idType format; the same packed value will be rejected again.';
     readonly retryable: false;
 }];
-/**
- * Failure modes the Unpaywall service layer can surface. A tool whose handler
- * lets `getUnpaywallService()` failures propagate spreads these into its
- * `errors[]`. None does today: `pubmed_fetch_fulltext`, the only consumer,
- * folds every Unpaywall failure into its tier chain, so the entries serve the
- * service's own `recoveryFor` hints.
- */
-export declare const UNPAYWALL_SERVICE_ERRORS: readonly [{
-    readonly reason: 'unpaywall_unreachable';
-    readonly code: JsonRpcErrorCode.ServiceUnavailable;
-    readonly when: 'Unpaywall was unreachable when resolving a DOI or fetching content.';
-    readonly recovery: 'Retry after a brief delay; Unpaywall was unreachable. The PMC source remains the primary path.';
-    readonly retryable: true;
-    readonly thrownBy: 'service';
-}];
 /**
  * Failure modes the OpenAlex service layer can surface. Tools whose handler
  * lets `getOpenAlexService()` / `getOpenAlexServiceOptional()` failures
@@ -126,7 +121,7 @@ export declare const OPENALEX_SERVICE_ERRORS: readonly [{
     readonly thrownBy: 'service';
 }, {
     readonly reason: 'openalex_invalid_response';
-    readonly code: JsonRpcErrorCode.SerializationError;
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
     readonly when: 'OpenAlex returned a body that could not be parsed (invalid JSON).';
     readonly recovery: 'Retry the request; OpenAlex returned a malformed response that could not be parsed.';
     readonly retryable: true;
@@ -154,33 +149,9 @@ export declare const EUROPEPMC_SERVICE_ERRORS: readonly [{
 }, {
     readonly reason: 'europepmc_invalid_input';
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: 'Europe PMC rejected the request input — an error message such as an empty query, an empty response to a sort with an undocumented field or no asc/desc direction, or an empty response to a pagination cursor on every attempt.';
-    readonly recovery: 'Adjust the input — the query, the sort, or the cursorMark — before retrying; the same input will be rejected again.';
+    readonly when: 'Europe PMC rejected the request input — an error message in place of results, an empty response to a sort with an undocumented field or no asc/desc direction, or a pagination cursor it cannot read (an empty response on the last attempt the retry budget allows, or a second HTTP 503 when the first page of the same query is served).';
+    readonly recovery: "Fix the rejected input before retrying — the query, the sort, or the cursorMark (pass the previous response's `nextCursorMark` verbatim, or `*` to restart); the same input will most likely be rejected again.";
     readonly retryable: false;
     readonly thrownBy: 'service';
 }];
-/**
- * Reason identifier union for type-safe authoring on the service layer.
- * Tool handlers get a tighter typed union from `ctx.fail` / `ctx.recoveryFor`
- * via the framework — this is the service-side fallback.
- */
-export type ServiceErrorReason = (typeof NCBI_SERVICE_ERRORS)[number]['reason'] | (typeof UNPAYWALL_SERVICE_ERRORS)[number]['reason'] | (typeof EUROPEPMC_SERVICE_ERRORS)[number]['reason'] | (typeof OPENALEX_SERVICE_ERRORS)[number]['reason'];
-/**
- * Service-layer counterpart to `ctx.recoveryFor`. Returns `{ recovery: { hint } }`
- * for the contract reason. Use at every service throw that stamps a `reason` so
- * the wire payload carries the same actionable hint the LLM gets from
- * handler-level `ctx.fail`.
- *
- * The parameter is constrained to `ServiceErrorReason`, so typos fail at compile
- * time. The runtime guard catches the impossible case where the reason union
- * and the recovery map drift apart in future edits.
- *
- * @example
- *   throw serviceUnavailable(msg, { reason: 'ncbi_unreachable', ...recoveryFor('ncbi_unreachable') });
- */
-export declare function recoveryFor(reason: ServiceErrorReason): {
-    recovery: {
-        hint: string;
-    };
-};
 //# sourceMappingURL=error-contracts.d.ts.map

package/dist/services/error-contracts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-contracts.d.ts","sourceRoot":"","sources":["../../src/services/error-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error-contracts.d.ts","sourceRoot":"","sources":["../../src/services/error-contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;aAE5B,MAAM,EAAE,YAAY;aACpB,IAAI;aACJ,IAAI,EAAE,gLAAgL;aACtL,QAAQ,EACN,iIAAiI;aACnI,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,kBAAkB;aAC1B,IAAI;aACJ,IAAI,EAAE,4IAA4I;aAClJ,QAAQ,EAAE,yEAAyE;aACnF,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,mBAAmB;aAC3B,IAAI;aACJ,IAAI,EAAE,gOAAgO;aACtO,QAAQ,EACN,0ZAA0Z;aAC5Z,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,wBAAwB;aAChC,IAAI;aACJ,IAAI,EAAE,mIAAmI;aACzI,QAAQ,EACN,8GAA8G;aAChH,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,uBAAuB;aAC/B,IAAI;aACJ,IAAI,EAAE,mEAAmE;aACzE,QAAQ,EAAE,iFAAiF;aAC3F,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,yBAAyB;aACjC,IAAI;aACJ,IAAI,EAAE,uEAAuE;aAC7E,QAAQ,EACN,gGAAgG;aAClG,SAAS;aACT,QAAQ,EAAE,SAAS;EAEb,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB;aAE3B,MAAM,EAAE,aAAa;aACrB,IAAI;aACJ,IAAI,EAAE,qYAAqY;aAC3Y,QAAQ,EAAE,6EAA6E;aACvF,SAAS;EAEH,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;aAE7B,MAAM,EAAE,cAAc;aACtB,IAAI;aACJ,IAAI,EAAE,0LAA0L;aAChM,QAAQ,EACN,uHAAuH;aACzH,SAAS;EAEH,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;aAEhC,MAAM,EAAE,sBAAsB;aAC9B,IAAI;aACJ,IAAI,EAAE,oDAAoD;aAC1D,QAAQ,EACN,4FAA4F;aAC9F,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,2BAA2B;aACnC,IAAI;aACJ,IAAI,EAAE,mEAAmE;aACzE,QAAQ,EAAE,qFAAqF;aAC/F,SAAS;aACT,QAAQ,EAAE,SAAS;EAEb,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;aAEjC,MAAM,EAAE,uBAAuB;aAC/B,IAAI;aACJ,IAAI,EAAE,qKAAqK;aAC3K,QAAQ,EACN,iGAAiG;aACnG,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,4BAA4B;aACpC,IAAI;aACJ,IAAI,EAAE,4EAA4E;aAClF,QAAQ,EACN,uFAAuF;aACzF,SAAS;aACT,QAAQ,EAAE,SAAS;;aAGnB,MAAM,EAAE,yBAAyB;aACjC,IAAI;aACJ,IAAI,EAAE,6UAA6U;aACnV,QAAQ,EACN,iNAAiN;aACnN,SAAS;aACT,QAAQ,EAAE,SAAS;EAEb,CAAC"}

package/dist/services/error-contracts.js

@@ -1,17 +1,22 @@
 /**
- * @fileoverview Canonical error contracts. Single source of truth for the
- * failure modes services throw and tools declare in `errors[]`, plus the
- * input rejections shared by the tools that forward a free-text query
- * upstream.
+ * @fileoverview Canonical error contracts: the failure modes the NCBI, Europe
+ * PMC, and OpenAlex services throw and tools declare in `errors[]`, plus the
+ * input rejections some tools raise before any upstream call. Unpaywall has no
+ * array here: its one caller, `pubmed_fetch_fulltext`, catches every Unpaywall
+ * failure and reports it as a tier outcome, so no Unpaywall reason reaches a
+ * caller as an error.
  *
- * Service-layer code can't reach `ctx.recoveryFor` (no Context), so it spreads
- * `recoveryFor(reason)` from this module into the error factory's `data` arg.
- * The framework mirrors `data.recovery.hint` into the wire payload's
- * `content[]` text, so clients get the same actionable hint they would from a
- * handler-level `ctx.fail`.
+ * Service-layer code stamps `data: { reason }` on its throws, adding its own
+ * `data.recovery` only where the hint depends on runtime detail. When a failure
+ * with no hint of its own reaches a tool or resource that declares the reason,
+ * the framework fills that entry's `recovery` in as `data.recovery.hint` — the
+ * same hint a handler-level `ctx.fail` gets. A tool's error also renders the
+ * hint as a `Recovery:` line in its `content[]` text (dropped when the message
+ * already contains it); a resource's carries it only in the JSON-RPC error's
+ * `data`.
  *
- * Tool definitions import the contract arrays directly and spread them into
- * their `errors: [...]` declarations to surface the failure modes to the LLM.
+ * Definitions import the contract arrays directly and spread them into their
+ * `errors: [...]` declarations to surface the failure modes to the LLM.
  * Every service-array entry carries `thrownBy: 'service'` so the linter's
  * `error-contract-unthrown` check skips it while still checking the handler's
  * own reasons. Spread a service array only into a tool whose handler lets that
@@ -38,16 +43,24 @@ export const NCBI_SERVICE_ERRORS = [
     {
         reason: 'ncbi_unreachable',
         code: JsonRpcErrorCode.ServiceUnavailable,
-        when: 'NCBI E-utilities is unreachable after all retry attempts.',
-        recovery: 'Retry after a brief delay; NCBI was unreachable across all retry attempts.',
+        when: 'NCBI E-utilities failed on every attempt the retry budget allowed — retries ran out, or the next backoff would overrun the total deadline.',
+        recovery: 'Retry after a brief delay; NCBI failed on every attempt this call made.',
+        retryable: true,
+        thrownBy: 'service',
+    },
+    {
+        reason: 'ncbi_rate_limited',
+        code: JsonRpcErrorCode.RateLimited,
+        when: 'NCBI answered HTTP 429 (too many requests) and the call stopped on it — retries ran out, the next backoff would overrun the total deadline, or the Retry-After NCBI named outlasts the time left or the 30-second backoff cap.',
+        recovery: "Wait as long as `retryAfter` says when present (a number of seconds or an HTTP date), otherwise a few seconds, then retry; NCBI is throttling this server's requests. If the server runs without NCBI_API_KEY, setting it raises the E-utilities ceiling from about 3 to about 10 requests per second and shortens the default gap between requests — an operator setting in the server's environment, not a tool input.",
         retryable: true,
         thrownBy: 'service',
     },
     {
         reason: 'ncbi_deadline_exceeded',
         code: JsonRpcErrorCode.Timeout,
-        when: 'Total request deadline expired before NCBI returned a response.',
-        recovery: 'Reduce batch size or retry; NCBI may be under temporary load.',
+        when: 'The total NCBI request deadline expired before NCBI answered successfully — mid-request, while queued, or during a retry backoff.',
+        recovery: 'Retry after a brief delay; NCBI may be under temporary load. For a large batch, split it into smaller calls.',
         retryable: true,
         thrownBy: 'service',
     },
@@ -69,34 +82,32 @@ export const NCBI_SERVICE_ERRORS = [
     },
 ];
 /**
- * Input failure the NCBI query tools reject before any call is made. Declared
- * here rather than inside `NCBI_SERVICE_ERRORS` so only the tools that actually
- * throw it advertise it — a tool that takes no free-text query can never
- * produce it, and declaring it there would advertise a failure mode that
- * cannot happen.
+ * Input failure the free-text query tools reject before any call is made —
+ * the NCBI query tools and `pubmed_europepmc_search` alike. Declared here
+ * rather than inside a service array so only the tools that actually throw it
+ * advertise it — a tool that takes no free-text query can never produce it,
+ * and declaring it there would advertise a failure mode that cannot happen.
  *
  * Unlike the service arrays in this module, this one is thrown from a tool
- * handler via `ctx.fail('blank_query', …)`, so its recovery hint resolves
- * through `ctx.recoveryFor` and it stays out of {@link ServiceErrorReason}.
+ * handler via `ctx.fail('blank_query', …)`, so its entry carries no `thrownBy`.
  */
-export const NCBI_QUERY_INPUT_ERRORS = [
+export const QUERY_INPUT_ERRORS = [
     {
         reason: 'blank_query',
         code: JsonRpcErrorCode.ValidationError,
-        when: 'The query holds no search term once whitespace, and anything the tool strips before searching, are removed — so NCBI would receive a blank term. pubmed_search_articles strips markup, bracketed field tags, and parentheses, so a bare field tag such as `[pdat]` or empty parentheses `()` count as blank there.',
-        recovery: 'Supply a nonblank search term — a bare field tag or empty parentheses carry none; NCBI cannot search a blank term and retrying the same input will not help.',
+        when: 'The query contains no search term: nothing is left once whitespace and invisible characters such as a zero-width space are disregarded. pubmed_search_articles and pubmed_europepmc_search first decode HTML entities and also disregard markup and parentheses, so `()`, `<b></b>`, and `&nbsp;` hold no term there; pubmed_search_articles also disregards bracketed field tags such as `[pdat]`.',
+        recovery: 'Supply a nonblank search term; retrying the same blank input will not help.',
         retryable: false,
     },
 ];
 /**
  * Input failure the identifier-conversion path rejects before any call is made.
- * Separate from {@link NCBI_QUERY_INPUT_ERRORS} for the same reason that array
+ * Separate from {@link QUERY_INPUT_ERRORS} for the same reason that array
  * is separate from the service contracts: only a tool that takes caller-supplied
  * identifiers can produce it.
  *
- * Thrown from a tool handler via `ctx.fail('malformed_id', …)`, so its recovery
- * hint resolves through `ctx.recoveryFor` and it stays out of
- * {@link ServiceErrorReason}.
+ * Thrown from a tool handler via `ctx.fail('malformed_id', …)`, so its entry
+ * carries no `thrownBy`.
  */
 export const NCBI_ID_INPUT_ERRORS = [
     {
@@ -107,23 +118,6 @@ export const NCBI_ID_INPUT_ERRORS = [
         retryable: false,
     },
 ];
-/**
- * Failure modes the Unpaywall service layer can surface. A tool whose handler
- * lets `getUnpaywallService()` failures propagate spreads these into its
- * `errors[]`. None does today: `pubmed_fetch_fulltext`, the only consumer,
- * folds every Unpaywall failure into its tier chain, so the entries serve the
- * service's own `recoveryFor` hints.
- */
-export const UNPAYWALL_SERVICE_ERRORS = [
-    {
-        reason: 'unpaywall_unreachable',
-        code: JsonRpcErrorCode.ServiceUnavailable,
-        when: 'Unpaywall was unreachable when resolving a DOI or fetching content.',
-        recovery: 'Retry after a brief delay; Unpaywall was unreachable. The PMC source remains the primary path.',
-        retryable: true,
-        thrownBy: 'service',
-    },
-];
 /**
  * Failure modes the OpenAlex service layer can surface. Tools whose handler
  * lets `getOpenAlexService()` / `getOpenAlexServiceOptional()` failures
@@ -140,7 +134,7 @@ export const OPENALEX_SERVICE_ERRORS = [
     },
     {
         reason: 'openalex_invalid_response',
-        code: JsonRpcErrorCode.SerializationError,
+        code: JsonRpcErrorCode.ServiceUnavailable,
         when: 'OpenAlex returned a body that could not be parsed (invalid JSON).',
         recovery: 'Retry the request; OpenAlex returned a malformed response that could not be parsed.',
         retryable: true,
@@ -172,36 +166,10 @@ export const EUROPEPMC_SERVICE_ERRORS = [
     {
         reason: 'europepmc_invalid_input',
         code: JsonRpcErrorCode.ValidationError,
-        when: 'Europe PMC rejected the request input — an error message such as an empty query, an empty response to a sort with an undocumented field or no asc/desc direction, or an empty response to a pagination cursor on every attempt.',
-        recovery: 'Adjust the input — the query, the sort, or the cursorMark — before retrying; the same input will be rejected again.',
+        when: 'Europe PMC rejected the request input — an error message in place of results, an empty response to a sort with an undocumented field or no asc/desc direction, or a pagination cursor it cannot read (an empty response on the last attempt the retry budget allows, or a second HTTP 503 when the first page of the same query is served).',
+        recovery: "Fix the rejected input before retrying — the query, the sort, or the cursorMark (pass the previous response's `nextCursorMark` verbatim, or `*` to restart); the same input will most likely be rejected again.",
         retryable: false,
         thrownBy: 'service',
     },
 ];
-const REASON_TO_RECOVERY = new Map([
-    ...NCBI_SERVICE_ERRORS,
-    ...UNPAYWALL_SERVICE_ERRORS,
-    ...EUROPEPMC_SERVICE_ERRORS,
-    ...OPENALEX_SERVICE_ERRORS,
-].map((entry) => [entry.reason, entry.recovery]));
-/**
- * Service-layer counterpart to `ctx.recoveryFor`. Returns `{ recovery: { hint } }`
- * for the contract reason. Use at every service throw that stamps a `reason` so
- * the wire payload carries the same actionable hint the LLM gets from
- * handler-level `ctx.fail`.
- *
- * The parameter is constrained to `ServiceErrorReason`, so typos fail at compile
- * time. The runtime guard catches the impossible case where the reason union
- * and the recovery map drift apart in future edits.
- *
- * @example
- *   throw serviceUnavailable(msg, { reason: 'ncbi_unreachable', ...recoveryFor('ncbi_unreachable') });
- */
-export function recoveryFor(reason) {
-    const hint = REASON_TO_RECOVERY.get(reason);
-    if (hint === undefined) {
-        throw new Error(`recoveryFor: no recovery hint registered for reason "${reason}"`);
-    }
-    return { recovery: { hint } };
-}
 //# sourceMappingURL=error-contracts.js.map

package/dist/services/error-contracts.js.map

@@ -1 +1 @@
-{"version":3,"file":"error-contracts.js","sourceRoot":"","sources":["../../src/services/error-contracts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"error-contracts.js","sourceRoot":"","sources":["../../src/services/error-contracts.ts"],"names":[],"mappings":"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"}

package/dist/services/europe-pmc/api-client.d.ts

@@ -45,8 +45,8 @@ export declare class EuropePmcApiClient {
      * query is HTTP 200 with `hitCount: 0`. A 404 is reclassified from its
      * status-mapped `NotFound` to `ServiceUnavailable` so the service retries it.
      * A retryable 5xx keeps its code, so a 504 stays `Timeout`. Only a failure
-     * that ends up `ServiceUnavailable` carries `europepmc_unreachable` and its
-     * recovery hint, the one code that reason is declared for. An upstream
+     * that ends up `ServiceUnavailable` carries `europepmc_unreachable`, the one
+     * code that reason is declared for. An upstream
      * `retryAfter` is kept. A 429 and every other 4xx pass through unchanged, as
      * does a 501, whose `data.retryable: false` keeps it out of the retry loop.
      * (#152)
@@ -84,6 +84,12 @@ export declare class EuropePmcApiClient {
  * optional source filter. EPMC's query syntax supports `SRC:"X"` field tokens —
  * the requested sources are OR-joined into a parenthesized clause and ANDed
  * with the caller's query.
+ *
+ * A single source is repeated (`SRC:"MED" OR SRC:"MED"`). Europe PMC matches
+ * nothing when a query is exactly one `EXT_ID` clause ANDed with one `SRC`
+ * clause and either value is quoted; the repeated clause matches quoted and
+ * unquoted `EXT_ID` alike and returns the same total as a lone clause for any
+ * other query. Multi-source clauses are sent as they are. (#175)
  */
 export declare function buildSearchQuery(params: Pick<EuropePmcSearchParams, 'query' | 'sources'>): string;
 //# sourceMappingURL=api-client.d.ts.map

package/dist/services/europe-pmc/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,wBAAwB,EAAI;IAEjE;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4C3D;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA4C7F;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7F;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9F;IAED,iFAAiF;YACnE,cAAc;IA8B5B,OAAO,CAAC,cAAc;CAavB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,MAAM,CAKjG"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,EAAsB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI5E,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GACpC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IACjB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAnC,YAA6B,MAAM,EAAE,wBAAwB,EAAI;IAEjE;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2C3D;IAED;;;;;;;;;OASG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,4BAA4B,CAAC,CA4C7F;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG7F;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAG9F;IAED,iFAAiF;YACnE,cAAc;IA8B5B,OAAO,CAAC,cAAc;CAavB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,MAAM,CAOjG"}

package/dist/services/europe-pmc/api-client.js

@@ -10,7 +10,6 @@
  */
 import { JsonRpcErrorCode, McpError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
 import { fetchWithTimeout, logger, requestContextService } from '@cyanheads/mcp-ts-core/utils';
-import { recoveryFor } from '../error-contracts.js';
 import { EUROPEPMC_API_BASE } from './types.js';
 const USER_AGENT = 'pubmed-mcp-server (+https://github.com/cyanheads/pubmed-mcp-server)';
 /**
@@ -36,8 +35,8 @@ export class EuropePmcApiClient {
      * query is HTTP 200 with `hitCount: 0`. A 404 is reclassified from its
      * status-mapped `NotFound` to `ServiceUnavailable` so the service retries it.
      * A retryable 5xx keeps its code, so a 504 stays `Timeout`. Only a failure
-     * that ends up `ServiceUnavailable` carries `europepmc_unreachable` and its
-     * recovery hint, the one code that reason is declared for. An upstream
+     * that ends up `ServiceUnavailable` carries `europepmc_unreachable`, the one
+     * code that reason is declared for. An upstream
      * `retryAfter` is kept. A 429 and every other 4xx pass through unchanged, as
      * does a 501, whose `data.retryable: false` keeps it out of the retry loop.
      * (#152)
@@ -66,14 +65,13 @@ export class EuropePmcApiClient {
                 throw new McpError(code, `Europe PMC search request failed: ${error.message}`, {
                     ...(code === JsonRpcErrorCode.ServiceUnavailable && {
                         reason: 'europepmc_unreachable',
-                        ...recoveryFor('europepmc_unreachable'),
                     }),
                     status,
                     ...(error.data?.retryAfter !== undefined && { retryAfter: error.data.retryAfter }),
                 }, { cause: error });
             }
             const msg = error instanceof Error ? error.message : String(error);
-            throw serviceUnavailable(`Europe PMC search request failed: ${msg}`, { reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') }, { cause: error });
+            throw serviceUnavailable(`Europe PMC search request failed: ${msg}`, { reason: 'europepmc_unreachable' }, { cause: error });
         }
         return response.text();
     }
@@ -112,7 +110,7 @@ export class EuropePmcApiClient {
                 throw error;
             }
             const msg = error instanceof Error ? error.message : String(error);
-            throw serviceUnavailable(`Europe PMC fullTextXML request failed: ${msg}`, { reason: 'europepmc_unreachable', epmcId, ...recoveryFor('europepmc_unreachable') }, { cause: error });
+            throw serviceUnavailable(`Europe PMC fullTextXML request failed: ${msg}`, { reason: 'europepmc_unreachable', epmcId }, { cause: error });
         }
         const xml = await response.text();
         if (!xml.trim()) {
@@ -159,7 +157,7 @@ export class EuropePmcApiClient {
             if (error instanceof McpError)
                 throw error;
             const msg = error instanceof Error ? error.message : String(error);
-            throw serviceUnavailable(`Europe PMC links request failed: ${msg}`, { reason: 'europepmc_unreachable', ...recoveryFor('europepmc_unreachable') }, { cause: error });
+            throw serviceUnavailable(`Europe PMC links request failed: ${msg}`, { reason: 'europepmc_unreachable' }, { cause: error });
         }
         return response.text();
     }
@@ -183,12 +181,19 @@ export class EuropePmcApiClient {
  * optional source filter. EPMC's query syntax supports `SRC:"X"` field tokens —
  * the requested sources are OR-joined into a parenthesized clause and ANDed
  * with the caller's query.
+ *
+ * A single source is repeated (`SRC:"MED" OR SRC:"MED"`). Europe PMC matches
+ * nothing when a query is exactly one `EXT_ID` clause ANDed with one `SRC`
+ * clause and either value is quoted; the repeated clause matches quoted and
+ * unquoted `EXT_ID` alike and returns the same total as a lone clause for any
+ * other query. Multi-source clauses are sent as they are. (#175)
  */
 export function buildSearchQuery(params) {
     const base = params.query.trim();
     if (!params.sources || params.sources.length === 0)
         return base;
-    const sourceClause = params.sources.map((s) => `SRC:"${s}"`).join(' OR ');
+    const sources = params.sources.length === 1 ? [...params.sources, ...params.sources] : params.sources;
+    const sourceClause = sources.map((s) => `SRC:"${s}"`).join(' OR ');
     return `(${base}) AND (${sourceClause})`;
 }
 //# sourceMappingURL=api-client.js.map

package/dist/services/europe-pmc/api-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../../src/services/europe-pmc/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE/F,OAAO,EAAE,kBAAkB,EAA8B,MAAM,YAAY,CAAC;AAE5E,MAAM,UAAU,GAAG,qEAAqE,CAAC;AAezF;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IACA,MAAM;IAAnC,YAA6B,MAAgC;sBAAhC,MAAM;IAA6B,CAAC;IAEjE;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,MAAM,CAAC,MAA6B;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrD,SAAS,EAAE,iBAAiB;YAC5B,iBAAiB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE;SAC3C,CAAC,CAAC;QAEH,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE;gBACjE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,EAAE;gBACjE,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;aAChD,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;gBAC9B,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;gBAClC,MAAM,QAAQ,GACZ,MAAM,KAAK,GAAG;oBACd,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,SAAS,KAAK,KAAK,CAAC,CAAC;gBACnF,IAAI,CAAC,QAAQ;oBAAE,MAAM,KAAK,CAAC;gBAC3B,MAAM,IAAI,GAAG,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC/E,MAAM,IAAI,QAAQ,CAChB,IAAI,EACJ,qCAAqC,KAAK,CAAC,OAAO,EAAE,EACpD;oBACE,GAAG,CAAC,IAAI,KAAK,gBAAgB,CAAC,kBAAkB,IAAI;wBAClD,MAAM,EAAE,uBAAuB;qBAChC,CAAC;oBACF,MAAM;oBACN,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,KAAK,SAAS,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;iBACnF,EACD,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,kBAAkB,CACtB,qCAAqC,GAAG,EAAE,EAC1C,EAAE,MAAM,EAAE,uBAAuB,EAAE,EACnC,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,WAAW,CAAC,MAAc,EAAE,MAAoB;QACpD,MAAM,GAAG,GAAG,GAAG,kBAAkB,IAAI,kBAAkB,CAAC,MAAM,CAAC,cAAc,CAAC;QAC9E,MAAM,GAAG,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrD,SAAS,EAAE,sBAAsB;YACjC,iBAAiB,EAAE,EAAE,MAAM,EAAE;SAC9B,CAAC,CAAC;QAEH,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE;gBACjE,OAAO,EAAE;oBACP,MAAM,EAAE,sCAAsC;oBAC9C,YAAY,EAAE,UAAU;iBACzB;gBACD,gBAAgB,EAAE,CAAC,GAAG,CAAC;gBACvB,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;gBAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,gBAAgB,CAAC,QAAQ,EAAE,CAAC;oBAC7C,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC;gBACtF,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,kBAAkB,CACtB,0CAA0C,GAAG,EAAE,EAC/C,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,EAAE,EAC3C,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YAChB,MAAM,CAAC,KAAK,CACV,gDAAgD,EAChD,qBAAqB,CAAC,oBAAoB,CAAC;gBACzC,SAAS,EAAE,2BAA2B;gBACtC,iBAAiB,EAAE,EAAE,MAAM,EAAE;aAC9B,CAAC,CACH,CAAC;YACF,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,yCAAyC,EAAE,CAAC;QACtF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAChC,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,IAAY,EAAE,QAAgB,EAAE,IAAY,EAAE,MAAoB;QAC1E,MAAM,GAAG,GAAG,GAAG,kBAAkB,QAAQ,kBAAkB,CAAC,IAAI,CAAC,mBAAmB,IAAI,aAAa,QAAQ,cAAc,CAAC;QAC5H,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,oBAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,IAAY,EAAE,QAAgB,EAAE,IAAY,EAAE,MAAoB;QAC3E,MAAM,GAAG,GAAG,GAAG,kBAAkB,QAAQ,kBAAkB,CAAC,IAAI,CAAC,oBAAoB,IAAI,aAAa,QAAQ,cAAc,CAAC;QAC7H,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,qBAAqB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACvE,CAAC;IAED,iFAAiF;IACzE,KAAK,CAAC,cAAc,CAC1B,GAAW,EACX,SAAiB,EACjB,IAAY,EACZ,MAAoB;QAEpB,MAAM,GAAG,GAAG,qBAAqB,CAAC,oBAAoB,CAAC;YACrD,SAAS;YACT,iBAAiB,EAAE,EAAE,IAAI,EAAE;SAC5B,CAAC,CAAC;QAEH,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE;gBACjE,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,YAAY,EAAE,UAAU,EAAE;gBACjE,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,CAAC;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,KAAK,YAAY,QAAQ;gBAAE,MAAM,KAAK,CAAC;YAC3C,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,kBAAkB,CACtB,oCAAoC,GAAG,EAAE,EACzC,EAAE,MAAM,EAAE,uBAAuB,EAAE,EACnC,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAEO,cAAc,CAAC,MAA6B;QAClD,MAAM,WAAW,GAA2B;YAC1C,KAAK,EAAE,gBAAgB,CAAC,MAAM,CAAC;YAC/B,MAAM,EAAE,MAAM;YACd,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,MAAM;YACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,GAAG;SACrC,CAAC;QACF,IAAI,MAAM,CAAC,IAAI;YAAE,WAAW,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QAChD,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK;YAAE,WAAW,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAE7D,OAAO,GAAG,kBAAkB,WAAW,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;IACvF,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAwD;IACvF,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACjC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAChE,MAAM,OAAO,GACX,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC;IACxF,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACnE,OAAO,IAAI,IAAI,UAAU,YAAY,GAAG,CAAC;AAC3C,CAAC"}

package/dist/services/europe-pmc/europe-pmc-service.d.ts

@@ -14,6 +14,10 @@
  * A search's retry boundary covers fetch and response classification, so
  * Europe PMC's intermittent empty `{ version }` envelope is retried like an
  * HTTP outage; only a sort or cursor that explains it is reported as bad input.
+ * Europe PMC answers an unreadable cursor with the HTTP 503 it uses for an
+ * outage, so a 503 on a caller-supplied cursor is checked against the first
+ * page of the same query, and the cursor is blamed only when a retry draws
+ * the 503 again while that first page was served.
  * A search reports the effective query Europe PMC echoes back, or — with no
  * echo — the source-filtered query it sent.
  *
@@ -51,12 +55,26 @@ export declare class EuropePmcService {
      * The retry boundary covers the fetch and the response classification
      * together, so an empty envelope retries like any other transient failure
      * rather than surfacing after the loop has already returned. (#159)
+     *
+     * The first HTTP 503 on a caller-supplied cursor draws one probe of the same
+     * query's first page, and the cursor is retried either way: one 503 is not
+     * enough to tell a bad cursor from a transient outage. A later 503 fails the
+     * search at once as non-retryable input only when that probe was served;
+     * otherwise it goes on through the ordinary retry path. A 503 with no retry
+     * left is never probed, since nothing could use the answer. (#180)
      */
     search(params: EuropePmcSearchParams): Promise<EuropePmcSearchResult>;
+    /**
+     * Whether Europe PMC serves the first page of the search in `params`: one
+     * request (`cursorMark: '*'`, `pageSize: 1`), paced like any other, with no
+     * retries of its own. Any failure reads as not served — except the caller's
+     * cancellation, which propagates.
+     */
+    private firstPageServed;
     /**
      * One search attempt: fetch, parse, and classify the body. `isLastAttempt`
-     * lets an empty envelope that has persisted through the whole retry budget
-     * be attributed to a caller-supplied cursor.
+     * lets an empty envelope on the last attempt the retry budget allows be
+     * attributed to a caller-supplied cursor.
      */
     private searchOnce;
     /**
@@ -129,6 +147,11 @@ export declare class EuropePmcService {
      * signal reaches the queue wait and the backoff sleep. `execute` receives the
      * one-based attempt number.
      *
+     * `reclassify`, when given, sees each failed attempt after its queue slot is
+     * released and before the retry decision, with the attempt's signal and its
+     * one-based number. The error it returns is the one the loop judges, so it
+     * can end the retries by returning a non-transient error.
+     *
      * A caller abort rethrows the caller's own reason; an exhausted failure is
      * reshaped by {@link toServiceError}, after the loop.
      */

package/dist/services/europe-pmc/europe-pmc-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"europe-pmc-service.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH,OAAO,EAGL,KAAK,KAAK,EAGX,MAAM,8BAA8B,CAAC;AAOtC,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,4CAA4C,CAAC;AAEzF,OAAO,EAAoB,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,KAAK,EACV,uBAAuB,EAEvB,kBAAkB,EAElB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EAErB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AA2FpB;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAY;IAE7C,YACmB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAQpC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAIpE;IAED;;;;OAIG;YACW,UAAU;IAwHxB;;;;;;;;;;OAUG;IACG,YAAY,CAChB,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQ/B;IAED;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC,CASlC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;OAKG;YACW,iBAAiB;IAkE/B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA8BlD;IAED;;;;;;;;;;OAUG;YACW,QAAQ;CA0CvB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAyB3C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE"}
+{"version":3,"file":"europe-pmc-service.d.ts","sourceRoot":"","sources":["../../../src/services/europe-pmc/europe-pmc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,OAAO,EAGL,KAAK,KAAK,EAGX,MAAM,8BAA8B,CAAC;AAMtC,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,4CAA4C,CAAC;AAEzF,OAAO,EAAoB,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEvE,OAAO,KAAK,EACV,uBAAuB,EAEvB,kBAAkB,EAElB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EAErB,qBAAqB,EACrB,eAAe,EAChB,MAAM,YAAY,CAAC;AAsGpB;;;;;;;;;;GAUG;AACH,qBAAa,gBAAgB;IAIzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAY;IAE7C,YACmB,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,MAAM,EAQpC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA+BpE;IAED;;;;;OAKG;YACW,eAAe;IAgB7B;;;;OAIG;YACW,UAAU;IAyHxB;;;;;;;;;;OAUG;IACG,YAAY,CAChB,IAAI,EAAE,SAAS,kBAAkB,EAAE,EACnC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAQ/B;IAED;;;;;;;OAOG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC,CASlC;IAED;;;;;;;;;;OAUG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAQjC;IAED;;;;;OAKG;YACW,iBAAiB;IAkE/B;;;;;;;;OAQG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CA4BlD;IAED;;;;;;;;;;;;;;;OAeG;YACW,QAAQ;CA8CvB;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAyB3C;AAED,6EAA6E;AAC7E,wBAAgB,mBAAmB,IAAI,gBAAgB,GAAG,SAAS,CAElE"}