alphacouncil-agent 0.9.4 → 1.0.1

package/knowledge/solo-test/persona-v3-solo-test-formulas/master_thorp/components/tools.json

@@ -1,11 +1,11 @@
 [
   {
     "assurance_class": "provisional_derived_proxy",
-    "derivation_evidence_hash": "sha256:2ba3ac5b35cc5602ce88a5ba7571d134cec1d2e9390b0dab4f2a80b6bb9649b0",
-    "derivation_spec_hash": "sha256:a495305aa77816f76fc7d6abe38f8b8ff3a79c6d17b67b84a8ef7e2383adfeca",
-    "derivation_spec_id": "master_thorp.edge_recalculator.prototype_v1.derived_proxy_v1",
+    "derivation_evidence_hash": "sha256:b85e21489b9a580f5bb3a2b8e7a537320277a23029675c607ae52d6d300a1657",
+    "derivation_spec_hash": "sha256:09e268a0fc88ee1fc5ece944be7ed8b15c1109eac01d6346cbf4452c9d380533",
+    "derivation_spec_id": "master_thorp.net_edge.prototype_v1.derived_proxy_v1",
     "dsl_version": "1.1",
-    "id": "master_thorp.edge_recalculator",
+    "id": "master_thorp.net_edge",
     "input_contracts": [
       {
         "on_missing": "fail",
@@ -14,44 +14,57 @@
           "basis": "instant",
           "window": null
         },
-        "unit": "derived_proxy_scalar",
-        "value_kind": "scalar"
+        "unit": "decimal",
+        "value_kind": "ratio"
+      },
+      {
+        "on_missing": "fail",
+        "period": {
+          "alignment": "as_of",
+          "basis": "instant",
+          "window": null
+        },
+        "unit": "decimal_of_mid",
+        "value_kind": "ratio"
       }
     ],
-    "input_schema_hash": "sha256:3c5f60644db4db6ee74254cf6078d73408e0390add348af4ab9d86a39f6c6ddd",
+    "input_schema_hash": "sha256:1b2e9ab2dcebe05a8d4a1d93746ac0ec592cc0a156c36b818d261e11aeb00d53",
     "inputs": [
       {
-        "fact_id": "probability.outcome_distribution"
+        "fact_id": "market.change_pct"
+      },
+      {
+        "fact_id": "execution.bid_ask"
       }
     ],
     "intended_use": "local_test_only",
-    "kind": "transform",
+    "kind": "recomputation",
     "on_missing": "fail",
-    "operation": "identity",
-    "output_id": "trade.edge",
+    "operation": "subtract",
+    "output_id": "trade.net_edge.master_thorp",
     "output_period": {
       "alignment": "as_of",
       "basis": "instant",
       "window": null
     },
-    "output_schema_hash": "sha256:f1212b5057a48fbc57f4c14f69c5b39c9eb37eadcf094116021ec58215bfd373",
+    "output_schema_hash": "sha256:9f96e26d5e549ade4e9e7f680eafd0a33d546cba620cd79dd757ca7cce8816e5",
     "production_eligible": false,
     "review_status": "not_human_reviewed",
     "schema_version": 1,
     "source_ids": [
-      "derived_proxy:master_thorp.edge_recalculator.prototype_v1"
+      "derived_proxy:master_thorp.net_edge.prototype_v1"
     ],
-    "unit": "derived_proxy_scalar",
-    "value_kind": "scalar",
-    "version": "0.1.0"
+    "unit": "decimal",
+    "value_kind": "ratio",
+    "version": "0.2.0"
   },
   {
     "assurance_class": "provisional_derived_proxy",
-    "derivation_evidence_hash": "sha256:e480491cd694394c9708f3c551753d0d74282f724fdb03a57b1845f28ed63a80",
-    "derivation_spec_hash": "sha256:f8f0d4ff36cadb45ee57fd18d6b83145601ee86e19c1d10fd23a905283aaadbf",
-    "derivation_spec_id": "master_thorp.fractional_kelly.prototype_v1.derived_proxy_v1",
+    "derivation_evidence_hash": "sha256:374b03940179a910863933294ea9670db249d921fb7e3249e0c6dd091d8af99a",
+    "derivation_spec_hash": "sha256:a6dd488d25efb31022335ad6f444940ca8def0a055f8c4ab720ddb82374a7cd1",
+    "derivation_spec_id": "master_thorp.edge_per_unit_of_volatility.prototype_v1.derived_proxy_v1",
     "dsl_version": "1.1",
-    "id": "master_thorp.fractional_kelly",
+    "id": "master_thorp.edge_per_unit_of_volatility",
     "input_contracts": [
       {
         "on_missing": "fail",
@@ -60,35 +73,48 @@
           "basis": "instant",
           "window": null
         },
-        "unit": "derived_proxy_scalar",
-        "value_kind": "scalar"
+        "unit": "decimal",
+        "value_kind": "ratio"
+      },
+      {
+        "on_missing": "fail",
+        "period": {
+          "alignment": "as_of",
+          "basis": "instant",
+          "window": null
+        },
+        "unit": "decimal_annualized_volatility",
+        "value_kind": "ratio"
       }
     ],
