@cyanheads/secedgar-mcp-server 0.19.0 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/AGENTS.md +15 -6
  2. package/CLAUDE.md +15 -6
  3. package/README.md +3 -1
  4. package/changelog/0.19.x/0.19.1.md +35 -0
  5. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +16 -2
  6. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  7. package/dist/mcp-server/tools/definitions/company-search.tool.js +177 -32
  8. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  9. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +8 -8
  10. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  11. package/dist/mcp-server/tools/definitions/find-holders.tool.js +2 -9
  12. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  13. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +8 -8
  14. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  15. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +3 -10
  16. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  17. package/dist/mcp-server/tools/definitions/index.d.ts +20 -13
  18. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +8 -8
  20. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/search-filings.tool.js +4 -11
  22. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/resolved-as.d.ts +4 -2
  24. package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/resolved-as.js +5 -3
  26. package/dist/mcp-server/tools/resolved-as.js.map +1 -1
  27. package/dist/mcp-server/tools/sec-upstream-errors.d.ts +15 -1
  28. package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -1
  29. package/dist/mcp-server/tools/sec-upstream-errors.js +15 -1
  30. package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -1
  31. package/dist/services/edgar/data/former-tickers.json +24159 -0
  32. package/dist/services/edgar/edgar-api-service.d.ts +92 -16
  33. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  34. package/dist/services/edgar/edgar-api-service.js +268 -69
  35. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  36. package/dist/services/edgar/former-tickers.d.ts +47 -0
  37. package/dist/services/edgar/former-tickers.d.ts.map +1 -0
  38. package/dist/services/edgar/former-tickers.js +77 -0
  39. package/dist/services/edgar/former-tickers.js.map +1 -0
  40. package/dist/services/edgar/types.d.ts +9 -4
  41. package/dist/services/edgar/types.d.ts.map +1 -1
  42. package/package.json +4 -3
  43. package/server.json +3 -3
  44. package/skills/secedgar-guide/SKILL.md +1 -1
@@ -4,14 +4,16 @@
4
4
  * with backoff, CIK resolution, and ticker/entity caching.
5
5
  * @module services/edgar/edgar-api-service
6
6
  */
