@cyanheads/secedgar-mcp-server 0.18.1 → 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 (141) hide show
  1. package/AGENTS.md +36 -24
  2. package/CLAUDE.md +36 -24
  3. package/README.md +16 -12
  4. package/changelog/0.19.x/0.19.0.md +47 -0
  5. package/changelog/0.19.x/0.19.1.md +35 -0
  6. package/changelog/template.md +10 -3
  7. package/dist/config/server-config.js +2 -2
  8. package/dist/config/server-config.js.map +1 -1
  9. package/dist/index.js +27 -9
  10. package/dist/index.js.map +1 -1
  11. package/dist/mcp-server/tools/dataset-schema.d.ts +14 -0
  12. package/dist/mcp-server/tools/dataset-schema.d.ts.map +1 -0
  13. package/dist/mcp-server/tools/dataset-schema.js +16 -0
  14. package/dist/mcp-server/tools/dataset-schema.js.map +1 -0
  15. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts +44 -14
  16. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  17. package/dist/mcp-server/tools/definitions/company-search.tool.js +197 -62
  18. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  19. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts +26 -12
  20. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  21. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +41 -39
  22. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  23. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts +12 -3
  24. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +23 -9
  26. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +2 -2
  28. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
  29. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts +16 -16
  30. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +17 -17
  32. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts +26 -12
  34. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  35. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +15 -37
  36. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  37. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts +36 -20
  38. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  39. package/dist/mcp-server/tools/definitions/find-holders.tool.js +26 -41
  40. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  41. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts +28 -12
  42. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  43. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +30 -44
  44. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  45. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts +50 -14
  46. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/get-filing.tool.js +193 -59
  48. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts +14 -6
  50. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
  51. package/dist/mcp-server/tools/definitions/get-financials.tool.js +38 -41
  52. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  53. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts +28 -12
  54. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  55. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +22 -35
  56. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  57. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +28 -12
  58. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  59. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +22 -31
  60. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  61. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts +36 -20
  62. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  63. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +22 -39
  64. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  65. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts +28 -12
  66. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  67. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +23 -32
  68. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  69. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts +16 -7
  70. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
  71. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +24 -32
  72. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
  73. package/dist/mcp-server/tools/definitions/index.d.ts +232 -101
  74. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  75. package/dist/mcp-server/tools/definitions/search-concepts.tool.js +3 -3
  76. package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
  77. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +46 -20
  78. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  79. package/dist/mcp-server/tools/definitions/search-filings.tool.js +126 -68
  80. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  81. package/dist/mcp-server/tools/resolved-as.d.ts +10 -0
  82. package/dist/mcp-server/tools/resolved-as.d.ts.map +1 -0
  83. package/dist/mcp-server/tools/resolved-as.js +13 -0
  84. package/dist/mcp-server/tools/resolved-as.js.map +1 -0
  85. package/dist/mcp-server/tools/sec-upstream-errors.d.ts +44 -0
  86. package/dist/mcp-server/tools/sec-upstream-errors.d.ts.map +1 -0
  87. package/dist/mcp-server/tools/sec-upstream-errors.js +48 -0
  88. package/dist/mcp-server/tools/sec-upstream-errors.js.map +1 -0
  89. package/dist/services/canvas-bridge/canvas-bridge.d.ts +98 -45
  90. package/dist/services/canvas-bridge/canvas-bridge.d.ts.map +1 -1
  91. package/dist/services/canvas-bridge/canvas-bridge.js +137 -126
  92. package/dist/services/canvas-bridge/canvas-bridge.js.map +1 -1
  93. package/dist/services/canvas-bridge/sql-gate-extras.d.ts +4 -17
  94. package/dist/services/canvas-bridge/sql-gate-extras.d.ts.map +1 -1
  95. package/dist/services/canvas-bridge/sql-gate-extras.js +4 -22
  96. package/dist/services/canvas-bridge/sql-gate-extras.js.map +1 -1
  97. package/dist/services/edgar/concept-map.d.ts +10 -6
  98. package/dist/services/edgar/concept-map.d.ts.map +1 -1
  99. package/dist/services/edgar/concept-map.js +90 -22
  100. package/dist/services/edgar/concept-map.js.map +1 -1
  101. package/dist/services/edgar/data/former-tickers.json +24159 -0
  102. package/dist/services/edgar/edgar-api-service.d.ts +250 -62
  103. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  104. package/dist/services/edgar/edgar-api-service.js +808 -189
  105. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  106. package/dist/services/edgar/filing-to-text.d.ts +71 -2
  107. package/dist/services/edgar/filing-to-text.d.ts.map +1 -1
  108. package/dist/services/edgar/filing-to-text.js +533 -5
  109. package/dist/services/edgar/filing-to-text.js.map +1 -1
  110. package/dist/services/edgar/former-tickers.d.ts +47 -0
  111. package/dist/services/edgar/former-tickers.d.ts.map +1 -0
  112. package/dist/services/edgar/former-tickers.js +77 -0
  113. package/dist/services/edgar/former-tickers.js.map +1 -0
  114. package/dist/services/edgar/listing-codes.d.ts +47 -0
  115. package/dist/services/edgar/listing-codes.d.ts.map +1 -0
  116. package/dist/services/edgar/listing-codes.js +110 -0
  117. package/dist/services/edgar/listing-codes.js.map +1 -0
  118. package/dist/services/edgar/mirror/edgar-mirror.d.ts +11 -1
  119. package/dist/services/edgar/mirror/edgar-mirror.d.ts.map +1 -1
  120. package/dist/services/edgar/mirror/edgar-mirror.js +19 -1
  121. package/dist/services/edgar/mirror/edgar-mirror.js.map +1 -1
  122. package/dist/services/edgar/mirror/tickers-sync.d.ts.map +1 -1
  123. package/dist/services/edgar/mirror/tickers-sync.js +1 -3
  124. package/dist/services/edgar/mirror/tickers-sync.js.map +1 -1
  125. package/dist/services/edgar/mirror/types.d.ts +3 -1
  126. package/dist/services/edgar/mirror/types.d.ts.map +1 -1
  127. package/dist/services/edgar/mirror/types.js +3 -1
  128. package/dist/services/edgar/mirror/types.js.map +1 -1
  129. package/dist/services/edgar/trigram-similarity.d.ts +5 -3
  130. package/dist/services/edgar/trigram-similarity.d.ts.map +1 -1
  131. package/dist/services/edgar/trigram-similarity.js +18 -17
  132. package/dist/services/edgar/trigram-similarity.js.map +1 -1
  133. package/dist/services/edgar/types.d.ts +20 -7
  134. package/dist/services/edgar/types.d.ts.map +1 -1
  135. package/package.json +6 -5
  136. package/server.json +3 -3
  137. package/skills/secedgar-guide/SKILL.md +3 -3
  138. package/dist/mcp-server/tools/escape-inline.d.ts +0 -35
  139. package/dist/mcp-server/tools/escape-inline.d.ts.map +0 -1
  140. package/dist/mcp-server/tools/escape-inline.js +0 -51
  141. package/dist/mcp-server/tools/escape-inline.js.map +0 -1
@@ -4,15 +4,19 @@
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';
15
- import { trigramSimilarity } from './trigram-similarity.js';
16
+ import { buildFormerTickerIndex, readFormerTicker, withEarlierHolders, } from './former-tickers.js';
17
+ import { listedSymbol, readTickerSpelling } from './listing-codes.js';
18
+ import { MF_TICKERS_URL, TICKERS_URL } from './mirror/types.js';
19
+ import { trigramScorer } from './trigram-similarity.js';
16
20
  import { childText, findTag, findTags } from './xml-nodes.js';
17
21
  const MAX_RETRIES = 3;
18
22
  const BASE_BACKOFF_MS = 1000;