-    "input_schema_hash": "sha256:6d0533ff016072d0f863ca19905311240bb6fc61554ceeea5bb686832e02d1b7",
+    "input_schema_hash": "sha256:589099421150597f448dad9a097aef60b96a8beb7e9eb7b1fef066305153690c",
     "inputs": [
       {
-        "fact_id": "risk.ruin_probability"
+        "output_id": "trade.net_edge.master_thorp"
+      },
+      {
+        "fact_id": "options.implied_volatility"
       }
     ],
     "intended_use": "local_test_only",
-    "kind": "transform",
+    "kind": "recomputation",
     "on_missing": "fail",
-    "operation": "identity",
-    "output_id": "position.fraction",
+    "operation": "divide",
+    "output_id": "trade.edge_per_unit_of_volatility.master_thorp",
     "output_period": {
       "alignment": "as_of",
       "basis": "instant",
       "window": null
     },
-    "output_schema_hash": "sha256:38381ae45c00286d05262d3458746edd6cd46cc637c3099692bfc345cbb2696b",
+    "output_schema_hash": "sha256:58d54e4438d5c1423d53dcbbfc391b7b70bcb41083f5df9230432bc419184a43",
     "production_eligible": false,
     "review_status": "not_human_reviewed",
     "schema_version": 1,
     "source_ids": [
-      "derived_proxy:master_thorp.fractional_kelly.prototype_v1"
+      "derived_proxy:master_thorp.edge_per_unit_of_volatility.prototype_v1"
     ],
-    "unit": "derived_proxy_scalar",
-    "value_kind": "scalar",
-    "version": "0.1.0"
+    "unit": "decimal",
+    "value_kind": "ratio",
+    "version": "0.2.0"
   }
 ]

package/knowledge/solo-test/persona-v3-solo-test-formulas/master_thorp/provisional-derivations/edge_per_unit_of_volatility.derived-proxy-evidence.json

@@ -0,0 +1,77 @@
+{
+  "artifact_kind": "persona_v3_provisional_formula_derivation_evidence",
+  "assurance_class": "provisional_derived_proxy",
+  "derivation_spec": {
+    "artifact_kind": "persona_v3_provisional_formula_derivation_spec",
+    "assurance_class": "provisional_derived_proxy",
+    "authoring_candidate_hash": "sha256:4d328d7bfb15575aad0df48c2431e55b692b96198230808c48b8d12e65bb145b",
+    "derivation_policy": "ai_authored_method_formula_v1",
+    "derivation_spec_id": "master_thorp.edge_per_unit_of_volatility.prototype_v1.derived_proxy_v1",
+    "formula": {
+      "inputs": [
+        {
+          "on_missing": "fail",
+          "operand": {
+            "output_id": "trade.net_edge.master_thorp"
+          },
+          "period": {
+            "alignment": "as_of",
+            "basis": "instant",
+            "window": null
+          },
+          "unit": "decimal",
+          "value_kind": "ratio"
+        },
+        {
+          "on_missing": "fail",
+          "operand": {
+            "fact_id": "options.implied_volatility"
+          },
+          "period": {
+            "alignment": "as_of",
+            "basis": "instant",
+            "window": null
+          },
+          "unit": "decimal_annualized_volatility",
+          "value_kind": "ratio"
+        }
+      ],
+      "kind": "recomputation",
+      "on_missing": "fail",
+      "operation": "divide",
+      "output": {
+        "output_id": "trade.edge_per_unit_of_volatility.master_thorp",
+        "period": {
+          "alignment": "as_of",
+          "basis": "instant",
+          "window": null
+        },
+        "unit": "decimal",
+        "value_kind": "ratio"
+      },
+      "version": "0.2.0"
+    },
+    "input_contract_source": "unknown_fact_fail_closed_proxy_scalar_v1",
+    "persona_id": "master_thorp",
+    "prototype_content_hash": "sha256:af33c7887d97bd0f25cec9a9d53be11efc3beb554952b2d280f45689f13baf8f",
+    "prototype_id": "master_thorp.edge_per_unit_of_volatility.prototype_v1",
+    "schema_version": 1,
+    "tool_id": "master_thorp.edge_per_unit_of_volatility"
+  },
+  "derivation_spec_hash": "sha256:a6dd488d25efb31022335ad6f444940ca8def0a055f8c4ab720ddb82374a7cd1",
+  "human_reviewer_ids": [],
+  "intended_use": "local_test_only",
+  "limitations": [
+    "ai_authored_candidate_formula_not_human_reviewed",
+    "thresholds_are_derived_from_published_method_writing_not_adjudicated",
+    "unknown_fact_proxy_scalar_unit_requires_a_local_test_adapter",
+    "no_human_formula_review_or_cryptographic_approval_exists",
+    "must_not_be_used_for_production_admission_release_or_method_model_claims"
+  ],
+  "method_model_eligible": false,
+  "production_effect": "none",
+  "production_eligible": false,
+  "review_status": "not_human_reviewed",
+  "schema_version": 1,
+  "signature_count": 0
+}

