alphacouncil-agent 1.0.0 → 1.0.2

package/mcp/lib/instrument-facts.mjs

@@ -13,12 +13,22 @@
  */
 
 import { LIMITS } from "./constants.mjs";
-import { fetchFundHoldings, fetchFundMetadata, lookThroughAggregate, topHoldingsCoverage } from "./funds.mjs";
+import {
+  MIN_LOOK_THROUGH_COVERAGE,
+  fetchFundHoldings,
+  fetchFundMetadata,
+  lookThroughAggregate,
+  topHoldingsCoverage,
+} from "./funds.mjs";
 import { fetchIndexAggregate, INDEX_PROXIES, normalizeIndexSymbol } from "./index-aggregate.mjs";
 import { fetchImpliedErp } from "./damodaran.mjs";
-import { fetchBasketBreadth } from "./breadth.mjs";
-import { fetchFundamentals } from "./fundamentals.mjs";
-import { fetchUniverse } from "./sec.mjs";
+import { chartUrl, fetchBasketBreadth, parseDailyCloses } from "./breadth.mjs";
+import { flowInputs, recordFundObservation } from "./fund-observations.mjs";
+import { fundFlow } from "./funds.mjs";
+import { fetchText } from "./quotes.mjs";
+import { deriveFundamentals } from "./fundamentals.mjs";
+import { evaluateRules } from "./screen.mjs";
+import { fetchCompanyFacts, fetchUniverse } from "./sec.mjs";
 
 /**
  * How many constituents may be resolved for a look-through pass.
@@ -51,6 +61,15 @@ export const LOOK_THROUGH_TARGET_COVERAGE = 0.6;
 export const LOOK_THROUGH_FACT_RULES = Object.freeze({
   "financial.leverage": "leverage.debt_to_equity",
   "valuation.revenue_growth": "growth.revenue_growth",
+  // Every one of these is a pure ratio that a weighted mean of constituents answers honestly,
+  // and every one of them was already legal to aggregate -- it simply had no line here, which
+  // is why eighteen seats stayed silent on a basket whose data was complete.
+  "accounting.cash_conversion": "accounting.cash_conversion",
+  "financial.gross_margin_5y": "profitability.gross_margin",
+  "financial.net_margin_5y": "profitability.net_margin",
+  "financial.return_on_equity_10y": "profitability.return_on_equity_10y",
+  "financial.incremental_return_on_capital": "profitability.incremental_return_on_capital",
+  "financial.interest_coverage": "coverage.interest_coverage",
 });
 
 /**
@@ -63,6 +82,29 @@ export const LOOK_THROUGH_FACT_RULES = Object.freeze({
  * is real and worth doing; it is simply not this pass, and pretending otherwise by summing is
  * the failure mode, not the shortcut.
  */
