@cyanheads/secedgar-mcp-server 0.15.13 → 0.15.14

package/dist/services/edgar/edgar-api-service.js

@@ -9,6 +9,7 @@ import { createPacer, httpErrorFromResponse, logger, requestContextService, with
 import { parseDocument } from 'htmlparser2';
 import { getServerConfig } from '../../config/server-config.js';
 import { getEdgarMirror } from './mirror/index.js';
+import { CALL_FAILURE_BUDGET_MS, CallScope } from './call-scope.js';
 import formerNamesData from './data/former-names.json' with { type: 'json' };
 import { parseFilingHeaders, parseSubmissionHeader, } from './filing-headers.js';
 import { trigramSimilarity } from './trigram-similarity.js';
@@ -19,8 +20,8 @@ const BASE_BACKOFF_MS = 1000;
  * Statuses worth a retry. 429 is deliberately absent: SEC holds a rate-limit block
  * until the request rate has stayed under the threshold for ten minutes, so the
  * ~3s retry budget cannot outlast it and every retry restarts the clock the caller
- * is waiting on (#112). An attempt that gets no HTTP response at all retries on the
- * same ladder (#173).
+ * is waiting on (#112). An attempt that gets no HTTP response at all (#173), and
+ * one whose body fails to read after its headers (#181), retry on the same ladder.
  */
 const RETRYABLE_STATUSES = new Set([500, 502, 503, 504]);
 /**
@@ -28,19 +29,31 @@ const RETRYABLE_STATUSES = new Set([500, 502, 503, 504]);
  * it is aborted and retried as a no-response failure (#173). Bun applies no connect
  * timeout of its own — an unanswered connect waits out the OS TCP timeout, 75 s on
  * macOS — and neither runtime bounds a server that accepts and never answers, so one
- * attempt could outlast the MCP client's 60 s request timeout alone. Three capped
- * attempts plus the 1 s and 2 s backoffs come to 48 s. The clock starts once the
- * pacer dispatches the request, so queue time never counts, and stops at headers,
- * so a multi-megabyte body is never cut off. SEC's slowest reads sampled send
- * headers in under 2 s.
+ * attempt could outlast the MCP client's 60 s request timeout alone. Each wait is
+ * also clamped to what is left of the call's {@link CALL_FAILURE_BUDGET_MS}, which
+ * bounds a whole tool call's failure time (#179). The clock starts once the
+ * pacer dispatches the request, so queue time never counts, and stops at headers;
+ * the body is bounded only by {@link BODY_IDLE_TIMEOUT_MS}, so a multi-megabyte body
+ * that keeps arriving is never cut off. SEC's slowest reads sampled send headers in
+ * under 2 s.
  */
 const ATTEMPT_HEADERS_TIMEOUT_MS = 15_000;
 /**
- * `data.reason` once every attempt got no HTTP response (#173). Declared retryable
- * on every tool that reaches SEC; set on `data.retryable` here for the same reason
- * as `rate_limited` (#122).
+ * How long a response body may go without a byte before the read is abandoned and
+ * the attempt retried as a body-read failure (#181). Measured between reads, never
+ * across the whole body, so a body still arriving, however slowly, is never cut.
+ * Without it a stalled body holds the call until undici's 300 s body timeout on
+ * Node, and indefinitely on Bun.
+ */
+const BODY_IDLE_TIMEOUT_MS = 15_000;
+/**
+ * `data.reason` once SEC gave no complete, readable answer: the last attempt got no
+ * HTTP response (#173) or its body failed to read, or a 200 body was not JSON
+ * (#181). Declared retryable on every tool that reaches SEC; set on `data.retryable`
+ * here for the same reason as `rate_limited` (#122).
  */
 const SEC_UNREACHABLE_REASON = 'sec_unreachable';
+const BUDGET_SPENT = { kind: 'budget_spent' };
 /**
  * `data.reason` on every SEC rate-limit failure — the upstream 429 and a call
  * refused locally while the cool-down after one runs — so a caller branches the
@@ -221,31 +234,30 @@ class EdgarApiService {
     dispose() {
         this.pacer.dispose();
     }
-    /** Fetch and parse JSON, throwing on non-OK responses. */
-    async fetchJson(url) {
-        const response = await this.rawFetch(url, true);
-        if (response.status === 404) {
+    /** Fetch and parse JSON, throwing on non-OK responses and on a body that is not JSON. */
+    async fetchJson(url, scope) {
+        const text = await this.rawFetch(url, true, scope);
+        if (text === null) {
             throw notFound(`SEC EDGAR API returned 404 for ${url}`, { url, status: 404 });
         }
-        return response.json();
+        return parseJson(url, text);
     }
     /** Fetch JSON, returning `null` on 404 and throwing on other non-OK responses. */
-    async tryFetchJson(url) {
-        const response = await this.rawFetch(url, true);
-        return response.status === 404 ? null : response.json();
+    async tryFetchJson(url, scope) {
+        const text = await this.rawFetch(url, true, scope);
+        return text === null ? null : parseJson(url, text);
     }
     /** Fetch raw text content (HTML filing documents). */
-    async fetchText(url) {
-        const response = await this.rawFetch(url, false);
-        if (response.status === 404) {
+    async fetchText(url, scope) {
+        const text = await this.rawFetch(url, false, scope);
+        if (text === null) {
             throw notFound(`SEC EDGAR returned 404 for ${url}`, { url, status: 404 });
         }
-        return response.text();
+        return text;
     }
     /** Fetch raw text content, returning `null` on 404 and throwing on other failures. */
-    async tryFetchText(url) {
-        const response = await this.rawFetch(url, false);
-        return response.status === 404 ? null : response.text();
+    tryFetchText(url, scope) {
+        return this.rawFetch(url, false, scope);
     }
     // --- CIK Resolution ---
     /**
@@ -258,8 +270,8 @@ class EdgarApiService {
      * On no-result name search, the returned empty array carries `suggestions` on
      * the thrown error at the handler layer — call `suggestCompanies` there.
      */
-    async resolveCik(query) {
-        const cache = await this.getTickerCache();
+    async resolveCik(query, scope) {
+        const cache = await this.getTickerCache(scope);
         const trimmed = query.trim();
         // Numeric → CIK
         if (/^\d+$/.test(trimmed)) {
@@ -347,10 +359,10 @@ class EdgarApiService {
      * Distinct from `searchFilings`: same URL path, different query param (`keysTyped`)
      * and response shape (`_source.entity`, not the filing-document `_source`).
      */
-    async resolveEntityByName(name) {
+    async resolveEntityByName(name, scope) {
         const url = new URL('https://efts.sec.gov/LATEST/search-index');
         url.searchParams.set('keysTyped', name);
-        const response = await this.fetchJson(url.toString());
+        const response = await this.fetchJson(url.toString(), scope);
         const hits = response?.hits?.hits;
         if (!Array.isArray(hits))
             return [];
@@ -367,8 +379,8 @@ class EdgarApiService {
         return matches;
     }
     /** Reverse lookup: CIK → ticker symbol. */
-    async cikToTicker(cik) {
-        const cache = await this.getTickerCache();
+    async cikToTicker(cik, scope) {
+        const cache = await this.getTickerCache(scope);
         return cache.byCik.get(cik.padStart(10, '0'))?.ticker;
     }
     /**
@@ -376,8 +388,8 @@ class EdgarApiService {
      * company_tickers_mf.json, which lists a series only once one of its share classes has a
      * ticker — a series with no listed class resolves to `undefined` rather than a wrong trust.
      */
-    async resolveFundSeries(seriesId) {
-        const cache = await this.getTickerCache();
+    async resolveFundSeries(seriesId, scope) {
+        const cache = await this.getTickerCache(scope);
         return cache.bySeriesId.get(seriesId.toUpperCase());
     }
     /**
@@ -387,8 +399,8 @@ class EdgarApiService {
      * class only — a trust whose series carry no ticker returns an empty list, which is not
      * the same as having no series.
      */
-    async listFundSeries(cik) {
-        const cache = await this.getTickerCache();
+    async listFundSeries(cik, scope) {
+        const cache = await this.getTickerCache(scope);
         const padded = cik.padStart(10, '0');
         const out = [];
         for (const [seriesId, match] of cache.bySeriesId) {
@@ -406,7 +418,7 @@ class EdgarApiService {
      * response also names the registrant, so a bare series ID resolves without a second call.
      * Entries come back newest-filed first and include amendments of the form.
      */
-    async getFundSeriesFilings(seriesId, formType, count) {
+    async getFundSeriesFilings(seriesId, formType, count, scope) {
         const url = new URL('https://www.sec.gov/cgi-bin/browse-edgar');
         url.searchParams.set('action', 'getcompany');
         url.searchParams.set('CIK', seriesId);
@@ -414,11 +426,11 @@ class EdgarApiService {
         url.searchParams.set('owner', 'include');
         url.searchParams.set('count', String(count));
         url.searchParams.set('output', 'atom');
-        return parseSeriesFilingFeed(await this.fetchText(url.toString()));
+        return parseSeriesFilingFeed(await this.fetchText(url.toString(), scope));
     }
     /** Return the current in-memory entry list (used by the handler for trigram suggestions). */
-    async getAllEntries() {
-        const cache = await this.getTickerCache();
+    async getAllEntries(scope) {
+        const cache = await this.getTickerCache(scope);
         return cache.allEntries;
     }
     // --- SEC API Methods ---
@@ -427,14 +439,15 @@ class EdgarApiService {
      * the last year or 1,000 filings, whichever holds more — + the `files[]`
      * archive-page manifest). Cached per CIK within
      * the ticker-cache TTL — the doc is large and re-read on every archive-paging
-     * scan (#78). A 404 throws (uncached) so a bad CIK still surfaces.
+     * scan (#78). A 404 throws (uncached) so a bad CIK still surfaces. Like every
+     * cache here, written only by a completed read — a cancelled one caches nothing.
      */
-    async getSubmissions(cik) {
+    async getSubmissions(cik, scope) {
         const padded = cik.padStart(10, '0');
         const cached = this.submissionsCache.get(padded);
         if (cached && this.isFresh(cached.at))
             return cached.data;
-        const data = await this.fetchJson(`https://data.sec.gov/submissions/CIK${padded}.json`);
+        const data = await this.fetchJson(`https://data.sec.gov/submissions/CIK${padded}.json`, scope);
         this.submissionsCache.set(padded, { at: Date.now(), data });
         return data;
     }
@@ -445,11 +458,11 @@ class EdgarApiService {
      * field-compatible with `FilingsRecent`. Cached per page within the ticker-cache
      * TTL (pages are large and effectively immutable once archived).
      */
-    async fetchArchivePage(name) {
+    async fetchArchivePage(name, scope) {
         const cached = this.archivePageCache.get(name);
         if (cached && this.isFresh(cached.at))
             return cached.data;
-        const data = await this.fetchJson(`https://data.sec.gov/submissions/${name}`);
+        const data = await this.fetchJson(`https://data.sec.gov/submissions/${name}`, scope);
         this.archivePageCache.set(name, { at: Date.now(), data });
         return data;
     }
@@ -462,12 +475,12 @@ class EdgarApiService {
      * bound how many quarters they scan and filter client-side (#77). Cached per
      * quarter within the ticker-cache TTL — an archived quarter is immutable.
      */
-    async fetchFullIndexQuarter(year, quarter) {
+    async fetchFullIndexQuarter(year, quarter, scope) {
         const key = `${year}Q${quarter}`;
         const cached = this.fullIndexCache.get(key);
         if (cached && this.isFresh(cached.at))
             return cached.data;
-        const text = await this.fetchText(`https://www.sec.gov/Archives/edgar/full-index/${year}/QTR${quarter}/master.idx`);
+        const text = await this.fetchText(`https://www.sec.gov/Archives/edgar/full-index/${year}/QTR${quarter}/master.idx`, scope);
         const data = parseMasterIndex(text);
         this.fullIndexCache.set(key, { at: Date.now(), data });
         return data;
@@ -476,7 +489,7 @@ class EdgarApiService {
     isFresh(at) {
         return Date.now() - at < getServerConfig().tickerCacheTtl * 1000;
     }
-    async searchFilings(params) {
+    async searchFilings(params, scope) {
         const url = new URL('https://efts.sec.gov/LATEST/search-index');
         // `q` is optional — EFTS honors `ciks` for pure entity scope with no
         // full-text query, so a bare cik:/ticker: search sends no `q`.
@@ -495,7 +508,7 @@ class EdgarApiService {
         }
         url.searchParams.set('from', String(params.from ?? 0));
         url.searchParams.set('size', String(params.size ?? 20));
-        const response = await this.fetchJson(url.toString());
+        const response = await this.fetchJson(url.toString(), scope);
         // Shape guard: EFTS can return a 2xx whose body omits `hits.total` (degraded
         // payload, or a rejected request echoed as `{ error: ... }` with 200). A genuine
         // zero-hit response is still well-formed (`hits.total.value: 0`, empty
@@ -517,8 +530,8 @@ class EdgarApiService {
      * Resolve likely company CIKs for a filing accession number using SEC search metadata.
      * Returns zero or more padded 10-digit CIKs in SEC-provided order.
      */
-    async findFilingCiks(accessionNumber) {
-        const response = await this.searchFilings({ query: accessionNumber, size: 10 });
+    async findFilingCiks(accessionNumber, scope) {
+        const response = await this.searchFilings({ query: accessionNumber, size: 10 }, scope);
         const normalizedAccession = accessionNumber.replace(/[^0-9]/g, '');
         const ciks = new Set();
         for (const hit of response.hits.hits) {
@@ -532,8 +545,8 @@ class EdgarApiService {
         return [...ciks];
     }
     /** Fetch a filing's document index. Returns `null` if the filing does not exist. */
-    tryGetFilingIndex(cik, accessionNumber) {
-        return this.tryFetchJson(filingArchiveUrl(cik, accessionNumber, 'index.json'));
+    tryGetFilingIndex(cik, accessionNumber, scope) {
+        return this.tryFetchJson(filingArchiveUrl(cik, accessionNumber, 'index.json'), scope);
     }
     /**
      * Fetch the SEC submission header page (`<accession>-index-headers.html`) and parse
@@ -541,8 +554,8 @@ class EdgarApiService {
      * and period. Returns `null` if the page is absent. The page exposes canonical SEC
      * document TYPE values (e.g. "EX-21.1") that the directory listing JSON does not.
      */
-    async tryGetFilingHeaders(cik, accessionNumber) {
-        const text = await this.tryFetchText(filingArchiveUrl(cik, accessionNumber, `${accessionNumber}-index-headers.html`));
+    async tryGetFilingHeaders(cik, accessionNumber, scope) {
+        const text = await this.tryFetchText(filingArchiveUrl(cik, accessionNumber, `${accessionNumber}-index-headers.html`), scope);
         return text ? parseFilingHeaders(text) : null;
     }
     /**
@@ -551,18 +564,18 @@ class EdgarApiService {
      * fallback for filings whose index-headers page is missing — common among filings
      * made before 2014; it lists no documents.
      */
-    async tryGetSubmissionHeader(cik, accessionNumber) {
-        const text = await this.tryFetchText(filingArchiveUrl(cik, accessionNumber, `${accessionNumber}.hdr.sgml`));
+    async tryGetSubmissionHeader(cik, accessionNumber, scope) {
+        const text = await this.tryFetchText(filingArchiveUrl(cik, accessionNumber, `${accessionNumber}.hdr.sgml`), scope);
         return text ? parseSubmissionHeader(text) : null;
     }
-    getFilingDocument(cik, accessionNumber, document) {
-        return this.fetchText(filingArchiveUrl(cik, accessionNumber, document));
+    getFilingDocument(cik, accessionNumber, document, scope) {
+        return this.fetchText(filingArchiveUrl(cik, accessionNumber, document), scope);
     }
     /**
      * Fetch a filing document, returning `null` when the archive path exists but this document does not.
      */
-    tryGetFilingDocument(cik, accessionNumber, document) {
-        return this.tryFetchText(filingArchiveUrl(cik, accessionNumber, document));
+    tryGetFilingDocument(cik, accessionNumber, document, scope) {
+        return this.tryFetchText(filingArchiveUrl(cik, accessionNumber, document), scope);
     }
     /**
      * Fetch the leading bytes of a filing document, stopping as soon as `stopAt` appears in
@@ -578,45 +591,20 @@ class EdgarApiService {
      * appears 1.5 KB in still costs 256 KB, and a `maxBytes` below that costs the same. Treat
      * both as "one chunk, not the file" rather than as a byte budget; `maxBytes` binds only on
      * a document long enough to arrive in several chunks, which is what stops a document
-     * missing `stopAt` entirely from being read to the end. A runtime that hands back no
-     * readable body (a stubbed fetch, for one) falls through to reading it whole, which costs
-     * bandwidth but returns the same text.
+     * missing `stopAt` entirely from being read to the end. The head is read inside the
+     * retry ladder like any other body, so a read that breaks off before the cutoff is
+     * retried; stopping at the cutoff is not a failure (#181).
      */
-    async tryGetFilingDocumentHead(cik, accessionNumber, document, options) {
-        const response = await this.rawFetch(filingArchiveUrl(cik, accessionNumber, document), false);
-        if (response.status === 404)
-            return null;
-        if (!response.body)
-            return response.text();
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        let text = '';
-        let read = 0;
-        try {
-            while (read < options.maxBytes) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                read += value.byteLength;
-                text += decoder.decode(value, { stream: true });
-                if (text.includes(options.stopAt))
-                    break;
-            }
-        }
-        finally {
-            await reader.cancel().catch(() => {
-                /* the body is being discarded; a cancel race has nothing left to report */
-            });
-        }
-        return text;
+    tryGetFilingDocumentHead(cik, accessionNumber, document, options, scope) {
+        return this.rawFetch(filingArchiveUrl(cik, accessionNumber, document), false, scope, options);
     }
     /**
      * Search EDGAR submissions for recent filings of specified form types, newest first.
      * Returns up to `limit` matches from the submissions recent-filings window. Each carries
      * `reportDate` (the period-of-report end date) for callers that target a specific period.
      */
-    async getRecentFilingsByForm(cik, formTypes, limit) {
-        const submissions = await this.getSubmissions(cik);
+    async getRecentFilingsByForm(cik, formTypes, limit, scope) {
+        const submissions = await this.getSubmissions(cik, scope);
         const recent = submissions.filings.recent;
         const results = [];
         for (let i = 0; i < recent.form.length && results.length < limit; i++) {
@@ -640,9 +628,9 @@ class EdgarApiService {
      * lookup; the live API is the fallback. A concept unit that arrives as
      * anything but an array is dropped (#141).
      */
-    async tryGetCompanyFacts(cik) {
+    async tryGetCompanyFacts(cik, scope) {
         const padded = cik.padStart(10, '0');
-        const facts = await this.mirrorOrLive((m) => m.companyFactsReady(), (m) => m.getCompanyFacts(cik), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyfacts/CIK${padded}.json`));
+        const facts = await this.mirrorOrLive((m) => m.companyFactsReady(), (m) => m.getCompanyFacts(cik), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyfacts/CIK${padded}.json`, scope));
         for (const namespace of Object.values(facts?.facts ?? {})) {
             for (const concept of Object.values(namespace))
                 concept.units = arrayUnits(concept.units);
@@ -656,9 +644,9 @@ class EdgarApiService {
      * A payload whose every unit arrives malformed comes back with no units — the
      * tag is named but carries nothing (#141).
      */
-    async tryGetCompanyConcept(cik, taxonomy, tag) {
+    async tryGetCompanyConcept(cik, taxonomy, tag, scope) {
         const padded = cik.padStart(10, '0');
-        const concept = await this.mirrorOrLive((m) => m.companyFactsReady(), (m) => m.getCompanyConcept(cik, taxonomy, tag), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyconcept/CIK${padded}/${taxonomy}/${tag}.json`));
+        const concept = await this.mirrorOrLive((m) => m.companyFactsReady(), (m) => m.getCompanyConcept(cik, taxonomy, tag), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyconcept/CIK${padded}/${taxonomy}/${tag}.json`, scope));
         if (concept)
             concept.units = arrayUnits(concept.units);
         return concept;
@@ -671,8 +659,8 @@ class EdgarApiService {
      * fall back to the live API until the mirror is complete. The live API is also
      * the fallback on a genuine miss.
      */
-    tryGetFrames(taxonomy, tag, unit, period) {
-        return this.mirrorOrLive((m) => m.companyFactsComplete(), (m) => m.getFrames(taxonomy, tag, unit, period), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/frames/${taxonomy}/${tag}/${unit}/${period}.json`));
+    tryGetFrames(taxonomy, tag, unit, period, scope) {
+        return this.mirrorOrLive((m) => m.companyFactsComplete(), (m) => m.getFrames(taxonomy, tag, unit, period), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/frames/${taxonomy}/${tag}/${unit}/${period}.json`, scope));
     }
     /**
      * Route a company-facts query through the local mirror when ready, with live-API
@@ -705,63 +693,115 @@ class EdgarApiService {
     }
     // --- Internals ---
     /**
-     * Paced fetch with retry/backoff. Returns the response on 2xx or 404. A 5xx, and
-     * an attempt that got no HTTP response, retry up to `MAX_RETRIES` attempts; then
-     * the 5xx throws its status-classified `McpError` and the no-response case throws
-     * `sec_unreachable`. Other non-OK statuses throw at once, as does the local
-     * refusal while SEC's rate-limit block is active, and the pacer's
+     * Paced fetch with retry/backoff. Returns the body's text on 2xx — only its head
+     * when `cutoff` is given — and `null` on 404, whose body is left unread. The body
+     * is read inside the ladder (#181): a 5xx, an attempt that got no HTTP response,
+     * and a 2xx whose body failed to read all retry up to `MAX_RETRIES` attempts, and
+     * then the last attempt decides — a 5xx throws its status-classified `McpError`,
+     * the other two `sec_unreachable`. Other non-OK statuses throw at once, as does
+     * the local refusal while SEC's rate-limit block is active, and the pacer's
      * `RequestCancelled` — those are `McpError`s from `send()`, never retried.
+     *
+     * Every failed attempt and every backoff is charged to the call's failure budget,
+     * and the ladder ends early once the budget cannot cover another backoff and
+     * attempt (#179). Once the caller's signal has fired, whatever rejects is rethrown
+     * untouched — a queued request leaves the pacer unsent, and an attempt in flight,
+     * a body read, or a backoff sleep ends at once — never retried or classified.
      */
-    async rawFetch(url, acceptJson) {
+    async rawFetch(url, acceptJson, scope, cutoff) {
+        scope.signal.throwIfAborted();
         const headers = { 'User-Agent': getServerConfig().userAgent };
         if (acceptJson)
             headers.Accept = 'application/json';
-        for (let attempt = 0;; attempt++) {
-            const outcome = await this.send(url, headers);
-            if (outcome.kind === 'answered' && (outcome.response.ok || outcome.response.status === 404)) {
-                return outcome.response;
+        /** The previous attempt's failure, which a request the budget stops before its next attempt ends with. */
+        let failed;
+        for (let attempt = 1;; attempt++) {
+            const outcome = scope.remainingMs > 0 ? await this.send(url, headers, scope) : BUDGET_SPENT;
+            // An answer that lands as the caller cancels is not read.
+            scope.signal.throwIfAborted();
+            if (outcome.kind === 'budget_spent') {
+                // Spent before this attempt could go out — by an earlier request, or by a
+                // concurrent one while this retry waited for its slot.
+                if (failed === undefined)
+                    throw secUnreachable(url, outcome);
+                throw await this.ladderFailure(url, failed, { attempt: attempt - 1, budgetStopped: true });
             }
-            const transient = outcome.kind === 'unanswered' || RETRYABLE_STATUSES.has(outcome.response.status);
-            if (transient && attempt < MAX_RETRIES - 1) {
-                await sleep(BASE_BACKOFF_MS * 2 ** attempt);
-                continue;
-            }
-            if (outcome.kind === 'unanswered')
-                throw secUnreachable(url, outcome);
-            const { response } = outcome;
-            const data = { url };
-            if (response.status === 403) {
-                const host = new URL(url).hostname;
-                data.recovery = {
-                    hint: `${host} may be blocking requests. Check EDGAR_USER_AGENT format ("AppName contact@email.com") or retry later.`,
-                };
+            let last = outcome;
+            if (outcome.kind === 'answered') {
+                const { response } = outcome;
+                if (response.status === 404)
+                    return null;
+                if (response.ok) {
+                    const body = await readBody(response, scope, cutoff);
+                    if (body.kind === 'read')
+                        return body.text;
+                    last = body;
+                }
             }
-            else if (response.status === 429) {
-                // send() closed the gate on this response, so the wait is the full cool-down.
-                const retryAfter = this.cooldownSecondsRemaining();
-                data.reason = RATE_LIMITED_REASON;
-                data.retryable = true;
-                data.retryAfter = retryAfter;
-                data.recovery = { hint: rateLimitHint(retryAfter) };
+            const transient = last.kind !== 'answered' || RETRYABLE_STATUSES.has(last.response.status);
+            if (!transient)
+                throw await this.ladderFailure(url, last, { attempt, budgetStopped: false });
+            scope.charge(outcome.waitedMs + (last.kind === 'body_failed' ? last.waitedMs : 0));
+            const backoffMs = BASE_BACKOFF_MS * 2 ** (attempt - 1);
+            if (attempt < MAX_RETRIES && scope.remainingMs > backoffMs) {
+                scope.charge(backoffMs);
+                await sleep(backoffMs, scope.signal);
+                failed = last;
+                continue;
             }
-            throw await httpErrorFromResponse(response, {
-                service: 'SEC EDGAR',
-                data,
-                // SEC answers a rate-limit block with a full HTML page. The recovery hint
-                // above carries everything actionable, so the markup is not forwarded (#112).
-                captureBody: response.status !== 429,
+            throw await this.ladderFailure(url, last, {
+                attempt,
+                budgetStopped: attempt < MAX_RETRIES || cutByBudget(last),
             });
         }
     }
     /**
-     * One attempt through the block gate and the pacer. A 429 closes the gate
-     * before the response is handed back, so no call admitted after it sends. A
-     * `fetch` rejection comes back as an unanswered attempt, and so does a probe
-     * this call waited on that got no HTTP response; the gate's refusal and the
-     * pacer's `RequestCancelled` throw.
+     * The error a request's last attempt earned: `sec_unreachable` for no response or
+     * an unreadable body; for an HTTP answer, its status-classified `McpError`, with
+     * the 403 and 429 hints. A 5xx ladder the failure budget stopped keeps its status
+     * mapping and `data`, and its message says the budget stopped it (#179).
+     */
+    async ladderFailure(url, last, end) {
+        if (last.kind !== 'answered')
+            return secUnreachable(url, last, end);
+        const { response } = last;
+        const data = { url };
+        if (response.status === 403) {
+            const host = new URL(url).hostname;
+            data.recovery = {
+                hint: `${host} may be blocking requests. Check EDGAR_USER_AGENT format ("AppName contact@email.com") or retry later.`,
+            };
+        }
+        else if (response.status === 429) {
+            // send() closed the gate on this response, so the wait is the full cool-down.
+            const retryAfter = this.cooldownSecondsRemaining();
+            data.reason = RATE_LIMITED_REASON;
+            data.retryable = true;
+            data.retryAfter = retryAfter;
+            data.recovery = { hint: rateLimitHint(retryAfter) };
+        }
+        const error = await httpErrorFromResponse(response, {
+            service: 'SEC EDGAR',
+            data,
+            // SEC answers a rate-limit block with a full HTML page. The recovery hint
+            // above carries everything actionable, so the markup is not forwarded (#112).
+            captureBody: response.status !== 429,
+        });
+        if (!end.budgetStopped)
+            return error;
+        return new McpError(error.code, `SEC EDGAR returned HTTP ${response.status} on attempt ${end.attempt} of ${MAX_RETRIES}; ${BUDGET_STOP_TEXT}.`, error.data, { cause: error });
+    }
+    /**
+     * One attempt through the block gate and the pacer, under the caller's signal. A
+     * 429 closes the gate before the response is handed back, so no call admitted
+     * after it sends. A `fetch` rejection comes back as an unanswered attempt, and so
+     * does a probe this call waited on that got no HTTP response; an attempt the spent
+     * failure budget kept from going out comes back as `budget_spent`. The gate's
+     * refusal and the pacer's `RequestCancelled` throw, and so does the caller's
+     * cancel, with its own reason — then a probe settles as having got no answer.
      */
-    async send(url, headers) {
-        const admission = await this.admit();
+    async send(url, headers, scope) {
+        const admission = await this.admit(scope);
         if ('kind' in admission)
             return admission;
         let outcome;
@@ -771,8 +811,8 @@ class EdgarApiService {
                 // slot, and a call queued before the block must not go out inside it.
                 if (this.gate !== admission.gate)
                     throw this.cooldownRefusal();
-                return fetchUntilHeaders(url, headers);
-            });
+                return fetchUntilHeaders(url, headers, scope);
+            }, { signal: scope.signal });
             if (outcome.kind === 'answered' && outcome.response.status === 429) {
                 this.gate = { state: 'closed', reopensAt: Date.now() + this.cooldownMs };
             }
@@ -787,18 +827,21 @@ class EdgarApiService {
      * cool-down runs. The first call after the cool-down becomes the probe; every
      * call behind it waits for the probe to resolve and then reads the gate again —
      * unless the probe got no HTTP response, which each waiter takes as its own
-     * unanswered attempt. Otherwise calls queued behind a silent SEC would probe one
-     * at a time, 15 s each, and the last of N would wait about 45·N s (#173).
+     * unanswered attempt, its wait on the probe charged to its own budget. Otherwise
+     * calls queued behind a silent SEC would probe one at a time, 15 s each, and the
+     * last of N would wait about 45·N s (#173). A waiter whose call is cancelled
+     * leaves with the caller's reason and leaves the gate as it found it (#179).
      */
-    async admit() {
+    async admit(scope) {
         for (;;) {
             const gate = this.gate;
             if (gate.state === 'open')
                 return { gate };
             if (gate.state === 'probing') {
-                const unanswered = await gate.settled;
+                const waitedFrom = Date.now();
+                const unanswered = await untilAborted(gate.settled, scope.signal);
                 if (unanswered)
-                    return unanswered;
+                    return { ...unanswered, waitedMs: Date.now() - waitedFrom };
                 continue;
             }
             if (gate.reopensAt > Date.now())
@@ -811,9 +854,13 @@ class EdgarApiService {
                 releaseProbe: (outcome) => {
                     /**
                      * A probe 429 has already closed the gate for a full cool-down. Any other
-                     * reply means SEC is serving again; no reply at all (a network error, or
-                     * no headers within the per-attempt cap) proves nothing about the block,
-                     * so the gate stays shut for the next call to probe in its place.
+                     * reply means SEC is serving again, even when its body then fails to read —
+                     * the probe settles at headers, and only its own call retries the body
+                     * (#181). No reply at all (a network error, or no headers within the
+                     * per-attempt cap) proves nothing about the block, so the gate stays shut
+                     * for the next call to probe in its place. Nor does a probe whose own call
+                     * was cancelled, or never sent for a spent budget: it settles with nothing,
+                     * so no waiter counts it as one of its own attempts (#179).
                      */
                     if (this.gate === probe) {
                         this.gate =
@@ -840,7 +887,7 @@ class EdgarApiService {
         const remainingMs = gate.state === 'closed' ? gate.reopensAt - Date.now() : 0;
         return Math.max(1, Math.ceil(remainingMs / 1000));
     }
-    getTickerCache() {
+    getTickerCache(scope) {
         const cache = this.tickerCache;
         if (cache && this.isFresh(cache.loadedAt)) {
             if (cache.fundRetryAt === undefined || Date.now() < cache.fundRetryAt) {
@@ -848,30 +895,39 @@ class EdgarApiService {
             }
             // The live fund slice failed and its retry window has passed: refetch it
             // onto the cached base, which keeps its own load time and TTL (#119).
-            return this.loadTickerCacheOnce(() => this.reloadFundSlice(cache));
+            return this.loadTickerCacheOnce(scope, (load) => this.reloadFundSlice(cache, load));
         }
-        return this.loadTickerCacheOnce(() => this.loadTickerCache());
+        return this.loadTickerCacheOnce(scope, (load) => this.loadTickerCache(load));
     }
     /**
      * Singleflight: concurrent callers (e.g. fetch-frames enriching ~5k reporters
      * in parallel) share one in-flight load instead of each queuing its own SEC
-     * fetch through the pacer.
+     * fetch through the pacer. The load runs under a scope of its own — its own
+     * failure budget, and no caller's signal — so one waiter's cancel ends only its
+     * own wait while the load completes and caches for the rest; each waiter is
+     * charged the failure time the load spent while it waited (#179). A call already
+     * cancelled starts no load.
      */
-    loadTickerCacheOnce(load) {
-        this.tickerCacheLoad ??= load().finally(() => {
-            this.tickerCacheLoad = undefined;
-        });
-        return this.tickerCacheLoad;
+    async loadTickerCacheOnce(waiter, load) {
+        waiter.signal.throwIfAborted();
+        if (!this.tickerCacheLoad) {
+            const scope = CallScope.unowned();
+            const promise = load(scope).finally(() => {
+                this.tickerCacheLoad = undefined;
+            });
+            this.tickerCacheLoad = { promise, scope, waits: new Map() };
+        }
+        return await awaitShared(this.tickerCacheLoad, waiter);
     }
     /** Load the whole ticker index: its base, then the live fund slice when the base calls for one. */
-    async loadTickerCache() {
-        const base = await this.loadTickerBase();
-        const funds = base.liveFunds ? await this.loadMfTickers() : NO_LIVE_FUNDS;
+    async loadTickerCache(scope) {
+        const base = await this.loadTickerBase(scope);
+        const funds = base.liveFunds ? await this.loadMfTickers(scope) : NO_LIVE_FUNDS;
         return this.buildTickerCache(base.rows, funds, Date.now());
     }
     /** Refetch a failed live fund slice and rebuild the index on the cached base. */
-    async reloadFundSlice(cache) {
-        return this.buildTickerCache(cache.baseRows, await this.loadMfTickers(), cache.loadedAt);
+    async reloadFundSlice(cache, scope) {
+        return this.buildTickerCache(cache.baseRows, await this.loadMfTickers(scope), cache.loadedAt);
     }
     /**
      * Everything the ticker index holds but the live fund slice, preferring the local
@@ -883,7 +939,7 @@ class EdgarApiService {
      * since the mirror stores a fund symbol as a bare ticker → CIK row. Strict mirror
      * mode reads nothing live, so the mirror's fund rows are its only fund tickers.
      */
-    async loadTickerBase() {
+    async loadTickerBase(scope) {
         const mirror = getEdgarMirror();
         if (mirror && (await mirror.tickersReady())) {
             const rows = await mirror.getTickerRows();
@@ -897,7 +953,7 @@ class EdgarApiService {
         else if (mirror && !getServerConfig().mirrorFallbackLive) {
             throw serviceUnavailable('EDGAR mirror enabled but the ticker layer is not synced; run `bun run mirror:init`', { layer: 'tickers' });
         }
-        const raw = await this.fetchJson('https://www.sec.gov/files/company_tickers.json');
+        const raw = await this.fetchJson('https://www.sec.gov/files/company_tickers.json', scope);
         return {
             liveFunds: true,
             rows: Object.values(raw).map((entry) => ({
@@ -912,17 +968,20 @@ class EdgarApiService {
      * Fetch company_tickers_mf.json (ETFs and mutual funds) as fund rows carrying
      * series and class IDs. Never throws: operating-company resolution must not
      * depend on the fund file. A failed load — any HTTP failure, no HTTP response
-     * at all (#173), a malformed body, or the block gate's local refusal — returns
-     * no rows and a `retryAt`, so the index without funds stands for the retry
+     * at all (#173), a body that fails to read or is not JSON (#181), a malformed
+     * body, or the block gate's local refusal — returns no rows and a `retryAt`, so
+     * the index without funds stands for the retry
      * window rather than the whole TTL (#119). The window is at least the error's
      * `retryAfter`, so a load refused by the rate-limit gate is not retried until
-     * the cool-down ends.
+     * the cool-down ends. It runs only inside the shared ticker load, whose scope no
+     * caller can cancel, so a failure here is always SEC's — a spent failure budget
+     * included (#179).
      */
-    async loadMfTickers() {
+    async loadMfTickers(scope) {
         let retryAfterMs = 0;
         let cause = { reason: 'malformed_body' };
         try {
-            const rows = parseMfTickerFile(await this.fetchJson(MF_TICKERS_URL));
+            const rows = parseMfTickerFile(await this.fetchJson(MF_TICKERS_URL, scope));
             if (rows)
                 return { retryAt: undefined, rows };
         }
@@ -1224,64 +1283,277 @@ export function pickPreferredTicker(a, b) {
         return aHyphen ? b : a;
     return a;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/** Sleep `ms`, or until `signal` fires — then reject with its reason. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+    });
+}
+/**
+ * `promise`, or the rejection `signal` fires with, whichever comes first. A wait on
+ * work this call does not own — the block-gate probe, the shared ticker load —
+ * leaves that work running when the caller cancels.
+ */
+function untilAborted(promise, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+        if (signal.aborted)
+            onAbort();
+    });
+}
+/**
+ * Wait on a shared load under the waiter's own signal, charging the waiter the
+ * failure time the load spent while it waited — no more, so a call that joins a
+ * load late is not billed for the failures before it asked (#179). One wait per
+ * call: a call already waiting joins that wait.
+ */
+function awaitShared(shared, waiter) {
+    let wait = shared.waits.get(waiter);
+    if (!wait) {
+        const spentBefore = shared.scope.spentMs;
+        wait = untilAborted(shared.promise, waiter.signal).finally(() => {
+            waiter.charge(shared.scope.spentMs - spentBefore);
+        });
+        shared.waits.set(waiter, wait);
+    }
+    return wait;
 }
 /**
- * One `fetch`, aborted when no response headers arrive within
- * {@link ATTEMPT_HEADERS_TIMEOUT_MS}. The timer is cleared once `fetch` settles, so
- * the body read is never bounded by it. `fetch` rejects with whatever reason the
- * signal carries, so the abort is recognized by the reason's identity. A
- * controller and `setTimeout` rather than `AbortSignal.timeout()`, as the
- * framework's `fetchWithTimeout` does: the latter can fail on a realm mismatch
- * under Bun.
+ * One `fetch` under the caller's signal, aborted when no response headers arrive
+ * within the lesser of {@link ATTEMPT_HEADERS_TIMEOUT_MS} and the call's failure
+ * budget left (#179) — or, with no budget left, not sent at all. The timer is
+ * cleared once `fetch` settles, so the body read is never bounded by it. `fetch`
+ * rejects with whatever reason the signal carries, so the timeout is recognized by
+ * the reason's identity; once the caller's signal has fired, the rejection is
+ * rethrown as it came. A controller and `setTimeout` rather than
+ * `AbortSignal.timeout()` or `AbortSignal.any()`, as the framework's
+ * `fetchWithTimeout` does: those can fail on a realm mismatch under Bun.
  */
-async function fetchUntilHeaders(url, headers) {
+async function fetchUntilHeaders(url, headers, scope) {
+    scope.signal.throwIfAborted();
+    const capMs = Math.min(ATTEMPT_HEADERS_TIMEOUT_MS, scope.remainingMs);
+    if (capMs <= 0)
+        return BUDGET_SPENT;
     const controller = new AbortController();
-    const deadline = new DOMException(`No response headers within ${ATTEMPT_HEADERS_TIMEOUT_MS}ms.`, 'TimeoutError');
-    const timer = setTimeout(() => controller.abort(deadline), ATTEMPT_HEADERS_TIMEOUT_MS);
+    const deadline = new DOMException(`No response headers within ${capMs}ms.`, 'TimeoutError');
+    const timer = setTimeout(() => controller.abort(deadline), capMs);
+    const cancel = () => controller.abort(scope.signal.reason);
+    scope.signal.addEventListener('abort', cancel, { once: true });
+    const dispatchedAt = Date.now();
     try {
         const response = await globalThis.fetch(url, { headers, signal: controller.signal });
-        return { kind: 'answered', response };
+        return { kind: 'answered', response, waitedMs: Date.now() - dispatchedAt };
+    }
+    catch (rejection) {
+        if (scope.signal.aborted)
+            throw rejection;
+        return {
+            kind: 'unanswered',
+            capMs,
+            rejection,
+            timedOut: controller.signal.reason === deadline,
+            waitedMs: Date.now() - dispatchedAt,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+        scope.signal.removeEventListener('abort', cancel);
+    }
+}
+/**
+ * Read one attempt's body as text — whole, or up to `cutoff` — failing the read once
+ * no bytes arrive for the lesser of {@link BODY_IDLE_TIMEOUT_MS} and the call's
+ * failure budget left (#179). The one place an attempt's body is read (#181). The
+ * body is cancelled once the read stops, so an early stop at the cutoff, a stall,
+ * and the caller's cancel all release the connection without reading the rest; a
+ * cancel that fails is not a body failure, since the body is being discarded either
+ * way. Both cutoff checks run between reads, so neither can cut below one read
+ * chunk. Once the caller's signal has fired, the read's rejection is rethrown as
+ * it came, never a body failure.
+ */
+async function readBody(response, scope, cutoff) {
+    if (!response.body)
+        return { kind: 'read', text: '' };
+    const stalled = new DOMException("No body bytes within the read's idle limit.", 'TimeoutError');
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    let bytes = 0;
+    let capMs = 0;
+    let readFrom = 0;
+    try {
+        while (cutoff === undefined || bytes < cutoff.maxBytes) {
+            capMs = Math.min(BODY_IDLE_TIMEOUT_MS, scope.remainingMs);
+            readFrom = Date.now();
+            const { done, value } = await nextChunk(reader, stalled, capMs, scope.signal);
+            if (done) {
+                text += decoder.decode();
+                break;
+            }
+            bytes += value.byteLength;
+            text += decoder.decode(value, { stream: true });
+            if (cutoff !== undefined && text.includes(cutoff.stopAt))
+                break;
+        }
+        return { kind: 'read', text };
     }
     catch (rejection) {
-        return { kind: 'unanswered', rejection, timedOut: controller.signal.reason === deadline };
+        if (scope.signal.aborted)
+            throw rejection;
+        // A stall is this read's own idle marker, recognized by identity.
+        return {
+            kind: 'body_failed',
+            capMs,
+            rejection,
+            stalled: rejection === stalled,
+            waitedMs: Date.now() - readFrom,
+        };
+    }
+    finally {
+        await reader.cancel().catch(() => {
+            /* the body is being discarded; a cancel racing its end has nothing to report */
+        });
+    }
+}
+/**
+ * The body's next read, rejecting with `stalled` once `capMs` pass with no bytes,
+ * and with the signal's reason once it fires.
+ */
+async function nextChunk(reader, stalled, capMs, signal) {
+    // Checked before the read: a chunk already buffered would otherwise win the race.
+    signal.throwIfAborted();
+    let timer;
+    let onAbort;
+    const idle = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(stalled), capMs);
+        onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([reader.read(), idle]);
     }
     finally {
         clearTimeout(timer);
+        if (onAbort)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+/**
+ * True when the failure budget cut the attempt's last wait short of its own cap —
+ * headers or body bytes that might still have come (#179).
+ */
+function cutByBudget(last) {
+    switch (last.kind) {
+        case 'answered':
+            return false;
+        case 'unanswered':
+            return last.timedOut && last.capMs < ATTEMPT_HEADERS_TIMEOUT_MS;
+        case 'body_failed':
+            return last.stalled && last.capMs < BODY_IDLE_TIMEOUT_MS;
+        default: {
+            const unhandled = last;
+            return unhandled;
+        }
+    }
+}
+/** How a failure the call's failure budget ended says so, in its message (#179). */
+const BUDGET_STOP_TEXT = `retries stopped at this call's ${CALL_FAILURE_BUDGET_MS / 1000} s budget for SEC failures`;
+/** A wait in seconds, to one decimal where it is not whole: `15`, `9.1`. */
+function seconds(ms) {
+    return String(Math.round(ms / 100) / 10);
+}
+/**
+ * Parse a 200's body as JSON. Every SEC route read as JSON serves JSON, so a body
+ * that does not parse — an HTML error page served as a 200 — fails as
+ * `sec_unreachable`, unretried since the body arrived whole; the parser's text,
+ * which quotes the body, rides `cause` only (#181).
+ */
+function parseJson(url, text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (rejection) {
+        throw secUnreachable(url, { kind: 'not_json', rejection });
     }
 }
 /**
- * The failure once the last attempt got no HTTP response (#173). The earlier
- * attempts may have drawn a 5xx: a 503, a 502, then a reset ends here too, so
- * the message claims only the last. Message and `data` are composed here from
- * the host, the attempt count, and the last attempt's transport code or
- * timeout: the runtime's own text is developer-facing (Bun's advice to pass
- * `verbose: true`, its "Is the computer able to access the url?"), and Bun's
- * rejection carries the full request URL on `path`. The rejection rides
- * `cause`, which the log records and the caller never sees.
+ * The failure once SEC gave no complete, readable answer. For the two ladder cases
+ * — no HTTP response (#173), a body that failed to read (#181) — the earlier
+ * attempts may have drawn a 5xx or failed the other way, so the message claims only
+ * the last. Message and `data` are composed here from the host, the attempt count,
+ * and the last attempt's transport code or timeout: the runtime's own text is
+ * developer-facing (Bun's advice to pass `verbose: true`, its "Is the computer able
+ * to access the url?"), and Bun carries the full request URL on `path` and, for
+ * some body failures, in its message. The rejection rides `cause`, which the log
+ * records and the caller never sees. A ladder the call's failure budget ended
+ * names the attempt it ended on and the budget (#179).
  */
-function secUnreachable(url, last) {
+function secUnreachable(url, last, end) {
     const host = new URL(url).hostname;
-    const ending = last.timedOut
-        ? `got no response headers within ${ATTEMPT_HEADERS_TIMEOUT_MS / 1000} s`
-        : `ended with ${transportCode(last.rejection) ?? 'a network error that carried no code'}`;
-    return serviceUnavailable(`No HTTP response from SEC EDGAR (${host}) on the last of ${MAX_RETRIES} attempts, which ${ending}.`, {
-        reason: SEC_UNREACHABLE_REASON,
-        retryable: true,
-        url,
-        recovery: {
-            hint: `SEC EDGAR (${host}) sent no HTTP response to the last attempt — a network failure between this server and SEC, not a problem with the request. Retry the same call in a minute.`,
-        },
-    }, { cause: last.rejection });
+    const { message, hint } = unreadableText(host, last, end);
+    return serviceUnavailable(message, { reason: SEC_UNREACHABLE_REASON, retryable: true, url, recovery: { hint } }, last.kind === 'budget_spent' ? undefined : { cause: last.rejection });
+}
+/** The message and recovery hint for each way SEC's answer was unreadable. */
+function unreadableText(host, last, end) {
+    const transportEnding = (rejection) => `ended with ${transportCode(rejection) ?? 'a network error that carried no code'}`;
+    const onAttempt = end?.budgetStopped
+        ? `attempt ${end.attempt} of ${MAX_RETRIES}`
+        : `the last of ${MAX_RETRIES} attempts`;
+    const close = end?.budgetStopped ? `; ${BUDGET_STOP_TEXT}.` : '.';
+    switch (last.kind) {
+        case 'unanswered':
+            return {
+                message: `No HTTP response from SEC EDGAR (${host}) on ${onAttempt}, which ${last.timedOut ? `got no response headers within ${seconds(last.capMs)} s` : transportEnding(last.rejection)}${close}`,
+                hint: `SEC EDGAR (${host}) sent no HTTP response to the last attempt — a network failure between this server and SEC, not a problem with the request. Retry the same call in a minute.`,
+            };
+        case 'body_failed':
+            return {
+                message: `The response body from SEC EDGAR (${host}) failed to read on ${onAttempt}, which ${last.stalled ? `got no body bytes for ${seconds(last.capMs)} s` : transportEnding(last.rejection)}${close}`,
+                hint: `SEC EDGAR (${host}) answered the last attempt, but its response body broke off or stalled before it finished — a network failure between this server and SEC, not a problem with the request. Retry the same call in a minute.`,
+            };
+        case 'budget_spent':
+            return {
+                message: `No request sent to SEC EDGAR (${host}): ${BUDGET_STOP_TEXT}, which its earlier requests spent.`,
+                hint: `SEC EDGAR (${host}) failed this call's earlier requests until its budget for SEC failures ran out — a network failure between this server and SEC, not a problem with the request. Retry the same call in a minute.`,
+            };
+        case 'not_json':
+            return {
+                message: `SEC EDGAR (${host}) answered, but its response body is not the JSON this request expects.`,
+                hint: `SEC EDGAR (${host}) answered with something other than the JSON it serves for this request, such as a temporary error page — not a problem with the request. Retry the same call in a minute.`,
+            };
+        default: {
+            const unhandled = last;
+            return unhandled;
+        }
+    }
 }
 /** An identifier-shaped transport code: `ECONNRESET`, `EAI_AGAIN`, `UND_ERR_CONNECT_TIMEOUT`. */
 const TRANSPORT_CODE = /^[A-Za-z][A-Za-z0-9_]*$/;
 /**
- * The transport code on a `fetch` rejection. Bun sets it on the rejection itself
- * (`code: 'ECONNRESET'`, no `cause`); Node's undici rejects with
- * `TypeError('fetch failed')` and sets it on `cause`. Read from the field, never
- * the message, whose wording differs by runtime and version.
+ * The transport code on a `fetch` or body-read rejection. Bun sets it on the
+ * rejection itself (`code: 'ECONNRESET'`, `'InvalidHTTPResponse'`, `'ZlibError'`,
+ * no `cause`); Node's undici rejects with `TypeError('fetch failed')` or, mid-body,
+ * `TypeError('terminated')` and sets it on `cause` — when it has one: its
+ * chunk-framing `HTTPParserError` carries none. Read from the field, never the
+ * message, whose wording differs by runtime and version.
  */
 function transportCode(rejection) {
     const codeOf = (value) => {