7
- import { McpError, notFound, rateLimited, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
8
- import { createPacer, httpErrorFromResponse, isRecord, logger, requestContextService, withExtra, } from '@cyanheads/mcp-ts-core/utils';
7
+ import { JsonRpcErrorCode, McpError, notFound, rateLimited, serviceUnavailable, } from '@cyanheads/mcp-ts-core/errors';
8
+ import { createPacer, httpErrorFromResponse, httpStatusToErrorCode, isRecord, logger, requestContextService, withExtra, } from '@cyanheads/mcp-ts-core/utils';
9
9
  import { parseDocument } from 'htmlparser2';
10
10
  import { getServerConfig } from '../../config/server-config.js';
11
11
  import { getEdgarMirror } from './mirror/index.js';
12
12
  import { CALL_FAILURE_BUDGET_MS, CallScope } from './call-scope.js';
13
13
  import formerNamesData from './data/former-names.json' with { type: 'json' };
14
+ import formerTickersData from './data/former-tickers.json' with { type: 'json' };
14
15
  import { parseFilingHeaders, parseSubmissionHeader, } from './filing-headers.js';
16
+ import { buildFormerTickerIndex, readFormerTicker, withEarlierHolders, } from './former-tickers.js';
15
17
  import { listedSymbol, readTickerSpelling } from './listing-codes.js';
16
18
  import { MF_TICKERS_URL, TICKERS_URL } from './mirror/types.js';
17
19
  import { trigramScorer } from './trigram-similarity.js';
@@ -193,6 +195,41 @@ const TRIGRAM_THRESHOLD = 0.3;
193
195
  const TRIGRAM_TOP_N = 3;
194
196
  /** The fund slice where nothing is read live: strict mirror mode. */
195
197
  const NO_LIVE_FUNDS = { retryAt: undefined, rows: [] };
198
+ /**
199
+ * An entity-index hit's name and first ticker (#236). SEC writes a listed entity's tickers
200
+ * after its name (`SCHWAB CHARLES CORP (SCHW, SCHW-PJ, SCHW-PD)`) and again in a `tickers`
201
+ * field its schema does not document (`SCHW, SCHW-PJ, SCHW-PD`). That field is the
202
+ * authority: only the parenthetical repeating it is cut, so one SEC lists no tickers for
203
+ * (`DEERFIELD HOLDINGS INC (DE)`) stays in the name and never becomes a ticker.
204
+ */
205
+ function splitEntityTickers(source) {
206
+ const tickers = typeof source.tickers === 'string' ? source.tickers : '';
207
+ const ticker = tickers.split(',')[0]?.trim();
208
+ if (!ticker)
209
+ return { name: source.entity };
210
+ const listed = ` (${tickers})`;
211
+ return {
212
+ name: source.entity.endsWith(listed) ? source.entity.slice(0, -listed.length) : source.entity,
213
+ ticker,
214
+ };
215
+ }
216
+ /** A subsidiaries exhibit's type: `EX-21`, `EX-21.1`, never `EX-210`. */
217
+ const SUBSIDIARIES_EXHIBIT = /^EX-21(?!\d)/i;
218
+ /**
219
+ * The name a full-text hit's `display_names` records for `cik` (`ROPER TECHNOLOGIES INC
220
+ * (ROP) (CIK 0000882835)` → `ROPER TECHNOLOGIES INC`), or `undefined` when none names it.
221
+ */
222
+ function filerNameIn(displayNames, cik) {
223
+ const entry = displayNames?.find((name) => name.includes(`(CIK ${cik})`));
224
+ return entry === undefined ? undefined : cleanDisplayName(entry);
225
+ }
226
+ /**
227
+ * `name` as the phrase `findSubsidiaryParents` searches for: in double quotes, with any
228
+ * double quote inside it dropped, since one would end the phrase early.
229
+ */
230
+ export function subsidiaryPhrase(name) {
231
+ return `"${name.replaceAll('"', '').trim()}"`;
232
+ }
196
233
  // ---------------------------------------------------------------------------
197
234
  // Corporate-suffix normalization
198
235
  // ---------------------------------------------------------------------------
@@ -294,8 +331,11 @@ export function foldNamePunctuation(name) {
294
331
  export function joinSpacedInitials(name) {
295
332
  return name.replace(/(?<=(?:^| )\p{L}) (?=\p{L}(?: |$))/gu, '');
296
333
  }
297
- /** A letter or digit: the characters a name's word boundary falls between (#218). */
298
- const NAME_WORD_CHAR = /[\p{L}\p{N}]/u;
334
+ /**
335
+ * A letter or digit: the characters a name's word boundary falls between (#218). A query
336
+ * with none names no company.
337
+ */
338
+ export const NAME_WORD_CHAR = /[\p{L}\p{N}]/u;
299
339
  /**
300
340
  * Whether index `at` of `text` is a word boundary — a letter or digit on exactly one side,
301
341
  * regex `\b` read over every script (#218). Either end of the string counts as a side
@@ -318,6 +358,97 @@ export function containsFromWordStart(name, query) {
318
358
  return false;
319
359
  }
320
360
  const NAME_TIERS = [0, 1, 2, 3, 4];
361
+ /** The loosest exact tier: 0–2 are exact, 3 is prefix, 4 is substring. */
362
+ export const LAST_EXACT_TIER = 2;
363
+ /** The comparison forms of `query` (trimmed) that {@link nameTier} reads. */
364
+ export function nameQuery(query) {
365
+ const lower = query.trim().toLowerCase();
366
+ const folded = foldNamePunctuation(lower);
367
+ const joined = joinSpacedInitials(folded);
368
+ return {
369
+ lower,
370
+ lowerNormalized: normalizeCompanySuffix(lower),
371
+ folded,
372
+ foldedNormalized: normalizeCompanySuffix(folded),
373
+ joined,
374
+ joinedNormalized: normalizeCompanySuffix(joined),
375
+ };
376
+ }
377
+ /**
378
+ * The {@link NameTier} at which `name` (any case) matches `query`, or `undefined` when no
379
+ * tier reaches it. The three exact tiers also accept a suffix-normalized equality (#107)
380
+ * and the name minus its terminal suffix, so `Apple` names `Apple Inc.` exactly (#155);
381
+ * the query's own suffix is never dropped, so `Toro Co` never meets `TORO CORP.`.
382
+ */
383
+ export function nameTier(name, query) {
384
+ // A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
385
+ const isExact = (candidate, form, formNormalized) => candidate === form ||
386
+ normalizeCompanySuffix(candidate) === formNormalized ||
387
+ (candidate.startsWith(form) && stripCompanySuffix(candidate) === form);
388
+ const lowerName = name.toLowerCase();
389
+ if (isExact(lowerName, query.lower, query.lowerNormalized))
390
+ return 0;
391
+ const foldedName = foldNamePunctuation(lowerName);
392
+ if (isExact(foldedName, query.folded, query.foldedNormalized))
393
+ return 1;
394
+ const joinedName = joinSpacedInitials(foldedName);
395
+ // With no initials joined on either side, this repeats the folded tier's comparison.
396
+ if ((joinedName !== foldedName || query.joined !== query.folded) &&
397
+ isExact(joinedName, query.joined, query.joinedNormalized)) {
398
+ return 2;
399
+ }
400
+ if (joinedName.startsWith(query.joined) && isWordBoundary(joinedName, query.joined.length)) {
401
+ return 3;
402
+ }
403
+ return containsFromWordStart(lowerName, query.lower) ? 4 : undefined;
404
+ }
405
+ /** A joined form's words, sorted: the word-order tier's comparison key (#236). */
406
+ function sortedWords(joined) {
407
+ return joined.split(' ').sort().join(' ');
408
+ }
409
+ /**
410
+ * The word-order tier's key for a query: its joined form with the terminal suffix normalized,
411
+ * words sorted — the query's own suffix is never dropped (#155). `undefined` for one word,
412
+ * which the exact tiers already compare.
413
+ */
414
+ function wordOrderQueryKey(query) {
415
+ return query.joined.includes(' ') ? sortedWords(query.joinedNormalized) : undefined;
416
+ }
417
+ /**
418
+ * The keys a registry or former name meets the word-order tier under (#236): its words once
419
+ * folded and its initials joined, sorted, with the terminal suffix normalized
420
+ * (`normalizeCompanySuffix`) and, when it has one, dropped (`stripCompanySuffix`) — the exact
421
+ * tiers' rules — so `SCHWAB CHARLES CORP` meets `Charles Schwab Corp` and `Charles Schwab`. A
422
+ * key of one word is left out, since a query of one word never reaches the tier.
423
+ */
424
+ function wordOrderKeys(name) {
425
+ const joined = joinSpacedInitials(foldNamePunctuation(name.toLowerCase()));
426
+ const stripped = stripCompanySuffix(joined);
427
+ return [normalizeCompanySuffix(joined), ...(stripped === undefined ? [] : [stripped])]
428
+ .filter((form) => form.includes(' '))
429
+ .map(sortedWords);
430
+ }
431
+ /** `entries` with each CIK's first entry only, in order: a company's current and former names can both match. */
432
+ function matchesByCik(entries) {
433
+ const seen = new Set();
434
+ return entries.filter((entry) => !seen.has(entry.cik) && seen.add(entry.cik));
435
+ }
436
+ /** Word-order key → the entries meeting it, in `entries` order (#236). */
437
+ function buildWordOrderIndex(entries) {
438
+ const index = new Map();
439
+ for (const entry of entries) {
440
+ if (!entry.name)
441
+ continue;
442
+ for (const key of wordOrderKeys(entry.name)) {
443
+ const hits = index.get(key);
444
+ if (hits)
445
+ hits.push(entry);
446
+ else
447
+ index.set(key, [entry]);
448
+ }
449
+ }
450
+ return index;
451
+ }
321
452
  // ---------------------------------------------------------------------------
322
453
  // Near-match company suggestions
323
454
  // ---------------------------------------------------------------------------
@@ -371,6 +502,8 @@ class EdgarApiService {
371
502
  submissionsCache = new LruMap(CACHE_BYTE_LIMITS.submissions);
372
503
  /** The newest XBRL acceptance each cached submissions document records, worked out once per document (#234). */
373
504
  xbrlRecency = new WeakMap();
505
+ /** Each ticker index's word-order keys, built on the first query that reaches the tier (#236). */
506
+ wordOrderIndexes = new WeakMap();
374
507
  /**
375
508
  * Filers whose recency read or live point read SEC just failed, keyed by padded CIK, each
376
509
  * mapped to the instant the mirror stops answering for it unasked (#234), at most
@@ -444,7 +577,8 @@ class EdgarApiService {
444
577
  * Resolve a query (ticker, name, or CIK) to company match(es).
445
578
  * - Numeric input → direct CIK lookup
446
579
  * - 1-5 letters in any case, or anything typed in uppercase → the ticker lookup (O(1)):
447
- * the symbol as listed, else a dotted share class in its hyphenated form (#110)
580
+ * the symbol as listed, else a dotted share class in its hyphenated form (#110), with a
581
+ * `reading` naming any earlier, different holder of the symbol (#237)
448
582
  * - Typed in uppercase, unlisted → the ticker-spelling readings (`readTickerSpelling`,
449
583
  * #235): a US venue code dropped (`UEC.N`), a preferred class run together (`CFGPH`), a
450
584
  * root listed only as classes (`GLOP`), each match carrying `reading`; a non-US listing
@@ -453,8 +587,11 @@ class EdgarApiService {
453
587
  * - Otherwise → name search (exact as written; exact once commas, periods, and
454
588
  * apostrophes are folded out and whitespace runs collapse; exact once spaced initials
455
589
  * join; prefix of the joined form ending at a word boundary; substring as written
456
- * starting at one — resolved within the best tier a current name reaches), then, for
457
- * input not typed in uppercase, the ticker lookup
590
+ * starting at one — resolved within the best tier a current name reaches). Typed in
591
+ * uppercase, a former ticker (#237) answers ahead of it unless a current name is the
592
+ * input exactly, or the former holder is listed no more and the names find one company
593
+ * - No name tier matching and two or more words → the word-order tier (#236)
594
+ * - Then, for input not typed in uppercase, the ticker lookup, then a former ticker
458
595
  * Returns a single match, an array of multiple matches, or an empty array (no match).
459
596
  * Multiple matches are every candidate of that tier, deduplicated by CIK, current names
460
597
  * first, never cut: a consumer shows the first ten through `ambiguousMatches` and counts
@@ -481,14 +618,20 @@ class EdgarApiService {
481
618
  // write BRK.B where the file lists BRK-B, and no registrant has both forms on file (#110).
482
619
  const upper = trimmed.toUpperCase();
483
620
  const typedUpper = trimmed === upper;
621
+ // The listing always answers; a symbol an earlier, different company held carries a reading
622
+ // naming it (`XOM` stays ExxonMobil Holdings Corp and names EXXON MOBIL CORP, #237).
484
623
  const listed = listedSymbol(upper, cache.byTicker);
485
- if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper)))
486
- return listed;
624
+ if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper))) {
625
+ return withEarlierHolders(listed, cache);
626
+ }
487
627
  // Uppercase spellings vendors write for listed symbols, ahead of the name passes, which
488
628
  // otherwise read `GS.K` as GSK plc through the period fold (#235).
489
629
  const reading = readTickerSpelling(trimmed, cache);
490
630
  if (reading !== undefined)
491
631
  return reading;
632
+ // An uppercase symbol the file no longer lists reads as the company that held it last
633
+ // (#237), weighed against the name passes below.
634
+ const formerTicker = typedUpper ? readFormerTicker(trimmed, cache) : undefined;
492
635
  // A query with no letter or digit names no company: `.` would fold to an empty string
493
636
  // that starts every name (#219).
494
637
  if (!NAME_WORD_CHAR.test(trimmed))
@@ -508,32 +651,7 @@ class EdgarApiService {
508
651
  // `helix acquisition corp iii` — and a substring, matched as written, starts at one, so
509
652
  // `SY Bancorp` never names Embassy Bancorp; a query ending mid-word (`Berkshire Hath`)
510
653
  // still matches there when the name as written contains it.
511
- const lower = trimmed.toLowerCase();
512
- const lowerNormalized = normalizeCompanySuffix(lower);
513
- const folded = foldNamePunctuation(lower);
514
- const foldedNormalized = normalizeCompanySuffix(folded);
515
- const joined = joinSpacedInitials(folded);
516
- const joinedNormalized = normalizeCompanySuffix(joined);
517
- // A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
518
- const isExact = (name, form, formNormalized) => name === form ||
519
- normalizeCompanySuffix(name) === formNormalized ||
520
- (name.startsWith(form) && stripCompanySuffix(name) === form);
521
- const tierOf = (name) => {
522
- if (isExact(name, lower, lowerNormalized))
523
- return 0;
524
- const foldedName = foldNamePunctuation(name);
525
- if (isExact(foldedName, folded, foldedNormalized))
526
- return 1;
527
- const joinedName = joinSpacedInitials(foldedName);
528
- // With no initials joined on either side, this repeats the folded tier's comparison.
529
- if ((joinedName !== foldedName || joined !== folded) &&
530
- isExact(joinedName, joined, joinedNormalized)) {
531
- return 2;
532
- }
533
- if (joinedName.startsWith(joined) && isWordBoundary(joinedName, joined.length))
534
- return 3;
535
- return containsFromWordStart(name, lower) ? 4 : undefined;
536
- };
654
+ const forms = nameQuery(trimmed);
537
655
  // Current names are registry rows, which carry a ticker; former names (the committed
538
656
  // asset) carry none. Resolution runs within the best tier a current name reaches —
539
657
  // several CIKs there are the ambiguity, and the tiers below are not listed. A former
@@ -545,7 +663,7 @@ class EdgarApiService {
545
663
  for (const entry of cache.allEntries) {
546
664
  if (!entry.name)
547
665
  continue;
548
- const tier = tierOf(entry.name.toLowerCase());
666
+ const tier = nameTier(entry.name, forms);
549
667
  if (tier === undefined)
550
668
  continue;
551
669
  (entry.ticker === undefined ? former : current)[tier].push(entry);
@@ -557,21 +675,47 @@ class EdgarApiService {
557
675
  ...current[bestCurrent],
558
676
  ...NAME_TIERS.filter((tier) => tier <= bestCurrent).flatMap((tier) => former[tier]),
559
677
  ];
560
- // Dedup by CIK (current + former names may match the same registrant).
561
- const seen = new Set();
562
- const deduped = [];
563
- for (const entry of candidates) {
564
- if (!seen.has(entry.cik)) {
565
- seen.add(entry.cik);
566
- deduped.push(entry);
567
- }
678
+ const named = matchesByCik(candidates);
679
+ // The former ticker answers ahead of the names (`BK` is BNY, not BK Technologies, whose
680
+ // name only starts with it; `STR` starts many names) unless a current name is the input
681
+ // exactly (`CHUBB` is Chubb Ltd, not CommerceHub), or its holder is listed no more and the
682
+ // names find one company (`DINE` stays Dine Brands, not Rewards Network) (#237).
683
+ const exactCurrent = bestCurrent !== undefined && bestCurrent <= LAST_EXACT_TIER;
684
+ if (formerTicker &&
685
+ !exactCurrent &&
686
+ (formerTicker.ticker !== undefined || named.length !== 1)) {
687
+ return formerTicker;
568
688
  }
569
- if (deduped.length > 0) {
570
- return deduped.length === 1 ? deduped[0] : deduped;
689
+ if (named.length > 0)
690
+ return named.length === 1 ? named[0] : named;
691
+ // When no tier reaches any name, a query of two or more words may reorder one: SEC writes
692
+ // `SCHWAB CHARLES CORP` for `Charles Schwab` (#236). Current names before former ones (#155).
693
+ const key = wordOrderQueryKey(forms);
694
+ if (key !== undefined) {
695
+ const hits = this.wordOrderIndex(cache.allEntries).get(key) ?? [];
696
+ const reordered = matchesByCik([
697
+ ...hits.filter((entry) => entry.ticker !== undefined),
698
+ ...hits.filter((entry) => entry.ticker === undefined),
699
+ ]);
700
+ if (reordered.length > 0) {
701
+ return reordered.length === 1 ? reordered[0] : reordered;
702
+ }
571
703
  }
572
704
  // A symbol typed in mixed or lower case, outside the short alphabetic shape, keeps the name
573
- // passes ahead of its ticker lookup (`brk.b`, `Bf.b`).
574
- return listed ?? [];
705
+ // passes ahead of its ticker lookup (`brk.b`, `Bf.b`), and so does a former ticker (`amrk`,
706
+ // while `bk` keeps the name passes' BK Technologies, #237).
707
+ if (listed)
708
+ return withEarlierHolders(listed, cache);
709
+ return (typedUpper ? undefined : readFormerTicker(trimmed, cache)) ?? [];
710
+ }
711
+ /** The word-order keys of one ticker index's entries, built once per index (#236). */
712
+ wordOrderIndex(entries) {
713
+ let index = this.wordOrderIndexes.get(entries);
714
+ if (!index) {
715
+ index = buildWordOrderIndex(entries);
716
+ this.wordOrderIndexes.set(entries, index);
717
+ }
718
+ return index;
575
719
  }
576
720
  /**
577
721
  * Resolve an entity name to CIK candidates via EFTS entity-autocomplete
@@ -585,7 +729,9 @@ class EdgarApiService {
585
729
  * Distinct from `searchFilings`: same URL path, different query param (`keysTyped`)
586
730
  * and response shape (`_source.entity`, not the filing-document `_source`). A
587
731
  * failure of the search backend throws `efts_degraded_response` like a search's,
588
- * never reads as no match (#206). The name is escaped like a search's `q` (#205).
732
+ * never reads as no match (#206). The name is escaped like a search's `q` (#205). A
733
+ * listed entity's name comes back without the ticker list SEC appends to it, its first
734
+ * ticker beside it (#236).
589
735
  */
590
736
  async resolveEntityByName(name, scope) {
591
737
  const url = new URL('https://efts.sec.gov/LATEST/search-index');
@@ -603,17 +749,57 @@ class EdgarApiService {
603
749
  const matches = [];
604
750
  for (const hit of hits) {
605
751
  const cik = hit._id?.padStart(10, '0');
606
- const entity = hit._source?.entity;
607
- if (!cik || !entity || seen.has(cik))
752
+ const source = hit._source;
753
+ if (!cik || !source?.entity || seen.has(cik))
608
754
  continue;
609
755
  seen.add(cik);
610
- matches.push({ cik, name: entity });
756
+ matches.push({ cik, ...splitEntityTickers(source) });
611
757
  }
612
758
  // A total with no numeric value reads as none, as searchFilings' shape guard reads it (#61):
613
759
  // the ambiguity sentence formats `value`, so a malformed one would throw a raw TypeError.
614
760
  const total = response.hits.total;
615
761
  return { matches, total: typeof total?.value === 'number' ? total : undefined };
616
762
  }
763
+ /**
764
+ * The filers whose 10-K subsidiaries exhibit (EX-21) holds `name` as a phrase (#236): one
765
+ * EDGAR full-text search for {@link subsidiaryPhrase} over 10-Ks, its first 100 documents.
766
+ * Only an exhibit whose type is EX-21 names a parent — the other 10-K documents that
767
+ * mention a private company are mostly a lender's schedule of investments or a
768
+ * competitor's or customer's narrative. Each filer of such an exhibit counts, since a
769
+ * combined report lists every co-registrant, and is reported at its newest one. Filers
770
+ * SEC's ticker file lists come first, then the newest exhibit, then search order. Fails
771
+ * as `searchFilings` fails.
772
+ */
773
+ async findSubsidiaryParents(name, scope) {
774
+ const response = await this.searchFilings({ query: subsidiaryPhrase(name), forms: ['10-K'], size: 100 }, scope);
775
+ // Insertion order is search order: a newer exhibit updates a filer in place.
776
+ const found = new Map();
777
+ for (const { _source: source } of response.hits.hits) {
778
+ if (!SUBSIDIARIES_EXHIBIT.test(source.file_type ?? ''))
779
+ continue;
780
+ for (const filer of source.ciks ?? []) {
781
+ const cik = filer.padStart(10, '0');
782
+ const known = found.get(cik);
783
+ if (known && known.filingDate >= source.file_date)
784
+ continue;
785
+ const filerName = filerNameIn(source.display_names, cik);
786
+ found.set(cik, {
787
+ cik,
788
+ accessionNumber: source.adsh,
789
+ filingDate: source.file_date,
790
+ ...(filerName !== undefined && { name: filerName }),
791
+ });
792
+ }
793
+ }
794
+ const cache = await this.getTickerCache(scope);
795
+ const parents = [...found.values()].map((parent) => {
796
+ const ticker = cache.byCik.get(parent.cik)?.ticker;
797
+ return ticker === undefined ? parent : { ...parent, ticker };
798
+ });
799
+ // `sort` is stable, so search order settles what the listing and the date leave tied.
800
+ return parents.sort((a, b) => Number(b.ticker !== undefined) - Number(a.ticker !== undefined) ||
801
+ b.filingDate.localeCompare(a.filingDate));
802
+ }
617
803
  /** Reverse lookup: CIK → ticker symbol. */
618
804
  async cikToTicker(cik, scope) {
619
805
  const cache = await this.getTickerCache(scope);
@@ -1128,15 +1314,16 @@ class EdgarApiService {
1128
1314
  * when `cutoff` is given — and `null` on 404. A body the ladder has no use for — a
1129
1315
  * 404's, a retried 5xx's, a 429's, one that lands as the caller cancels — is
1130
1316
  * cancelled unread (#188); an error the last attempt earns carries a bounded head
1131
- * of its body, read like any other (#202). The body is read inside the ladder
1132
- * (#181): a 5xx, an attempt that got no HTTP response, a 2xx whose body failed to
1133
- * read, and — for a request that opts in with `backendFailure` — a 2xx whose whole
1134
- * body relays a transient failure of the search backend (#206) all retry up to
1135
- * `MAX_RETRIES` attempts, and then the last attempt decides — a 5xx throws
1136
- * `sec_unavailable` (#233), a backend failure `efts_degraded_response`, the
1137
- * other two `sec_unreachable`. Other non-OK statuses throw at once, as does
1138
- * the local refusal while SEC's rate-limit block is active, and the pacer's
1139
- * `RequestCancelled` — those are `McpError`s from `send()`, never retried.
1317
+ * of its body on its `cause`, for the log only, read like any other (#202, #244).
1318
+ * The body is read inside the ladder (#181): a 5xx, an attempt that got no HTTP
1319
+ * response, a 2xx whose body failed to read, and — for a request that opts in
1320
+ * with `backendFailure` — a 2xx whose whole body relays a transient failure of
1321
+ * the search backend (#206) all retry up to `MAX_RETRIES` attempts, and then
1322
+ * the last attempt decides — a 5xx throws `sec_unavailable` (#233), a backend
1323
+ * failure `efts_degraded_response`, the other two `sec_unreachable`. Other
1324
+ * non-OK statuses throw at once, as does the local refusal while SEC's
1325
+ * rate-limit block is active, and the pacer's `RequestCancelled` — those are
1326
+ * `McpError`s from `send()`, never retried.
1140
1327
  *
1141
1328
  * Every failed attempt and every backoff is charged to the call's failure budget,
1142
1329
  * and the ladder ends early once the budget cannot cover another backoff and
@@ -1221,9 +1408,10 @@ class EdgarApiService {
1221
1408
  * mapping's `data`: `url`, `status`, and SEC's `Retry-After` when it sends one.
1222
1409
  *
1223
1410
  * An HTTP answer's body is read under `scope` for the error's diagnostic
1224
- * (`errorBodyHead`, #202) — except a 429's, and the one `scope` is `null` for: a
1225
- * retried 5xx whose body was released before its backoff. Either is built without
1226
- * a body, the 429's cancelled unread (#188).
1411
+ * (`errorBodyHead`, #202), which rides the error's `cause` to the log and never its
1412
+ * `data` (#244) — except a 429's, and the one `scope` is `null` for: a retried 5xx
1413
+ * whose body was released before its backoff. Either is built without a body, the
1414
+ * 429's cancelled unread (#188).
1227
1415
  */
1228
1416
  async ladderFailure(url, last, end, scope) {
1229
1417
  if (last.kind === 'backend_failed')
@@ -1255,20 +1443,19 @@ class EdgarApiService {
1255
1443
  };
1256
1444
  }
1257
1445
  // A 429's body is SEC's full HTML block page; the hint above carries everything
1258
- // actionable, so the markup is not forwarded (#112).
1446
+ // actionable, so the markup is not read (#112).
1447
+ let body;
1259
1448
  if (scope === null || status === 429) {
1260
1449
  await discardBody(response);
1261
1450
  }
1262
1451
  else {
1263
- const body = await errorBodyHead(response, scope);
1264
- // The two names `httpErrorFromResponse` gives a body it captures itself.
1265
- if (body !== undefined)
1266
- Object.assign(data, { body, responseBody: body });
1452
+ body = await errorBodyHead(response, scope);
1267
1453
  }
1268
1454
  const error = await httpErrorFromResponse(response, {
1269
1455
  service: 'SEC EDGAR',
1270
1456
  data,
1271
1457
  captureBody: false,
1458
+ ...(body !== undefined && { cause: errorBodyCause(status, body) }),
1272
1459
  });
1273
1460
  if (!RETRYABLE_STATUSES.has(status))
1274
1461
  return error;
@@ -1555,6 +1742,7 @@ class EdgarApiService {
1555
1742
  byCik,
1556
1743
  bySeriesId,
1557
1744
  byTicker,
1745
+ formerTickers: buildFormerTickerIndex(formerTickersData),
1558
1746
  fundRetryAt: funds.retryAt,
1559
1747
  loadedAt,
1560
1748
  };
@@ -2091,6 +2279,17 @@ async function errorBodyHead(response, scope) {
2091
2279
  return read.text;
2092
2280
  return read.text === '' ? undefined : `${read.text}…`;
2093
2281
  }
2282
+ /**
2283
+ * An error response's diagnostic body ({@link errorBodyHead}) as the `cause` of the
2284
+ * error built from that response (#244). The call's failure log record writes every
2285
+ * cause's `data` under the call's `requestId`, and no client envelope carries a cause.
2286
+ * On the error's own `data` the body would reach the caller as given: the framework
2287
+ * keeps off the wire only a body its own capture read, and that capture has no stall
2288
+ * bound or signal (#202).
2289
+ */
2290
+ function errorBodyCause(status, body) {
2291
+ return new McpError(httpStatusToErrorCode(status) ?? JsonRpcErrorCode.InternalError, `SEC EDGAR's HTTP ${status} response body.`, { body });
2292
+ }
2094
2293
  /**
2095
2294
  * `text`'s first {@link ERROR_BODY_LIMIT_BYTES} bytes — never a partial code point —
2096
2295
  * and `…`, or `undefined` when the whole of it fits: the bound on every upstream