package/knowledge/solo-test/persona-v3-solo-test-formulas/master_thorp/provisional-derivations/net_edge.derived-proxy-evidence.json

@@ -0,0 +1,76 @@
+{
+  "artifact_kind": "persona_v3_provisional_formula_derivation_evidence",
+  "assurance_class": "provisional_derived_proxy",
+  "derivation_spec": {
+    "artifact_kind": "persona_v3_provisional_formula_derivation_spec",
+    "assurance_class": "provisional_derived_proxy",
+    "authoring_candidate_hash": "sha256:d3b8e93179f9c97e9fa5892910e77f45cb606ff7a85e7ae2ffe2a28ca546292a",
+    "derivation_policy": "ai_authored_method_formula_v1",
+    "derivation_spec_id": "master_thorp.net_edge.prototype_v1.derived_proxy_v1",
+    "formula": {
+      "inputs": [
+        {
+          "on_missing": "fail",
+          "operand": {
+            "fact_id": "market.change_pct"
+          },
+          "period": {
+            "alignment": "as_of",
+            "basis": "instant",
+            "window": null
+          },
+          "unit": "decimal",
+          "value_kind": "ratio"
+        },
+        {
+          "on_missing": "fail",
+          "operand": {
+            "fact_id": "execution.bid_ask"
+          },
+          "period": {
+            "alignment": "as_of",
+            "basis": "instant",
+            "window": null
+          },
+          "unit": "decimal_of_mid",
+          "value_kind": "ratio"
+        }
+      ],
+      "kind": "recomputation",
+      "on_missing": "fail",
+      "operation": "subtract",
+      "output": {
+        "output_id": "trade.net_edge.master_thorp",
+        "period": {
+          "alignment": "as_of",
+          "basis": "instant",
+          "window": null
+        },
+        "unit": "decimal",
+        "value_kind": "ratio"
+      },
+      "version": "0.2.0"
+    },
+    "input_contract_source": "grounding_adapter_canonical_contract_v1",
+    "persona_id": "master_thorp",
+    "prototype_content_hash": "sha256:af33c7887d97bd0f25cec9a9d53be11efc3beb554952b2d280f45689f13baf8f",
+    "prototype_id": "master_thorp.net_edge.prototype_v1",
+    "schema_version": 1,
+    "tool_id": "master_thorp.net_edge"
+  },
+  "derivation_spec_hash": "sha256:09e268a0fc88ee1fc5ece944be7ed8b15c1109eac01d6346cbf4452c9d380533",
+  "human_reviewer_ids": [],
+  "intended_use": "local_test_only",
+  "limitations": [
+    "ai_authored_candidate_formula_not_human_reviewed",
+    "thresholds_are_derived_from_published_method_writing_not_adjudicated",
+    "no_human_formula_review_or_cryptographic_approval_exists",
+    "must_not_be_used_for_production_admission_release_or_method_model_claims"
+  ],
+  "method_model_eligible": false,
+  "production_effect": "none",
+  "production_eligible": false,
+  "review_status": "not_human_reviewed",
+  "schema_version": 1,
+  "signature_count": 0
+}

package/mcp/lib/breadth.mjs

