alphacouncil-agent 0.5.5 → 0.8.0

package/mcp/lib/personas-v2/memory.mjs

@@ -0,0 +1,156 @@
+/**
+ * Persona memory, with the time boundary that makes a backtest mean anything.
+ *
+ * Five layers: doctrine (immutable outside a release), episodic (append-only judgments),
+ * belief (current positions, pointing back at episodes), postmortem (written only after the
+ * horizon expires), working (discarded at the end of a run).
+ *
+ * The rule everything else exists to serve:
+ *
+ *     public_at <= as_of  AND  memory_created_at <= as_of
+ *
+ * Both clauses. The first keeps a model from reading a filing that had not been published.
+ * The second keeps it from reading its own diary -- a note written in 2026 is not available
+ * to a run dated 2024, however true it was. Drop the second clause and a model launders
+ * hindsight through its own memory, every backtest built on it is fiction, and the returns
+ * look wonderful for exactly the wrong reason.
+ */
+
+const LAYERS = ["doctrine", "episodic", "belief", "postmortem", "working"];
+export const MEMORY_LAYERS = Object.freeze(LAYERS);
+
+const day = 24 * 60 * 60 * 1000;
+const toTime = (value) => {
+  const t = Date.parse(String(value ?? ""));
+  return Number.isFinite(t) ? t : null;
+};
+
+export class LeakError extends Error {
+  constructor(message) { super(message); this.name = "LeakError"; }
+}
+
+/**
+ * Both clauses, applied to one record.
+ *
+ * A record missing either timestamp is *excluded*: an undated memory cannot be shown to be
+ * in the past, and admitting it "because it is probably fine" is the whole failure mode.
+ */
+export function isVisible(record, asOf) {
+  const cutoff = toTime(asOf);
+  if (cutoff === null) throw new LeakError(`as_of is not a date: ${JSON.stringify(asOf)}`);
+  const published = toTime(record?.public_at);
+  const created = toTime(record?.memory_created_at);
+  if (published === null || created === null) return false;
+  return published <= cutoff && created <= cutoff;
+}
+
+/** The reading side of the leak rule. Everything a persona sees passes through here. */
+export function visibleMemory(records, asOf, { layer } = {}) {
+  return (records || [])
+    .filter((r) => (layer ? r.layer === layer : true))
+    .filter((r) => isVisible(r, asOf));
+}
+
+/**
+ * Refuses to write a record that would be invisible to the run that created it.
+ *
+ * A memory dated after its own run is either a clock bug or hindsight being backdated
+ * forwards; both should stop the run rather than settle quietly into the archive.
+ */
+export function assertWritable(record, asOf) {
+  if (!LAYERS.includes(record?.layer)) throw new LeakError(`unknown memory layer: ${JSON.stringify(record?.layer)}`);
+  const created = toTime(record?.memory_created_at);
+  const cutoff = toTime(asOf);
+  if (created === null) throw new LeakError("memory_created_at is required");
+  if (cutoff === null) throw new LeakError(`as_of is not a date: ${JSON.stringify(asOf)}`);
+  if (created > cutoff) throw new LeakError(`memory_created_at ${record.memory_created_at} is after as_of ${asOf}`);
+  return true;
+}
+
+/** One judgment, as it was made, with the evidence it was allowed to see. */
+export function episode({ persona_id, symbol, as_of, decision, evidence_ids = [], invalidation = [], horizon_days }) {
+  return {
+    layer: "episodic",
+    persona_id,
+    symbol,
+    as_of,
+    public_at: as_of,
+    memory_created_at: as_of,
+    stance: decision?.stance,
+    reason: decision?.reason,
+    score: decision?.score ? { score: decision.score.score, max_possible: decision.score.max_possible, coverage: decision.score.coverage } : null,
+    evidence_ids,
+    invalidation,
+    horizon_days: horizon_days ?? null,
+    expires_at: horizon_days ? new Date(toTime(as_of) + horizon_days * day).toISOString().slice(0, 10) : null,
+  };
+}
+
+/**
+ * A postmortem may not be written before the horizon it is judging has elapsed.
+ *
+ * Grading a call the day after making it is how a system convinces itself it was right: at
+ * that distance the outcome is still mostly noise, and the note it leaves behind becomes a
+ * belief that steers every later run.
+ */
+export function canWritePostmortem(ep, now) {
+  const expires = toTime(ep?.expires_at);
+  const t = toTime(now);
+  if (expires === null) return { allowed: false, reason: "no_horizon" };
+  if (t === null) return { allowed: false, reason: "no_clock" };
+  return t >= expires ? { allowed: true } : { allowed: false, reason: "horizon_not_reached", expires_at: ep.expires_at };
+}
+
+export function postmortem({ episode: ep, now, outcome, failure_mode, rule_updates = [] }) {
+  const gate = canWritePostmortem(ep, now);
+  if (!gate.allowed) throw new LeakError(`postmortem refused: ${gate.reason}${gate.expires_at ? ` (expires ${gate.expires_at})` : ""}`);
+  return {
+    layer: "postmortem",
+    persona_id: ep.persona_id,
+    symbol: ep.symbol,
+    as_of: ep.as_of,
+    public_at: now,
+    memory_created_at: now,
+    outcome,
+    // Which of the four it was matters more than whether the call made money: data, method,
+    // timing and leakage each imply a different repair.
+    failure_mode: failure_mode ?? null,
+    rule_updates,
+  };
+}
+
+/**
+ * Current beliefs, each pointing back at the episode that formed it.
+ *
+ * Decayed rather than deleted: a stale belief is reported as stale so the reader can see
+ * the model is running on an old read, which is different from having no view.
+ */
+export function currentBeliefs(records, asOf, { decay_days } = {}) {
+  const cutoff = toTime(asOf);
+  const visible = visibleMemory(records, asOf, { layer: "belief" });
+  const latest = new Map();
+  for (const record of visible) {
+    const prev = latest.get(record.claim_id);
+    if (!prev || toTime(record.memory_created_at) > toTime(prev.memory_created_at)) latest.set(record.claim_id, record);
+  }
+  return [...latest.values()].map((record) => {
+    const age = decay_days ? Math.floor((cutoff - toTime(record.memory_created_at)) / day) : null;
+    return { ...record, age_days: age, stale: decay_days ? age > decay_days : false };
+  });
+}
+
+/**
+ * What a persona is allowed to carry into a run at `as_of`.
+ *
+ * Working memory is never returned: it belongs to the run that made it and must not become
+ * a long-term belief by default.
+ */
+export function recallFor(pack, records, asOf) {
+  const decay = pack?.memory_policy?.belief_decay_days;
+  return {
+    episodic: visibleMemory(records, asOf, { layer: "episodic" }),
+    beliefs: currentBeliefs(records, asOf, { decay_days: decay }),
+    postmortems: visibleMemory(records, asOf, { layer: "postmortem" }),
+    excluded_by_leak_rule: (records || []).filter((r) => r.layer !== "working" && !isVisible(r, asOf)).length,
+  };
+}

