@cyanheads/secedgar-mcp-server 0.17.1 → 0.18.0

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 (76) hide show
  1. package/AGENTS.md +8 -5
  2. package/CLAUDE.md +8 -5
  3. package/README.md +2 -1
  4. package/changelog/0.18.x/0.18.0.md +16 -0
  5. package/dist/mcp-server/tools/ambiguous-matches.d.ts +20 -0
  6. package/dist/mcp-server/tools/ambiguous-matches.d.ts.map +1 -0
  7. package/dist/mcp-server/tools/ambiguous-matches.js +22 -0
  8. package/dist/mcp-server/tools/ambiguous-matches.js.map +1 -0
  9. package/dist/mcp-server/tools/definitions/company-search.tool.d.ts.map +1 -1
  10. package/dist/mcp-server/tools/definitions/company-search.tool.js +11 -6
  11. package/dist/mcp-server/tools/definitions/company-search.tool.js.map +1 -1
  12. package/dist/mcp-server/tools/definitions/compare-companies.tool.d.ts.map +1 -1
  13. package/dist/mcp-server/tools/definitions/compare-companies.tool.js +16 -9
  14. package/dist/mcp-server/tools/definitions/compare-companies.tool.js.map +1 -1
  15. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.d.ts.map +1 -1
  16. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js +10 -2
  17. package/dist/mcp-server/tools/definitions/dataframe-describe.tool.js.map +1 -1
  18. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.d.ts.map +1 -1
  19. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js +6 -6
  20. package/dist/mcp-server/tools/definitions/dataframe-drop.tool.js.map +1 -1
  21. package/dist/mcp-server/tools/definitions/dataframe-query.tool.d.ts.map +1 -1
  22. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js +10 -10
  23. package/dist/mcp-server/tools/definitions/dataframe-query.tool.js.map +1 -1
  24. package/dist/mcp-server/tools/definitions/fetch-frames.tool.d.ts.map +1 -1
  25. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js +12 -7
  26. package/dist/mcp-server/tools/definitions/fetch-frames.tool.js.map +1 -1
  27. package/dist/mcp-server/tools/definitions/find-holders.tool.d.ts.map +1 -1
  28. package/dist/mcp-server/tools/definitions/find-holders.tool.js +48 -11
  29. package/dist/mcp-server/tools/definitions/find-holders.tool.js.map +1 -1
  30. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.d.ts.map +1 -1
  31. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js +13 -12
  32. package/dist/mcp-server/tools/definitions/get-beneficial-owners.tool.js.map +1 -1
  33. package/dist/mcp-server/tools/definitions/get-filing.tool.d.ts.map +1 -1
  34. package/dist/mcp-server/tools/definitions/get-filing.tool.js +16 -9
  35. package/dist/mcp-server/tools/definitions/get-filing.tool.js.map +1 -1
  36. package/dist/mcp-server/tools/definitions/get-financials.tool.d.ts.map +1 -1
  37. package/dist/mcp-server/tools/definitions/get-financials.tool.js +19 -21
  38. package/dist/mcp-server/tools/definitions/get-financials.tool.js.map +1 -1
  39. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.d.ts.map +1 -1
  40. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js +11 -19
  41. package/dist/mcp-server/tools/definitions/get-fund-holdings.tool.js.map +1 -1
  42. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts +10 -0
  43. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.d.ts.map +1 -1
  44. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js +23 -9
  45. package/dist/mcp-server/tools/definitions/get-insider-transactions.tool.js.map +1 -1
  46. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.d.ts.map +1 -1
  47. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js +8 -14
  48. package/dist/mcp-server/tools/definitions/get-institutional-holdings.tool.js.map +1 -1
  49. package/dist/mcp-server/tools/definitions/get-material-events.tool.d.ts.map +1 -1
  50. package/dist/mcp-server/tools/definitions/get-material-events.tool.js +6 -4
  51. package/dist/mcp-server/tools/definitions/get-material-events.tool.js.map +1 -1
  52. package/dist/mcp-server/tools/definitions/get-snapshot.tool.d.ts.map +1 -1
  53. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js +11 -8
  54. package/dist/mcp-server/tools/definitions/get-snapshot.tool.js.map +1 -1
  55. package/dist/mcp-server/tools/definitions/index.d.ts +337 -326
  56. package/dist/mcp-server/tools/definitions/index.d.ts.map +1 -1
  57. package/dist/mcp-server/tools/definitions/search-concepts.tool.js +2 -2
  58. package/dist/mcp-server/tools/definitions/search-concepts.tool.js.map +1 -1
  59. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts +12 -0
  60. package/dist/mcp-server/tools/definitions/search-filings.tool.d.ts.map +1 -1
  61. package/dist/mcp-server/tools/definitions/search-filings.tool.js +33 -10
  62. package/dist/mcp-server/tools/definitions/search-filings.tool.js.map +1 -1
  63. package/dist/mcp-server/tools/escape-inline.d.ts +35 -0
  64. package/dist/mcp-server/tools/escape-inline.d.ts.map +1 -0
  65. package/dist/mcp-server/tools/escape-inline.js +51 -0
  66. package/dist/mcp-server/tools/escape-inline.js.map +1 -0
  67. package/dist/mcp-server/tools/format-usd.d.ts +22 -0
  68. package/dist/mcp-server/tools/format-usd.d.ts.map +1 -0
  69. package/dist/mcp-server/tools/format-usd.js +53 -0
  70. package/dist/mcp-server/tools/format-usd.js.map +1 -0
  71. package/dist/services/edgar/edgar-api-service.d.ts +30 -9
  72. package/dist/services/edgar/edgar-api-service.d.ts.map +1 -1
  73. package/dist/services/edgar/edgar-api-service.js +90 -30
  74. package/dist/services/edgar/edgar-api-service.js.map +1 -1
  75. package/package.json +1 -1
  76. package/server.json +3 -3
package/AGENTS.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Agent Protocol
2
2
 
3
3
  **Server:** secedgar-mcp-server
4
- **Version:** 0.17.1
4
+ **Version:** 0.18.0
5
5
  **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -87,7 +87,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
87
87
  - **User-Agent required:** `"AppName contact@email.com"` on every SEC request or IP gets blocked
88
88
  - **CIK zero-padding:** the `data.sec.gov` APIs (submissions, companyfacts, companyconcept) require the 10-digit zero-padded CIK (`String(cik).padStart(10, '0')`). Archive paths under `www.sec.gov/Archives/edgar/data/` take it unpadded — SEC answers the padded path with a 301, and `fetch` follows it inside the same pacer slot, so every archive read would cost two requests. `filingArchiveUrl` (exported from `edgar-api-service.ts`) strips the zeros for all seven archive reads and for `get_filing`'s `filing_url` (#156)