+/**
+ * Absolute company figures a fund owns a real, computable dollar share of.
+ *
+ * `LOOK_THROUGH_BLOCKED` refuses the naive version of this and is right to: summing every
+ * constituent's owner earnings produces "the ETF's owner earnings" as though the fund owned
+ * each business outright, which it does not. What the fund does own is a stake — its position
+ * value over the company's market capitalisation — and that stake's claim on the figure is
+ * ordinary look-through accounting:
+ *
+ *     fund's claim = AUM x SUM over i of ( weight_i / market_cap_i ) x figure_i
+ *
+ * The result is in dollars and is the fund's, not the index's. Because the fund's own market
+ * capitalisation is its AUM, every seat that divides one of these by market capitalisation
+ * gets the weighted look-through yield without a single change to its method.
+ */
+export const LOOK_THROUGH_CLAIM_FACTS = Object.freeze([
+  "financial.owner_earnings",
+  "financial.free_cash_flow_5y",
+  "financial.net_current_asset_value",
+  "valuation.downside_asset_value",
+  "valuation.downside_floor",
+]);
+
 export const LOOK_THROUGH_BLOCKED = Object.freeze({
   "financial.owner_earnings": "absolute currency; needs a per-constituent market capitalisation to become a yield",
   "financial.net_current_asset_value": "absolute currency; needs a per-constituent market capitalisation to become a ratio",
@@ -71,6 +113,35 @@ export const LOOK_THROUGH_BLOCKED = Object.freeze({
   "capital_allocation.share_count": "a count, not a rate; it has no portfolio-level meaning",
 });
 
+/**
+ * Mechanical-screen rule id -> the pack fact id it supplies, mirroring the grounding adapter's
+ * own map. Percent rules publish 15 for 15%, and every pack ratio is a decimal.
+ */
+const SCREEN_RULE_FACTS = Object.freeze({
+  roe_10y: "financial.return_on_equity_10y",
+  interest_cover: "financial.interest_coverage",
+  gross_margin: "financial.gross_margin_5y",
+  ocf_over_ni: "accounting.cash_conversion",
+  net_margin: "financial.net_margin_5y",
+  // An absolute, and the only one the screen carries. It is not aggregated as a ratio -- it
+  // feeds the ownership-claim pass, where dollars are the right unit.
+  fcf_5y: "financial.free_cash_flow_5y",
+});
+const SCREEN_PERCENT_RULES = new Set(["roe_10y", "gross_margin", "net_margin"]);
+
+/**
+ * The unit a look-through fact must carry.
+ *
+ * The aggregate of a quantity IS that quantity, so it has to arrive under the same contract the
+ * single-company path declares. Emitting every aggregate as a bare `decimal` made the executor
+ * reject coverage and cash conversion, which are multiples -- the fact was present and unusable,
+ * which reads exactly like the fact being absent.
+ */
+const LOOK_THROUGH_UNITS = Object.freeze({
+  "financial.interest_coverage": "multiple",
+  "accounting.cash_conversion": "multiple",
+});
+
 export const LOOK_THROUGH_FACT_IDS = Object.freeze(Object.keys(LOOK_THROUGH_FACT_RULES));
 
 const finite = (value) => typeof value === "number" && Number.isFinite(value);
@@ -241,11 +312,15 @@ export async function resolveConstituentFacts(holdings, { signal, asOf = null, c
   // The aggregate inherits whatever span its inputs covered; without carrying it the basket
   // fact arrives as a bare number that no duration contract can accept.
   const perHoldingPeriods = new Map();
+  // A share count is not aggregable and is not aggregated. It is kept because a market
+  // capitalisation -- shares times price -- is what turns an absolute figure into the fund's
+  // own dollar claim on it.
+  const shareCounts = new Map();
   const unavailable = [];
   const ranked = [...holdings]
     .sort((left, right) => (right.weight || 0) - (left.weight || 0))
     .slice(0, LOOK_THROUGH_MAX_CONSTITUENTS);
-  if (!ranked.length) return { perHolding, perHoldingPeriods, unavailable, attempted: 0 };
+  if (!ranked.length) return { perHolding, perHoldingPeriods, shareCounts, unavailable, attempted: 0 };
 
   let universe = null;
   try {
@@ -255,6 +330,7 @@ export async function resolveConstituentFacts(holdings, { signal, asOf = null, c
     return {
       perHolding,
       perHoldingPeriods,
+      shareCounts,
       unavailable: [`look-through: SEC ticker universe unavailable (${String(error?.message || error)})`],
       attempted: 0,
     };
@@ -267,12 +343,29 @@ export async function resolveConstituentFacts(holdings, { signal, asOf = null, c
       const cik = universe.get(ticker);
       if (!cik) { unavailable.push(`look-through ${ticker}: no SEC registrant for this ticker`); continue; }
       try {
-        const derived = await fetchFundamentals({ cik, ticker, asOf, signal });
+        // One document, both readers. The derived fundamentals and the mechanical screen read
+        // the same Company Facts filing, and fetching it twice per constituent would double
+        // the cost of a look-through for metrics that were already on disk. The screen is
+        // where the margins, cash conversion, ten-year ROE and interest coverage live -- which
+        // is why wiring only the fundamentals path left those aggregates permanently empty.
+        const companyFacts = await fetchCompanyFacts(cik, { signal });
+        const derived = deriveFundamentals({ companyFacts, asOf });
+        const screened = evaluateRules(companyFacts, { asOf });
         const facts = {};
         const periods = {};
+        for (const rule of screened.rules || []) {
+          const factId = SCREEN_RULE_FACTS[rule?.id];
+          if (!factId || rule.skipped || !Number.isFinite(rule.value)) continue;
+          // The screen publishes percentages as 15 for 15%; every pack ratio is a decimal.
+          facts[factId] = SCREEN_PERCENT_RULES.has(rule.id) ? rule.value / 100 : rule.value;
+          if (rule.period_start && rule.period_end) {
+            periods[factId] = { start: rule.period_start, end: rule.period_end };
+          }
+        }
         for (const [factId, metric] of Object.entries(derived.metrics || {})) {
           if (!metric || !Number.isFinite(metric.value)) continue;
           facts[factId] = metric.value;
+          if (factId === "capital_allocation.share_count") shareCounts.set(ticker, metric.value);
           if (metric.period_start && metric.period_end) {
             periods[factId] = { start: metric.period_start, end: metric.period_end };
           }
@@ -285,7 +378,7 @@ export async function resolveConstituentFacts(holdings, { signal, asOf = null, c
     }
   };
   await Promise.all(Array.from({ length: Math.min(concurrency, ranked.length) }, worker));
-  return { perHolding, perHoldingPeriods, unavailable, attempted: ranked.length };
+  return { perHolding, perHoldingPeriods, shareCounts, unavailable, attempted: ranked.length };
 }
 
 /**
@@ -297,20 +390,134 @@ export async function resolveConstituentFacts(holdings, { signal, asOf = null, c
  * correct outcome and not a failure.
  */
 /**
- * The interval a basket-level aggregate covers: the widest span its contributing constituents
- * reported. Stating a narrower one would claim coverage the inputs do not have, and stating
- * none at all leaves the fact unusable by any duration contract.
+ * The interval a basket-level aggregate covers.
+ *
+ * The outer envelope -- earliest start to latest end -- is the wrong answer. Constituents keep
+ * different fiscal calendars, so the union of forty five-year spans is five years plus a year
+ * of calendar edges, and a fact that genuinely covers five years then fails a five-year
+ * contract for a reason that has nothing to do with its coverage.
+ *
+ * The median end date and the median span describe what the aggregate actually covers: a
+ * typical constituent's reporting window, which is the window the number was averaged over.
  */
 function aggregatePeriod(perHoldingPeriods, factId, tickers) {
-  let start = null;
-  let end = null;
+  const spans = [];
   for (const ticker of tickers) {
     const span = perHoldingPeriods?.get(ticker)?.[factId];
     if (!span?.start || !span?.end) continue;
-    if (!start || span.start < start) start = span.start;
-    if (!end || span.end > end) end = span.end;
+    const start = Date.parse(span.start);
+    const end = Date.parse(span.end);
+    if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) continue;
+    spans.push({ end, days: (end - start) / 86_400_000 });
+  }
+  if (!spans.length) return {};
+  const median = (values) => {
+    const sorted = [...values].sort((left, right) => left - right);
+    return sorted[Math.floor(sorted.length / 2)];
+  };
+  const end = median(spans.map((span) => span.end));
+  const days = median(spans.map((span) => span.days));
+  return {
+    period_start: new Date(end - days * 86_400_000).toISOString().slice(0, 10),
+    period_end: new Date(end).toISOString().slice(0, 10),
+  };
+}
+
+/**
+ * The dollar claim a fund has on an absolute company figure, summed across constituents.
+ *
+ * Requires a market capitalisation per constituent, which is its own filed share count times
+ * its last close — both already in hand from the fundamentals pass and the breadth pass. A
+ * constituent missing either is excluded and costs coverage rather than being assumed.
+ */
+/**
+ * A share count for a fund whose holdings file does not carry one.
+ *
+ * There are two routes and they are not equally good, which matters because a flow is a
+ * DIFFERENCE of two counts and therefore keeps only their error.
+ *
+ * The good route is the issuer's own assets over its own net asset value, on the same date
+ * from the same source: that ratio IS shares outstanding, an identity rather than an estimate,
+ * and it is trustworthy enough to difference.
+ *
+ * The weak route is the assets implied by disclosed positions over the fund's market price. It
+ * is fine for a market capitalisation -- the product is the size we already had -- and unfit
+ * for a flow, because a 95%-priced position sum and a premium to NAV each carry error that a
+ * subtraction leaves behind while cancelling the number. `flowInputs` refuses it by basis.
+ */
+async function impliedFundShares(symbol, netAssets, metadata, signal) {
+  if (finite(metadata?.nav) && metadata.nav > 0 && finite(metadata?.aum) && metadata.aum > 0) {
+    return { value: metadata.aum / metadata.nav, how: "issuer_aum_over_nav" };
+  }
+  if (!finite(netAssets) || netAssets <= 0) return null;
+  try {
+    const closes = parseDailyCloses(JSON.parse(await fetchText(chartUrl(symbol), LIMITS.QUOTE_FETCH_MS, signal)));
+    const close = closes?.at(-1);
+    if (!finite(close) || close <= 0) return null;
+    return { value: netAssets / close, how: "assets_from_disclosed_positions_over_market_price" };
+  } catch {
+    return null;
+  }
+}
+
+export function lookThroughClaims({ holdings, perHoldingFacts, perHoldingPeriods, shareCounts, closes, netAssets, holdingsMeta }) {
+  const facts = [];
+  const unavailable = [];
+  if (!finite(netAssets) || netAssets <= 0) {
+    unavailable.push("look-through claims: the fund's own size is unknown, so a dollar claim cannot be scaled");
+    return { facts, unavailable };
+  }
+  const priced = new Map();
+  for (const holding of holdings || []) {
+    const ticker = String(holding?.ticker || "").toUpperCase();
+    const shares = shareCounts?.get?.(ticker);
+    const close = closes?.[ticker];
+    if (!finite(holding?.weight) || !finite(shares) || shares <= 0 || !finite(close) || close <= 0) continue;
+    priced.set(ticker, { weight: holding.weight, marketCap: shares * close });
+  }
+  if (!priced.size) {
+    unavailable.push("look-through claims: no constituent supplied both a share count and a price");
+    return { facts, unavailable };
+  }
+  for (const factId of LOOK_THROUGH_CLAIM_FACTS) {
+    let claim = 0;
+    let covered = 0;
+    for (const [ticker, { weight, marketCap }] of priced) {
+      const value = perHoldingFacts?.get?.(ticker)?.[factId];
+      if (!finite(value)) continue;
+      claim += (weight / marketCap) * value;
+      covered += weight;
+    }
+    if (covered < MIN_LOOK_THROUGH_COVERAGE) {
+      unavailable.push(
+        `look-through claim ${factId}: ${(covered * 100).toFixed(1)}% of the basket by weight supplied it,`
+        + ` below the ${(MIN_LOOK_THROUGH_COVERAGE * 100).toFixed(0)}% floor`,
+      );
+      continue;
+    }
+    facts.push({
+      fact_id: factId,
+      value: Number((claim * netAssets).toFixed(2)),
+      // A claim on a one-year figure covers a year and a claim on a five-year total covers
+      // five. It inherits the window its inputs reported, for the same reason the ratio
+      // aggregates do.
+      ...aggregatePeriod(perHoldingPeriods, factId, [...priced.keys()]),
+      value_kind: "monetary",
+      unit: "currency_units",
+      currency: "USD",
+      scale: 1,
+      source_kind: "issuer_disclosure",
+      source_url: holdingsMeta?.source_url,
+      public_at: holdingsMeta?.public_at,
+      observation_date: holdingsMeta?.as_of,
+      confidence: 0.65,
+      derivation: "rederived",
+      method: "fund_ownership_share_of_constituent_figure",
+      coverage_weight: Number(covered.toFixed(6)),
+      title: `${holdingsMeta?.symbol || "fund"} look-through claim on ${factId}`,
+    });
   }
-  return start && end ? { period_start: start, period_end: end } : {};
+  return { facts, unavailable };
 }
 
 export function lookThroughFacts({ holdings, perHoldingFacts, perHoldingPeriods, factIds, holdingsMeta }) {
@@ -342,7 +549,7 @@ export function lookThroughFacts({ holdings, perHoldingFacts, perHoldingPeriods,
       fact_id: factId,
       value: aggregate.value,
       value_kind: "ratio",
-      unit: "decimal",
+      unit: LOOK_THROUGH_UNITS[factId] || "decimal",
       ratio_denominator: `weight_${aggregate.method}`,
       source_kind: "issuer_disclosure",
       source_url: holdingsMeta?.source_url,
@@ -456,12 +663,14 @@ export async function gatherInstrumentFacts({
   }
   unavailable.push(...(erp?.unavailable || []));
   unavailable.push(...(aggregate?.unavailable || []));
+  let breadthResult = null;
   if (holdings?.holdings?.length) {
     facts.push(...structureFacts(holdings, metadata));
     // Breadth is computed from the basket rather than bought: every free screener that
     // publishes it forbids the query, and the holdings are already in hand.
-    const breadth = await fetchBasketBreadth(holdings.holdings, { signal })
+    breadthResult = await fetchBasketBreadth(holdings.holdings, { signal })
       .catch((error) => ({ available: false, unavailable: [`breadth: ${String(error?.message || error)}`] }));
+    const breadth = breadthResult;
     unavailable.push(...(breadth.unavailable || []));
     if (breadth.available) {
       const shared = {
@@ -497,6 +706,77 @@ export async function gatherInstrumentFacts({
           title: `${holdings.symbol} assets from disclosed positions`,
         });
       }
+      // The fund's own shares outstanding. This is the fund as an issuer, not an aggregate of
+      // anything -- and it is what lets a seat build the fund's market capitalisation with the
+      // same arithmetic it uses on a company, which is why ten seats could not read a basket.
+      const fundShares = finite(holdings.shares_outstanding)
+        ? { value: holdings.shares_outstanding, how: "issuer_disclosed_shares_outstanding" }
+        : await impliedFundShares(holdings.symbol, breadth.net_assets, metadata, signal);
+      if (fundShares) {
+        facts.push({
+          ...shared,
+          fact_id: "capital_allocation.share_count",
+          value: Number(fundShares.value.toFixed(2)),
+          value_kind: "count",
+          unit: "shares",
+          ratio_denominator: undefined,
+          derivation: fundShares.how === "issuer_disclosed_shares_outstanding" ? "reported" : "rederived",
+          method: fundShares.how,
+          title: `${holdings.symbol} shares outstanding`,
+        });
+      }
+      // What this run saw about the fund's size, appended to its own ledger. No issuer serves
+      // a share-count history keylessly, so the history is built one run at a time and a flow
+      // becomes computable from the second observation onward.
+      const observed = recordFundObservation({
+        symbol: holdings.symbol,
+        asOf: holdings.as_of,
+        sharesOutstanding: fundShares?.value ?? null,
+        sharesBasis: fundShares?.how ?? null,
+        nav: finite(metadata?.nav) ? metadata.nav : null,
+        netAssets: finite(metadata?.aum) ? metadata.aum : breadth.net_assets,
+        sourceUrl: holdings.source_url,
+      });
+      const inputs = flowInputs(observed.observations);
+      const flow = inputs
+        ? fundFlow({ sharesNow: inputs.sharesNow, sharesPrior: inputs.sharesPrior, nav: inputs.nav, issuer: holdings.issuer })
+        : null;
+      if (flow && finite(flow.value)) {
+        facts.push({
+          ...shared,
+          fact_id: "fund.net_flow",
+          value: flow.value,
+          value_kind: "monetary",
+          unit: "currency_units",
+          currency: "USD",
+          scale: 1,
+          ratio_denominator: undefined,
+          derivation: "rederived",
+          observation_date: inputs.asOf,
+          method: `${flow.construction.formula}; ${inputs.priorAsOf} to ${inputs.asOf}, ${inputs.gapDays} days apart`,
+          title: `${holdings.symbol} net creation over ${inputs.gapDays} days`,
+        });
+        if (finite(inputs.netAssets) && inputs.netAssets > 0) {
+          facts.push({
+            ...shared,
+            fact_id: "fund.net_flow_ratio",
+            value: Number((flow.value / inputs.netAssets).toFixed(6)),
+            ratio_denominator: "net_assets",
+            derivation: "rederived",
+            observation_date: inputs.asOf,
+            method: `net creation over assets; ${inputs.priorAsOf} to ${inputs.asOf}, ${inputs.gapDays} days apart`,
+            title: `${holdings.symbol} net creation as a share of assets`,
+          });
+        }
+      } else {
+        const filed = observed.observations.filter((row) => row.shares_basis === "issuer_disclosed_shares_outstanding").length;
+        unavailable.push(filed >= 1
+          ? `fund flow for ${holdings.symbol}: ${filed} issuer-published share-count observation(s) on record;`
+            + " a flow needs two, and no issuer serves a keyless history. The ledger grows one run at a time."
+          : `fund flow for ${holdings.symbol}: ${holdings.issuer} publishes no shares outstanding, and the count`
+            + " reconstructed from assets over price may size the fund but must not be differenced into a flow --"
+            + " the subtraction cancels the number and keeps the error.");
+      }
       // The gap between weighted and counted breadth IS the concentration story: a
       // cap-weighted basket can be above its average on weight while most members are below.
       facts.push({
@@ -516,10 +796,12 @@ export async function gatherInstrumentFacts({
   if (holdings?.holdings?.length && lookThroughFactIds.length) {
     let resolved = perHoldingFacts;
     let resolvedPeriods = null;
+    let resolvedShareCounts = null;
     if (!resolved) {
       const constituents = await resolveConstituentFacts(holdings.holdings, { signal, asOf });
       resolved = constituents.perHolding;
       resolvedPeriods = constituents.perHoldingPeriods;
+      resolvedShareCounts = constituents.shareCounts;
       unavailable.push(...constituents.unavailable);
       provenance.look_through = {
         constituents_attempted: constituents.attempted,
@@ -535,12 +817,31 @@ export async function gatherInstrumentFacts({
     });
     facts.push(...through.facts);
     unavailable.push(...through.unavailable);
+
+    // The fund's own size is what scales a per-dollar claim back into dollars. Prefer the
+    // issuer's published figure and fall back to the assets implied by the disclosed
+    // positions, which is the same number the size fact above is built from.
+    const netAssets = finite(metadata?.aum) ? metadata.aum : breadthResult?.net_assets;
+    const claims = lookThroughClaims({
+      holdings: holdings.holdings,
+      perHoldingFacts: resolved,
+      perHoldingPeriods: resolvedPeriods,
+      shareCounts: resolvedShareCounts,
+      closes: breadthResult?.closes,
+      netAssets,
+      holdingsMeta: holdings,
+    });
+    facts.push(...claims.facts);
+    unavailable.push(...claims.unavailable);
   }
 
   return {
     symbol,
     research_model: instrument?.research_model || "market_instrument",
     provenance,
+    // The disclosed positions themselves, so a caller that needs the basket's identity rather
+    // than its aggregates -- news, for one -- does not fetch the holdings file a second time.
+    holdings: holdings?.holdings || null,
     facts,
     // Several facts have more than one route -- the implied ERP and the valuation percentile
     // are computed from the published workbook when the index feed cannot supply them -- and

package/mcp/lib/instruments.mjs

@@ -9,6 +9,7 @@
  */
 
 import { localized } from "./lang.mjs";
+import { FUND_REGISTRY } from "./funds.mjs";
 
 export const ASSET_TYPES = Object.freeze([
   "equity",
@@ -35,10 +36,24 @@ function normalizedRawType(value) {
   return String(value || "").trim().toUpperCase().replace(/[\s-]+/gu, "_");
 }
 
+/**
+ * Cash indices people type without the caret.
+ *
+ * `^SOX` classified as an index and `SOX` did not, so a run on the name everyone actually uses
+ * produced no basket facts at all and every seat abstained for want of data it was never going
+ * to get. These are index names, not listed tickers -- deliberately a short curated set rather
+ * than the whole alias table, because an alias that collides with a real ticker would route a
+ * tradable security into the index path, which is the mirror image of the same defect.
+ */
+const BARE_INDEX_SYMBOLS = new Set([
+  "SOX", "SPX", "NDX", "DJIA", "DJI", "RUT", "VIX", "IXIC", "GSPC", "COMPQ", "NYA", "OEX", "XAX",
+]);
+
 function symbolHeuristic(symbol) {
   const text = String(symbol || "").trim().toUpperCase();
   if (!text) return null;
   if (text.startsWith("^")) return "index";
+  if (BARE_INDEX_SYMBOLS.has(text)) return "index";
   if (text.endsWith("=F")) return "future";
   if (text.endsWith("=X")) return "fx";
   if (/^[A-Z0-9]+-USD$/u.test(text)) return "crypto";
@@ -94,6 +109,16 @@ export function classifyInstrument({ symbol, quote, filer } = {}) {
       classificationSource = "sec_filer_sic";
     }
   }
+  // A basket we hold an issuer holdings endpoint for is a basket, whatever a quote feed did or
+  // did not say. This is a lookup of something this repository states, not a guess from ticker
+  // shape, and it runs only after real evidence has had its turn so genuine metadata still
+  // wins and still reports its own provenance. It strengthens the fail-closed rule below
+  // rather than weakening it: the outcome is a fund, which is the one thing that can never be
+  // sent through an operating-company screen.
+  if (!assetType && Object.hasOwn(FUND_REGISTRY, String(symbol || quote?.symbol || "").trim().toUpperCase())) {
+    assetType = "etf";
+    classificationSource = "registered_fund_holdings_source";
+  }
   // Deliberately fail closed. A bare ticker shape tells us nothing: SPY, QQQ and VOO all
   // match it, and the previous `equity` fallback sent them into an operating-company Company
   // Facts screen whenever Yahoo metadata was missing -- the exact QQQ defect 0.9.5 set out to

package/mcp/lib/markdown.mjs

@@ -118,25 +118,33 @@ const MASTER_STATEMENT_COPY = Object.freeze({
     heading: "\u9010\u5e2d\u65b9\u6cd5\u8f93\u51fa", acted: "\u6709\u5224\u65ad\u7684\u5e2d\u4f4d", abstained: "\u8bf4\u8fd9\u4e0d\u5f52\u5b83\u7ba1\u7684\u5e2d\u4f4d",
     stance: "\u7acb\u573a", intent: "\u610f\u5411", origin: "\u9648\u8bcd\u6765\u6e90", statement: "\u672c\u8f6e\u53d1\u8a00\uff08\u4e0d\u662f\u672c\u4eba\u5f15\u8bed\uff09",
     findings: "\u5173\u952e\u53d1\u73b0", disagreements: "\u4e0e\u5206\u6790\u5e08\u5206\u6b67", change: "\u6539\u53d8\u5224\u65ad\u6761\u4ef6", sources: "\u6765\u6e90\u6216\u660e\u786e\u7f3a\u53e3",
-    abstainLead: (n) => `\u53e6\u6709 ${n} \u5e2d\u5728\u672c\u8f6e\u4e0d\u7ed9\u65b9\u5411\uff0c\u5404\u81ea\u7f3a\u7684\u662f\u65b9\u6cd5\u5fc5\u9700\u7684\u8f93\u5165\uff0c\u8fd9\u4e0d\u662f\u770b\u7a7a\u7968\uff1a`,
+    abstainLead: (n) => `\u53e6\u6709 ${n} \u5e2d\u672c\u8f6e\u672a\u80fd\u53d6\u5f97\u5176\u65b9\u6cd5\u5fc5\u9700\u7684\u8f93\u5165\uff0c\u56e0\u6b64\u6ca1\u6709\u7ed9\u51fa\u65b9\u5411\u3002\u8fd9\u662f\u6570\u636e\u7f3a\u53e3\uff0c\u4e0d\u662f\u770b\u7a7a\u7968\uff1a`,
+    declined: "\u770b\u8fc7\u4e4b\u540e\u51b3\u5b9a\u4e0d\u53c2\u4e0e\u7684\u5e2d\u4f4d",
+    declinedLead: (n) => `\u4ee5\u4e0b ${n} \u5e2d\u7684\u65b9\u6cd5\u8dd1\u5b8c\u4e86\uff0c\u5e76\u4e14\u5f97\u51fa\u4e86\u201c\u4e0d\u662f\u8fd9\u4e2a\u201d\u3002\u8fd9\u662f\u5224\u65ad\uff0c\u4e0d\u662f\u7f3a\u6570\u636e\uff1a`,
   },
   en: {
     heading: "Method-Seat Outputs", acted: "Seats with a view", abstained: "Seats that say this is not theirs to call",
     stance: "Stance", intent: "Intent", origin: "Statement source", statement: "Recorded statement (not a quote)",
     findings: "Key findings", disagreements: "Disagreements", change: "What would change the view", sources: "Sources or explicit gaps",
-    abstainLead: (n) => `A further ${n} seat(s) issue no direction this round, each missing a method-critical input. These are not bearish votes:`,
+    abstainLead: (n) => `A further ${n} seat(s) issue no direction because a method-critical input did not arrive this round. This is a data gap, not a bearish vote:`,
+    declined: "Seats whose method examined this and declined",
+    declinedLead: (n) => `${n} seat(s) ran their method to completion and it returned "not this one". These are judgments, not missing data:`,
   },
   ja: {
     heading: "\u30e1\u30bd\u30c3\u30c9\u5e2d\u3054\u3068\u306e\u51fa\u529b", acted: "\u5224\u65ad\u3092\u793a\u3057\u305f\u5e2d", abstained: "\u81ea\u5206\u306e\u62c5\u5f53\u3067\u306f\u306a\u3044\u3068\u3057\u305f\u5e2d",
     stance: "\u30b9\u30bf\u30f3\u30b9", intent: "\u610f\u5411", origin: "\u898b\u89e3\u306e\u751f\u6210\u5143", statement: "\u4eca\u56de\u306e\u767a\u8a00\uff08\u672c\u4eba\u306e\u5f15\u7528\u3067\u306f\u3042\u308a\u307e\u305b\u3093\uff09",
     findings: "\u4e3b\u306a\u6240\u898b", disagreements: "\u5206\u6790\u62c5\u5f53\u3068\u306e\u76f8\u9055", change: "\u5224\u65ad\u304c\u5909\u308f\u308b\u6761\u4ef6", sources: "\u51fa\u5178\u307e\u305f\u306f\u660e\u793a\u7684\u306a\u6b20\u843d",
-    abstainLead: (n) => `\u4ed6\u306b ${n} \u5e2d\u306f\u4eca\u56de\u65b9\u5411\u6027\u3092\u793a\u3057\u307e\u305b\u3093\u3002\u3044\u305a\u308c\u3082\u30e1\u30bd\u30c3\u30c9\u306b\u5fc5\u8981\u306a\u5165\u529b\u3092\u6b20\u3044\u3066\u304a\u308a\u3001\u5f31\u6c17\u7968\u3067\u306f\u3042\u308a\u307e\u305b\u3093\uff1a`,
+    abstainLead: (n) => `\u4ed6\u306b ${n} \u5e2d\u306f\u3001\u30e1\u30bd\u30c3\u30c9\u306b\u5fc5\u8981\u306a\u5165\u529b\u304c\u4eca\u56de\u5c4a\u304b\u306a\u304b\u3063\u305f\u305f\u3081\u65b9\u5411\u6027\u3092\u793a\u3057\u307e\u305b\u3093\u3002\u30c7\u30fc\u30bf\u306e\u6b20\u843d\u3067\u3042\u308a\u3001\u5f31\u6c17\u7968\u3067\u306f\u3042\u308a\u307e\u305b\u3093\uff1a`,
+    declined: "\u691c\u8a0e\u3057\u305f\u4e0a\u3067\u898b\u9001\u3063\u305f\u5e2d",
+    declinedLead: (n) => `\u6b21\u306e ${n} \u5e2d\u306f\u30e1\u30bd\u30c3\u30c9\u3092\u6700\u5f8c\u307e\u3067\u5b9f\u884c\u3057\u3001\u300c\u3053\u308c\u3067\u306f\u306a\u3044\u300d\u3068\u7d50\u8ad6\u3057\u307e\u3057\u305f\u3002\u30c7\u30fc\u30bf\u4e0d\u8db3\u3067\u306f\u306a\u304f\u5224\u65ad\u3067\u3059\uff1a`,
   },
   ko: {
     heading: "\ubc29\ubc95\ub860 \uc88c\uc11d\ubcc4 \ucd9c\ub825", acted: "\ud310\ub2e8\uc744 \ub0b8 \uc88c\uc11d", abstained: "\uc790\uae30 \uc18c\uad00\uc774 \uc544\ub2c8\ub77c\uace0 \ubc1d\ud78c \uc88c\uc11d",
     stance: "\uc785\uc7a5", intent: "\uc758\ud5a5", origin: "\ubc1c\uc5b8 \ucd9c\ucc98", statement: "\uc774\ubc88 \ubc1c\uc5b8(\ubcf8\uc778 \uc778\uc6a9\uc774 \uc544\ub2d8)",
     findings: "\ud575\uc2ec \ubc1c\uacac", disagreements: "\ubd84\uc11d\uac00\uc640\uc758 \uc774\uacac", change: "\ud310\ub2e8 \ubcc0\uacbd \uc870\uac74", sources: "\ucd9c\ucc98 \ub610\ub294 \uba85\uc2dc\uc801 \ub370\uc774\ud130 \uacf5\ubc31",
-    abstainLead: (n) => `\uadf8 \uc678 ${n}\uac1c \uc88c\uc11d\uc740 \uc774\ubc88 \ud68c\ucc28\uc5d0 \ubc29\ud5a5\uc744 \uc81c\uc2dc\ud558\uc9c0 \uc54a\uc2b5\ub2c8\ub2e4. \uac01\uac01 \ubc29\ubc95\ub860\uc5d0 \ud544\uc694\ud55c \uc785\ub825\uc774 \uc5c6\uc73c\uba70 \uc57d\uc138 \ud22c\ud45c\uac00 \uc544\ub2d9\ub2c8\ub2e4:`,
+    abstainLead: (n) => `\uadf8 \uc678 ${n}\uac1c \uc88c\uc11d\uc740 \ubc29\ubc95\ub860\uc5d0 \ud544\uc694\ud55c \uc785\ub825\uc774 \uc774\ubc88 \ud68c\ucc28\uc5d0 \ub3c4\ucc29\ud558\uc9c0 \uc54a\uc544 \ubc29\ud5a5\uc744 \uc81c\uc2dc\ud558\uc9c0 \uc54a\uc2b5\ub2c8\ub2e4. \ub370\uc774\ud130 \uacf5\ubc31\uc774\uba70 \uc57d\uc138 \ud22c\ud45c\uac00 \uc544\ub2d9\ub2c8\ub2e4:`,
+    declined: "\uac80\ud1a0 \ud6c4 \ucc38\uc5ec\ud558\uc9c0 \uc54a\uae30\ub85c \ud55c \uc88c\uc11d",
+    declinedLead: (n) => `\ub2e4\uc74c ${n}\uac1c \uc88c\uc11d\uc740 \ubc29\ubc95\ub860\uc744 \ub05d\uae4c\uc9c0 \uc218\ud589\ud588\uace0 "\uc774\uac83\uc740 \uc544\ub2c8\ub2e4"\ub77c\ub294 \uacb0\ub860\uc5d0 \ub3c4\ub2ec\ud588\uc2b5\ub2c8\ub2e4. \ub370\uc774\ud130 \ubd80\uc871\uc774 \uc544\ub2c8\ub77c \ud310\ub2e8\uc785\ub2c8\ub2e4:`,
   },
 });
 
@@ -183,12 +191,25 @@ function renderMasterStatements(run) {
   const sections = [`### ${copy.heading}`, voiceDisclaimer(run.language)];
   if (acted.length) sections.push(`#### ${copy.acted}`, acted.map(seatBlock).join("\n\n"));
   if (abstained.length) {
-    // One paragraph, not one row per seat. The stable IDs stay visible so the gate and the
-    // reader can both account for every selected seat without twenty-five identical lines.
-    const merged = abstained
+    // Two reasons wear the same word and they are not the same event. A seat whose method
+    // examined the subject and declined has ANSWERED -- Graham finding no asset floor, a
+    // volatility seat finding no testable observation -- and reporting that as "missing an
+    // input" tells a reader the system broke when the method spoke. A seat whose required
+    // fact never arrived genuinely is a gap. Rendering them together made every run read as
+    // the second kind, which is the complaint this split exists to answer.
+    // One paragraph each, not one row per seat: the stable IDs stay visible so the gate and
+    // the reader can both account for every selected seat.
+    const merged = (group) => group
       .map((opinion) => `${masterTitle(opinion.master, run.language)} (\`${opinion.master}\`) \u2014 ${opinion.voice_statement}`)
       .join(" ");
-    sections.push(`#### ${copy.abstained}`, `${copy.abstainLead(abstained.length)}\n\n${merged}`);
+    const declined = abstained.filter((opinion) => methodDeclined(opinion));
+    const ungrounded = abstained.filter((opinion) => !methodDeclined(opinion));
+    if (declined.length) {
+      sections.push(`#### ${copy.declined}`, `${copy.declinedLead(declined.length)}\n\n${merged(declined)}`);
+    }
+    if (ungrounded.length) {
+      sections.push(`#### ${copy.abstained}`, `${copy.abstainLead(ungrounded.length)}\n\n${merged(ungrounded)}`);
+    }
   }
   return sections.join("\n\n");
 }
@@ -202,6 +223,18 @@ function renderMasterStatements(run) {
  * weakest thing a council produces and the dissenting seat is the informative one. Stating
  * this next to the opinions is the difference between a bench and a vote count.
  */
+/**
+ * Did the seat's own method reach this, or did the data never arrive?
+ *
+ * A fired veto and a false eligibility condition are both the method running to completion and
+ * returning "not this one". Anything else -- an unmet required fact type, a coverage shortfall,
+ * an executor refusal -- is the run failing to give the method what it asked for.
+ */
+export function methodDeclined(opinion) {
+  const reason = String(opinion?.decision?.reason || opinion?.reason || "");
+  return reason === "veto" || reason === "eligibility";
+}
+
 export function masterCorrelationNote(run) {
   const opinions = run?.master_opinions || [];
   if (!opinions.length) return "";