alphacouncil-agent 0.5.0

package/mcp/lib/run-store.mjs

@@ -0,0 +1,140 @@
+import { appendFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { DEBATE_ROLES, RUNS_DIR } from "./constants.mjs";
+import { invalidParams } from "./errors.mjs";
+import { readJson, writeJson } from "./fsutil.mjs";
+import { agentState, completenessStatus, sourceManifest, taskState, verificationStatus } from "./gates.mjs";
+
+export { agentState, taskState };
+
+export function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function runId(symbol) {
+  const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "Z");
+  return `${symbol.toUpperCase()}-${stamp}`;
+}
+
+export function safeSymbol(symbol) {
+  if (typeof symbol !== "string" || !/^[A-Za-z0-9.^=+\-]{1,32}$/.test(symbol)) {
+    throw invalidParams("symbol must be 1-32 chars and contain only ticker-safe characters.");
+  }
+  if (/^\.+$/.test(symbol)) throw invalidParams("symbol cannot be only dots.");
+  return symbol.toUpperCase();
+}
+
+export function runPath(id) {
+  if (typeof id !== "string" || !/^[A-Z0-9.^=+\-_]{1,80}$/.test(id)) {
+    throw invalidParams("run_id is invalid.");
+  }
+  return join(RUNS_DIR, id);
+}
+
+/**
+ * How much material the evidence agents actually found, counted by grade.
+ * A run that is mostly C is not necessarily wrong, but it is a different kind of report
+ * and the reader should be told before the conclusion, not after.
+ */
+export function richnessSummary(run) {
+  const counts = { A: 0, B: 0, C: 0, unrated: 0 };
+  for (const packet of run.packets || []) {
+    const grade = ["A", "B", "C"].includes(packet.information_richness) ? packet.information_richness : "unrated";
+    counts[grade] += 1;
+  }
+  return counts;
+}
+
+export function statusSnapshot(run) {
+  const gate = verificationStatus(run);
+  const completeness = completenessStatus(run);
+  return {
+    run_id: run.run_id,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    language: run.language,
+    execution_mode: run.execution_mode,
+    visibility_required: run.visibility_required,
+    dry_run: run.dry_run,
+    status: run.status,
+    phase: run.phase,
+    verification: gate.verification,
+    missing_source_count: gate.missing_claim_source_ids.length,
+    completeness: completeness.completeness,
+    missing_evidence_count: completeness.missing_evidence_count,
+    missing_debate_count: completeness.missing_debate_count,
+    information_richness: richnessSummary(run),
+    report_quality: run.report_quality?.status || "not_checked",
+    missing_report_items_count: run.report_quality?.missing?.length || 0,
+    started_at: run.started_at,
+    updated_at: run.updated_at,
+    completed_at: run.completed_at,
+    tasks: run.tasks.map((task) => taskState(run, task)),
+    agents: DEBATE_ROLES.map((role) => agentState(run, role)),
+  };
+}
+
+export function writeStatus(run, patch = {}) {
+  Object.assign(run, patch, { updated_at: new Date().toISOString() });
+  writeJson(join(runPath(run.run_id), "status.json"), statusSnapshot(run));
+}
+
+export function appendEvent(run, type, data = {}) {
+  appendFileSync(join(runPath(run.run_id), "events.jsonl"), `${JSON.stringify({
+    at: new Date().toISOString(),
+    type,
+    ...data,
+  })}\n`);
+}
+
+export function writeSourceManifest(run) {
+  writeJson(join(runPath(run.run_id), "source_manifest.json"), sourceManifest(run));
+}
+
+export function updateTask(run, task, status, patch = {}) {
+  run.task_status[task] = { ...taskState(run, task), ...patch, task, status, updated_at: new Date().toISOString() };
+  writeStatus(run);
+  appendEvent(run, `task_${status}`, { task, ...patch });
+}
+
+export function updateAgent(run, role, status, patch = {}) {
+  run.agent_status[role] = { ...agentState(run, role), ...patch, role, status, updated_at: new Date().toISOString() };
+  writeStatus(run);
+  appendEvent(run, `agent_${status}`, { role, ...patch });
+}
+
+export function artifactPaths(run) {
+  const dir = runPath(run.run_id);
+  const analyst_markdown = Object.fromEntries(
+    [...(run.tasks || []), ...DEBATE_ROLES].map((role) => [role, join(dir, `${role}.md`)])
+  );
+  return {
+    run_dir: dir,
+    final_report_md: join(dir, "final_report.md"),
+    user_response_md: join(dir, "user_response.md"),
+    artifact_index_md: join(dir, "artifact_index.md"),
+    all_agents_md: join(dir, "all_agents.md"),
+    evidence_json: join(dir, "evidence.json"),
+    source_manifest_json: join(dir, "source_manifest.json"),
+    status_json: join(dir, "status.json"),
+    events_jsonl: join(dir, "events.jsonl"),
+    report_quality_json: join(dir, "report_quality.json"),
+    decision_json: join(dir, "decision.json"),
+    analyst_markdown,
+  };
+}
+
+export function existingDebate(dir) {
+  return {
+    bull: existsSync(join(dir, "bull_researcher.json")) ? readJson(join(dir, "bull_researcher.json")) : null,
+    bear: existsSync(join(dir, "bear_researcher.json")) ? readJson(join(dir, "bear_researcher.json")) : null,
+    manager: existsSync(join(dir, "manager_synthesis.json")) ? readJson(join(dir, "manager_synthesis.json")) : null,
+  };
+}
+
+export function saveRun(run) {
+  writeJson(join(runPath(run.run_id), "evidence.json"), run);
+  writeSourceManifest(run);
+  writeStatus(run);
+}