@@ -0,0 +1,126 @@
+/**
+ * Market breadth, computed from the basket rather than bought from a screener.
+ *
+ * "What fraction of the index is above its 200-day average" is the classic breadth reading,
+ * and every free source for it is either a screener whose robots.txt forbids the query or a
+ * vendor feed. But the question only ever concerns one basket at a time, and the holdings of
+ * that basket are already fetched -- so the honest way to get it is to compute it: one year of
+ * daily closes per constituent, one moving average each, count how many are above.
+ *
+ * That is a real cost, one request per name, which is why it is bounded and why the result
+ * always reports how much of the basket it actually measured. Breadth over 40% of the weights
+ * is a different claim from breadth over 95%, and a reader cannot tell them apart from the
+ * number alone.
+ */
+
+import { LIMITS } from "./constants.mjs";
+import { fetchText } from "./quotes.mjs";
+
+/** A 200-day average needs 200 closes; a year of trading gives about 252. */
+export const BREADTH_WINDOW_DAYS = 200;
+export const BREADTH_MIN_CLOSES = 200;
+export const BREADTH_MAX_SYMBOLS = 120;
+export const BREADTH_MIN_COVERAGE = 0.5;
+
+export const chartUrl = (symbol) => (
+  `https://query1.finance.yahoo.com/v8/finance/chart/${encodeURIComponent(symbol)}?range=1y&interval=1d`
+);
+
+/**
+ * Closing prices from a Yahoo chart payload, nulls removed.
+ *
+ * A halted or untraded session is written as null, not as the previous close. Dropping it is
+ * correct for an average; carrying it forward would invent a print.
+ */
+export function parseDailyCloses(json) {
+  const result = json?.chart?.result?.[0];
+  const closes = result?.indicators?.quote?.[0]?.close;
+  if (!Array.isArray(closes)) return null;
+  const clean = closes.filter((value) => typeof value === "number" && Number.isFinite(value) && value > 0);
+  return clean.length ? clean : null;
+}
+
+/** Simple moving average of the last `window` closes, or null when there is not enough history. */
+export function movingAverage(closes, window = BREADTH_WINDOW_DAYS) {
+  if (!Array.isArray(closes) || closes.length < window) return null;
+  const tail = closes.slice(-window);
+  return tail.reduce((sum, value) => sum + value, 0) / tail.length;
+}
+
+export function isAboveAverage(closes, window = BREADTH_WINDOW_DAYS) {
+  const average = movingAverage(closes, window);
+  if (average === null) return null;
+  return closes.at(-1) > average;
+}
+
+/**
+ * Weighted share of a basket trading above its own 200-day average.
+ *
+ * Weighted, not counted: a breadth reading that treats the largest and smallest holding alike
+ * describes a portfolio nobody owns. The unweighted count is returned alongside it, because
+ * the gap between the two IS the concentration story -- a cap-weighted basket can be above its
+ * average on weight while most of its members are below.
+ */
+export async function fetchBasketBreadth(holdings, { signal, concurrency = 8 } = {}) {
+  const unavailable = [];
+  const ranked = [...(holdings || [])]
+    .filter((row) => row?.ticker && Number.isFinite(row.weight) && row.weight > 0)
+    .sort((left, right) => right.weight - left.weight)
+    .slice(0, BREADTH_MAX_SYMBOLS);
+  if (!ranked.length) {
+    return { available: false, unavailable: ["breadth: the basket published no weighted holdings"] };
+  }
+
+  const measured = [];
+  const queue = [...ranked];
+  const worker = async () => {
+    for (let next = queue.shift(); next; next = queue.shift()) {
+      try {
+        const closes = parseDailyCloses(JSON.parse(await fetchText(chartUrl(next.ticker), LIMITS.QUOTE_FETCH_MS, signal)));
+        if (!closes || closes.length < BREADTH_MIN_CLOSES) {
+          unavailable.push(`breadth ${next.ticker}: fewer than ${BREADTH_MIN_CLOSES} daily closes in the last year`);
+          continue;
+        }
+        const above = isAboveAverage(closes);
+        if (above === null) continue;
+        measured.push({ ticker: next.ticker, weight: next.weight, above, close: closes.at(-1), units: next.units });
+      } catch (error) {
+        unavailable.push(`breadth ${next.ticker}: ${String(error?.message || error)}`);
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, ranked.length) }, worker));
+
+  const coverage = measured.reduce((sum, row) => sum + row.weight, 0);
+  if (!measured.length || coverage < BREADTH_MIN_COVERAGE) {
+    unavailable.push(
+      `breadth: measured ${(coverage * 100).toFixed(1)}% of basket weight, below the ${BREADTH_MIN_COVERAGE * 100}% floor`,
+    );
+    return { available: false, coverage_weight: Number(coverage.toFixed(6)), measured: measured.length, unavailable };
+  }
+  const aboveWeight = measured.filter((row) => row.above).reduce((sum, row) => sum + row.weight, 0);
+  const aboveCount = measured.filter((row) => row.above).length;
+  // The same closes price the basket. An issuer that publishes unit counts but no assets
+  // under management -- which is the common case outside the two largest -- gets its size
+  // from the positions it disclosed, rather than staying an unexplained blank.
+  const priced = measured.filter((row) => Number.isFinite(row.units) && row.units > 0);
+  const pricedWeight = priced.reduce((sum, row) => sum + row.weight, 0);
+  const netAssets = priced.reduce((sum, row) => sum + (row.units * row.close), 0);
+  return Object.freeze({
+    available: true,
+    // The last close per constituent, already fetched to compute breadth. A market
+    // capitalisation is a share count times a price, and this is the price -- re-fetching it
+    // would be forty quotes for numbers that are in hand.
+    closes: Object.freeze(Object.fromEntries(measured.map((row) => [row.ticker, row.close]))),
+    // Only meaningful when nearly the whole basket was priced; a partial sum is not the fund.
+    net_assets: pricedWeight >= 0.95 && netAssets > 0 ? Number(netAssets.toFixed(2)) : null,
+    net_assets_coverage: Number(pricedWeight.toFixed(6)),
+    weighted_above: Number((aboveWeight / coverage).toFixed(6)),
+    counted_above: Number((aboveCount / measured.length).toFixed(6)),
+    coverage_weight: Number(coverage.toFixed(6)),
+    measured: measured.length,
+    window_days: BREADTH_WINDOW_DAYS,
+    method: "share_of_constituents_trading_above_their_own_200_day_simple_average",
+    unavailable,
+  });
+}

