canli-markets-mcp 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## Unreleased
 
+## 0.3.0
+
+- Fix: `event_study` took filing times from the submissions file's `acceptanceDateTime`, which is
+  labelled UTC but is not reliable. Measured 2026-10-11 on 450 filings from 25 companies' files:
+  - each file was either right for every filing in it, or shifted by one US Eastern offset (+4 h
+    in daylight time, +5 h in standard time);
+  - the same filing read differently in two files (Apple's and its director's);
+  - the shifted files were the ones rebuilt since early October 2026;
+  - edgartools#1501 also saw files that give Eastern time labelled UTC.
+
+  Day 0 turns on the 16:00 close, so a filing could land on the wrong day. With today's +1 shift
+  that happens only to afternoon filings: 1 of 31 JPMorgan 8-Ks since 2025, and none of 55 NVIDIA
+  insider sales. In a file that labels Eastern time as UTC, every release after the close would
+  fall on its own day.
+
+  Event times are now calibrated per file against the filing index page's "Accepted" time (the
+  newest and oldest event; 2 extra requests). If the two disagree, each event is read from its own
+  index page. The result says which was done (`event_times`).
+
+- New tool `earnings_calendar`: earnings dates from the companies' own 8-Ks under Item 2.02 (results
+  of operations).
+  - For a company: its recent results releases, the quarter each covered (from its 10-Q and 10-K
+    period ends), and whether each came before the open or after the close. The time is EDGAR's
+    acceptance time from the filing index, in Eastern time; the submissions API's
+    `acceptanceDateTime` is not used (see the `event_study` fix below).
+  - The next release is estimated 52 weeks after the one that followed the same quarter a year
+    earlier, with a window from how far the company's dates have moved year on year, and marked
+    upcoming, due now or late.
+  - Across the market: the companies that reported in the same weeks last year, with this year's
+    implied date, marked reported once they have (within three weeks).
+  - Estimates, not announcements. Checked live: Apple 2026-10-29 after the close, NVIDIA 2026-11-18
+    after the close, Walmart 2026-11-19 before the open, JPMorgan 2026-10-13 before the open.
+- `company_events` gives each 8-K the headline of the press release attached to it (an EX-99
+  exhibit), for example "Apple reports third quarter results", "Pfizer Announces Chief Financial
+  Officer Transition" or "Bank of America Increases Common Stock Dividend 14% to $0.32 Per Share".
+  The headline is the first line of real text after EDGAR's document header and the boilerplate; it
+  is never the company's letterhead, and an exhibit that opens with financial statements has none.
+  These are news headlines from the companies themselves, not a news wire. Reading them adds up to
+  two requests per filing; `excerpts: false` skips both.
+- Fix: a ticker that is not in the SEC's file of listed companies went to EDGAR's name search, which
+  matches prefixes, so "VOO" (an ETF) was Vooy, Inc. Mutual fund and ETF tickers now resolve through
+  the SEC's fund ticker file to the trust that registers them (VOO is Vanguard Index Funds). A
+  ticker in neither file is refused rather than guessed. If the fund file cannot be read, names are
+  searched as before.
+
 ## 0.2.1
 
 The first 0.2 release on npm: 0.2.0's tools, and a fix for answers that were wrong without warning.

package/README.md

@@ -44,7 +44,8 @@ received and when, so any figure can be checked against the same document later.
 | `list_filings` | What has it filed: by form and date, with links | SEC |
 | `read_filing` | What does the filing say: one 10-K/10-Q item ("risk factors", "md&a"), an 8-K press release (`EX-99.1`), paged | SEC |
 | `search_filings` | Which filings mention a phrase, since 2001 | EDGAR full-text search |
-| `company_events` | A company's news from its 8-Ks (earnings, deals, executive changes, restatements, bankruptcies, cyber incidents) in the filing's own words; or one kind of event across the market | Form 8-K |
+| `company_events` | A company's news from its 8-Ks (earnings, deals, executive changes, restatements, bankruptcies, cyber incidents): the headline of the press release attached, and the filing's own words; or one kind of event across the market | Form 8-K |
+| `earnings_calendar` | A company's results release dates with the quarter covered and before the open or after the close, and the next one estimated from the same quarter last year; or who is due to report in a window across the market | SEC EDGAR (8-K Item 2.02) |
 | `segment_revenue` | Where revenue comes from: by segment (with operating income), product and region, three years, checked against total revenue | 10-K/10-Q XBRL |
 | `insider_trades` | Who inside bought or sold, at what price, under a 10b5-1 plan or not | Form 4 |
 | `fund_holdings` | What a fund manager holds, its weights, and what it bought and sold last quarter | 13F |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "canli-markets-mcp",
-  "version": "0.2.1",
-  "description": "MCP server for markets, funds and the economy from the sources themselves, no key: options chains and volatility, short interest, dark pools, futures positioning, fund and ETF holdings, 13D/13G, 8-K events, segment revenue, executive pay, Form D, the Fed, Treasury auctions, World Bank and OECD macro, screens, filings and prices. Every result cites its sources.",
+  "version": "0.3.0",
+  "description": "MCP server for markets, funds and the economy from the sources themselves, no key: options chains and volatility, short interest, dark pools, futures positioning, fund and ETF holdings, 13D/13G, earnings dates and 8-K press-release headlines, segment revenue, executive pay, Form D, the Fed, Treasury auctions, World Bank and OECD macro, screens, filings and prices. Every result cites its sources.",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/earnings.mjs