package/mcp/lib/screen.mjs

@@ -0,0 +1,283 @@
+import { fetchUniverse, fetchCompanyFacts, annualSeries, CONCEPTS } from "./sec.mjs";
+import { invalidParams } from "./errors.mjs";
+
+/**
+ * Mechanical elimination screen. No language model is involved.
+ *
+ * This is the layer that makes stock-finding honest: an LLM asked to "recommend some
+ * stocks" returns the names most frequent in its training data attached to hallucinated
+ * figures. Here every rejection names the metric, the computed value and the threshold,
+ * so any verdict can be checked or argued with.
+ *
+ * The rules eliminate; they never select. Surviving is not a recommendation, it means
+ * "worth spending research time on".
+ */
+
+const pct = (x) => (x === null ? null : Number((x * 100).toFixed(2)));
+const last = (series, n) => series.slice(-n);
+const sum = (xs) => xs.reduce((a, b) => a + b, 0);
+
+function values(facts, key, asOf) {
+  const found = annualSeries(facts, CONCEPTS[key], { asOf });
+  return found ? found.series.map((e) => ({ end: e.end, filed: e.filed, val: e.val })) : [];
+}
+
+/**
+ * Seven elimination rules with three exemptions.
+ * Each returns { id, passed, value, threshold, reason } or { skipped } when the inputs
+ * are not available -- a missing input is never silently treated as a pass.
+ */
+export function evaluateRules(facts, { asOf = null } = {}) {
+  const revenue = values(facts, "revenue", asOf);
+  const netIncome = values(facts, "netIncome", asOf);
+  const grossProfit = values(facts, "grossProfit", asOf);
+  const operatingIncome = values(facts, "operatingIncome", asOf);
+  const ocf = values(facts, "operatingCashFlow", asOf);
+  const capex = values(facts, "capex", asOf);
+  const equity = values(facts, "equity", asOf);
+  const interest = values(facts, "interestExpense", asOf);
+  const shares = values(facts, "sharesOutstanding", asOf);
+
+  const rules = [];
+  const add = (id, label, compute) => {
+    try {
+      const result = compute();
+      rules.push(result === null ? { id, label, skipped: true, reason: "inputs unavailable in filings" } : { id, label, ...result });
+    } catch (error) {
+      rules.push({ id, label, skipped: true, reason: `could not compute: ${error.message}` });
+    }
+  };
+
+  add("roe_10y", { en: "10-year average ROE", zh: "10年平均ROE" }, () => {
+    const ni = last(netIncome, 10);
+    const eq = last(equity, 10);
+    if (ni.length < 5 || eq.length < 5) return null;
+    const n = Math.min(ni.length, eq.length);
+    const roes = [];
+    for (let i = 0; i < n; i += 1) {
+      const e = eq[eq.length - n + i].val;
+      if (e > 0) roes.push(ni[ni.length - n + i].val / e);
+    }
+    if (roes.length < 5) return null;
+    const avg = sum(roes) / roes.length;
+    return { passed: avg >= 0.08, value: pct(avg), unit: "%", threshold: 8, direction: "min", years: roes.length };
+  });
+
+  add("fcf_5y", { en: "5-year cumulative free cash flow", zh: "5年累计自由现金流" }, () => {
+    const o = last(ocf, 5);
+    const c = last(capex, 5);
+    if (o.length < 3 || c.length < 3) return null;
+    const n = Math.min(o.length, c.length);
+    const total = sum(o.slice(-n).map((x) => x.val)) - sum(c.slice(-n).map((x) => x.val));
+    // Raw dollars, not billions rounded to two places: rounding erased the entire figure
+    // for anything below ~$5m, which is most of the small-cap universe.
+    return { passed: total >= 0, value: Math.round(total), unit: "USD", threshold: 0, direction: "min", years: n };
+  });
+
+  add("interest_cover", { en: "EBIT / interest cover", zh: "利息保障倍数" }, () => {
+    const ebit = last(operatingIncome, 1)[0];
+    const int = last(interest, 1)[0];
+    if (!ebit || !int || int.val === 0) return null;
+    const cover = ebit.val / Math.abs(int.val);
+    return { passed: cover >= 2, value: Number(cover.toFixed(2)), unit: "x", threshold: 2, direction: "min" };
+  });
+
+  add("gross_margin", { en: "long-run gross margin", zh: "长期毛利率" }, () => {
+    const gp = last(grossProfit, 5);
+    const rev = last(revenue, 5);
+    if (gp.length < 3 || rev.length < 3) return null;
+    const n = Math.min(gp.length, rev.length);
+    const margins = [];
+    for (let i = 0; i < n; i += 1) {
+      const r = rev[rev.length - n + i].val;
+      if (r > 0) margins.push(gp[gp.length - n + i].val / r);
+    }
+    if (!margins.length) return null;
+    const avg = sum(margins) / margins.length;
+    return { passed: avg >= 0.15, value: pct(avg), unit: "%", threshold: 15, direction: "min", years: margins.length };
+  });
+
+  add("ocf_over_ni", { en: "5-year OCF / net income", zh: "5年经营现金流/净利" }, () => {
+    const o = last(ocf, 5);
+    const ni = last(netIncome, 5);
+    if (o.length < 3 || ni.length < 3) return null;
+    const n = Math.min(o.length, ni.length);
+    const totalNi = sum(ni.slice(-n).map((x) => x.val));
+    if (totalNi <= 0) return null;
+    const ratio = sum(o.slice(-n).map((x) => x.val)) / totalNi;
+    return { passed: ratio >= 0.7, value: Number(ratio.toFixed(2)), unit: "x", threshold: 0.7, direction: "min", years: n };
+  });
+
+  add("net_margin", { en: "long-run net margin", zh: "长期净利率" }, () => {
+    const ni = last(netIncome, 5);
+    const rev = last(revenue, 5);
+    if (ni.length < 3 || rev.length < 3) return null;
+    const n = Math.min(ni.length, rev.length);
+    const totalRev = sum(rev.slice(-n).map((x) => x.val));
+    if (totalRev <= 0) return null;
+    const margin = sum(ni.slice(-n).map((x) => x.val)) / totalRev;
+    return { passed: margin >= 0.05, value: pct(margin), unit: "%", threshold: 5, direction: "min", years: n };
+  });
+
+  add("dilution", { en: "5-year share dilution", zh: "5年股本稀释" }, () => {
+    const s = last(shares, 5);
+    if (s.length < 3) return null;
+    const first = s[0].val;
+    const latest = s[s.length - 1].val;
+    if (!(first > 0)) return null;
+    const change = latest / first - 1;
+    return { passed: change <= 0.20, value: pct(change), unit: "%", threshold: 20, direction: "max", years: s.length };
+  });
+
+  // Exemptions. These are the only legitimate way past a failed rule -- a good story is
+  // not, and the screen deliberately gives no mechanism for one.
+  const exemptions = [];
+  const rule = (id) => rules.find((r) => r.id === id);
+  const failed = (id) => rule(id) && rule(id).passed === false;
+
+  const gm = rule("gross_margin");
+  const historyYears = revenue.length;
+  if (failed("roe_10y") && historyYears < 10 && gm?.value > 30 && last(ocf, 2).every((x) => x.val > 0)) {
+    exemptions.push({
+      rule: "roe_10y",
+      reason: `listed under 10 years (${historyYears}y of filings) with gross margin ${gm.value}% and positive recent operating cash flow`,
+    });
+  }
+  if (failed("fcf_5y") && gm?.value > 50) {
+    exemptions.push({ rule: "fcf_5y", reason: `gross margin ${gm.value}% suggests reinvestment rather than an unprofitable model -- verify manually` });
+  }
+  if (failed("net_margin") && rule("ocf_over_ni") && rule("ocf_over_ni").value > 1.5) {
+    exemptions.push({ rule: "net_margin", reason: `OCF/NI of ${rule("ocf_over_ni").value}x indicates heavy non-cash charges depressing reported margin` });
+  }
+
+  const exempted = new Set(exemptions.map((e) => e.rule));
+  const failures = rules.filter((r) => r.passed === false && !exempted.has(r.id));
+  const skipped = rules.filter((r) => r.skipped);
+
+  return {
+    rules,
+    exemptions,
+    failures,
+    skipped_count: skipped.length,
+    verdict: failures.length === 0 ? "survives" : "eliminated",
+    // Data coverage is reported, never assumed: a company that failed nothing because
+    // nothing could be computed is not the same as one that passed.
+    evaluated_count: rules.length - skipped.length,
+  };
+}
+
+export function explainResult(result, ticker) {
+  const lines = [`${ticker}: ${result.verdict}`];
+  if (result.failures.length) {
+    lines.push("eliminated by:");
+    for (const f of result.failures) {
+      lines.push(`  - ${typeof f.label === "string" ? f.label : f.label.en}: measured ${f.value}${f.unit === "%" ? "%" : ` ${f.unit}`} against a threshold of ${f.threshold}${f.years ? ` over ${f.years}y` : ""}`);
+    }
+  }
+  if (result.exemptions.length) {
+    lines.push("exempted:");
+    for (const e of result.exemptions) lines.push(`  - ${e.rule}: ${e.reason}`);
+  }
+  if (result.skipped_count) {
+    lines.push(`${result.skipped_count} of ${result.rules.length} rules could not be computed from filings and were NOT treated as passes.`);
+  }
+  return lines.join("\n");
+}
+
+export async function screenTicker({ cik, ticker, asOf = null }) {
+  // The tool schema offers `ticker`, so callers pass one. Demanding a CIK anyway turned a
+  // documented argument into an error and made the caller go look up an identifier the
+  // universe file already holds -- the opposite of working without configuration.
+  let resolved = cik;
+  if (!resolved && ticker) {
+    const wanted = String(ticker).trim().toUpperCase();
+    const universe = await fetchUniverse();
+    const hit = universe.find((row) => String(row.ticker).toUpperCase() === wanted);
+    if (!hit) {
+      throw invalidParams(
+        `no US filer with ticker "${ticker}" in the SEC universe. `
+        + "Non-US listings are absent from it; supply a cik, or use market_coverage to see what this market supports.",
+      );
+    }
+    resolved = hit.cik;
+  }
+  if (!resolved) throw invalidParams("screenTicker needs a cik or a ticker");
+  const cikUsed = resolved;
+  const facts = await fetchCompanyFacts(cikUsed);
+  const result = evaluateRules(facts, { asOf });
+  return { ticker: ticker || facts.entityName, cik: cikUsed, resolved_from_ticker: !cik && Boolean(ticker), entity: facts.entityName, as_of: asOf, ...result };
+}
+
+
+/**
+ * Screen a list of candidates and report every elimination with its reason.
+ *
+ * Deliberately bounded rather than "screen the whole market": each company is one SEC
+ * request at ~120ms, so 10,000 filers is twenty minutes of requests SEC would rightly
+ * throttle. A funnel narrows first -- by industry, index, or a name list -- and this
+ * layer eliminates mechanically from what is handed to it.
+ */
+export async function screenBatch({ candidates = [], asOf = null, concurrency = 3 } = {}) {
+  if (!Array.isArray(candidates) || candidates.length === 0) {
+    throw invalidParams("screenBatch needs candidates: [{cik, ticker}]");
+  }
+  if (candidates.length > 40) {
+    throw invalidParams(`too many candidates (${candidates.length}). Narrow the funnel first -- SEC is one request per company and rate-limits. Cap is 40.`);
+  }
+
+  const results = [];
+  const queue = [...candidates];
+  const worker = async () => {
+    while (queue.length) {
+      const candidate = queue.shift();
+      try {
+        results.push(await screenTicker({ ...candidate, asOf }));
+      } catch (error) {
+        // A fetch failure is a data gap, never an elimination: silently dropping a name
+        // because SEC timed out would bias the survivors.
+        results.push({
+          ticker: candidate.ticker || candidate.cik,
+          cik: candidate.cik,
+          verdict: "unavailable",
+          error: String(error.message || error),
+        });
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(4, concurrency)) }, worker));
+
+  const survivors = results.filter((r) => r.verdict === "survives");
+  const eliminated = results.filter((r) => r.verdict === "eliminated");
+  const unavailable = results.filter((r) => r.verdict === "unavailable");
+
+  return {
+    as_of: asOf,
+    screened: results.length,
+    survivors: survivors.map((r) => ({
+      ticker: r.ticker,
+      cik: r.cik,
+      entity: r.entity,
+      rules_computed: r.evaluated_count,
+      rules_total: r.rules.length,
+      exemptions: r.exemptions,
+    })),
+    eliminated: eliminated.map((r) => ({
+      ticker: r.ticker,
+      cik: r.cik,
+      // The whole point: never "did not pass", always which metric at which value.
+      reasons: r.failures.map((f) => ({
+        rule: f.id,
+        label: f.label,
+        measured: f.value,
+        unit: f.unit,
+        threshold: f.threshold,
+        years: f.years,
+      })),
+    })),
+    unavailable: unavailable.map((r) => ({ ticker: r.ticker, cik: r.cik, error: r.error })),
+    disclaimer:
+      "Surviving is not a recommendation. These rules eliminate; they never select. A survivor is a name worth "
+      + "spending research time on, and the council still has to run. Rules whose inputs were missing from the "
+      + "filings were skipped rather than passed, so check rules_computed before treating a survivor as clean.",
+  };
+}

