alphacouncil-agent 0.9.2 → 1.0.0

package/mcp/lib/gates.mjs

@@ -1,13 +1,17 @@
-import { DEBATE_ROLES, LIMITS, PLACEHOLDER_BODIES, QUICK_REPORT_SECTIONS, REPORT_SECTIONS } from "./constants.mjs";
+import { DEBATE_ROLES, LIMITS, PLACEHOLDER_BODIES, QUICK_REPORT_SECTIONS, RECORDED_BENCH_MARKER_PREFIX, REPORT_SECTIONS } from "./constants.mjs";
+import { isFundOrIndex } from "./instruments.mjs";
 import { denseLength, headingIncludesAlias, normalizeHeading, parseHeadings } from "./headings.mjs";
-import { isChineseLanguage } from "./lang.mjs";
+import { isChineseLanguage, languageKey, readerLanguageStatus } 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.";
+  if (/##\s*(Disclaimer|免责声明|免責事項|면책)/iu.test(text)) return text;
+  const note = {
+    zh: "\n\n---\n\n## 免责声明\n\n本报告由 AI 自动生成，**仅供教育与研究**，**不构成投资建议**，也不构成任何证券买卖推荐或要约。AI 分析可能不完整、过时或错误。投资决策前请自行核实并咨询持牌专业人士。作者不对任何损失承担责任。",
+    en: "\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.",
+    ja: "\n\n---\n\n## 免責事項\n\n本レポートは AI が生成した**教育・調査目的のみ**の資料で、**投資助言ではありません**。証券の売買推奨や勧誘でもありません。AI の分析は不完全、古い、または誤っている可能性があります。投資判断の前にご自身で確認し、資格を有する専門家へ相談してください。作成者は損失について責任を負いません。",
+    ko: "\n\n---\n\n## 면책 조항\n\n이 보고서는 AI가 생성한 **교육 및 연구 목적의 자료**이며 **투자 조언이 아닙니다**. 증권 매매 권유나 청약도 아닙니다. AI 분석은 불완전하거나 오래되었거나 틀릴 수 있습니다. 투자 결정 전에 직접 확인하고 자격을 갖춘 전문가와 상의하십시오. 작성자는 손실에 대해 책임을 지지 않습니다.",
+  }[languageKey(language)];
   return `${text}${note}`;
 }
 
@@ -18,9 +22,12 @@ export function withVerificationBanner(markdown, gate, language) {
   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`;
+  const banner = {
+    zh: `\n\n---\n\n## 来源核验\n\n**状态：needs_verification。** 以下重大论断引用了证据包中不存在的来源 ID；本轮尚未通过来源核验：\n\n${lines}\n`,
+    en: `\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`,
+    ja: `\n\n---\n\n## 出典検証ゲート\n\n**状態：needs_verification。** 次の重要な主張は証拠パケットに存在しない出典 ID を参照しています。この実行は出典検証を通過していません：\n\n${lines}\n`,
+    ko: `\n\n---\n\n## 출처 검증 게이트\n\n**상태: needs_verification.** 다음 중요 주장은 증거 패킷에 없는 출처 ID를 참조합니다. 이 실행은 출처 검증을 통과하지 못했습니다:\n\n${lines}\n`,
+  }[languageKey(language)];
   return `${text}${banner}`;
 }
 
@@ -80,6 +87,27 @@ export function agentState(run, role) {
   return run.agent_status?.[role] || { role, status: "pending" };
 }
 