@@ -0,0 +1,172 @@
+// Earnings dates from the companies' own filings. A results release is filed on Form 8-K under Item
+// 2.02 (Results of Operations and Financial Condition), so a company's 8-Ks give the dates it
+// reported, and the filing index gives the time EDGAR accepted each one (Eastern time).
+//
+// For one company: its recent releases, the quarter each covered and whether it came before the
+// open or after the close, and the next one estimated from the same quarter a year earlier. Across
+// the market: the companies that reported in the same weeks last year, with the date that implies
+// this year, marked when they have already reported. Estimates, not announcements. No key.
+import { z } from "zod";
+
+import { archiveBase, filings, getJson, getText, NotFound, resolveEntity, tickerTable } from "./sources.mjs";
+
+const DAY = 86400000;
+const DATE = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date as YYYY-MM-DD");
+const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
+const plus = (d, days) => iso(Date.parse(d) + days * DAY);
+const between = (a, b) => Math.round((Date.parse(b) - Date.parse(a)) / DAY);
+const median = (xs) => { const s = [...xs].sort((x, y) => x - y); return s.length ? (s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2) : null; };
+const WEEKDAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+const weekday = (d) => WEEKDAYS[new Date(`${d}T12:00:00Z`).getUTCDay()];
+// Fifty-two weeks: the same weekday a year on, as most companies keep.
+const YEAR = 364;
+
+// EDGAR prints the acceptance time on the filing index in Eastern time ("2026-07-14 06:30:38").
+// The submissions API's acceptanceDateTime is not used: many files shift it by an Eastern offset
+// (see acceptanceTimes in sources.mjs).
+export function acceptedEastern(indexHtml) {
+  const m = String(indexHtml).match(/Accepted<\/div>\s*<div class="info">\s*(\d{4}-\d{2}-\d{2}) (\d{2}):(\d{2})(?::\d{2})?/);
+  return m ? { date: m[1], time: `${m[2]}:${m[3]}`, minutes: Number(m[2]) * 60 + Number(m[3]) } : null;
+}
+export function timing(minutes) {
+  if (minutes == null) return null;
+  return minutes < 9 * 60 + 30 ? "before the open" : minutes >= 16 * 60 ? "after the close" : "during market hours";
+}
+
+// The releases: 8-Ks carrying Item 2.02, oldest first. A second one within 20 days (a correction,
+// a supplement) belongs to the same quarter and is not a new release.
+export function releasesFrom(rows) {
+  const out = [];
+  for (const r of [...rows].filter((x) => x.form === "8-K" && String(x.items ?? "").split(",").map((s) => s.trim()).includes("2.02")).sort((x, y) => x.filingDate.localeCompare(y.filingDate))) {
+    const last = out[out.length - 1];
+    if (last && between(last.date, r.filingDate) <= 20) { last.also.push(r.accessionNumber); continue; }
+    out.push({ date: r.filingDate, accession: r.accessionNumber, document: r.primaryDocument, also: [] });
+  }
+  return out;
+}
+
+// The next release, from the release that followed the same quarter a year earlier; failing that,
+// from the usual gap between releases. The window is how far the company's dates have moved from
+// one year to the next.
+export function nextRelease(releases, today) {
+  if (!releases.length) return null;
+  const last = releases[releases.length - 1];
+  const yearAgo = releases.findIndex((r) => Math.abs(between(r.date, last.date) - YEAR) <= 30);
+  const shifts = [];
+  for (const r of releases) {
+    const before = releases.find((q) => Math.abs(between(q.date, r.date) - YEAR) <= 30);
+    if (before) shifts.push(Math.abs(between(before.date, r.date) - YEAR));
+  }
+  const window = Math.min(21, Math.max(3, Math.ceil(median(shifts) ?? 7) + 2));
+  let expected, basis, basedOn = null;
+  const prior = yearAgo >= 0 ? releases[yearAgo + 1] : null;
+  if (prior && between(last.date, plus(prior.date, YEAR)) > 30) {
+    expected = plus(prior.date, YEAR);
+    basedOn = prior.date;
+    basis = `52 weeks after ${prior.date}, the release that followed the same quarter a year earlier`;
+  } else {
+    const gaps = releases.slice(-9).map((r, i, a) => (i ? between(a[i - 1].date, r.date) : null)).filter((g) => g != null);
+    const gap = median(gaps);
+    if (!gap) return null;
+    expected = plus(last.date, Math.round(gap));
+    basis = `${Math.round(gap)} days after ${last.date}, the usual gap between its releases (less than a year of history to compare with)`;
+  }
+  const status = today > plus(expected, window) ? "late: no release filed yet" : today >= plus(expected, -window) ? "due now" : "upcoming";
+  return { expected, weekday: weekday(expected), window_days: window, earliest: plus(expected, -window), latest: plus(expected, window), basis, based_on: basedOn, status, year_on_year_moves_days: shifts.slice(-8) };
+}
+
+export const earningsInput = z.object({
+  company: z.string().min(1).max(120).optional().describe("Ticker, CIK or name: its results releases and the next one estimated. Leave out for the market."),
+  quarters: z.number().int().min(1).max(20).optional().describe("Past releases to list for a company; default 8."),
+  since: DATE.optional().describe("Across the market: first day of the window; default today."),
+  until: DATE.optional().describe("Across the market: last day; default 14 days after since, at most 31."),
+  limit: z.number().int().min(1).max(500).optional().describe("Across the market: most companies to list (the largest first); default 100."),
+}).strict();
+
+async function companyCalendar(session, a) {
+  const e = await resolveEntity(session, a.company);
+  const today = iso(session.now());
+  // The quarters shown, and at least five, so the release a year before the latest is in hand.
+  const { sub, rows } = await filings(session, e.cik, { since: plus(today, -(Math.max(a.quarters ?? 8, 5) + 1) * 92) });
+  const releases = releasesFrom(rows);
+  if (!releases.length) throw new NotFound(`${sub.name} has filed no 8-K under Item 2.02 (results of operations) in the period read${sub.category?.includes("foreign") || (sub.filings?.recent?.form ?? []).includes("6-K") ? "; foreign private issuers furnish results on Form 6-K, which has no item numbers" : ""}.`);
+  // The quarter each release covered: the latest fiscal period end from its 10-Qs and 10-Ks in the
+  // 100 days before it.
+  const ends = [...new Set(rows.filter((r) => /^10-[QK]/.test(r.form) && r.reportDate).map((r) => r.reportDate))].sort();
+  const covered = (d) => ends.filter((p) => p < d && between(p, d) <= 100).pop() ?? null;
+  const shown = releases.slice(-(a.quarters ?? 8));
+  const out = [];
+  for (const r of shown) {
+    const base = archiveBase(e.cik, r.accession);
+    let at = null;
+    try { at = acceptedEastern(await getText(session, `${base}/${r.accession}-index.htm`, { maxBytes: 2 * 1024 * 1024 })); } catch (err) { if (!(err instanceof NotFound)) throw err; }
+    out.push([r.date, weekday(r.date), at?.time ?? null, timing(at?.minutes), covered(r.date), r.accession, `${base}/${r.document}`]);
+  }
+  const next = nextRelease(releases, today);
+  const lastYearRow = next?.based_on ? out.find((row) => row[0] === next.based_on) : null;
+  return {
+    company: { cik: e.cik, name: sub.name, ticker: sub.tickers?.[0] ?? e.ticker ?? null, fiscal_year_end: sub.fiscalYearEnd ?? null },
+    as_of: today,
+    next: next ? { ...next, ...(lastYearRow?.[3] ? { last_year_timing: lastYearRow[3] } : {}) } : null,
+    releases: { columns: ["date", "weekday", "accepted_et", "timing", "quarter_ended", "accession", "url"], rows: out.reverse() },
+    note: "Dates are when the company filed its results 8-K (Item 2.02); accepted_et is when EDGAR accepted it, usually minutes after the press release. The next date is an estimate from the company's own history, not an announcement: companies move dates, and a release can come before its 8-K.",
+    source: `https://www.sec.gov/cgi-bin/browse-edgar?action=getcompany&CIK=${e.cik}&type=8-K&dateb=&owner=include&count=40`,
+    limits: ["From the company's own 8-K filings on EDGAR, as filed. Foreign private issuers furnish results on Form 6-K, which has no item numbers, and are not covered.", "Not investment advice."],
+  };
+}
+
+// Companies that filed a results 8-K in a window, one row per company (the first release in it).
+async function reporters(session, since, until) {
+  const by = new Map();
+  for (let from = 0; from < 3000; from += 100) {
+    const r = await getJson(session, `https://efts.sec.gov/LATEST/search-index?q=%22Item%202.02%22&forms=8-K&dateRange=custom&startdt=${since}&enddt=${until}${from ? `&from=${from}` : ""}`);
+    const page = r?.hits?.hits ?? [];
+    for (const h of page) {
+      const s = h._source ?? {};
+      if (!(s.items ?? []).includes("2.02") || !s.ciks?.[0]) continue;
+      const cik = Number(s.ciks[0]);
+      const prev = by.get(cik);
+      if (!prev || s.file_date < prev.date) by.set(cik, { cik, date: s.file_date, name: String(s.display_names?.[0] ?? "").replace(/\s*\(CIK \d+\)\s*$/, "").replace(/\s*\([^)]*\)\s*$/, "").replace(/\s+/g, " ").trim() || null });
+    }
+    if (page.length < 100) break;
+  }
+  return by;
+}
+
+async function marketCalendar(session, a) {
+  const today = iso(session.now());
+  const since = a.since ?? today, until = a.until ?? plus(since, 14);
+  if (until < since) throw new Error("until must be on or after since.");
+  if (between(since, until) > 31) throw new Error("The window can be at most 31 days; narrow since and until.");
+  // Last year's same weeks (52 weeks earlier, so weekdays line up), and this year's releases so far.
+  const before = await reporters(session, plus(since, -YEAR), plus(until, -YEAR));
+  // Reports this year from three weeks before the window to three weeks after it (or today), the
+  // same tolerance a release is matched to its expected date with.
+  const doneUntil = plus(until, 21) < today ? plus(until, 21) : today;
+  const done = since <= today ? await reporters(session, plus(since, -21), doneUntil) : new Map();
+  const table = Object.values(await tickerTable(session));
+  const rank = new Map(), ticker = new Map();
+  table.forEach((r, i) => { if (!rank.has(r.cik_str)) { rank.set(r.cik_str, i); ticker.set(r.cik_str, r.ticker); } });
+  const rows = [...before.values()].map((b) => {
+    const expected = plus(b.date, YEAR);
+    const reported = done.get(b.cik);
+    const hit = reported && Math.abs(between(expected, reported.date)) <= 21 ? reported.date : null;
+    return { expected, name: b.name, ticker: ticker.get(b.cik) ?? null, status: hit ? "reported" : expected < today ? "expected (date passed, not yet filed)" : "expected", reported_on: hit, last_year: b.date, cik: b.cik, rank: rank.get(b.cik) ?? Infinity };
+  });
+  const listed = rows.filter((r) => Number.isFinite(r.rank));
+  const pick = [...listed].sort((x, y) => x.rank - y.rank).slice(0, a.limit ?? 100).sort((x, y) => x.expected.localeCompare(y.expected) || x.rank - y.rank);
+  return {
+    since, until, as_of: today,
+    companies: rows.length, listed: listed.length, shown: pick.length,
+    columns: ["expected", "company", "ticker", "status", "reported_on", "last_year", "cik"],
+    rows: pick.map((r) => [r.expected, r.name, r.ticker, r.status, r.reported_on, r.last_year, r.cik]),
+    note: "Each expected date is 52 weeks after the company's results 8-K (Item 2.02) in the same weeks last year, an estimate rather than an announcement. Listed companies only, largest first (by the SEC's ticker file) when there are more than the limit. A company is marked reported when it filed a results 8-K within three weeks of its expected date. earnings_calendar with company refines one company from its full history.",
+    sources: [`https://efts.sec.gov/LATEST/search-index?q=%22Item%202.02%22&forms=8-K&dateRange=custom&startdt=${plus(since, -YEAR)}&enddt=${plus(until, -YEAR)}`, "https://www.sec.gov/files/company_tickers.json"],
+    limits: ["From EDGAR full-text search of 8-Ks under Item 2.02, as filed. Companies that changed their schedule, listed in the past year or furnish results on Form 6-K (foreign private issuers) are missed or misdated.", "Not investment advice."],
+  };
+}
+
+export async function earningsCalendar(session, args) {
+  const a = earningsInput.parse(args);
+  return a.company ? companyCalendar(session, a) : marketCalendar(session, a);
+}