package/mcp/lib/constants.mjs

@@ -58,6 +58,19 @@ export const OUTPUT_MODES = [
  * section body must carry, calibrated against the manager fallback report, which emits
  * several legitimately terse sections ("## Confidence\nmedium").
  */
+/**
+ * Anchors for the system-owned publication sections.
+ *
+ * The quality gate must never locate these by heading text. A PM-authored section is
+ * relabelled rather than deleted, and several of those localized commentary titles legally
+ * contain a section alias -- the Japanese label "PMによるメソッド席の説明" contains the
+ * `master_bench` alias "メソッド席". Heading assignment keeps the richest body, so the
+ * commentary could win the assignment and every per-seat coverage check would then fail
+ * against PM prose, leaving the report permanently unpublishable in ja/ko.
+ */
+export const RECORDED_BENCH_MARKER_PREFIX = "alphacouncil:recorded-master-bench:v1:";
+export const RECORDED_INSTRUMENT_MARKER_PREFIX = "alphacouncil:recorded-instrument-structure:v1:";
+
 export const REPORT_SECTIONS = [
   { id: "conclusion", aliases: ["结论", "conclusion", "結論", "결론"], min_body: 6 },
   { id: "analyst_work_log", aliases: ["分析师工作记录", "analyst work log", "アナリスト作業記録", "分析担当作業記録", "분석가 작업 기록"], min_body: 12, per_task: true },
@@ -66,6 +79,7 @@ export const REPORT_SECTIONS = [
   // then mentions none of them is the defect this entry exists to catch; a screen-only
   // run that never selected one must not be failed for omitting it.
   { id: "master_bench", aliases: ["大师席", "master席位", "master bench", "master lens", "マスターベンチ", "マスター・ベンチ", "メソッド席", "마스터 벤치", "방법론 좌석"], min_body: 20, when_masters: true },
+  { id: "instrument_structure", aliases: ["基金与指数结构", "ETF与指数结构", "资产结构与穿透", "fund and index structure", "instrument structure and look through", "ETF index structure", "ファンドと指数の構造", "資産構造とルックスルー", "펀드와 지수 구조", "자산 구조 및 룩스루"], min_body: 40, when_fund_or_index: true },
   { id: "market_expectations", aliases: ["市场预期", "market expectations", "市場予想", "市場期待", "시장 기대"], min_body: 8 },
   { id: "analyst_rating", aliases: ["分析师评级", "analyst rating", "target price", "アナリスト評価", "目標株価", "애널리스트 등급", "목표가"], min_body: 8 },
   { id: "earnings_call", aliases: ["电话会", "earnings call", "決算説明会", "실적 발표 콜"], min_body: 8 },
@@ -100,6 +114,7 @@ const QUICK_REPORT_SECTION_IDS = new Set([
   "analyst_work_log",
   "debate_record",
   "master_bench",
+  "instrument_structure",
   "earnings_call",
   "news",
   "valuation",

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);
+  }
+}