package/mcp/lib/sec.mjs

@@ -0,0 +1,131 @@
+import { LIMITS } from "./constants.mjs";
+import { invalidParams } from "./errors.mjs";
+
+/**
+ * Keyless SEC client.
+ *
+ * SEC requires a descriptive User-Agent with a contact and rate-limits to ~10 req/s.
+ * Everything here comes from filings, so a figure is what the company actually reported,
+ * not a vendor's adjusted version of it.
+ *
+ * The field that matters most is `filed`. A fiscal year ending 2024-09-28 was not public
+ * until 2024-11-01, so anything that reasons "as of" a date must filter on `filed`, not
+ * on the period end. Getting this wrong is the single easiest way to build a screen or a
+ * backtest that looks brilliant and is measuring the future.
+ */
+// SEC's User-Agent rules are stricter than the published guidance and were established
+// by testing, not by reading: it wants `Name/version (email)`, and it returns 403 with an
+// HTML body when the contact contains a URL or a domain it associates with crawlers --
+// including a github.com noreply address. Anyone running this at volume should set
+// ALPHACOUNCIL_SEC_USER_AGENT to a real contact of their own.
+const UA = process.env.ALPHACOUNCIL_SEC_USER_AGENT
+  || "AlphaCouncil-Agent/0.4 (alphacouncil@runbox.com)";
+
+const MIN_INTERVAL_MS = 120; // stay under SEC's ~10 req/s guidance
+let lastCall = 0;
+
+async function throttle() {
+  const wait = lastCall + MIN_INTERVAL_MS - Date.now();
+  if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+  lastCall = Date.now();
+}
+
+async function secJson(url, timeoutMs = LIMITS.QUOTE_FETCH_MS * 2) {
+  await throttle();
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: ctrl.signal,
+      headers: { "User-Agent": UA, Accept: "application/json" },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+    const text = await res.text();
+    if (text.trimStart().startsWith("<")) throw new Error(`SEC returned HTML rather than JSON for ${url} (rate limited or blocked)`);
+    return JSON.parse(text);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** The full US listed universe: ~10k entries of {cik, ticker, title}. */
+export async function fetchUniverse() {
+  const raw = await secJson("https://www.sec.gov/files/company_tickers.json");
+  return Object.values(raw).map((row) => ({
+    cik: String(row.cik_str).padStart(10, "0"),
+    ticker: row.ticker,
+    title: row.title,
+  }));
+}
+
+export async function fetchCompanyFacts(cik) {
+  const padded = String(cik).replace(/\D/g, "").padStart(10, "0");
+  if (padded.length !== 10) throw invalidParams(`invalid CIK: ${cik}`);
+  return secJson(`https://data.sec.gov/api/xbrl/companyfacts/CIK${padded}.json`);
+}
+
+/**
+ * Annual series for a concept, newest last, filtered to what was public by `asOf`.
+ *
+ * Tries several tags because the same economic quantity has different names depending on
+ * when and under which taxonomy a company filed.
+ */
+export function annualSeries(facts, tags, { asOf = null, unit = "USD" } = {}) {
+  const cutoff = asOf ? new Date(asOf).getTime() : null;
+  for (const tag of tags) {
+    const entries = facts?.facts?.["us-gaap"]?.[tag]?.units?.[unit];
+    if (!Array.isArray(entries) || entries.length === 0) continue;
+
+    const byPeriod = new Map();
+    for (const entry of entries) {
+      if (entry.form !== "10-K" || !entry.end || !Number.isFinite(entry.val)) continue;
+      // Look-ahead guard: a filing is only usable once it was actually filed.
+      if (cutoff && new Date(entry.filed).getTime() > cutoff) continue;
+      const prior = byPeriod.get(entry.end);
+      // Keep the most recently filed value for a period: restatements supersede.
+      if (!prior || new Date(entry.filed) > new Date(prior.filed)) byPeriod.set(entry.end, entry);
+    }
+    if (byPeriod.size === 0) continue;
+    const series = [...byPeriod.values()].sort((a, b) => new Date(a.end) - new Date(b.end));
+    return { tag, unit, series };
+  }
+  return null;
+}
+
+/** Concept aliases, ordered by preference. */
+export const CONCEPTS = {
+  revenue: [
+    "RevenueFromContractWithCustomerExcludingAssessedTax",
+    "Revenues",
+    "SalesRevenueNet",
+    "RevenueFromContractWithCustomerIncludingAssessedTax",
+  ],
+  netIncome: ["NetIncomeLoss", "ProfitLoss"],
+  grossProfit: ["GrossProfit"],
+  operatingIncome: ["OperatingIncomeLoss"],
+  operatingCashFlow: ["NetCashProvidedByUsedInOperatingActivities", "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations"],
+  capex: ["PaymentsToAcquirePropertyPlantAndEquipment", "PaymentsToAcquireProductiveAssets"],
+  equity: ["StockholdersEquity", "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"],
+  assets: ["Assets"],
+  interestExpense: ["InterestExpense", "InterestIncomeExpenseNet", "InterestExpenseDebt"],
+  sharesOutstanding: ["CommonStockSharesOutstanding", "WeightedAverageNumberOfDilutedSharesOutstanding"],
+};
+
+export const secUserAgent = () => UA;
+
+/** Company metadata including SIC industry classification. Keyless. */
+export async function fetchSubmissions(cik) {
+  const padded = String(cik).replace(/\D/g, "").padStart(10, "0");
+  if (padded.length !== 10) throw invalidParams(`invalid CIK: ${cik}`);
+  const data = await secJson(`https://data.sec.gov/submissions/CIK${padded}.json`);
+  return {
+    cik: padded,
+    name: data.name,
+    tickers: data.tickers || [],
+    exchanges: data.exchanges || [],
+    sic: data.sic || null,
+    sic_description: data.sicDescription || null,
+    state_of_incorporation: data.stateOfIncorporation || null,
+    fiscal_year_end: data.fiscalYearEnd || null,
+  };
+}