alphacouncil-agent 0.5.0

package/mcp/lib/gates.mjs

@@ -0,0 +1,208 @@
+import { DEBATE_ROLES, LIMITS, PLACEHOLDER_BODIES, REPORT_SECTIONS } from "./constants.mjs";
+import { denseLength, normalizeHeading, parseHeadings } from "./headings.mjs";
+import { isChineseLanguage } from "./lang.mjs";
+
+export function withDisclaimer(markdown, language) {
+  const text = typeof markdown === "string" ? markdown : "";
+  if (/##\s*(Disclaimer|免责声明)/i.test(text)) return text;
+  const note = isChineseLanguage(language)
+    ? "\n\n---\n\n## 免责声明\n\n本报告由 AI 自动生成,**仅供教育与研究**,**不构成投资建议**,不构成任何证券买卖推荐或要约。AI 分析可能不完整、过时或错误。投资决策前请自行核实并咨询持牌专业人士。作者不对任何损失承担责任。"
+    : "\n\n---\n\n## Disclaimer\n\nThis report is AI-generated for **educational and research purposes only**. It is **not investment advice**, not a recommendation to buy or sell any security, and not a solicitation. AI analysis can be incomplete, outdated, or wrong. Do your own research and consult a licensed professional before any investment decision. The authors accept no liability for any loss.";
+  return `${text}${note}`;
+}
+
+export function withVerificationBanner(markdown, gate, language) {
+  const text = typeof markdown === "string" ? markdown : "";
+  if (!gate || gate.verification !== "needs_verification") return text;
+  const pairs = gate.missing_claim_source_ids || [];
+  const lines = pairs.length
+    ? pairs.map((item) => `- ${item.task}: ${item.source_id}`).join("\n")
+    : "- (unspecified)";
+  const banner = isChineseLanguage(language)
+    ? `\n\n---\n\n## 来源核验 / Source Verification Gate\n\n**状态:needs_verification。** 以下重大论断引用了不存在的来源 ID,本次运行尚未通过来源核验:\n\n${lines}\n`
+    : `\n\n---\n\n## Source Verification Gate / 来源核验\n\n**Status: needs_verification.** The following material claims cite source IDs that are not present in any evidence packet; this run has NOT passed source verification:\n\n${lines}\n`;
+  return `${text}${banner}`;
+}
+
+export function scopedSourceId(task, id, index = 0) {
+  const raw = String(id || `S${index + 1}`).trim() || `S${index + 1}`;
+  return raw.includes(":") ? raw : `${task}:${raw}`;
+}
+
+export function sourceManifest(run) {
+  const sources = [];
+  const known = new Set();
+  for (const packet of run.packets || []) {
+    for (const source of packet.sources || []) {
+      if (!source?.id) continue;
+      known.add(source.id);
+      sources.push({ task: packet.task, ...source });
+    }
+  }
+  const missing_claim_source_ids = [];
+  for (const packet of run.packets || []) {
+    for (const claim of packet.claims || []) {
+      for (const id of claim.source_ids || []) {
+        if (!known.has(id)) missing_claim_source_ids.push({ task: packet.task, source_id: id });
+      }
+    }
+  }
+  return {
+    run_id: run.run_id,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    source_count: sources.length,
+    sources,
+    missing_claim_source_ids,
+  };
+}
+
+export function verificationStatus(run) {
+  const missing = sourceManifest(run).missing_claim_source_ids;
+  return {
+    verification: missing.length ? "needs_verification" : "passed",
+    missing_claim_source_ids: missing,
+  };
+}
+
+export function taskState(run, task) {
+  return run.task_status?.[task] || { task, status: "pending" };
+}
+
+export function agentState(run, role) {
+  return run.agent_status?.[role] || { role, status: "pending" };
+}
+
+export function completenessStatus(run) {
+  const tasks = Array.isArray(run.tasks) ? run.tasks : [];
+  const missing_evidence = tasks.filter((task) => taskState(run, task).status !== "completed");
+  // All three debate roles, including portfolio_manager. SKILL.md and the
+  // record_visible_decision tool description have always promised the PM is enforced;
+  // the gate only ever checked the two researchers, so a run that skipped the PM
+  // entirely could still report itself complete.
+  const missing_debate = DEBATE_ROLES.filter((role) => agentState(run, role).status !== "completed");
+  // A run that selected a master bench and recorded no opinions used to report itself
+  // complete. That let the most expensive stage be skipped silently while the report still
+  // read as a finished committee -- and a bench nobody consulted is worse than no bench,
+  // because the reader believes the verdict survived twenty-one lenses.
+  const selected = Array.isArray(run.masters) ? run.masters : [];
+  const recorded = new Set((run.master_opinions || []).map((o) => o.master));
+  const missing_masters = selected.filter((id) => !recorded.has(id));
+  const complete = missing_evidence.length === 0 && missing_debate.length === 0 && missing_masters.length === 0;
+  return {
+    completeness: complete ? "complete" : "incomplete",
+    missing_evidence,
+    missing_debate,
+    missing_masters,
+    missing_evidence_count: missing_evidence.length,
+    missing_debate_count: missing_debate.length,
+    missing_masters_count: missing_masters.length,
+  };
+}
+
+export function withCompletenessBanner(markdown, completeness, language) {
+  const text = typeof markdown === "string" ? markdown : "";
+  if (!completeness || completeness.completeness !== "incomplete") return text;
+  const ev = completeness.missing_evidence || [];
+  const db = completeness.missing_debate || [];
+  const ms = completeness.missing_masters || [];
+  const evLine = ev.length ? ev.map((task) => `- ${task}`).join("\n") : "- (none)";
+  const dbLine = db.length ? db.map((role) => `- ${role}`).join("\n") : "- (none)";
+  // Naming the skipped seats matters more than the flag: "incomplete" without a list
+  // invites the reader to assume it was something minor.
+  const msLine = ms.length ? ms.map((id) => `- ${id}`).join("\n") : "";
+  const banner = isChineseLanguage(language)
+    ? `> [!WARNING]\n## 流程未完成 / Incomplete Council Run\n\n**状态:incomplete。** 本次运行未跑完完整委员会流程,结论不可信。\n\n未完成的证据角色:\n${evLine}\n\n未完成的辩论角色:\n${dbLine}\n${msLine ? `\n未给出意见的大师席位:\n${msLine}\n` : ""}`
+    : `> [!WARNING]\n## Incomplete Council Run / 流程未完成\n\n**Status: incomplete.** This run did NOT execute the full council workflow; the conclusion is unreliable.\n\nMissing evidence roles:\n${evLine}\n\nMissing debate roles:\n${dbLine}\n${msLine ? `\nMaster seats that gave no opinion:\n${msLine}\n` : ""}`;
+  return `${banner}\n\n---\n\n${text}`;
+}
+
+/**
+ * Assign each heading to at most one required section, longest matching alias first.
+ *
+ * Without the longest-alias rule, "Quant Factor / Technical Risk View" would satisfy the
+ * risks section as well as the quant section, and a report could pass while genuinely
+ * having no risks section at all.
+ */
+function assignHeadings(headings) {
+  const assigned = new Map();
+  for (const heading of headings) {
+    const normalized = normalizeHeading(heading.title);
+    if (!normalized) continue;
+    let best = null;
+    for (const section of REPORT_SECTIONS) {
+      for (const alias of section.aliases) {
+        const needle = normalizeHeading(alias);
+        if (!needle || !normalized.includes(needle)) continue;
+        if (!best || needle.length > best.needleLength) {
+          best = { section, needleLength: needle.length };
+        }
+      }
+    }
+    if (!best) continue;
+    const existing = assigned.get(best.section.id);
+    // Keep the richest body when a report repeats a section.
+    if (!existing || denseLength(heading.body) > denseLength(existing.body)) {
+      assigned.set(best.section.id, heading);
+    }
+  }
+  return assigned;
+}
+
+const isPlaceholder = (body) => {
+  const compact = String(body || "").replace(/^[-*+]\s*/, "").trim().toLowerCase();
+  return PLACEHOLDER_BODIES.includes(compact);
+};
+
+export function validateFinalReport(markdown, run) {
+  const text = String(markdown || "");
+  const headings = parseHeadings(text);
+  const assigned = assignHeadings(headings);
+  const missing = [];
+  const sections = [];
+
+  for (const section of REPORT_SECTIONS) {
+    const heading = assigned.get(section.id);
+    if (!heading) {
+      missing.push(`missing section: ${section.id}`);
+      sections.push({ id: section.id, status: "missing" });
+      continue;
+    }
+    const bodyChars = denseLength(heading.body);
+    if (isPlaceholder(heading.body)) {
+      missing.push(`placeholder section: ${section.id} ("${heading.title}")`);
+      sections.push({ id: section.id, status: "placeholder", heading: heading.title, line: heading.line, body_chars: bodyChars });
+      continue;
+    }
+    if (bodyChars < section.min_body) {
+      missing.push(`section too thin: ${section.id} ("${heading.title}") has ${bodyChars} of ${section.min_body} required characters`);
+      sections.push({ id: section.id, status: "too_thin", heading: heading.title, line: heading.line, body_chars: bodyChars });
+      continue;
+    }
+    sections.push({ id: section.id, status: "ok", heading: heading.title, line: heading.line, body_chars: bodyChars });
+  }
+
+  // Scoped to the analyst work log body. The old check searched the whole document, so
+  // a task id appearing once in the source table satisfied "this analyst was reported".
+  const workLog = assigned.get("analyst_work_log");
+  const workLogBody = (workLog?.body || "").toLowerCase();
+  for (const task of run.tasks || []) {
+    if (!workLogBody.includes(String(task).toLowerCase())) {
+      missing.push(`missing analyst work log entry: ${task}`);
+    }
+  }
+
+  const sourceCount = (run.packets || []).reduce((sum, packet) => sum + (packet.sources?.length || 0), 0);
+  if (sourceCount > 0 && !/[a-z_]+:s\d+/i.test(text)) missing.push("missing scoped source IDs such as market_data:S1");
+  const minLength = run.dry_run ? LIMITS.REPORT_MIN_CHARS_DRY : LIMITS.REPORT_MIN_CHARS;
+  if (denseLength(text) < minLength) missing.push(`report too short: minimum ${minLength} non-space characters`);
+
+  return {
+    schema_version: 2,
+    status: missing.length ? "needs_revision" : "passed",
+    missing,
+    sections,
+    checked_at: new Date().toISOString(),
+    required_sections: REPORT_SECTIONS.map((section) => section.id),
+  };
+}

package/mcp/lib/grounding.mjs

@@ -0,0 +1,252 @@
+import { fetchQuote } from "./quotes.mjs";
+import { getMacroSnapshot } from "./macro.mjs";
+import { screenTicker } from "./screen.mjs";
+import { resolveIndustry, industryCoverage } from "./industry.mjs";
+import { fetchSubmissions, fetchUniverse } from "./sec.mjs";
+import { fetchMarketFinancials, coverageFor, marketFor } from "./markets.mjs";
+
+/**
+ * Hard facts, assembled before any analyst starts searching.
+ *
+ * The gap this closes: the tools already knew Micron's filed cash flow and the current
+ * 10-year yield, and the analysts did not. Each one went off and searched from nothing,
+ * free to report a number from a news summary that contradicts the filing without anyone
+ * noticing. Grounding puts the deterministic facts in the prompt first and changes what
+ * the search is FOR -- from producing numbers to explaining and challenging numbers that
+ * are already established.
+ *
+ * The discipline that makes this work rather than just adding context: a searched number
+ * never silently overwrites a filed one. A contradiction is reported as a contradiction.
+ */
+
+async function safely(label, fn) {
+  try {
+    return { ok: true, value: await fn() };
+  } catch (error) {
+    // A gap stays a visible gap. Grounding that silently omits a failed source would be
+    // worse than no grounding, because the prompt would look complete.
+    return { ok: false, error: `${label}: ${String(error?.message || error)}` };
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string} [options.symbol]   exchange ticker, for the quote
+ * @param {string} [options.cik]      SEC CIK, for filings and the screen
+ * @param {string} [options.industry] industry query, for the chain map
+ * @param {boolean} [options.macro]   include the macro snapshot
+ * @param {string} [options.asOf]     only use filings filed by this date
+ */
+export async function gatherGrounding({ symbol, cik, industry, macro = true, asOf = null } = {}) {
+  // Without this, a caller that has a ticker but not a CIK gets no filer profile and no
+  // mechanical screen -- the filings half of "established facts" disappears and nothing
+  // in the output says it was skipped.
+  if (!cik && symbol && marketFor(symbol)?.id === "US") {
+    cik = await fetchUniverse()
+      .then((rows) => rows.find((r) => String(r.ticker).toUpperCase() === String(symbol).toUpperCase())?.cik)
+      .catch(() => undefined);
+  }
+  const jobs = [];
+  const out = { as_of: asOf, gathered_at: new Date().toISOString(), unavailable: [] };
+
+  if (symbol) {
+    jobs.push(safely("quote", () => fetchQuote(symbol)).then((r) => {
+      if (r.ok && !r.value?.error) out.quote = r.value;
+      else out.unavailable.push(r.ok ? `quote: ${r.value.error}` : r.error);
+    }));
+  }
+
+  if (cik) {
+    jobs.push(safely("filer profile", () => fetchSubmissions(cik)).then((r) => {
+      if (r.ok) out.filer = r.value;
+      else out.unavailable.push(r.error);
+    }));
+    jobs.push(safely("screen", () => screenTicker({ cik, ticker: symbol, asOf })).then((r) => {
+      if (!r.ok) { out.unavailable.push(r.error); return; }
+      const s = r.value;
+      out.screen = {
+        verdict: s.verdict,
+        rules_computed: s.evaluated_count,
+        rules_total: s.rules.length,
+        // Only the computed rules: a skipped rule is not a fact about the company.
+        metrics: s.rules.filter((x) => !x.skipped).map((x) => ({
+          rule: x.id, label: x.label, value: x.value, unit: x.unit, threshold: x.threshold, direction: x.direction, passed: x.passed,
+        })),
+        failures: s.failures.map((f) => ({ rule: f.id, value: f.value, unit: f.unit, threshold: f.threshold })),
+        exemptions: s.exemptions,
+        skipped: s.rules.filter((x) => x.skipped).map((x) => ({ rule: x.id, label: x.label })),
+      };
+    }));
+  }
+
+  if (macro) {
+    jobs.push(safely("macro", () => getMacroSnapshot({ blocks: ["rates", "dollar_liquidity", "commodities"] })).then((r) => {
+      if (!r.ok) { out.unavailable.push(r.error); return; }
+      out.macro = {
+        derived: r.value.derived.filter((d) => d.available).map((d) => ({ id: d.id, label: d.label, value: d.value })),
+        unavailable: r.value.unavailable,
+      };
+    }));
+  }
+
+  // Non-US symbols never reach the SEC path, so without this they arrived at the analyst
+  // with nothing but a price.
+  if (symbol && marketFor(symbol)?.id !== "US") {
+    jobs.push(safely("market financials", () => fetchMarketFinancials(symbol)).then((r) => {
+      if (!r.ok) { out.unavailable.push(r.error); return; }
+      out.market = r.value;
+      if (!r.value.financials) out.unavailable.push(`structured financials for ${symbol}: ${r.value.guidance}`);
+    }));
+  }
+
+  if (industry) {
+    const curated = resolveIndustry(industry);
+    out.industry = {
+      query: industry,
+      coverage: industryCoverage(industry),
+      ...(curated
+        ? {
+          id: curated.id,
+          title: curated.title,
+          participants: curated.layers.flatMap((l) => l.participants.map((p) => ({ ...p, layer: l.layer }))),
+          demand_drivers: curated.demand_drivers,
+          key_questions: curated.key_questions,
+          cyclicality: curated.cyclicality,
+        }
+        : {}),
+    };
+  }
+
+  await Promise.all(jobs);
+
+  // Coverage across every symbol in play, so a report cannot quietly become US-only.
+  const inPlay = [symbol, ...(out.industry?.participants || []).map((p) => p.symbol)].filter(Boolean);
+  if (inPlay.length) out.coverage = coverageFor([...new Set(inPlay)]);
+  return out;
+}
+
+const fmt = (value, unit) => {
+  if (value === null || value === undefined) return "n/a";
+  if (unit === "%") return `${value}%`;
+  if (unit === "USD") return Math.abs(value) >= 1e9 ? `$${(value / 1e9).toFixed(2)}bn` : `$${value.toLocaleString("en-US")}`;
+  return unit ? `${value} ${unit}` : String(value);
+};
+
+/**
+ * Render grounding as a prompt block.
+ *
+ * The instructions are the substance here. Facts alone would just be more context for a
+ * model to paraphrase; what changes behaviour is telling it what these facts are FOR and
+ * what it may not do with them.
+ */
+/**
+ * A skipped rule arrives either as a bare id or as {rule, label}. Handling only the object
+ * form silently rendered an empty list -- which reads as "nothing was skipped", the exact
+ * opposite of what the line exists to say.
+ */
+const skippedName = (entry, chinese) =>
+  (typeof entry === "string" ? entry : localized(entry?.label, chinese) || entry?.rule) || String(entry ?? "");
+
+/** Render a bilingual label. Every {en, zh} value must pass through here before display. */
+const localized = (label, chinese) => {
+  if (label == null) return "";
+  if (typeof label === "string") return label;
+  return (chinese ? label.zh : label.en) ?? label.en ?? label.zh ?? "";
+};
+
+export function groundingBlock(grounding, language = "English") {
+  const chinese = /中文|chinese|zh/i.test(String(language));
+  if (!grounding || (!grounding.quote && !grounding.screen && !grounding.macro && !grounding.industry)) return "";
+
+  const lines = [];
+  const head = chinese
+    ? "## 已确立的事实（来自申报原文与交易所数据，不是你的记忆）"
+    : "## Established facts (from filings and exchange data, not from your memory)";
+  lines.push(head);
+
+  if (grounding.filer) {
+    lines.push(chinese
+      ? `- 主体：${grounding.filer.name}｜SIC ${grounding.filer.sic ?? "未知"}（${grounding.filer.sic_description ?? "-"}）｜交易所 ${grounding.filer.exchanges.join(", ") || "未知"}`
+      : `- Filer: ${grounding.filer.name} | SIC ${grounding.filer.sic ?? "unknown"} (${grounding.filer.sic_description ?? "-"}) | exchange ${grounding.filer.exchanges.join(", ") || "unknown"}`);
+  }
+  if (grounding.quote) {
+    const q = grounding.quote;
+    lines.push(chinese
+      ? `- 行情（延迟约15分钟，${q.source}）：${q.symbol} ${q.price}${q.currency ? " " + q.currency : ""}${q.change_pct != null ? `，${q.change_pct > 0 ? "+" : ""}${q.change_pct}%` : ""}`
+      : `- Quote (~15m delayed, ${q.source}): ${q.symbol} ${q.price}${q.currency ? " " + q.currency : ""}${q.change_pct != null ? `, ${q.change_pct > 0 ? "+" : ""}${q.change_pct}%` : ""}`);
+  }
+  if (grounding.screen) {
+    const s = grounding.screen;
+    lines.push(chinese
+      ? `- 硬指标筛选：${s.verdict === "survives" ? "通过" : "淘汰"}（${s.rules_computed}/${s.rules_total} 条可算）`
+      : `- Mechanical screen: ${s.verdict} (${s.rules_computed} of ${s.rules_total} rules computable)`);
+    for (const m of s.metrics) {
+      lines.push(`  - ${localized(m.label, chinese)}: ${fmt(m.value, m.unit)} (${m.direction === "max" ? "max" : "min"} ${m.threshold}) ${m.passed ? "pass" : "FAIL"}`);
+    }
+    if (s.skipped.length) {
+      lines.push(chinese
+        ? `  - 无法从申报计算，未按通过处理：${s.skipped.map((x) => skippedName(x, chinese)).join("、")}`
+        : `  - Not computable from filings and NOT treated as passes: ${s.skipped.map((x) => skippedName(x, chinese)).join(", ")}`);
+    }
+  }
+  if (grounding.macro?.derived?.length) {
+    lines.push(chinese ? "- 宏观读数：" : "- Macro readings:");
+    // Derived labels are {en, zh}; interpolating the object printed "[object Object]"
+    // next to a real number, which reads as a broken field rather than a missing one.
+    for (const d of grounding.macro.derived) {
+      const name = localized(d.label, chinese) || d.id;
+      lines.push(`  - ${name}: ${d.value}`);
+    }
+  }
+  if (grounding.market?.financials) {
+    const f = grounding.market.financials;
+    lines.push(chinese
+      ? `- ${f.source} 申报（${f.gregorian_year ?? f.period.year}Q${f.period.quarter}，${f.currency} ${f.unit}）：营收 ${f.revenue?.toLocaleString() ?? "n/a"}｜毛利 ${f.gross_profit?.toLocaleString() ?? "n/a"}｜营业利益 ${f.operating_income?.toLocaleString() ?? "n/a"}｜EPS ${f.eps ?? "n/a"}`
+      : `- ${f.source} filing (${f.gregorian_year ?? f.period.year}Q${f.period.quarter}, ${f.currency} ${f.unit}): revenue ${f.revenue?.toLocaleString() ?? "n/a"} | gross profit ${f.gross_profit?.toLocaleString() ?? "n/a"} | operating income ${f.operating_income?.toLocaleString() ?? "n/a"} | EPS ${f.eps ?? "n/a"}`);
+  }
+  if (grounding.coverage?.rows?.length) {
+    const none = grounding.coverage.rows.filter((r) => r.structured_financials === "no").map((r) => r.symbol);
+    if (none.length) {
+      lines.push(chinese
+        ? `- 以下标的没有结构化财务源，任何关于它们的财务数字必须来自你读到的原始文件并注明出处：${none.join("、")}`
+        : `- No structured financial feed for: ${none.join(", ")}. Any financial figure for these must come from a primary document you actually read, and be cited as such.`);
+    }
+  }
+  if (grounding.industry?.participants?.length) {
+    const names = grounding.industry.participants.map((p) => `${p.name}${p.symbol ? ` (${p.symbol})` : " (unlisted)"}`);
+    lines.push(chinese
+      ? `- 产业链参与者（含非美，名单为人工维护）：${names.join("、")}`
+      : `- Value-chain participants (includes non-US; list is hand-maintained): ${names.join(", ")}`);
+  }
+  if (grounding.unavailable?.length) {
+    lines.push(chinese ? `- 取不到的数据（属于数据缺口，禁止用记忆补）：${grounding.unavailable.join("；")}`
+      : `- Could not be retrieved -- these are data gaps and must NOT be filled from memory: ${grounding.unavailable.join("; ")}`);
+  }
+
+  lines.push("");
+  lines.push(chinese
+    ? [
+      "**这些事实改变你搜索的目的。** 它们已经确立，不需要你再去找一遍。你联网搜索是为了：",
+      "1. **解释**这些数字为什么是这样——是什么业务变化导致的？",
+      "2. **补上**它们没覆盖的：最新一季、指引、管理层表态、竞争与监管动向、非美同业。",
+      "3. **挑战**它们：有没有公开信息说明这些数字会在下一期发生方向性变化？",
+      "",
+      "铁律：",
+      "- **搜到的数字不得覆盖申报数字。** 两者冲突时，两个都写出来、都给来源、明确指出这是冲突，并说明可能的口径差异（期间、GAAP/non-GAAP、币种、是否含一次性项）。让读者看到分歧，不要替读者选。",
+      "- 上面标为「无法计算」或「取不到」的，是真实的数据缺口。写进 open_questions，不要用你的背景知识填。",
+      "- 引用上面的事实时注明来自申报/交易所，与你搜到的来源分开标注。",
+    ].join("\n")
+    : [
+      "**These facts change what your search is for.** They are already established; do not go and re-find them. Search in order to:",
+      "1. **Explain** why the numbers look like this -- what change in the business produced them?",
+      "2. **Extend** what they do not cover: the latest quarter, guidance, management commentary, competitive and regulatory developments, non-US peers.",
+      "3. **Challenge** them: is there public information indicating these figures change direction next period?",
+      "",
+      "Hard rules:",
+      "- **A searched number never overwrites a filed number.** Where they conflict, report BOTH with their sources, say plainly that they conflict, and identify the likely reason (different period, GAAP vs non-GAAP, currency, inclusion of one-off items). Show the reader the disagreement rather than resolving it for them.",
+      "- Anything marked not computable or not retrieved above is a genuine data gap. Put it in open_questions; do not fill it from background knowledge.",
+      "- When you cite a fact from above, mark it as filing or exchange data, distinct from sources you found by searching.",
+    ].join("\n"));
+
+  return lines.join("\n");
+}

package/mcp/lib/headings.mjs

@@ -0,0 +1,65 @@
+/**
+ * Minimal Markdown heading parser.
+ *
+ * The report quality gate used to lowercase the whole document and ask
+ * `haystack.includes("risk")`, so any report that happened to contain the word "risk"
+ * anywhere passed the "Risks section" check. Structure has to be parsed to be checked.
+ */
+
+const ATX = /^(#{1,6})\s+(.*?)\s*#*\s*$/;
+const FENCE = /^(\s*)(```|~~~)/;
+
+/**
+ * @returns {{level:number,title:string,body:string,line:number}[]}
+ * `body` runs from just after the heading to the next heading of the same or higher
+ * level (i.e. a subsection stays inside its parent's body).
+ */
+export function parseHeadings(markdown) {
+  const lines = String(markdown || "").split(/\r?\n/);
+  const found = [];
+  let fence = null;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    const fenceMatch = FENCE.exec(line);
+    if (fenceMatch) {
+      const marker = fenceMatch[2];
+      if (fence === null) fence = marker;
+      else if (fence === marker) fence = null;
+      continue;
+    }
+    if (fence !== null) continue; // A '#' inside a code fence is not a heading.
+    const match = ATX.exec(line);
+    if (!match || !match[2]) continue;
+    found.push({ level: match[1].length, title: match[2], line: i + 1, start: i + 1 });
+  }
+
+  return found.map((heading, index) => {
+    let end = lines.length;
+    for (let j = index + 1; j < found.length; j += 1) {
+      if (found[j].level <= heading.level) {
+        end = found[j].start - 1;
+        break;
+      }
+    }
+    const { start, ...rest } = heading;
+    return { ...rest, body: lines.slice(start, end).join("\n").trim() };
+  });
+}
+
+/**
+ * Fold a heading or alias into a comparable form: lowercase, punctuation and digits
+ * collapsed to spaces, CJK left intact (CJK has no word boundaries to preserve).
+ */
+export function normalizeHeading(text) {
+  return String(text || "")
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}]+/gu, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Non-whitespace character count, the only length measure that survives CJK. */
+export function denseLength(text) {
+  return String(text || "").replace(/\s+/g, "").length;
+}