package/mcp/lib/personas-v2/policy.mjs

@@ -0,0 +1,187 @@
+/**
+ * The deterministic half of a method model.
+ *
+ * Everything here runs before any model call and decides the things a language model must
+ * not decide: whether the method can evaluate this security at all, what it scores, which
+ * vetoes fire, and therefore what stance gets narrated. The model writes prose about a
+ * verdict it did not choose.
+ *
+ * Pure by construction: no network, no clock, no filesystem. Same inputs, same decision.
+ */
+
+const OPS = {
+  ">=": (a, b) => a >= b,
+  ">": (a, b) => a > b,
+  "<=": (a, b) => a <= b,
+  "<": (a, b) => a < b,
+  "==": (a, b) => a === b,
+  "!=": (a, b) => a !== b,
+};
+
+/** `a.b.c` against a plain object. Returns undefined rather than throwing on a gap. */
+export function readPath(facts, path) {
+  return String(path || "").split(".").reduce((node, key) => (
+    node && typeof node === "object" && key in node ? node[key] : undefined
+  ), facts);
+}
+
+const MISSING = (v) => v === undefined || v === null || v === "" || (typeof v === "number" && !Number.isFinite(v));
+
+/**
+ * Can this method evaluate this security at all?
+ *
+ * A requirement whose input is missing fails the gate. That is deliberate and is the
+ * opposite of the mechanical screen's rule for scoring: there, a missing input is `skipped`
+ * and must never be read as a pass. Here, missing inputs are precisely the reason a method
+ * should decline, and declining early costs nothing and says more than an essay would.
+ */
+export function evaluateEligibility(pack, facts) {
+  const requires = pack?.decision_policy?.eligibility?.requires || [];
+  const unmet = [];
+  for (const requirement of requires) {
+    const parsed = parseCondition(requirement);
+    if (!parsed) { unmet.push({ requirement, reason: "unparsable" }); continue; }
+    const actual = readPath(facts, parsed.path);
+    if (MISSING(actual)) { unmet.push({ requirement, reason: "missing_input", path: parsed.path }); continue; }
+    if (!compare(actual, parsed.op, parsed.value)) {
+      unmet.push({ requirement, reason: "not_met", path: parsed.path, actual });
+    }
+  }
+  return { eligible: unmet.length === 0, unmet };
+}
+
+/**
+ * `path >= 4`, `path` (truthy), `!path` (falsy). Small on purpose: a condition language
+ * that grows an evaluator grows a way to be wrong quietly.
+ */
+export function parseCondition(text) {
+  const raw = String(text || "").trim();
+  if (!raw) return null;
+  const m = /^([A-Za-z0-9_.]+)\s*(>=|<=|==|!=|>|<)\s*(.+)$/.exec(raw);
+  if (m) return { path: m[1], op: m[2], value: literal(m[3]) };
+  if (/^![A-Za-z0-9_.]+$/.test(raw)) return { path: raw.slice(1), op: "==", value: false };
+  if (/^[A-Za-z0-9_.]+$/.test(raw)) return { path: raw, op: "==", value: true };
+  return null;
+}
+
+function literal(text) {
+  const t = String(text).trim().replace(/^["']|["']$/g, "");
+  if (t === "true") return true;
+  if (t === "false") return false;
+  const n = Number(t);
+  return Number.isFinite(n) && t !== "" ? n : t;
+}
+
+function compare(actual, op, expected) {
+  if (typeof expected === "boolean") return op === "!=" ? Boolean(actual) !== expected : Boolean(actual) === expected;
+  const fn = OPS[op];
+  return fn ? fn(actual, expected) : false;
+}
+
+/**
+ * Score the method's own rules.
+ *
+ * A rule whose input is missing is `uncomputable` -- never a miss, never a hit. Folding it
+ * into either one is how a screen reports "6/7 passed" while hiding that the seventh was
+ * never evaluated. `max_possible` therefore excludes uncomputable rules, so the ratio
+ * describes what was actually measured, and `coverage` reports how much of the method ran.
+ */
+export function scoreMethod(pack, facts) {
+  const scoring = pack?.decision_policy?.scoring;
+  if (!scoring) return { score: 0, max_possible: 0, declared_max: 0, coverage: 0, hits: [], misses: [], uncomputable: [] };
+  const hits = [];
+  const misses = [];
+  const uncomputable = [];
+  let score = 0;
+  let max_possible = 0;
+
+  for (const rule of scoring.rules || []) {
+    const actual = readPath(facts, rule.metric);
+    if (MISSING(actual)) { uncomputable.push({ id: rule.id, metric: rule.metric }); continue; }
+    max_possible += rule.points;
+    if (compare(actual, rule.op, rule.value)) {
+      score += rule.points;
+      hits.push({ id: rule.id, metric: rule.metric, actual, threshold: rule.value, points: rule.points, provenance: rule.provenance });
+    } else {
+      misses.push({ id: rule.id, metric: rule.metric, actual, threshold: rule.value, points: rule.points, provenance: rule.provenance });
+    }
+  }
+  const declared_max = scoring.max_score || 0;
+  return {
+    score,
+    max_possible,
+    declared_max,
+    coverage: declared_max ? max_possible / declared_max : 0,
+    hits,
+    misses,
+    uncomputable,
+  };
+}
+
+/** Vetoes are absolute: one fires and the stance is opposed regardless of score. */
+export function evaluateVetoes(pack, facts) {
+  const triggered = [];
+  for (const veto of pack?.decision_policy?.vetoes || []) {
+    const parsed = parseCondition(veto.condition);
+    if (!parsed) continue;
+    const actual = readPath(facts, parsed.path);
+    if (MISSING(actual)) continue;
+    if (compare(actual, parsed.op, parsed.value)) {
+      triggered.push({ id: veto.id, condition: veto.condition, actual, source_ids: veto.source_ids || [] });
+    }
+  }
+  return triggered;
+}
+
+/** Highest band whose floor the ratio clears. */
+export function stanceFromRatio(pack, ratio) {
+  const bands = [...(pack?.decision_policy?.stance_bands || [])].sort((a, b) => b.min_ratio - a.min_ratio);
+  for (const band of bands) if (ratio >= band.min_ratio) return band.stance;
+  return "out_of_scope";
+}
+
+/**
+ * The whole deterministic decision. `narratable` tells the caller whether spending a model
+ * call is warranted at all -- an ineligible method has nothing for a model to say.
+ */
+export function decide(pack, facts, { min_coverage = 0.5 } = {}) {
+  const eligibility = evaluateEligibility(pack, facts);
+  if (!eligibility.eligible) {
+    return {
+      persona_id: pack?.persona_id,
+      stance: "out_of_scope",
+      reason: "eligibility",
+      eligibility,
+      narratable: false,
+      score: null,
+      vetoes_triggered: [],
+    };
+  }
+  const scored = scoreMethod(pack, facts);
+  // Enough of the method has to have run for its score to mean anything. A rule set that
+  // could only evaluate a fifth of itself has not judged the company, it has sampled it.
+  if (scored.declared_max && scored.coverage < min_coverage) {
+    return {
+      persona_id: pack?.persona_id,
+      stance: "out_of_scope",
+      reason: "insufficient_coverage",
+      eligibility,
+      score: scored,
+      narratable: false,
+      vetoes_triggered: [],
+    };
+  }
+  const vetoes_triggered = evaluateVetoes(pack, facts);
+  const ratio = scored.max_possible ? scored.score / scored.max_possible : 0;
+  const stance = vetoes_triggered.length ? "opposed" : stanceFromRatio(pack, ratio);
+  return {
+    persona_id: pack?.persona_id,
+    stance,
+    reason: vetoes_triggered.length ? "veto" : "score",
+    eligibility,
+    score: scored,
+    ratio,
+    vetoes_triggered,
+    narratable: true,
+  };
+}

package/mcp/lib/personas-v2/slice.mjs

@@ -0,0 +1,96 @@
+/**
+ * Information asymmetry, enforced.
+ *
+ * The frozen fact pack is shared and identical for every model -- four methods must not
+ * discover four market caps in the name of independence. What differs is what each one is
+ * allowed to look at on top of it, and that is the only lever in this system that produces
+ * disagreement from something other than tone.
+ *
+ * A model that never sees the price cannot anchor on the drawdown. That is the point, and
+ * it only holds if the exclusion is applied here rather than requested in a prompt.
+ */
+
+/** Facts every model shares and none may overwrite. */
+export const FROZEN_KEYS = Object.freeze(["quote", "filer", "screen", "as_of", "symbol"]);
+
+export class SliceError extends Error {
+  constructor(message) { super(message); this.name = "SliceError"; }
+}
+
+/**
+ * The evidence one model may read: the frozen pack, plus only the analyst packets its
+ * research policy names.
+ *
+ * @returns {{frozen: object, packets: object[], excluded: string[], slice: string[]}}
+ */
+export function sliceFor(pack, { frozen = {}, packets = [] } = {}) {
+  const slice = pack?.research_policy?.evidence_slice;
+  // No declared slice means the model sees everything. That is a legitimate configuration,
+  // but it is recorded so a differentiation result can be read in the right light: seats
+  // sharing all evidence should not then be credited for agreeing.
+  const unrestricted = !Array.isArray(slice) || slice.length === 0;
+  const allowed = new Set(unrestricted ? (packets || []).map((p) => p.task) : slice);
+  const kept = (packets || []).filter((p) => allowed.has(p.task));
+  const excluded = (packets || []).filter((p) => !allowed.has(p.task)).map((p) => p.task);
+  return {
+    persona_id: pack?.persona_id,
+    frozen: pickFrozen(frozen),
+    packets: kept,
+    slice: unrestricted ? "unrestricted" : [...slice],
+    excluded,
+  };
+}
+
+function pickFrozen(frozen) {
+  const out = {};
+  for (const key of FROZEN_KEYS) if (key in (frozen || {})) out[key] = frozen[key];
+  return out;
+}
+
+/**
+ * A model may disagree with a derived number. It may not silently replace a filed one.
+ *
+ * Recomputation is where independence is supposed to live, so the check is on the write
+ * rather than on the intent: a private figure that contradicts the frozen pack is kept and
+ * flagged as a dispute, never merged over the top of it.
+ */
+export function reconcile(frozen, recomputed) {
+  const disputes = [];
+  const accepted = {};
+  for (const [path, value] of Object.entries(recomputed || {})) {
+    const filed = FROZEN_KEYS.some((key) => path === key || path.startsWith(`${key}.`))
+      ? readPath(frozen, path)
+      : undefined;
+    if (filed !== undefined && filed !== null && filed !== value) {
+      disputes.push({ path, filed, recomputed: value });
+      continue;
+    }
+    accepted[path] = value;
+  }
+  return { accepted, disputes };
+}
+
+function readPath(node, path) {
+  return String(path).split(".").reduce((n, k) => (n && typeof n === "object" && k in n ? n[k] : undefined), node);
+}
+
+/**
+ * Round one carries no name and no style: evidence, computation, decision, confidence,
+ * the abandonment condition, and where it is most likely wrong. Identity is attached
+ * afterwards, so the debate argues with a judgment before it knows whose it is.
+ */
+export function anonymize(opinion) {
+  const {
+    persona_id, master, display_name, voice, // eslint-disable-line no-unused-vars
+    ...rest
+  } = opinion || {};
+  return { ...rest, submitted_as: "anonymous" };
+}
+
+/** Two anonymous submissions are comparable only if identity really is gone. */
+export function assertAnonymous(submission) {
+  for (const key of ["persona_id", "master", "display_name", "voice"]) {
+    if (key in (submission || {})) throw new SliceError(`anonymous submission still carries ${key}`);
+  }
+  return true;
+}

package/mcp/lib/rpc.mjs

@@ -1,9 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import readline from "node:readline";
-import { LIMITS, OUTPUT_MODES, SERVER_NAME, VERSION } from "./constants.mjs";
+import { LIMITS, MASTER_STANCES, OUTPUT_MODES, SERVER_NAME, VERSION } from "./constants.mjs";
 import { RpcCode, methodNotFound, invalidParams, toRpcError } from "./errors.mjs";
-import { readJson, readJsonl } from "./fsutil.mjs";
+import { readJson, readJsonl, writeJson } from "./fsutil.mjs";
 import { resolveLanguage } from "./lang.mjs";
 import { sweepStaleOutputs } from "./codex.mjs";
 import { sourceManifest } from "./gates.mjs";
@@ -38,6 +38,36 @@ export function sendError(id, code, message, data) {
   send({ jsonrpc: "2.0", id, error: { code, message, ...(data === undefined ? {} : { data }) } });
 }
 
+/**
+ * What a `record_*` call returns: progress, not the whole run.
+ *
+ * These handlers used to echo the entire run object -- every packet, every master opinion,
+ * the full grounding block -- on every call. The payload therefore grew with each recording,
+ * and late in a twenty-one-seat run a single response passed 240k characters. On any host
+ * that keeps tool results in the transcript that is a context-exhaustion bug, and it gets
+ * worse exactly when the run is most nearly finished.
+ *
+ * The caller needs to know what landed and what is still outstanding. The full state is on
+ * disk in status.json and is one read away for anyone who wants it.
+ */
+export function recordAck(run, extra = {}) {
+  return {
+    run_id: run.run_id,
+    symbol: run.symbol,
+    status: run.status,
+    phase: run.phase,
+    recorded_tasks: (run.packets || []).map((p) => p.task),
+    pending_tasks: (run.tasks || []).filter((t) => !(run.packets || []).some((p) => p.task === t)),
+    recorded_masters: (run.master_opinions || []).map((o) => o.master),
+    pending_masters: (run.masters || []).filter((m) => !(run.master_opinions || []).some((o) => o.master === m)),
+    completeness: run.completeness,
+    missing_evidence_count: run.missing_evidence_count,
+    missing_debate_count: run.missing_debate_count,
+    status_json: join(runPath(run.run_id), "status.json"),
+    ...extra,
+  };
+}
+
 export function jsonContent(text, structuredContent = {}) {
   return {
     content: [{ type: "text", text }],
@@ -136,7 +166,11 @@ export function tools() {
       properties: {
         run_id: { type: "string" },
         master: { type: "string", enum: masterIds },
-        packet: { type: "object" },
+        packet: {
+          type: "object",
+          description: `The master_opinion packet. stance MUST be one of ${MASTER_STANCES.join(" | ")} -- anything else is recorded as out_of_scope and carries zero weight, so a seat whose stance does not survive normalization silently stops voting. Common synonyms (long/bullish, neutral/hold, short/bearish/avoid, n/a/abstain) are mapped for you.`,
+          properties: { stance: { type: "string", enum: MASTER_STANCES } },
+        },
         thread_id: { type: "string" },
       },
       required: ["run_id", "master", "packet"],
@@ -326,6 +360,13 @@ export async function handleToolCall(id, params) {
       saveRun(run);
     }
     const specs = visibleAgentSpecs(run, args.prompt || "");
+    // Planning settles every seat whose method cannot reach this security, writing those
+    // opinions directly. They have to be persisted here or the completeness gate would keep
+    // waiting for a report from a seat that will never be spawned.
+    if (specs.masters_declined?.length) {
+      saveRun(run);
+      writeJson(join(runPath(run.run_id), "evidence.json"), run);
+    }
     // Returned with the plan, not left to a separate opt-in call: a host that skips the
     // preflight is exactly the host whose subagents will fail silently.
     const preflight = preflightNetworkPermissions({ roster: args.roster || "default" });
@@ -347,19 +388,28 @@ export async function handleToolCall(id, params) {
   }
   if (name === "record_visible_packet") {
     const run = recordVisiblePacket(args);
-    sendResult(id, jsonContent(`Recorded visible evidence packet ${args.task} for ${run.symbol}: ${run.run_id}`, run));
+    sendResult(id, jsonContent(`Recorded visible evidence packet ${args.task} for ${run.symbol}: ${run.run_id}`, recordAck(run)));
     return;
   }
   if (name === "record_visible_decision") {
     const result = recordVisibleDecision(args);
-    sendResult(id, jsonContent(`Recorded visible decision ${args.role} for ${result.run.symbol}: ${result.run.run_id}`, result));
+    sendResult(id, jsonContent(
+      `Recorded visible decision ${args.role} for ${result.run.symbol}: ${result.run.run_id}`,
+      // decision and opinion are small and are what a caller reads back; only the full
+      // run object is dropped.
+      recordAck(result.run, {
+        decision: result.decision,
+        report_quality: result.report_quality?.status,
+        missing_report_items: result.report_quality?.missing || [],
+      }),
+    ));
     return;
   }
   if (name === "record_master_opinion") {
     const result = recordMasterOpinion(args);
     sendResult(id, jsonContent(
       `Recorded master opinion ${args.master} (${result.opinion.stance}) for ${result.run.symbol}: ${result.recorded}/${result.expected} master seats in.`,
-      result,
+      recordAck(result.run, { opinion: result.opinion, recorded: result.recorded, expected: result.expected }),
     ));
     return;
   }

package/mcp/lib/screen.mjs

@@ -17,8 +17,16 @@ const pct = (x) => (x === null ? null : Number((x * 100).toFixed(2)));
 const last = (series, n) => series.slice(-n);
 const sum = (xs) => xs.reduce((a, b) => a + b, 0);
 
+/**
+ * XBRL reports share counts under the `shares` unit, not `USD`. Requesting the default unit
+ * for a share concept returns nothing, so the dilution rule reported `skipped` for every
+ * company that has ever been screened -- seven rules advertised, six ever computed, and the
+ * skip looked exactly like a genuine data gap.
+ */
+const UNIT_BY_CONCEPT = { sharesOutstanding: "shares" };
+
 function values(facts, key, asOf) {
-  const found = annualSeries(facts, CONCEPTS[key], { asOf });
+  const found = annualSeries(facts, CONCEPTS[key], { asOf, unit: UNIT_BY_CONCEPT[key] || "USD" });
   return found ? found.series.map((e) => ({ end: e.end, filed: e.filed, val: e.val })) : [];
 }
 

package/mcp/lib/sec.mjs

@@ -70,26 +70,80 @@ export async function fetchCompanyFacts(cik) {
  * Tries several tags because the same economic quantity has different names depending on
  * when and under which taxonomy a company filed.
  */
+/**
+ * How long a reported period is, in days. Instant facts (balance-sheet items) have no start.
+ */
+const spanDays = (entry) =>
+  entry.start ? Math.round((Date.parse(entry.end) - Date.parse(entry.start)) / 86400000) : null;
+
+/**
+ * Is this entry an annual figure?
+ *
+ * A 10-K carries quarterly and stub periods alongside the annual ones. Keying only on the
+ * end date treated each as its own year: Lumentum's 2015 produced ten "years" from one
+ * fiscal year -- nine quarters and stubs plus the real 363-day period. Every multi-year rule
+ * then averaged quarterly income against annual equity, silently.
+ *
+ * Fiscal years run 52 or 53 weeks, so the window has to be wider than 365 exactly.
+ */
+const ANNUAL_MIN_DAYS = 300;
+const ANNUAL_MAX_DAYS = 400;
+const isAnnual = (entry) => {
+  const days = spanDays(entry);
+  // Instant facts have no duration: shares outstanding, equity, total assets.
+  if (days === null) return true;
+  return days >= ANNUAL_MIN_DAYS && days <= ANNUAL_MAX_DAYS;
+};
+
+/** The fiscal year a period belongs to, taken from its end date. */
+const fiscalYear = (entry) => Number(String(entry.end).slice(0, 4));
+
+/**
+ * Annual history for a concept, merged across every alias.
+ *
+ * Merging matters as much as the annual filter. The function used to return at the first
+ * alias with any data, and revenue moved to RevenueFromContractWithCustomerExcludingAssessedTax
+ * when ASC 606 was adopted -- so a company reporting under the new tag since 2022 looked like
+ * it had four years of history, which then fired a "listed under ten years" exemption on a
+ * company that had been public for a decade.
+ *
+ * Aliases are ordered by preference, so an earlier alias wins where both cover a year.
+ */
 export function annualSeries(facts, tags, { asOf = null, unit = "USD" } = {}) {
   const cutoff = asOf ? new Date(asOf).getTime() : null;
+  const byYear = new Map();
+  let usedTags = [];
+
   for (const tag of tags) {
     const entries = facts?.facts?.["us-gaap"]?.[tag]?.units?.[unit];
     if (!Array.isArray(entries) || entries.length === 0) continue;
+    let contributed = false;
 
-    const byPeriod = new Map();
     for (const entry of entries) {
       if (entry.form !== "10-K" || !entry.end || !Number.isFinite(entry.val)) continue;
+      if (!isAnnual(entry)) continue;
       // Look-ahead guard: a filing is only usable once it was actually filed.
       if (cutoff && new Date(entry.filed).getTime() > cutoff) continue;
-      const prior = byPeriod.get(entry.end);
-      // Keep the most recently filed value for a period: restatements supersede.
-      if (!prior || new Date(entry.filed) > new Date(prior.filed)) byPeriod.set(entry.end, entry);
+
+      const year = fiscalYear(entry);
+      const prior = byYear.get(year);
+      if (!prior) {
+        byYear.set(year, { ...entry, tag });
+        contributed = true;
+        continue;
+      }
+      // An earlier alias always wins the year; within one alias, the latest filing wins,
+      // because a restatement supersedes what it restates.
+      if (prior.tag === tag && new Date(entry.filed) > new Date(prior.filed)) {
+        byYear.set(year, { ...entry, tag });
+      }
     }
-    if (byPeriod.size === 0) continue;
-    const series = [...byPeriod.values()].sort((a, b) => new Date(a.end) - new Date(b.end));
-    return { tag, unit, series };
+    if (contributed) usedTags.push(tag);
   }
-  return null;
+
+  if (byYear.size === 0) return null;
+  const series = [...byYear.values()].sort((a, b) => new Date(a.end) - new Date(b.end));
+  return { tag: usedTags[0], tags: usedTags, unit, series };
 }
 
 /** Concept aliases, ordered by preference. */