canli-backtest-mcp 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canli-backtest-mcp",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "MCP server for backtests that refuse lookahead: point-in-time factors from SEC filings, cross-sectional backtests of any signal on your own prices, costs on actual trades, and every variant counted in a trial ledger.",
   "private": false,
   "type": "module",
@@ -20,9 +20,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.3.1",
-    "canli-fundamentals-mcp": "^0.5.0",
+    "canli-fundamentals-mcp": "^0.7.0",
+    "canli-markets-mcp": "^0.6.0",
     "canli-validation-mcp": "^0.14.0",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1"
@@ -51,5 +52,8 @@
     "overfitting",
     "factor-investing",
     "ai-agents"
-  ]
+  ],
+  "overrides": {
+    "zod": "4.6.7"
+  }
 }

package/src/annotate.mjs

@@ -0,0 +1,251 @@
+// Annotation: turn figures into a labelled dataset that people have checked against the filings.
+//
+// annotation_packet takes figures (company, measure, period, value), labels each one by machine
+// against the company's XBRL filings (verify_claims: confirmed, contradicted, not reported or not
+// checkable, with the filed figure and its source), and writes one packet per annotator as a CSV a
+// person fills in, a key with the machine labels, and the guidelines. Packets are blind by default:
+// they carry the source link, not the machine's verdict or the filed figure, so a person's label is
+// their own and can be compared with the machine's afterwards.
+// annotation_agreement reads the filled packets: agreement and Cohen's kappa between annotators,
+// and between the people and the machine, with every disagreement listed.
+// annotation_gold merges them into a gold set (unanimous labels, then a reviewer's decisions),
+// writes it as JSONL with a datasheet, and hashes every input so the set can be traced.
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { z } from "zod";
+
+import { createSession as marketsSession } from "canli-markets-mcp/src/sources.mjs";
+import { verifyClaims } from "canli-markets-mcp/src/verify.mjs";
+
+export const LABELS = Object.freeze(["confirmed", "contradicted", "not_reported", "cannot_find"]);
+const COLUMNS = ["item_id", "company", "measure", "period", "claimed", "unit", "source", "label", "correct_value", "note"];
+const sha = (x) => createHash("sha256").update(x).digest("hex");
+const filePath = z.string().min(1).max(1000).refine((s) => !s.includes("\0"), "a file path cannot contain a NUL character");
+
+const item = z.object({
+  company: z.string().min(1).max(120),
+  measure: z.string().min(2).max(80),
+  period: z.string().min(2).max(60),
+  value: z.number(),
+  unit: z.string().max(30).optional(),
+  note: z.string().max(500).optional(),
+}).strict();
+
+export const packetInput = z.object({
+  task: z.string().regex(/^[a-z0-9][a-z0-9-]{2,63}$/).describe("A name for the task, e.g. q3-revenue-check: the folder the files go in."),
+  items: z.array(item).min(1).max(200).optional().describe("Figures to label: company, measure, period, value (and unit), as for verify_claims."),
+  items_file: filePath.optional().describe("Or a JSONL file of the same objects, up to 2,000."),
+  text: z.string().min(10).max(6000).optional().describe("Or a draft about one company (an AI's answer, say): every figure in it with a measure and a period becomes an item. Needs company."),
+  company: z.string().min(1).max(120).optional().describe("With text: the company the draft is about."),
+  annotators: z.number().int().min(1).max(5).optional().describe("Packets to write, one per person. Default 2: two people label every item independently."),
+  assisted: z.boolean().optional().describe("Show the machine's label and the filed figure in the packets. Default false (blind), so agreement with the machine means something."),
+  out_dir: filePath.optional().describe("Folder for the task folder. Default: a new temporary folder."),
+}).strict();
+export const agreementInput = z.object({ task_dir: filePath.describe("The folder annotation_packet wrote, with the filled packets in it.") }).strict();
+export const goldInput = z.object({
+  task_dir: filePath.describe("The folder annotation_packet wrote, with the filled packets in it."),
+  reviews: z.array(z.object({ item_id: z.string().max(40), label: z.enum(LABELS), correct_value: z.number().optional(), note: z.string().max(500).optional() }).strict()).max(2000).optional()
+    .describe("A reviewer's decisions on items the annotators disagreed on."),
+}).strict();
+
+// ---- CSV ---------------------------------------------------------------------------------------------
+const quote = (v) => { const s = v === null || v === undefined ? "" : String(v); return /[",\n\r]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s; };
+export const toCsv = (rows) => rows.map((r) => r.map(quote).join(",")).join("\n") + "\n";
+export function parseCsv(text) {
+  const rows = [], s = text.replace(/^/, "");
+  let row = [], cell = "", q = false;
+  for (let i = 0; i < s.length; i += 1) {
+    const ch = s[i];
+    if (q) { if (ch === '"') { if (s[i + 1] === '"') { cell += '"'; i += 1; } else q = false; } else cell += ch; continue; }
+    if (ch === '"') q = true;
+    else if (ch === ",") { row.push(cell); cell = ""; }
+    else if (ch === "\n" || ch === "\r") { if (ch === "\r" && s[i + 1] === "\n") i += 1; row.push(cell); cell = ""; if (row.some((x) => x !== "")) rows.push(row); row = []; }
+    else cell += ch;
+  }
+  if (cell !== "" || row.length) { row.push(cell); if (row.some((x) => x !== "")) rows.push(row); }
+  return rows;
+}
+
+const GUIDELINES = `# Labelling guidelines (canli.annotation.v1)
+
+Work alone. Do not compare labels with anyone until every packet is in.
+
+For each row, open the link in \`source\` (the filing, or SEC's record of the company's XBRL facts),
+find the figure for the company, measure and period, and set \`label\` to one of:
+
+- \`confirmed\`: the filing reports this figure for this period, after its own scaling ("in
+  millions") and to the precision the claim is written in (416.2 billion matches 416,161 million).
+- \`contradicted\`: the filing reports a different figure. Put the filed figure, in the claim's unit,
+  in \`correct_value\`.
+- \`not_reported\`: the company's filings do not report this measure for this period.
+- \`cannot_find\`: you could not settle it. Say where you looked in \`note\`.
+
+A restated figure: label against the latest filing and say in \`note\` that it was restated.
+Non-GAAP or adjusted figures are judged against the company's own reconciliation; say so in \`note\`.
+`;
+
+// ---- packets ------------------------------------------------------------------------------------------
+// session: a canli-markets-mcp session (SEC requests, cache, clock); one is made when none is given.
+export async function annotationPacket(session, args) {
+  session ??= marketsSession();
+  const a = packetInput.parse(args);
+  let items = a.items ?? [];
+  if (a.items_file) items = items.concat(readFileSync(a.items_file, "utf8").split(/\r?\n/).filter((l) => l.trim()).map((l, i) => {
+    try { return item.parse(JSON.parse(l)); } catch (e) { throw new RangeError(`items_file line ${i + 1}: ${e.message}`); }
+  }));
+  // A draft: verify_claims finds its figures and labels them in the same pass.
+  let fromText = null;
+  if (a.text) {
+    if (!a.company) throw new RangeError("text needs company: the company the draft is about.");
+    const r = await verifyClaims(session, { company: a.company, text: a.text });
+    const col = (name) => r.columns.indexOf(name);
+    fromText = r.rows.map((row) => ({ item: { company: a.company, measure: String(row[col("measure")]), period: String(row[col("period")]), value: Number(row[col("claimed")]), ...(row[col("unit")] ? { unit: String(row[col("unit")]) } : {}), note: String(row[col("claim")] ?? "").slice(0, 500) },
+      machine: { verdict: row[col("verdict")] ?? null, filed: row[col("filed")] ?? null, note: row[col("note")] ?? null, source: row[col("source")] ?? null } })).filter((x) => Number.isFinite(x.item.value));
+    items = items.concat(fromText.map((x) => x.item));
+  }
+  if (!items.length) throw new RangeError(a.text ? "The draft has no figure with a measure and a period to label." : "Send items, items_file or text.");
+  if (items.length > 2000) throw new RangeError("At most 2,000 items in one task.");
+  // Machine labels: verify_claims per company, 25 claims a call.
+  const machine = new Array(items.length);
+  const byCompany = new Map();
+  items.forEach((it, i) => { if (!byCompany.has(it.company)) byCompany.set(it.company, []); byCompany.get(it.company).push(i); });
+  // Items from a draft already carry their machine labels.
+  const preset = items.length - (fromText?.length ?? 0);
+  fromText?.forEach((x, k) => { machine[preset + k] = x.machine; });
+  for (const [company, allIdx] of byCompany) {
+    const idx = allIdx.filter((i) => i < preset);
+    for (let k = 0; k < idx.length; k += 25) {
+      const part = idx.slice(k, k + 25);
+      try {
+        const r = await verifyClaims(session, { company, claims: part.map((i) => ({ measure: items[i].measure, period: items[i].period, value: items[i].value, ...(items[i].unit ? { unit: items[i].unit } : {}) })) });
+        const col = (name) => r.columns.indexOf(name);
+        part.forEach((i, j) => { const row = r.rows[j] ?? []; machine[i] = { verdict: row[col("verdict")] ?? null, filed: row[col("filed")] ?? null, note: row[col("note")] ?? null, source: row[col("source")] ?? null }; });
+      } catch (e) {
+        for (const i of part) machine[i] = { verdict: "not_checkable", filed: null, note: `machine check failed: ${String(e.message).slice(0, 200)}`, source: null };
+      }
+    }
+  }
+  const ids = items.map((it) => sha(JSON.stringify([it.company, it.measure, it.period, it.value, it.unit ?? null])).slice(0, 12));
+  const dir = join(a.out_dir ?? mkdtempSync(join(tmpdir(), "canli-annotation-")), a.task);
+  mkdirSync(dir, { recursive: true });
+  const n = a.annotators ?? 2, assisted = a.assisted ?? false;
+  const packets = [];
+  for (let p = 1; p <= n; p += 1) {
+    const cols = assisted ? [...COLUMNS.slice(0, 7), "machine_label", "machine_filed", ...COLUMNS.slice(7)] : COLUMNS;
+    const rows = items.map((it, i) => [ids[i], it.company, it.measure, it.period, it.value, it.unit ?? "", machine[i].source ?? "", ...(assisted ? [machine[i].verdict, machine[i].filed] : []), "", "", ""]);
+    const file = join(dir, `annotator-${p}.csv`);
+    writeFileSync(file, toCsv([cols, ...rows]));
+    packets.push(file);
+  }
+  const key = { schema: "canli.annotation-key.v1", task: a.task, created_at: new Date(session.now?.() ?? Date.now()).toISOString(), assisted, annotators: n, labels: LABELS,
+    items: items.map((it, i) => ({ item_id: ids[i], ...it, machine: machine[i] })) };
+  writeFileSync(join(dir, "key.json"), JSON.stringify(key, null, 1));
+  writeFileSync(join(dir, "GUIDELINES.md"), GUIDELINES);
+  const counts = {};
+  for (const m of machine) counts[m.verdict] = (counts[m.verdict] ?? 0) + 1;
+  return {
+    task: a.task, task_dir: dir, items: items.length, packets, key: join(dir, "key.json"), guidelines: join(dir, "GUIDELINES.md"),
+    machine_labels: counts, blind: !assisted,
+    next: `Each person fills the label column of one packet (GUIDELINES.md says how), then annotation_agreement with task_dir ${dir}, then annotation_gold.`,
+  };
+}
+
+// ---- reading filled packets ----------------------------------------------------------------------------
+function readTask(dir) {
+  const key = JSON.parse(readFileSync(join(dir, "key.json"), "utf8"));
+  const packets = [];
+  for (let p = 1; p <= key.annotators; p += 1) {
+    const file = join(dir, `annotator-${p}.csv`), text = readFileSync(file, "utf8"), rows = parseCsv(text);
+    const head = rows[0], at = (name) => head.indexOf(name);
+    if (at("item_id") < 0 || at("label") < 0) throw new RangeError(`${file}: the header must keep item_id and label`);
+    const labels = new Map();
+    for (const [r, row] of rows.slice(1).entries()) {
+      const label = (row[at("label")] ?? "").trim().toLowerCase();
+      if (label && !LABELS.includes(label)) throw new RangeError(`${file} row ${r + 2}: label "${label}" is not one of ${LABELS.join(", ")}`);
+      const cv = (row[at("correct_value")] ?? "").trim();
+      labels.set(row[at("item_id")], { label: label || null, correct_value: cv === "" ? null : Number(cv), note: (row[at("note")] ?? "").trim() || null });
+    }
+    packets.push({ file, sha256: sha(text), labels });
+  }
+  return { key, packets };
+}
+
+// The machine's verdict on the annotation scale: not_checkable has no human counterpart.
+const MACHINE = { confirmed: "confirmed", "confirmed as first reported": "confirmed", contradicted: "contradicted", "not reported": "not_reported" };
+const machineLabel = (m) => MACHINE[m?.verdict] ?? null;
+
+export function kappa(pairs) {
+  const n = pairs.length;
+  if (!n) return { items: 0, agreement: null, kappa: null };
+  const agree = pairs.filter(([x, y]) => x === y).length / n;
+  let pe = 0;
+  for (const l of LABELS) pe += (pairs.filter(([x]) => x === l).length / n) * (pairs.filter(([, y]) => y === l).length / n);
+  return { items: n, agreement: Math.round(agree * 1e4) / 1e4, kappa: pe < 1 ? Math.round(((agree - pe) / (1 - pe)) * 1e4) / 1e4 : null };
+}
+
+export function annotationAgreement(args) {
+  const { task_dir } = agreementInput.parse(args);
+  const { key, packets } = readTask(task_dir);
+  const ids = key.items.map((x) => x.item_id);
+  const done = packets.map((p) => ids.filter((id) => p.labels.get(id)?.label).length);
+  const pairs = [];
+  for (let a = 0; a < packets.length; a += 1) for (let b = a + 1; b < packets.length; b += 1) {
+    const both = ids.filter((id) => packets[a].labels.get(id)?.label && packets[b].labels.get(id)?.label).map((id) => [packets[a].labels.get(id).label, packets[b].labels.get(id).label]);
+    pairs.push({ annotators: [a + 1, b + 1], ...kappa(both) });
+  }
+  // The people's majority (a tie has none) against the machine.
+  const majority = (id) => {
+    const votes = packets.map((p) => p.labels.get(id)?.label).filter(Boolean), c = {};
+    for (const v of votes) c[v] = (c[v] ?? 0) + 1;
+    const top = Object.entries(c).sort((x, y) => y[1] - x[1]);
+    return top.length && (top.length === 1 || top[0][1] > top[1][1]) ? top[0][0] : null;
+  };
+  const vsMachine = kappa(key.items.map((x) => [majority(x.item_id), machineLabel(x.machine)]).filter(([h, m]) => h && m));
+  const disagreements = key.items.filter((x) => new Set(packets.map((p) => p.labels.get(x.item_id)?.label).filter(Boolean)).size > 1)
+    .map((x) => [x.item_id, x.company, x.measure, x.period, x.value, ...packets.map((p) => p.labels.get(x.item_id)?.label ?? null), machineLabel(x.machine)]);
+  return {
+    task: key.task, items: ids.length, labelled: done, between_annotators: pairs, people_vs_machine: vsMachine,
+    disagreements: { columns: ["item_id", "company", "measure", "period", "claimed", ...packets.map((_, i) => `annotator_${i + 1}`), "machine"], rows: disagreements.slice(0, 200), count: disagreements.length },
+    meaning: "kappa is Cohen's: agreement beyond what the labels' frequencies give by chance (1 perfect, 0 chance; above 0.8 is usually read as strong). people_vs_machine compares the annotators' majority label with the machine's where both exist.",
+    next: disagreements.length ? "A reviewer decides the disagreements; pass them to annotation_gold as reviews." : "annotation_gold writes the gold set.",
+  };
+}
+
+export function annotationGold(args) {
+  const { task_dir, reviews = [] } = goldInput.parse(args);
+  const { key, packets } = readTask(task_dir);
+  const review = new Map(reviews.map((r) => [r.item_id, r]));
+  const gold = [], open = [];
+  for (const x of key.items) {
+    const labels = packets.map((p) => p.labels.get(x.item_id)).filter((l) => l?.label);
+    const set = new Set(labels.map((l) => l.label));
+    const decided = review.get(x.item_id);
+    let final = null, how = null;
+    if (decided) { final = decided; how = "reviewer"; }
+    else if (labels.length === packets.length && set.size === 1) { final = labels[0]; how = "unanimous"; }
+    if (!final) { open.push(x.item_id); continue; }
+    const values = labels.map((l) => l.correct_value).filter((v) => v !== null);
+    gold.push({ item_id: x.item_id, company: x.company, measure: x.measure, period: x.period, claimed: x.value, unit: x.unit ?? null,
+      label: final.label, correct_value: final.correct_value ?? (values.length ? values[0] : null), decided_by: how, annotator_labels: packets.map((p) => p.labels.get(x.item_id)?.label ?? null),
+      machine: x.machine, agrees_with_machine: machineLabel(x.machine) ? machineLabel(x.machine) === final.label : null });
+  }
+  const out = join(task_dir, "gold.jsonl");
+  const body = gold.map((g) => JSON.stringify(g)).join("\n") + (gold.length ? "\n" : "");
+  writeFileSync(out, body);
+  const between = packets.length > 1 ? kappa(key.items.map((x) => [packets[0].labels.get(x.item_id)?.label, packets[1].labels.get(x.item_id)?.label]).filter(([p, q]) => p && q)) : null;
+  const datasheet = {
+    schema: "canli.annotation-datasheet.v1", task: key.task, items: key.items.length, gold: gold.length, open: open.length,
+    labels: Object.fromEntries(LABELS.map((l) => [l, gold.filter((g) => g.label === l).length])),
+    decided_by: { unanimous: gold.filter((g) => g.decided_by === "unanimous").length, reviewer: gold.filter((g) => g.decided_by === "reviewer").length },
+    agreement_first_two: between, machine_agreement_on_gold: gold.filter((g) => g.agrees_with_machine !== null).length ? Math.round((gold.filter((g) => g.agrees_with_machine).length / gold.filter((g) => g.agrees_with_machine !== null).length) * 1e4) / 1e4 : null,
+    blind: !key.assisted, guidelines: "canli.annotation.v1",
+    inputs: { key_sha256: sha(readFileSync(join(task_dir, "key.json"))), packets: packets.map((p) => ({ file: p.file, sha256: p.sha256 })), reviews_sha256: sha(JSON.stringify(reviews)) },
+    gold_sha256: sha(body),
+  };
+  writeFileSync(join(task_dir, "datasheet.json"), JSON.stringify(datasheet, null, 1));
+  return { gold_file: out, datasheet_file: join(task_dir, "datasheet.json"), ...datasheet, open_items: open.slice(0, 200),
+    next: open.length ? `${open.length} items still need a reviewer's decision: pass them as reviews.` : "Every item has a gold label." };
+}

package/src/breadth.mjs

@@ -0,0 +1,413 @@
+// mcp-backtest/src/breadth.mjs
+//
+// The breadth lab: many weakly correlated sleeves from one price panel, traded as one account.
+// Ported from ALPHAC's research/breadth_lab (lab.py, round2.py, round4.py, effective_bets.py,
+// netting_law.py), whose rules it keeps:
+//
+// - A sleeve is one signal inside one group of names (an industry, say): at each rebalance the names
+//   are ranked on the signal, the ranks demeaned and scaled to gross 1 within the group, and the mean
+//   of the last k rebalances' weights is held (overlapping portfolios cut turnover).
+// - Weights decided at a close trade at the next close and earn from the close after; costs are
+//   charged on those trades, plus borrow on shorts. Each sleeve is hedged with its trailing market
+//   beta and scaled to a target volatility, both measured up to the day before.
+// - The book holds every sleeve at equal weight and trades the netted positions: one sleeve's sale is
+//   another's purchase, so the account pays far less than the sleeves would alone. Both costs are
+//   reported (the lab's netting law: about 30% of the summed standalone cost at 10,000 sleeves).
+// - How many independent bets the book holds is counted, not assumed: the participation ratio
+//   (trace C)^2 / sum C_ij^2 of the weekly correlation matrix (n for uncorrelated series, 1 for
+//   copies), for sleeves and for each signal's family book, and ideas as clusters of family books.
+//
+// Pure: no files, no network. Inputs are aligned arrays; panel-io.mjs reads CSV files into them.
+
+import { createHash } from "node:crypto";
+
+export const BREADTH_LIMITS_TEXT = Object.freeze([
+  "Prices, volumes and groups are the caller's: survivorship, splits, dividends and data errors pass straight into every sleeve.",
+  "A sleeve built on many signals and groups is a search: report the number of sleeves, keep a period untouched for the test, and judge the book there, not on the years used to choose it.",
+  "Costs are per name per unit traded (tiers by dollar volume when it is given, else cost_bps) plus borrow on shorts; the market hedge is assumed costless, as with a futures overlay.",
+]);
+
+const DAY_YEAR = 252;
+
+// ---- rolling statistics over one column (NaN = missing) -------------------------------------------
+
+function rolling(x, w, minN, fn) {
+  const n = x.length, out = new Float64Array(n).fill(NaN);
+  let s1 = 0, s2 = 0, s3 = 0, c = 0;
+  for (let i = 0; i < n; i += 1) {
+    const v = x[i];
+    if (!Number.isNaN(v)) { s1 += v; s2 += v * v; s3 += v * v * v; c += 1; }
+    if (i >= w) { const o = x[i - w]; if (!Number.isNaN(o)) { s1 -= o; s2 -= o * o; s3 -= o * o * o; c -= 1; } }
+    if (c >= minN) out[i] = fn(s1, s2, s3, c);
+  }
+  return out;
+}
+const mean = (x, w, m) => rolling(x, w, m, (s1, _s2, _s3, c) => s1 / c);
+const sum = (x, w, m) => rolling(x, w, m, (s1) => s1);
+const std = (x, w, m) => rolling(x, w, m, (s1, s2, _s3, c) => (c > 1 ? Math.sqrt(Math.max(0, (s2 - (s1 * s1) / c) / (c - 1))) : NaN));
+// Sample skewness with pandas' bias correction.
+const skew = (x, w, m) => rolling(x, w, m, (s1, s2, s3, c) => {
+  if (c < 3) return NaN;
+  const mu = s1 / c, m2 = s2 / c - mu * mu, m3 = s3 / c - 3 * mu * (s2 / c) + 2 * mu ** 3;
+  if (m2 <= 1e-14) return NaN;
+  return (Math.sqrt(c * (c - 1)) / (c - 2)) * (m3 / m2 ** 1.5);
+});
+function rollMax(x, w, minN) {
+  const n = x.length, out = new Float64Array(n).fill(NaN), dq = [];
+  let c = 0;
+  for (let i = 0; i < n; i += 1) {
+    if (!Number.isNaN(x[i])) { while (dq.length && x[dq.at(-1)] <= x[i]) dq.pop(); dq.push(i); c += 1; }
+    if (i >= w && !Number.isNaN(x[i - w])) c -= 1;
+    while (dq.length && dq[0] <= i - w) dq.shift();
+    if (c >= minN && dq.length) out[i] = x[dq[0]];
+  }
+  return out;
+}
+const shift = (x, k) => { const out = new Float64Array(x.length).fill(NaN); for (let i = k; i < x.length; i += 1) out[i] = x[i - k]; return out; };
+const map2 = (a, b, f) => { const out = new Float64Array(a.length); for (let i = 0; i < a.length; i += 1) out[i] = f(a[i], b[i]); return out; };
+const map1 = (a, f) => { const out = new Float64Array(a.length); for (let i = 0; i < a.length; i += 1) out[i] = f(a[i], i); return out; };
+
+// ---- the shared daily context --------------------------------------------------------------------
+
+export function context({ dates, tickers, prices, dollarVolume = null, minPrice = 5, minDollarVolume = 5e6, costBps = 10 }) {
+  const n = dates.length;
+  const r = {}, r0 = {}, ltri = {}, adv = {}, eligible = {}, cost = {};
+  for (const t of tickers) {
+    const p = prices[t];
+    const rt = new Float64Array(n).fill(NaN);
+    for (let i = 1; i < n; i += 1) if (p[i] > 0 && p[i - 1] > 0) rt[i] = p[i] / p[i - 1] - 1;
+    r[t] = rt;
+    r0[t] = map1(rt, (v) => (Number.isNaN(v) ? 0 : v));
+    let acc = 0;
+    ltri[t] = map1(r0[t], (v) => (acc += Math.log1p(Math.max(v, -0.99))));
+    const dv = dollarVolume?.[t] ? map1(dollarVolume[t], (v) => (v > 0 ? v : NaN)) : null;
+    adv[t] = dv ? rollMedian(dv, 63, 40) : null;
+    eligible[t] = map1(p, (v, i) => (v >= minPrice && (!dv || adv[t][i] >= minDollarVolume) ? 1 : 0));
+    cost[t] = dv ? map1(adv[t], (a) => (a >= 5e7 ? 0.001 : a >= 1e7 ? 0.002 : 0.004)) : null;
+  }
+  // The market: the equal-weighted return of the names eligible yesterday.
+  const market = new Float64Array(n);
+  for (let i = 1; i < n; i += 1) {
+    let s = 0, c = 0;
+    for (const t of tickers) if (eligible[t][i - 1] && !Number.isNaN(r[t][i])) { s += r[t][i]; c += 1; }
+    market[i] = c ? s / c : 0;
+  }
+  return { dates, tickers, prices, dollarVolume: dollarVolume ?? null, r, r0, ltri, adv, eligible, cost, flatCost: costBps / 1e4, market, n };
+}
+
+function rollMedian(x, w, minN) {
+  const out = new Float64Array(x.length).fill(NaN);
+  for (let i = 0; i < x.length; i += 1) {
+    const win = [];
+    for (let k = Math.max(0, i - w + 1); k <= i; k += 1) if (!Number.isNaN(x[k])) win.push(x[k]);
+    if (win.length >= minN) { win.sort((a, b) => a - b); const h = win.length >> 1; out[i] = win.length % 2 ? win[h] : (win[h - 1] + win[h]) / 2; }
+  }
+  return out;
+}
+
+// ---- signals: higher = long; each a daily series per name, sampled at the rebalance dates -------------
+
+const ret = (c, t, a, b) => map2(shift(c.ltri[t], b), shift(c.ltri[t], a), (x, y) => Math.expm1(x - y));
+function beta(c, t, w) {
+  const h = w >> 1, m = c.market;
+  const mr = mean(map2(c.r0[t], m, (x, y) => x * y), w, h), rm = mean(c.r0[t], w, h), mm = mean(m, w, h), m2 = mean(map1(m, (x) => x * x), w, h);
+  return map1(mr, (v, i) => (v - rm[i] * mm[i]) / (m2[i] - mm[i] * mm[i]));
+}
+const marketMean = (c, f, w, minN) => mean(map1(c.market, f), w, minN);
+
+// Each entry: [needs, rebalance, reference, function(c, t)]. needs: "price" or "volume".
+export const SIGNALS = Object.freeze({
+  mom_12_1: ["price", "M", "Jegadeesh and Titman (1993): return from 12 months to 1 month ago", (c, t) => ret(c, t, 252, 21)],
+  mom_6_1: ["price", "M", "Jegadeesh and Titman (1993): return from 6 months to 1 month ago", (c, t) => ret(c, t, 126, 21)],
+  mom_12_7: ["price", "M", "Novy-Marx (2012): intermediate momentum, 12 to 7 months ago", (c, t) => ret(c, t, 252, 147)],
+  mom_accel: ["price", "M", "Momentum acceleration: 6-1 month return minus 12-7 month return", (c, t) => map2(ret(c, t, 126, 21), ret(c, t, 252, 147), (a, b) => a - b)],
+  rev_36_12: ["price", "M", "De Bondt and Thaler (1985): long-term reversal, 36 to 12 months ago, negated", (c, t) => map1(ret(c, t, 756, 252), (v) => -v)],
+  rev_1m: ["price", "M", "Jegadeesh (1990): one-month reversal, negated", (c, t) => map1(ret(c, t, 21, 0), (v) => -v)],
+  rev_1w: ["price", "W", "Lehmann (1990): one-week reversal, negated, rebalanced weekly", (c, t) => map1(ret(c, t, 5, 0), (v) => -v)],
+  hi52: ["price", "M", "George and Hwang (2004): nearness to the 52-week high (log)", (c, t) => map2(c.ltri[t], rollMax(c.ltri[t], 252, 200), (a, b) => a - b)],
+  lowvol_63: ["price", "M", "Ang, Hodrick, Xing and Zhang (2006): low 3-month volatility", (c, t) => map1(std(c.r[t], 63, 40), (v) => -v)],
+  lowbeta_252: ["price", "M", "Frazzini and Pedersen (2014): low one-year beta to the equal-weighted market", (c, t) => map1(beta(c, t, 252), (v) => -v)],
+  ivol_63: ["price", "M", "Ang et al. (2006): low idiosyncratic volatility, market-model residuals over 3 months", (c, t) => {
+    const b = beta(c, t, 252);
+    return map1(std(map1(c.r0[t], (v, i) => v - b[i] * c.market[i]), 63, 40), (v) => -v);
+  }],
+  max_21: ["price", "M", "Bali, Cakici and Whitelaw (2011): low maximum daily return over a month", (c, t) => map1(rollMax(c.r[t], 21, 15), (v) => -v)],
+  skew_252: ["price", "M", "Boyer, Mitton and Vorkink (2010): low one-year skewness of daily returns", (c, t) => map1(skew(c.r[t], 252, 200), (v) => -v)],
+  zero_days_252: ["price", "M", "Lesmond, Ogden and Trzcinka (1999): share of zero-return days over a year", (c, t) => mean(map1(c.r[t], (v) => (Number.isNaN(v) ? NaN : v === 0 ? 1 : 0)), 252, 200)],
+  updays: ["price", "M", "Da, Gurun and Warachka (2014): share of up minus down days, months 12 to 2", (c, t) => mean(shift(map1(c.r[t], (v) => (Number.isNaN(v) ? NaN : Math.sign(v))), 21), 231, 180)],
+  resid_mom: ["price", "M", "Blitz, Huij and Martens (2011): residual momentum, months 12 to 2 over residual volatility", (c, t) => {
+    const b = shift(beta(c, t, 252), 1);
+    const e = shift(map1(c.r0[t], (v, i) => (Number.isNaN(b[i]) ? NaN : v - b[i] * c.market[i])), 21);
+    return map2(sum(e, 231, 180), std(e, 231, 180), (s, sd) => s / (sd * Math.sqrt(231)));
+  }],
+  coskew_252: ["price", "M", "Harvey and Siddique (2000): low coskewness with the market over a year", (c, t) => {
+    const w = 252, h = 126, m = c.market, r = c.r[t];
+    const mm = marketMean(c, (x) => x, w, h), mv = map2(marketMean(c, (x) => x * x, w, h), mm, (a, b) => a - b * b);
+    const mr = mean(r, w, h), r2 = mean(map1(r, (v) => v * v), w, h);
+    const rmm = mean(map2(r, m, (v, x) => v * x * x), w, h), rm = mean(map2(r, m, (v, x) => v * x), w, h);
+    return map1(rmm, (v, i) => {
+      const num = v - 2 * rm[i] * mm[i] + mr[i] * (mm[i] ** 2 - mv[i]);
+      return -num / (Math.sqrt(Math.max(r2[i] - mr[i] ** 2, 0)) * mv[i]);
+    });
+  }],
+  dbeta_252: ["price", "M", "Ang, Chen and Xing (2006): downside beta, on days the market fell", (c, t) => {
+    const w = 252, h = 126, d = map1(c.market, (x) => (x < 0 ? 1 : 0)), md = map2(c.market, d, (x, y) => x * y);
+    const n = mean(d, w, h), erm = mean(map2(c.r0[t], md, (x, y) => x * y), w, h), er = mean(map2(c.r0[t], d, (x, y) => x * y), w, h);
+    const em = mean(md, w, h), em2 = mean(map1(md, (x) => x * x), w, h);
+    return map1(n, (k, i) => { const a = em[i] / k, b = em2[i] / k; return (erm[i] / k - (er[i] / k) * a) / (b - a * a); });
+  }],
+  lag_corr_252: ["price", "M", "Hou and Moskowitz (2005): price delay, correlation with yesterday's market", (c, t) => {
+    const w = 252, h = 126, ml = shift(c.market, 1), r = c.r0[t];
+    const er = mean(r, w, h), eml = mean(ml, w, h), erml = mean(map2(r, ml, (x, y) => x * y), w, h);
+    const sm = map2(mean(map1(ml, (x) => x * x), w, h), eml, (a, b) => Math.sqrt(a - b * b)), sr = map2(mean(map1(r, (x) => x * x), w, h), er, (a, b) => Math.sqrt(Math.max(a - b * b, 1e-12)));
+    return map1(erml, (v, i) => (v - er[i] * eml[i]) / sm[i] / sr[i]);
+  }],
+  season: ["price", "M", "Heston and Sadka (2008): mean return of the coming calendar month over the previous five years", (c, t) => seasonality(c, t)],
+  vol_shock: ["volume", "M", "Gervais, Kaniel and Mingelgrin (2001): one-month dollar volume against the year's", (c, t) => map2(mean(c.dollarVolume[t], 21, 15), mean(c.dollarVolume[t], 252, 200), (a, b) => Math.log(a / b))],
+  amihud_63: ["volume", "M", "Amihud (2002): illiquidity, |return| per dollar traded over 3 months", (c, t) => mean(map2(c.r[t], c.dollarVolume[t], (x, v) => (v > 0 ? Math.abs(x) / v : NaN)), 63, 40)],
+  small_63: ["volume", "M", "Banz (1981): small size, proxied by low median dollar volume", (c, t) => map1(c.adv[t], (v) => -Math.log(v))],
+  dvol_cv: ["volume", "M", "Chordia, Subrahmanyam and Anshuman (2001): steadier dollar volume", (c, t) => {
+    const dv = map1(c.dollarVolume[t], (v) => (v > 0 ? v : NaN));
+    return map2(std(dv, 126, 80), mean(dv, 126, 80), (s, m) => -(s / m));
+  }],
+});
+
+// Mean return of the coming calendar month in each of the previous five years, known at month end.
+function seasonality(c, t) {
+  const month = c.dates.map((d) => d.slice(0, 7)), out = new Float64Array(c.n).fill(NaN), monthly = new Map();
+  for (let i = 0; i < c.n; i += 1) monthly.set(month[i], (monthly.get(month[i]) ?? 1) * (1 + Math.max(c.r0[t][i], -0.99)));
+  for (let i = 0; i < c.n; i += 1) {
+    const [y, m] = month[i].split("-").map(Number), next = m === 12 ? 1 : m + 1, ny = m === 12 ? y + 1 : y;
+    const past = [1, 2, 3, 4, 5].map((k) => monthly.get(`${ny - k}-${String(next).padStart(2, "0")}`)).filter((v) => v !== undefined);
+    if (past.length === 5) out[i] = past.reduce((a, b) => a + b - 1, 0) / 5;
+  }
+  return out;
+}
+
+export function signalCatalog() {
+  return Object.entries(SIGNALS).map(([name, [needs, every, reference]]) => ({ name, needs, rebalance: every === "W" ? "weekly" : "monthly", reference }));
+}
+
+// ---- sleeves and the netted book -------------------------------------------------------------------
+
+function rebalanceDays(dates, every) {
+  const out = [];
+  for (let i = 0; i < dates.length; i += 1) {
+    const next = dates[i + 1];
+    if (next === undefined) { out.push(i); continue; }
+    if (every === "M" ? next.slice(0, 7) !== dates[i].slice(0, 7) : isoWeek(next) !== isoWeek(dates[i])) out.push(i);
+  }
+  return out;
+}
+function isoWeek(date) {
+  const d = new Date(`${date}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + 3 - ((d.getUTCDay() + 6) % 7));
+  return `${d.getUTCFullYear()}-${Math.floor((d - Date.UTC(d.getUTCFullYear(), 0, 1)) / 6048e5)}`;
+}
+
+// Rank-demeaned weights, gross 1 in each group with at least minNames eligible names.
+function groupWeights(c, values, i, groupOf, minNames) {
+  const byGroup = new Map();
+  for (const t of c.tickers) {
+    const v = values[t][i], g = groupOf(t);
+    if (g == null || Number.isNaN(v) || !Number.isFinite(v) || !c.eligible[t][i]) continue;
+    if (!byGroup.has(g)) byGroup.set(g, []);
+    byGroup.get(g).push([t, v]);
+  }
+  const w = new Map();
+  for (const [g, list] of byGroup) {
+    if (list.length < minNames) continue;
+    list.sort((a, b) => a[1] - b[1]);
+    const ranks = new Map();
+    for (let k = 0; k < list.length;) { // ties share their mean rank, as pandas' rank(pct=True)
+      let j = k; while (j + 1 < list.length && list[j + 1][1] === list[k][1]) j += 1;
+      for (let q = k; q <= j; q += 1) ranks.set(list[q][0], ((k + j) / 2 + 1) / list.length);
+      k = j + 1;
+    }
+    const mu = [...ranks.values()].reduce((a, b) => a + b, 0) / list.length;
+    let gross = 0;
+    for (const [t] of list) gross += Math.abs(ranks.get(t) - mu);
+    if (gross > 0) for (const [t] of list) w.set(t, { g, w: (ranks.get(t) - mu) / gross });
+  }
+  return w;
+}
+
+const statsOf = (x) => {
+  const v = [...x].filter((y) => !Number.isNaN(y));
+  if (v.length < 60) return { days: v.length, sharpe: null };
+  const mu = v.reduce((a, b) => a + b, 0) / v.length, sd = Math.sqrt(v.reduce((a, b) => a + (b - mu) ** 2, 0) / (v.length - 1));
+  if (!(sd > 0)) return { days: v.length, sharpe: null };
+  let eq = 1, peak = 1, dd = 0;
+  for (const y of v) { eq *= 1 + y; peak = Math.max(peak, eq); dd = Math.min(dd, eq / peak - 1); }
+  const sr = (mu / sd) * Math.sqrt(DAY_YEAR);
+  return { days: v.length, sharpe: round(sr, 3), t: round(sr * Math.sqrt(v.length / DAY_YEAR), 2), ann_return: round(mu * DAY_YEAR, 4), ann_vol: round(sd * Math.sqrt(DAY_YEAR), 4), max_drawdown: round(dd, 4) };
+};
+const round = (x, d) => (Number.isFinite(x) ? Math.round(x * 10 ** d) / 10 ** d : null);
+
+export function runBreadth(input) {
+  const { dates, tickers, groups = null, signals = null, smoothing = null, minNames = 10, targetVol = 0.1, maxLeverage = 5, borrow = 0.005, splitDate = null } = input;
+  const c = context(input);
+  const groupOf = groups ? (t) => groups[t] ?? null : () => "all";
+  const wanted = signals ?? Object.keys(SIGNALS).filter((s) => SIGNALS[s][0] === "price" || c.dollarVolume);
+  for (const s of wanted) {
+    if (!SIGNALS[s]) throw new RangeError(`unknown signal ${s}; breadth_signals lists them`);
+    if (SIGNALS[s][0] === "volume" && !c.dollarVolume) throw new RangeError(`${s} needs dollar_volume_file`);
+  }
+  const n = c.n, sleeves = [], netted = Object.fromEntries(tickers.map((t) => [t, new Float64Array(n)]));
+  const standaloneCost = new Float64Array(n), active = new Float64Array(n);
+  const costOf = (t, i) => (c.cost[t] ? (Number.isNaN(c.cost[t][i]) ? 0.004 : c.cost[t][i]) : c.flatCost);
+  const pending = [];
+  for (const s of wanted) {
+    const [, every, reference, fn] = SIGNALS[s];
+    const values = Object.fromEntries(tickers.map((t) => [t, fn(c, t)]));
+    const k = smoothing ?? (every === "W" ? 4 : 3);
+    // Held weights per name (the mean of the last k rebalances, back to gross 1 per group), and its group.
+    const held = Object.fromEntries(tickers.map((t) => [t, new Float64Array(n)]));
+    const recent = [];
+    let last = new Map();
+    const rebal = new Set(rebalanceDays(dates, every));
+    for (let i = 0; i < n; i += 1) {
+      if (rebal.has(i)) {
+        recent.push(groupWeights(c, values, i, groupOf, minNames));
+        if (recent.length > k) recent.shift();
+        const avg = new Map(), gross = new Map();
+        for (const wmap of recent) for (const [t, { g, w }] of wmap) { const a = avg.get(t) ?? { g, w: 0 }; a.w += w / recent.length; avg.set(t, a); }
+        for (const [, { g, w }] of avg) gross.set(g, (gross.get(g) ?? 0) + Math.abs(w));
+        last = new Map([...avg].map(([t, { g, w }]) => [t, { g, w: gross.get(g) > 0 ? w / gross.get(g) : 0 }]));
+      }
+      for (const [t, { w }] of last) held[t][i] = w;
+    }
+    // Per group: gross and cost series, from weights traded a day later and earning a day after that.
+    const groupNames = new Map();
+    for (const t of tickers) { const g = groupOf(t); if (g != null) { if (!groupNames.has(g)) groupNames.set(g, []); groupNames.get(g).push(t); } }
+    for (const [g, names] of groupNames) {
+      const gross = new Float64Array(n).fill(NaN), costs = new Float64Array(n), live = new Float64Array(n);
+      let any = false;
+      for (let i = 2; i < n; i += 1) {
+        let gr = 0, short = 0, liveGross = 0, cost = 0;
+        for (const t of names) {
+          const lv = held[t][i - 2];
+          if (lv) { gr += lv * c.r0[t][i]; liveGross += Math.abs(lv); if (lv < 0) short -= lv; }
+          const traded = held[t][i - 1] - held[t][i - 2];
+          if (traded) cost += Math.abs(traded) * costOf(t, i - 1);
+        }
+        costs[i] = cost;
+        if (liveGross > 0) { gross[i] = gr - short * borrow / DAY_YEAR; live[i] = 1; any = true; }
+      }
+      if (!any) continue;
+      // costs[i] are the trades made at close i-1, charged on day i.
+      const net = map1(gross, (v, i) => (Number.isNaN(v) ? NaN : v - costs[i]));
+      pending.push({ s, g, every, reference, names, held, gross, net, costs });
+    }
+  }
+  // Hedge each sleeve with its trailing beta and scale to target volatility, both lagged a day.
+  const m = c.market, mm = mean(m, 252, 126), mvar = map2(mean(map1(m, (x) => x * x), 252, 126), mm, (a, b) => a - b * b);
+  for (const p of pending) {
+    const raw = map1(p.net, (v) => (Number.isNaN(v) ? 0 : v)), rawMean = mean(raw, 252, 126);
+    const b = map1(mean(map2(raw, m, (x, y) => x * y), 252, 126), (v, i) => (v - rawMean[i] * mm[i]) / mvar[i]);
+    const hedged = map1(raw, (v, i) => (i > 0 && Number.isFinite(b[i - 1]) ? v - b[i - 1] * m[i] : NaN));
+    const vol = map1(std(hedged, 126, 63), (v) => v * Math.sqrt(DAY_YEAR));
+    const lev = map1(vol, (v, i) => (i > 0 && vol[i - 1] > 0 ? Math.min(targetVol / vol[i - 1], maxLeverage) : NaN));
+    p.returns = map1(hedged, (v, i) => (Number.isNaN(p.net[i]) || !Number.isFinite(lev[i]) ? NaN : v * lev[i]));
+    p.lev = lev;
+    for (let i = 2; i < n; i += 1) {
+      if (Number.isNaN(p.returns[i])) continue;
+      active[i] += 1;
+      standaloneCost[i] += p.costs[i] * lev[i];
+      for (const t of p.names) netted[t][i - 1] += p.held[t][i - 1] * lev[i];
+    }
+  }
+  // The book: equal weight across the sleeves live each day; the account trades the netted weights.
+  // Standalone cost is each sleeve's own trades at its leverage; the netted account also pays for
+  // changes in leverage, so the netting ratio errs against netting.
+  const bookGross = new Float64Array(n).fill(NaN), nettedCost = new Float64Array(n), sCost = new Float64Array(n);
+  for (let i = 2; i < n; i += 1) {
+    if (!active[i]) continue;
+    let s = 0;
+    for (const p of pending) if (!Number.isNaN(p.returns[i])) s += p.returns[i] + p.costs[i] * p.lev[i];
+    bookGross[i] = s / active[i];
+    let nc = 0;
+    for (const t of tickers) { const d = netted[t][i - 1] / active[i] - (active[i - 1] ? netted[t][i - 2] / active[i - 1] : 0); if (d) nc += Math.abs(d) * costOf(t, i - 1); }
+    nettedCost[i] = nc; sCost[i] = standaloneCost[i] / active[i];
+  }
+  const netBook = map1(bookGross, (v, i) => v - nettedCost[i]), soloBook = map1(bookGross, (v, i) => v - sCost[i]);
+  const ids = pending.map((p) => `${p.s}@${p.g}`), family = pending.map((p) => p.s);
+  const bets = effectiveBets(dates, pending.map((p) => p.returns), family);
+  const window = (x, after) => (splitDate ? map1(x, (v, i) => ((dates[i] > splitDate) === after ? v : NaN)) : x);
+  const sumOf = (x) => [...x].reduce((a, b) => a + (Number.isNaN(b) ? 0 : b), 0);
+  return {
+    sleeves: pending.length, signals: wanted.length, groups: new Set(pending.map((p) => p.g)).size,
+    book: {
+      netted: statsOf(netBook), standalone: statsOf(soloBook), before_costs: statsOf(bookGross),
+      cost_per_year_netted: round((sumOf(nettedCost) / Math.max(1, [...active].filter(Boolean).length)) * DAY_YEAR, 4),
+      cost_per_year_standalone: round((sumOf(sCost) / Math.max(1, [...active].filter(Boolean).length)) * DAY_YEAR, 4),
+      netting_ratio: round(sumOf(nettedCost) / sumOf(sCost), 3),
+      ...(splitDate ? { search: { netted: statsOf(window(netBook, false)) }, test: { netted: statsOf(window(netBook, true)), note: `After ${splitDate}: judge the book here only if nothing was chosen on these dates.` } } : {}),
+    },
+    effective_bets: bets,
+    sleeve_columns: ["id", "signal", "group", "names", "sharpe_after_costs", "sharpe_before_costs_unhedged"],
+    sleeve_rows: pending.map((p, j) => [ids[j], p.s, p.g, p.names.length, statsOf(p.returns).sharpe, statsOf(p.gross).sharpe]),
+    series: { ids, family, returns: pending.map((p) => p.returns), book: netBook },
+    specs: pending.map((p, j) => ({ id: ids[j], signal: p.s, group: p.g, rebalance: p.every === "W" ? "weekly" : "monthly", smoothing: smoothing ?? (p.every === "W" ? 4 : 3), min_names: minNames, target_vol: targetVol, reference: p.reference, spec_sha256: createHash("sha256").update(JSON.stringify([p.s, p.g, p.every, smoothing, minNames, targetVol, maxLeverage, borrow])).digest("hex") })),
+  };
+}
+
+// ---- effective independent bets ---------------------------------------------------------------------
+
+// Weekly sums (at least 3 days), then correlations over weeks both series have (at least minWeeks).
+function weekly(dates, series) {
+  const keys = dates.map(isoWeek), order = [...new Set(keys)];
+  const at = new Map(order.map((k, i) => [k, i]));
+  return series.map((x) => {
+    const s = new Float64Array(order.length), c = new Uint16Array(order.length);
+    for (let i = 0; i < x.length; i += 1) if (!Number.isNaN(x[i])) { s[at.get(keys[i])] += x[i]; c[at.get(keys[i])] += 1; }
+    return map1(s, (v, i) => (c[i] >= 3 ? v : NaN));
+  });
+}
+function corr(a, b, minN) {
+  let n = 0, sa = 0, sb = 0, saa = 0, sbb = 0, sab = 0;
+  for (let i = 0; i < a.length; i += 1) {
+    if (Number.isNaN(a[i]) || Number.isNaN(b[i])) continue;
+    n += 1; sa += a[i]; sb += b[i]; saa += a[i] * a[i]; sbb += b[i] * b[i]; sab += a[i] * b[i];
+  }
+  if (n < minN) return NaN;
+  const v = (saa - (sa * sa) / n) * (sbb - (sb * sb) / n);
+  return v > 0 ? (sab - (sa * sb) / n) / Math.sqrt(v) : NaN;
+}
+// (trace C)^2 / sum of squared entries = (sum of eigenvalues)^2 / sum of squared eigenvalues.
+function participation(cm) {
+  const k = cm.length;
+  let s2 = 0;
+  for (let i = 0; i < k; i += 1) for (let j = 0; j < k; j += 1) { const v = i === j ? 1 : Number.isNaN(cm[i][j]) ? 0 : cm[i][j]; s2 += v * v; }
+  return k ? (k * k) / s2 : 0;
+}
+const matrix = (ws, minWeeks) => ws.map((a, i) => ws.map((b, j) => (i === j ? 1 : j < i ? NaN : corr(a, b, minWeeks)))).map((row, i, all) => row.map((v, j) => (j < i ? all[j][i] : v)));
+
+export function effectiveBets(dates, series, family = null, { threshold = 0.5, minWeeks = 104 } = {}) {
+  const ws = weekly(dates, series), cm = matrix(ws, minWeeks), k = series.length;
+  const off = [];
+  for (let i = 0; i < k; i += 1) for (let j = i + 1; j < k; j += 1) if (!Number.isNaN(cm[i][j])) off.push(cm[i][j]);
+  const out = { series: k, avg_pairwise_corr: off.length ? round(off.reduce((a, b) => a + b, 0) / off.length, 4) : null, effective_bets: round(participation(cm), 1) };
+  if (!family) return out;
+  const names = [...new Set(family)];
+  const books = names.map((f) => {
+    const members = series.filter((_, i) => family[i] === f);
+    return map1(members[0], (_, t) => { let s = 0, c = 0; for (const x of members) if (!Number.isNaN(x[t])) { s += x[t]; c += 1; } return c ? s / c : NaN; });
+  });
+  const bm = matrix(weekly(dates, books), minWeeks);
+  // Ideas: average linkage on |corr| of the family books, joined while the link is at least threshold.
+  let clusters = names.map((_, i) => [i]);
+  for (;;) {
+    let best = -1, pair = null;
+    for (let i = 0; i < clusters.length; i += 1) for (let j = i + 1; j < clusters.length; j += 1) {
+      let s = 0, c = 0;
+      for (const a of clusters[i]) for (const b of clusters[j]) { const v = Math.abs(bm[a][b]); s += Number.isNaN(v) ? 0 : v; c += 1; }
+      if (s / c > best) { best = s / c; pair = [i, j]; }
+    }
+    if (!pair || best < threshold) break;
+    clusters[pair[0]] = clusters[pair[0]].concat(clusters[pair[1]]);
+    clusters.splice(pair[1], 1);
+  }
+  clusters = clusters.map((cl) => cl.map((i) => names[i])).sort((a, b) => b.length - a.length);
+  return { ...out, families: names.length, effective_bets_families: round(participation(bm), 1), ideas: clusters.length, idea_threshold_abs_corr: threshold, idea_members: clusters };
+}

package/src/panel.mjs

@@ -0,0 +1,123 @@
+// A price panel for the breadth lab and backtest_signal, built from free sources: the tickers you
+// name or an index fund's current holdings (its latest SEC N-PORT), each ticker's daily adjusted
+// closes and volume from canli-markets-mcp's price_history, and an industry for each company from
+// its SEC SIC code, grouped into the twelve Fama-French industries. Writes prices, dollar volume and
+// groups as CSV files breadth_book reads directly.
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { fundPortfolio } from "canli-markets-mcp/src/funds.mjs";
+import { submissions, tickerTable } from "canli-markets-mcp/src/sources.mjs";
+import { priceHistory } from "canli-markets-mcp/src/tools.mjs";
+import { z } from "zod";
+
+import { writePanel } from "./panel-io.mjs";
+
+const date = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "a date as YYYY-MM-DD");
+export const panelInput = z.object({
+  tickers: z.array(z.string().min(1).max(12).regex(/^[A-Za-z0-9.\-]+$/)).min(2).max(600).optional().describe("US tickers to include."),
+  index_fund: z.string().min(2).max(10).optional().describe("Or an index fund or ETF whose current holdings make the universe: IVV (S&P 500), IJH (mid caps), IJR (small caps), QQQ, VTI..."),
+  max_names: z.number().int().min(2).max(600).optional().describe("With index_fund: the largest holdings to take. Default 500."),
+  start: date.describe("First date."),
+  end: date.optional().describe("Last date; default today."),
+  out_dir: z.string().min(1).max(1000).optional().describe("Folder for prices.csv, dollar_volume.csv and groups.csv. Default: a new temporary folder."),
+}).strict();
+
+// The twelve Fama-French industries by four-digit SIC (Kenneth French's definitions).
+const FF12 = [
+  ["NoDur", [[100, 999], [2000, 2399], [2700, 2749], [2770, 2799], [3100, 3199], [3940, 3989]]],
+  ["Durbl", [[2500, 2519], [2590, 2599], [3630, 3659], [3710, 3711], [3714, 3714], [3716, 3716], [3750, 3751], [3792, 3792], [3900, 3939], [3990, 3999]]],
+  ["Manuf", [[2520, 2589], [2600, 2699], [2750, 2769], [3000, 3099], [3200, 3569], [3580, 3629], [3700, 3709], [3712, 3713], [3715, 3715], [3717, 3749], [3752, 3791], [3793, 3799], [3830, 3839], [3860, 3899]]],
+  ["Enrgy", [[1200, 1399], [2900, 2999]]],
+  ["Chems", [[2800, 2829], [2840, 2899]]],
+  ["BusEq", [[3570, 3579], [3660, 3692], [3694, 3699], [3810, 3829], [7370, 7379]]],
+  ["Telcm", [[4800, 4899]]],
+  ["Utils", [[4900, 4949]]],
+  ["Shops", [[5000, 5999], [7200, 7299], [7600, 7699]]],
+  ["Hlth", [[2830, 2839], [3693, 3693], [3840, 3859], [8000, 8099]]],
+  ["Money", [[6000, 6999]]],
+];
+export function ff12(sic) {
+  const s = Number(sic);
+  if (!Number.isFinite(s) || s <= 0) return null;
+  for (const [name, ranges] of FF12) if (ranges.some(([lo, hi]) => s >= lo && s <= hi)) return name;
+  return "Other";
+}
+
+const legal = /\b(inc|incorporated|corp|corporation|co|company|ltd|limited|plc|holdings?|group|class [a-c]|cl [a-c]|the|sa|nv|ag|se|lp|llc|new|del|de)\b/g;
+const key = (name) => String(name ?? "").toLowerCase().replace(/&/g, " and ").replace(/[^a-z0-9 ]+/g, " ").replace(legal, " ").replace(/\s+/g, " ").trim();
+
+// The holdings of an index fund as tickers, matched to SEC's ticker table by name (a holding whose
+// name matches no listed company, or several, is left out and counted).
+async function fundTickers(session, fund, max) {
+  const p = await fundPortfolio(session, { fund, top: Math.min(max * 2, 500), compare: false });
+  const byName = new Map();
+  for (const r of Object.values(await tickerTable(session))) {
+    const k = key(r.title);
+    if (!byName.has(k)) byName.set(k, []);
+    byName.get(k).push(r);
+  }
+  const at = (c) => p.columns.indexOf(c);
+  const tickers = [], unmatched = [], seen = new Set();
+  for (const row of p.rows) {
+    if (row[at("asset_category")] !== "EC") continue; // equities only
+    const hits = byName.get(key(row[at("name")])) ?? [];
+    const cik = new Set(hits.map((h) => h.cik_str));
+    if (cik.size !== 1) { unmatched.push(row[at("name")]); continue; }
+    if (seen.has(hits[0].cik_str)) continue;
+    seen.add(hits[0].cik_str);
+    tickers.push(hits[0].ticker);
+    if (tickers.length >= max) break;
+  }
+  return { tickers, unmatched, fund: p.fund, period: p.period };
+}
+
+export async function buildPanel(session, args) {
+  const a = panelInput.parse(args);
+  if (!a.tickers === !a.index_fund) throw new RangeError("Send tickers or index_fund.");
+  const end = a.end ?? new Date(session.now()).toISOString().slice(0, 10);
+  if (!(a.start < end)) throw new RangeError("start must be before end.");
+  let universe = a.tickers?.map((t) => t.toUpperCase()) ?? null, from = null;
+  if (a.index_fund) { from = await fundTickers(session, a.index_fund.toUpperCase(), a.max_names ?? 500); universe = from.tickers; }
+  const cikOf = new Map(Object.values(await tickerTable(session)).map((r) => [r.ticker, r.cik_str]));
+  const series = new Map(), groups = {}, failed = [];
+  for (const t of universe) {
+    try {
+      const p = await priceHistory(session, { symbol: t, start: a.start, end, adjusted: true });
+      series.set(t, p);
+      const cik = cikOf.get(t.replace(/\./g, "-"));
+      const sub = cik ? await submissions(session, cik).catch(() => null) : null;
+      groups[t] = ff12(sub?.sic) ?? "Other";
+    } catch (err) { failed.push([t, String(err.message).slice(0, 120)]); }
+  }
+  const tickers = [...series.keys()];
+  if (tickers.length < 2) throw new RangeError(`Prices came back for ${tickers.length} ticker(s); ${failed.slice(0, 5).map((f) => f.join(": ")).join("; ")}`);
+  const dates = [...new Set(tickers.flatMap((t) => series.get(t).dates))].sort();
+  const idx = new Map(dates.map((d, i) => [d, i]));
+  const prices = {}, dollars = {};
+  for (const t of tickers) {
+    const p = series.get(t), px = new Array(dates.length).fill(null), dv = new Array(dates.length).fill(null);
+    p.dates.forEach((d, i) => { px[idx.get(d)] = p.close[i]; dv[idx.get(d)] = p.volume?.[i] != null && p.close[i] != null ? Math.round(p.volume[i] * p.close[i]) : null; });
+    prices[t] = px; dollars[t] = dv;
+  }
+  const dir = a.out_dir ?? mkdtempSync(join(tmpdir(), "canli-panel-"));
+  const files = { prices_file: join(dir, "prices.csv"), dollar_volume_file: join(dir, "dollar_volume.csv"), groups_file: join(dir, "groups.csv") };
+  writePanel(files.prices_file, { dates, tickers, values: prices });
+  writePanel(files.dollar_volume_file, { dates, tickers, values: dollars });
+  writeFileSync(files.groups_file, `ticker,group\n${tickers.map((t) => `${t},${groups[t]}`).join("\n")}\n`);
+  const count = {};
+  for (const g of Object.values(groups)) count[g] = (count[g] ?? 0) + 1;
+  return {
+    ...files, tickers: tickers.length, dates: dates.length, first_date: dates[0], last_date: dates.at(-1),
+    groups: count, source: [...new Set(tickers.map((t) => series.get(t).source))],
+    ...(from ? { universe: { fund: from.fund, period: from.period, unmatched_holdings: from.unmatched.length } } : {}),
+    ...(failed.length ? { failed: { count: failed.length, examples: failed.slice(0, 10) } } : {}),
+    next: `breadth_book with prices_file ${files.prices_file}, groups_file ${files.groups_file} and dollar_volume_file ${files.dollar_volume_file}.`,
+    limits: [
+      "An index fund's current holdings are today's survivors: companies that left the index or failed before today are missing, which flatters a backtest over past years (survivorship bias).",
+      "Prices are price_history's provider's (Yahoo's public chart data unless you set an Alpaca or Tiingo key): adjusted for splits and dividends by the provider.",
+      "Industries come from each company's SEC SIC code, grouped into the twelve Fama-French industries; a SIC code describes the filer's main line of business as SEC records it.",
+    ],
+  };
+}

package/src/server.mjs

@@ -7,7 +7,7 @@
 // Local stdio only: prices, signals and ledgers stay on this machine. Point-in-time SEC data comes
 // from canli-fundamentals-mcp (cached under ~/.cache/canli-fundamentals); the ledger is
 // canli-validation-mcp's (files under ~/.canli/ledgers), so both servers read the same searches.
-import { mkdtempSync, readFileSync, realpathSync } from "node:fs";
+import { mkdtempSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,15 +16,19 @@ import { McpServer } from "@modelcontextprotocol/server";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { createSession as fundamentalsSession, loadCompany, resolveSeries } from "canli-fundamentals-mcp/src/server.mjs";
+import { createSession as marketsSession } from "canli-markets-mcp/src/sources.mjs";
 import { ledgerDir, recordTrial } from "canli-validation-mcp/src/ledger.mjs";
 
+import { agreementInput, annotationAgreement, annotationGold, annotationPacket, goldInput, packetInput } from "./annotate.mjs";
+import { BREADTH_LIMITS_TEXT, effectiveBets, runBreadth, signalCatalog } from "./breadth.mjs";
+import { buildPanel, panelInput } from "./panel.mjs";
 import { ENGINE_LIMITS_TEXT, describe, runBacktest } from "./engine.mjs";
 import { readPanel, writePanel } from "./panel-io.mjs";
 import { FACTORS, PIT_LIMITS_TEXT, buildFactorPanel } from "./pit.mjs";
 
 export const SERVER_NAME = "canli-backtest-mcp";
 export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-export const SERVER_INSTRUCTIONS = "Backtests that refuse lookahead. Build a point-in-time factor from SEC filings with pit_factor (or bring your own signal CSV, each row dated when it was known), then run backtest_signal against your own prices CSV. Pass the same ledger name to every backtest_signal call in one search: the reply judges the best variant against all of them.";
+export const SERVER_INSTRUCTIONS = "Backtests that refuse lookahead. Build a point-in-time factor from SEC filings with pit_factor (or bring your own signal CSV, each row dated when it was known), then run backtest_signal against your own prices CSV. Pass the same ledger name to every backtest_signal call in one search: the reply judges the best variant against all of them. For breadth, price_panel builds a free price panel (an index fund's holdings, prices, dollar volume and industries), breadth_book builds a sleeve for every signal in every industry from one price panel and trades them as one netted account; effective_bets counts the independent bets in any set of return series. For datasets, annotation_packet, annotation_agreement and annotation_gold turn figures into a gold set people have checked against the filings.";
 export const SERVER_INFO = Object.freeze({
   name: SERVER_NAME,
   version: SERVER_VERSION,
@@ -79,7 +83,33 @@ export const backtestInput = z.object({
   label: z.string().min(1).max(200).optional().describe("The variant's name in the ledger. Default: the settings."),
 });
 
+export const breadthInput = z.object({
+  prices_file: filePath.describe("CSV: a date column and one column of closing (total-return) prices per ticker."),
+  groups_file: filePath.optional().describe("CSV with columns ticker,group (an industry, say): one sleeve per signal per group. Default: one group, the whole panel."),
+  dollar_volume_file: filePath.optional().describe("CSV like prices_file with daily dollar volume: adds the liquidity signals, a $5m liquidity floor and cost tiers by volume."),
+  signals: z.array(z.string().min(1).max(40)).min(1).max(40).optional().describe("Signals from breadth_signals. Default: every one the data allows."),
+  min_names: z.number().int().min(3).max(200).optional().describe("Fewest eligible names a group needs at a rebalance. Default 10."),
+  smoothing: z.number().int().min(1).max(12).optional().describe("Rebalances whose weights are averaged (overlapping portfolios). Default 3 (monthly), 4 (weekly)."),
+  cost_bps: z.number().min(0).max(500).optional().describe("Cost per unit traded when no dollar volume is given. Default 10."),
+  target_vol: z.number().gt(0).max(1).optional().describe("Each sleeve's volatility target. Default 0.10."),
+  split_date: date.optional().describe("Report the book before and after this date: choose on the first part, judge on the second."),
+  out_file: filePath.optional().describe("Where to write every sleeve's daily returns (CSV, one column per sleeve): a dataset to train or select on. Its specs go beside it as .specs.json. Default: a new temporary file."),
+  ledger: z.string().regex(/^[a-z0-9][a-z0-9-]{2,63}$/).optional().describe("Record the netted book in a search ledger and judge it against every run there."),
+}).strict();
+export const betsInput = z.object({
+  returns_file: filePath.describe("CSV: a date column and one column of daily returns per series (breadth_book's out_file, say)."),
+  family_separator: z.string().min(1).max(3).optional().describe("Columns named family<sep>member are grouped into families, e.g. \"@\" for breadth_book's signal@group. Default: no families."),
+  threshold: z.number().gt(0).lt(1).optional().describe("Families whose books correlate at least this much (in absolute value, average linkage) count as one idea. Default 0.5."),
+}).strict();
+
 export const TOOL_DESCRIPTIONS = Object.freeze({
+  breadth_signals: "The cross-sectional signals breadth_book builds sleeves from: momentum, reversal, low volatility and beta, idiosyncratic risk, lottery demand, skewness, price delay, seasonality and liquidity, each with its formula's source and the data it needs.",
+  breadth_book: `Build many weakly correlated sleeves (every signal inside every group of names) from your price panel and trade them as one netted account, ALPHAC's breadth lab: rank-weighted within each group, overlapping portfolios, hedged and scaled to a volatility target, costs on actual trades. Returns the book netted and standalone, the netting ratio, effective independent bets and ideas, and writes every sleeve's returns as a training dataset. ${BREADTH_LIMITS_TEXT[1]}`,
+  annotation_packet: "Start a labelled dataset: figures (company, measure, period, value) are checked by machine against the SEC filings and written as blind CSV packets for two or more people to label, with guidelines and a key holding the machine labels.",
+  annotation_agreement: "Read filled annotation packets: how often the people agree (Cohen's kappa), how often they agree with the machine, and every disagreement.",
+  annotation_gold: "Merge filled annotation packets and a reviewer's decisions into a gold dataset (JSONL: each item's label, who decided it, the machine label and source) with a datasheet of agreement and hashes.",
+  price_panel: "Build a price panel from free sources for breadth_book or backtest_signal: the tickers you name or an index fund's current holdings, daily adjusted closes and dollar volume, and each company's Fama-French industry from its SEC SIC code, written as CSV files.",
+  effective_bets: "How many independent bets a set of return series holds: the participation ratio of their weekly correlations (n for unrelated series, 1 for copies), and with families, the families' bets and the ideas they cluster into.",
   list_factors: "The point-in-time factors pit_factor builds from SEC filings, and what each measures.",
   pit_factor: `Build a factor from SEC filings for a list of tickers, monthly from start to end, using only what had been filed by each date (restatements invisible until filed). Writes a signal CSV for backtest_signal. ${PIT_LIMITS_TEXT[0]}`,
   backtest_signal: `Backtest a signal against your prices: rank, long and short quantiles, rebalance, trading only on what was known lag_days earlier, costs on actual trades. Pass ledger to judge the best of a search against all of it. ${ENGINE_LIMITS_TEXT[1]}`,
@@ -128,6 +158,58 @@ export async function toolBacktestSignal(session, args) {
   return text({ settings, tickers: tickers.length, ...stats, plain_reading: plain, ...(search ? { search } : {}), limits: ENGINE_LIMITS_TEXT });
 }
 
+function readGroups(path) {
+  const lines = readFileSync(path, "utf8").replace(/^\uFEFF/, "").split(/\r?\n/).filter((l) => l.trim());
+  const out = {};
+  for (const [i, line] of lines.entries()) {
+    const [t, g] = line.split(",").map((x) => x.trim());
+    if (i === 0 && /^ticker$/i.test(t)) continue;
+    if (!t || !g) throw new RangeError(`groups_file line ${i + 1}: expected ticker,group`);
+    out[t] = g;
+  }
+  return out;
+}
+const asFloat = (values, tickers) => Object.fromEntries(tickers.map((t) => [t, Float64Array.from(values[t], (v) => (v === null ? NaN : v))]));
+
+export async function toolBreadthBook(session, args) {
+  const a = breadthInput.parse(args);
+  const prices = readPanel(a.prices_file, "prices_file");
+  const dv = a.dollar_volume_file ? readPanel(a.dollar_volume_file, "dollar_volume_file") : null;
+  if (dv && dv.dates.join() !== prices.dates.join()) throw new RangeError("dollar_volume_file must have the same dates as prices_file");
+  const tickers = prices.tickers.filter((t) => !dv || dv.tickers.includes(t));
+  const r = runBreadth({ dates: prices.dates, tickers, prices: asFloat(prices.values, tickers), dollarVolume: dv ? asFloat(dv.values, tickers) : null,
+    groups: a.groups_file ? readGroups(a.groups_file) : null, signals: a.signals ?? null, minNames: a.min_names ?? 10, smoothing: a.smoothing ?? null,
+    costBps: a.cost_bps ?? 10, targetVol: a.target_vol ?? 0.1, splitDate: a.split_date ?? null });
+  if (!r.sleeves) throw new RangeError("No sleeve had enough eligible names: lower min_names, add names to the groups, or check that prices are at least 5.");
+  const file = a.out_file ?? join(session.outDir ?? mkdtempSync(join(tmpdir(), "canli-breadth-")), "sleeves.csv");
+  const cell = (x) => (Number.isNaN(x) ? null : Math.round(x * 1e8) / 1e8);
+  writePanel(file, { dates: prices.dates, tickers: [...r.series.ids, "book_netted"], values: Object.fromEntries([...r.series.ids.map((id, j) => [id, Array.from(r.series.returns[j], cell)]), ["book_netted", Array.from(r.series.book, cell)]]) });
+  writeFileSync(`${file}.specs.json`, JSON.stringify({ schema: "canli.breadth-sleeves.v1", prices_file: a.prices_file, settings: { min_names: a.min_names ?? 10, smoothing: a.smoothing ?? null, cost_bps: a.cost_bps ?? 10, target_vol: a.target_vol ?? 0.1 }, sleeves: r.specs }, null, 1));
+  let search = null;
+  if (a.ledger) {
+    const res = recordTrial(session.ledgerDir, { ledger: a.ledger, label: `breadth ${r.signals} signals x ${r.groups} groups`, returns: Array.from(r.series.book).filter((x) => !Number.isNaN(x)), periods_per_year: 252, params: { signals: a.signals ?? "all", groups_file: a.groups_file ?? null, min_names: a.min_names ?? 10 } });
+    search = { ledger: res.ledger, trial: res.trial, trials: res.trials, deflated: res.deflated, plain_reading: res.plain_reading };
+  }
+  const b = r.book;
+  const top = [...r.sleeve_rows].sort((x, y) => (y[4] ?? -9) - (x[4] ?? -9));
+  return text({
+    sleeves: r.sleeves, signals: r.signals, groups: r.groups, book: b, effective_bets: r.effective_bets,
+    sleeve_columns: r.sleeve_columns, best_sleeves: top.slice(0, 10), worst_sleeves: top.slice(-5),
+    dataset: { file, specs: `${file}.specs.json`, columns: r.sleeves + 1, rows: prices.dates.length },
+    plain_reading: `${r.sleeves} sleeves (${r.signals} signals x ${r.groups} groups) hold ${r.effective_bets.effective_bets} independent bets at sleeve level${r.effective_bets.effective_bets_families ? `, ${r.effective_bets.effective_bets_families} across signal families and ${r.effective_bets.ideas} ideas` : ""}. Traded as one account the book's Sharpe after costs is ${b.netted.sharpe ?? "n/a"} (${b.standalone.sharpe ?? "n/a"} if each sleeve paid its own costs); netting cuts costs to ${b.netting_ratio} of the standalone total.`,
+    ...(search ? { search } : {}),
+    limits: BREADTH_LIMITS_TEXT,
+  });
+}
+
+export async function toolEffectiveBets(args) {
+  const a = betsInput.parse(args);
+  const p = readPanel(a.returns_file, "returns_file");
+  const series = p.tickers.map((t) => Float64Array.from(p.values[t], (v) => (v === null ? NaN : v)));
+  const family = a.family_separator ? p.tickers.map((t) => t.split(a.family_separator)[0]) : null;
+  return text({ ...effectiveBets(p.dates, series, family, { threshold: a.threshold ?? 0.5 }), meaning: "effective_bets is (sum of eigenvalues)^2 / sum of squared eigenvalues of the weekly correlation matrix: Sharpe grows with the square root of independent bets, not of series. A sign flip does not make a new bet." });
+}
+
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 const WRITES_LOCAL = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
 
@@ -140,6 +222,13 @@ export function registerTools(server, session) {
   tool("list_factors", "Point-in-time factors", z.object({}).strict(), READ_ONLY, async () => text({ factors: Object.fromEntries(Object.entries(FACTORS).map(([k, v]) => [k, v.meaning])), plus: "level:<measure> for any annual measure (revenue, net_income, assets, equity, operating_cash_flow, ...)", limits: PIT_LIMITS_TEXT }));
   tool("pit_factor", "Build a point-in-time factor", pitInput, { ...WRITES_LOCAL, openWorldHint: true }, (args) => toolPitFactor(session, args));
   tool("backtest_signal", "Backtest a signal without lookahead", backtestInput, WRITES_LOCAL, (args) => toolBacktestSignal(session, args));
+  tool("price_panel", "Build a price panel", panelInput, { ...WRITES_LOCAL, openWorldHint: true }, async (args) => text(await buildPanel(session.markets ??= marketsSession(), args)));
+  tool("breadth_signals", "Breadth lab signals", z.object({}).strict(), READ_ONLY, async () => text({ signals: signalCatalog(), next: "breadth_book with your prices_file (and groups_file, dollar_volume_file) builds a sleeve per signal per group.", limits: BREADTH_LIMITS_TEXT }));
+  tool("breadth_book", "Breadth book of sleeves", breadthInput, WRITES_LOCAL, (args) => toolBreadthBook(session, args));
+  tool("effective_bets", "Effective independent bets", betsInput, READ_ONLY, (args) => toolEffectiveBets(args));
+  tool("annotation_packet", "Annotation packets", packetInput, { ...WRITES_LOCAL, openWorldHint: true }, async (args) => text(await annotationPacket(session.markets ??= marketsSession(), args)));
+  tool("annotation_agreement", "Annotation agreement", agreementInput, READ_ONLY, async (args) => text(annotationAgreement(args)));
+  tool("annotation_gold", "Annotation gold set", goldInput, WRITES_LOCAL, async (args) => text(annotationGold(args)));
   return catalog;
 }