+/**
+ * One definition of "this seat still owes the run something", used by every caller.
+ *
+ * The status snapshot and the completeness gate used to read a missing `master_status` entry
+ * as "fine" while the debate and PM gates read the same absence as "missing". A run recovered
+ * through the idempotent plan path could therefore report `complete` with no pending seats
+ * and still be hard-rejected at `record_visible_decision` naming exactly those seats -- an
+ * unrecoverable state behind a status display that said nothing was wrong.
+ *
+ * The shared reading resolves it toward unblocking: a seat that is genuinely waiting always
+ * has a `waiting` entry, because every write path that records an opinion also writes the
+ * status. A missing entry therefore only occurs on a run persisted before that invariant
+ * existed, and treating that as a hard block would strand the run with no way forward.
+ */
+export function masterSeatIncomplete(run, id) {
+  const recorded = (run?.master_opinions || []).some((opinion) => opinion?.master === id);
+  if (!recorded) return true;
+  const state = run?.master_status?.[id];
+  return Boolean(state) && state.status !== "completed";
+}
+
 export function completenessStatus(run) {
   const tasks = Array.isArray(run.tasks) ? run.tasks : [];
   const quick = run.council_mode === "quick";
@@ -109,8 +137,7 @@ export function completenessStatus(run) {
   // 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 missing_masters = selected.filter((id) => masterSeatIncomplete(run, id));
   const complete = missing_evidence.length === 0 && missing_debate.length === 0 && missing_masters.length === 0;
   return {
     completeness: complete ? "complete" : "incomplete",
@@ -139,9 +166,12 @@ export function withCompletenessBanner(markdown, completeness, language) {
   // 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` : ""}`;
+  const banner = {
+    zh: `> [!WARNING]\n## 委员会流程未完成\n\n**状态：incomplete。** 本轮没有完成全部委员会流程，结论不可靠。\n\n未完成的证据席：\n${evLine}\n\n未完成的辩论席：\n${dbLine}\n${msLine ? `\n未给出意见的方法席：\n${msLine}\n` : ""}`,
+    en: `> [!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 ? `\nMethod seats that gave no opinion:\n${msLine}\n` : ""}`,
+    ja: `> [!WARNING]\n## 委員会プロセス未完了\n\n**状態：incomplete。** 委員会の全工程を完了していないため、結論は信頼できません。\n\n未完了の証拠席：\n${evLine}\n\n未完了の討論席：\n${dbLine}\n${msLine ? `\n意見を記録できなかったメソッド席：\n${msLine}\n` : ""}`,
+    ko: `> [!WARNING]\n## 위원회 실행 미완료\n\n**상태: incomplete.** 전체 위원회 절차가 완료되지 않아 결론을 신뢰할 수 없습니다.\n\n미완료 증거 좌석:\n${evLine}\n\n미완료 토론 좌석:\n${dbLine}\n${msLine ? `\n의견을 기록하지 못한 방법론 좌석:\n${msLine}\n` : ""}`,
+  }[languageKey(language)];
   return `${banner}\n\n---\n\n${text}`;
 }
 
@@ -182,6 +212,54 @@ const isPlaceholder = (body) => {
   return PLACEHOLDER_BODIES.includes(compact);
 };
 
+const LANGUAGE_CORE_SECTIONS = new Set([
+  "conclusion", "analyst_work_log", "debate_record", "master_bench", "market_expectations",
+  "earnings_call", "news", "valuation", "price_levels", "risks", "position", "data_gaps",
+  "invalidation",
+]);
+
+function readerLanguageAudit(assigned, language) {
+  const requested = languageKey(language);
+  const mismatched = [];
+  let targetCharacters = 0;
+  let observedCharacters = 0;
+  const bodies = [];
+  for (const id of LANGUAGE_CORE_SECTIONS) {
+    const heading = assigned.get(id);
+    const body = heading?.body || "";
+    if (!body.trim()) continue;
+    bodies.push(body);
+    const section = readerLanguageStatus(body, language, { minimumTargetCharacters: 2, minimumRatio: 0.05 });
+    targetCharacters += section.target_characters;
+    observedCharacters += section.reader_characters;
+    // Pure Han fragments are inconclusive across Chinese/Japanese. Let the whole
+    // report establish the locale, but reject sections with positive other-language
+    // evidence so one translated heading cannot hide a foreign-language body.
+    if (![requested, "shared_han", "undetermined"].includes(section.observed_locale)) mismatched.push(id);
+
+    const titleProbe = readerLanguageStatus(heading?.title || "", language, { minimumTargetCharacters: 1, minimumRatio: 0 });
+    const { scripts = {} } = titleProbe;
+    let titleLocale = "undetermined";
+    if ((scripts.hangul || 0) > 0) titleLocale = "ko";
+    else if ((scripts.kana || 0) > 0 || (titleProbe.japanese_markers || 0) > 0) titleLocale = "ja";
+    else if ((titleProbe.chinese_markers || 0) > 0) titleLocale = "zh";
+    else if ((scripts.latin || 0) > 0 && (scripts.han || 0) === 0) titleLocale = "en";
+    else if ((scripts.han || 0) > 0) titleLocale = "shared_han";
+    const sharedHanAllowed = titleLocale === "shared_han" && ["zh", "ja"].includes(requested);
+    if (![requested, "undetermined"].includes(titleLocale) && !sharedHanAllowed) mismatched.push(`heading:${id}`);
+  }
+  const whole = readerLanguageStatus(bodies.join("\n"), language, { minimumTargetCharacters: 12, minimumRatio: 0.08 });
+  const languageStatus = mismatched.length || whole.status !== "passed" ? "failed" : "passed";
+  return {
+    requested_locale: requested,
+    observed_locale: whole.observed_locale,
+    language_status: languageStatus,
+    target_script_characters: whole.target_characters || targetCharacters,
+    reader_characters_checked: observedCharacters,
+    mismatched_sections: mismatched,
+  };
+}
+
 export function validateFinalReport(markdown, run) {
   const text = String(markdown || "");
   const headings = parseHeadings(text);
@@ -192,8 +270,10 @@ export function validateFinalReport(markdown, run) {
   const contractSections = quick ? QUICK_REPORT_SECTIONS : REPORT_SECTIONS;
 
   const benchRan = ((run?.masters || []).length > 0) || ((run?.master_opinions || []).length > 0);
+  const fundOrIndex = isFundOrIndex(run?.grounding?.instrument);
   for (const section of contractSections) {
     if (section.when_masters && !benchRan) continue;
+    if (section.when_fund_or_index && !fundOrIndex) continue;
     const heading = assigned.get(section.id);
     if (!heading) {
       missing.push(`missing section: ${section.id}`);
@@ -224,6 +304,36 @@ export function validateFinalReport(markdown, run) {
     }
   }
 
+  // A bench heading is not evidence that every selected method is readable. The previous
+  // gate passed a report containing only a generic bench paragraph even when twenty-five
+  // selected seats had no statement at all. Require both the frozen record and its exact
+  // stable ID in the system-owned publication section.
+  const selectedMethodSeats = [...new Set(
+    (run?.masters?.length ? run.masters : (run?.master_opinions || []).map((opinion) => opinion.master))
+      .filter((id) => typeof id === "string" && id.length),
+  )];
+  const opinionsByMaster = new Map((run?.master_opinions || []).map((opinion) => [opinion.master, opinion]));
+  // Anchor, not heading assignment. A relabelled PM commentary section can legally contain a
+  // localized bench alias, and it would then win the "richest body" assignment and fail every
+  // seat here against PM prose. The marker only ever appears in the system-generated bench,
+  // which assembly appends last, so everything from it onwards is system-owned output.
+  const benchMarkerAt = text.indexOf(`<!-- ${RECORDED_BENCH_MARKER_PREFIX}`);
+  const benchBody = benchMarkerAt >= 0 ? text.slice(benchMarkerAt) : (assigned.get("master_bench")?.body || "");
+  const readableMethodStatements = [];
+  const renderedMethodStatements = [];
+  for (const id of selectedMethodSeats) {
+    const opinion = opinionsByMaster.get(id);
+    if (!opinion) {
+      missing.push(`missing recorded method-seat opinion: ${id}`);
+    } else if (denseLength(opinion.voice_statement) < 20) {
+      missing.push(`missing readable method-seat statement: ${id}`);
+    } else {
+      readableMethodStatements.push(id);
+    }
+    if (!benchBody.includes(id)) missing.push(`method-seat statement not rendered in Master Bench: ${id}`);
+    else renderedMethodStatements.push(id);
+  }
+
   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
@@ -231,6 +341,10 @@ export function validateFinalReport(markdown, run) {
     : quick ? LIMITS.REPORT_MIN_CHARS_QUICK : LIMITS.REPORT_MIN_CHARS;
   if (denseLength(text) < minLength) missing.push(`report too short: minimum ${minLength} non-space characters`);
   const execution = completenessStatus(run || {});
+  const languageAudit = readerLanguageAudit(assigned, run?.language);
+  if (languageAudit.language_status !== "passed") {
+    missing.push(`report reader language mismatch: requested=${languageAudit.requested_locale}; sections=${languageAudit.mismatched_sections.join(",") || "insufficient target-language text"}`);
+  }
   if (quick) {
     const markerCount = (text.match(/alphacouncil:quick-scope:v1:begin/gu) || []).length;
     if (markerCount !== 1) missing.push("missing system-owned quick_v1 scope marker");
@@ -263,10 +377,30 @@ export function validateFinalReport(markdown, run) {
     evidence_coverage: execution.evidence_coverage,
     degraded_evidence: execution.degraded_evidence,
     degraded_debate: execution.degraded_debate,
+    requested_locale: languageAudit.requested_locale,
+    observed_locale: languageAudit.observed_locale,
+    language_status: languageAudit.language_status,
+    language_mismatched_sections: languageAudit.mismatched_sections,
+    target_script_characters: languageAudit.target_script_characters,
+    reader_characters_checked: languageAudit.reader_characters_checked,
+    method_statement_coverage: {
+      selected_count: selectedMethodSeats.length,
+      readable_count: readableMethodStatements.length,
+      rendered_count: renderedMethodStatements.length,
+      readable_master_ids: readableMethodStatements,
+      rendered_master_ids: renderedMethodStatements,
+      status: readableMethodStatements.length === selectedMethodSeats.length
+        && renderedMethodStatements.length === selectedMethodSeats.length
+        ? "passed"
+        : "failed",
+    },
     status: missing.length ? "needs_revision" : "passed",
     missing,
     sections,
     checked_at: new Date().toISOString(),
-    required_sections: contractSections.filter((s) => !s.when_masters || benchRan).map((section) => section.id),
+    required_sections: contractSections
+      .filter((section) => (!section.when_masters || benchRan)
+        && (!section.when_fund_or_index || fundOrIndex))
+      .map((section) => section.id),
   };
 }

package/mcp/lib/grounding.mjs

@@ -1,6 +1,10 @@
 import { fetchQuote } from "./quotes.mjs";
 import { invalidParams } from "./errors.mjs";
 import { getMacroSnapshot } from "./macro.mjs";
+import { fetchMacroSeries } from "./fred.mjs";
+import { fetchFundamentals } from "./fundamentals.mjs";
+import { fetchInsiderOwnership } from "./insider-ownership.mjs";
+import { gatherInstrumentFacts, LOOK_THROUGH_FACT_IDS } from "./instrument-facts.mjs";
 import { fetchOptionsChain } from "./options.mjs";
 import { screenTicker } from "./screen.mjs";
 import { resolveIndustry, industryCoverage } from "./industry.mjs";
@@ -8,6 +12,9 @@ import { fetchSubmissions, fetchUniverse } from "./sec.mjs";
 import { fetchMarketFinancials, coverageFor, marketFor } from "./markets.mjs";
 import { inclusiveCutoffTime } from "./personas-v3/source-anchor.mjs";
 import { adaptGroundingToTypedFacts } from "./personas-v3/grounding-adapter.mjs";
+import { classifyInstrument, instrumentResearchChecklist, isFundOrIndex } from "./instruments.mjs";
+// Aliased: this module already has a private `localized(label, chinese)` for metric labels.
+import { localized as localizedText } from "./lang.mjs";
 
 const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/u;
 
@@ -78,6 +85,7 @@ export async function gatherGrounding({
   options = true,
   asOf = null,
   now = new Date(),
+  language = "English",
   signal,
 } = {}) {
   const snapshotPolicy = liveSnapshotPolicy(asOf, { now });
@@ -87,53 +95,131 @@ export async function gatherGrounding({
     gathered_at: gatheredAt,
     point_in_time_policy: snapshotPolicy,
     unavailable: [],
+    not_applicable: [],
   };
-  // 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.
-  // The current ticker universe is itself time-varying. A historical run may use an explicit
-  // CIK with SEC's filed-at filter, but it must not resolve that CIK from today's universe.
-  if (!cik && symbol && marketFor(symbol)?.id === "US" && snapshotPolicy.allowed) {
-    cik = await fetchUniverse({ signal })
-      .then((rows) => rows.find((r) => String(r.ticker).toUpperCase() === String(symbol).toUpperCase())?.cik)
-      .catch(() => undefined);
-  } else if (!cik && symbol && marketFor(symbol)?.id === "US") {
-    out.unavailable.push("SEC ticker mapping: historical cutoff requires an explicit point-in-time CIK; today's ticker universe was not fetched");
-  }
   const jobs = [];
+  let quoteJob = null;
 
   if (symbol && snapshotPolicy.allowed) {
-    jobs.push(safely("quote", () => fetchQuote(symbol, { signal })).then((r) => {
+    quoteJob = safely("quote", () => fetchQuote(symbol, { signal })).then((r) => {
       if (r.ok && !r.value?.error) out.quote = r.value;
       else out.unavailable.push(r.ok ? `quote: ${r.value.error}` : r.error);
-    }));
+    });
+    jobs.push(quoteJob);
   } else if (symbol) {
     out.unavailable.push("quote: historical cutoff requires an archived point-in-time price; current snapshot was not fetched");
   }
 
+  if (macro && snapshotPolicy.allowed) {
+    jobs.push(safely("macro", () => getMacroSnapshot({ blocks: ["rates", "dollar_liquidity", "commodities"], signal })).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,
+      };
+    }));
+    // Dated official series, fetched alongside the market block rather than instead of it.
+    // The block prices the present; these carry the history a regime or an impulse needs, and
+    // each observation publishes its own date, so they are the only macro input that can
+    // reach the typed-fact pack with real lineage.
+    jobs.push(safely("macro series", () => fetchMacroSeries({ asOf, signal })).then((r) => {
+      if (!r.ok) { out.unavailable.push(r.error); return; }
+      out.macro_series = r.value;
+      out.unavailable.push(...r.value.unavailable);
+    }));
+  } else if (macro) {
+    out.unavailable.push("macro: historical cutoff requires archived observations; current market snapshots were not fetched");
+  }
+
+  // Classification is a routing decision, so wait for the already-started quote metadata
+  // before choosing SEC/company versus fund/index paths. Macro continues in parallel.
+  if (quoteJob) await quoteJob;
+  out.instrument = classifyInstrument({ symbol, quote: out.quote });
+
+  // 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. Fund registrants still get their submissions profile,
+  // but never an operating-company Company Facts screen.
+  const symbolMarket = marketFor(symbol);
+  const secRegistrantCandidate = symbolMarket?.id === "US"
+    && !["index", "future", "fx", "crypto"].includes(out.instrument.asset_type);
+  if (!cik && symbol && secRegistrantCandidate && snapshotPolicy.allowed) {
+    const mapping = await safely("SEC ticker mapping", () => fetchUniverse({ signal }));
+    if (mapping.ok) {
+      const match = mapping.value.find((row) => String(row.ticker).toUpperCase() === String(symbol).toUpperCase());
+      cik = match?.cik;
+      if (match) {
+        out.sec_ticker_match = { cik: match.cik, ticker: match.ticker, title: match.title };
+        out.instrument = classifyInstrument({ symbol, quote: out.quote, filer: { title: match.title } });
+      }
+    } else {
+      out.unavailable.push(mapping.error);
+    }
+  } else if (!cik && symbol && secRegistrantCandidate) {
+    out.unavailable.push("SEC ticker mapping: historical cutoff requires an explicit point-in-time CIK; today's ticker universe was not fetched");
+  }
+
   // Persona methods must receive the same shape the options calculator actually returns.
   // Do not manufacture realised volatility, a friction-adjusted edge, or event coverage:
   // the delayed CBOE snapshot does not contain any of them. Its explicit `unavailable`
   // entries remain attached to the grounding so downstream policies see gaps as gaps.
-  if (symbol && options && marketFor(symbol)?.id === "US" && snapshotPolicy.allowed) {
+  if (symbol && options && symbolMarket?.id === "US" && !out.instrument.index_like && snapshotPolicy.allowed) {
     jobs.push(safely("options chain", () => fetchOptionsChain(symbol, { asOf, signal })).then((r) => {
       if (r.ok && r.value?.available) out.options = r.value;
       else out.unavailable.push(r.ok ? `options chain: ${r.value?.reason || "unavailable"}` : r.error);
     }));
-  } else if (symbol && options && marketFor(symbol)?.id === "US") {
+  } else if (symbol && options && symbolMarket?.id === "US" && !out.instrument.index_like) {
     out.unavailable.push("options chain: historical cutoff requires an archived chain; current CBOE snapshot was not fetched");
+  } else if (symbol && options && out.instrument.index_like) {
+    out.not_applicable.push(localizedText(language, {
+      en: "CBOE equity/ETF option-chain adapter: direct cash-index symbol is not supported; use the appropriate listed derivative or ETF proxy explicitly",
+      zh: "CBOE 股票/ETF 期权链适配器：不支持直接的现金指数代码；请显式使用对应的上市衍生品或 ETF 代理。",
+      ja: "CBOE の株式/ETF オプションチェーン・アダプタ：現物指数シンボルには非対応です。対応する上場デリバティブまたは ETF 代理を明示的に使用してください。",
+      ko: "CBOE 주식/ETF 옵션 체인 어댑터: 현물 지수 심볼은 지원하지 않습니다. 해당 상장 파생상품 또는 ETF 프록시를 명시적으로 사용하십시오.",
+    }));
   }
 
   if (cik) {
     if (snapshotPolicy.allowed) {
-      jobs.push(safely("filer profile", () => fetchSubmissions(cik, { signal })).then((r) => {
-        if (r.ok) out.filer = r.value;
-        else out.unavailable.push(r.error);
-      }));
+      // Resolve the registrant before deciding whether Company Facts applies. Scheduling
+      // both in parallel recreated the QQQ bug when quote metadata was unavailable: the
+      // screen started under an equity fallback before the fund name arrived.
+      const filer = await safely("filer profile", () => fetchSubmissions(cik, { signal }));
+      if (filer.ok) {
+        out.filer = filer.value;
+        out.instrument = classifyInstrument({ symbol, quote: out.quote, filer: out.filer });
+      } else out.unavailable.push(filer.error);
     } else {
       out.unavailable.push("filer profile: SEC submissions metadata is current, not point-in-time versioned; it was excluded from the historical information set");
     }
-    jobs.push(safely("screen", () => screenTicker({ cik, ticker: symbol, asOf, signal })).then((r) => {
+    // The mechanical screen answers "is this worth research time"; the derived fundamentals
+    // answer "what do the method seats need". Both read the same Company Facts document, so
+    // they share one classification gate and run together.
+    if (out.instrument.sec_companyfacts_applicable && snapshotPolicy.allowed) {
+      const fundamentalsJob = safely("fundamentals", () => fetchFundamentals({ cik, ticker: symbol, asOf, signal })).then((r) => {
+        if (!r.ok) { out.unavailable.push(r.error); return; }
+        out.fundamentals = r.value;
+        out.unavailable.push(...(r.value.unavailable || []).map((gap) => (
+          typeof gap === "string" ? gap : `fundamentals ${gap.metric}: ${gap.code}${gap.detail ? ` (${gap.detail})` : ""}`
+        )));
+      });
+      jobs.push(fundamentalsJob);
+      // Section 16 ownership is chained after the fundamentals rather than run beside them: it
+      // is a RATIO over shares outstanding, and taking that count from a second source would
+      // make the numerator and the denominator describe different registers.
+      jobs.push((async () => {
+        await fundamentalsJob;
+        const shares = out.fundamentals?.metrics?.["capital_allocation.share_count"]?.value;
+        if (!Number.isFinite(shares)) return;
+        const owned = await safely("insider ownership", () => fetchInsiderOwnership(cik, {
+          sharesOutstanding: shares, asOf, signal,
+        }));
+        if (!owned.ok) { out.unavailable.push(owned.error); return; }
+        out.insider_ownership = owned.value;
+        out.unavailable.push(...(owned.value.unavailable || []));
+      })());
+    }
+    if (out.instrument.sec_companyfacts_applicable) jobs.push(safely("screen", () => screenTicker({ cik, ticker: symbol, asOf, signal })).then((r) => {
       if (!r.ok) { out.unavailable.push(r.error); return; }
       const s = r.value;
       const metricSourceIds = (metric) => (metric.source_records || []).map((source) => (
@@ -166,32 +252,60 @@ export async function gatherGrounding({
         skipped: s.rules.filter((x) => x.skipped).map((x) => ({ rule: x.id, label: x.label })),
       };
     }));
-  }
-
-  if (macro && snapshotPolicy.allowed) {
-    jobs.push(safely("macro", () => getMacroSnapshot({ blocks: ["rates", "dollar_liquidity", "commodities"], signal })).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,
-      };
+    else if (out.instrument.asset_type === "unknown") {
+      // Not the same thing as "not applicable": we could not classify the security at all,
+      // so withholding the screen is a gap the report must show, not a settled routing call.
+      out.unavailable.push(localizedText(language, {
+        en: "SEC Company Facts screen: instrument type unresolved (no exchange metadata and no registrant match), so the operating-company screen was withheld rather than assumed",
+        zh: "SEC Company Facts 筛选：证券类型未能判定（既无交易所元数据也无注册人匹配），因此不做经营公司假设，直接跳过该筛选。",
+        ja: "SEC Company Facts スクリーン：銘柄種別を判定できず（取引所メタデータも登録人一致もなし）、事業会社と仮定せずスクリーンを見送りました。",
+        ko: "SEC Company Facts 스크린: 증권 유형을 확정하지 못해(거래소 메타데이터·등록인 일치 모두 없음) 사업회사로 가정하지 않고 스크린을 보류했습니다.",
+      }));
+    } else out.not_applicable.push(localizedText(language, {
+      en: `operating-company SEC Company Facts screen: not applicable to ${out.instrument.asset_type}`,
+      zh: `经营公司 SEC Company Facts 筛选：不适用于 ${out.instrument.asset_type}。`,
+      ja: `事業会社向け SEC Company Facts スクリーン：${out.instrument.asset_type} には適用されません。`,
+      ko: `사업회사용 SEC Company Facts 스크린: ${out.instrument.asset_type}에는 적용되지 않습니다.`,
     }));
-  } else if (macro) {
-    out.unavailable.push("macro: historical cutoff requires archived observations; current market snapshots were not fetched");
   }
 
   // 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" && snapshotPolicy.allowed) {
+  if (symbol && symbolMarket && symbolMarket.id !== "US" && !isFundOrIndex(out.instrument) && snapshotPolicy.allowed) {
     jobs.push(safely("market financials", () => fetchMarketFinancials(symbol, { signal })).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}`);
     }));
-  } else if (symbol && marketFor(symbol)?.id !== "US") {
+  } else if (symbol && symbolMarket && symbolMarket.id !== "US" && !isFundOrIndex(out.instrument)) {
     out.unavailable.push(`structured financials for ${symbol}: this adapter is not point-in-time versioned; current data was not fetched for a historical cutoff`);
   }
 
+  // A fund or index has no issuer financials, so this is where its evidence comes from
+  // instead: published holdings, index-level valuation and the look-through aggregates that
+  // let an operating-company method run against a basket at all.
+  if (symbol && isFundOrIndex(out.instrument) && snapshotPolicy.allowed) {
+    jobs.push(safely("instrument aggregate", () => gatherInstrumentFacts({
+      symbol, instrument: out.instrument, asOf, signal,
+      // The operating-company facts a basket can supply at all: everything the method seats
+      // ask of a company, aggregated by weight across the constituents that publish it.
+      lookThroughFactIds: LOOK_THROUGH_FACT_IDS,
+    })).then((r) => {
+      if (!r.ok) { out.unavailable.push(r.error); return; }
+      out.instrument_aggregate = r.value;
+      out.unavailable.push(...(r.value.unavailable || []));
+    }));
+  }
+
+  if (symbol && isFundOrIndex(out.instrument)) {
+    out.not_applicable.push(localizedText(language, {
+      en: `operating-company structured financials: not applicable to ${out.instrument.asset_type}; use look-through or aggregate index evidence`,
+      zh: `经营公司结构化财报：不适用于 ${out.instrument.asset_type}；请使用持仓穿透或指数聚合证据。`,
+      ja: `事業会社の構造化財務データ：${out.instrument.asset_type} には適用されません。ルックスルーまたは指数集計エビデンスを使用してください。`,
+      ko: `사업회사 구조화 재무데이터: ${out.instrument.asset_type}에는 적용되지 않습니다. 룩스루 또는 지수 집계 증거를 사용하십시오.`,
+    }));
+  }
+
   if (industry && snapshotPolicy.allowed) {
     const curated = resolveIndustry(industry);
     out.industry = {
@@ -216,7 +330,31 @@ export async function gatherGrounding({
 
   // 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)]);
+  if (inPlay.length && !isFundOrIndex(out.instrument)) out.coverage = coverageFor([...new Set(inPlay)]);
+  else if (symbol && isFundOrIndex(out.instrument)) {
+    out.coverage = {
+      rows: [{
+        symbol,
+        market: symbolMarket?.id || "market",
+        structured_financials: localizedText(language, {
+          en: "not applicable", zh: "不适用", ja: "適用外", ko: "해당 없음",
+        }),
+        reason: localizedText(language, {
+          en: `${out.instrument.asset_type} requires holdings/index look-through rather than issuer financial statements`,
+          zh: `${out.instrument.asset_type} 需要持仓/指数穿透，而不是发行人财务报表。`,
+          ja: `${out.instrument.asset_type} は発行体の財務諸表ではなく、保有銘柄・指数のルックスルーが必要です。`,
+          ko: `${out.instrument.asset_type}는 발행인 재무제표가 아니라 보유종목·지수 룩스루가 필요합니다.`,
+        }),
+      }],
+      summary: { full: 0, summary_only: 0, none: 0, not_applicable: 1 },
+      note: localizedText(language, {
+        en: "Fund/index research uses dated holdings, methodology and aggregate or look-through evidence.",
+        zh: "基金/指数研究使用带日期的持仓、方法论，以及聚合或穿透证据。",
+        ja: "ファンド/指数のリサーチは、日付入りの保有銘柄・方法論・集計またはルックスルーのエビデンスを使用します。",
+        ko: "펀드/지수 리서치는 일자가 명시된 보유종목, 방법론, 집계 또는 룩스루 증거를 사용합니다.",
+      }),
+    };
+  }
   const typed = adaptGroundingToTypedFacts(out, {
     asOf: asOf || gatheredAt,
     knowledgeAsOf: asOf || gatheredAt,
@@ -258,7 +396,7 @@ const localized = (label, chinese) => {
 
 export function groundingBlock(grounding, language = "English") {
   const chinese = /中文|chinese|zh/i.test(String(language));
-  if (!grounding || (!grounding.quote && !grounding.screen && !grounding.options && !grounding.macro && !grounding.industry)) return "";
+  if (!grounding || (!grounding.instrument && !grounding.quote && !grounding.screen && !grounding.options && !grounding.macro && !grounding.industry)) return "";
 
   const lines = [];
   const head = chinese
@@ -266,6 +404,13 @@ export function groundingBlock(grounding, language = "English") {
     : "## Established facts (from filings and exchange data, not from your memory)";
   lines.push(head);
 
+  if (grounding.instrument) {
+    const i = grounding.instrument;
+    lines.push(chinese
+      ? `- 资产类型：${i.asset_type}｜研究模型 ${i.research_model}｜识别来源 ${i.classification_source}`
+      : `- Instrument: ${i.asset_type} | research model ${i.research_model} | classified by ${i.classification_source}`);
+  }
+
   if (grounding.filer) {
     lines.push(chinese
       ? `- 主体：${grounding.filer.name}｜SIC ${grounding.filer.sic ?? "未知"}（${grounding.filer.sic_description ?? "-"}）｜交易所 ${grounding.filer.exchanges.join(", ") || "未知"}`
@@ -339,6 +484,13 @@ export function groundingBlock(grounding, language = "English") {
     lines.push(chinese ? `- 取不到的数据（属于数据缺口，禁止用记忆补）：${grounding.unavailable.join("；")}`
       : `- Could not be retrieved -- these are data gaps and must NOT be filled from memory: ${grounding.unavailable.join("; ")}`);
   }
+  if (grounding.not_applicable?.length) {
+    lines.push(chinese ? `- 明确不适用（不是数据抓取错误）：${grounding.not_applicable.join("；")}`
+      : `- Explicitly not applicable (not a retrieval failure): ${grounding.not_applicable.join("; ")}`);
+  }
+
+  const instrumentChecklist = instrumentResearchChecklist(grounding.instrument, language);
+  if (instrumentChecklist) lines.push("", instrumentChecklist);
 
   lines.push("");
   lines.push(chinese