package/src/events.mjs

@@ -67,6 +67,43 @@ export function itemExcerpt(text, code, max = 420) {
   return out ? out.slice(0, max) + (out.length > max ? "…" : "") : null;
 }
 
+// The headline of a press release exhibit: its first line of real text after EDGAR's document header
+// and the boilerplate around it ("Exhibit 99.1", "FOR IMMEDIATE RELEASE", contacts, the dateline).
+const BOILERPLATE = /^(exhibit\s*99(\.\d+)?|ex-?99(\.\d+)?|document|press release|news release|for immediate release|for release|investor (relations|contacts?)|media (relations|contacts?)|contacts?:?|page \d+|\d+|[•■▪●◦\-–—*]+)$/i;
+// A company's name as words, without punctuation or legal suffixes, to tell its letterhead from a headline.
+const nameKey = (n) => String(n ?? "").toLowerCase().replace(/[^a-z0-9& ]+/g, " ").split(/\s+/).filter((w) => w && !["inc", "corp", "corporation", "co", "company", "ltd", "plc", "llc", "lp", "the", "nv", "sa", "ag", "holdings", "group"].includes(w)).join(" ");
+export function pressHeadline(html, company = null) {
+  const letterhead = company ? nameKey(company) : null;
+  let s = String(html ?? "");
+  // EDGAR's document header (<TYPE>, <SEQUENCE>, <FILENAME>, <DESCRIPTION>) comes before <TEXT>.
+  const textAt = s.search(/<TEXT>/i);
+  if (textAt >= 0) s = s.slice(textAt + 6);
+  const lines = htmlToText(s).split("\n").map((x) => x.replace(/\s+/g, " ").replace(/\s*Exhibit 99(\.\d+)?$/i, "").trim()).filter(Boolean);
+  for (const l of lines.slice(0, 60)) {
+    if (BOILERPLATE.test(l) || /\.(htm|html|jpe?g|png|gif)$/i.test(l)) continue;
+    if (letterhead && nameKey(l) === letterhead) continue;
+    // An exhibit that opens with financial statements is not a press release.
+    if (/^(unaudited |audited )?(condensed |interim )?(consolidated |combined )?(financial (statements?|information|data)\b|financial$|balance sheets?\b|statements? of (operations|income|cash flows|financial (position|condition)))/i.test(l)) return null;
+    // A dateline ("NEW YORK, June 18, 2026") or a date alone is not the headline.
+    if (/^[A-Z][A-Za-z .,'&-]*,\s+[A-Z][a-z]+\.? \d{1,2},? \d{4}\b/.test(l) || /^[A-Z][a-z]+\.? \d{1,2},? \d{4}$/.test(l)) continue;
+    const words = l.split(" ").length;
+    if (words < 3 || words > 40 || l.length > 300 || !/[A-Za-z]{4,}/.test(l)) continue;
+    return l;
+  }
+  return null;
+}
+
+// The headline of the press release attached to an 8-K, when it has one (an EX-99 exhibit).
+async function headlineFor(session, cik, accession, company) {
+  try {
+    const ex = (await filingDocuments(session, cik, accession)).find((d) => /^EX-99/.test(d.type ?? ""));
+    return ex ? pressHeadline(await getText(session, ex.url, { maxBytes: 8 * 1024 * 1024 }), company) : null;
+  } catch (err) {
+    if (err instanceof NotFound) return null;
+    throw err;
+  }
+}
+
 async function excerptFor(session, url, codes) {
   try {
     const text = await getText(session, url, { maxBytes: 8 * 1024 * 1024, transform: htmlToText });
@@ -86,7 +123,7 @@ export const eventsInput = z.object({
   since: DATE.optional().describe("Filed on or after this date; default 180 days ago for a company, 30 days across the market."),
   until: DATE.optional().describe("Filed on or before this date; default today."),
   limit: z.number().int().min(1).max(40).optional().describe("Most events to list; default 15."),
-  excerpts: z.boolean().optional().describe("Read each filing for the opening of what it says; default true (one request per filing)."),
+  excerpts: z.boolean().optional().describe("Read each filing for the opening of what it says and its press release's headline; default true (up to three requests per filing)."),
 }).strict();
 
 export async function companyEvents(session, args) {
@@ -94,9 +131,9 @@ export async function companyEvents(session, args) {
   const code = a.event ? eventCode(a.event) : null;
   const limit = a.limit ?? 15;
   const until = a.until ?? isoDay(session);
-  const columns = ["filed", "company", "items", "events", "excerpt", "accession", "url"];
+  const columns = ["filed", "company", "items", "events", "headline", "excerpt", "accession", "url"];
   const limits = [
-    "From Forms 8-K as filed with the SEC, usually within four business days of the event; Canli Capital does not edit or verify them. Excerpts are the opening of the filing's text under the item.",
+    "From Forms 8-K as filed with the SEC, usually within four business days of the event; Canli Capital does not edit or verify them. Excerpts are the opening of the filing's text under the item; a headline is the title of the press release attached as an exhibit (EX-99), when there is one.",
     "An earnings release (2.02) or investor presentation (7.01) is usually in exhibit 99.1; read it with read_filing and document \"EX-99.1\".",
     "Not investment advice.",
   ];
@@ -111,7 +148,8 @@ export async function companyEvents(session, args) {
     const out = [];
     for (const { r, codes } of picked.slice(0, limit)) {
       const url = `${archiveBase(e.cik, r.accessionNumber)}/${String(r.primaryDocument).replace(/^xsl[^/]*\//, "")}`;
-      out.push([r.filingDate, sub.name, codes, decode(codes), a.excerpts === false ? null : await excerptFor(session, url, code ? [code] : codes), r.accessionNumber, url]);
+      const read = a.excerpts !== false;
+      out.push([r.filingDate, sub.name, codes, decode(codes), read ? await headlineFor(session, e.cik, r.accessionNumber, sub.name) : null, read ? await excerptFor(session, url, code ? [code] : codes) : null, r.accessionNumber, url]);
     }
     const counts = {};
     for (const { codes } of picked) for (const c of codes) if (c !== "9.01") counts[ITEMS[c]?.[0] ?? c] = (counts[ITEMS[c]?.[0] ?? c] ?? 0) + 1;
@@ -145,7 +183,8 @@ export async function companyEvents(session, args) {
       if (main) file = main.name;
     }
     const url = `${archiveBase(cik, adsh)}/${file}`;
-    out.push([s.file_date, (s.display_names?.[0] ?? "").replace(/\s+/g, " ").trim() || null, s.items ?? [], decode(s.items ?? []), a.excerpts === false ? null : await excerptFor(session, url, [code]), adsh, url]);
+    const read = a.excerpts !== false;
+    out.push([s.file_date, (s.display_names?.[0] ?? "").replace(/\s+/g, " ").trim() || null, s.items ?? [], decode(s.items ?? []), read ? await headlineFor(session, cik, adsh, String(s.display_names?.[0] ?? "").replace(/\s*\(.*$/, "")) : null, read ? await excerptFor(session, url, [code]) : null, adsh, url]);
   }
   return { event: { item: code, name: ITEMS[code][0], meaning: ITEMS[code][1] }, since, until, found: hits.length, columns, rows: out, source: `https://efts.sec.gov/LATEST/search-index?q=%22Item%20${code}%22&forms=8-K&dateRange=custom&startdt=${since}&enddt=${until}`, limits };
 }

package/src/research.mjs

@@ -4,7 +4,7 @@
 import { z } from "zod";
 
 import { parseForm4 } from "./forms.mjs";
-import { archiveBase, filings, getJson, getText, NotFound, resolveEntity, submissions } from "./sources.mjs";
+import { acceptanceTimes, archiveBase, filings, getJson, getText, NotFound, resolveEntity, submissions } from "./sources.mjs";
 import { priceHistory } from "./tools.mjs";
 
 const DATE = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date as YYYY-MM-DD");
@@ -456,7 +456,7 @@ export const eventInput = z.object({
 }).strict();
 
 // The first trading session at or after a filing's acceptance time (16:00 New York close).
-function sessionAfter(iso, tradingDays) {
+export function sessionAfter(iso, tradingDays) {
   const t = new Date(iso);
   const nyDate = new Intl.DateTimeFormat("en-CA", { timeZone: "America/New_York", year: "numeric", month: "2-digit", day: "2-digit" }).format(t);
   const nyHour = Number(new Intl.DateTimeFormat("en-US", { timeZone: "America/New_York", hour: "2-digit", hour12: false }).format(t)) % 24;
@@ -470,29 +470,30 @@ export async function eventStudy(session, args) {
   const symbol = a.symbol.toUpperCase(), bench = (a.benchmark ?? "SPY").toUpperCase();
   const [pre, post] = a.window ?? [-1, 5], est = a.estimation_days ?? 120, gap = 10, model = a.model ?? "market";
   // Events: dates, or filing acceptance times.
-  let raw = [], source = null;
+  let raw = [], source = null, eventTimes = null;
   if (a.events) raw = a.events.map((d) => ({ at: d, kind: "date", label: d }));
   else {
     const e = await resolveEntity(session, symbol);
     const since = a.since ?? daysAgo(session, 3 * 365);
-    const { rows } = await filings(session, e.cik, { since });
+    const { sub, rows } = await filings(session, e.cik, { since });
     source = `https://data.sec.gov/submissions/CIK${String(e.cik).padStart(10, "0")}.json`;
-    const sub = await submissions(session, e.cik);
-    const acc = new Map();
-    const r = sub.filings?.recent ?? {};
-    (r.accessionNumber ?? []).forEach((x, i) => acc.set(x, r.acceptanceDateTime?.[i]));
     if (a.event_type === "earnings" || a.event_type === "8k") {
-      for (const f of rows) if (f.form === "8-K" && f.filingDate >= since && (a.event_type === "8k" || String(f.items ?? "").split(",").includes("2.02"))) raw.push({ at: acc.get(f.accessionNumber) ?? `${f.filingDate}T21:00:00.000Z`, kind: "filing", label: `${f.form} ${f.accessionNumber}` });
+      for (const f of rows) if (f.form === "8-K" && f.filingDate >= since && (a.event_type === "8k" || String(f.items ?? "").split(",").includes("2.02"))) raw.push({ accession: f.accessionNumber, filed: f.filingDate, kind: "filing", label: `${f.form} ${f.accessionNumber}` });
     } else {
       const code = a.event_type === "insider_buys" ? "P" : "S";
       const f4 = rows.filter((f) => f.form === "4" && f.filingDate >= since).slice(0, 120);
       await Promise.all(f4.map(async (f) => {
         try {
           const doc = parseForm4(await getText(session, `${archiveBase(e.cik, f.accessionNumber)}/${f.primaryDocument.replace(/^xsl[^/]*\//, "")}`, { maxBytes: 4 * 1024 * 1024 }));
-          if (doc.rows.some((t) => t.code === code && t.kind === "stock")) raw.push({ at: acc.get(f.accessionNumber) ?? `${f.filingDate}T21:00:00.000Z`, kind: "filing", label: `Form 4 ${f.accessionNumber} (${doc.owners.map((o) => o.name).join("; ")})` });
+          if (doc.rows.some((t) => t.code === code && t.kind === "stock")) raw.push({ accession: f.accessionNumber, filed: f.filingDate, kind: "filing", label: `Form 4 ${f.accessionNumber} (${doc.owners.map((o) => o.name).join("; ")})` });
         } catch { /* unreadable Form 4 skipped */ }
       }));
     }
+    // Day 0 turns on before or after the 16:00 close, so the time must be right (acceptanceTimes).
+    const { times, shift } = await acceptanceTimes(session, e.cik, sub, raw.map((x) => x.accession));
+    for (const x of raw) x.at = times.has(x.accession) ? new Date(times.get(x.accession)).toISOString() : `${x.filed}T21:00:00.000Z`;
+    eventTimes = shift == null ? "Acceptance times read from each filing's index page on EDGAR (Eastern time); the submissions file's times did not agree with them."
+      : `Acceptance times from EDGAR's submissions file${shift ? `, which shifted them by ${shift > 0 ? "+" : "-"}1 US Eastern offset (4 or 5 hours); corrected` : ""}, checked against the filing index pages of the newest and oldest event.`;
   }
   if (!raw.length) throw new NotFound(`No ${a.event_type ?? "given"} events for ${symbol}${a.event_type ? ` since ${a.since ?? daysAgo(session, 3 * 365)}` : ""}.`);
   raw.sort((x, y) => String(x.at).localeCompare(String(y.at)));
@@ -540,6 +541,7 @@ export async function eventStudy(session, args) {
     ...(skipped.length ? { skipped: { columns: ["event", "reason"], rows: skipped.slice(0, 20) } } : {}),
     meaning: "Abnormal return = actual return minus the model's expected return; CAR sums it over the window. t_stat and p_value test whether the mean CAR across events differs from zero (cross-sectional t test). Returns are simple daily returns of adjusted closes.",
     ...(source ? { sources: [source] } : {}),
+    ...(eventTimes ? { event_times: eventTimes } : {}),
     price_source: ps.source,
     limits: [...LIMITS, "Daily data; events on nearby days overlap and are not adjusted for; a few events give a weak test; a significant average is not a trading rule after costs."],
   };

package/src/server.mjs

@@ -15,6 +15,7 @@ import { createSession, evidenceScope } from "./sources.mjs";
 import * as Adv from "./advisers.mjs";
 import * as Cal from "./calendar.mjs";
 import * as CB from "./centralbank.mjs";
+import * as Earn from "./earnings.mjs";
 import * as E from "./events.mjs";
 import * as F from "./funds.mjs";
 import * as G from "./global.mjs";
@@ -29,7 +30,7 @@ import * as T from "./tools.mjs";
 
 export const SERVER_NAME = "canli-markets-mcp";
 export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-export const SERVER_INSTRUCTIONS = "Market data and research from the public sources themselves. Across the market: screen_companies ranks every US-listed company on fundamentals, company_report gives one company's financials, segment_revenue its revenue by segment, product and region, valuation, risk, insiders and filings in one call, event_study measures price reactions to earnings or insider trades, mentions_trend counts a phrase in filings over time. Companies: company_profile, list_filings, then read_filing (section \"risk factors\", \"md&a\" and so on for a 10-K or 10-Q; document \"EX-99.1\" for an 8-K press release); search_filings finds words across all filings; executive_pay reads a proxy's pay-versus-performance table; company_events gives a company's 8-K news (or, by event, the whole market's: restatements, bankruptcies, cyber incidents). Ownership: insider_trades (Form 4) and fund_holdings (a manager's 13F); large_holders (13D/13G: 5 percent holders and activists), investment_advisers (Form ADV); funds: fund_portfolio (what a mutual fund or ETF holds, its flows and returns, from N-PORT); private markets: private_offerings (Form D raises by startups and funds); positioning: short_interest, off_exchange_volume (FINRA dark pools), fails_to_deliver (SEC) and futures_positioning (CFTC Commitments of Traders). Rates and the economy: economic_calendar (when the data comes out), fomc (the Fed's decisions, votes and projections), treasury_yields, treasury_auctions, federal_debt, economic_series (FRED), world_economy (World Bank, every country) and economic_outlook (OECD projections). Options: options_chain, volatility_surface and futures_curve (Cboe delayed data). Prices: price_history for stocks in the US and abroad, currencies, futures, indices and crypto (no key needed; the user's Alpaca or Tiingo key is used for US stocks when set). Every result has its source URL; cite it.";
+export const SERVER_INSTRUCTIONS = "Market data and research from the public sources themselves. Across the market: screen_companies ranks every US-listed company on fundamentals, company_report gives one company's financials, segment_revenue its revenue by segment, product and region, valuation, risk, insiders and filings in one call, event_study measures price reactions to earnings or insider trades, mentions_trend counts a phrase in filings over time. Companies: company_profile, list_filings, then read_filing (section \"risk factors\", \"md&a\" and so on for a 10-K or 10-Q; document \"EX-99.1\" for an 8-K press release); search_filings finds words across all filings; executive_pay reads a proxy's pay-versus-performance table; company_events gives a company's 8-K news (or, by event, the whole market's: restatements, bankruptcies, cyber incidents). earnings_calendar gives a company's results dates and the next one estimated, or who reports in a window. Ownership: insider_trades (Form 4) and fund_holdings (a manager's 13F); large_holders (13D/13G: 5 percent holders and activists), investment_advisers (Form ADV); funds: fund_portfolio (what a mutual fund or ETF holds, its flows and returns, from N-PORT); private markets: private_offerings (Form D raises by startups and funds); positioning: short_interest, off_exchange_volume (FINRA dark pools), fails_to_deliver (SEC) and futures_positioning (CFTC Commitments of Traders). Rates and the economy: economic_calendar (when the data comes out), fomc (the Fed's decisions, votes and projections), treasury_yields, treasury_auctions, federal_debt, economic_series (FRED), world_economy (World Bank, every country) and economic_outlook (OECD projections). Options: options_chain, volatility_surface and futures_curve (Cboe delayed data). Prices: price_history for stocks in the US and abroad, currencies, futures, indices and crypto (no key needed; the user's Alpaca or Tiingo key is used for US stocks when set). Every result has its source URL; cite it.";
 export const SERVER_INFO = Object.freeze({
   name: SERVER_NAME, version: SERVER_VERSION, title: "Canli Markets",
   websiteUrl: "https://canlicapital.com/developers",
@@ -44,9 +45,10 @@ export const TOOL_DESCRIPTIONS = Object.freeze({
   insider_trades: "Insider transactions at a company from its Form 4 filings: who (officers, directors, 10% owners), what (open-market buys and sales, option exercises, tax withholding, gifts), shares, price, value, holdings after, and 10b5-1 plan flags, with a buy/sell summary. Default: the last 90 days.",
   fund_holdings: "A fund manager's 13F holdings for a quarter (latest by default): positions by value with portfolio weights, the total checked against the filing's cover page, and what changed since the previous quarter (new, exited, added, reduced).",
   fund_portfolio: "What a US mutual fund or ETF holds, from its own SEC Form N-PORT (VOO, IVV, QQQ, AGG, FXAIX): every position with value and weight, exposure by asset type, issuer, country and currency, a bond fund's coupon and maturity profile, its monthly returns, the money that came in and went out each month, and what changed since the previous quarter.",
+  earnings_calendar: "Earnings dates from the companies' own 8-Ks (Item 2.02, results of operations). For a company: its recent results releases with the quarter each covered and whether it came before the open or after the close (EDGAR's acceptance time), and the next release estimated from the same quarter a year earlier, with a window. Across the market: who is due to report in a window, from when they reported in the same weeks last year, marked once they have. Estimates, not announcements.",
   investment_advisers: "Investment advisers from the SEC's Form ADV database (IAPD) by name or CRD: matching firms with SEC file numbers, status, whether they report disclosure events, offices and branch counts, then the best match in full: registration and since when, other names and relying advisers, its latest ADV date, and links to its Form ADV and brochures.",
   large_holders: "Who owns more than 5 percent of a company, from Schedules 13D and 13G: each holder's latest stake (shares, percent of class, voting power), whether it is passive (13G) or may seek to influence control (13D, with its stated purpose); or, with no company, the newest 13D stakes across the whole market.",
-  company_events: "Company news from the source: the events companies must report on Form 8-K (earnings, deals, executive changes, restatements, auditor changes, bankruptcies, cyber incidents, layoffs, delisting notices), for one company or, by event, across the whole market, each with the opening of what the filing says.",
+  company_events: "Company news from the source: the events companies must report on Form 8-K (earnings, deals, executive changes, restatements, auditor changes, bankruptcies, cyber incidents, layoffs, delisting notices), for one company or, by event, across the whole market, each with the headline of the press release it attached and the opening of what the filing says.",
   private_offerings: "Private markets from Form D, filed when startups and funds sell securities without registering: amount offered and sold, number of investors, minimum investment, exemption (Rule 506(b) or 506(c)), industry, fund type and the people behind it, for one issuer or across the market (newest first, filtered by industry or amount sold).",
   fails_to_deliver: "Shares that failed to settle, from the SEC's fails-to-deliver data (NSCC): a stock's outstanding fail balance on each settlement date over the latest half-month files, with prices and dollar values, or the securities with the largest fails across the market.",
   off_exchange_volume: "How much of a US stock trades away from the exchanges, from FINRA's OTC transparency data: weekly shares and trades in dark pools (ATSs) and with other off-exchange dealers, and the largest dark pools and dealers in the latest week.",
@@ -83,9 +85,10 @@ export const TOOL_KEYWORDS = Object.freeze({
   insider_trades: "insider insiders buying selling buy sell form 4 executives directors ceo cfo officers stock sales purchases",
   fund_holdings: "13f hedge fund institutional investor holdings portfolio positions manager owns own bought sold stake",
   fund_portfolio: "etf etfs mutual fund funds holdings constituents portfolio composition what does it hold exposure top holdings weights bond fund maturity coupon flows inflows outflows creations redemptions n-port index fund vanguard ishares fidelity invesco",
+  earnings_calendar: "earnings date dates calendar when report reports reporting results release next earnings upcoming this week season quarterly results announcement before the open after the close bmo amc schedule due expected",
   investment_advisers: "investment adviser advisers ria registered investment adviser form adv iapd hedge fund manager asset manager wealth manager firm crd disclosures brochure",
   large_holders: "activist activists 13d 13g beneficial owner owners 5 percent stake stakes major shareholders blockholders largest holders who owns control proxy fight hostile",
-  company_events: "news events announcement announced 8-k current report ceo cfo resign resignation departure appointed hired fired merger acquisition deal agreement bankruptcy chapter 11 restatement restated auditor cyber hack breach layoffs restructuring impairment delisting earnings release guidance",
+  company_events: "news headlines headline press release press releases latest news events announcement announced 8-k current report ceo cfo resign resignation departure appointed hired fired merger acquisition deal agreement bankruptcy chapter 11 restatement restated auditor cyber hack breach layoffs restructuring impairment delisting earnings release guidance",
   private_offerings: "private placement placements form d raise raised fundraising funding round startup startups venture capital vc private equity hedge fund real estate syndication reg d 506b 506c accredited investors",
   fails_to_deliver: "fails to deliver ftd failed settlement naked short selling short squeeze reg sho threshold securities settlement fails nscc",
   off_exchange_volume: "dark pool dark pools ats off exchange otc volume internalization wholesalers citadel virtu where does it trade hidden liquidity block trades",
@@ -123,6 +126,7 @@ export const OUTPUT_SCHEMAS = Object.freeze({
   insider_trades: z.looseObject({ summary: opt(z.looseObject({})), ...table, ...common }).describe("rows are Form 4 transactions, newest first; summary totals open-market purchases and sales."),
   fund_holdings: z.looseObject({ period: opt(z.string()), total_value: opt(z.number()), entries_total: opt(z.number()), positions_total: opt(z.number()), matches_cover_page: opt(z.boolean()), changes_since: opt(z.looseObject({})), ...table, ...common }).describe("rows are positions by value with weights; changes_since compares with the previous quarter."),
   fund_portfolio: z.looseObject({ fund: opt(z.looseObject({})), period: opt(z.string()), net_assets: opt(z.number().nullable()), positions: opt(z.number()), exposure: opt(z.looseObject({})), bonds: opt(z.looseObject({})), monthly_returns: opt(z.looseObject({})), flows: opt(z.looseObject({})), changes_since: opt(z.looseObject({})), ...table, ...common }).describe("rows are the largest positions by value, weights as fractions of net assets; exposure sums weights by asset type, issuer, country and currency; flows are dollars in and out each month."),
+  earnings_calendar: z.looseObject({ company: opt(z.looseObject({})), next: opt(z.looseObject({}).nullable()), releases: opt(z.looseObject({})), since: opt(z.string()), until: opt(z.string()), ...table, ...common }).describe("For a company: next is the estimated next release (expected, earliest, latest, basis, status) and releases is a table, newest first. Across the market: rows are companies in the order of columns."),
   investment_advisers: z.looseObject({ matches: opt(z.number()), firm: opt(z.looseObject({})), ...table, ...common }).describe("rows are matching firms in the order of columns; firm is the best match (or the CRD asked for) in full."),
   large_holders: z.looseObject({ company: opt(z.looseObject({})), purposes_13d: opt(z.array(z.unknown())), earlier_text_filings: opt(z.looseObject({})), ...table, ...common }).describe("rows are holders (latest filing each, largest stake first) or, across the market, filings; percent_of_class is a fraction."),
   company_events: z.looseObject({ company: opt(z.looseObject({})), event: opt(z.looseObject({})), counts: opt(z.looseObject({})), ...table, ...common }).describe("rows are 8-K filings, newest first: items are the 8-K item numbers, events their names, excerpt the opening of the filing's text under the item."),
@@ -152,13 +156,13 @@ export const OUTPUT_SCHEMAS = Object.freeze({
   price_history: z.looseObject({ symbol: opt(z.string()), change: opt(z.looseObject({})), dates: opt(z.array(z.string())), close: opt(z.array(z.number())), ...common }).describe("dates, open, high, low, close and volume are aligned columns, oldest first; change.total_return is the window's return with dividends reinvested (a fraction)."),
 });
 
-const TITLES = { screen_companies: "Screen companies", company_report: "Company report", event_study: "Event study", mentions_trend: "Mentions over time", company_profile: "Company profile", list_filings: "List filings", read_filing: "Read a filing", search_filings: "Search filings", insider_trades: "Insider trades", fund_holdings: "Fund holdings (13F)", fund_portfolio: "Fund or ETF portfolio (N-PORT)", large_holders: "Large holders (13D/13G)", investment_advisers: "Investment advisers (Form ADV)", company_events: "Company events (8-K)", private_offerings: "Private offerings (Form D)", short_interest: "Short interest (FINRA)", off_exchange_volume: "Dark pool and OTC volume (FINRA)", fails_to_deliver: "Fails to deliver (SEC)", executive_pay: "Executive pay vs performance", fomc: "Fed rate decisions (FOMC)", economic_calendar: "Economic calendar", index_constituents: "Index constituents", options_chain: "Options chain (Cboe)", volatility_surface: "Volatility surface (Cboe)", futures_curve: "Futures curve (Cboe)", segment_revenue: "Revenue by segment", futures_positioning: "Futures positioning (CFTC COT)", treasury_yields: "Treasury yields", economic_series: "Economic series (FRED)", world_economy: "World economy (World Bank)", economic_outlook: "Economic outlook (OECD projections)", treasury_auctions: "Treasury auctions", federal_debt: "US federal debt", price_history: "Price history" };
+const TITLES = { screen_companies: "Screen companies", company_report: "Company report", event_study: "Event study", mentions_trend: "Mentions over time", company_profile: "Company profile", list_filings: "List filings", read_filing: "Read a filing", search_filings: "Search filings", insider_trades: "Insider trades", fund_holdings: "Fund holdings (13F)", fund_portfolio: "Fund or ETF portfolio (N-PORT)", large_holders: "Large holders (13D/13G)", earnings_calendar: "Earnings calendar", investment_advisers: "Investment advisers (Form ADV)", company_events: "Company events (8-K)", private_offerings: "Private offerings (Form D)", short_interest: "Short interest (FINRA)", off_exchange_volume: "Dark pool and OTC volume (FINRA)", fails_to_deliver: "Fails to deliver (SEC)", executive_pay: "Executive pay vs performance", fomc: "Fed rate decisions (FOMC)", economic_calendar: "Economic calendar", index_constituents: "Index constituents", options_chain: "Options chain (Cboe)", volatility_surface: "Volatility surface (Cboe)", futures_curve: "Futures curve (Cboe)", segment_revenue: "Revenue by segment", futures_positioning: "Futures positioning (CFTC COT)", treasury_yields: "Treasury yields", economic_series: "Economic series (FRED)", world_economy: "World economy (World Bank)", economic_outlook: "Economic outlook (OECD projections)", treasury_auctions: "Treasury auctions", federal_debt: "US federal debt", price_history: "Price history" };
 export const TOOLS = Object.freeze({
   screen_companies: [R.screenInput, R.screenCompanies], company_report: [R.reportInput, R.companyReport], event_study: [R.eventInput, R.eventStudy], mentions_trend: [R.trendInput, R.mentionsTrend],
   company_profile: [T.profileInput, T.companyProfile], list_filings: [T.listInput, T.listFilings], read_filing: [T.readInput, T.readFiling],
   search_filings: [T.searchInput, T.searchFilings], insider_trades: [T.insiderInput, T.insiderTrades], fund_holdings: [T.holdingsInput, T.fundHoldings],
   treasury_yields: [T.treasuryInput, T.treasuryYields], economic_series: [T.fredInput, T.economicSeries], price_history: [T.priceInput, T.priceHistory],
-  fund_portfolio: [F.portfolioInput, F.fundPortfolio], options_chain: [Opt.chainInput, Opt.optionsChain], volatility_surface: [Opt.surfaceInput, Opt.volatilitySurface], futures_curve: [Opt.curveInput, Opt.futuresCurve], segment_revenue: [Seg.segmentInput, Seg.segmentRevenue], index_constituents: [F.indexInput, F.indexConstituents], fomc: [CB.fomcInput, CB.fomc], economic_calendar: [Cal.calendarInput, Cal.economicCalendar], executive_pay: [Pay.payInput, Pay.executivePay], short_interest: [Pos.shortInput, Pos.shortInterest], off_exchange_volume: [Pos.offExchangeInput, Pos.offExchangeVolume], fails_to_deliver: [Pos.ftdInput, Pos.failsToDeliver], futures_positioning: [Pos.cotInput, Pos.futuresPositioning], private_offerings: [P.offeringsInput, P.privateOfferings], company_events: [E.eventsInput, E.companyEvents], large_holders: [O.holdersInput, O.largeHolders], investment_advisers: [Adv.adviserInput, Adv.investmentAdvisers], world_economy: [G.worldInput, G.worldEconomy], economic_outlook: [G.outlookInput, G.economicOutlook], treasury_auctions: [G.auctionInput, G.treasuryAuctions], federal_debt: [G.debtInput, G.federalDebt],
+  fund_portfolio: [F.portfolioInput, F.fundPortfolio], options_chain: [Opt.chainInput, Opt.optionsChain], volatility_surface: [Opt.surfaceInput, Opt.volatilitySurface], futures_curve: [Opt.curveInput, Opt.futuresCurve], segment_revenue: [Seg.segmentInput, Seg.segmentRevenue], index_constituents: [F.indexInput, F.indexConstituents], fomc: [CB.fomcInput, CB.fomc], economic_calendar: [Cal.calendarInput, Cal.economicCalendar], executive_pay: [Pay.payInput, Pay.executivePay], short_interest: [Pos.shortInput, Pos.shortInterest], off_exchange_volume: [Pos.offExchangeInput, Pos.offExchangeVolume], fails_to_deliver: [Pos.ftdInput, Pos.failsToDeliver], futures_positioning: [Pos.cotInput, Pos.futuresPositioning], private_offerings: [P.offeringsInput, P.privateOfferings], company_events: [E.eventsInput, E.companyEvents], large_holders: [O.holdersInput, O.largeHolders], earnings_calendar: [Earn.earningsInput, Earn.earningsCalendar], investment_advisers: [Adv.adviserInput, Adv.investmentAdvisers], world_economy: [G.worldInput, G.worldEconomy], economic_outlook: [G.outlookInput, G.economicOutlook], treasury_auctions: [G.auctionInput, G.treasuryAuctions], federal_debt: [G.debtInput, G.federalDebt],
 });
 const ANNOTATIONS = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
 

package/src/sources.mjs

@@ -170,6 +170,13 @@ export async function postJson(session, url, payload, opts = {}) {
 export const pad10 = (cik) => String(Number(cik)).padStart(10, "0");
 export const archiveBase = (cik, accession) => `https://www.sec.gov/Archives/edgar/data/${Number(cik)}/${String(accession).replace(/-/g, "")}`;
 
+// Fund share classes by ticker (mutual funds and ETFs), from the SEC's fund ticker file.
+export async function fundTickers(session) {
+  const d = await getJson(session, "https://www.sec.gov/files/company_tickers_mf.json", { maxBytes: 8 * 1024 * 1024 });
+  const at = Object.fromEntries((d?.fields ?? []).map((f, i) => [f, i]));
+  return new Map((d?.data ?? []).map((r) => [r[at.symbol], { cik: r[at.cik], series: r[at.seriesId], class: r[at.classId] }]));
+}
+
 export async function tickerTable(session) {
   return getJson(session, "https://www.sec.gov/files/company_tickers.json");
 }
@@ -218,6 +225,14 @@ export async function resolveEntity(session, query) {
   const table = await tickerTable(session);
   const want = q.toUpperCase().replace(/\./g, "-").replace(/^\$/, "");
   for (const row of Object.values(table)) if (row.ticker === want) return { cik: row.cik_str, name: row.title, ticker: row.ticker, matched_by: "ticker" };
+  // Mutual funds and ETFs are in the SEC's fund ticker file, under the trust that registers them. If
+  // that file cannot be read, names are searched as before.
+  let funds = null;
+  try { funds = await fundTickers(session); } catch (err) { if (!(err instanceof NotFound)) throw err; }
+  const fund = funds?.get(want);
+  if (fund) return { cik: fund.cik, name: null, ticker: want, matched_by: "fund ticker", series: fund.series, class: fund.class };
+  // Written like a ticker but in neither file: not a name to guess at ("VOO" is not Vooy, Inc.).
+  if (funds && /^\$?[A-Z]{1,5}([.-][A-Z])?$/.test(q)) throw new NotFound(`${want} is not a ticker in the SEC's files of listed companies, mutual funds and ETFs (a delisted or changed ticker, or a foreign listing). Pass the company's name or CIK instead.`);
   const filer = knownAs(nameWords(q).join(" "));
   if (filer && typeof filer !== "string") return { cik: filer.cik, name: filer.name, ticker: null, matched_by: "name" };
   const listed = listedByName(table, q);
@@ -253,6 +268,70 @@ function filingRows(block) {
   return out;
 }
 
+// When EDGAR accepted each filing. The submissions files label acceptanceDateTime UTC, but it is not
+// reliable. Measured 2026-10-11 on 450 filings from 25 companies' files:
+//   - each file was either right for every filing in it, or shifted by one US Eastern offset
+//     (+4 h in daylight time, +5 h in standard time);
+//   - the same filing read differently in two files (the issuer's and the insider's);
+//   - the shifted files were the ones rebuilt since early October 2026.
+// edgartools#1501 also saw files with Eastern time labelled UTC. So the filing index page's
+// "Accepted" time (Eastern) calibrates a whole file: one probe, a second to check it, and
+// every time is read from its own index page if they disagree.
+const NY = new Intl.DateTimeFormat("en-US", { timeZone: "America/New_York", hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", second: "2-digit" });
+const HOUR = 3600000;
+export function easternOffsetMs(ms) {
+  const at = Math.floor(ms / 1000) * 1000;
+  const p = Object.fromEntries(NY.formatToParts(new Date(at)).map((x) => [x.type, x.value]));
+  return at - Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour) % 24, Number(p.minute), Number(p.second));
+}
+// An Eastern wall-clock time ("2026-07-14 06:30:38") as a moment.
+export function easternToMs(wall) {
+  const asUtc = Date.parse(`${wall.replace(" ", "T")}Z`);
+  for (const h of [4, 5]) if (easternOffsetMs(asUtc + h * HOUR) === h * HOUR) return asUtc + h * HOUR;
+  return asUtc + 5 * HOUR;
+}
+export function acceptedOnIndex(html) {
+  const m = String(html).match(/Accepted<\/div>\s*<div class="info">\s*(\d{4}-\d{2}-\d{2} \d{2}:\d{2})(:\d{2})?/);
+  return m ? `${m[1]}${m[2] ?? ":00"}` : null;
+}
+// The file's error in Eastern offsets (-1, 0 or 1) from one filing's true time, or NaN.
+export function fileShift(apiMs, trueMs) {
+  const d = apiMs - trueMs, off = easternOffsetMs(trueMs);
+  return d === 0 ? 0 : d === off ? 1 : d === -off ? -1 : NaN;
+}
+export function unshift(apiMs, shift) {
+  if (shift === 0) return apiMs;
+  for (const h of [4, 5]) if (easternOffsetMs(apiMs - shift * h * HOUR) === h * HOUR) return apiMs - shift * h * HOUR;
+  return null;
+}
+export async function acceptanceTimes(session, cik, sub, accessions) {
+  const r = sub.filings?.recent ?? {};
+  const api = new Map();
+  (r.accessionNumber ?? []).forEach((a, i) => { const ms = Date.parse(r.acceptanceDateTime?.[i] ?? ""); if (Number.isFinite(ms)) api.set(a, ms); });
+  const fromIndex = async (acc) => {
+    try {
+      const wall = acceptedOnIndex(await getText(session, `${archiveBase(cik, acc)}/${acc}-index.htm`, { maxBytes: 2 * 1024 * 1024 }));
+      return wall ? easternToMs(wall) : null;
+    } catch (err) { if (err instanceof NotFound) return null; throw err; }
+  };
+  const want = [...new Set(accessions)];
+  const inFile = want.filter((a) => api.has(a)).sort((x, y) => api.get(x) - api.get(y));
+  const times = new Map();
+  const shifts = [];
+  for (const acc of new Set([inFile.at(-1), inFile[0]].filter(Boolean))) {
+    const t = await fromIndex(acc);
+    if (t == null) continue;
+    times.set(acc, t);
+    shifts.push(fileShift(api.get(acc), t));
+  }
+  const shift = shifts.length && shifts.every((s) => s === shifts[0]) && !Number.isNaN(shifts[0]) ? shifts[0] : null;
+  await Promise.all(want.filter((a) => !times.has(a)).map(async (acc) => {
+    const t = shift != null && api.has(acc) ? unshift(api.get(acc), shift) : await fromIndex(acc);
+    if (t != null) times.set(acc, t);
+  }));
+  return { times, shift };
+}
+
 // Filings newest first: the recent block (at least a year, up to 1,000 filings), then older pages
 // only while they may hold filings on or after `since`.
 export async function filings(session, cik, { since } = {}) {