@@ -54,6 +58,13 @@ const BODY_IDLE_TIMEOUT_MS = 15_000;
54
58
  * `rate_limited` (#122).
55
59
  */
56
60
  const SEC_UNREACHABLE_REASON = 'sec_unreachable';
61
+ /**
62
+ * `data.reason` once SEC answered the last attempt with a 500, 502, 503, or 504,
63
+ * whatever the earlier attempts got (#233). Declared and set retryable beside
64
+ * `sec_unreachable`, under one code for all four: a 504 is SEC's gateway failing,
65
+ * as this service's own header timeout is (#173), not this request timing out.
66
+ */
67
+ const SEC_UNAVAILABLE_REASON = 'sec_unavailable';
57
68
  const BUDGET_SPENT = { kind: 'budget_spent' };
58
69
  /**
59
70
  * `data.reason` on every SEC rate-limit failure — the upstream 429 and a call
@@ -72,8 +83,6 @@ const OPEN_GATE = { state: 'open' };
72
83
  function rateLimitHint(retryAfterSeconds) {
73
84
  return `SEC is rate-limiting this server's IP. It resumes serving an IP only after its request rate has stayed below 10 requests/second for 10 minutes, and any request sent meanwhile restarts that clock, so this server sends nothing to SEC until the cool-down ends — retry in ${retryAfterSeconds} seconds. A shared outbound IP can trigger the block even while this server stays under the limit.`;
74
85
  }
75
- /** URL for SEC's mutual-fund ticker file (ETFs and open-end funds). */
76
- const MF_TICKERS_URL = 'https://www.sec.gov/files/company_tickers_mf.json';
77
86
  /**
78
87
  * How long a failed load of the fund-ticker file stands before one resolution
79
88
  * refetches it (#119). A window rather than every resolution: against a
@@ -81,12 +90,146 @@ const MF_TICKERS_URL = 'https://www.sec.gov/files/company_tickers_mf.json';
81
90
  * to each one. After a rate-limit failure the window stretches to the cool-down.
82
91
  */
83
92
  const FUND_SLICE_RETRY_MS = 60_000;
93
+ const DAY_MS = 86_400_000;
94
+ /**
95
+ * How long a filer's failed recency read or live point read stands before a point read
96
+ * asks SEC about that filer again, the mirror answering meanwhile (#234): against a
97
+ * persistent 5xx, each filer costs one three-attempt ladder a minute rather than one per read.
98
+ */
99
+ const FILER_RETRY_MS = 60_000;
100
+ /** Most filers the failure marks hold; past it the mark used longest ago is dropped. */
101
+ const FILER_FAILURE_LIMIT = 4_096;
102
+ const MIB = 1_048_576;
103
+ /**
104
+ * Most bytes each per-key cache of parsed SEC documents holds, by the estimates below —
105
+ * 448 MiB across the three; past its limit a cache drops the entries used longest ago.
106
+ * Every company-scoped read and every mirror point read (#234) goes through the submissions
107
+ * cache. The full-index share holds the heaviest run of quarters one pre-2001 browse reads
108
+ * (`FULL_INDEX_QUARTER_SCAN_CAP` in `search-filings.tool.ts`, 8: 1999Q1–2000Q4, about
109
+ * 221 MiB by `FULL_INDEX_ROW_BYTES`), so the next page of a browse reads no quarter again:
110
+ * a share smaller than one scan drops each quarter before the repeat reaches it.
111
+ * Exported for the cache tests.
112
+ */
113
+ export const CACHE_BYTE_LIMITS = {
114
+ submissions: 160 * MIB,
115
+ archivePages: 32 * MIB,
116
+ fullIndex: 256 * MIB,
117
+ };
118
+ /**
119
+ * Estimated heap one value of a parsed filings column set retains (`filings.recent` or an
120
+ * archive page), at least the most measured under Bun or Node. Exported for the cache tests.
121
+ */
122
+ export const FILING_VALUE_BYTES = 24;
123
+ /**
124
+ * Estimated heap a parsed submissions document retains beyond its `recent` columns (entity
125
+ * metadata, the archive-page manifest), at least the most measured under Bun or Node.
126
+ * Exported for the cache tests.
127
+ */
128
+ export const SUBMISSIONS_DOC_BYTES = 4_096;
129
+ /**
130
+ * Estimated heap one parsed full-index row retains, at least the most measured under Bun or
131
+ * Node. Exported for the cache tests.
132
+ */
133
+ export const FULL_INDEX_ROW_BYTES = 352;
134
+ /**
135
+ * A string-keyed map keeping the entries used most recently — a read or a write is a use —
136
+ * whose weights sum to at most `limit`: a write past it drops the entries used longest ago,
137
+ * and an entry heavier than `limit` on its own is not kept. The one eviction mechanism for
138
+ * the per-key document caches (weighed in estimated bytes) and the filer failure marks (one
139
+ * apiece).
140
+ */
141
+ class LruMap {
142
+ entries = new Map();
143
+ limit;
144
+ total = 0;
145
+ constructor(limit) {
146
+ this.limit = limit;
147
+ }
148
+ /** The value under `key`, which becomes the entry used most recently. */
149
+ get(key) {
150
+ const entry = this.entries.get(key);
151
+ if (entry === undefined)
152
+ return undefined;
153
+ this.entries.delete(key);
154
+ this.entries.set(key, entry);
155
+ return entry.value;
156
+ }
157
+ /**
158
+ * Write `value` as the entry used most recently, then drop the least recently used until
159
+ * the weights fit. A value heavier than the limit is not kept and drops only its own key's
160
+ * earlier entry.
161
+ */
162
+ set(key, value, weight) {
163
+ this.delete(key);
164
+ if (weight > this.limit)
165
+ return;
166
+ this.entries.set(key, { value, weight });
167
+ this.total += weight;
168
+ for (const [oldest, entry] of this.entries) {
169
+ if (this.total <= this.limit)
170
+ break;
171
+ this.entries.delete(oldest);
172
+ this.total -= entry.weight;
173
+ }
174
+ }
175
+ delete(key) {
176
+ const entry = this.entries.get(key);
177
+ if (entry === undefined)
178
+ return;
179
+ this.entries.delete(key);
180
+ this.total -= entry.weight;
181
+ }
182
+ }
183
+ /** Estimated heap a parsed filings column set retains: each column value at {@link FILING_VALUE_BYTES}. */
184
+ function filingColumnsBytes(columns) {
185
+ let values = 0;
186
+ for (const column of Object.values(columns)) {
187
+ if (Array.isArray(column))
188
+ values += column.length;
189
+ }
190
+ return values * FILING_VALUE_BYTES;
191
+ }
84
192
  /** Trigram similarity threshold — minimum Dice score to include a candidate suggestion. */
85
193
  const TRIGRAM_THRESHOLD = 0.3;
86
194
  /** Maximum number of near-match suggestions to include. */
87
195
  const TRIGRAM_TOP_N = 3;
88
196
  /** The fund slice where nothing is read live: strict mirror mode. */
89
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
+ }
90
233
  // ---------------------------------------------------------------------------
91
234
  // Corporate-suffix normalization
92
235
  // ---------------------------------------------------------------------------