89
89
  - **ETF/mutual-fund tickers:** `loadTickerCache` fetches `company_tickers_mf.json` alongside `company_tickers.json` and merges fund symbols (VOO, SCHD, JEPI…) into `byTicker`. Fund CIKs are registrant trusts (1:many with series), so fund rows go into `byTicker` only — never `byCik`, whichever source they come from. Resolved fund matches carry `seriesId`/`classId` from the live MF file, the only source of either. On a mirror-served ticker base the live MF fetch is merged in when `EDGAR_MIRROR_FALLBACK_LIVE` is on, so fund tickers resolve even if the mirror predates MF ingestion (#43); strict mirror-only (`FALLBACK_LIVE=false`) uses the mirror's own MF rows (ticker→CIK, no series/class). The mirror stores a fund symbol with an empty name — its schema has no series column — and `mirrorIndexRow` reads that empty name as the fund marker; a symbol claims `byTicker` in the order equity → live fund → mirror fund, so a live entry supersedes the mirror's bare row and keeps its series (#135). **The live fund slice has its own failure window:** a failed MF load (any HTTP failure, a malformed body, the block gate's refusal) is not cached for the ticker-cache TTL — `loadMfTickers` returns no rows and a `retryAt` `FUND_SLICE_RETRY_MS` (60 s) out, or the error's `retryAfter` when longer, so nothing is retried while the gate is closed. The first resolution after it refetches the file once, single-flight, onto the cached base (`reloadFundSlice`), which keeps its own load time: the equity index is not refetched and its TTL does not move. A per-resolution retry was rejected — against a persistent 5xx it adds three requests and ~3 s of backoff to every lookup (#119). Each failed load logs one warning through the framework's global `logger` (no request context to attach to) carrying `endpoint: 'company_tickers_mf'` (never the URL — framework log guidance keeps URLs out of log fields), the HTTP status or `malformed_body`, and the retry delay (#43).
90
- - **Name and ticker resolution:** `resolveCik` walks numeric CIK → the `/^[A-Z]{1,5}$/` ticker fast path → the name passes (exact → exact once folded → prefix once folded → substring over `allEntries`) → a catch-all `byTicker` lookup for symbols whose shape skipped the fast path. Three normalizations hang off that chain. The name passes' **exact** tier also compares suffix-normalized forms (`normalizeCompanySuffix`): the terminal whitespace-delimited token only, a trailing `.`/`,` stripped as part of recognizing it, expanded to one of four canonical long forms — `corp`→`corporation`, `inc`→`incorporated`, `co`→`company`, `ltd`→`limited`. **The four buckets are never merged.** The registry carries distinct registrants differing only in which suffix they use (`TORO CO` 0000737758 vs `TORO CORP.` 0001941131, and the same shape on Blue Owl and Fluent), so a single "has a corporate suffix" marker would compare two companies equal. Only the terminal token is rewritten — the same words sit mid-name in titles ending in a different suffix (`American Water Works Company, Inc.`) — and a terminal token that merely contains one (`Ltd./ADR`) is not a suffix. Punctuation elsewhere in a name is the fold's (below). `llc`/`plc` and the `lp`/limited-partnership family get no bucket and must never fold into the `ltd` bucket (#107); they drop for a bare query (below) but never normalize into one of the four. The name passes **resolve within the best tier a current name reaches**: several CIKs there are the ambiguity, listed without the tiers below, so `Itron` resolves to ITRON, INC. instead of listing SOLITRON and POSITRON beside it. The exact tier also matches a registry name minus its terminal suffix and a comma before it (`stripCompanySuffix` over `DROPPABLE_SUFFIXES`: the four buckets plus `plc`, `llc`, `lp`, `nv`, `sa`, `ag`, and `se`, with or without periods), so `Apple` names `Apple Inc.` exactly. The wider set is deliberate: with the four buckets alone, `Rio Tinto` silently picked RIO TINTO LTD over RIO TINTO PLC; now both drop to an exact hit and tie. Only the registry side is stripped, so `Toro Co` never meets `TORO CORP.` and `Rio Tinto plc` never meets RIO TINTO LTD, and two suffix variants of one base name (`Blue Owl Capital`) tie. Current names (registry rows, which carry a ticker) choose the tier. A former name joins at that tier or better but never outranks one — otherwise `Travelers` resolves to Citigroup through its former name `travelers inc` — and decides alone only when no current name matches (`Facebook Inc`). Against the 2026-10-02 registry plus the former-names asset, 930 of 34,865 name queries move from ambiguous to resolved and no resolved CIK changes (#155). The **punctuation fold** (`foldNamePunctuation`, #210) deletes `,` `.` `'` `’` from the query and from every current and former name, so `QXO Inc` meets `QXO, Inc.`, `Fluent Inc` meets `Fluent, Inc.`, and `Jeffs Brands` the former name `jeffs' brands ltd`; a period is deleted, never spaced, so `U.S. Bancorp` meets `US BANCORP \DE\`. It is comparison-only — returned names and `suggestCompanies` never see it — and a helper of its own: `normalizeCompanySuffix` and `stripCompanySuffix` read the as-written strings, and the folded tiers run them again on the folded forms. Tier order: exact as written, exact once folded, prefix once folded, substring as written. Exact as written ranks first so a title typed as listed never ties a former name equal to it only once folded (`McGraw Hill, Inc.` stays alone beside S&P Global's former `mcgraw hill inc`), and substring stays as written, since a folded `Embassy Bancorp, Inc.` contains `sy bancorp inc` and would answer `S.Y. Bancorp Inc` with another bank. Without the fold a weaker tier answered a punctuation-free spelling with another registrant (`BlackRock Inc` reached BLACKROCK INCOME TRUST, INC. by prefix, `Block Inc` H&R BLOCK INC by substring). Against the 2026-11-03 registry plus the former-names asset, no title queried as listed changes its answer and no title or former name changes CIK; six former names typed as listed move to `multiple_matches` with the current registrant first, since a current title now matches them too (`energizer holdings inc` lists ENERGIZER HOLDINGS, INC. ahead of the former holder). `\DE\`-style state tags, `&` `-` `/`, and conformed names that space their initials (`J M SMUCKER Co`) stay out of scope. The **catch-all ticker lookup** retries a dotted symbol with `.`→`-` on a miss — brokers and market data write `BRK.B` where `company_tickers.json` lists `BRK-B`, and that file carries exactly one dotted ticker (a placeholder), so the substitution cannot land on the wrong registrant. The early gate stays untouched: it is a fast path, not the only ticker lookup, and `search_filings`' `ticker:` token inherits the fix through `resolveCik` with no change of its own (#110)
90
+ - **Name and ticker resolution:** `resolveCik` walks numeric CIK → the `/^[A-Z]{1,5}$/` ticker fast path → the name passes (exact → exact once folded → exact once initials join → prefix → substring over `allEntries`) → a catch-all `byTicker` lookup for symbols whose shape skipped the fast path. Four normalizations hang off that chain. The name passes' **exact** tiers also compare suffix-normalized forms (`normalizeCompanySuffix`): the terminal whitespace-delimited token only, a trailing `.`/`,` stripped as part of recognizing it, expanded to one of four canonical long forms — `corp`→`corporation`, `inc`→`incorporated`, `co`→`company`, `ltd`→`limited`. **The four buckets are never merged.** The registry carries distinct registrants differing only in which suffix they use (`TORO CO` 0000737758 vs `TORO CORP.` 0001941131, and the same shape on Blue Owl and Fluent), so a single "has a corporate suffix" marker would compare two companies equal. Only the terminal token is rewritten — the same words sit mid-name in titles ending in a different suffix (`American Water Works Company, Inc.`) — and a terminal token that merely contains one (`Ltd./ADR`) is not a suffix. Punctuation elsewhere in a name is the fold's (below). `llc`/`plc` and the `lp`/limited-partnership family get no bucket and must never fold into the `ltd` bucket (#107); they drop for a bare query (below) but never normalize into one of the four. The name passes **resolve within the best tier a current name reaches**: several CIKs there are the ambiguity, listed without the tiers below, so `Itron` resolves to ITRON, INC. instead of listing SOLITRON and POSITRON beside it. The exact tier also matches a registry name minus its terminal suffix and a comma before it (`stripCompanySuffix` over `DROPPABLE_SUFFIXES`: the four buckets plus `plc`, `llc`, `lp`, `nv`, `sa`, `ag`, and `se`, with or without periods), so `Apple` names `Apple Inc.` exactly. The wider set is deliberate: with the four buckets alone, `Rio Tinto` silently picked RIO TINTO LTD over RIO TINTO PLC; now both drop to an exact hit and tie. Only the registry side is stripped, so `Toro Co` never meets `TORO CORP.` and `Rio Tinto plc` never meets RIO TINTO LTD, and two suffix variants of one base name (`Blue Owl Capital`) tie. Current names (registry rows, which carry a ticker) choose the tier. A former name joins at that tier or better but never outranks one — otherwise `Travelers` resolves to Citigroup through its former name `travelers inc` — and decides alone only when no current name matches (`Facebook Inc`). Against the 2026-10-02 registry plus the former-names asset, 930 of 34,865 name queries move from ambiguous to resolved and no resolved CIK changes (#155). The **punctuation fold** (`foldNamePunctuation`, #210) deletes `,` `.` `'` `’` from the query and from every current and former name, then collapses each whitespace run to one space (#219), so `QXO Inc` meets `QXO, Inc.`, `Fluent Inc` meets `Fluent, Inc.`, `Jeffs Brands` the former name `jeffs' brands ltd`, and `Forgent Networks Inc` the former name `forgent networks inc`; a period is deleted, never spaced, so `U.S. Bancorp` meets `US BANCORP \DE\`. It is comparison-only — returned names and `suggestCompanies` never see it — and a helper of its own: `normalizeCompanySuffix` and `stripCompanySuffix` read the as-written strings, and the folded tiers run them again on the folded forms. Without the fold a weaker tier answered a punctuation-free spelling with another registrant (`BlackRock Inc` reached BLACKROCK INCOME TRUST, INC. by prefix, `Block Inc` H&R BLOCK INC by substring). Against the 2026-11-03 registry plus the former-names asset, no title queried as listed changes its answer and no title or former name changes CIK; six former names typed as listed move to `multiple_matches` with the current registrant first, since a current title now matches them too (`energizer holdings inc` lists ENERGIZER HOLDINGS, INC. ahead of the former holder). The **initials join** (`joinSpacedInitials`, #219) turns each run of two or more one-letter words in a folded form into one word (`j m smucker co` → `jm smucker co`), so `JM Smucker` and `J.M. Smucker` meet `J M SMUCKER Co` and `WP Carey` meets `W. P. Carey Inc.`; it is comparison-only like the fold, and its tier runs the suffix helpers again on the joined forms. **No hit starts or ends inside a word** (#218): a prefix must end at a word boundary of the joined name and a substring must start at one in the name as written — a boundary is regex `\b`, a letter or digit on exactly one side — so `SY Bancorp, Inc.` no longer names Embassy Bancorp through `embassy`, `helix acquisition corp ii` no longer lists the later `Helix Acquisition Corp. III`, and `ticker:MRO` (a delisted symbol) no longer scopes to PermRock Royalty Trust. Tier order: exact as written, exact once folded, exact once initials join, prefix of the joined form, substring as written. Each tier ranks above the looser one after it, so a title typed as listed never ties a former name equal to it only once folded (`McGraw Hill, Inc.` stays alone beside S&P Global's former `mcgraw hill inc`), and `US Gold` names U.S. GOLD CORP. alone instead of tying McEwen's former `u s gold corp`, equal only once joined. Substring stays as written, so a query ending mid-word still reaches a name containing it as written (`Berkshire Hath`) but never one containing it only once folded: `Helix Acquisition Corp. III` folds to a name holding `helix acquisition corp ii`. A query with no letter or digit (`.`, `'`) is `no_match` instead of folding to a string that starts every name. Against the 2026-11-03 registry plus the former-names asset (#218, #219), no title queried as listed changes its answer; of the former names typed as listed, nine move from `multiple_matches` to their own CIK (`ace ltd` no longer lists MDA Space Ltd. beside Chubb), `total` keeps its CIK in a different list, and `u s gold corp` moves to `multiple_matches` with U.S. GOLD CORP. first; 174 of the 178 joined or dotted spellings of the 63 names that space their initials resolve to their own CIK, against 15 before, the other four naming U.S. GOLD CORP.; and all 37 double-spaced former names resolve typed single-spaced, against 17 before. Only a query with no letter or digit loses its match, but a query cut short mid-word that the prefix tier answered alone can now list several companies (`baldw` lists Baldwin Insurance Group beside Matson, whose former name is `alexander & baldwin inc`). `\DE\`-style state tags, `&` `-` `/`, and a dotted word SEC splits in two (`AMAZON COM INC` for `Amazon.com`) stay out of scope. The **catch-all ticker lookup** retries a dotted symbol with `.`→`-` on a miss — brokers and market data write `BRK.B` where `company_tickers.json` lists `BRK-B`, and that file carries exactly one dotted ticker (a placeholder), so the substitution cannot land on the wrong registrant. The early gate stays untouched: it is a fast path, not the only ticker lookup, and `search_filings`' `ticker:` token inherits the fix through `resolveCik` with no change of its own (#110). **No consumer reads the first of several matches** (#223): `get_financials`, `get_snapshot`, `get_insider_transactions`, and `search_filings`' `ticker:` token throw `ambiguous_company` (`data.matches` of `cik`/`name`/`ticker`, at most 10, also listed in the message) before any SEC read; `company_search` and `get_material_events` throw `multiple_matches`, `find_holders` and `get_beneficial_owners` `ambiguous_issuer`, `get_institutional_holdings` `ambiguous_entity`, `get_fund_holdings` `ambiguous_fund`, and `compare_companies` reports a per-company `failed[]` reason `ambiguous`. `search_filings`' `cik:` token resolves a zero-padded CIK, which never matches several
91
91
  - **Former-name resolution:** `src/services/edgar/data/former-names.json` is a committed asset (generated offline via `bun run gen:former-names`) containing `[lowercasedFormerName, zeroPaddedCIK]` tuples. `buildTickerCache` folds them into `allEntries` for name search and the trigram pass. Regenerate on demand after major M&A waves — former names are immutable, so the file rarely needs updating.
92
92
  - **Near-match suggestions:** `suggestCompanies(query, allEntries)` runs a Dice-coefficient trigram pass on the zero-hit search path, returning up to 3 candidates above a threshold. Each entry is scored on its **name and its ticker**, keeping the higher of the two — one ranked, deduped, top-N list rather than two disjoint ones, so a strong ticker match can outrank a weak name match and vice versa, and a ticker-shaped miss gets help instead of a bare `no_match` (#111). An entry missing either field is simply not scored on it: former-name entries carry a name and no ticker, and MF rows carry neither a name nor a place in `allEntries`, so fund tickers stay structurally unreachable here regardless of what the scorer does. Suggestions appear in the `no_match` error `data.suggestions` and in the error message. Never auto-resolves. Only the throw that attaches suggestions names the field in its hint (`company_search` passes its own `recovery.hint`: that sentence, then the contract text); the contract's `no_match` recovery never mentions it, since a zero-hit miss with no near match and the bare-CIK 404 carry no `suggestions` (#153).
93
93
  - **XBRL friendly names:** `concept-map.ts` maps `"revenue"` → real XBRL tags; handles historical tag changes (ASC 606), including both assessed-tax variants — a filer presenting revenue gross of excise/sales tax reports only `RevenueFromContractWithCustomerIncludingAssessedTax`, and without it the walk fell through to tags SEC retired in 2018 (#98). The Including variant sits BEHIND `Revenues`, not ahead of it — the two disagree for filers that tag gross sales and net-of-excise sales under separate elements, so promoting it over `Revenues` swaps the definition partway back through the history and prints a step change that is a tag switch, not a business fact; behind `Revenues` it only fills frames no current tag covers. The same precedent places successor tags: `capex` walks `PaymentsToAcquireProductiveAssets` behind the PP&E-only tag (it also counts software and intangibles) and `interest_expense` walks `InterestExpenseNonoperating` behind both older tags, so NVIDIA, Amazon, Visa, and Microsoft reach current values and no frame the older tags cover changes (#125); the banks' `InterestExpenseOperating` (JPMorgan, Bank of America, and Wells Fargo report interest expense only under it from 2024) goes behind that, since it matches `InterestExpense` for 33 of 37 CY2025Q2 filers reporting both but `InterestExpenseNonoperating` for 0 of 4 (#147). SEC serves both successors with no label, so the line falls back to the concept's label. A different-definition tag still goes in `relatedTags`, never `tags` — `ppe_net`'s finance-lease-inclusive total is the primary line for Alphabet, Meta, and Tesla (#36, #130). `ifrsTags` covers every concept with an IFRS element confirmed present in a live 20-F filer's companyfacts; `notes_payable` is deliberately unmapped (IFRS presents borrowings as one caption, with no notes/debt split) and `shares_outstanding` is `dei`. Never add an `ifrsTags` entry from the taxonomy alone — an element existing is not evidence filers tag it (#99). `ifrsTags` order is semantic the same way `tags` is: index 0 is the counterpart of the us-gaap index-0 tag, so the same concept answers the same question under either taxonomy (`accounts_receivable` leads with the trade-only caption, not the combined trade-and-other one; `share_repurchases` with the financing outflow, not the treasury-only line a share-cancelling filer tags zero). Verify a candidate order against filers that report BOTH tags — presence alone does not settle which one leads. One concept has no right order: IFRS filers split between the employee-scheme share-based-payment element and the IFRS 2.51(a) expense total, and the two invert between filers (SAP's total is its real line with the employee element a two-period fringe; Sanofi is the exact opposite), so `stock_based_compensation` carries `ifrsTagSelection: 'coverage'` and picks per filer by which tag covers more standard periods (#101). It is the only concept that does, and the flag is scoped to `ifrsTags` on purpose — its us-gaap pair IS a ladder, since `AllocatedShareBasedCompensationExpense` is the disaggregated line and out-covers the total for Alphabet, IBM, Tesla, and P&G.
@@ -100,7 +100,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
100
100
  - **Fiscal-period caveats:** SEC reports a filer's fiscal Q4 as the 10-K residual, never as a discrete quarterly fact, so the calendar quarter that a filer's fiscal Q4 *spans* carries no frame-tagged quarterly value. That is not always the quarter holding the fiscal year-end date — a January year-end closes a fiscal Q4 running Nov–Jan, which SEC frames as calendar Q4 — and calendar-year filers are affected too (no discrete Q4). `fiscal-periods.ts` owns both directions: `fiscalQ4Caveats(period)` for the cross-company frame view (`fetch_frames`), `missingQuarterCaveats(frames)` for the per-filer series view (`get_financials`, `get_snapshot`, `compare_companies`) (#95). The per-filer detection is data-driven — no maintained filer list — and reads only the newest 4 years carrying quarterly frames, applying the per-year quorum inside that window rather than before it, because SEC frame-tagged all four calendar quarters before ~CY2021 and drops the fiscal-Q4 quarter after; a whole-history read would let the older years mask the live gap, and filtering first would let a filer whose recent years are too sparse silently describe the older regime. **Keep that slice-then-filter order.** The detector reports a *set* of absent quarters, not one: a filer whose remaining fiscal quarters also span non-calendar durations loses two (Costco tags only calendar Q1 and Q4), and the per-year quorum is two of four — low enough to admit that shape, high enough to bound the absent set at two and keep a one-quarter stub year from dragging a third in (#100). Message wording and the derivation advice differ between the one- and two-quarter cases; the three consuming tools all iterate `caveats`, so nothing downstream assumes at most one entry.
101
101
  - **`get_financials` period default:** with `period_type` unset the series defaults to `annual` (clean FY series); if the annual filter empties a non-empty series whose frames are all instant (`CY####Q#I` — balance-sheet, shares-outstanding, raw instant tags), it falls back to the full series so the first call returns data (#48). An explicit `period_type` is honored. `annual` on an instant series returns the framed instants whose `end` is one of the filer's fiscal-year ends (`filerFiscalYearEndsWithComparatives` — each annual report's own year, the #148 rule, plus the comparative years it restates, the same set `compare_companies` aligns on, so MSFT reaches its first XBRL 10-K's `CY2009Q2I` and `CY2008Q2I`), read from companyfacts only on that path — which otherwise fails — and reusing a payload already read. Selection keys on `end`, never on the frame holder's form or quarter: BSX's 2025-12-31 instant, framed on its Q2-2026 10-Q while the 10-K's own fact carries no frame, is kept with the 10-Q's provenance, and a June year end lands on `Q2I`. A cover-date concept (`shares_outstanding` for a 10-K filer, dated weeks after the year end) has no year-end instant, and a failed or `null` read selects nothing; both still fail `no_period_data`, with a hint naming which (#167). Any other explicit `period_type` that excludes everything still errors.
102
102
  - **8-K item codes:** SEC replaced the original single-integer item numbering with the current `x.xx` scheme in Release 33-8400, effective **2004-08-23**, so EDGAR's `items` field carries two disjoint vocabularies. `eight-k-items.ts` decodes by the code's **shape**, never the filing date — dotted is current, a bare integer is legacy — because filers reported pre-changeover events under the old numbers for months after the effective date, and a date-keyed table would mislabel exactly those. The two vocabularies reuse integers for unrelated events (legacy `5` is Other Events, current `5.02` is officer departures; legacy `12` is the ancestor of `2.02`), so a dotted `items` filter never matches a pre-2004 filing — `get_material_events`' zero-hit notice says so and echoes the codes actually present. The tables back three surfaces: the tool's `items` enum, the decoded per-filing rows, and the `secedgar://filing-types` resource. A code matching a shape but absent from that regime's table comes back with no label rather than a guess.
103
- - **EFTS quirks:** `dateRange=custom` must be set when using date params; the singular `entity` param is ignored — `cik:`/`ticker:` targeting passes the resolved CIK via the plural `ciks` param (server-side scope, independent of the filing's name text, so former-name filings on the same CIK are matched); `size` is ignored entirely and every request answers with 100 hits, so `find_holders` pages with `from` alone and expresses its budget in pages (5 → 500 rows). The result window is 10,000 documents, so a `from` past 9,900 is refused as a `ResponseError` body, with or without `q` and whatever the match total; `search_filings` sends `offset` as `from` only under `sort=relevance` with no entity scope on a 2001-onward range, fails a deeper `offset` there as `offset_out_of_range` before any request (`MAX_RELEVANCE_OFFSET`, which `find_holders`' continuation recipe also names), and keeps the schema's 9,999 for its other paths, which page the rows they assembled (#214). A hit is one matching **document**, not a filing: `_id` is `<accession>:<filename>`, a filing whose body and exhibits both match arrives once per document, and `hits.total.value` and the `form_filter` aggregation (keyed on `root_forms`, amendments folded in) count documents. `search_filings` collapses hits to one row per accession (first-ranked hit's fields, plus `matched_documents` in rank order) and counts `total` / `form_distribution` from those filings; no EFTS parameter yields a search's filing count (`collapse`/`aggs` are ignored), so `total` is exact only when one window held every match, else a lower bound beside `total_documents`. **A browse is the exception:** a forms- or entity-only request (no `q`) matches each filing's primary document alone (S-1 January 2025: 200 hits over two pages, 200 distinct accessions, every `file_type` the form), so `hits.total.value` is the filing count and `total` is EDGAR's count — exact when the relation is `eq`, at any offset — trusted while the window shows one document per accession, else back to the window lower bound; `dataset.truncated` still flags a window short of it, and `form_distribution` covers the filings in hand. The straddling merge keeps the window count for its 2001-onward side, since its `total` counts assembled rows. Under `sort=relevance`, `from` counts documents and the 100-hit window runs past the page, so a page lists the filings among its own `limit` documents (the window's first rows, which can number fewer than `limit`) and only a filing straddling a page edge recurs on the next page (#124). A backend failure arrives as a 200 too, with `errorType`, `errorMessage`, `trace`, and `requestId` in place of `hits`; its handling is in the rate-limit note above (#206). Caller text is escaped before it reaches full-text search: `searchFilings`' `q` and `resolveEntityByName`'s `keysTyped` both go through `escapeEftsText`, which doubles each backslash and writes each control character (category Cc) as `\uXXXX`, so a term holding either is searched as typed. The escape lives in the service, not a tool, so `find_holders`' `search_key` re-sent through `search_filings` runs the same search. `find_holders` quotes the conformed name minus one trailing qualifier — a `\` or `/`, one to six letters, an optional closing `\` or `/` (`/[\\/][A-Za-z]{1,6}[\\/]?$/`, then a trim) — since 13F information tables print the issuer without it: `"US BANCORP"` matches 2,315 documents in the 2026-Q2 filing window, the phrase with its `\DE\` qualifier 2, and `PROGRESSIVE CORP/OH/` is searched as `"PROGRESSIVE CORP"`. A slash inside a name (`CULLEN/FROST BANKERS, INC.`) and an undelimited state token (`UNIVERSAL DISPLAY CORP PA`) stay, and `resolved_issuer_name` keeps the registry title (#205). A notice naming a `secedgar_search_filings` call as JSON — `find_holders`' first-page and continuation recipes, `company_search`'s withheld-filings recipe — puts it in a code span (`markdown().inlineCode`, fenced past any backtick run), since `content[]` renders as Markdown and outside code the quoted phrase's `\"` loses its backslash, as would a caller's form type typed into `company_search`'s `forms` (#220)
103
+ - **EFTS quirks:** `dateRange=custom` must be set when using date params; the singular `entity` param is ignored — `cik:`/`ticker:` targeting passes the resolved CIK via the plural `ciks` param (server-side scope, independent of the filing's name text, so former-name filings on the same CIK are matched); `size` is ignored entirely and every request answers with 100 hits, so `find_holders` pages with `from` alone and expresses its budget in pages (5 → 500 rows). The result window is 10,000 documents, so a `from` past 9,900 is refused as a `ResponseError` body, with or without `q` and whatever the match total; `search_filings` sends `offset` as `from` only under `sort=relevance` with no entity scope on a 2001-onward range, fails a deeper `offset` there as `offset_out_of_range` before any request (`MAX_RELEVANCE_OFFSET`, which `find_holders`' continuation recipe also names), and keeps the schema's 9,999 for its other paths, which page the rows they assembled (#214). A hit is one matching **document**, not a filing: `_id` is `<accession>:<filename>`, a filing whose body and exhibits both match arrives once per document, and `hits.total.value` and the `form_filter` aggregation (keyed on `root_forms`, amendments folded in) count documents. `search_filings` collapses hits to one row per accession (first-ranked hit's fields, plus `matched_documents` in rank order) and counts `total` / `form_distribution` from those filings; no EFTS parameter yields a search's filing count (`collapse`/`aggs` are ignored), so `total` is exact only when one window held every match, else a lower bound beside `total_documents`. **A browse is the exception:** a forms- or entity-only request (no `q`) matches each filing's primary document alone (S-1 January 2025: 200 hits over two pages, 200 distinct accessions, every `file_type` the form), so `hits.total.value` is the filing count and `total` is EDGAR's count — exact when the relation is `eq`, at any offset — trusted while the window shows one document per accession, else back to the window lower bound; `dataset.truncated` still flags a window short of it, and `form_distribution` covers the filings in hand. The straddling merge keeps the window count for its 2001-onward side, since its `total` counts assembled rows. Under `sort=relevance`, `from` counts documents and the 100-hit window runs past the page, so a page lists the filings among its own `limit` documents (the window's first rows, which can number fewer than `limit`) and only a filing straddling a page edge recurs on the next page (#124). A backend failure arrives as a 200 too, with `errorType`, `errorMessage`, `trace`, and `requestId` in place of `hits`; its handling is in the rate-limit note above (#206). Caller text is escaped before it reaches full-text search: `searchFilings`' `q` and `resolveEntityByName`'s `keysTyped` both go through `escapeEftsText`, which doubles each backslash and writes each control character (category Cc) as `\uXXXX`, so a term holding either is searched as typed. The escape lives in the service, not a tool, so `find_holders`' `search_key` re-sent through `search_filings` runs the same search. `find_holders` quotes the conformed name minus one trailing qualifier — a `\` or `/`, one to six letters, an optional closing `\` or `/` (`/[\\/][A-Za-z]{1,6}[\\/]?$/`, then a trim) — since 13F information tables print the issuer without it: `"US BANCORP"` matches 2,315 documents in the 2026-Q2 filing window, the phrase with its `\DE\` qualifier 2, and `PROGRESSIVE CORP/OH/` is searched as `"PROGRESSIVE CORP"`. A slash inside a name (`CULLEN/FROST BANKERS, INC.`) and an undelimited state token (`UNIVERSAL DISPLAY CORP PA`) stay, and `resolved_issuer_name` keeps the registry title (#205). Two registrants whose titles match once that qualifier is gone (`FIRST BANCORP /PR/` and `FIRST BANCORP /NC/`; `INDEPENDENT BANK CORP /MI/` and `INDEPENDENT BANK CORP`) search one phrase and get the same holders, and keeping the qualifier is no fix (`"FIRST BANCORP /PR/"` matches 9 documents in that window, `"FIRST BANCORP"` 458, FBP's CUSIP 353), so a name search with at least one match checks the in-memory registry (`getAllEntries`, no request) for every other current registrant (a ticker-file row, never a former name) whose title, minus its own qualifier, equals the phrase case-insensitively, and names each with CIK and ticker in a sentence pointing to `cusip`. The sentence joins the tool's `notices` list, since `ctx.enrich.notice` and `ctx.enrich.truncated`'s guidance are last-wins (#224). A notice naming a `secedgar_search_filings` call as JSON — `find_holders`' first-page and continuation recipes, `company_search`'s withheld-filings recipe — puts it in a code span (`markdown().inlineCode`, fenced past any backtick run), since `content[]` renders as Markdown and outside code the quoted phrase's `\"` loses its backslash, as would a caller's form type typed into `company_search`'s `forms` (#220)
104
104
  - **Submissions archive walk:** the submissions feed's `filings.recent` holds the last year or 1,000 filings, whichever is more — so 26,000+ rows for JPMorgan, and a filing day is never split (Microsoft's window runs to 1,002 rows to finish its oldest day); everything older lives on `filings.files[]` archive pages of 200–360 KB each. Every tool that reads past `recent` goes through `SubmissionsArchiveWalk` (`submissions-archive.ts`): one `ARCHIVE_PAGE_SCAN_CAP` (10) for all, pages read one at a time through the service's pacer and page cache, and no page selected when the lower bound falls on or after `recent`'s oldest date — so a call answered by `recent` sends no archive request. The caller picks the order — `newest-first` (`company_search`, `search_filings`' pre-2001 arm, `get_material_events`, `get_insider_transactions`' window), or `oldest-first` forward from a date (`get_institutional_holdings`' quarter lookup, since newest-first cannot reach JPMorgan's 2020-Q4 13F-HR on page 41 of 70 under the cap) — and can stop after any page; `scannedThrough` (the oldest page start read) and `truncated` (selected pages left unread, whether the cap, an early stop, or a caller that never started the walk left them) are reported the same way everywhere. Worst case per call is the submissions document plus 10 pages plus the tool's own document reads (`get_insider_transactions`: 111). `get_material_events` without a date window walks only to fill `limit`: it enters the walk when fewer than `limit` `recent` rows pass the `items` filter — the same count as the stop test, so unrelated recent 8-Ks never stand in for matches (#139) — and stops on the page that fills it with rows passing that filter, and its `dataset.truncated` is true whenever selected pages went unread — including when `recent` alone fills `limit` and no page is read, since the dataframe then holds only the recent window (#134); a result short of `limit` with selected pages unread (only the cap ends a walk that short) gets a notice naming the pages read, the oldest date reached, and the lever — `filed_before=<that date>` alone or in a window when undated, narrowing the window with `filed_before=<that date>` when dated, since a newest-first walk reaches older filings only through an earlier upper bound — appended to the zero-match or empty-window notice when one fires, since `ctx.enrich.notice` is last-wins; an empty-window notice the cap cut short claims no 8-K only "as far back as the scan reached" and drops its widen-the-range advice (#139); `get_institutional_holdings` stops on the first page holding a 13F-HR or 13F-NT for the quarter, and runs the #86 operating-company routing only when neither `recent` nor the pages read hold any 13F-HR or 13F-NT — a notice-only manager asked for a quarter it filed nothing for gets the plain quarter miss (#117, #133); without a `quarter`, a manager whose `recent` holds 13F-NT notices and no 13F-HR gets the notice message for its newest notice rather than the #86 classification (#133). **Page selection widens both date bounds by a day:** a manifest page's `filingFrom` / `filingTo` can sit a day off its own rows in either direction (JPMorgan's page 041 is listed to 2021-02-17 but holds 42 filings dated 2021-02-18; Apple's page 001 is listed a day past its newest row), so an exact overlap test skipped the page holding a window's edge day. The slack costs at most one extra page per bound, and every caller filters rows by their own filing dates (#137)
105
105
  - **13F amendment composition:** `get_institutional_holdings` composes a quarter from the original 13F-HR and its same-period 13F-HR/A amendments (`composeHoldings`), ordered by `acceptanceDateTime`, then filing date, then accession — never `amendmentNo`, since filers skip numbers and two amendments can land on one day. A `RESTATEMENT` replaces everything composed so far, earlier `NEW HOLDINGS` included, so the base is the last restatement whose table reads (the original when none does) and nothing before it is read (`superseded`). A `NEW HOLDINGS` after the base appends its rows, unless its table repeats every composed row (CUSIP, class, put/call, discretion, shares, share type; value is left out because its unit changed on 2023-01-03) — a mislabeled resubmission that would double the portfolio — in which case it applies as a restatement. Each accession's values normalize by its own filing date. An amendment whose type, index, or table cannot be read, or whose table has no rows, is `not_applied` instead of blanking the quarter. The original's table is always read (it backs `total_holdings_in_filing`); each amendment table is two more requests on the call's `CallScope`, and a 429 or a spent budget stops further optional reads (#198).
106
106
  - **Filing metadata outside `recent`:** `get_filing` takes `form`, `filing_date`, and `period_ending` from `recent` when the accession is there, else from the filing's own SEC header — the raw `<TYPE>` / `<FILING-DATE>` / `<PERIOD>` in `index-headers.html`, which the tool already fetches to type the documents, and only when that page 404s (common before 2014) the sub-1 KB `<accession>.hdr.sgml`. `FILING-DATE` is the filing date, not the acceptance timestamp, and matches the submissions feed; an S-8 or Form 4 header has no `PERIOD`. `company_name` stays the current registrant name (#126), read from the feed of the CIK whose directory served the filing
@@ -111,7 +111,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
111
111
  - **Section matching:** `get_filing`'s `section` compares through `foldForHeadingMatch` (`filing-to-text.ts`) on **both** operands — Unicode whitespace runs collapse to one space, U+2018/U+2019 → `'`, U+201C/U+201D → `"`, then lowercase. Comparison-time only: `FilingHeading.heading`, the `outline` output, `content[]`, and every character offset keep the document's own bytes. EDGAR headings carry NBSP runs and typographic quotes, so a caller re-sending an outline heading through a UI that normalizes either one never byte-matched the heading it came from — which broke the `section_not_found` recovery loop the error's own hint points at (#106). No fuzzy matching — `"item 8"` resolves only to Item 8 — but every tier runs on folded operands, so a single-spaced needle also reaches a heading whose marker carries an NBSP run or a double space (`Item 9.` in a 2004 10-K). Folding only one operand does not fix the round trip. One boundary (`sectionMatches`): a needle ending in a number never continues into a longer one. A trailing digit never runs on into another digit, so `item 1` matches `Item 1.` and `Item 1A` but never `Item 12`, and `item 5` reaches an 8-K's `Item 5.02` while `item 5.0` does not. A trailing roman numeral (a final word of `i`, `v`, `x`) must end at a space, punctuation, or the heading's end, so `part i` never matches `PART II`, `PART III`, `PART IV`, or `PART II, III`: Sono-Tek's 10-Q (0001171520-26-000305), which prints Part I only inside a one-line TOC, landed `part i` on `PART II - OTHER INFORMATION`, and Microsoft's FY2026 10-K on `PART II, III` (348204). `part i` now falls through to the line tier (Microsoft: the body `PART I` at 6900) or misses with the outline (Sono-Tek; an S-1, whose Part I is the unlabeled prospectus). Plain-text outlines keep TOC rows worded differently from their body heading, and a TOC row for Item 10–16 precedes the body Item 1 — a bare substring test landed `item 1` on another Item in 6 of 37 plain 10-K/10-Q outlines and 1 of 270 HTML landings (#136). **Resolution order (#169, #166, #177)**, first hit wins, over every detected heading (`detectHeadings(text)`, which takes no cap, run once per call — the 50-entry cap belongs to the rendered outline alone; with the first 50 only, a heavy 10-K's financial-statement captions put Items 9B–16 out of reach) and the document's own lines: (1) **exact** (`resolveSection`) — a heading whose `headingKey` (the dedup key: the fold, a terminal-punctuation strip, and the marker separator folded to one space) equals the needle's, or whose title after its Item/Part marker does — failing that, the same with a leading sub-item label removed (below); a bare marker (`ITEM 1.`, `Part II`) has no title and is never a candidate, or GSBD's `item 1` jumps to a bare TOC `ITEM 1.`. The tier exists for #170's widened all-caps class: CCC's `SPECIAL NOTE REGARDING FORWARD-LOOKING STATEMENTS AND RISK FACTORS` (7562) otherwise takes `risk factors` from `Item 1A. Risk Factors.` (67351). (2) **Item/Part substring** — the first Item or Part heading (`isStructuralHeading`, bare and run-in markers included) that `sectionMatches`: a value inside an Item title names that Item, while a line equal to it is often a table-row label (CCC's `compensation` → `Item 11. Executive Compensation` at 493087, not the `Compensation` cell at 418658). (3) **an equal line** and (5) **a table-row label, else a prefix line** — a document line (`matchSectionLine`, `filing-to-text.ts`, which reports whether its line ranks in tier 3; `findSectionLine` is its offset alone), for a mixed-case subheading the outline never lists (`Liquidity and Capital Resources`): a line whose `headingKey` equals the needle's and that labels no table row (3), else — only when no such line exists — the first equal line that labels one (5, below), else one that starts with it (5) at a word boundary within `MAX_TITLE_CHARS` (a date-suffixed title: `Consolidated Schedule of Investments as of June 30, 2026`), unless a one-word needle runs on into a longer Title Case title (`continuesIntoLongerTitle`: the next word opens on a capital in a line that is not all caps). One word heads many unrelated titles — `business` landed on `Business Combinations.` (C3is), `Business Seasonality and Product Introductions` (Apple 10-Q), and a cross-reference line `Business Overview—Governmental regulations…` (DRDGOLD); a needle of two or more words keeps its continuation (`Human Capital` → `Human Capital Management`), and a suffix opening lowercase or on punctuation (`(continued)`, `—Parent Company Only`) always does. The cost: `forward-looking` no longer reaches `Forward-Looking Statements`, nor `revenue` `Revenue Recognition`; both miss with the outline. Equality goes first because a prefix match alone lands `Competition` on an earlier line that merely begins with the word. **A table-row label ranks in tier 5, ahead of a prefix line (#184):** an equal line labels a row when its next line with content (spacer lines passed over) is a figure row, or is a label — at most 60 characters, opening uppercase, ending on no `.`, `:`, `;`, or `,`, closing quotes and brackets passed over (a cross-reference `See “Item 18. Financial Statements.”` over its page number is no label) — whose next line with content is one (`labelsTableRow`; Microsoft's segment table `Revenue` / `Client` / `$ 9,350 …`). A figure row is a lone currency or nil cell (`$`, `-`, `–`, `—`), or a line whose text after its last letter holds a digit and, when the line has a letter, opens on a dotted leader, a tab, or two or more spaces behind a label of at most 60 characters (`isFigureRow`: `Product sales....... $4,759`; ``$ 7,746 $ `7,835``, a stray backtick in a 2004 cell); one space never qualifies (`The effective rate was 21%.`), and past the label bound the line is a table set on one line, which a heading may sit over (AMC Robotics' S-1 0001493152-26-047958: MD&A `Revenue` at 177926 over `Three months ended June 30, 2026 2025 $ Change …`). All 13 `Revenue` lines in Microsoft's 2004 10-K (0001193125-04-150689) label rows, and as tier-3 lines took `revenue` from `SEGMENT PRODUCT REVENUE/OPERATING INCOME (LOSS)` (81018) to the selected-data row at 66987; Aware's `Revenue:` over `Product sales....... $4,759` (112947) took it from `CONTRACT REVENUE` (49489). Demoted rather than skipped, a row label still lands when no heading contains the value (`total revenue` keeps its income-statement row), under the plain line notice. The test reads at most two content lines past an equal line. Over 26 corpus filings × 104 section values it labels 124 lines on the resolution path, none a detected heading, and moves 22 landings and no outline entry: 15 from a row label onto a heading or prose subheading for the value (Microsoft FY2026 `revenue` → its MD&A `Revenue` subheading at 217873; `earnings per share` → the EPS note in both Microsoft 10-Ks), 2 onto a table's caption line, 1 onto another row label (BAB's `goodwill`, from its balance-sheet row to a note table's), and 4 onto a heading that only contains the words (Arxis `net income` → `NOTE 16. NET INCOME (LOSS) PER SHARE`, and Nutanix's → `NOTE 11. NET INCOME (LOSS) PER SHARE` past a `Net income` row of `—` cells; CCC `net income` → the all-caps row label `NET INCOME (LOSS) INCLUDING NON-CONTROLLING INTEREST`, a detected heading; CCC `revenues` → `COST OF REVENUES` at 332106, since all four of its `Revenues` lines label rows). In both line tiers a line is skipped when it opens lowercase (a wrapped sentence or bullet); when it sits under a line ending on a comma or semicolon, or opens on an unpunctuated Item marker followed by a lowercase word (a wrapped cross-reference, the `followsMidSentence` / `isWrappedProse` guards heading detection applies: `…in Part II,\nItem 8 on this Form 10-K…`); or when it is a TOC row (`isTocRow`). A TOC row ends in a page cell set off by **two or more** spaces or a tab (`TOC_PAGE_TAIL_RE`; one space would read the year in `as of June 30, 2026` as a page number), or its next line with content is a page cell (`PAGE_CELL_LINE_RE`: a number, `F-3`, or a lowercase roman `ii`, which counts only on its own line — `Part iv` is not a page cell); either form may put a `Page` word before the number (`Page 3`), spacer lines passed over (an HTML TOC table puts NBSP rows between its cells). A line that is not a marker, followed directly by an Item/Part marker, is a TOC title cell with no page column; a marker run straight into its title counts (`MARKER_LINE_RE` takes `TITLE_RUN_IN`, #180: `Item 2Properties`). A marker line — a Part over its first Item — is a TOC row when that Item row is: the Item line ends in a page cell, the line below it holds or ends in one (a title cell, or Aware's wrapped `of Equity Securities....... 12`), or, for a bare marker, the line below its title holds one. Microsoft's FY2026 10-K prints body `PART IV` only as page furniture, so `part iv` reaches the line tier, where `PART IV / Item 15. / Exhibit and Financial Statement Schedules / 93` was taken; it now lands on the body's first `PART IV` (352884). A body Part sits over its Item too, but prose follows, not a page cell. The first remaining line wins, at its first non-blank character; one linear pass serves tiers 3 and 5, run only after tiers 1 and 2 miss, so a value landing on a tier-4 heading now pays that pass (7–11 ms on a 1 MB S-1). A cut page's guidance after a `section` landing says to pass `next_offset` as `offset` without `section`, which outranks `offset` — kept, it returns the same page. A line landing says so in the notice, composed into the truncation guidance when the page is cut (`notice` is last-wins): `No detected heading matches section '<value>', so this page starts at the first document line that does.` — no new output field. An equal line that outranked a heading merely containing the value says `No detected heading equals section '<value>', so this page starts at the first document line that does, ahead of headings that only contain it.` instead, since that heading does match by substring. Every #166 acceptance offset holds. (4) **other substring** — the first other heading that `sectionMatches`, after the equal line: a heading that merely holds the word took Arxis' S-1 `business` to `NOTE 3. BUSINESS COMBINATIONS` (544705) past its `Business` heading line (323578), and CCC's `revenue` to `COST OF REVENUES` (332106) past the MD&A `Revenue` subheading (256790). An exact or Item/Part heading still beats an equal line (Reddit's `use of proceeds` → the `USE OF PROCEEDS` heading); every other heading ranks after one. Over 67 corpus filings × 103 section values the order moved 24 landings, each one the validation predicted: 17 onto the section named (Microsoft FY2026 `general` → `GENERAL` at 8720, not `GENERAL RISKS`; DRDGOLD's `risk`, `directors`, `management`, and `employees` → body Items instead of TOC rows), and 7 onto a different place that is defensible but that a reader may like less, since an Item heading or a line equal to the value now outranks a heading that only holds it — JPM's 10-Q `risk` lands on Item 3, a one-sentence cross-reference, not `FIRMWIDE RISK MANAGEMENT`; `revenue` in Microsoft's 2004 and FY2026 10-Ks and Aware's on a selected-data, MD&A-table, or income-statement row label rather than a heading containing the word — the three landings tier 5's row labels move (#184, above); `summary` on Item 16 `Form 10-K Summary`; Intel's 2000 `consolidated balance sheets` on an Item 14 index row. (6) `section_not_found`. **A proxy statement keeps its headings ahead of the lines:** for a proxy or information statement form (`PROXY_FORM_RE`: DEF 14A, DEFA14A, DEFM14A, PRE 14A, DEF 14C, …), tier 1 is followed by the first heading of any kind that `sectionMatches`, then the line tiers — its ITEM headings are ballot proposals, not the Regulation S-K item taxonomy, and its lines equal to a value are mostly table cells. Under tiers 2–4 Goldman Sachs' DEF 14A (0001193125-26-117433) took `compensation` from the CD&A (123680) to `ITEM 2. … (SAY ON PAY)` (274744) and `summary` from `EXECUTIVE SUMMARY` (16953) to a Pay versus Performance column header (282286). The form is read before `section` resolves, so the `.hdr.sgml` fallback request (#126) now precedes a `section_not_found`. **Inside each heading tier a body heading ranks ahead of a table-of-contents row (#174):** a heading is a TOC row when its title line — its own line, or the next line with content after a bare or joined marker — is one by `isTocRow` (the line tiers' test), or the next line with content below it ends in a page cell (a TOC title wrapped onto a second line, Aware's `of Equity Securities....... 12`), or the title wraps once with its page cell on its own line under the wrap — the title line, one continuation line, and a `PAGE_CELL_LINE_RE` line on three consecutive lines, the continuation in the title line's case: no lowercase letter under an all-caps title line, an opening lowercase one under a mixed-case one (`of Equity Securities`) (#183). DRDGOLD's TOC row `ITEM 14.` / `MATERIAL MODIFICATIONS TO THE RIGHTS OF SECURITY HOLDERS AND USE OF` / `PROCEEDS` / `79` took `item 14` and `material modifications to the rights of security holders` at 8146 from the body heading at 433144. A body heading over one line of body text and a page number has the same three lines: across 26 filings the step without the consecutive-line and case conditions flags 47 body headings (`Item 4. Mine Safety Disclosures` / `Not applicable.` / `31`, spacer lines between or not, and DRDGOLD's `NOTE 22 ASSET HELD FOR SALE` over its page footer and `F-50`); with them it flags only that TOC row (8146) and its title cell (8155), moves those two landings, and changes no outline. An all-caps body heading over a one-word all-caps line and a page number on consecutive lines (`ITEM 4. MINE SAFETY DISCLOSURES` / `NONE` / `31`) still reads as a TOC row and lands as its tier's only match; `isTocHeading` in `filing-to-text.ts` owns the test, finding the line start from the newline before the offset since an NBSP-led Item's offset sits one past it. A TOC row still lands when it is its tier's only match. Three TOC shapes survive dedup: a row worded apart from its body heading (First Bancorp's 8-K `Item 9.01 Financial Statements and Exhibits. Page 1` took `item 9` at 2041 from the body Item at 2402), a bare all-caps marker over its title and page cells (DRDGOLD's FY2026 20-F `ITEM 3.` / `KEY INFORMATION` / `6` took `item 3` at 6174 from `ITEM 3. KEY INFORMATION` at 34346, and nearly every other `item N` the same way), and the title cell itself (`key information`). TOC rows are ranked, never dropped or pushed behind the line tiers: the test also reads a body heading over a page number (CCC's `Item 6. Reserved.` at 234199, Reddit's S-1 `PART II` at 1021631), and behind the line tiers CCC's and Microsoft's `item 6` left the body heading for a bare TOC marker line. With the dedup-key fold, the ranking moved 83 landings over the corpus, each from a TOC row onto a body heading (DRDGOLD 35, Worthington Steel 20, GSBD 9, Amazon's 2003 10-K 8, Aware 6, First Bancorp 4, CCC 1), and no other: 78 onto the body heading the row copies, 5 onto another the value names (Amazon 2003's `part ii`–`part iv` onto its body Parts, Aware's `management` from its TOC Item 12 to body Item 7, Worthington Steel's `other information` from its TOC Item 5 to body `PART II. OTHER INFORMATION`). **A leading 20-F sub-item label is ignored (#175):** 20-F filers label sub-items (`3D. RISK FACTORS`, `B. Business Overview`), so a plain-phrase value never equalled the line. Tier 1 and both line tiers also compare the heading or line key with a leading label removed (`withoutSubItemLabel`: `/^(?:\d{1,2}[a-z]|[a-z])\. /` on the folded key, anchored, so constant-time), and the one-word longer-title rule judges the line after its label — Regencell's `B. Business Overview` keeps `business` a miss while `business overview` lands (151573). The value itself is never stripped, so `3D. RISK FACTORS` still matches its own line; a line opening on an initial (`L. John Doerr`) strips the same way and so matches only a value equal to the rest of the line. The landing is the line's first character, label included (DRDGOLD `risk factors` → 34503). Tier 1 strips only once no heading equals the value as printed, so an earlier `A. RISK FACTORS` never takes `risk factors` from a later `Item 1A. Risk Factors`; a labelled body heading still ranks ahead of a TOC row. The line tiers keep the first line equal either way: across the corpus the labelled line they land on is the 20-F sub-item itself and a later unlabelled one is narrower (DRDGOLD `business overview` → `4B. BUSINESS OVERVIEW` at 176975, not `Business overview` at 269017). Over the corpus the strip moved 23 landings, all in the three 20-Fs: 19 misses now land on the labelled sub-item, and 4 earlier landings move onto one (DRDGOLD `compensation` from the `Compensation of key management` subheading inside Item 6B, 328266, to `6B. COMPENSATION` at 324690); no filing without labelled sub-item lines changed. **The outline cut (#169):** past 50 detected headings the outline is every Item/Part heading (`isStructuralHeading`, bare and run-in markers included) plus the earliest other headings up to 50, in offset order (`selectOutline`) — shared by the first-page `outline` and the `section_not_found` message and data. When the Item/Part headings alone pass 50, each bare marker that a later titled heading for the same Item or Part repeats is left out first (`outlineStructuralHeadings`): DRDGOLD's FY2026 20-F renders all 31 TOC Items as bare markers (`ITEM 3.`), which filled the cut and pushed body Items 16A–19 out; its outline now runs `ITEM 1.` through `ITEM 19. EXHIBITS` from the body. A bare marker no titled heading repeats stays, and `section` still matches every heading. The miss message heads a cut outline `Outline (50 of N detected headings):` (else `Outline:`), and a cut first page appends `The outline lists 50 of N detected headings, every Item and Part heading among them; section matches all of them.` to the truncation guidance — `…among them, bare table-of-contents copies of titled ones aside; …` when bare markers were left out (DRDGOLD: `The outline lists 50 of 142 detected headings, every Item and Part heading among them, bare table-of-contents copies of titled ones aside; section matches all of them.`), and no Item/Part clause when the kept Item/Part headings alone pass 50, which reaches `structuredContent.notice` and `content[]` — no new output field, since the outline is emitted only on a truncated first page. A document of 50 or fewer headings renders as before.
112
112
  - **Binary filing documents:** a filing index routinely carries scanned pages, PDF exhibits, `Financial_Report.xlsx`, and `-xbrl.zip` — `filingToExtract` runs `html-to-text` over whatever bytes arrive and never inspects a content type, so requesting one used to return decoded binary as `content` with no error (#96). `get-filing.tool.ts` detects them with one rule, `binaryType`: the filename extension (`binaryTypeFromName`), the one signal every filing carries, plus a header-page `GRAPHIC` type for a scan named oddly — the header page is read before the body (#161). Two halves, both needed — `documents[]` entries carry `binary: true`, and `resolveFilingArchive` throws `binary_document` before `tryGetFilingDocument` runs, since the `document` input is an unconstrained string and a catalog marker alone cannot stop a caller. Extension-driven and bucket-independent on purpose: a PDF exhibit is typed `EX-99.*` and files under `exhibits`, not among the graphics.
113
113
  - **Dataframes:** `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_fetch_frames`, `secedgar_compare_companies`, `secedgar_get_insider_transactions`, `secedgar_get_institutional_holdings`, `secedgar_get_material_events`, `secedgar_find_holders`, `secedgar_get_beneficial_owners`, and `secedgar_get_fund_holdings` materialize their full result set as `df_<id>` on a shared DuckDB-backed canvas (one per tenant). The two ownership tools register the full parsed set (inline response is a preview capped at `limit`); `get_insider_transactions` scans at least `INSIDER_CANVAS_FILING_SCAN` recent filings when canvas is available (so small inline limits don't under-scan the window), capped at 100, and flags `dataset.truncated` when more Form 4 filings exist beyond the scanned window (#63); with a `filed_after` / `filed_before` window it reads the in-window Form 4 / 4-A rows with an XML primary document — `recent`, then the archive pages overlapping the window, newest first, stopping once the scan cap plus a sentinel row are in hand — and with a canvas parses every one up to 100 instead of the 40-filing floor, since the window already bounds the set; `dataset.truncated` is then the sentinel or unread overlapping pages, and `history_scanned_through` the oldest filing parsed (#127); a company's submissions feed also lists the Form 4s it filed as a reporting owner of another issuer (JPMorgan's 10% stake in a BlackRock fund), so a parsed document whose `issuerCik` differs from the resolved CIK, compared with zero-padding stripped, adds no row inline or to the dataframe and is counted in `filings_other_issuer` — it still counts toward `filings_scanned`, the scan floor, and `history_scanned_through`, and the no-canvas stop rule is unchanged — though a skipped filing adds no transactions, so a no-canvas call reads on through such filings until `limit` transactions are in hand, within the same scan cap (#157); its `shares_traded` is an unsigned magnitude paired with a `direction` (acquire/dispose) column, so net activity is `SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END)` (#46); `get_financials`' dataframe materializes the source-filing fiscal keys as `source_filing_fy`/`source_filing_fp` (renamed from bare `fiscal_year`/`fiscal_period` — every comparative period restated in one filing carries that filing's fy/fp, so `period_end` is the time key for ORDER BY/GROUP BY/windowing) (#72); `compare_companies`' dataframe holds the FULL aligned series across every period while the inline matrix is capped at `periods`, and each row carries both the aligned `period` key and the underlying XBRL `frame` (they differ for point-in-time concepts) (#85). In an annual matrix an instant enters only on one of the filer's fiscal-year ends and takes the key of the annual duration ending that day. The ends come from the companyfacts payload already in hand (`filerFiscalYearEndsWithComparatives` in `concept-series.ts`, shared with `get_financials`' annual view of an instant): each annual report's own year (the #148 rule) plus the comparative years it restates — its year-long facts ending a whole number of years earlier, within a week — so the first XBRL 10-K's prior-year balance keys too, while a year-long figure ending off the report's calendar (a December filer's trailing year to 09-30) stays out. The #148 test of a 10-Q-held annual frame keeps `filerFiscalYearEnds` (each report's own year only): it matches day of year, where a comparative year adds nothing but a wider tolerance. The key is the first `CY####` frame on any concept in the payload ending then, so a balance lands beside its fiscal year's income lines even when none is requested; with no framed duration ending on it, the calendar year in which that fiscal year's second half starts (SEC's own framing: a year ending 06-30 is that year, one ending 06-27 or 05-31 the year before — Seagate's and Western Digital's years ending 2025-06-27 are `CY2024`; SEC departs from it for the year both ended 2012-06-29, framed `CY2012`, which is why a framed key wins). Interim and cover-date instants stay out of the annual matrix, and a company-concept left with none gets a gap plus a caveat pointing at quarterly; when that empties the whole matrix, `no_comparable_data` says the values were all off fiscal-year ends and its hint names `period_type: "quarterly"` (omitting `period_type` keeps annual). Quarterly keys are unchanged. The year ends are read lazily, only when an annual matrix meets an instant (#171). The period-ends caveat checks every inline column — the newest can hold one company alone — spelling out the newest column whose ends differ and naming the others; the inline window is the newest periods of the union across companies, so a company-concept pair whose values all predate it is named in `caveats` — one line per concept, each company with its newest period and the dataframe pointer — and never in `gaps`, which keeps meaning no value in any period (#144). Each row set carries an all-nullable schema (framework's `inferSchemaFromRows` always emits `nullable: true` since mcp-ts-core 0.10.4). Per-table TTL is delegated to the framework via `RegisterTableOptions.ttlMs` (resolved in mcp-ts-core#140); bridge still tracks metadata expiry in `ctx.state` for provenance. Every producer emits the describe-then-query pointer on the branch that registers the dataframe, composed once by `dataframeGuidance(dataset)` in the bridge so the wording cannot drift; where a truncation call already fires there it rides as that call's `guidance`, since `ctx.enrich.notice` is last-wins across `notice`/`truncated` and a second call would clobber the first (#104). `secedgar_dataframe_query` detects a `row_limit`-bound result from `QueryResult.truncated` rather than `rowCount > rows.length` — `row_limit` is pushed into the query as the provider's cap, so a capped result comes back with `rowCount === rows.length` and the arithmetic cannot see it; `rowCount` is then the cap and not a total, so that branch names the cap instead of printing "of N rows", `row_count_capped` carries the same disclosure into `format()`, and the fallback comparison stays for the `registerAs` path, where `truncated` is never set. A SQL `LIMIT` exactly equal to the cap is indistinguishable from a result that holds that many rows and is reported as exact (#109). `secedgar_dataframe_query` runs framework's SQL gate with `denySystemCatalogs: true` to block `information_schema`, `pg_catalog`, `sqlite_master`, and `duckdb_*` catalog access. Raw DuckDB execution errors (missing table, syntax) are caught in `bridge.query` and re-thrown as structured `missing_table`/`invalid_sql` reasons, with DuckDB's "Did you mean …?" hint stripped so internal catalog names don't leak (#47). The framework's own classifications pass through untouched and are declared on the tool's contract (`thrownBy: 'service'`, since the handler never names them): a SELECT that prepares and then fails on the data — a `Conversion` / `Invalid Input` / `Out of Range` error, e.g. `CAST('abc' AS INTEGER)` — is `ValidationError` with `sql_execution_error` (mcp-ts-core 0.13.4; `DatabaseError` with no reason before), and the gate's `multi_statement`, `denied_function`, `sql_read_only`, and `plan_operator_not_allowed` rejections arrive with their own recovery hints — since mcp-ts-core 0.13.15 the gate also denies engine-setting and SQL-from-string functions (`current_setting`, `query_table`) as `denied_function` and a file named as a table (`FROM 'data.csv'`) as `sql_read_only`, and since 0.13.16 it refuses any unqualified `current_schema`, since the parse tree cannot tell the bare function from a column of that name — a staged or aliased column so named is read qualified (`c.current_schema`). `get_beneficial_owners` registers one row per reporting person rather than one per filing, since powers and percent of class are per person, and each row carries the filing's `purpose_of_transaction` and the person's `notes` uncut, the text the inline result bounds (#200); `get_fund_holdings` registers every position in the report while the inline list is one `limit`-sized page from `offset`, and its rows carry the fund keys (`series_id`, `registrant_cik`, `report_period_date`, `accession_number`) so a portfolio joins the 13F and 13D/G rows on `cusip`. Insider rows carry `issuer_cik` and no `cusip`, 13F rows the reverse; 13D/G rows carry both.
114
- - **Beneficial ownership (13D/13G):** SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML under the `SCHEDULE 13D` / `SCHEDULE 13G` names on **2024-12-18**; the changeover is total, so a legacy-name filter matches nothing recent and a current-name filter matches nothing older. The two schedules are **separate schemas, not one shape with optional fields** — 13D repeats `reportingPersons/reportingPersonInfo` with the power fields flat on each person and the percentage in `percentOfClass`; 13G repeats `coverPageHeaderReportingPersonDetails` with the powers nested inside `reportingPersonBeneficiallyOwnedNumberOfShares`, the percentage in `classPercent`, no reporting-person CIK anywhere, and no purpose-of-transaction field at all (its item 4 is structured ownership data, which is what makes it the passive form). `beneficial-ownership-parser.ts` therefore branches per schema and dispatches on the submission type, falling back to whichever repeated reporting-person element the document carries. **Ownership powers and percent of class are per reporting person, including on joint filings** — a fund, its adviser, and its controlling principal each report the same underlying shares, so the parsed owner list is never collapsed to a group total and the percentages must not be summed. Discovery runs off the issuer's own `getSubmissions()`: SEC cross-lists a schedule under every CIK party to it, so no entity-scoped EFTS step is needed. **Filer text is data, kept as filed and bounded per field:** Item 4 `purpose_of_transaction` and each person's cover-page `notes` keep their line breaks (CR and CRLF as filed) and come back whole up to 5,000 and 2,000 characters; past that, the value is its first N characters with nothing appended and `purpose_truncated` / `notes_truncated` say so, on both surfaces. Item 4 is the substantive 13D field: 5,000 sits just above the 90th percentile of 48 sampled Item 4s (4,916), where 1,200 cut 34 of them, and uncut the 20 longest sampled make a 136.5 KB response; 2,000 clears the longest of 77 sampled notes (1,852), and a bound stays because reporting persons per filing are unbounded. When anything was cut, the cut count and the pointer to the whole text — the dataframe's uncut columns, or `secedgar_get_filing` on the accession — ride the tool's one composed notice. `format()` renders each value as a blockquote through `escapeMarkdownInline`, every line prefixed `> ` (indented under a note's list item) and the cut marker after it, behind a blank line so the marker and the next block cannot lazily continue the quote; reporting-person names, `security_class`, `issuer_name`, and the cover-page codes render escaped too (#200).
114
+ - **Beneficial ownership (13D/13G):** SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML under the `SCHEDULE 13D` / `SCHEDULE 13G` names on **2024-12-18**; the changeover is total, so a legacy-name filter matches nothing recent and a current-name filter matches nothing older. The two schedules are **separate schemas, not one shape with optional fields** — 13D repeats `reportingPersons/reportingPersonInfo` with the power fields flat on each person and the percentage in `percentOfClass`; 13G repeats `coverPageHeaderReportingPersonDetails` with the powers nested inside `reportingPersonBeneficiallyOwnedNumberOfShares`, the percentage in `classPercent`, no reporting-person CIK anywhere, and no purpose-of-transaction field at all (its item 4 is structured ownership data, which is what makes it the passive form). `beneficial-ownership-parser.ts` therefore branches per schema and dispatches on the submission type, falling back to whichever repeated reporting-person element the document carries. **Ownership powers and percent of class are per reporting person, including on joint filings** — a fund, its adviser, and its controlling principal each report the same underlying shares, so the parsed owner list is never collapsed to a group total and the percentages must not be summed. Discovery runs off the issuer's own `getSubmissions()`: SEC cross-lists a schedule under every CIK party to it, so no entity-scoped EFTS step is needed. **Filer text is data, kept as filed and bounded per field:** Item 4 `purpose_of_transaction` and each person's cover-page `notes` keep their line breaks (CR and CRLF as filed) and come back whole up to 5,000 and 2,000 characters; past that, the value is its first N characters with nothing appended and `purpose_truncated` / `notes_truncated` say so, on both surfaces. Item 4 is the substantive 13D field: 5,000 sits just above the 90th percentile of 48 sampled Item 4s (4,916), where 1,200 cut 34 of them, and uncut the 20 longest sampled make a 136.5 KB response; 2,000 clears the longest of 77 sampled notes (1,852), and a bound stays because reporting persons per filing are unbounded. When anything was cut, the cut count and the pointer to the whole text — the dataframe's uncut columns, or `secedgar_get_filing` on the accession — ride the tool's one composed notice. `format()` renders each value as a blockquote through `escapeInline`, every line prefixed `> ` (indented under a note's list item) and the cut marker after it, behind a blank line so the marker and the next block cannot lazily continue the quote; reporting-person names, `security_class`, `issuer_name`, and the cover-page codes render escaped too (#200).
115
115
  - **NPORT-P series routing:** a fund's public portfolio report covers **exactly one series**, a registrant trust holds many (iShares Trust: 390 listed series, 200+ reports for a single period), and the series identity appears **only inside the document** — neither the submissions feed nor EFTS carries `seriesId` on an NPORT-P row. Routing is therefore series-first: EDGAR's company browse accepts a series ID in place of a CIK (`getFundSeriesFilings`), which is the one SEC surface mapping a series to its accessions and which also names the registrant, so a bare series ID resolves in one request. The browse feed's registrant outranks any registrant the `fund` input implied, since `series_id` can name a series of an entirely different trust and the archive path is keyed on the registrant. The bounded header scan (`tryGetFilingDocumentHead` + `parseNportHeader`, cap `SERIES_SCAN_LIMIT`) is the fallback and the disambiguator for a trust whose series carry no listed ticker; SEC's archive host **ignores `Range`** (a ranged request answers 200 with the whole body), so the saving is client-side stream cancellation only — and the cutoff cannot cut below one read chunk, which Bun sets at 262,144 bytes, so `HEADER_MAX_BYTES` binds only on a document arriving in several chunks. **A registrant's own NPORT-P list is never the candidate set for a series-structured trust**: series fiscal quarters are staggered, so the list interleaves funds and one report at the newest period does not mean one fund — it means the fund whose quarter ends latest. The scan therefore runs on the newest batch even when that batch holds one report, and a series found there re-routes through the browse feed; only a report naming no series at all (a closed-end fund, which also carries no `classId`) is answered from the registrant's list. Candidates are ordered by **reported period, not filing date**: an `NPORT-P/A` restating an old period is filed after every report of the periods that followed it. Reports publish on a ~60-day lag, so `report_period_date` and `publication_lag_days` are first-class output and the `as_of` enrichment states both.
116
116
  - **Local mirror (opt-in, `EDGAR_MIRROR_ENABLED`):** routes `resolveCik`, `tryGetCompanyConcept`, `tryGetCompanyFacts`, and `tryGetFrames` to a local SQLite mirror (framework `MirrorService`) of `company_tickers.json` + the `companyfacts.zip` bulk archive; the live API is the fallback on a miss (`EDGAR_MIRROR_FALLBACK_LIVE`). Bootstrap out-of-band with `bun run mirror:init`; refresh nightly via cron (HTTP) or `bun run mirror:refresh`. The three `mirror:*` commands also ship in the production Docker image — run them against a deployed container with `docker exec <container> bun run mirror:<init|refresh|verify>`. Node/Bun only — skipped on Workers. Frames are assembled from the company-facts store, so `loc` (business location) is absent. The ingester stores a tag's own name when SEC serves it with no label (`InterestExpenseNonoperating`), so every read path treats a stored label equal to a camel-case compound tag as no label (`storedLabel`) — callers fall back to the concept's label, and `getFrames` answers an empty `label` as the live frames API does; a one-word element's label is the word itself (`Revenues`) and is kept. Read-side, so stored rows need no migration. No FTS5 — every routed lookup is exact/indexed (cik+taxonomy+tag point, taxonomy+tag scan, cik scan for the whole-company read, ticker/CIK). Mirror ingests MF fund symbols from `company_tickers_mf.json`; on the mirror path a live MF merge supplements them when `FALLBACK_LIVE` is on (superseding the mirror's bare fund rows with series/class, and covering a mirror synced before MF ingestion), so funds resolve there too (#43, #135).
117
117
 
@@ -246,7 +246,10 @@ src/
246
246
  canvas-bridge.ts # Framework DataCanvas adapter, df_<id> minting, per-table TTL
247
247
  sql-gate-extras.ts # Bridge-layer system-catalog deny on top of framework SQL gate
248
248
  mcp-server/
249
+ tools/ambiguous-matches.ts # Candidate list (message text + `matches` data) for an ambiguous company resolution
250
+ tools/escape-inline.ts # escapeInline — escapeMarkdownInline in time linear in its input length (mcp-ts-core#809), for every unauthored string a format() renders
249
251
  tools/fixed-point.ts # Fixed-point rendering of parsed numbers without rounding their digits
252
+ tools/format-usd.ts # USD amounts scaled by magnitude (T/B/M/K, sign before the $) and every-digit grouping for content[] (#222)
250
253
  tools/form-filter.ts # `forms` normalization (trim, uppercase, drop blanks) shared by search_filings and company_search (#194)
251
254
  tools/limit-clamp.ts # Over-cap numeric inputs served at the cap (#197) and ID lists answered to the cap (#201), behind EDGAR_CLAMP_OVERSIZED_LIMITS
252
255
  tools/definitions/
@@ -449,7 +452,7 @@ import { getEdgarApiService } from '@/services/edgar/edgar-api-service.js';
449
452
  - [ ] `ctx.log` for logging, `ctx.state` for storage
450
453
  - [ ] Handlers throw on failure — typed `errors[]` contract + `ctx.fail(reason, …)` when failure modes are known; factories or plain `Error` for ad-hoc throws. No try/catch.
451
454
  - [ ] Tool error contracts include `recovery` strings (≥5 words)
452
- - [ ] `format()` renders all data the LLM needs — Claude Code reads `structuredContent`, Claude Desktop reads `content[]`; both must carry the same data
455
+ - [ ] `format()` renders all data the LLM needs — Claude Code reads `structuredContent`, Claude Desktop reads `content[]`; both must carry the same data. Every string the server did not author (SEC text, caller input, SQL results) renders through `escapeInline` (`src/mcp-server/tools/escape-inline.ts`) — the framework's `escapeMarkdownInline`, kept linear in its input length until mcp-ts-core#809 lands — and JSON meant to be copied back into a call renders as a code span (`markdown().inlineCode`), so it reads back under CommonMark as the `structuredContent` value
453
456
  - [ ] EDGAR upstream sparsity: schemas reflect real nullability; `format()` preserves uncertainty (don't fabricate facts from missing XBRL fields); tests cover at least one sparse payload
454
457
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
455
458
  - [ ] Tests use `createMockContext({ errors: tool.errors })` from `@cyanheads/mcp-ts-core/testing` for tools with declared contracts
package/CLAUDE.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Agent Protocol
2
2
 
3
3
  **Server:** secedgar-mcp-server
4
- **Version:** 0.17.1
4
+ **Version:** 0.18.0
5
5
  **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`
6
6
  **Engines:** Bun ≥1.4.0, Node ≥24.0.0
7
7
  **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0
@@ -87,7 +87,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
87
87
  - **User-Agent required:** `"AppName contact@email.com"` on every SEC request or IP gets blocked
88
88
  - **CIK zero-padding:** the `data.sec.gov` APIs (submissions, companyfacts, companyconcept) require the 10-digit zero-padded CIK (`String(cik).padStart(10, '0')`). Archive paths under `www.sec.gov/Archives/edgar/data/` take it unpadded — SEC answers the padded path with a 301, and `fetch` follows it inside the same pacer slot, so every archive read would cost two requests. `filingArchiveUrl` (exported from `edgar-api-service.ts`) strips the zeros for all seven archive reads and for `get_filing`'s `filing_url` (#156)
89
89
  - **ETF/mutual-fund tickers:** `loadTickerCache` fetches `company_tickers_mf.json` alongside `company_tickers.json` and merges fund symbols (VOO, SCHD, JEPI…) into `byTicker`. Fund CIKs are registrant trusts (1:many with series), so fund rows go into `byTicker` only — never `byCik`, whichever source they come from. Resolved fund matches carry `seriesId`/`classId` from the live MF file, the only source of either. On a mirror-served ticker base the live MF fetch is merged in when `EDGAR_MIRROR_FALLBACK_LIVE` is on, so fund tickers resolve even if the mirror predates MF ingestion (#43); strict mirror-only (`FALLBACK_LIVE=false`) uses the mirror's own MF rows (ticker→CIK, no series/class). The mirror stores a fund symbol with an empty name — its schema has no series column — and `mirrorIndexRow` reads that empty name as the fund marker; a symbol claims `byTicker` in the order equity → live fund → mirror fund, so a live entry supersedes the mirror's bare row and keeps its series (#135). **The live fund slice has its own failure window:** a failed MF load (any HTTP failure, a malformed body, the block gate's refusal) is not cached for the ticker-cache TTL — `loadMfTickers` returns no rows and a `retryAt` `FUND_SLICE_RETRY_MS` (60 s) out, or the error's `retryAfter` when longer, so nothing is retried while the gate is closed. The first resolution after it refetches the file once, single-flight, onto the cached base (`reloadFundSlice`), which keeps its own load time: the equity index is not refetched and its TTL does not move. A per-resolution retry was rejected — against a persistent 5xx it adds three requests and ~3 s of backoff to every lookup (#119). Each failed load logs one warning through the framework's global `logger` (no request context to attach to) carrying `endpoint: 'company_tickers_mf'` (never the URL — framework log guidance keeps URLs out of log fields), the HTTP status or `malformed_body`, and the retry delay (#43).
90
- - **Name and ticker resolution:** `resolveCik` walks numeric CIK → the `/^[A-Z]{1,5}$/` ticker fast path → the name passes (exact → exact once folded → prefix once folded → substring over `allEntries`) → a catch-all `byTicker` lookup for symbols whose shape skipped the fast path. Three normalizations hang off that chain. The name passes' **exact** tier also compares suffix-normalized forms (`normalizeCompanySuffix`): the terminal whitespace-delimited token only, a trailing `.`/`,` stripped as part of recognizing it, expanded to one of four canonical long forms — `corp`→`corporation`, `inc`→`incorporated`, `co`→`company`, `ltd`→`limited`. **The four buckets are never merged.** The registry carries distinct registrants differing only in which suffix they use (`TORO CO` 0000737758 vs `TORO CORP.` 0001941131, and the same shape on Blue Owl and Fluent), so a single "has a corporate suffix" marker would compare two companies equal. Only the terminal token is rewritten — the same words sit mid-name in titles ending in a different suffix (`American Water Works Company, Inc.`) — and a terminal token that merely contains one (`Ltd./ADR`) is not a suffix. Punctuation elsewhere in a name is the fold's (below). `llc`/`plc` and the `lp`/limited-partnership family get no bucket and must never fold into the `ltd` bucket (#107); they drop for a bare query (below) but never normalize into one of the four. The name passes **resolve within the best tier a current name reaches**: several CIKs there are the ambiguity, listed without the tiers below, so `Itron` resolves to ITRON, INC. instead of listing SOLITRON and POSITRON beside it. The exact tier also matches a registry name minus its terminal suffix and a comma before it (`stripCompanySuffix` over `DROPPABLE_SUFFIXES`: the four buckets plus `plc`, `llc`, `lp`, `nv`, `sa`, `ag`, and `se`, with or without periods), so `Apple` names `Apple Inc.` exactly. The wider set is deliberate: with the four buckets alone, `Rio Tinto` silently picked RIO TINTO LTD over RIO TINTO PLC; now both drop to an exact hit and tie. Only the registry side is stripped, so `Toro Co` never meets `TORO CORP.` and `Rio Tinto plc` never meets RIO TINTO LTD, and two suffix variants of one base name (`Blue Owl Capital`) tie. Current names (registry rows, which carry a ticker) choose the tier. A former name joins at that tier or better but never outranks one — otherwise `Travelers` resolves to Citigroup through its former name `travelers inc` — and decides alone only when no current name matches (`Facebook Inc`). Against the 2026-10-02 registry plus the former-names asset, 930 of 34,865 name queries move from ambiguous to resolved and no resolved CIK changes (#155). The **punctuation fold** (`foldNamePunctuation`, #210) deletes `,` `.` `'` `’` from the query and from every current and former name, so `QXO Inc` meets `QXO, Inc.`, `Fluent Inc` meets `Fluent, Inc.`, and `Jeffs Brands` the former name `jeffs' brands ltd`; a period is deleted, never spaced, so `U.S. Bancorp` meets `US BANCORP \DE\`. It is comparison-only — returned names and `suggestCompanies` never see it — and a helper of its own: `normalizeCompanySuffix` and `stripCompanySuffix` read the as-written strings, and the folded tiers run them again on the folded forms. Tier order: exact as written, exact once folded, prefix once folded, substring as written. Exact as written ranks first so a title typed as listed never ties a former name equal to it only once folded (`McGraw Hill, Inc.` stays alone beside S&P Global's former `mcgraw hill inc`), and substring stays as written, since a folded `Embassy Bancorp, Inc.` contains `sy bancorp inc` and would answer `S.Y. Bancorp Inc` with another bank. Without the fold a weaker tier answered a punctuation-free spelling with another registrant (`BlackRock Inc` reached BLACKROCK INCOME TRUST, INC. by prefix, `Block Inc` H&R BLOCK INC by substring). Against the 2026-11-03 registry plus the former-names asset, no title queried as listed changes its answer and no title or former name changes CIK; six former names typed as listed move to `multiple_matches` with the current registrant first, since a current title now matches them too (`energizer holdings inc` lists ENERGIZER HOLDINGS, INC. ahead of the former holder). `\DE\`-style state tags, `&` `-` `/`, and conformed names that space their initials (`J M SMUCKER Co`) stay out of scope. The **catch-all ticker lookup** retries a dotted symbol with `.`→`-` on a miss — brokers and market data write `BRK.B` where `company_tickers.json` lists `BRK-B`, and that file carries exactly one dotted ticker (a placeholder), so the substitution cannot land on the wrong registrant. The early gate stays untouched: it is a fast path, not the only ticker lookup, and `search_filings`' `ticker:` token inherits the fix through `resolveCik` with no change of its own (#110)
90
+ - **Name and ticker resolution:** `resolveCik` walks numeric CIK → the `/^[A-Z]{1,5}$/` ticker fast path → the name passes (exact → exact once folded → exact once initials join → prefix → substring over `allEntries`) → a catch-all `byTicker` lookup for symbols whose shape skipped the fast path. Four normalizations hang off that chain. The name passes' **exact** tiers also compare suffix-normalized forms (`normalizeCompanySuffix`): the terminal whitespace-delimited token only, a trailing `.`/`,` stripped as part of recognizing it, expanded to one of four canonical long forms — `corp`→`corporation`, `inc`→`incorporated`, `co`→`company`, `ltd`→`limited`. **The four buckets are never merged.** The registry carries distinct registrants differing only in which suffix they use (`TORO CO` 0000737758 vs `TORO CORP.` 0001941131, and the same shape on Blue Owl and Fluent), so a single "has a corporate suffix" marker would compare two companies equal. Only the terminal token is rewritten — the same words sit mid-name in titles ending in a different suffix (`American Water Works Company, Inc.`) — and a terminal token that merely contains one (`Ltd./ADR`) is not a suffix. Punctuation elsewhere in a name is the fold's (below). `llc`/`plc` and the `lp`/limited-partnership family get no bucket and must never fold into the `ltd` bucket (#107); they drop for a bare query (below) but never normalize into one of the four. The name passes **resolve within the best tier a current name reaches**: several CIKs there are the ambiguity, listed without the tiers below, so `Itron` resolves to ITRON, INC. instead of listing SOLITRON and POSITRON beside it. The exact tier also matches a registry name minus its terminal suffix and a comma before it (`stripCompanySuffix` over `DROPPABLE_SUFFIXES`: the four buckets plus `plc`, `llc`, `lp`, `nv`, `sa`, `ag`, and `se`, with or without periods), so `Apple` names `Apple Inc.` exactly. The wider set is deliberate: with the four buckets alone, `Rio Tinto` silently picked RIO TINTO LTD over RIO TINTO PLC; now both drop to an exact hit and tie. Only the registry side is stripped, so `Toro Co` never meets `TORO CORP.` and `Rio Tinto plc` never meets RIO TINTO LTD, and two suffix variants of one base name (`Blue Owl Capital`) tie. Current names (registry rows, which carry a ticker) choose the tier. A former name joins at that tier or better but never outranks one — otherwise `Travelers` resolves to Citigroup through its former name `travelers inc` — and decides alone only when no current name matches (`Facebook Inc`). Against the 2026-10-02 registry plus the former-names asset, 930 of 34,865 name queries move from ambiguous to resolved and no resolved CIK changes (#155). The **punctuation fold** (`foldNamePunctuation`, #210) deletes `,` `.` `'` `’` from the query and from every current and former name, then collapses each whitespace run to one space (#219), so `QXO Inc` meets `QXO, Inc.`, `Fluent Inc` meets `Fluent, Inc.`, `Jeffs Brands` the former name `jeffs' brands ltd`, and `Forgent Networks Inc` the former name `forgent networks inc`; a period is deleted, never spaced, so `U.S. Bancorp` meets `US BANCORP \DE\`. It is comparison-only — returned names and `suggestCompanies` never see it — and a helper of its own: `normalizeCompanySuffix` and `stripCompanySuffix` read the as-written strings, and the folded tiers run them again on the folded forms. Without the fold a weaker tier answered a punctuation-free spelling with another registrant (`BlackRock Inc` reached BLACKROCK INCOME TRUST, INC. by prefix, `Block Inc` H&R BLOCK INC by substring). Against the 2026-11-03 registry plus the former-names asset, no title queried as listed changes its answer and no title or former name changes CIK; six former names typed as listed move to `multiple_matches` with the current registrant first, since a current title now matches them too (`energizer holdings inc` lists ENERGIZER HOLDINGS, INC. ahead of the former holder). The **initials join** (`joinSpacedInitials`, #219) turns each run of two or more one-letter words in a folded form into one word (`j m smucker co` → `jm smucker co`), so `JM Smucker` and `J.M. Smucker` meet `J M SMUCKER Co` and `WP Carey` meets `W. P. Carey Inc.`; it is comparison-only like the fold, and its tier runs the suffix helpers again on the joined forms. **No hit starts or ends inside a word** (#218): a prefix must end at a word boundary of the joined name and a substring must start at one in the name as written — a boundary is regex `\b`, a letter or digit on exactly one side — so `SY Bancorp, Inc.` no longer names Embassy Bancorp through `embassy`, `helix acquisition corp ii` no longer lists the later `Helix Acquisition Corp. III`, and `ticker:MRO` (a delisted symbol) no longer scopes to PermRock Royalty Trust. Tier order: exact as written, exact once folded, exact once initials join, prefix of the joined form, substring as written. Each tier ranks above the looser one after it, so a title typed as listed never ties a former name equal to it only once folded (`McGraw Hill, Inc.` stays alone beside S&P Global's former `mcgraw hill inc`), and `US Gold` names U.S. GOLD CORP. alone instead of tying McEwen's former `u s gold corp`, equal only once joined. Substring stays as written, so a query ending mid-word still reaches a name containing it as written (`Berkshire Hath`) but never one containing it only once folded: `Helix Acquisition Corp. III` folds to a name holding `helix acquisition corp ii`. A query with no letter or digit (`.`, `'`) is `no_match` instead of folding to a string that starts every name. Against the 2026-11-03 registry plus the former-names asset (#218, #219), no title queried as listed changes its answer; of the former names typed as listed, nine move from `multiple_matches` to their own CIK (`ace ltd` no longer lists MDA Space Ltd. beside Chubb), `total` keeps its CIK in a different list, and `u s gold corp` moves to `multiple_matches` with U.S. GOLD CORP. first; 174 of the 178 joined or dotted spellings of the 63 names that space their initials resolve to their own CIK, against 15 before, the other four naming U.S. GOLD CORP.; and all 37 double-spaced former names resolve typed single-spaced, against 17 before. Only a query with no letter or digit loses its match, but a query cut short mid-word that the prefix tier answered alone can now list several companies (`baldw` lists Baldwin Insurance Group beside Matson, whose former name is `alexander & baldwin inc`). `\DE\`-style state tags, `&` `-` `/`, and a dotted word SEC splits in two (`AMAZON COM INC` for `Amazon.com`) stay out of scope. The **catch-all ticker lookup** retries a dotted symbol with `.`→`-` on a miss — brokers and market data write `BRK.B` where `company_tickers.json` lists `BRK-B`, and that file carries exactly one dotted ticker (a placeholder), so the substitution cannot land on the wrong registrant. The early gate stays untouched: it is a fast path, not the only ticker lookup, and `search_filings`' `ticker:` token inherits the fix through `resolveCik` with no change of its own (#110). **No consumer reads the first of several matches** (#223): `get_financials`, `get_snapshot`, `get_insider_transactions`, and `search_filings`' `ticker:` token throw `ambiguous_company` (`data.matches` of `cik`/`name`/`ticker`, at most 10, also listed in the message) before any SEC read; `company_search` and `get_material_events` throw `multiple_matches`, `find_holders` and `get_beneficial_owners` `ambiguous_issuer`, `get_institutional_holdings` `ambiguous_entity`, `get_fund_holdings` `ambiguous_fund`, and `compare_companies` reports a per-company `failed[]` reason `ambiguous`. `search_filings`' `cik:` token resolves a zero-padded CIK, which never matches several
91
91
  - **Former-name resolution:** `src/services/edgar/data/former-names.json` is a committed asset (generated offline via `bun run gen:former-names`) containing `[lowercasedFormerName, zeroPaddedCIK]` tuples. `buildTickerCache` folds them into `allEntries` for name search and the trigram pass. Regenerate on demand after major M&A waves — former names are immutable, so the file rarely needs updating.
92
92
  - **Near-match suggestions:** `suggestCompanies(query, allEntries)` runs a Dice-coefficient trigram pass on the zero-hit search path, returning up to 3 candidates above a threshold. Each entry is scored on its **name and its ticker**, keeping the higher of the two — one ranked, deduped, top-N list rather than two disjoint ones, so a strong ticker match can outrank a weak name match and vice versa, and a ticker-shaped miss gets help instead of a bare `no_match` (#111). An entry missing either field is simply not scored on it: former-name entries carry a name and no ticker, and MF rows carry neither a name nor a place in `allEntries`, so fund tickers stay structurally unreachable here regardless of what the scorer does. Suggestions appear in the `no_match` error `data.suggestions` and in the error message. Never auto-resolves. Only the throw that attaches suggestions names the field in its hint (`company_search` passes its own `recovery.hint`: that sentence, then the contract text); the contract's `no_match` recovery never mentions it, since a zero-hit miss with no near match and the bare-CIK 404 carry no `suggestions` (#153).
93
93
  - **XBRL friendly names:** `concept-map.ts` maps `"revenue"` → real XBRL tags; handles historical tag changes (ASC 606), including both assessed-tax variants — a filer presenting revenue gross of excise/sales tax reports only `RevenueFromContractWithCustomerIncludingAssessedTax`, and without it the walk fell through to tags SEC retired in 2018 (#98). The Including variant sits BEHIND `Revenues`, not ahead of it — the two disagree for filers that tag gross sales and net-of-excise sales under separate elements, so promoting it over `Revenues` swaps the definition partway back through the history and prints a step change that is a tag switch, not a business fact; behind `Revenues` it only fills frames no current tag covers. The same precedent places successor tags: `capex` walks `PaymentsToAcquireProductiveAssets` behind the PP&E-only tag (it also counts software and intangibles) and `interest_expense` walks `InterestExpenseNonoperating` behind both older tags, so NVIDIA, Amazon, Visa, and Microsoft reach current values and no frame the older tags cover changes (#125); the banks' `InterestExpenseOperating` (JPMorgan, Bank of America, and Wells Fargo report interest expense only under it from 2024) goes behind that, since it matches `InterestExpense` for 33 of 37 CY2025Q2 filers reporting both but `InterestExpenseNonoperating` for 0 of 4 (#147). SEC serves both successors with no label, so the line falls back to the concept's label. A different-definition tag still goes in `relatedTags`, never `tags` — `ppe_net`'s finance-lease-inclusive total is the primary line for Alphabet, Meta, and Tesla (#36, #130). `ifrsTags` covers every concept with an IFRS element confirmed present in a live 20-F filer's companyfacts; `notes_payable` is deliberately unmapped (IFRS presents borrowings as one caption, with no notes/debt split) and `shares_outstanding` is `dei`. Never add an `ifrsTags` entry from the taxonomy alone — an element existing is not evidence filers tag it (#99). `ifrsTags` order is semantic the same way `tags` is: index 0 is the counterpart of the us-gaap index-0 tag, so the same concept answers the same question under either taxonomy (`accounts_receivable` leads with the trade-only caption, not the combined trade-and-other one; `share_repurchases` with the financing outflow, not the treasury-only line a share-cancelling filer tags zero). Verify a candidate order against filers that report BOTH tags — presence alone does not settle which one leads. One concept has no right order: IFRS filers split between the employee-scheme share-based-payment element and the IFRS 2.51(a) expense total, and the two invert between filers (SAP's total is its real line with the employee element a two-period fringe; Sanofi is the exact opposite), so `stock_based_compensation` carries `ifrsTagSelection: 'coverage'` and picks per filer by which tag covers more standard periods (#101). It is the only concept that does, and the flag is scoped to `ifrsTags` on purpose — its us-gaap pair IS a ladder, since `AllocatedShareBasedCompensationExpense` is the disaggregated line and out-covers the total for Alphabet, IBM, Tesla, and P&G.
@@ -100,7 +100,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
100
100
  - **Fiscal-period caveats:** SEC reports a filer's fiscal Q4 as the 10-K residual, never as a discrete quarterly fact, so the calendar quarter that a filer's fiscal Q4 *spans* carries no frame-tagged quarterly value. That is not always the quarter holding the fiscal year-end date — a January year-end closes a fiscal Q4 running Nov–Jan, which SEC frames as calendar Q4 — and calendar-year filers are affected too (no discrete Q4). `fiscal-periods.ts` owns both directions: `fiscalQ4Caveats(period)` for the cross-company frame view (`fetch_frames`), `missingQuarterCaveats(frames)` for the per-filer series view (`get_financials`, `get_snapshot`, `compare_companies`) (#95). The per-filer detection is data-driven — no maintained filer list — and reads only the newest 4 years carrying quarterly frames, applying the per-year quorum inside that window rather than before it, because SEC frame-tagged all four calendar quarters before ~CY2021 and drops the fiscal-Q4 quarter after; a whole-history read would let the older years mask the live gap, and filtering first would let a filer whose recent years are too sparse silently describe the older regime. **Keep that slice-then-filter order.** The detector reports a *set* of absent quarters, not one: a filer whose remaining fiscal quarters also span non-calendar durations loses two (Costco tags only calendar Q1 and Q4), and the per-year quorum is two of four — low enough to admit that shape, high enough to bound the absent set at two and keep a one-quarter stub year from dragging a third in (#100). Message wording and the derivation advice differ between the one- and two-quarter cases; the three consuming tools all iterate `caveats`, so nothing downstream assumes at most one entry.
101
101
  - **`get_financials` period default:** with `period_type` unset the series defaults to `annual` (clean FY series); if the annual filter empties a non-empty series whose frames are all instant (`CY####Q#I` — balance-sheet, shares-outstanding, raw instant tags), it falls back to the full series so the first call returns data (#48). An explicit `period_type` is honored. `annual` on an instant series returns the framed instants whose `end` is one of the filer's fiscal-year ends (`filerFiscalYearEndsWithComparatives` — each annual report's own year, the #148 rule, plus the comparative years it restates, the same set `compare_companies` aligns on, so MSFT reaches its first XBRL 10-K's `CY2009Q2I` and `CY2008Q2I`), read from companyfacts only on that path — which otherwise fails — and reusing a payload already read. Selection keys on `end`, never on the frame holder's form or quarter: BSX's 2025-12-31 instant, framed on its Q2-2026 10-Q while the 10-K's own fact carries no frame, is kept with the 10-Q's provenance, and a June year end lands on `Q2I`. A cover-date concept (`shares_outstanding` for a 10-K filer, dated weeks after the year end) has no year-end instant, and a failed or `null` read selects nothing; both still fail `no_period_data`, with a hint naming which (#167). Any other explicit `period_type` that excludes everything still errors.
102
102
  - **8-K item codes:** SEC replaced the original single-integer item numbering with the current `x.xx` scheme in Release 33-8400, effective **2004-08-23**, so EDGAR's `items` field carries two disjoint vocabularies. `eight-k-items.ts` decodes by the code's **shape**, never the filing date — dotted is current, a bare integer is legacy — because filers reported pre-changeover events under the old numbers for months after the effective date, and a date-keyed table would mislabel exactly those. The two vocabularies reuse integers for unrelated events (legacy `5` is Other Events, current `5.02` is officer departures; legacy `12` is the ancestor of `2.02`), so a dotted `items` filter never matches a pre-2004 filing — `get_material_events`' zero-hit notice says so and echoes the codes actually present. The tables back three surfaces: the tool's `items` enum, the decoded per-filing rows, and the `secedgar://filing-types` resource. A code matching a shape but absent from that regime's table comes back with no label rather than a guess.
103
- - **EFTS quirks:** `dateRange=custom` must be set when using date params; the singular `entity` param is ignored — `cik:`/`ticker:` targeting passes the resolved CIK via the plural `ciks` param (server-side scope, independent of the filing's name text, so former-name filings on the same CIK are matched); `size` is ignored entirely and every request answers with 100 hits, so `find_holders` pages with `from` alone and expresses its budget in pages (5 → 500 rows). The result window is 10,000 documents, so a `from` past 9,900 is refused as a `ResponseError` body, with or without `q` and whatever the match total; `search_filings` sends `offset` as `from` only under `sort=relevance` with no entity scope on a 2001-onward range, fails a deeper `offset` there as `offset_out_of_range` before any request (`MAX_RELEVANCE_OFFSET`, which `find_holders`' continuation recipe also names), and keeps the schema's 9,999 for its other paths, which page the rows they assembled (#214). A hit is one matching **document**, not a filing: `_id` is `<accession>:<filename>`, a filing whose body and exhibits both match arrives once per document, and `hits.total.value` and the `form_filter` aggregation (keyed on `root_forms`, amendments folded in) count documents. `search_filings` collapses hits to one row per accession (first-ranked hit's fields, plus `matched_documents` in rank order) and counts `total` / `form_distribution` from those filings; no EFTS parameter yields a search's filing count (`collapse`/`aggs` are ignored), so `total` is exact only when one window held every match, else a lower bound beside `total_documents`. **A browse is the exception:** a forms- or entity-only request (no `q`) matches each filing's primary document alone (S-1 January 2025: 200 hits over two pages, 200 distinct accessions, every `file_type` the form), so `hits.total.value` is the filing count and `total` is EDGAR's count — exact when the relation is `eq`, at any offset — trusted while the window shows one document per accession, else back to the window lower bound; `dataset.truncated` still flags a window short of it, and `form_distribution` covers the filings in hand. The straddling merge keeps the window count for its 2001-onward side, since its `total` counts assembled rows. Under `sort=relevance`, `from` counts documents and the 100-hit window runs past the page, so a page lists the filings among its own `limit` documents (the window's first rows, which can number fewer than `limit`) and only a filing straddling a page edge recurs on the next page (#124). A backend failure arrives as a 200 too, with `errorType`, `errorMessage`, `trace`, and `requestId` in place of `hits`; its handling is in the rate-limit note above (#206). Caller text is escaped before it reaches full-text search: `searchFilings`' `q` and `resolveEntityByName`'s `keysTyped` both go through `escapeEftsText`, which doubles each backslash and writes each control character (category Cc) as `\uXXXX`, so a term holding either is searched as typed. The escape lives in the service, not a tool, so `find_holders`' `search_key` re-sent through `search_filings` runs the same search. `find_holders` quotes the conformed name minus one trailing qualifier — a `\` or `/`, one to six letters, an optional closing `\` or `/` (`/[\\/][A-Za-z]{1,6}[\\/]?$/`, then a trim) — since 13F information tables print the issuer without it: `"US BANCORP"` matches 2,315 documents in the 2026-Q2 filing window, the phrase with its `\DE\` qualifier 2, and `PROGRESSIVE CORP/OH/` is searched as `"PROGRESSIVE CORP"`. A slash inside a name (`CULLEN/FROST BANKERS, INC.`) and an undelimited state token (`UNIVERSAL DISPLAY CORP PA`) stay, and `resolved_issuer_name` keeps the registry title (#205). A notice naming a `secedgar_search_filings` call as JSON — `find_holders`' first-page and continuation recipes, `company_search`'s withheld-filings recipe — puts it in a code span (`markdown().inlineCode`, fenced past any backtick run), since `content[]` renders as Markdown and outside code the quoted phrase's `\"` loses its backslash, as would a caller's form type typed into `company_search`'s `forms` (#220)
103
+ - **EFTS quirks:** `dateRange=custom` must be set when using date params; the singular `entity` param is ignored — `cik:`/`ticker:` targeting passes the resolved CIK via the plural `ciks` param (server-side scope, independent of the filing's name text, so former-name filings on the same CIK are matched); `size` is ignored entirely and every request answers with 100 hits, so `find_holders` pages with `from` alone and expresses its budget in pages (5 → 500 rows). The result window is 10,000 documents, so a `from` past 9,900 is refused as a `ResponseError` body, with or without `q` and whatever the match total; `search_filings` sends `offset` as `from` only under `sort=relevance` with no entity scope on a 2001-onward range, fails a deeper `offset` there as `offset_out_of_range` before any request (`MAX_RELEVANCE_OFFSET`, which `find_holders`' continuation recipe also names), and keeps the schema's 9,999 for its other paths, which page the rows they assembled (#214). A hit is one matching **document**, not a filing: `_id` is `<accession>:<filename>`, a filing whose body and exhibits both match arrives once per document, and `hits.total.value` and the `form_filter` aggregation (keyed on `root_forms`, amendments folded in) count documents. `search_filings` collapses hits to one row per accession (first-ranked hit's fields, plus `matched_documents` in rank order) and counts `total` / `form_distribution` from those filings; no EFTS parameter yields a search's filing count (`collapse`/`aggs` are ignored), so `total` is exact only when one window held every match, else a lower bound beside `total_documents`. **A browse is the exception:** a forms- or entity-only request (no `q`) matches each filing's primary document alone (S-1 January 2025: 200 hits over two pages, 200 distinct accessions, every `file_type` the form), so `hits.total.value` is the filing count and `total` is EDGAR's count — exact when the relation is `eq`, at any offset — trusted while the window shows one document per accession, else back to the window lower bound; `dataset.truncated` still flags a window short of it, and `form_distribution` covers the filings in hand. The straddling merge keeps the window count for its 2001-onward side, since its `total` counts assembled rows. Under `sort=relevance`, `from` counts documents and the 100-hit window runs past the page, so a page lists the filings among its own `limit` documents (the window's first rows, which can number fewer than `limit`) and only a filing straddling a page edge recurs on the next page (#124). A backend failure arrives as a 200 too, with `errorType`, `errorMessage`, `trace`, and `requestId` in place of `hits`; its handling is in the rate-limit note above (#206). Caller text is escaped before it reaches full-text search: `searchFilings`' `q` and `resolveEntityByName`'s `keysTyped` both go through `escapeEftsText`, which doubles each backslash and writes each control character (category Cc) as `\uXXXX`, so a term holding either is searched as typed. The escape lives in the service, not a tool, so `find_holders`' `search_key` re-sent through `search_filings` runs the same search. `find_holders` quotes the conformed name minus one trailing qualifier — a `\` or `/`, one to six letters, an optional closing `\` or `/` (`/[\\/][A-Za-z]{1,6}[\\/]?$/`, then a trim) — since 13F information tables print the issuer without it: `"US BANCORP"` matches 2,315 documents in the 2026-Q2 filing window, the phrase with its `\DE\` qualifier 2, and `PROGRESSIVE CORP/OH/` is searched as `"PROGRESSIVE CORP"`. A slash inside a name (`CULLEN/FROST BANKERS, INC.`) and an undelimited state token (`UNIVERSAL DISPLAY CORP PA`) stay, and `resolved_issuer_name` keeps the registry title (#205). Two registrants whose titles match once that qualifier is gone (`FIRST BANCORP /PR/` and `FIRST BANCORP /NC/`; `INDEPENDENT BANK CORP /MI/` and `INDEPENDENT BANK CORP`) search one phrase and get the same holders, and keeping the qualifier is no fix (`"FIRST BANCORP /PR/"` matches 9 documents in that window, `"FIRST BANCORP"` 458, FBP's CUSIP 353), so a name search with at least one match checks the in-memory registry (`getAllEntries`, no request) for every other current registrant (a ticker-file row, never a former name) whose title, minus its own qualifier, equals the phrase case-insensitively, and names each with CIK and ticker in a sentence pointing to `cusip`. The sentence joins the tool's `notices` list, since `ctx.enrich.notice` and `ctx.enrich.truncated`'s guidance are last-wins (#224). A notice naming a `secedgar_search_filings` call as JSON — `find_holders`' first-page and continuation recipes, `company_search`'s withheld-filings recipe — puts it in a code span (`markdown().inlineCode`, fenced past any backtick run), since `content[]` renders as Markdown and outside code the quoted phrase's `\"` loses its backslash, as would a caller's form type typed into `company_search`'s `forms` (#220)
104
104
  - **Submissions archive walk:** the submissions feed's `filings.recent` holds the last year or 1,000 filings, whichever is more — so 26,000+ rows for JPMorgan, and a filing day is never split (Microsoft's window runs to 1,002 rows to finish its oldest day); everything older lives on `filings.files[]` archive pages of 200–360 KB each. Every tool that reads past `recent` goes through `SubmissionsArchiveWalk` (`submissions-archive.ts`): one `ARCHIVE_PAGE_SCAN_CAP` (10) for all, pages read one at a time through the service's pacer and page cache, and no page selected when the lower bound falls on or after `recent`'s oldest date — so a call answered by `recent` sends no archive request. The caller picks the order — `newest-first` (`company_search`, `search_filings`' pre-2001 arm, `get_material_events`, `get_insider_transactions`' window), or `oldest-first` forward from a date (`get_institutional_holdings`' quarter lookup, since newest-first cannot reach JPMorgan's 2020-Q4 13F-HR on page 41 of 70 under the cap) — and can stop after any page; `scannedThrough` (the oldest page start read) and `truncated` (selected pages left unread, whether the cap, an early stop, or a caller that never started the walk left them) are reported the same way everywhere. Worst case per call is the submissions document plus 10 pages plus the tool's own document reads (`get_insider_transactions`: 111). `get_material_events` without a date window walks only to fill `limit`: it enters the walk when fewer than `limit` `recent` rows pass the `items` filter — the same count as the stop test, so unrelated recent 8-Ks never stand in for matches (#139) — and stops on the page that fills it with rows passing that filter, and its `dataset.truncated` is true whenever selected pages went unread — including when `recent` alone fills `limit` and no page is read, since the dataframe then holds only the recent window (#134); a result short of `limit` with selected pages unread (only the cap ends a walk that short) gets a notice naming the pages read, the oldest date reached, and the lever — `filed_before=<that date>` alone or in a window when undated, narrowing the window with `filed_before=<that date>` when dated, since a newest-first walk reaches older filings only through an earlier upper bound — appended to the zero-match or empty-window notice when one fires, since `ctx.enrich.notice` is last-wins; an empty-window notice the cap cut short claims no 8-K only "as far back as the scan reached" and drops its widen-the-range advice (#139); `get_institutional_holdings` stops on the first page holding a 13F-HR or 13F-NT for the quarter, and runs the #86 operating-company routing only when neither `recent` nor the pages read hold any 13F-HR or 13F-NT — a notice-only manager asked for a quarter it filed nothing for gets the plain quarter miss (#117, #133); without a `quarter`, a manager whose `recent` holds 13F-NT notices and no 13F-HR gets the notice message for its newest notice rather than the #86 classification (#133). **Page selection widens both date bounds by a day:** a manifest page's `filingFrom` / `filingTo` can sit a day off its own rows in either direction (JPMorgan's page 041 is listed to 2021-02-17 but holds 42 filings dated 2021-02-18; Apple's page 001 is listed a day past its newest row), so an exact overlap test skipped the page holding a window's edge day. The slack costs at most one extra page per bound, and every caller filters rows by their own filing dates (#137)
105
105
  - **13F amendment composition:** `get_institutional_holdings` composes a quarter from the original 13F-HR and its same-period 13F-HR/A amendments (`composeHoldings`), ordered by `acceptanceDateTime`, then filing date, then accession — never `amendmentNo`, since filers skip numbers and two amendments can land on one day. A `RESTATEMENT` replaces everything composed so far, earlier `NEW HOLDINGS` included, so the base is the last restatement whose table reads (the original when none does) and nothing before it is read (`superseded`). A `NEW HOLDINGS` after the base appends its rows, unless its table repeats every composed row (CUSIP, class, put/call, discretion, shares, share type; value is left out because its unit changed on 2023-01-03) — a mislabeled resubmission that would double the portfolio — in which case it applies as a restatement. Each accession's values normalize by its own filing date. An amendment whose type, index, or table cannot be read, or whose table has no rows, is `not_applied` instead of blanking the quarter. The original's table is always read (it backs `total_holdings_in_filing`); each amendment table is two more requests on the call's `CallScope`, and a 429 or a spent budget stops further optional reads (#198).
106
106
  - **Filing metadata outside `recent`:** `get_filing` takes `form`, `filing_date`, and `period_ending` from `recent` when the accession is there, else from the filing's own SEC header — the raw `<TYPE>` / `<FILING-DATE>` / `<PERIOD>` in `index-headers.html`, which the tool already fetches to type the documents, and only when that page 404s (common before 2014) the sub-1 KB `<accession>.hdr.sgml`. `FILING-DATE` is the filing date, not the acceptance timestamp, and matches the submissions feed; an S-8 or Form 4 header has no `PERIOD`. `company_name` stays the current registrant name (#126), read from the feed of the CIK whose directory served the filing
@@ -111,7 +111,7 @@ Tailor suggestions to what's actually missing or stale — don't recite the full
111
111
  - **Section matching:** `get_filing`'s `section` compares through `foldForHeadingMatch` (`filing-to-text.ts`) on **both** operands — Unicode whitespace runs collapse to one space, U+2018/U+2019 → `'`, U+201C/U+201D → `"`, then lowercase. Comparison-time only: `FilingHeading.heading`, the `outline` output, `content[]`, and every character offset keep the document's own bytes. EDGAR headings carry NBSP runs and typographic quotes, so a caller re-sending an outline heading through a UI that normalizes either one never byte-matched the heading it came from — which broke the `section_not_found` recovery loop the error's own hint points at (#106). No fuzzy matching — `"item 8"` resolves only to Item 8 — but every tier runs on folded operands, so a single-spaced needle also reaches a heading whose marker carries an NBSP run or a double space (`Item 9.` in a 2004 10-K). Folding only one operand does not fix the round trip. One boundary (`sectionMatches`): a needle ending in a number never continues into a longer one. A trailing digit never runs on into another digit, so `item 1` matches `Item 1.` and `Item 1A` but never `Item 12`, and `item 5` reaches an 8-K's `Item 5.02` while `item 5.0` does not. A trailing roman numeral (a final word of `i`, `v`, `x`) must end at a space, punctuation, or the heading's end, so `part i` never matches `PART II`, `PART III`, `PART IV`, or `PART II, III`: Sono-Tek's 10-Q (0001171520-26-000305), which prints Part I only inside a one-line TOC, landed `part i` on `PART II - OTHER INFORMATION`, and Microsoft's FY2026 10-K on `PART II, III` (348204). `part i` now falls through to the line tier (Microsoft: the body `PART I` at 6900) or misses with the outline (Sono-Tek; an S-1, whose Part I is the unlabeled prospectus). Plain-text outlines keep TOC rows worded differently from their body heading, and a TOC row for Item 10–16 precedes the body Item 1 — a bare substring test landed `item 1` on another Item in 6 of 37 plain 10-K/10-Q outlines and 1 of 270 HTML landings (#136). **Resolution order (#169, #166, #177)**, first hit wins, over every detected heading (`detectHeadings(text)`, which takes no cap, run once per call — the 50-entry cap belongs to the rendered outline alone; with the first 50 only, a heavy 10-K's financial-statement captions put Items 9B–16 out of reach) and the document's own lines: (1) **exact** (`resolveSection`) — a heading whose `headingKey` (the dedup key: the fold, a terminal-punctuation strip, and the marker separator folded to one space) equals the needle's, or whose title after its Item/Part marker does — failing that, the same with a leading sub-item label removed (below); a bare marker (`ITEM 1.`, `Part II`) has no title and is never a candidate, or GSBD's `item 1` jumps to a bare TOC `ITEM 1.`. The tier exists for #170's widened all-caps class: CCC's `SPECIAL NOTE REGARDING FORWARD-LOOKING STATEMENTS AND RISK FACTORS` (7562) otherwise takes `risk factors` from `Item 1A. Risk Factors.` (67351). (2) **Item/Part substring** — the first Item or Part heading (`isStructuralHeading`, bare and run-in markers included) that `sectionMatches`: a value inside an Item title names that Item, while a line equal to it is often a table-row label (CCC's `compensation` → `Item 11. Executive Compensation` at 493087, not the `Compensation` cell at 418658). (3) **an equal line** and (5) **a table-row label, else a prefix line** — a document line (`matchSectionLine`, `filing-to-text.ts`, which reports whether its line ranks in tier 3; `findSectionLine` is its offset alone), for a mixed-case subheading the outline never lists (`Liquidity and Capital Resources`): a line whose `headingKey` equals the needle's and that labels no table row (3), else — only when no such line exists — the first equal line that labels one (5, below), else one that starts with it (5) at a word boundary within `MAX_TITLE_CHARS` (a date-suffixed title: `Consolidated Schedule of Investments as of June 30, 2026`), unless a one-word needle runs on into a longer Title Case title (`continuesIntoLongerTitle`: the next word opens on a capital in a line that is not all caps). One word heads many unrelated titles — `business` landed on `Business Combinations.` (C3is), `Business Seasonality and Product Introductions` (Apple 10-Q), and a cross-reference line `Business Overview—Governmental regulations…` (DRDGOLD); a needle of two or more words keeps its continuation (`Human Capital` → `Human Capital Management`), and a suffix opening lowercase or on punctuation (`(continued)`, `—Parent Company Only`) always does. The cost: `forward-looking` no longer reaches `Forward-Looking Statements`, nor `revenue` `Revenue Recognition`; both miss with the outline. Equality goes first because a prefix match alone lands `Competition` on an earlier line that merely begins with the word. **A table-row label ranks in tier 5, ahead of a prefix line (#184):** an equal line labels a row when its next line with content (spacer lines passed over) is a figure row, or is a label — at most 60 characters, opening uppercase, ending on no `.`, `:`, `;`, or `,`, closing quotes and brackets passed over (a cross-reference `See “Item 18. Financial Statements.”` over its page number is no label) — whose next line with content is one (`labelsTableRow`; Microsoft's segment table `Revenue` / `Client` / `$ 9,350 …`). A figure row is a lone currency or nil cell (`$`, `-`, `–`, `—`), or a line whose text after its last letter holds a digit and, when the line has a letter, opens on a dotted leader, a tab, or two or more spaces behind a label of at most 60 characters (`isFigureRow`: `Product sales....... $4,759`; ``$ 7,746 $ `7,835``, a stray backtick in a 2004 cell); one space never qualifies (`The effective rate was 21%.`), and past the label bound the line is a table set on one line, which a heading may sit over (AMC Robotics' S-1 0001493152-26-047958: MD&A `Revenue` at 177926 over `Three months ended June 30, 2026 2025 $ Change …`). All 13 `Revenue` lines in Microsoft's 2004 10-K (0001193125-04-150689) label rows, and as tier-3 lines took `revenue` from `SEGMENT PRODUCT REVENUE/OPERATING INCOME (LOSS)` (81018) to the selected-data row at 66987; Aware's `Revenue:` over `Product sales....... $4,759` (112947) took it from `CONTRACT REVENUE` (49489). Demoted rather than skipped, a row label still lands when no heading contains the value (`total revenue` keeps its income-statement row), under the plain line notice. The test reads at most two content lines past an equal line. Over 26 corpus filings × 104 section values it labels 124 lines on the resolution path, none a detected heading, and moves 22 landings and no outline entry: 15 from a row label onto a heading or prose subheading for the value (Microsoft FY2026 `revenue` → its MD&A `Revenue` subheading at 217873; `earnings per share` → the EPS note in both Microsoft 10-Ks), 2 onto a table's caption line, 1 onto another row label (BAB's `goodwill`, from its balance-sheet row to a note table's), and 4 onto a heading that only contains the words (Arxis `net income` → `NOTE 16. NET INCOME (LOSS) PER SHARE`, and Nutanix's → `NOTE 11. NET INCOME (LOSS) PER SHARE` past a `Net income` row of `—` cells; CCC `net income` → the all-caps row label `NET INCOME (LOSS) INCLUDING NON-CONTROLLING INTEREST`, a detected heading; CCC `revenues` → `COST OF REVENUES` at 332106, since all four of its `Revenues` lines label rows). In both line tiers a line is skipped when it opens lowercase (a wrapped sentence or bullet); when it sits under a line ending on a comma or semicolon, or opens on an unpunctuated Item marker followed by a lowercase word (a wrapped cross-reference, the `followsMidSentence` / `isWrappedProse` guards heading detection applies: `…in Part II,\nItem 8 on this Form 10-K…`); or when it is a TOC row (`isTocRow`). A TOC row ends in a page cell set off by **two or more** spaces or a tab (`TOC_PAGE_TAIL_RE`; one space would read the year in `as of June 30, 2026` as a page number), or its next line with content is a page cell (`PAGE_CELL_LINE_RE`: a number, `F-3`, or a lowercase roman `ii`, which counts only on its own line — `Part iv` is not a page cell); either form may put a `Page` word before the number (`Page 3`), spacer lines passed over (an HTML TOC table puts NBSP rows between its cells). A line that is not a marker, followed directly by an Item/Part marker, is a TOC title cell with no page column; a marker run straight into its title counts (`MARKER_LINE_RE` takes `TITLE_RUN_IN`, #180: `Item 2Properties`). A marker line — a Part over its first Item — is a TOC row when that Item row is: the Item line ends in a page cell, the line below it holds or ends in one (a title cell, or Aware's wrapped `of Equity Securities....... 12`), or, for a bare marker, the line below its title holds one. Microsoft's FY2026 10-K prints body `PART IV` only as page furniture, so `part iv` reaches the line tier, where `PART IV / Item 15. / Exhibit and Financial Statement Schedules / 93` was taken; it now lands on the body's first `PART IV` (352884). A body Part sits over its Item too, but prose follows, not a page cell. The first remaining line wins, at its first non-blank character; one linear pass serves tiers 3 and 5, run only after tiers 1 and 2 miss, so a value landing on a tier-4 heading now pays that pass (7–11 ms on a 1 MB S-1). A cut page's guidance after a `section` landing says to pass `next_offset` as `offset` without `section`, which outranks `offset` — kept, it returns the same page. A line landing says so in the notice, composed into the truncation guidance when the page is cut (`notice` is last-wins): `No detected heading matches section '<value>', so this page starts at the first document line that does.` — no new output field. An equal line that outranked a heading merely containing the value says `No detected heading equals section '<value>', so this page starts at the first document line that does, ahead of headings that only contain it.` instead, since that heading does match by substring. Every #166 acceptance offset holds. (4) **other substring** — the first other heading that `sectionMatches`, after the equal line: a heading that merely holds the word took Arxis' S-1 `business` to `NOTE 3. BUSINESS COMBINATIONS` (544705) past its `Business` heading line (323578), and CCC's `revenue` to `COST OF REVENUES` (332106) past the MD&A `Revenue` subheading (256790). An exact or Item/Part heading still beats an equal line (Reddit's `use of proceeds` → the `USE OF PROCEEDS` heading); every other heading ranks after one. Over 67 corpus filings × 103 section values the order moved 24 landings, each one the validation predicted: 17 onto the section named (Microsoft FY2026 `general` → `GENERAL` at 8720, not `GENERAL RISKS`; DRDGOLD's `risk`, `directors`, `management`, and `employees` → body Items instead of TOC rows), and 7 onto a different place that is defensible but that a reader may like less, since an Item heading or a line equal to the value now outranks a heading that only holds it — JPM's 10-Q `risk` lands on Item 3, a one-sentence cross-reference, not `FIRMWIDE RISK MANAGEMENT`; `revenue` in Microsoft's 2004 and FY2026 10-Ks and Aware's on a selected-data, MD&A-table, or income-statement row label rather than a heading containing the word — the three landings tier 5's row labels move (#184, above); `summary` on Item 16 `Form 10-K Summary`; Intel's 2000 `consolidated balance sheets` on an Item 14 index row. (6) `section_not_found`. **A proxy statement keeps its headings ahead of the lines:** for a proxy or information statement form (`PROXY_FORM_RE`: DEF 14A, DEFA14A, DEFM14A, PRE 14A, DEF 14C, …), tier 1 is followed by the first heading of any kind that `sectionMatches`, then the line tiers — its ITEM headings are ballot proposals, not the Regulation S-K item taxonomy, and its lines equal to a value are mostly table cells. Under tiers 2–4 Goldman Sachs' DEF 14A (0001193125-26-117433) took `compensation` from the CD&A (123680) to `ITEM 2. … (SAY ON PAY)` (274744) and `summary` from `EXECUTIVE SUMMARY` (16953) to a Pay versus Performance column header (282286). The form is read before `section` resolves, so the `.hdr.sgml` fallback request (#126) now precedes a `section_not_found`. **Inside each heading tier a body heading ranks ahead of a table-of-contents row (#174):** a heading is a TOC row when its title line — its own line, or the next line with content after a bare or joined marker — is one by `isTocRow` (the line tiers' test), or the next line with content below it ends in a page cell (a TOC title wrapped onto a second line, Aware's `of Equity Securities....... 12`), or the title wraps once with its page cell on its own line under the wrap — the title line, one continuation line, and a `PAGE_CELL_LINE_RE` line on three consecutive lines, the continuation in the title line's case: no lowercase letter under an all-caps title line, an opening lowercase one under a mixed-case one (`of Equity Securities`) (#183). DRDGOLD's TOC row `ITEM 14.` / `MATERIAL MODIFICATIONS TO THE RIGHTS OF SECURITY HOLDERS AND USE OF` / `PROCEEDS` / `79` took `item 14` and `material modifications to the rights of security holders` at 8146 from the body heading at 433144. A body heading over one line of body text and a page number has the same three lines: across 26 filings the step without the consecutive-line and case conditions flags 47 body headings (`Item 4. Mine Safety Disclosures` / `Not applicable.` / `31`, spacer lines between or not, and DRDGOLD's `NOTE 22 ASSET HELD FOR SALE` over its page footer and `F-50`); with them it flags only that TOC row (8146) and its title cell (8155), moves those two landings, and changes no outline. An all-caps body heading over a one-word all-caps line and a page number on consecutive lines (`ITEM 4. MINE SAFETY DISCLOSURES` / `NONE` / `31`) still reads as a TOC row and lands as its tier's only match; `isTocHeading` in `filing-to-text.ts` owns the test, finding the line start from the newline before the offset since an NBSP-led Item's offset sits one past it. A TOC row still lands when it is its tier's only match. Three TOC shapes survive dedup: a row worded apart from its body heading (First Bancorp's 8-K `Item 9.01 Financial Statements and Exhibits. Page 1` took `item 9` at 2041 from the body Item at 2402), a bare all-caps marker over its title and page cells (DRDGOLD's FY2026 20-F `ITEM 3.` / `KEY INFORMATION` / `6` took `item 3` at 6174 from `ITEM 3. KEY INFORMATION` at 34346, and nearly every other `item N` the same way), and the title cell itself (`key information`). TOC rows are ranked, never dropped or pushed behind the line tiers: the test also reads a body heading over a page number (CCC's `Item 6. Reserved.` at 234199, Reddit's S-1 `PART II` at 1021631), and behind the line tiers CCC's and Microsoft's `item 6` left the body heading for a bare TOC marker line. With the dedup-key fold, the ranking moved 83 landings over the corpus, each from a TOC row onto a body heading (DRDGOLD 35, Worthington Steel 20, GSBD 9, Amazon's 2003 10-K 8, Aware 6, First Bancorp 4, CCC 1), and no other: 78 onto the body heading the row copies, 5 onto another the value names (Amazon 2003's `part ii`–`part iv` onto its body Parts, Aware's `management` from its TOC Item 12 to body Item 7, Worthington Steel's `other information` from its TOC Item 5 to body `PART II. OTHER INFORMATION`). **A leading 20-F sub-item label is ignored (#175):** 20-F filers label sub-items (`3D. RISK FACTORS`, `B. Business Overview`), so a plain-phrase value never equalled the line. Tier 1 and both line tiers also compare the heading or line key with a leading label removed (`withoutSubItemLabel`: `/^(?:\d{1,2}[a-z]|[a-z])\. /` on the folded key, anchored, so constant-time), and the one-word longer-title rule judges the line after its label — Regencell's `B. Business Overview` keeps `business` a miss while `business overview` lands (151573). The value itself is never stripped, so `3D. RISK FACTORS` still matches its own line; a line opening on an initial (`L. John Doerr`) strips the same way and so matches only a value equal to the rest of the line. The landing is the line's first character, label included (DRDGOLD `risk factors` → 34503). Tier 1 strips only once no heading equals the value as printed, so an earlier `A. RISK FACTORS` never takes `risk factors` from a later `Item 1A. Risk Factors`; a labelled body heading still ranks ahead of a TOC row. The line tiers keep the first line equal either way: across the corpus the labelled line they land on is the 20-F sub-item itself and a later unlabelled one is narrower (DRDGOLD `business overview` → `4B. BUSINESS OVERVIEW` at 176975, not `Business overview` at 269017). Over the corpus the strip moved 23 landings, all in the three 20-Fs: 19 misses now land on the labelled sub-item, and 4 earlier landings move onto one (DRDGOLD `compensation` from the `Compensation of key management` subheading inside Item 6B, 328266, to `6B. COMPENSATION` at 324690); no filing without labelled sub-item lines changed. **The outline cut (#169):** past 50 detected headings the outline is every Item/Part heading (`isStructuralHeading`, bare and run-in markers included) plus the earliest other headings up to 50, in offset order (`selectOutline`) — shared by the first-page `outline` and the `section_not_found` message and data. When the Item/Part headings alone pass 50, each bare marker that a later titled heading for the same Item or Part repeats is left out first (`outlineStructuralHeadings`): DRDGOLD's FY2026 20-F renders all 31 TOC Items as bare markers (`ITEM 3.`), which filled the cut and pushed body Items 16A–19 out; its outline now runs `ITEM 1.` through `ITEM 19. EXHIBITS` from the body. A bare marker no titled heading repeats stays, and `section` still matches every heading. The miss message heads a cut outline `Outline (50 of N detected headings):` (else `Outline:`), and a cut first page appends `The outline lists 50 of N detected headings, every Item and Part heading among them; section matches all of them.` to the truncation guidance — `…among them, bare table-of-contents copies of titled ones aside; …` when bare markers were left out (DRDGOLD: `The outline lists 50 of 142 detected headings, every Item and Part heading among them, bare table-of-contents copies of titled ones aside; section matches all of them.`), and no Item/Part clause when the kept Item/Part headings alone pass 50, which reaches `structuredContent.notice` and `content[]` — no new output field, since the outline is emitted only on a truncated first page. A document of 50 or fewer headings renders as before.
112
112
  - **Binary filing documents:** a filing index routinely carries scanned pages, PDF exhibits, `Financial_Report.xlsx`, and `-xbrl.zip` — `filingToExtract` runs `html-to-text` over whatever bytes arrive and never inspects a content type, so requesting one used to return decoded binary as `content` with no error (#96). `get-filing.tool.ts` detects them with one rule, `binaryType`: the filename extension (`binaryTypeFromName`), the one signal every filing carries, plus a header-page `GRAPHIC` type for a scan named oddly — the header page is read before the body (#161). Two halves, both needed — `documents[]` entries carry `binary: true`, and `resolveFilingArchive` throws `binary_document` before `tryGetFilingDocument` runs, since the `document` input is an unconstrained string and a catalog marker alone cannot stop a caller. Extension-driven and bucket-independent on purpose: a PDF exhibit is typed `EX-99.*` and files under `exhibits`, not among the graphics.
113
113
  - **Dataframes:** `secedgar_search_filings`, `secedgar_get_financials`, `secedgar_fetch_frames`, `secedgar_compare_companies`, `secedgar_get_insider_transactions`, `secedgar_get_institutional_holdings`, `secedgar_get_material_events`, `secedgar_find_holders`, `secedgar_get_beneficial_owners`, and `secedgar_get_fund_holdings` materialize their full result set as `df_<id>` on a shared DuckDB-backed canvas (one per tenant). The two ownership tools register the full parsed set (inline response is a preview capped at `limit`); `get_insider_transactions` scans at least `INSIDER_CANVAS_FILING_SCAN` recent filings when canvas is available (so small inline limits don't under-scan the window), capped at 100, and flags `dataset.truncated` when more Form 4 filings exist beyond the scanned window (#63); with a `filed_after` / `filed_before` window it reads the in-window Form 4 / 4-A rows with an XML primary document — `recent`, then the archive pages overlapping the window, newest first, stopping once the scan cap plus a sentinel row are in hand — and with a canvas parses every one up to 100 instead of the 40-filing floor, since the window already bounds the set; `dataset.truncated` is then the sentinel or unread overlapping pages, and `history_scanned_through` the oldest filing parsed (#127); a company's submissions feed also lists the Form 4s it filed as a reporting owner of another issuer (JPMorgan's 10% stake in a BlackRock fund), so a parsed document whose `issuerCik` differs from the resolved CIK, compared with zero-padding stripped, adds no row inline or to the dataframe and is counted in `filings_other_issuer` — it still counts toward `filings_scanned`, the scan floor, and `history_scanned_through`, and the no-canvas stop rule is unchanged — though a skipped filing adds no transactions, so a no-canvas call reads on through such filings until `limit` transactions are in hand, within the same scan cap (#157); its `shares_traded` is an unsigned magnitude paired with a `direction` (acquire/dispose) column, so net activity is `SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END)` (#46); `get_financials`' dataframe materializes the source-filing fiscal keys as `source_filing_fy`/`source_filing_fp` (renamed from bare `fiscal_year`/`fiscal_period` — every comparative period restated in one filing carries that filing's fy/fp, so `period_end` is the time key for ORDER BY/GROUP BY/windowing) (#72); `compare_companies`' dataframe holds the FULL aligned series across every period while the inline matrix is capped at `periods`, and each row carries both the aligned `period` key and the underlying XBRL `frame` (they differ for point-in-time concepts) (#85). In an annual matrix an instant enters only on one of the filer's fiscal-year ends and takes the key of the annual duration ending that day. The ends come from the companyfacts payload already in hand (`filerFiscalYearEndsWithComparatives` in `concept-series.ts`, shared with `get_financials`' annual view of an instant): each annual report's own year (the #148 rule) plus the comparative years it restates — its year-long facts ending a whole number of years earlier, within a week — so the first XBRL 10-K's prior-year balance keys too, while a year-long figure ending off the report's calendar (a December filer's trailing year to 09-30) stays out. The #148 test of a 10-Q-held annual frame keeps `filerFiscalYearEnds` (each report's own year only): it matches day of year, where a comparative year adds nothing but a wider tolerance. The key is the first `CY####` frame on any concept in the payload ending then, so a balance lands beside its fiscal year's income lines even when none is requested; with no framed duration ending on it, the calendar year in which that fiscal year's second half starts (SEC's own framing: a year ending 06-30 is that year, one ending 06-27 or 05-31 the year before — Seagate's and Western Digital's years ending 2025-06-27 are `CY2024`; SEC departs from it for the year both ended 2012-06-29, framed `CY2012`, which is why a framed key wins). Interim and cover-date instants stay out of the annual matrix, and a company-concept left with none gets a gap plus a caveat pointing at quarterly; when that empties the whole matrix, `no_comparable_data` says the values were all off fiscal-year ends and its hint names `period_type: "quarterly"` (omitting `period_type` keeps annual). Quarterly keys are unchanged. The year ends are read lazily, only when an annual matrix meets an instant (#171). The period-ends caveat checks every inline column — the newest can hold one company alone — spelling out the newest column whose ends differ and naming the others; the inline window is the newest periods of the union across companies, so a company-concept pair whose values all predate it is named in `caveats` — one line per concept, each company with its newest period and the dataframe pointer — and never in `gaps`, which keeps meaning no value in any period (#144). Each row set carries an all-nullable schema (framework's `inferSchemaFromRows` always emits `nullable: true` since mcp-ts-core 0.10.4). Per-table TTL is delegated to the framework via `RegisterTableOptions.ttlMs` (resolved in mcp-ts-core#140); bridge still tracks metadata expiry in `ctx.state` for provenance. Every producer emits the describe-then-query pointer on the branch that registers the dataframe, composed once by `dataframeGuidance(dataset)` in the bridge so the wording cannot drift; where a truncation call already fires there it rides as that call's `guidance`, since `ctx.enrich.notice` is last-wins across `notice`/`truncated` and a second call would clobber the first (#104). `secedgar_dataframe_query` detects a `row_limit`-bound result from `QueryResult.truncated` rather than `rowCount > rows.length` — `row_limit` is pushed into the query as the provider's cap, so a capped result comes back with `rowCount === rows.length` and the arithmetic cannot see it; `rowCount` is then the cap and not a total, so that branch names the cap instead of printing "of N rows", `row_count_capped` carries the same disclosure into `format()`, and the fallback comparison stays for the `registerAs` path, where `truncated` is never set. A SQL `LIMIT` exactly equal to the cap is indistinguishable from a result that holds that many rows and is reported as exact (#109). `secedgar_dataframe_query` runs framework's SQL gate with `denySystemCatalogs: true` to block `information_schema`, `pg_catalog`, `sqlite_master`, and `duckdb_*` catalog access. Raw DuckDB execution errors (missing table, syntax) are caught in `bridge.query` and re-thrown as structured `missing_table`/`invalid_sql` reasons, with DuckDB's "Did you mean …?" hint stripped so internal catalog names don't leak (#47). The framework's own classifications pass through untouched and are declared on the tool's contract (`thrownBy: 'service'`, since the handler never names them): a SELECT that prepares and then fails on the data — a `Conversion` / `Invalid Input` / `Out of Range` error, e.g. `CAST('abc' AS INTEGER)` — is `ValidationError` with `sql_execution_error` (mcp-ts-core 0.13.4; `DatabaseError` with no reason before), and the gate's `multi_statement`, `denied_function`, `sql_read_only`, and `plan_operator_not_allowed` rejections arrive with their own recovery hints — since mcp-ts-core 0.13.15 the gate also denies engine-setting and SQL-from-string functions (`current_setting`, `query_table`) as `denied_function` and a file named as a table (`FROM 'data.csv'`) as `sql_read_only`, and since 0.13.16 it refuses any unqualified `current_schema`, since the parse tree cannot tell the bare function from a column of that name — a staged or aliased column so named is read qualified (`c.current_schema`). `get_beneficial_owners` registers one row per reporting person rather than one per filing, since powers and percent of class are per person, and each row carries the filing's `purpose_of_transaction` and the person's `notes` uncut, the text the inline result bounds (#200); `get_fund_holdings` registers every position in the report while the inline list is one `limit`-sized page from `offset`, and its rows carry the fund keys (`series_id`, `registrant_cik`, `report_period_date`, `accession_number`) so a portfolio joins the 13F and 13D/G rows on `cusip`. Insider rows carry `issuer_cik` and no `cusip`, 13F rows the reverse; 13D/G rows carry both.
114
- - **Beneficial ownership (13D/13G):** SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML under the `SCHEDULE 13D` / `SCHEDULE 13G` names on **2024-12-18**; the changeover is total, so a legacy-name filter matches nothing recent and a current-name filter matches nothing older. The two schedules are **separate schemas, not one shape with optional fields** — 13D repeats `reportingPersons/reportingPersonInfo` with the power fields flat on each person and the percentage in `percentOfClass`; 13G repeats `coverPageHeaderReportingPersonDetails` with the powers nested inside `reportingPersonBeneficiallyOwnedNumberOfShares`, the percentage in `classPercent`, no reporting-person CIK anywhere, and no purpose-of-transaction field at all (its item 4 is structured ownership data, which is what makes it the passive form). `beneficial-ownership-parser.ts` therefore branches per schema and dispatches on the submission type, falling back to whichever repeated reporting-person element the document carries. **Ownership powers and percent of class are per reporting person, including on joint filings** — a fund, its adviser, and its controlling principal each report the same underlying shares, so the parsed owner list is never collapsed to a group total and the percentages must not be summed. Discovery runs off the issuer's own `getSubmissions()`: SEC cross-lists a schedule under every CIK party to it, so no entity-scoped EFTS step is needed. **Filer text is data, kept as filed and bounded per field:** Item 4 `purpose_of_transaction` and each person's cover-page `notes` keep their line breaks (CR and CRLF as filed) and come back whole up to 5,000 and 2,000 characters; past that, the value is its first N characters with nothing appended and `purpose_truncated` / `notes_truncated` say so, on both surfaces. Item 4 is the substantive 13D field: 5,000 sits just above the 90th percentile of 48 sampled Item 4s (4,916), where 1,200 cut 34 of them, and uncut the 20 longest sampled make a 136.5 KB response; 2,000 clears the longest of 77 sampled notes (1,852), and a bound stays because reporting persons per filing are unbounded. When anything was cut, the cut count and the pointer to the whole text — the dataframe's uncut columns, or `secedgar_get_filing` on the accession — ride the tool's one composed notice. `format()` renders each value as a blockquote through `escapeMarkdownInline`, every line prefixed `> ` (indented under a note's list item) and the cut marker after it, behind a blank line so the marker and the next block cannot lazily continue the quote; reporting-person names, `security_class`, `issuer_name`, and the cover-page codes render escaped too (#200).
114
+ - **Beneficial ownership (13D/13G):** SEC replaced the legacy `SC 13D` / `SC 13G` text filings with structured XML under the `SCHEDULE 13D` / `SCHEDULE 13G` names on **2024-12-18**; the changeover is total, so a legacy-name filter matches nothing recent and a current-name filter matches nothing older. The two schedules are **separate schemas, not one shape with optional fields** — 13D repeats `reportingPersons/reportingPersonInfo` with the power fields flat on each person and the percentage in `percentOfClass`; 13G repeats `coverPageHeaderReportingPersonDetails` with the powers nested inside `reportingPersonBeneficiallyOwnedNumberOfShares`, the percentage in `classPercent`, no reporting-person CIK anywhere, and no purpose-of-transaction field at all (its item 4 is structured ownership data, which is what makes it the passive form). `beneficial-ownership-parser.ts` therefore branches per schema and dispatches on the submission type, falling back to whichever repeated reporting-person element the document carries. **Ownership powers and percent of class are per reporting person, including on joint filings** — a fund, its adviser, and its controlling principal each report the same underlying shares, so the parsed owner list is never collapsed to a group total and the percentages must not be summed. Discovery runs off the issuer's own `getSubmissions()`: SEC cross-lists a schedule under every CIK party to it, so no entity-scoped EFTS step is needed. **Filer text is data, kept as filed and bounded per field:** Item 4 `purpose_of_transaction` and each person's cover-page `notes` keep their line breaks (CR and CRLF as filed) and come back whole up to 5,000 and 2,000 characters; past that, the value is its first N characters with nothing appended and `purpose_truncated` / `notes_truncated` say so, on both surfaces. Item 4 is the substantive 13D field: 5,000 sits just above the 90th percentile of 48 sampled Item 4s (4,916), where 1,200 cut 34 of them, and uncut the 20 longest sampled make a 136.5 KB response; 2,000 clears the longest of 77 sampled notes (1,852), and a bound stays because reporting persons per filing are unbounded. When anything was cut, the cut count and the pointer to the whole text — the dataframe's uncut columns, or `secedgar_get_filing` on the accession — ride the tool's one composed notice. `format()` renders each value as a blockquote through `escapeInline`, every line prefixed `> ` (indented under a note's list item) and the cut marker after it, behind a blank line so the marker and the next block cannot lazily continue the quote; reporting-person names, `security_class`, `issuer_name`, and the cover-page codes render escaped too (#200).
115
115
  - **NPORT-P series routing:** a fund's public portfolio report covers **exactly one series**, a registrant trust holds many (iShares Trust: 390 listed series, 200+ reports for a single period), and the series identity appears **only inside the document** — neither the submissions feed nor EFTS carries `seriesId` on an NPORT-P row. Routing is therefore series-first: EDGAR's company browse accepts a series ID in place of a CIK (`getFundSeriesFilings`), which is the one SEC surface mapping a series to its accessions and which also names the registrant, so a bare series ID resolves in one request. The browse feed's registrant outranks any registrant the `fund` input implied, since `series_id` can name a series of an entirely different trust and the archive path is keyed on the registrant. The bounded header scan (`tryGetFilingDocumentHead` + `parseNportHeader`, cap `SERIES_SCAN_LIMIT`) is the fallback and the disambiguator for a trust whose series carry no listed ticker; SEC's archive host **ignores `Range`** (a ranged request answers 200 with the whole body), so the saving is client-side stream cancellation only — and the cutoff cannot cut below one read chunk, which Bun sets at 262,144 bytes, so `HEADER_MAX_BYTES` binds only on a document arriving in several chunks. **A registrant's own NPORT-P list is never the candidate set for a series-structured trust**: series fiscal quarters are staggered, so the list interleaves funds and one report at the newest period does not mean one fund — it means the fund whose quarter ends latest. The scan therefore runs on the newest batch even when that batch holds one report, and a series found there re-routes through the browse feed; only a report naming no series at all (a closed-end fund, which also carries no `classId`) is answered from the registrant's list. Candidates are ordered by **reported period, not filing date**: an `NPORT-P/A` restating an old period is filed after every report of the periods that followed it. Reports publish on a ~60-day lag, so `report_period_date` and `publication_lag_days` are first-class output and the `as_of` enrichment states both.
116
116
  - **Local mirror (opt-in, `EDGAR_MIRROR_ENABLED`):** routes `resolveCik`, `tryGetCompanyConcept`, `tryGetCompanyFacts`, and `tryGetFrames` to a local SQLite mirror (framework `MirrorService`) of `company_tickers.json` + the `companyfacts.zip` bulk archive; the live API is the fallback on a miss (`EDGAR_MIRROR_FALLBACK_LIVE`). Bootstrap out-of-band with `bun run mirror:init`; refresh nightly via cron (HTTP) or `bun run mirror:refresh`. The three `mirror:*` commands also ship in the production Docker image — run them against a deployed container with `docker exec <container> bun run mirror:<init|refresh|verify>`. Node/Bun only — skipped on Workers. Frames are assembled from the company-facts store, so `loc` (business location) is absent. The ingester stores a tag's own name when SEC serves it with no label (`InterestExpenseNonoperating`), so every read path treats a stored label equal to a camel-case compound tag as no label (`storedLabel`) — callers fall back to the concept's label, and `getFrames` answers an empty `label` as the live frames API does; a one-word element's label is the word itself (`Revenues`) and is kept. Read-side, so stored rows need no migration. No FTS5 — every routed lookup is exact/indexed (cik+taxonomy+tag point, taxonomy+tag scan, cik scan for the whole-company read, ticker/CIK). Mirror ingests MF fund symbols from `company_tickers_mf.json`; on the mirror path a live MF merge supplements them when `FALLBACK_LIVE` is on (superseding the mirror's bare fund rows with series/class, and covering a mirror synced before MF ingestion), so funds resolve there too (#43, #135).
117
117
 
@@ -246,7 +246,10 @@ src/
246
246
  canvas-bridge.ts # Framework DataCanvas adapter, df_<id> minting, per-table TTL
247
247
  sql-gate-extras.ts # Bridge-layer system-catalog deny on top of framework SQL gate
248
248
  mcp-server/
249
+ tools/ambiguous-matches.ts # Candidate list (message text + `matches` data) for an ambiguous company resolution
250
+ tools/escape-inline.ts # escapeInline — escapeMarkdownInline in time linear in its input length (mcp-ts-core#809), for every unauthored string a format() renders
249
251
  tools/fixed-point.ts # Fixed-point rendering of parsed numbers without rounding their digits
252
+ tools/format-usd.ts # USD amounts scaled by magnitude (T/B/M/K, sign before the $) and every-digit grouping for content[] (#222)
250
253
  tools/form-filter.ts # `forms` normalization (trim, uppercase, drop blanks) shared by search_filings and company_search (#194)
251
254
  tools/limit-clamp.ts # Over-cap numeric inputs served at the cap (#197) and ID lists answered to the cap (#201), behind EDGAR_CLAMP_OVERSIZED_LIMITS
252
255
  tools/definitions/
@@ -449,7 +452,7 @@ import { getEdgarApiService } from '@/services/edgar/edgar-api-service.js';
449
452
  - [ ] `ctx.log` for logging, `ctx.state` for storage
450
453
  - [ ] Handlers throw on failure — typed `errors[]` contract + `ctx.fail(reason, …)` when failure modes are known; factories or plain `Error` for ad-hoc throws. No try/catch.
451
454
  - [ ] Tool error contracts include `recovery` strings (≥5 words)
452
- - [ ] `format()` renders all data the LLM needs — Claude Code reads `structuredContent`, Claude Desktop reads `content[]`; both must carry the same data
455
+ - [ ] `format()` renders all data the LLM needs — Claude Code reads `structuredContent`, Claude Desktop reads `content[]`; both must carry the same data. Every string the server did not author (SEC text, caller input, SQL results) renders through `escapeInline` (`src/mcp-server/tools/escape-inline.ts`) — the framework's `escapeMarkdownInline`, kept linear in its input length until mcp-ts-core#809 lands — and JSON meant to be copied back into a call renders as a code span (`markdown().inlineCode`), so it reads back under CommonMark as the `structuredContent` value
453
456
  - [ ] EDGAR upstream sparsity: schemas reflect real nullability; `format()` preserves uncertainty (don't fabricate facts from missing XBRL fields); tests cover at least one sparse payload
454
457
  - [ ] Registered in `createApp()` arrays (directly or via barrel exports)
455
458
  - [ ] Tests use `createMockContext({ errors: tool.errors })` from `@cyanheads/mcp-ts-core/testing` for tools with declared contracts
package/README.md CHANGED
@@ -130,7 +130,7 @@ The skill ships in `skills/secedgar-guide/SKILL.md`. Plugin hosts load it from t
130
130
 
131
131
  ### `secedgar_get_insider_transactions` <sub>tool</sub>
132
132
 
133
- - `company` is the issuer; `transaction_type` `purchase` (code P), `sale` (code S), or `all` (default); `limit` 1–1,000, served at 100 (default 20); does not cover Forms 3 or 5
133
+ - `company` is the issuer, as a ticker, CIK, or current or former name; a name matching several companies fails as `ambiguous_company`, listing each CIK, name, and ticker to retry with; `transaction_type` `purchase` (code P), `sale` (code S), or `all` (default); `limit` 1–1,000, served at 100 (default 20); does not cover Forms 3 or 5
134
134
  - Without a date window it scans up to 100 of the newest Form 4 / 4-A filings; `filed_after` / `filed_before` (inclusive, either alone) read any period since mid-2003, up to 100 filings; `history_scanned_through` names the oldest filing parsed
135
135
  - Each transaction carries the reporting person, relationship, `transaction_code` and `transaction_type`, `is_derivative`, unsigned `shares_traded` with `direction` (`acquire` / `dispose`), price per share, and shares owned after; `dataset.truncated` flags filings beyond those parsed, and `filings_other_issuer` counts Form 4s the company filed as a reporting owner of another issuer, which add no rows. Price text preserves the numeric digits in fixed-point notation, with at least two decimal places.
136
136
 
@@ -149,6 +149,7 @@ The skill ships in `skills/secedgar-guide/SKILL.md`. Plugin hosts load it from t
149
149
  ### `secedgar_find_holders` <sub>tool</sub>
150
150
 
151
151
  - `issuer` as a ticker, CIK, or name, plus an optional 9-character `cusip`, the precise match key (a name phrase-match both over- and under-matches); `quarter` as `YYYY-QN`, defaulting to the newest quarter past its 45-day filing deadline; `limit` 1–100 (default 20; up to 1,000 is served at 100) from up to 500 fetched filings
152
+ - Without `cusip`, the phrase is the issuer's registry name minus a trailing qualifier such as `\DE\` or `/OH/`; when another registrant's name reduces to the same phrase (`FIRST BANCORP /PR/` and `/NC/`), the holders can include that company's, and the notice names it with CIK and ticker and points to `cusip`
152
153
  - Rows carry `filer_cik`, `accession_number`, and `form`, while `search_mode` (`cusip` / `name`), `total_filings`, `fetched`, and `holders_in_quarter` size the result; the list is unranked, so pass a `filer_cik` to `secedgar_get_institutional_holdings` to read the position
153
154
  - When matching documents exceed the fetch budget, the notice gives an exact `secedgar_search_filings` continuation with the query, dates and document offset. Filter `results.period_ending` to the quarter end, then deduplicate across the sample's `filer_cik` and search results' `cik`, keeping the latest `filing_date`. Advance by 100 documents per full page up to offset 9,900, whose page ends at EDGAR's 10,000-document paging ceiling; lower-bound totals may hide more beyond it
154
155
 
@@ -0,0 +1,16 @@
1
+ ---
2
+ summary: "Company name resolution no longer matches inside a word, and no tool silently answers for the first of several matching companies."
3
+ breaking: true
4
+ security: false
5
+ ---
6
+
7
+ # 0.18.0 — 2026-11-03
8
+
9
+ ## Changed
10
+
11
+ - **Breaking: calls that answered now fail, listing the matches** ([#218](https://github.com/cyanheads/secedgar-mcp-server/issues/218), [#219](https://github.com/cyanheads/secedgar-mcp-server/issues/219), [#223](https://github.com/cyanheads/secedgar-mcp-server/issues/223)). `secedgar_get_insider_transactions` with `company` "Energizer Holdings Inc" or "Blue Owl Capital" fails with `ambiguous_company`, and so does `secedgar_search_filings` with `ticker:Fluent`. `secedgar_company_search` with `query` "u s gold corp" or "baldw" fails with `multiple_matches`. Retry with a ticker or CIK from the list.
12
+ - **Company name resolution** ([#218](https://github.com/cyanheads/secedgar-mcp-server/issues/218), [#219](https://github.com/cyanheads/secedgar-mcp-server/issues/219)): no hit starts or ends inside a word ("SY Bancorp" no longer finds "Embassy Bancorp"), whitespace runs and spaced initials fold ("JM Smucker" finds "J M SMUCKER Co"), and a query with no letter or digit matches nothing. The `secedgar_company_search` `query` description follows.
13
+ - **`ambiguous_company`** ([#223](https://github.com/cyanheads/secedgar-mcp-server/issues/223)) is declared in `errors[]` on `secedgar_get_insider_transactions` and `secedgar_search_filings`, with the candidates in `data.matches` (`cik`, `name`, `ticker`) as on `secedgar_get_financials`.
14
+ - **USD amounts in `content[]`** ([#222](https://github.com/cyanheads/secedgar-mcp-server/issues/222)) scale by magnitude (T, B, M, K) with the sign before the `$` in `get_financials`, `fetch_frames`, `get_institutional_holdings`, and `get_fund_holdings`, so a small value no longer reads as `$0.00B` or `$0.0M`. Per-share and other-unit values keep every digit.
15
+ - **SEC and caller text in `content[]`** ([#221](https://github.com/cyanheads/secedgar-mcp-server/issues/221)), such as names, labels, descriptions, echoed inputs, and dataframe cells, is Markdown-escaped so a CommonMark parse reads back the `structuredContent` value; `secedgar_dataframe_describe` prints staged parameters as code spans. Escaping runs in time linear in input length ([mcp-ts-core#809](https://github.com/cyanheads/mcp-ts-core/issues/809)).
16
+ - **`secedgar_find_holders`** ([#224](https://github.com/cyanheads/secedgar-mcp-server/issues/224)) adds a notice when another current registrant's name reduces to the searched phrase (`FIRST BANCORP /PR/` and `/NC/`), naming it with CIK and ticker and pointing to `cusip`.
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @fileoverview The candidates an ambiguous company resolution names, rendered for the error
3
+ * message itself (clients that read only `content[]` otherwise get a "pick from the matches
4
+ * list" instruction with no list to pick from, #90) and for the `matches` data field.
5
+ * @module mcp-server/tools/ambiguous-matches
6
+ */
7
+ import type { CikMatch } from '../../services/edgar/types.js';
8
+ /**
9
+ * The first {@link MAX_SHOWN} candidates of a multi-match `resolveCik` result: `list` reads
10
+ * `<cik> <name> (<ticker>), …` for the message, `matches` carries the same rows as data.
11
+ */
12
+ export declare function ambiguousMatches(resolved: readonly CikMatch[]): {
13
+ list: string;
14
+ matches: {
15
+ cik: string;
16
+ name: string | undefined;
17
+ ticker: string | undefined;
18
+ }[];
19
+ };
20
+ //# sourceMappingURL=ambiguous-matches.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ambiguous-matches.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/ambiguous-matches.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAK1D;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE;IAG1D,IAAI;IAGJ,OAAO;;;;;EAEV"}
@@ -0,0 +1,22 @@
1
+ /**
2
+ * @fileoverview The candidates an ambiguous company resolution names, rendered for the error
3
+ * message itself (clients that read only `content[]` otherwise get a "pick from the matches
4
+ * list" instruction with no list to pick from, #90) and for the `matches` data field.
5
+ * @module mcp-server/tools/ambiguous-matches
6
+ */
7
+ /** Candidates named per ambiguous resolution. */
8
+ const MAX_SHOWN = 10;
9
+ /**
10
+ * The first {@link MAX_SHOWN} candidates of a multi-match `resolveCik` result: `list` reads
11
+ * `<cik> <name> (<ticker>), …` for the message, `matches` carries the same rows as data.
12
+ */
13
+ export function ambiguousMatches(resolved) {
14
+ const shown = resolved.slice(0, MAX_SHOWN);
15
+ return {
16
+ list: shown
17
+ .map((m) => `${m.cik} ${m.name ?? 'Unknown'}${m.ticker ? ` (${m.ticker})` : ''}`)
18
+ .join(', '),
19
+ matches: shown.map((m) => ({ cik: m.cik, name: m.name, ticker: m.ticker })),
20
+ };
21
+ }
22
+ //# sourceMappingURL=ambiguous-matches.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ambiguous-matches.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/ambiguous-matches.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,iDAAiD;AACjD,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA6B;IAC5D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAC3C,OAAO;QACL,IAAI,EAAE,KAAK;aACR,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;aAChF,IAAI,CAAC,IAAI,CAAC;QACb,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;KAC5E,CAAC;AACJ,CAAC"}
@@ -1 +1 @@
1
- {"version":3,"file":"company-search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/company-search.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAG3E,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,mCAAmC,CAAC;AAuF3C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2d5B,CAAC;AAEH,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEjE"}
1
+ {"version":3,"file":"company-search.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/company-search.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAI3E,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,mCAAmC,CAAC;AAuF3C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAie5B,CAAC;AAEH,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAEjE"}