alphacouncil-agent 0.9.2 → 1.0.0

package/mcp/lib/council-options.mjs

@@ -4,6 +4,7 @@ import { loadPacks } from "./personas-v2/loader.mjs";
 import { compiledPersonaPacks } from "./personas-v3/registry.mjs";
 import { sha256 } from "./personas-v3/canonical.mjs";
 import { selectorCard } from "./master-catalog.mjs";
+import { languageKey, localized } from "./lang.mjs";
 
 /**
  * The menu a host shows before a run starts.
@@ -42,7 +43,8 @@ const estimateSelectionRange = ({ analysts = 0, allMasters = 1, verifiers = 0, d
 };
 
 export function councilOptions({ language = "English" } = {}) {
-  const chinese = /中文|chinese|zh/i.test(String(language));
+  const locale = languageKey(language);
+  const copy = (messages) => localized(language, messages);
   const reg = registry();
   const packs = loadPacks();
   const v3Packs = compiledPersonaPacks();
@@ -59,15 +61,6 @@ export function councilOptions({ language = "English" } = {}) {
     covers: (p.tags || []).join(", "),
   }));
 
-  const rosterChoices = masterRosters.map((roster) => {
-    const members = selectRoster(reg, { kind: "master", roster });
-    return {
-      roster,
-      count: members.length,
-      members: members.map((m) => ({ id: m.id, title: personaTitle(m, language) })),
-    };
-  });
-
   // A flattened, stable-order catalog is the selection source of truth. Rosters remain
   // useful shortcuts, but a user may choose any 1..N individual methods across schools.
   const masterChoices = reg.ids("master").map((id, offset) => {
@@ -77,7 +70,13 @@ export function councilOptions({ language = "English" } = {}) {
     const v3Selection = v3?.manifest?.selection;
     const v3Label = v3?.admitted_label;
     const provisionalV3 = v3?.build_profile === "solo_test";
-    const localized = (value) => chinese ? value?.zh : value?.en;
+    const field = (value, label) => {
+      const selected = value?.[locale];
+      if (typeof selected !== "string" || !selected.trim()) {
+        throw new Error(`${id}: missing ${locale} selector ${label}`);
+      }
+      return selected;
+    };
     // Until a physical v3 pack exists, bind the receipt to the exact v2 pack or prompt
     // persona rather than publishing a null hash. A prompt edit must invalidate a catalog
     // the user saw before that edit just as a v3 policy edit does.
@@ -94,13 +93,19 @@ export function councilOptions({ language = "English" } = {}) {
     return {
       index: offset + 1,
       id,
-      title: localized(v3Label) || personaTitle(persona, language),
+      title: v3Label ? field(v3Label, "title") : personaTitle(persona, language),
       ...(v3Selection ? {
-        identity: localized(v3Selection.identity),
-        method: localized(v3Selection.method),
-        best_for: localized(v3Selection.best_for),
+        identity: field(v3Selection.identity, "identity"),
+        method: field(v3Selection.method, "method"),
+        best_for: field(v3Selection.best_for, "best_for"),
       } : selectorCard(persona, language)),
       maturity: v3?.maturity || pack?.kind || "prompt_lens",
+      maturity_label: copy({
+        en: v3?.maturity === "method_model" ? "Validated method model" : v3?.maturity === "candidate" ? "Candidate method" : "Provisional operator lens",
+        zh: v3?.maturity === "method_model" ? "已验证方法模型" : v3?.maturity === "candidate" ? "候选方法" : "临时操作视角",
+        ja: v3?.maturity === "method_model" ? "検証済みメソッドモデル" : v3?.maturity === "candidate" ? "候補メソッド" : "暫定オペレーター・レンズ",
+        ko: v3?.maturity === "method_model" ? "검증된 방법론 모델" : v3?.maturity === "candidate" ? "후보 방법론" : "임시 오퍼레이터 렌즈",
+      }),
       runtime_level: v3?.admission?.level || (pack ? "v2_operator" : "v1_prompt"),
       admission_level: v3?.admission?.level || (pack ? "operator_lens" : "prompt_lens"),
       pack_format: v3 ? provisionalV3 ? "schema_v3_solo_test" : "schema_v3_physical" : pack ? "schema_v2_legacy" : "prompt_v1_legacy",
@@ -119,15 +124,31 @@ export function councilOptions({ language = "English" } = {}) {
     };
   });
 
+  const masterById = new Map(masterChoices.map((master) => [master.id, master]));
+  const rosterChoices = masterRosters.map((roster) => {
+    const members = selectRoster(reg, { kind: "master", roster });
+    return {
+      roster,
+      count: members.length,
+      members: members.map((member) => ({
+        id: member.id,
+        title: masterById.get(member.id)?.title || personaTitle(member, language),
+      })),
+    };
+  });
+
   const allMasters = masterChoices.length;
   const verifiers = reg.ids("verifier");
 
   const presets = [
     {
       id: "quick",
-      label: chinese
-        ? "快速：4 位核心分析师并行 + 最多 4 位大师 + 单轮并行多空 + 短综合"
-        : "Quick: 4 core analysts in parallel + up to 4 masters + one parallel bull/bear round + short synthesis",
+      label: copy({
+        en: "Quick: 4 core analysts in parallel + up to 4 masters + one parallel bull/bear round + short synthesis",
+        zh: "快速：4 位核心分析师并行 + 最多 4 位大师 + 单轮并行多空 + 短综合",
+        ja: "クイック：中核アナリスト4席を並列実行 + マスター最大4席 + 1回の並列Bull/Bear + 短い総合判断",
+        ko: "퀵: 핵심 분석가 4개 좌석 병렬 + 마스터 최대 4개 좌석 + 1회 병렬 Bull/Bear + 짧은 종합 판단",
+      }),
       analysts: QUICK_TASKS,
       master_selection: "required_1_to_N",
       master_selection_maximum: 4,
@@ -139,33 +160,52 @@ export function councilOptions({ language = "English" } = {}) {
       debate_rounds: 1,
       report_contract: "quick_v1",
       full_council_equivalent: false,
-      good_for: chinese
-        ? "十分钟级方向性初读：保留大师、核心分析师和近期公司/行业新闻；不做三轮交叉问答或对抗核验"
-        : "A bounded directional read retaining masters, core analysts and recent company/industry news; no three-round cross-exam or adversarial verification.",
+      good_for: copy({
+        en: "A bounded directional read retaining masters, core analysts and recent company/industry news; no three-round cross-exam or adversarial verification.",
+        zh: "十分钟级方向性初读：保留大师、核心分析师和近期公司/行业新闻；不做三轮交叉问答或对抗核验",
+        ja: "短時間の方向性確認。マスター、中核アナリスト、直近の企業・業界ニュースを含むが、3ラウンドの反対尋問や対抗検証は行わない。",
+        ko: "짧은 방향성 검토. 마스터, 핵심 분석가, 최근 기업·산업 뉴스를 포함하지만 3라운드 교차 질문이나 적대적 검증은 수행하지 않는다.",
+      }),
     },
     {
       id: "standard",
-      label: chinese ? "标准：8 位分析师 + 所选大师 + 辩论" : "Standard: 8 analysts + selected masters + debate",
+      label: copy({
+        en: "Standard: 8 analysts + selected masters + debate",
+        zh: "标准：8 位分析师 + 所选大师 + 辩论",
+        ja: "標準：アナリスト8席 + 選択したマスター + 討論",
+        ko: "표준: 분석가 8개 좌석 + 선택한 마스터 + 토론",
+      }),
       analysts: DEFAULT_TASKS,
       master_selection: "required_1_to_N",
       suggested_masters_roster: "masters-core",
       verify: false,
       ...estimateSelectionRange({ analysts: DEFAULT_TASKS.length, allMasters }),
-      good_for: chinese
-        ? "默认推荐。覆盖完整证据面，并运行用户本次确认的方法席"
-        : "The recommended default: full evidence coverage plus this run's confirmed methods.",
+      good_for: copy({
+        en: "The recommended default: full evidence coverage plus this run's confirmed methods.",
+        zh: "默认推荐。覆盖完整证据面，并运行用户本次确认的方法席",
+        ja: "推奨される標準設定。証拠範囲を完全にカバーし、この実行で確定したメソッド席を動かす。",
+        ko: "권장 기본값. 전체 증거 범위를 다루고 이번 실행에서 확정한 방법론 좌석을 실행한다.",
+      }),
     },
     {
       id: "deep",
-      label: chinese ? "深度：全部分析师 + 所选大师 + 交叉验证 + 辩论" : "Deep: every analyst + selected masters + verification + debate",
+      label: copy({
+        en: "Deep: every analyst + selected masters + verification + debate",
+        zh: "深度：全部分析师 + 所选大师 + 交叉验证 + 辩论",
+        ja: "詳細：全アナリスト + 選択したマスター + 交差検証 + 討論",
+        ko: "심층: 전체 분석가 + 선택한 마스터 + 교차 검증 + 토론",
+      }),
       analysts: allAnalysts.map((p) => p.id),
       master_selection: "required_1_to_N",
       suggested_masters_roster: "masters-core",
       verify: true,
       ...estimateSelectionRange({ analysts: allAnalysts.length, allMasters, verifiers: verifiers.length * 3 }),
-      good_for: chinese
-        ? "要下真钱的时候用。每条承重论断都会被回源、独立重算和反面检索"
-        : "For a decision with real money behind it. Every load-bearing claim is re-sourced, re-derived and attacked.",
+      good_for: copy({
+        en: "For a decision with real money behind it. Every load-bearing claim is re-sourced, re-derived and attacked.",
+        zh: "要下真钱的时候用。每条承重论断都会被回源、独立重算和反面检索",
+        ja: "実資金を伴う判断向け。重要な主張をすべて原典確認、独立再計算、反証検索にかける。",
+        ko: "실제 자금이 걸린 판단용. 핵심 주장을 모두 원출처 확인, 독립 재계산, 반증 검색에 부친다.",
+      }),
     },
   ];
 
@@ -179,16 +219,31 @@ export function councilOptions({ language = "English" } = {}) {
     all_master_ids: masterChoices.map((m) => m.id),
     all_masters_count: allMasters,
     verifiers: verifiers.map((id) => ({ id, title: personaTitle(reg.get(id), language) })),
-    how_to_ask: chinese ? [
-      "每次新的委员会运行都先展示逐席名单，并要求用户选择至少 1 位大师；可以单选、任意多选或全选。",
-      "用户已经点名时，把这些席位预选出来，但仍要展示名单并让用户提交本次选择。旧运行的选择不能自动复用。",
-      "优先使用宿主原生多选；容纳不了完整名单时，展示固定编号表，并接受编号、稳定 ID 或 all。",
-      "选择提交本身就是确认。不要再追加第二个确认问题，但没有 selection receipt 就不能开始研究。",
-    ] : [
-      "Before every new council run, show the individual catalog and require at least one master selection. The user may pick one, any combination, or all.",
-      "If the request already names masters, preselect them, but still show the catalog and require a submission for this run. Never reuse an old run's selection silently.",
-      "Prefer a host-native multi-select. If it cannot hold the full catalog, show the stable numbered table and accept numbers, stable IDs, or all.",
-      "Submitting the selection is the confirmation. Do not add another confirmation question, but do not start research without a selection receipt.",
-    ],
+    how_to_ask: copy({
+      en: [
+        "Before every new council run, show the individual catalog and require at least one master selection. The user may pick one, any combination, or all.",
+        "If the request already names masters, preselect them, but still show the catalog and require a submission for this run. Never reuse an old run's selection silently.",
+        "Prefer a host-native multi-select. If it cannot hold the full catalog, show the stable numbered table and accept numbers, stable IDs, or all.",
+        "Submitting the selection is the confirmation. Do not add another confirmation question, but do not start research without a selection receipt.",
+      ],
+      zh: [
+        "每次新的委员会运行都先展示逐席名单，并要求用户选择至少 1 位大师；可以单选、任意多选或全选。",
+        "用户已经点名时，把这些席位预选出来，但仍要展示名单并让用户提交本次选择。旧运行的选择不能自动复用。",
+        "优先使用宿主原生多选；容纳不了完整名单时，展示固定编号表，并接受编号、稳定 ID 或 all。",
+        "选择提交本身就是确认。不要再追加第二个确认问题，但没有 selection receipt 就不能开始研究。",
+      ],
+      ja: [
+        "新しい委員会実行の前に必ず席ごとの一覧を表示し、少なくとも1つのマスター席を選んでもらう。単独、複数、全選択が可能。",
+        "依頼文でマスターが指定済みでも、事前選択として表示したうえで今回の選択送信を求める。以前の実行の選択を黙って再利用しない。",
+        "ホストの複数選択を優先し、一覧を収められない場合は固定番号表を示して番号、stable ID、allを受け付ける。",
+        "選択の送信自体を確定とする。二重確認は追加しないが、selection receiptなしで調査を開始しない。",
+      ],
+      ko: [
+        "새 위원회 실행 전에는 좌석별 목록을 모두 보여 주고 최소 1개 마스터 좌석을 선택받는다. 단일, 복수, 전체 선택이 가능하다.",
+        "요청에 마스터가 이미 지정되어 있어도 사전 선택으로 표시한 뒤 이번 실행의 선택 제출을 받아야 한다. 이전 실행의 선택을 조용히 재사용하지 않는다.",
+        "호스트의 다중 선택 기능을 우선하고, 전체 목록을 담을 수 없으면 고정 번호표를 보여 준 뒤 번호, stable ID 또는 all을 받는다.",
+        "선택 제출 자체가 확정이다. 두 번째 확인 질문은 추가하지 않지만 selection receipt 없이는 조사를 시작하지 않는다.",
+      ],
+    }),
   };
 }

package/mcp/lib/council-selection.mjs

@@ -5,6 +5,7 @@ import { COUNCIL_MODES, LIMITS, SELECTIONS_DIR } from "./constants.mjs";
 import { councilOptions } from "./council-options.mjs";
 import { invalidParams } from "./errors.mjs";
 import { readJson, writeJson } from "./fsutil.mjs";
+import { resolveLanguage } from "./lang.mjs";
 import { safeSymbol } from "./run-store.mjs";
 import { cleanupSelectionStore } from "./selection-cleanup.mjs";
 import { ensureSelectionLockStore, withSelectionLock } from "./selection-locks.mjs";
@@ -12,11 +13,34 @@ import { ensureSelectionLockStore, withSelectionLock } from "./selection-locks.m
 const SELECTION_ID = /^SEL-[0-9a-f-]{36}$/i;
 const RECEIPT_ID = /^RCP-[0-9a-f-]{36}$/i;
 const QUICK_MASTER_MAX = 4;
+const SUPPORTED_SELECTION_LANGUAGES = Object.freeze(["中文", "English", "日本語", "한국어"]);
 
 function digest(value) {
   return createHash("sha256").update(JSON.stringify(value)).digest("hex");
 }
 
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function receiptSelectionHash(receipt) {
+  return digest({
+    schema_version: receipt.schema_version,
+    selection_receipt: receipt.selection_receipt,
+    selection_id: receipt.selection_id,
+    symbol: receipt.symbol,
+    council_mode: receipt.council_mode,
+    catalog_hash: receipt.catalog_hash,
+    request_hash: receipt.request_hash,
+    intent_hash: receipt.intent_hash,
+    selected_master_ids: receipt.selected_master_ids,
+    selected_master_pack_hashes: receipt.selected_master_pack_hashes,
+    selection_mode: receipt.selection_mode,
+    created_at: receipt.created_at,
+    expires_at: receipt.expires_at,
+  });
+}
+
 function councilMode(value) {
   const mode = value === undefined ? "full" : String(value);
   if (!COUNCIL_MODES.includes(mode)) {
@@ -27,6 +51,21 @@ function councilMode(value) {
   return mode;
 }
 
+function selectionLanguage(args = {}) {
+  const language = resolveLanguage({ language: args.language, prompt: args.prompt });
+  if (!SUPPORTED_SELECTION_LANGUAGES.includes(language)) {
+    throw invalidParams(
+      `Selection language ${JSON.stringify(language)} is unsupported. Use zh-CN, en-US, ja-JP or ko-KR.`,
+      {
+        reason: "UNSUPPORTED_SELECTION_LANGUAGE",
+        requested_language: args.language ?? null,
+        supported_languages: ["zh-CN", "en-US", "ja-JP", "ko-KR"],
+      },
+    );
+  }
+  return language;
+}
+
 function ensureStore() {
   ensureSelectionLockStore(SELECTIONS_DIR);
 }
@@ -76,7 +115,8 @@ function markExpired(record) {
 }
 
 export function catalogSnapshot(language = "English") {
-  const options = councilOptions({ language });
+  const effectiveLanguage = selectionLanguage({ language });
+  const options = councilOptions({ language: effectiveLanguage });
   const catalog = {
     schema_version: 1,
     language: options.language,
@@ -94,8 +134,8 @@ export function beginCouncilSelection(args = {}, { now = Date.now() } = {}) {
   // performed before the new record exists and never follows symlinks or unknown names.
   cleanupSelectionStore({ selectionsDir: SELECTIONS_DIR, now });
   const symbol = safeSymbol(args.symbol);
-  const language = String(args.language || "English");
   const prompt = typeof args.prompt === "string" ? args.prompt : "";
+  const language = selectionLanguage({ language: args.language, prompt });
   const mode = councilMode(args.council_mode);
   const catalog = catalogSnapshot(language);
   const preselected = args.preselected_master_ids === undefined
@@ -349,12 +389,6 @@ function confirmCouncilSelectionUnlocked(args = {}, { now = Date.now() } = {}) {
     catalog_hash: record.catalog_hash,
     request_hash: record.request_hash,
     intent_hash: record.intent_hash,
-    selection_hash: digest({
-      selection_id: record.selection_id,
-      catalog_hash: record.catalog_hash,
-      council_mode: record.council_mode || "full",
-      selected_master_ids: record.selected_master_ids,
-    }),
     selected_master_ids: record.selected_master_ids,
     selected_master_pack_hashes: selectedPackHashes,
     selection_mode: record.selection_mode,
@@ -363,6 +397,7 @@ function confirmCouncilSelectionUnlocked(args = {}, { now = Date.now() } = {}) {
     consumed_at: null,
     consumed_by_run_id: null,
   };
+  receiptRecord.selection_hash = receiptSelectionHash(receiptRecord);
   writeJson(selectionPath(record.selection_id), record);
   writeJson(receiptPath(receipt), receiptRecord);
   return confirmationResult(record);
@@ -388,6 +423,7 @@ function confirmationResult(record) {
     selection_receipt: record.selection_receipt,
     status: record.status,
     symbol: record.symbol,
+    language: record.language,
     council_mode: record.council_mode || "full",
     catalog_hash: record.catalog_hash,
     intent_hash: record.intent_hash,
@@ -406,7 +442,50 @@ function confirmationResult(record) {
 function consumeCouncilSelectionUnlocked(args = {}, { now = Date.now() } = {}) {
   ensureStore();
   const receipt = readReceipt(args.selection_receipt);
+  if (receipt.selection_receipt !== args.selection_receipt) {
+    throw invalidParams("The selection receipt file does not match its requested receipt id.", {
+      reason: "MASTER_SELECTION_RECORD_MISMATCH",
+      mismatched_fields: ["selection_receipt"],
+    });
+  }
   const selection = readSelection(receipt.selection_id);
+  const expectedPackHashes = Object.fromEntries(
+    selection.catalog.masters
+      .filter((master) => selection.selected_master_ids.includes(master.id))
+      .map((master) => [master.id, master.pack_hash]),
+  );
+  const recordBindings = [
+    ["schema_version", receipt.schema_version, selection.schema_version],
+    ["selection_id", receipt.selection_id, selection.selection_id],
+    ["selection_receipt", receipt.selection_receipt, selection.selection_receipt],
+    ["symbol", receipt.symbol, selection.symbol],
+    ["council_mode", receipt.council_mode || "full", selection.council_mode || "full"],
+    ["catalog_hash", receipt.catalog_hash, selection.catalog_hash],
+    ["request_hash", receipt.request_hash, selection.request_hash],
+    ["intent_hash", receipt.intent_hash, selection.intent_hash],
+    ["selected_master_ids", receipt.selected_master_ids, selection.selected_master_ids],
+    ["selection_mode", receipt.selection_mode, selection.selection_mode],
+    ["created_at", receipt.created_at, selection.confirmed_at],
+    ["expires_at", receipt.expires_at, selection.expires_at],
+  ];
+  const mismatchedBindings = recordBindings
+    .filter(([, receiptValue, selectionValue]) => !sameJson(receiptValue, selectionValue))
+    .map(([field]) => field);
+  if (mismatchedBindings.length) {
+    throw invalidParams("The selection receipt does not match its confirmed selection record.", {
+      reason: "MASTER_SELECTION_RECORD_MISMATCH",
+      mismatched_fields: mismatchedBindings,
+    });
+  }
+  if (!sameJson(receipt.selected_master_pack_hashes, expectedPackHashes)) {
+    throw invalidParams("The selected persona pack hashes do not match the confirmed selection record.", {
+      reason: "MASTER_SELECTION_PACK_HASH_MISMATCH",
+      mismatched_master_ids: [...new Set([
+        ...selection.selected_master_ids,
+        ...Object.keys(receipt.selected_master_pack_hashes || {}),
+      ])].filter((id) => receipt.selected_master_pack_hashes?.[id] !== expectedPackHashes[id]),
+    });
+  }
   const symbol = safeSymbol(args.symbol);
   if (receipt.symbol !== symbol || selection.symbol !== symbol) {
     throw invalidParams(`Selection receipt is for ${receipt.symbol}, not ${symbol}.`, {
@@ -434,8 +513,15 @@ function consumeCouncilSelectionUnlocked(args = {}, { now = Date.now() } = {}) {
       mismatched_master_ids: mismatchedPackHashes,
     });
   }
-  const language = String(args.language || "English");
+  const expectedSelectionHash = receiptSelectionHash(receipt);
+  if (receipt.selection_hash !== expectedSelectionHash) {
+    throw invalidParams("The selection receipt hash is invalid.", {
+      reason: "MASTER_SELECTION_HASH_MISMATCH",
+      expected_selection_hash: expectedSelectionHash,
+    });
+  }
   const prompt = typeof args.prompt === "string" ? args.prompt : "";
+  const language = selectionLanguage({ language: args.language, prompt });
   const mode = councilMode(args.council_mode);
   if ((receipt.council_mode || "full") !== mode || (selection.council_mode || "full") !== mode) {
     throw invalidParams("The selection receipt belongs to a different council mode.", {

package/mcp/lib/damodaran.mjs

@@ -0,0 +1,119 @@
+/**
+ * Damodaran's monthly implied equity risk premium, with its history.
+ *
+ * The premium the market is actually pricing is the input a valuation method compares against,
+ * and it is the one number here that no other free source publishes. It also carries the
+ * history that makes a percentile meaningful: "the ERP is 4.2%" says nothing without "which is
+ * the Nth percentile since 2008".
+ *
+ * Published as an .xlsx, which is why this is readable at all -- see `xlsx.mjs`. Before that
+ * reader existed the whole series was an explicit gap with a URL attached.
+ */
+
+import { LIMITS } from "./constants.mjs";
+import { excelSerialToIso, readWorkbook } from "./xlsx.mjs";
+
+export const ERP_MONTHLY_URL = "https://pages.stern.nyu.edu/~adamodar/pc/implprem/ERPbymonth.xlsx";
+
+/** Column headers, matched by text: the sheet gains columns between vintages. */
+const COLUMNS = Object.freeze({
+  month: "Start of month",
+  index_level: "S&P 500",
+  bond_rate: "T.Bond Rate",
+  // The trailing-twelve-month premium is the headline series; the others are variants of it.
+  erp: "ERP (T12m)",
+});
+
+const numeric = (cell) => {
+  const value = Number(cell);
+  return Number.isFinite(value) ? value : null;
+};
+
+export function parseErpWorkbook(buffer) {
+  // Two sheets carry the series: a long history that lags, and a rolling last-twelve-months
+  // sheet that is current. Reading only the first makes an up-to-date dataset look years
+  // stale, so both are merged and the later observation wins on a shared month.
+  const { sheets, date1904 } = readWorkbook(buffer);
+  // Each sheet carries its own header; columns are resolved per sheet rather than once.
+  const byDate = new Map();
+  for (const sheet of sheets) {
+    const headerRow = sheet.rows.findIndex((row) => row?.[0] === COLUMNS.month || row?.[0] === "Date");
+    if (headerRow < 0) continue;
+    const header = sheet.rows[headerRow];
+    const columnOf = (...labels) => header.findIndex((cell) => labels.includes(String(cell || "").trim()));
+    const at = {
+      month: 0,
+      indexLevel: columnOf(COLUMNS.index_level),
+      bondRate: columnOf(COLUMNS.bond_rate, "10-year US Treasury"),
+      erp: columnOf(COLUMNS.erp, "ERP"),
+    };
+    if (at.erp < 0) continue;
+    for (const row of sheet.rows.slice(headerRow + 1)) {
+      const date = excelSerialToIso(row?.[at.month], { date1904 });
+      const erp = numeric(row?.[at.erp]);
+      // A month with no premium is dropped rather than interpolated: this is a published
+      // series, and a value nobody published is not an observation.
+      if (!date || erp === null) continue;
+      byDate.set(date, {
+        date,
+        erp,
+        bond_rate: at.bondRate >= 0 ? numeric(row?.[at.bondRate]) : null,
+        index_level: at.indexLevel >= 0 ? numeric(row?.[at.indexLevel]) : null,
+      });
+    }
+  }
+  const observations = [...byDate.values()].sort((left, right) => left.date.localeCompare(right.date));
+  if (!observations.length) throw new Error("ERP workbook produced no dated observations");
+  return observations;
+}
+
+/**
+ * Where the latest premium sits in its own published history.
+ *
+ * Reported with the sample it ranked against, matching the contract the other feeds use: a
+ * percentile without its window is not a fact a method can act on.
+ */
+export function erpPercentile(observations, { sinceDays = 365 * 20 } = {}) {
+  if (!Array.isArray(observations) || observations.length < 24) return null;
+  const latest = observations.at(-1);
+  const cutoff = new Date(`${latest.date}T00:00:00Z`);
+  cutoff.setUTCDate(cutoff.getUTCDate() - sinceDays);
+  const start = cutoff.toISOString().slice(0, 10);
+  const sample = observations.filter((row) => row.date >= start);
+  if (sample.length < 24) return null;
+  const below = sample.filter((row) => row.erp < latest.erp).length;
+  return {
+    percentile: Number((below / sample.length).toFixed(4)),
+    sample_size: sample.length,
+    sample_start: sample[0].date,
+    sample_end: latest.date,
+  };
+}
+
+export async function fetchImpliedErp({ signal, asOf = null } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), LIMITS.QUOTE_FETCH_MS * 3);
+  if (signal) signal.addEventListener("abort", () => controller.abort(), { once: true });
+  try {
+    const response = await fetch(ERP_MONTHLY_URL, { signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const all = parseErpWorkbook(Buffer.from(await response.arrayBuffer()));
+    const visible = asOf ? all.filter((row) => row.date <= String(asOf).slice(0, 10)) : all;
+    if (!visible.length) throw new Error(`no ERP observation at or before ${asOf}`);
+    const latest = visible.at(-1);
+    return Object.freeze({
+      source: "damodaran_implied_erp_monthly",
+      source_url: ERP_MONTHLY_URL,
+      observations: visible,
+      latest: latest.erp,
+      bond_rate: latest.bond_rate,
+      observation_date: latest.date,
+      // The publication anchor is the month the observation belongs to, not the fetch time.
+      public_at: `${latest.date}T00:00:00.000Z`,
+      percentile: erpPercentile(visible),
+      basis: "damodaran_trailing_twelve_month_implied_erp",
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}