@@ -188,8 +331,11 @@ export function foldNamePunctuation(name) {
188
331
  export function joinSpacedInitials(name) {
189
332
  return name.replace(/(?<=(?:^| )\p{L}) (?=\p{L}(?: |$))/gu, '');
190
333
  }
191
- /** A letter or digit: the characters a name's word boundary falls between (#218). */
192
- 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;
193
339
  /**
194
340
  * Whether index `at` of `text` is a word boundary — a letter or digit on exactly one side,
195
341
  * regex `\b` read over every script (#218). Either end of the string counts as a side
@@ -212,6 +358,97 @@ export function containsFromWordStart(name, query) {
212
358
  return false;
213
359
  }
214
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
+ }
215
452
  // ---------------------------------------------------------------------------
216
453
  // Near-match company suggestions
217
454
  // ---------------------------------------------------------------------------
@@ -225,10 +462,10 @@ const NAME_TIERS = [0, 1, 2, 3, 4];
225
462
  * meets TRIGRAM_THRESHOLD, sorted descending.
226
463
  */
227
464
  export function suggestCompanies(query, allEntries) {
228
- const q = query.toLowerCase();
465
+ const similarity = trigramScorer(query.toLowerCase());
229
466
  const scored = [];
230
467
  for (const entry of allEntries) {
231
- const score = Math.max(entry.name ? trigramSimilarity(q, entry.name.toLowerCase()) : 0, entry.ticker ? trigramSimilarity(q, entry.ticker.toLowerCase()) : 0);
468
+ const score = Math.max(entry.name ? similarity(entry.name.toLowerCase()) : 0, entry.ticker ? similarity(entry.ticker.toLowerCase()) : 0);
232
469
  if (score >= TRIGRAM_THRESHOLD) {
233
470
  scored.push({ score, entry });
234
471
  }
@@ -257,12 +494,34 @@ class EdgarApiService {
257
494
  gate = OPEN_GATE;
258
495
  tickerCache;
259
496
  tickerCacheLoad;
260
- /** Per-CIK submissions doc cache, keyed by padded CIK (TTL = EDGAR_TICKER_CACHE_TTL). */
261
- submissionsCache = new Map();
262
- /** Per-page submissions archive cache, keyed by page name (TTL = EDGAR_TICKER_CACHE_TTL). */
263
- archivePageCache = new Map();
264
- /** Per-quarter full-index cache, keyed by `${year}Q${quarter}` (TTL = EDGAR_TICKER_CACHE_TTL). */
265
- fullIndexCache = new Map();
497
+ /**
498
+ * Per-CIK submissions doc cache, keyed by padded CIK (TTL = EDGAR_TICKER_CACHE_TTL), holding at
499
+ * most `CACHE_BYTE_LIMITS.submissions`. Mirror point reads take each filer's recency from it
500
+ * (#234), so every filer the mirror serves passes through it.
501
+ */
502
+ submissionsCache = new LruMap(CACHE_BYTE_LIMITS.submissions);
503
+ /** The newest XBRL acceptance each cached submissions document records, worked out once per document (#234). */
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();
507
+ /**
508
+ * Filers whose recency read or live point read SEC just failed, keyed by padded CIK, each
509
+ * mapped to the instant the mirror stops answering for it unasked (#234), at most
510
+ * {@link FILER_FAILURE_LIMIT} of them.
511
+ */
512
+ filerFailures = new LruMap(FILER_FAILURE_LIMIT);
513
+ /** Each filer's recency read in flight, which the point reads asking meanwhile share (#234). */
514
+ recencyLoads = new Map();
515
+ /**
516
+ * Per-page submissions archive cache, keyed by page name (TTL = EDGAR_TICKER_CACHE_TTL),
517
+ * holding at most `CACHE_BYTE_LIMITS.archivePages`.
518
+ */
519
+ archivePageCache = new LruMap(CACHE_BYTE_LIMITS.archivePages);
520
+ /**
521
+ * Per-quarter full-index cache, keyed by `${year}Q${quarter}` (TTL = EDGAR_TICKER_CACHE_TTL),
522
+ * holding at most `CACHE_BYTE_LIMITS.fullIndex`.
523
+ */
524
+ fullIndexCache = new LruMap(CACHE_BYTE_LIMITS.fullIndex);
266
525
  constructor() {
267
526
  const config = getServerConfig();
268
527
  this.cooldownMs = config.rateLimitCooldownSeconds * 1000;
@@ -317,13 +576,22 @@ class EdgarApiService {
317
576
  /**
318
577
  * Resolve a query (ticker, name, or CIK) to company match(es).
319
578
  * - Numeric input → direct CIK lookup
320
- * - 1-5 uppercase letters → ticker lookup (O(1))
579
+ * - 1-5 letters in any case, or anything typed in uppercase → the ticker lookup (O(1)):
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)
582
+ * - Typed in uppercase, unlisted → the ticker-spelling readings (`readTickerSpelling`,
583
+ * #235): a US venue code dropped (`UEC.N`), a preferred class run together (`CFGPH`), a
584
+ * root listed only as classes (`GLOP`), each match carrying `reading`; a non-US listing
585
+ * (`7203.T`) is no match
321
586
  * - No letter or digit (`.`, `'`) → no match
322
587
  * - Otherwise → name search (exact as written; exact once commas, periods, and
323
588
  * apostrophes are folded out and whitespace runs collapse; exact once spaced initials
324
589
  * join; prefix of the joined form ending at a word boundary; substring as written
325
- * starting at one — resolved within the best tier a current name reaches), then the
326
- * catch-all 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
327
595
  * Returns a single match, an array of multiple matches, or an empty array (no match).
328
596
  * Multiple matches are every candidate of that tier, deduplicated by CIK, current names
329
597
  * first, never cut: a consumer shows the first ten through `ambiguousMatches` and counts
@@ -344,13 +612,26 @@ class EdgarApiService {
344
612
  // return a CIK-only match and let the caller resolve identity from submissions.
345
613
  return { cik: padded };
346
614
  }
347
- // Short alphabetic → ticker (includes ETF/MF tickers from company_tickers_mf.json)
615
+ // A listed symbol (ETF/MF tickers from company_tickers_mf.json included) answers first for
616
+ // short alphabetic input in any case, and for any input typed in uppercase, so a reading
617
+ // or the period fold never takes a symbol the file lists; brokers and market-data sites
618
+ // write BRK.B where the file lists BRK-B, and no registrant has both forms on file (#110).
348
619
  const upper = trimmed.toUpperCase();
349
- if (/^[A-Z]{1,5}$/.test(upper)) {
350
- const match = cache.byTicker.get(upper);
351
- if (match)
352
- return match;
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).
623
+ const listed = listedSymbol(upper, cache.byTicker);
624
+ if (listed && (typedUpper || /^[A-Z]{1,5}$/.test(upper))) {
625
+ return withEarlierHolders(listed, cache);
353
626
  }
627
+ // Uppercase spellings vendors write for listed symbols, ahead of the name passes, which
628
+ // otherwise read `GS.K` as GSK plc through the period fold (#235).
629
+ const reading = readTickerSpelling(trimmed, cache);
630
+ if (reading !== undefined)
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;
354
635
  // A query with no letter or digit names no company: `.` would fold to an empty string
355
636
  // that starts every name (#219).
356
637
  if (!NAME_WORD_CHAR.test(trimmed))
@@ -370,32 +651,7 @@ class EdgarApiService {
370
651
  // `helix acquisition corp iii` — and a substring, matched as written, starts at one, so
371
652
  // `SY Bancorp` never names Embassy Bancorp; a query ending mid-word (`Berkshire Hath`)
372
653
  // still matches there when the name as written contains it.
373
- const lower = trimmed.toLowerCase();
374
- const lowerNormalized = normalizeCompanySuffix(lower);
375
- const folded = foldNamePunctuation(lower);
376
- const foldedNormalized = normalizeCompanySuffix(folded);
377
- const joined = joinSpacedInitials(folded);
378
- const joinedNormalized = normalizeCompanySuffix(joined);
379
- // A suffix-dropped name is a prefix of the full one, so the strip runs on prefix hits only.
380
- const isExact = (name, form, formNormalized) => name === form ||
381
- normalizeCompanySuffix(name) === formNormalized ||
382
- (name.startsWith(form) && stripCompanySuffix(name) === form);
383
- const tierOf = (name) => {
384
- if (isExact(name, lower, lowerNormalized))
385
- return 0;
386
- const foldedName = foldNamePunctuation(name);
387
- if (isExact(foldedName, folded, foldedNormalized))
388
- return 1;
389
- const joinedName = joinSpacedInitials(foldedName);
390
- // With no initials joined on either side, this repeats the folded tier's comparison.
391
- if ((joinedName !== foldedName || joined !== folded) &&
392
- isExact(joinedName, joined, joinedNormalized)) {
393
- return 2;
394
- }
395
- if (joinedName.startsWith(joined) && isWordBoundary(joinedName, joined.length))
396
- return 3;
397
- return containsFromWordStart(name, lower) ? 4 : undefined;
398
- };
654
+ const forms = nameQuery(trimmed);
399
655
  // Current names are registry rows, which carry a ticker; former names (the committed
400
656
  // asset) carry none. Resolution runs within the best tier a current name reaches —
401
657
  // several CIKs there are the ambiguity, and the tiers below are not listed. A former
@@ -407,7 +663,7 @@ class EdgarApiService {
407
663
  for (const entry of cache.allEntries) {
408
664
  if (!entry.name)
409
665
  continue;
410
- const tier = tierOf(entry.name.toLowerCase());
666
+ const tier = nameTier(entry.name, forms);
411
667
  if (tier === undefined)
412
668
  continue;
413
669
  (entry.ticker === undefined ? former : current)[tier].push(entry);
@@ -419,25 +675,47 @@ class EdgarApiService {
419
675
  ...current[bestCurrent],
420
676
  ...NAME_TIERS.filter((tier) => tier <= bestCurrent).flatMap((tier) => former[tier]),
421
677
  ];
422
- // Dedup by CIK (current + former names may match the same registrant).
423
- const seen = new Set();
424
- const deduped = [];
425
- for (const entry of candidates) {
426
- if (!seen.has(entry.cik)) {
427
- seen.add(entry.cik);
428
- deduped.push(entry);
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;
688
+ }
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;
429
702
  }
430
703
  }
431
- if (deduped.length > 0) {
432
- return deduped.length === 1 ? deduped[0] : deduped;
704
+ // A symbol typed in mixed or lower case, outside the short alphabetic shape, keeps the name
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);
433
717
  }
434
- // Also try as ticker if nothing matched (handles >5-char and digit-containing symbols
435
- // that bypassed the early ticker gate above). On a miss, retry a dotted symbol in
436
- // SEC's hyphenated share-class form — brokers and market-data sites write BRK.B where
437
- // company_tickers.json lists BRK-B, and no registrant has both forms on file (#110).
438
- const tickerMatch = cache.byTicker.get(upper) ??
439
- (upper.includes('.') ? cache.byTicker.get(upper.replaceAll('.', '-')) : undefined);
440
- return tickerMatch ?? [];
718
+ return index;
441
719
  }
442
720
  /**
443
721
  * Resolve an entity name to CIK candidates via EFTS entity-autocomplete
@@ -451,7 +729,9 @@ class EdgarApiService {
451
729
  * Distinct from `searchFilings`: same URL path, different query param (`keysTyped`)
452
730
  * and response shape (`_source.entity`, not the filing-document `_source`). A
453
731
  * failure of the search backend throws `efts_degraded_response` like a search's,
454
- * 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).
455
735
  */
456
736
  async resolveEntityByName(name, scope) {
457
737
  const url = new URL('https://efts.sec.gov/LATEST/search-index');
@@ -469,17 +749,57 @@ class EdgarApiService {
469
749
  const matches = [];
470
750
  for (const hit of hits) {
471
751
  const cik = hit._id?.padStart(10, '0');
472
- const entity = hit._source?.entity;
473
- if (!cik || !entity || seen.has(cik))
752
+ const source = hit._source;
753
+ if (!cik || !source?.entity || seen.has(cik))
474
754
  continue;
475
755
  seen.add(cik);
476
- matches.push({ cik, name: entity });
756
+ matches.push({ cik, ...splitEntityTickers(source) });
477
757
  }
478
758
  // A total with no numeric value reads as none, as searchFilings' shape guard reads it (#61):
479
759
  // the ambiguity sentence formats `value`, so a malformed one would throw a raw TypeError.
480
760
  const total = response.hits.total;
481
761
  return { matches, total: typeof total?.value === 'number' ? total : undefined };
482
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
+ }
483
803
  /** Reverse lookup: CIK → ticker symbol. */
484
804
  async cikToTicker(cik, scope) {
485
805
  const cache = await this.getTickerCache(scope);
@@ -541,20 +861,23 @@ class EdgarApiService {
541
861
  * the last year or 1,000 filings, whichever holds more — + the `files[]`
542
862
  * archive-page manifest). Cached per CIK within
543
863
  * the ticker-cache TTL — the doc is large and re-read on every archive-paging
544
- * scan (#78). A 404 throws (uncached) so a bad CIK still surfaces. A body without
864
+ * scan (#78) and by every mirror point read (#234) — within
865
+ * `CACHE_BYTE_LIMITS.submissions`, the documents used longest ago dropped first. A 404
866
+ * throws (uncached) so a bad CIK still surfaces. A body without
545
867
  * the shape the readers index fails as `sec_unreachable` (#186). Like every cache
546
868
  * here, written only by a completed read — a cancelled or rejected one caches nothing.
547
869
  */
548
870
  async getSubmissions(cik, scope) {
549
871
  const padded = cik.padStart(10, '0');
550
- const cached = this.submissionsCache.get(padded);
551
- if (cached && this.isFresh(cached.at))
552
- return cached.data;
872
+ const cached = this.readFresh(this.submissionsCache, padded);
873
+ if (cached !== undefined)
874
+ return cached;
553
875
  const url = `https://data.sec.gov/submissions/CIK${padded}.json`;
554
876
  const data = await this.fetchJson(url, scope);
555
877
  if (!isSubmissionsBody(data))
556
878
  throw unexpectedShape(url, 'a submissions document');
557
- this.submissionsCache.set(padded, { at: Date.now(), data });
879
+ const bytes = SUBMISSIONS_DOC_BYTES + filingColumnsBytes(data.filings.recent);
880
+ this.submissionsCache.set(padded, { at: Date.now(), data }, bytes);
558
881
  return data;
559
882
  }
560
883
  /**
@@ -563,17 +886,18 @@ class EdgarApiService {
563
886
  * `recent` window. Read through `SubmissionsArchiveWalk`. The page body is a flat parallel-array object
564
887
  * field-compatible with `FilingsRecent`; one without its six indexed columns fails
565
888
  * as `sec_unreachable`, uncached (#186). Cached per page within the ticker-cache
566
- * TTL (pages are large and effectively immutable once archived).
889
+ * TTL (pages are large and effectively immutable once archived) and
890
+ * `CACHE_BYTE_LIMITS.archivePages`, the pages used longest ago dropped first.
567
891
  */
568
892
  async fetchArchivePage(name, scope) {
569
- const cached = this.archivePageCache.get(name);
570
- if (cached && this.isFresh(cached.at))
571
- return cached.data;
893
+ const cached = this.readFresh(this.archivePageCache, name);
894
+ if (cached !== undefined)
895
+ return cached;
572
896
  const url = `https://data.sec.gov/submissions/${name}`;
573
897
  const data = await this.fetchJson(url, scope);
574
898
  if (!isFilingColumns(data))
575
899
  throw unexpectedShape(url, 'a submissions archive page');
576
- this.archivePageCache.set(name, { at: Date.now(), data });
900
+ this.archivePageCache.set(name, { at: Date.now(), data }, filingColumnsBytes(data));
577
901
  return data;
578
902
  }
579
903
  /**
@@ -583,18 +907,29 @@ class EdgarApiService {
583
907
  * full-text only reaches 2001, but the quarterly indexes reach 1993. The file
584
908
  * is not form-filterable server-side (a whole-quarter download), so callers
585
909
  * bound how many quarters they scan and filter client-side (#77). Cached per
586
- * quarter within the ticker-cache TTL — an archived quarter is immutable.
910
+ * quarter within the ticker-cache TTL — an archived quarter is immutable — and
911
+ * `CACHE_BYTE_LIMITS.fullIndex`, the quarters used longest ago dropped first.
587
912
  */
588
913
  async fetchFullIndexQuarter(year, quarter, scope) {
589
914
  const key = `${year}Q${quarter}`;
590
- const cached = this.fullIndexCache.get(key);
591
- if (cached && this.isFresh(cached.at))
592
- return cached.data;
915
+ const cached = this.readFresh(this.fullIndexCache, key);
916
+ if (cached !== undefined)
917
+ return cached;
593
918
  const text = await this.fetchText(`https://www.sec.gov/Archives/edgar/full-index/${year}/QTR${quarter}/master.idx`, scope);
594
919
  const data = parseMasterIndex(text);
595
- this.fullIndexCache.set(key, { at: Date.now(), data });
920
+ this.fullIndexCache.set(key, { at: Date.now(), data }, data.length * FULL_INDEX_ROW_BYTES);
596
921
  return data;
597
922
  }
923
+ /** The document cached under `key` while within the ticker-cache TTL; an expired entry is dropped. */
924
+ readFresh(cache, key) {
925
+ const cached = cache.get(key);
926
+ if (cached === undefined)
927
+ return undefined;
928
+ if (this.isFresh(cached.at))
929
+ return cached.data;
930
+ cache.delete(key);
931
+ return undefined;
932
+ }
598
933
  /** True when a cache entry loaded at `at` is still within the ticker-cache TTL. */
599
934
  isFresh(at) {
600
935
  return Date.now() - at < getServerConfig().tickerCacheTtl * 1000;
@@ -766,14 +1101,13 @@ class EdgarApiService {
766
1101
  * Fetch every XBRL fact a company has reported. Returns `null` on 404.
767
1102
  * Backs the whole-company reads (`get_snapshot`, `compare_companies`) and the
768
1103
  * no-data error path, which surfaces the namespaces and tags a filer uses.
769
- * Served from the local mirror when enabled and synced — the mirror stores one
770
- * row per (cik, taxonomy, tag) and reassembles the API shape off a `cik` point
771
- * lookup; the live API is the fallback. A concept unit that arrives as
772
- * anything but an array is dropped (#141).
1104
+ * Routed through the local mirror by {@link pointRead}; the mirror stores one row
1105
+ * per (cik, taxonomy, tag) and reassembles the API shape off a `cik` point lookup.
1106
+ * A concept unit that arrives as anything but an array is dropped (#141).
773
1107
  */
774
1108
  async tryGetCompanyFacts(cik, scope) {
775
1109
  const padded = cik.padStart(10, '0');
776
- 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));
1110
+ const facts = await this.pointRead(padded, scope, (mirror) => mirror.getCompanyFacts(cik), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyfacts/CIK${padded}.json`, scope));
777
1111
  for (const namespace of Object.values(facts?.facts ?? {})) {
778
1112
  for (const concept of Object.values(namespace))
779
1113
  concept.units = arrayUnits(concept.units);
@@ -782,57 +1116,197 @@ class EdgarApiService {
782
1116
  }
783
1117
  /**
784
1118
  * Fetch XBRL data for a concept. Returns `null` if the company does not report this tag.
785
- * Served from the local mirror when enabled and synced; the live API is the
786
- * fallback (and covers filings newer than the last refresh when `mirrorFallbackLive`).
787
- * A payload whose every unit arrives malformed comes back with no units — the
788
- * tag is named but carries nothing (#141).
1119
+ * Routed through the local mirror by {@link pointRead}: where the store answers, a tag
1120
+ * it lacks for a filer it holds is `null` with no live read, as SEC's 404 for an
1121
+ * unreported tag would be (#234). A payload whose every unit arrives malformed comes
1122
+ * back with no units — the tag is named but carries nothing (#141).
789
1123
  */
790
1124
  async tryGetCompanyConcept(cik, taxonomy, tag, scope) {
791
1125
  const padded = cik.padStart(10, '0');
792
- 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));
1126
+ const concept = await this.pointRead(padded, scope, (mirror) => mirror.getCompanyConcept(cik, taxonomy, tag), () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/companyconcept/CIK${padded}/${taxonomy}/${tag}.json`, scope));
793
1127
  if (concept)
794
1128
  concept.units = arrayUnits(concept.units);
795
1129
  return concept;
796
1130
  }
797
1131
  /**
798
1132
  * Fetch cross-company frame data. Returns `null` if no companies report this combination.
799
- * A frame is a full scan of the company-facts store, so it is served from the
800
- * mirror only when that layer is fully synced (`companyFactsComplete()`) — a
801
- * partial or mid-sync store would yield a silently-incomplete frame, so frames
802
- * fall back to the live API until the mirror is complete. The live API is also
803
- * the fallback on a genuine miss.
1133
+ * A frame is a full scan of the company-facts store, so the mirror serves it only once
1134
+ * that layer is fully synced (`companyFactsComplete()`): a partial or mid-sync store
1135
+ * would yield a silently incomplete frame, so frames read live until it is complete,
1136
+ * and strict mode (`mirrorFallbackLive` off) throws instead (#29). On a complete store:
1137
+ * - Strict mode → the store's frame, `null` on a miss; nothing is sent.
1138
+ * - A period whose filing window was still open at the companyfacts checkpoint
1139
+ * ({@link frameWindowClosesMs}), or a store with no checkpoint → live, since filers
1140
+ * may have reported for it since (#234). On any failure but the caller's cancel the
1141
+ * store's frame answers, or the live failure stands when the store has none.
1142
+ * - A closed period → the store's frame, which applies the holder-form rules the live
1143
+ * frames API cannot (#123, #142); live on a miss.
804
1144
  */
805
- tryGetFrames(taxonomy, tag, unit, period, scope) {
806
- 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));
1145
+ async tryGetFrames(taxonomy, tag, unit, period, scope) {
1146
+ const live = () => this.tryFetchJson(`https://data.sec.gov/api/xbrl/frames/${taxonomy}/${tag}/${unit}/${period}.json`, scope);
1147
+ const mirror = getEdgarMirror();
1148
+ if (!mirror)
1149
+ return live();
1150
+ const strict = !getServerConfig().mirrorFallbackLive;
1151
+ if (!(await mirror.companyFactsComplete())) {
1152
+ if (strict)
1153
+ throw companyFactsNotSynced();
1154
+ return live();
1155
+ }
1156
+ const stored = () => mirror.getFrames(taxonomy, tag, unit, period);
1157
+ if (strict)
1158
+ return stored();
1159
+ // No checkpoint parses to NaN, which compares false: the period counts as open.
1160
+ const checkpointMs = Date.parse((await mirror.companyFactsCheckpoint()) ?? '');
1161
+ if (!(checkpointMs >= frameWindowClosesMs(period))) {
1162
+ try {
1163
+ return await live();
1164
+ }
1165
+ catch (error) {
1166
+ if (scope.signal.aborted)
1167
+ throw error;
1168
+ const frame = await stored();
1169
+ if (frame === null)
1170
+ throw error;
1171
+ return frame;
1172
+ }
1173
+ }
1174
+ return (await stored()) ?? live();
807
1175
  }
808
1176
  /**
809
- * Route a company-facts query through the local mirror when ready, with live-API
810
- * fallback. The `ready` predicate is the caller's readiness gate — point lookups
811
- * pass `companyFactsReady()` (tolerant of an in-progress refresh); the frames
812
- * aggregation passes the stricter `companyFactsComplete()` so a partial or
813
- * mid-sync store never yields an incomplete frame. Paths:
814
- * - Mirror ready + hit → return mirror result
815
- * - Mirror ready + miss + fallbackLive → fall through to live()
816
- * - Mirror ready + miss + strict → return null
817
- * - Mirror not ready + fallbackLive → fall through to live()
818
- * - Mirror not ready + strict → throw ServiceUnavailable
819
- * - No mirror → fall through to live()
1177
+ * Route a point read of one filer (`tryGetCompanyConcept`, `tryGetCompanyFacts`; `cik`
1178
+ * zero-padded) through the local mirror (#234):
1179
+ * - No mirror → live.
1180
+ * - The company-facts layer has never synced → live; strict mode (`mirrorFallbackLive`
1181
+ * off) throws instead.
1182
+ * - Strict mode → the store, `null` on a miss; nothing is sent.
1183
+ * - A filer the store does not hold → live, failing as the live read does, since the
1184
+ * store has nothing to answer with.
1185
+ * - The call's SEC-failure budget already spent, or no sign the filer has filed XBRL
1186
+ * since the store's facts were compiled ({@link filerMayHaveFiled}) → the store; a tag
1187
+ * it lacks is `null`, as SEC answers for a tag the filer does not report.
1188
+ * - Otherwise → live. A 404 answers the store's row where it holds one, since SEC never
1189
+ * drops a fact from a filer's companyfacts once reported, and `null` where it does not.
1190
+ * On any failure but the caller's cancel the store answers, and goes on answering for
1191
+ * that filer without asking SEC for {@link FILER_RETRY_MS}, or the failure's
1192
+ * `retryAfter` when longer — so a rate-limit refusal never turns an answer the store
1193
+ * holds into a failure — unless the call's own spent failure budget ended the read
1194
+ * ({@link markFilerFailed}).
820
1195
  */
821
- async mirrorOrLive(ready, mirrorRead, live) {
1196
+ async pointRead(cik, scope, mirrorRead, live) {
822
1197
  const mirror = getEdgarMirror();
823
- if (mirror) {
824
- if (await ready(mirror)) {
825
- const hit = await mirrorRead(mirror);
826
- if (hit != null)
827
- return hit;
828
- if (!getServerConfig().mirrorFallbackLive)
829
- return null;
1198
+ if (!mirror)
1199
+ return live();
1200
+ const strict = !getServerConfig().mirrorFallbackLive;
1201
+ if (!(await mirror.companyFactsReady())) {
1202
+ if (strict)
1203
+ throw companyFactsNotSynced();
1204
+ return live();
1205
+ }
1206
+ if (strict)
1207
+ return mirrorRead(mirror);
1208
+ if (!(await mirror.holdsFiler(cik)))
1209
+ return live();
1210
+ if (scope.remainingMs === 0 || !(await this.filerMayHaveFiled(mirror, cik, scope))) {
1211
+ return mirrorRead(mirror);
1212
+ }
1213
+ let answer;
1214
+ try {
1215
+ answer = await live();
1216
+ }
1217
+ catch (error) {
1218
+ if (scope.signal.aborted)
1219
+ throw error;
1220
+ this.markFilerFailed(cik, error);
1221
+ return mirrorRead(mirror);
1222
+ }
1223
+ return answer ?? mirrorRead(mirror);
1224
+ }
1225
+ /**
1226
+ * Whether SEC may hold facts for the filer that the store lacks: its newest XBRL filing
1227
+ * ({@link filerRecency}) was accepted on or after the day before the companyfacts
1228
+ * checkpoint — the bulk archive's `Last-Modified` — a margin for filings accepted while
1229
+ * SEC compiled it. A store with no checkpoint answers yes, reading nothing; a failed
1230
+ * recency read answers no, so the store answers.
1231
+ */
1232
+ async filerMayHaveFiled(mirror, cik, scope) {
1233
+ const checkpointMs = Date.parse((await mirror.companyFactsCheckpoint()) ?? '');
1234
+ if (Number.isNaN(checkpointMs))
1235
+ return true;
1236
+ const latestXbrlMs = await this.filerRecency(cik, scope);
1237
+ return latestXbrlMs !== undefined && latestXbrlMs >= checkpointMs - DAY_MS;
1238
+ }
1239
+ /**
1240
+ * The filer's newest XBRL acceptance in ms ({@link latestXbrlAcceptanceMs}) from its
1241
+ * submissions document, read through `getSubmissions` and its cache — so a call that
1242
+ * already holds the document sends nothing, and otherwise one read goes out per filer
1243
+ * per TTL — or `undefined` while a failure marks the filer ({@link markFilerFailed}).
1244
+ * Point reads asking while a read is in flight share it: a read the same call started,
1245
+ * or another call's that cannot outspend this call's SEC-failure budget, the waiter
1246
+ * charged the failure time it spent waiting; a read that could outlast the waiter's
1247
+ * budget is not joined, and the call reads for itself. A shared read is cancelled only
1248
+ * by the call that started it, and then each waiter asks again under its own scope. The
1249
+ * caller's own cancel rethrows untouched.
1250
+ */
1251
+ async filerRecency(cik, scope) {
1252
+ for (;;) {
1253
+ const failedUntil = this.filerFailures.get(cik);
1254
+ if (failedUntil !== undefined) {
1255
+ if (Date.now() < failedUntil)
1256
+ return undefined;
1257
+ this.filerFailures.delete(cik);
1258
+ }
1259
+ const load = this.recencyLoads.get(cik);
1260
+ if (!load) {
1261
+ const promise = this.readFilerRecency(cik, scope).finally(() => {
1262
+ this.recencyLoads.delete(cik);
1263
+ });
1264
+ this.recencyLoads.set(cik, { promise, scope, waits: new Map() });
1265
+ return await promise;
1266
+ }
1267
+ if (load.scope === scope)
1268
+ return await load.promise;
1269
+ if (load.scope.remainingMs > scope.remainingMs)
1270
+ return await this.readFilerRecency(cik, scope);
1271
+ try {
1272
+ return await awaitShared(load, scope);
830
1273
  }
831
- else if (!getServerConfig().mirrorFallbackLive) {
832
- throw serviceUnavailable('EDGAR mirror enabled but the company-facts layer is not synced; run `bun run mirror:init`', { layer: 'companyfacts' });
1274
+ catch (error) {
1275
+ // A shared read rejects only when the call that started it is cancelled.
1276
+ if (scope.signal.aborted || !load.scope.signal.aborted)
1277
+ throw error;
833
1278
  }
834
1279
  }
835
- return live();
1280
+ }
1281
+ /** One recency read; any failure but the caller's cancel answers `undefined`, marking the filer ({@link markFilerFailed}). */
1282
+ async readFilerRecency(cik, scope) {
1283
+ try {
1284
+ const submissions = await this.getSubmissions(cik, scope);
1285
+ let latest = this.xbrlRecency.get(submissions);
1286
+ if (latest === undefined) {
1287
+ latest = latestXbrlAcceptanceMs(submissions.filings);
1288
+ this.xbrlRecency.set(submissions, latest);
1289
+ }
1290
+ return latest;
1291
+ }
1292
+ catch (error) {
1293
+ if (scope.signal.aborted)
1294
+ throw error;
1295
+ this.markFilerFailed(cik, error);
1296
+ return undefined;
1297
+ }
1298
+ }
1299
+ /**
1300
+ * Have the store answer for the filer without asking SEC — no recency read, no live
1301
+ * point read — for {@link FILER_RETRY_MS}, or the failure's `retryAfter` when longer.
1302
+ * A failure the call's own failure budget ended ({@link budgetEndedFailures}) marks
1303
+ * nothing: SEC failed none of its attempts, so it says nothing about the filer.
1304
+ */
1305
+ markFilerFailed(cik, error) {
1306
+ if (error instanceof McpError && budgetEndedFailures.has(error))
1307
+ return;
1308
+ const until = Date.now() + Math.max(FILER_RETRY_MS, retryAfterMs(error));
1309
+ this.filerFailures.set(cik, until, 1);
836
1310
  }
837
1311
  // --- Internals ---
838
1312
  /**
@@ -840,15 +1314,16 @@ class EdgarApiService {
840
1314
  * when `cutoff` is given — and `null` on 404. A body the ladder has no use for — a
841
1315
  * 404's, a retried 5xx's, a 429's, one that lands as the caller cancels — is
842
1316
  * cancelled unread (#188); an error the last attempt earns carries a bounded head
843
- * of its body, read like any other (#202). The body is read inside the ladder
844
- * (#181): a 5xx, an attempt that got no HTTP response, a 2xx whose body failed to
845
- * read, and — for a request that opts in with `backendFailure` — a 2xx whose whole
846
- * body relays a transient failure of the search backend (#206) all retry up to
847
- * `MAX_RETRIES` attempts, and then the last attempt decides — a 5xx throws its
848
- * status-classified `McpError`, a backend failure `efts_degraded_response`, the
849
- * other two `sec_unreachable`. Other non-OK statuses throw at once, as does
850
- * the local refusal while SEC's rate-limit block is active, and the pacer's
851
- * `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.
852
1327
  *
853
1328
  * Every failed attempt and every backoff is charged to the call's failure budget,
854
1329
  * and the ladder ends early once the budget cannot cover another backoff and
@@ -876,7 +1351,7 @@ class EdgarApiService {
876
1351
  // concurrent one while this retry waited for its slot. A 5xx it ends with had
877
1352
  // its body released before the backoff, so the error is built without one.
878
1353
  if (failed === undefined)
879
- throw secUnreachable(url, outcome);
1354
+ throw endedByBudget(secUnreachable(url, outcome));
880
1355
  throw await this.ladderFailure(url, failed, { attempt: attempt - 1, budgetStopped: true }, null);
881
1356
  }
882
1357
  let last = outcome;
@@ -916,20 +1391,27 @@ class EdgarApiService {
916
1391
  failed = last;
917
1392
  continue;
918
1393
  }
919
- throw await this.ladderFailure(url, last, { attempt, budgetStopped: attempt < MAX_RETRIES || cutByBudget(last) }, scope);
1394
+ const cut = cutByBudget(last);
1395
+ const error = await this.ladderFailure(url, last, { attempt, budgetStopped: attempt < MAX_RETRIES || cut }, scope);
1396
+ // A wait this call's budget cut spends what is left of it, so no attempt follows one:
1397
+ // a first attempt cut short means SEC failed none of this request's attempts.
1398
+ throw attempt === 1 && cut ? endedByBudget(error) : error;
920
1399
  }
921
1400
  }
922
1401
  /**
923
1402
  * The error a request's last attempt earned: `sec_unreachable` for no response or
924
1403
  * an unreadable body; `efts_degraded_response` for a body relaying a failure of the
925
- * search backend (#206); for an HTTP answer, its status-classified `McpError`, with
926
- * the 403 and 429 hints. A 5xx ladder the failure budget stopped keeps its status
927
- * mapping and `data`, and its message says the budget stopped it (#179).
1404
+ * search backend (#206); `sec_unavailable` for a 500, 502, 503, or 504, its message
1405
+ * naming the attempt the ladder ended on and, when the failure budget stopped it,
1406
+ * the budget (#179, #233); for any other HTTP answer, its status-classified
1407
+ * `McpError`, with the 403 and 429 hints. Every HTTP answer keeps the status
1408
+ * mapping's `data`: `url`, `status`, and SEC's `Retry-After` when it sends one.
928
1409
  *
929
1410
  * An HTTP answer's body is read under `scope` for the error's diagnostic
930
- * (`errorBodyHead`, #202) — except a 429's, and the one `scope` is `null` for: a
931
- * retried 5xx whose body was released before its backoff. Either is built without
932
- * 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).
933
1415
  */
934
1416
  async ladderFailure(url, last, end, scope) {
935
1417
  if (last.kind === 'backend_failed')
@@ -937,14 +1419,15 @@ class EdgarApiService {
937
1419
  if (last.kind !== 'answered')
938
1420
  return secUnreachable(url, last, end);
939
1421
  const { response } = last;
1422
+ const { status } = response;
1423
+ const host = new URL(url).hostname;
940
1424
  const data = { url };
941
- if (response.status === 403) {
942
- const host = new URL(url).hostname;
1425
+ if (status === 403) {
943
1426
  data.recovery = {
944
1427
  hint: `${host} may be blocking requests. Check EDGAR_USER_AGENT format ("AppName contact@email.com") or retry later.`,
945
1428
  };
946
1429
  }
947
- else if (response.status === 429) {
1430
+ else if (status === 429) {
948
1431
  // send() closed the gate on this response, so the wait is the full cool-down.
949
1432
  const retryAfter = this.cooldownSecondsRemaining();
950
1433
  data.reason = RATE_LIMITED_REASON;
@@ -952,25 +1435,32 @@ class EdgarApiService {
952
1435
  data.retryAfter = retryAfter;
953
1436
  data.recovery = { hint: rateLimitHint(retryAfter) };
954
1437
  }
1438
+ else if (RETRYABLE_STATUSES.has(status)) {
1439
+ data.reason = SEC_UNAVAILABLE_REASON;
1440
+ data.retryable = true;
1441
+ data.recovery = {
1442
+ hint: `SEC EDGAR (${host}) answered the last attempt with HTTP ${status} — a failure on SEC's side, not a problem with the request. Retry the same call in a minute.`,
1443
+ };
1444
+ }
955
1445
  // A 429's body is SEC's full HTML block page; the hint above carries everything
956
- // actionable, so the markup is not forwarded (#112).
957
- if (scope === null || response.status === 429) {
1446
+ // actionable, so the markup is not read (#112).
1447
+ let body;
1448
+ if (scope === null || status === 429) {
958
1449
  await discardBody(response);
959
1450
  }
960
1451
  else {
961
- const body = await errorBodyHead(response, scope);
962
- // The two names `httpErrorFromResponse` gives a body it captures itself.
963
- if (body !== undefined)
964
- Object.assign(data, { body, responseBody: body });
1452
+ body = await errorBodyHead(response, scope);
965
1453
  }
966
1454
  const error = await httpErrorFromResponse(response, {
967
1455
  service: 'SEC EDGAR',
968
1456
  data,
969
1457
  captureBody: false,
1458
+ ...(body !== undefined && { cause: errorBodyCause(status, body) }),
970
1459
  });
971
- if (!end.budgetStopped)
1460
+ if (!RETRYABLE_STATUSES.has(status))
972
1461
  return error;
973
- 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 });
1462
+ const { close, onAttempt } = ladderEndText(end);
1463
+ return serviceUnavailable(`SEC EDGAR (${host}) answered HTTP ${status} on ${onAttempt}${close}`, error.data, { cause: error });
974
1464
  }
975
1465
  /**
976
1466
  * One attempt through the block gate and the pacer, under the caller's signal. A
@@ -1111,39 +1601,54 @@ class EdgarApiService {
1111
1601
  return this.buildTickerCache(cache.baseRows, await this.loadMfTickers(scope), cache.loadedAt);
1112
1602
  }
1113
1603
  /**
1114
- * Everything the ticker index holds but the live fund slice, preferring the local
1115
- * mirror when it is enabled and synced; company_tickers.json is the cold-start /
1116
- * not-ready fallback and the only source when the mirror is off. `liveFunds` says
1117
- * whether company_tickers_mf.json supplements it: always on the live path, and on
1118
- * the mirror path under `mirrorFallbackLive`, where it covers a mirror synced
1119
- * before fund ingestion (#43) and is the only source of series and class IDs,
1120
- * since the mirror stores a fund symbol as a bare ticker → CIK row. Strict mirror
1121
- * mode reads nothing live, so the mirror's fund rows are its only fund tickers.
1604
+ * Everything the ticker index holds but the live fund slice. `liveFunds` says whether
1605
+ * company_tickers_mf.json supplements it — everywhere but strict mirror mode — as the
1606
+ * only source of series and class IDs, since the mirror stores a fund symbol as a bare
1607
+ * ticker → CIK row (#43).
1608
+ * - No mirror, or its ticker layer not synced → company_tickers.json, failing as that
1609
+ * read does; strict mode (`mirrorFallbackLive` off) throws instead.
1610
+ * - Strict mode → the mirror's rows, its fund rows its only fund tickers; nothing is sent.
1611
+ * - Otherwise → company_tickers.json, read every TTL as with no mirror, plus the mirror's
1612
+ * fund rows, which rank behind the live fund slice and still resolve a symbol it lacks
1613
+ * (#135). When the ticker file fails — a rate-limit refusal included — the index is
1614
+ * built from all the mirror's rows and stands for the TTL, with one warning (#234).
1615
+ * The load runs under the shared ticker load's scope, which no caller can cancel.
1122
1616
  */
1123
1617
  async loadTickerBase(scope) {
1124
1618
  const mirror = getEdgarMirror();
1125
- if (mirror && (await mirror.tickersReady())) {
1126
- const rows = await mirror.getTickerRows();
1127
- if (rows.length > 0) {
1128
- return {
1129
- liveFunds: getServerConfig().mirrorFallbackLive,
1130
- rows: rows.map(mirrorIndexRow),
1131
- };
1619
+ const mirrorRows = mirror && (await mirror.tickersReady())
1620
+ ? (await mirror.getTickerRows()).map(mirrorIndexRow)
1621
+ : [];
1622
+ if (mirror && !getServerConfig().mirrorFallbackLive) {
1623
+ if (mirrorRows.length === 0) {
1624
+ throw serviceUnavailable('EDGAR mirror enabled but the ticker layer is not synced; run `bun run mirror:init`', { layer: 'tickers' });
1132
1625
  }
1626
+ return { liveFunds: false, rows: mirrorRows };
1133
1627
  }
1134
- else if (mirror && !getServerConfig().mirrorFallbackLive) {
1135
- throw serviceUnavailable('EDGAR mirror enabled but the ticker layer is not synced; run `bun run mirror:init`', { layer: 'tickers' });
1628
+ if (mirrorRows.length === 0)
1629
+ return { liveFunds: true, rows: await this.fetchTickerFile(scope) };
1630
+ try {
1631
+ const equity = await this.fetchTickerFile(scope);
1632
+ return {
1633
+ liveFunds: true,
1634
+ rows: [...equity, ...mirrorRows.filter((row) => row.kind === 'fund')],
1635
+ };
1636
+ }
1637
+ catch (error) {
1638
+ // Background index maintenance with no request of its own to attach to (#43).
1639
+ logger.warning("Ticker file (company_tickers.json) failed to load; the ticker index is built from the local mirror's rows until it reloads.", withExtra(requestContextService.createRequestContext({ operation: 'loadTickerBase' }), {
1640
+ endpoint: 'company_tickers',
1641
+ ...failureFields(error),
1642
+ }));
1643
+ return { liveFunds: true, rows: mirrorRows };
1136
1644
  }
1137
- const raw = await this.fetchJson('https://www.sec.gov/files/company_tickers.json', scope);
1138
- return {
1139
- liveFunds: true,
1140
- rows: Object.values(raw).map((entry) => ({
1141
- cik: String(entry.cik_str).padStart(10, '0'),
1142
- kind: 'equity',
1143
- name: entry.title,
1144
- ticker: entry.ticker,
1145
- })),
1146
- };
1645
+ }
1646
+ /** company_tickers.json as equity rows; a 200 holding no ticker entry fails as `sec_unreachable`. */
1647
+ async fetchTickerFile(scope) {
1648
+ const rows = parseTickerFile(await this.fetchJson(TICKERS_URL, scope));
1649
+ if (!rows)
1650
+ throw unexpectedShape(TICKERS_URL, 'the ticker file');
1651
+ return rows;
1147
1652
  }
1148
1653
  /**
1149
1654
  * Fetch company_tickers_mf.json (ETFs and mutual funds) as fund rows carrying
@@ -1159,7 +1664,7 @@ class EdgarApiService {
1159
1664
  * included (#179).
1160
1665
  */
1161
1666
  async loadMfTickers(scope) {
1162
- let retryAfterMs = 0;
1667
+ let retryMs = FUND_SLICE_RETRY_MS;
1163
1668
  let cause = { reason: 'malformed_body' };
1164
1669
  try {
1165
1670
  const rows = parseMfTickerFile(await this.fetchJson(MF_TICKERS_URL, scope));
@@ -1167,16 +1672,9 @@ class EdgarApiService {
1167
1672
  return { retryAt: undefined, rows };
1168
1673
  }
1169
1674
  catch (error) {
1170
- const data = error instanceof McpError ? error.data : undefined;
1171
- if (typeof data?.retryAfter === 'number')
1172
- retryAfterMs = data.retryAfter * 1000;
1173
- cause = {
1174
- ...(typeof data?.status === 'number' && { status: data.status }),
1175
- ...(typeof data?.reason === 'string' && { reason: data.reason }),
1176
- error: error instanceof Error ? error.message : String(error),
1177
- };
1675
+ retryMs = Math.max(FUND_SLICE_RETRY_MS, retryAfterMs(error));
1676
+ cause = failureFields(error);
1178
1677
  }
1179
- const retryMs = Math.max(FUND_SLICE_RETRY_MS, retryAfterMs);
1180
1678
  // Background index maintenance with no request of its own to attach to, so the
1181
1679
  // global logger carries it (#43).
1182
1680
  logger.warning('Fund-ticker file (company_tickers_mf.json) failed to load; ETF and mutual-fund tickers stay unresolved until it is retried.', withExtra(requestContextService.createRequestContext({ operation: 'loadMfTickers' }), {
@@ -1244,6 +1742,7 @@ class EdgarApiService {
1244
1742
  byCik,
1245
1743
  bySeriesId,
1246
1744
  byTicker,
1745
+ formerTickers: buildFormerTickerIndex(formerTickersData),
1247
1746
  fundRetryAt: funds.retryAt,
1248
1747
  loadedAt,
1249
1748
  };
@@ -1266,6 +1765,103 @@ function arrayUnits(units) {
1266
1765
  }
1267
1766
  return kept;
1268
1767
  }
1768
+ /**
1769
+ * The newest acceptance time, in ms, among the XBRL filings a submissions document lists
1770
+ * (#234). The `isXBRL` flag counts on any form: companyfacts takes facts from 8-Ks and
1771
+ * 424B2 fee exhibits as well as periodic reports. Archive pages are not read, so each
1772
+ * counts as an XBRL filing at the end of its last filing day (`filingTo` plus a day).
1773
+ * `+Infinity` — read live — when `recent` lacks either column or a time does not parse;
1774
+ * `-Infinity` when the filer lists no XBRL filing.
1775
+ */
1776
+ function latestXbrlAcceptanceMs(filings) {
1777
+ const { acceptanceDateTime, isXBRL } = filings.recent;
1778
+ if (!Array.isArray(acceptanceDateTime) || !Array.isArray(isXBRL)) {
1779
+ return Number.POSITIVE_INFINITY;
1780
+ }
1781
+ let latest = Number.NEGATIVE_INFINITY;
1782
+ for (const [i, flag] of isXBRL.entries()) {
1783
+ if (flag !== 1)
1784
+ continue;
1785
+ const accepted = Date.parse(acceptanceDateTime[i] ?? '');
1786
+ if (Number.isNaN(accepted))
1787
+ return Number.POSITIVE_INFINITY;
1788
+ latest = Math.max(latest, accepted);
1789
+ }
1790
+ for (const page of filings.files) {
1791
+ const filedTo = Date.parse(page.filingTo);
1792
+ if (Number.isNaN(filedTo))
1793
+ return Number.POSITIVE_INFINITY;
1794
+ latest = Math.max(latest, filedTo + DAY_MS);
1795
+ }
1796
+ return latest;
1797
+ }
1798
+ /** A frames period: `CY2025`, `CY2026Q3`, or the instant `CY2026Q3I`. */
1799
+ const FRAME_PERIOD = /^CY(\d{4})(?:Q([1-4])I?)?$/;
1800
+ /**
1801
+ * When filers stop reporting for a frames period, in ms (#234): November 1 of the next
1802
+ * year for an annual period, whose frame takes fiscal years ending as late as June 30
1803
+ * plus four months to file; the first day of the seventh month after its calendar
1804
+ * quarter for a quarterly or instant period. `+Infinity`, never closed, for any other.
1805
+ */
1806
+ function frameWindowClosesMs(period) {
1807
+ const match = FRAME_PERIOD.exec(period);
1808
+ if (!match)
1809
+ return Number.POSITIVE_INFINITY;
1810
+ const year = Number(match[1]);
1811
+ return match[2] === undefined
1812
+ ? Date.UTC(year + 1, 10, 1)
1813
+ : Date.UTC(year, Number(match[2]) * 3 + 6, 1);
1814
+ }
1815
+ /**
1816
+ * The wait a failure's `data.retryAfter` asks for, in ms, at most the rate-limit
1817
+ * cool-down; 0 when it names none. A rate-limit refusal carries whole seconds; a 5xx
1818
+ * carries SEC's `Retry-After` header as sent, read when it gives seconds (an HTTP-date
1819
+ * reads as none).
1820
+ */
1821
+ function retryAfterMs(error) {
1822
+ const retryAfter = error instanceof McpError ? error.data?.retryAfter : undefined;
1823
+ const seconds = typeof retryAfter === 'string' ? Number(retryAfter) : retryAfter;
1824
+ if (typeof seconds !== 'number' || !(seconds > 0))
1825
+ return 0;
1826
+ return Math.min(seconds, getServerConfig().rateLimitCooldownSeconds) * 1000;
1827
+ }
1828
+ /** A failed ticker-file load's log fields: its HTTP status and `data.reason` when it carries them, and its message. */
1829
+ function failureFields(error) {
1830
+ const data = error instanceof McpError ? error.data : undefined;
1831
+ return {
1832
+ ...(typeof data?.status === 'number' && { status: data.status }),
1833
+ ...(typeof data?.reason === 'string' && { reason: data.reason }),
1834
+ error: error instanceof Error ? error.message : String(error),
1835
+ };
1836
+ }
1837
+ /** Strict mirror mode's failure while the company-facts layer has never completed a sync. */
1838
+ function companyFactsNotSynced() {
1839
+ return serviceUnavailable('EDGAR mirror enabled but the company-facts layer is not synced; run `bun run mirror:init`', { layer: 'companyfacts' });
1840
+ }
1841
+ /**
1842
+ * Parse company_tickers.json — `{ cik_str, ticker, title }` entries keyed by index — into
1843
+ * equity rows, skipping any entry without that shape. Returns `undefined` when no entry
1844
+ * has it, which the caller fails like any unreadable answer (#234).
1845
+ */
1846
+ function parseTickerFile(raw) {
1847
+ if (!isRecord(raw))
1848
+ return;
1849
+ const rows = [];
1850
+ for (const entry of Object.values(raw)) {
1851
+ if (!isRecord(entry) || typeof entry.ticker !== 'string' || typeof entry.title !== 'string') {
1852
+ continue;
1853
+ }
1854
+ if (typeof entry.cik_str !== 'number' && typeof entry.cik_str !== 'string')
1855
+ continue;
1856
+ rows.push({
1857
+ cik: String(entry.cik_str).padStart(10, '0'),
1858
+ kind: 'equity',
1859
+ name: entry.title,
1860
+ ticker: entry.ticker,
1861
+ });
1862
+ }
1863
+ return rows.length > 0 ? rows : undefined;
1864
+ }
1269
1865
  /**
1270
1866
  * Classify a mirror ticker row. The mirror schema has no series or class column:
1271
1867
  * tickers-sync stores a fund symbol from company_tickers_mf.json with an empty
@@ -1683,6 +2279,17 @@ async function errorBodyHead(response, scope) {
1683
2279
  return read.text;
1684
2280
  return read.text === '' ? undefined : `${read.text}…`;
1685
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
+ }
1686
2293
  /**
1687
2294
  * `text`'s first {@link ERROR_BODY_LIMIT_BYTES} bytes — never a partial code point —
1688
2295
  * and `…`, or `undefined` when the whole of it fits: the bound on every upstream
@@ -1750,6 +2357,18 @@ function cutByBudget(last) {
1750
2357
  }
1751
2358
  }
1752
2359
  }
2360
+ /**
2361
+ * The failures the call's own failure budget caused, SEC failing none of the request's
2362
+ * attempts (#179): a request the spent budget kept from being sent, and one whose only
2363
+ * attempt the budget cut short of its own 15 s wait. A filer is never marked failed for one
2364
+ * (`markFilerFailed`, #234). Tracked here rather than on `data`, which reaches the caller.
2365
+ */
2366
+ const budgetEndedFailures = new WeakSet();
2367
+ /** `error`, recorded as one the call's own failure budget caused ({@link budgetEndedFailures}). */
2368
+ function endedByBudget(error) {
2369
+ budgetEndedFailures.add(error);
2370
+ return error;
2371
+ }
1753
2372
  /** How a failure the call's failure budget ended says so, in its message (#179). */
1754
2373
  const BUDGET_STOP_TEXT = `retries stopped at this call's ${CALL_FAILURE_BUDGET_MS / 1000} s budget for SEC failures`;
1755
2374
  /** A wait in seconds, to one decimal where it is not whole: `15`, `9.1`. */