alphacouncil-agent 1.0.2 → 1.0.4

package/mcp/lib/orchestrator.mjs

@@ -1200,7 +1200,15 @@ export async function groundingForHeadlessRun({ symbol, asOf, grounding, dryRun,
   let timer;
   const controller = Number.isFinite(timeoutMs) ? new AbortController() : null;
   try {
-    const work = gather({ symbol, asOf, ...(controller ? { signal: controller.signal } : {}) });
+    // The budget is handed DOWN so grounding can settle and return what it has. Racing it from
+    // out here discarded a completed quote and a completed screen whenever one feed was slow,
+    // and the analysts then reported a missing ticker for a symbol that had been supplied.
+    // The outer race stays as a backstop, with headroom, for a call that hangs entirely.
+    const work = gather({
+      symbol, asOf,
+      ...(Number.isFinite(timeoutMs) ? { budgetMs: timeoutMs } : {}),
+      ...(controller ? { signal: controller.signal } : {}),
+    });
     if (!Number.isFinite(timeoutMs)) return await work;
     return await Promise.race([
       work,
@@ -1209,7 +1217,7 @@ export async function groundingForHeadlessRun({ symbol, asOf, grounding, dryRun,
           const error = new Error(`quick grounding timed out after ${Math.round(timeoutMs)}ms`);
           reject(error);
           controller?.abort(error);
-        }, timeoutMs);
+        }, timeoutMs + LIMITS.GROUNDING_SETTLE_HEADROOM_MS);
       }),
     ]);
   } catch (error) {

package/mcp/lib/personas/engine.mjs

@@ -13,6 +13,8 @@ import { typedFactPackFromGrounding } from "../personas-v3/grounding-adapter.mjs
 import { buildAnonymousPreDecision, freezeAnonymousDecision } from "../personas-v3/runtime.mjs";
 import { executeDeterministicPersonaPolicy } from "../personas-v3/deterministic-executor.mjs";
 import { languageKey, localized } from "../lang.mjs";
+import { displayMasterLabel } from "../markdown.mjs";
+import { voiceFromDecision, voiceFromDecline } from "../voice-from-decision.mjs";
 import {
   declinedOpinion as v2DeclinedOpinion,
   planMasters as planLegacyMasters,
@@ -77,7 +79,19 @@ function planV3Seat(run, id, pack) {
       pack,
     };
   }
-  if (preDecision.eligibility.status !== "ready") {
+  // A seat with SOME of its required facts still runs its own policy.
+  //
+  // Several seats are authored with a veto that says, in the method's own words, what an absent
+  // fact means -- Pabrai passing without a downside floor, Graham without an asset floor. Those
+  // facts are also tool inputs, so a missing one used to end the run at this gate and the veto
+  // written for exactly that case never executed. The seat then reported "missing X", which is
+  // the runtime describing itself rather than the method answering.
+  //
+  // Vetoes are evaluated before scoring, and every tool, veto and rule already declares its own
+  // `on_missing` and `on_uncomputable` behaviour, so letting the policy run does not invent an
+  // answer: it reaches the authored one. A seat with NONE of its required facts is still a hard
+  // decline -- there is no method left to run.
+  if (preDecision.eligibility.status === "out_of_scope") {
     const frozenDecision = freezeAnonymousDecision(preDecision);
     return {
       id,
@@ -106,9 +120,27 @@ function planV3Seat(run, id, pack) {
       decision: v3DecisionRecord(id, pack, preDecision, frozenDecision),
     };
   } catch (error) {
-    // A malformed policy, unknown operation, missing declared fact, or arithmetic failure
-    // blocks this physical v3 seat. The seat still owns the ID and never falls through to a
-    // legacy prompt or an LLM-authored stance.
+    // A seat that could not run because a fact it needs is absent has DECLINED, not broken.
+    // Partially grounded seats now execute so their authored vetoes can answer, and a seat
+    // without such a veto reaches the same clean abstention it always did -- reporting that as
+    // a blocked policy would turn "there was nothing to compute with" into "the system
+    // failed", which is the confusion this whole pass exists to remove.
+    if (preDecision?.eligibility?.status === "insufficient_grounding" && error?.code === "MISSING_TOOL_INPUT") {
+      const frozenDecision = freezeAnonymousDecision(preDecision);
+      return {
+        id,
+        engine: "v3_method_runtime",
+        declined: true,
+        reason: preDecision.eligibility.status,
+        pack,
+        preDecision,
+        frozenDecision,
+        decision: v3DecisionRecord(id, pack, preDecision, frozenDecision),
+      };
+    }
+    // A malformed policy, unknown operation, or arithmetic failure blocks this physical v3
+    // seat. The seat still owns the ID and never falls through to a legacy prompt or an
+    // LLM-authored stance.
     return {
       id,
       engine: "v3_method_runtime",
@@ -191,8 +223,12 @@ export function completedMasterOpinion(run, item) {
   }
   const result = item.frozenDecision.structured_decision.result;
   const locale = languageKey(run.language);
-  const label = item.pack.admitted_label?.[locale]
-    || item.pack.admitted_label?.en || item.id;
+  // The pack's admitted label carries a maturity suffix -- "provisional operator lens" and its
+  // translations -- which belongs in the assurance section, not inside a sentence about the
+  // company. Left in, every statement read "using the X provisional operator lens method",
+  // which is both ungrammatical and a second copy of a disclosure the report already makes.
+  const label = displayMasterLabel(item.pack.admitted_label?.[locale]
+    || item.pack.admitted_label?.en || item.id);
   const copy = localized(run.language, {
     en: { withheld: (pct) => `${pct}% coverage; score withheld`, unscored: "not scored", verdict: (stance, reason) => `${label} frozen decision: ${stance} (${reason})`, summary: (score) => `Using the ${label} method on ${run.symbol}, the PersonaPack v3 deterministic policy executed with score ${score}. Typed facts, hard vetoes, and score bands produced this stance; no language model selected it.`, hit: (id) => `score hit: ${id}`, miss: (id) => `score miss: ${id}`, eligibility: (id) => `eligibility condition ${id} becomes satisfied`, veto: (id) => `hard veto ${id} no longer triggers`, score: (id) => `score condition ${id} becomes satisfied` },
     zh: { withheld: (pct) => `覆盖率 ${pct}%，分数被保留不发布`, unscored: "未评分", verdict: (stance, reason) => `${label}的冻结结论：${stance}（${reason}）`, summary: (score) => `按${label}方法审视 ${run.symbol}：PersonaPack v3 确定性政策已执行，得分 ${score}。该立场由结构化事实、硬否决和评分带产生，没有让语言模型选择立场。`, hit: (id) => `评分命中：${id}`, miss: (id) => `评分未命中：${id}`, eligibility: (id) => `资格条件 ${id} 变为满足`, veto: (id) => `硬否决 ${id} 不再触发`, score: (id) => `评分条件 ${id} 变为满足` },
@@ -223,6 +259,16 @@ export function completedMasterOpinion(run, item) {
     verdict: copy.verdict(result.stance, result.reason),
     summary: deterministicStatement,
     voice_statement: deterministicStatement,
+    // The five fields, composed from the frozen decision rather than written about it: which
+    // facts were read and their values, what the tools produced, which scoring conditions held
+    // and which did not, and what would move the verdict. A one-line statement told a reader
+    // the stance and nothing about how it was reached.
+    voice: voiceFromDecision({
+      result,
+      policy: item.pack.components?.decision_policy,
+      factPack: item.preDecision?.fact_pack,
+      language: run.language,
+    }),
     voice_status: "deterministic_fallback",
     voice_language: run.language,
     statement_origin: "deterministic_policy_fallback",
@@ -263,8 +309,12 @@ export function declinedMasterOpinion(run, item) {
   if (item?.engine !== "v3_method_runtime") return v2DeclinedOpinion(run, item.id, item.decision);
   const eligibility = item.preDecision.eligibility;
   const locale = languageKey(run.language);
-  const label = item.pack.admitted_label?.[locale]
-    || item.pack.admitted_label?.en || item.id;
+  // The pack's admitted label carries a maturity suffix -- "provisional operator lens" and its
+  // translations -- which belongs in the assurance section, not inside a sentence about the
+  // company. Left in, every statement read "using the X provisional operator lens method",
+  // which is both ungrammatical and a second copy of a disclosure the report already makes.
+  const label = displayMasterLabel(item.pack.admitted_label?.[locale]
+    || item.pack.admitted_label?.en || item.id);
   const instrument = run?.grounding?.instrument;
   const fundOrIndex = instrument?.fund_like === true || instrument?.index_like === true
     || ["etf", "mutual_fund", "index"].includes(instrument?.asset_type);
@@ -284,7 +334,14 @@ export function declinedMasterOpinion(run, item) {
     verdict: copy.verdict,
     summary: copy.summary(missing),
     voice_statement: deterministicStatement,
-    voice_status: "deterministic_fallback",
+    // The five fields, composed from the frozen decision rather than written about it: which
+    // facts were read and their values, what the tools produced, which scoring conditions held
+    // and which did not, and what would move the verdict. A one-line statement told a reader
+    // the stance and nothing about how it was reached.
+    // An abstention is readable too: what the method did have, what it needed, and why it will
+    // not substitute a proxy for the difference.
+    voice: voiceFromDecline({ eligibility, language: run.language }),
+    voice_status: "deterministic_scope",
     voice_language: run.language,
     statement_origin: "deterministic_scope_fallback",
     key_findings: [deterministicStatement],

package/mcp/lib/personas-v3/deterministic-executor.mjs

@@ -701,9 +701,33 @@ function nativeMetrics(policy, facts, outputs) {
   return { metrics, status };
 }
 
+/** True when a condition reads only typed facts and literals, so no tool has to run first. */
+function readsOnlyFacts(node) {
+  if (!node || typeof node !== "object") return true;
+  if (Object.hasOwn(node, "output_id")) return false;
+  return Object.values(node).every((value) => (
+    Array.isArray(value) ? value.every(readsOnlyFacts) : readsOnlyFacts(value)
+  ));
+}
+
 function executeValidatedPolicy(preDecision, policy, tools, pipeline) {
   const facts = new Map(preDecision.fact_pack.facts.map((fact) => [fact.fact_id, fact]));
   const outputs = new Map();
+
+  // A veto that reads only facts is evaluated before any tool runs.
+  //
+  // Several seats are authored with a veto that says what an ABSENT fact means -- Pabrai
+  // passing without a downside floor, Graham without an asset floor. That same fact is usually
+  // a tool input, and a tool declaring `on_missing: "fail"` aborts the whole policy before any
+  // veto is reached, so the seat reported a missing input and the author's answer never ran.
+  // Hoisting fact-only vetoes changes no arithmetic: they need nothing a tool produces, and a
+  // veto that reads a tool output still waits for it.
+  const vetoedOnFactsAlone = policy.hard_vetoes.some((record, index) => {
+    if (!readsOnlyFacts(record.condition)) return false;
+    const early = evaluateCondition(record.condition, facts, outputs, `decision_policy.hard_vetoes[${index}].condition`);
+    return early.computable ? Boolean(early.value) : record.on_uncomputable.action === "trigger";
+  });
+
   const toolById = new Map(tools.map((tool) => [tool.id, tool]));
   const toolTrace = [];
   for (const toolId of pipeline) {
@@ -712,7 +736,12 @@ function executeValidatedPolicy(preDecision, policy, tools, pipeline) {
     const resolved = tool.inputs.map((operand) => resolveOperand(operand, facts, outputs));
     const missing = unique(resolved.flatMap((input) => input.missing_input_ids));
     if (missing.length) {
-      if (tool.on_missing === "fail") policyFail("MISSING_TOOL_INPUT", `tool ${tool.id} is missing an input`, { tool_id: tool.id, missing_input_ids: missing });
+      // A tool that cannot run is fatal, EXCEPT when a fact-only veto has already decided this
+      // seat. Then the arithmetic it would have fed is irrelevant to the outcome, and aborting
+      // reports a missing input in place of the answer the author wrote for exactly this case.
+      if (tool.on_missing === "fail" && !vetoedOnFactsAlone) {
+        policyFail("MISSING_TOOL_INPUT", `tool ${tool.id} is missing an input`, { tool_id: tool.id, missing_input_ids: missing });
+      }
       toolTrace.push({
         tool_id: tool.id,
         tool_version: tool.version,
@@ -894,7 +923,15 @@ function executeValidatedPolicy(preDecision, policy, tools, pipeline) {
 /** Execute and freeze one ready anonymous pre-decision. */
 export function executeDeterministicPersonaPolicy(preDecision) {
   if (!isObject(preDecision) || preDecision.phase !== "anonymous_pre_decision") policyFail("INVALID_PRE_DECISION", "expected an anonymous_pre_decision payload");
-  if (preDecision.eligibility?.status !== "ready") policyFail("PRE_DECISION_NOT_READY", `typed-fact gate is ${preDecision.eligibility?.status || "invalid"}`);
+  // `insufficient_grounding` runs. Every tool, veto and rule declares its own `on_missing` and
+  // `on_uncomputable` behaviour, and those declarations are how a method states what an absent
+  // input means -- several seats are authored with a veto that answers exactly that case.
+  // Refusing to execute reported this gate instead of the method's own answer. Nothing is
+  // invented: a fact that is absent stays absent, and every reader of it takes its declared
+  // path. `out_of_scope` -- no required fact present at all -- is still a hard stop.
+  if (!["ready", "insufficient_grounding"].includes(preDecision.eligibility?.status)) {
+    policyFail("PRE_DECISION_NOT_READY", `typed-fact gate is ${preDecision.eligibility?.status || "invalid"}`);
+  }
   const contract = preDecision.anonymous_method_contract;
   const policy = contract?.decision_policy;
   const tools = contract?.tools;

package/mcp/lib/personas-v3/grounding-adapter.mjs

@@ -805,6 +805,10 @@ export function adaptGroundingToTypedFacts(grounding, { asOf, knowledgeAsOf = as
   macroSeriesFacts(grounding, context);
   fundamentalFacts(grounding, context);
   instrumentAggregateFacts(grounding, context);
+  // The same converter, over the market-level block a company run now carries. Reusing it
+  // rather than writing a second one keeps one set of lineage and unit rules for facts that
+  // are the same facts, whoever the subject is.
+  instrumentAggregateFacts({ instrument_aggregate: grounding?.market_valuation, gathered_at: grounding?.gathered_at }, context);
   insiderOwnershipFacts(grounding, context);
   crossMarketFacts(grounding, context);
   basketNewsFacts(grounding, context);

package/mcp/lib/personas-v3/runtime.mjs

@@ -528,10 +528,17 @@ export function assertFrozenDecisionIntegrity(frozenDecision) {
   return true;
 }
 
-/** Dispatch only an eligible anonymous decision. Missing required facts never call the layer. */
+/**
+ * Dispatch a decision the seat can still reach.
+ *
+ * `out_of_scope` -- none of the required facts present -- never calls the layer, because there
+ * is no method left to run. `insufficient_grounding` does: the policy's own vetoes and
+ * `on_missing` rules are how a method states what an absent input means, and refusing to
+ * execute them reported the runtime's own gate instead of the method's answer.
+ */
 export async function runAnonymousDecisionLayer(preDecision, decisionLayer) {
   verifyAnonymousPreDecision(preDecision);
-  if (preDecision.eligibility.status !== "ready") {
+  if (preDecision.eligibility.status === "out_of_scope") {
     return deepFreeze({
       decision_layer_called: false,
       frozen_decision: freezeAnonymousDecision(preDecision),

package/mcp/lib/screen.mjs

@@ -69,10 +69,36 @@ function ruleProvenance(series) {
  * Each returns { id, passed, value, threshold, reason } or { skipped } when the inputs
  * are not available -- a missing input is never silently treated as a pass.
  */
+/**
+ * Gross profit, direct where the filer tagged it and revenue less cost of revenue where not.
+ *
+ * The subtraction is the filer's own arithmetic on the filer's own figures, matched by period
+ * end so a year is never differenced against a different year. Years the filer did tag keep the
+ * tagged value: a direct number always beats a reconstructed one.
+ */
+export function derivedGrossProfit(direct, revenue, cost) {
+  if (direct?.length) return direct;
+  if (!revenue?.length || !cost?.length) return direct || [];
+  const costByEnd = new Map(cost.map((row) => [row.end, row]));
+  const derived = [];
+  for (const row of revenue) {
+    const paired = costByEnd.get(row.end);
+    if (!paired || !Number.isFinite(paired.val)) continue;
+    derived.push({
+      ...row,
+      val: row.val - paired.val,
+      tag: `${row.tag} - ${paired.tag}`,
+      derived_from: [row.tag, paired.tag],
+    });
+  }
+  return derived;
+}
+
 export function evaluateRules(facts, { asOf = null } = {}) {
   const revenue = values(facts, "revenue", asOf);
   const netIncome = values(facts, "netIncome", asOf);
-  const grossProfit = values(facts, "grossProfit", asOf);
+  // Derived where the filer did not tag it directly, from two figures it did publish.
+  const grossProfit = derivedGrossProfit(values(facts, "grossProfit", asOf), values(facts, "revenue", asOf), values(facts, "costOfRevenue", asOf));
   const operatingIncome = values(facts, "operatingIncome", asOf);
   const ocf = values(facts, "operatingCashFlow", asOf);
   const capex = values(facts, "capex", asOf);

package/mcp/lib/sec.mjs

@@ -31,21 +31,54 @@ async function throttle() {
   lastCall = Date.now();
 }
 
-async function secJson(url, timeoutMs = LIMITS.QUOTE_FETCH_MS * 2, upstreamSignal) {
-  await throttle();
-  const abort = linkedAbort(timeoutMs, upstreamSignal);
-  try {
-    const res = await fetch(url, {
-      signal: abort.signal,
-      headers: { "User-Agent": UA, Accept: "application/json" },
-    });
-    if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
-    const text = await res.text();
-    if (text.trimStart().startsWith("<")) throw new Error(`SEC returned HTML rather than JSON for ${url} (rate limited or blocked)`);
-    return JSON.parse(text);
-  } finally {
-    abort.cleanup();
+/**
+ * SEC answers 429 when a client outruns its guidance, and the throttle above only paces a
+ * single process -- a second one, or a burst of look-through fetches, still crosses the line.
+ * Without a backoff the whole evidence chain for a run collapses on one rate-limited response,
+ * which is indistinguishable in the report from the data not existing.
+ *
+ * Deliberately short and bounded: three attempts over about a second and a half. A caller that
+ * is genuinely over budget should fail fast and be told, not stall a research run.
+ */
+const RATE_LIMIT_ATTEMPTS = 3;
+const RATE_LIMIT_BACKOFF_MS = 400;
+
+function isRateLimited(status) {
+  return status === 429 || status === 503;
+}
+
+async function withRateLimitRetry(attempt) {
+  let lastError = null;
+  for (let tries = 0; tries < RATE_LIMIT_ATTEMPTS; tries += 1) {
+    if (tries > 0) await new Promise((resolve) => setTimeout(resolve, RATE_LIMIT_BACKOFF_MS * (2 ** (tries - 1))));
+    const outcome = await attempt();
+    if (!outcome.rateLimited) return outcome;
+    lastError = outcome.error;
   }
+  throw lastError;
+}
+
+async function secJson(url, timeoutMs = LIMITS.QUOTE_FETCH_MS * 2, upstreamSignal) {
+  const outcome = await withRateLimitRetry(async () => {
+    await throttle();
+    const abort = linkedAbort(timeoutMs, upstreamSignal);
+    try {
+      const res = await fetch(url, {
+        signal: abort.signal,
+        headers: { "User-Agent": UA, Accept: "application/json" },
+      });
+      if (isRateLimited(res.status)) {
+        return { rateLimited: true, error: new Error(`HTTP ${res.status} for ${url}`) };
+      }
+      if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+      const text = await res.text();
+      if (text.trimStart().startsWith("<")) throw new Error(`SEC returned HTML rather than JSON for ${url} (rate limited or blocked)`);
+      return { rateLimited: false, value: JSON.parse(text) };
+    } finally {
+      abort.cleanup();
+    }
+  });
+  return outcome.value;
 }
 
 /** Raw filing index for one registrant. Callers that need form types read this, not `fetchSubmissions`. */
@@ -188,12 +221,42 @@ export const CONCEPTS = {
   ],
   netIncome: ["NetIncomeLoss", "ProfitLoss"],
   grossProfit: ["GrossProfit"],
-  operatingIncome: ["OperatingIncomeLoss"],
+  // Most filers never tag GrossProfit -- ten of fifteen large caps tested do not -- and report
+  // revenue and cost of revenue separately instead. The margin is derived from those when the
+  // direct tag is absent, which is arithmetic the filer already published rather than an
+  // estimate. Without this, a gross-margin rule was unavailable for two thirds of the market
+  // and every seat that reads it fell silent.
+  costOfRevenue: [
+    "CostOfGoodsAndServicesSold",
+    "CostOfRevenue",
+    "CostOfGoodsSold",
+    "CostOfServices",
+    "CostOfGoodsAndServicesSoldExcludingDepreciationDepletionAndAmortization",
+  ],
+  operatingIncome: ["OperatingIncomeLoss", "OperatingIncomeLossIncludingEquityMethodInvestments"],
   operatingCashFlow: ["NetCashProvidedByUsedInOperatingActivities", "NetCashProvidedByUsedInOperatingActivitiesContinuingOperations"],
-  capex: ["PaymentsToAcquirePropertyPlantAndEquipment", "PaymentsToAcquireProductiveAssets"],
+  // Capital expenditure has no single tag in practice. Corning files PaymentsForCapitalImprovements
+  // and nothing this list previously contained, which alone removed owner earnings -- and with
+  // it Buffett and Ackman -- for every issuer that tags it that way.
+  capex: [
+    "PaymentsToAcquirePropertyPlantAndEquipment",
+    "PaymentsToAcquireProductiveAssets",
+    "PaymentsForCapitalImprovements",
+    "PaymentsForProceedsFromProductiveAssets",
+    "PaymentsToAcquireOtherPropertyPlantAndEquipment",
+    "PaymentsToAcquireMachineryAndEquipment",
+  ],
   equity: ["StockholdersEquity", "StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"],
   assets: ["Assets"],
-  interestExpense: ["InterestExpense", "InterestIncomeExpenseNet", "InterestExpenseDebt"],
+  interestExpense: [
+    "InterestExpense",
+    "InterestIncomeExpenseNet",
+    "InterestExpenseDebt",
+    "InterestExpenseNonoperating",
+    "InterestAndDebtExpense",
+    "InterestIncomeExpenseNonoperatingNet",
+    "InterestExpenseBorrowings",
+  ],
   sharesOutstanding: ["CommonStockSharesOutstanding", "WeightedAverageNumberOfDilutedSharesOutstanding"],
 };
 

package/mcp/lib/voice-from-decision.mjs

@@ -0,0 +1,211 @@
+/**
+ * The five-field voice, composed from the frozen decision rather than written about it.
+ *
+ * A seat that computed a real verdict from real facts was reporting it in one sentence, and a
+ * reader could not see what it had looked at. The five fields existed and nothing filled them.
+ *
+ * The deterministic record already holds everything they need: which facts were read and what
+ * they were, which tools ran and what they produced, which scoring rules hit and missed, which
+ * vetoes fired, the band the score landed in, and the conditions that would move it. Composing
+ * the fields FROM that record has a property that asking a model to restate a sentence does
+ * not: the explanation cannot drift from the verdict, because it is derived from it. If the
+ * text says a rule missed, the rule missed.
+ *
+ * Nothing here is a claim about a named person. It is a rendering of arithmetic the seat's own
+ * policy performed, in the report's language.
+ */
+
+import { localized } from "./lang.mjs";
+import { defaultIntentForStance } from "./voice.mjs";
+
+const MAX_ITEMS = 4;
+
+function finite(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** Numbers a reader can scan: decimals stay short, big money keeps its magnitude. */
+export function readableValue(fact) {
+  const value = fact?.value;
+  if (!finite(value)) return String(value ?? "—");
+  if (fact.unit === "decimal" && Math.abs(value) < 10) return `${(value * 100).toFixed(1)}%`;
+  if (Math.abs(value) >= 1e9) return `${(value / 1e9).toFixed(2)}B`;
+  if (Math.abs(value) >= 1e6) return `${(value / 1e6).toFixed(1)}M`;
+  return Number(value.toFixed(4)).toString();
+}
+
+/** Every fact id a condition reads, in the order it reads them. */
+export function factsInCondition(node, into = []) {
+  if (!node || typeof node !== "object") return into;
+  if (typeof node.fact_id === "string") into.push(node.fact_id);
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) value.forEach((entry) => factsInCondition(entry, into));
+    else if (value && typeof value === "object") factsInCondition(value, into);
+  }
+  return into;
+}
+
+function copyFor(language) {
+  return localized(language, {
+    en: {
+      readFacts: (list) => `Facts this method read: ${list}.`,
+      noFacts: "The point-in-time record supplied none of the facts this method reads.",
+      computed: (list) => `It computed ${list}.`,
+      hits: (n, total, list) => `${n} of ${total} scoring conditions held: ${list}.`,
+      misses: (list) => `Conditions that did not hold: ${list}.`,
+      noRules: "No scoring condition could be evaluated on what was available.",
+      veto: (list) => `A hard veto decided this before scoring: ${list}.`,
+      band: (stance, ratio) => `The score of ${ratio} places it in the ${stance} band.`,
+      intent: (label) => `On this evidence the method's position is: ${label}.`,
+      changes: (list) => `This changes if: ${list}.`,
+      noChanges: "No stated condition would move this within the method's own rules.",
+      disagree: "This is a single method run on frozen facts. It is not a forecast, and where it differs from the analyst sections the difference is the method's scope, not a correction of them.",
+      declineWhat: (list) => `This method requires ${list}, and the point-in-time record did not carry ${list === "" ? "them" : "all of it"}.`,
+      declineWhy: "It abstains rather than substituting a proxy, because a number the method did not compute is not the method's answer.",
+    },
+    zh: {
+      readFacts: (list) => `本方法读取的事实：${list}。`,
+      noFacts: "时点一致的记录没有提供本方法需要的任何事实。",
+      computed: (list) => `据此计算得到：${list}。`,
+      hits: (n, total, list) => `${total} 条评分条件中有 ${n} 条成立：${list}。`,
+      misses: (list) => `未成立的条件：${list}。`,
+      noRules: "在可得资料上没有任何评分条件能够求值。",
+      veto: (list) => `在评分之前已由硬否决决定：${list}。`,
+      band: (stance, ratio) => `得分 ${ratio}，落在「${stance}」档。`,
+      intent: (label) => `基于这些证据，本方法的立场是：${label}。`,
+      changes: (list) => `以下情况会改变这一判断：${list}。`,
+      noChanges: "在本方法自身的规则内，没有任何已陈述的条件会改变它。",
+      disagree: "这是一次在冻结事实上运行的单一方法，不是预测。与分析师各席的差异来自方法的适用范围，不构成对他们的更正。",
+      declineWhat: (list) => `本方法需要 ${list}，而时点一致的记录没有全部提供。`,
+      declineWhy: "它选择弃权而不是用替代值补位，因为方法没有计算出来的数字不是方法的答案。",
+    },
+    ja: {
+      readFacts: (list) => `この手法が読んだ事実：${list}。`,
+      noFacts: "時点整合した記録に、この手法が読む事実はありませんでした。",
+      computed: (list) => `そこから算出：${list}。`,
+      hits: (n, total, list) => `${total} 件の採点条件のうち ${n} 件が成立：${list}。`,
+      misses: (list) => `成立しなかった条件：${list}。`,
+      noRules: "利用可能な資料では採点条件を評価できませんでした。",
+      veto: (list) => `採点の前にハード拒否で決着：${list}。`,
+      band: (stance, ratio) => `スコア ${ratio}、「${stance}」の帯に入ります。`,
+      intent: (label) => `この証拠に基づく手法の立場：${label}。`,
+      changes: (list) => `次の場合に判断は変わります：${list}。`,
+      noChanges: "手法自身の規則の範囲では、判断を動かす条件は示されていません。",
+      disagree: "凍結された事実に対する単一手法の実行であり、予測ではありません。アナリスト各席との差異は手法の適用範囲によるもので、訂正ではありません。",
+      declineWhat: (list) => `この手法は ${list} を必要としますが、時点整合した記録が揃いませんでした。`,
+      declineWhy: "代替値で埋めず棄権します。手法が計算していない数値は手法の答えではないからです。",
+    },
+    ko: {
+      readFacts: (list) => `이 방법이 읽은 사실: ${list}.`,
+      noFacts: "시점이 일치하는 기록에 이 방법이 읽는 사실이 없었습니다.",
+      computed: (list) => `이로부터 산출: ${list}.`,
+      hits: (n, total, list) => `채점 조건 ${total}개 중 ${n}개 성립: ${list}.`,
+      misses: (list) => `성립하지 않은 조건: ${list}.`,
+      noRules: "확보된 자료로는 어떤 채점 조건도 평가할 수 없었습니다.",
+      veto: (list) => `채점 전에 하드 비토로 결정됨: ${list}.`,
+      band: (stance, ratio) => `점수 ${ratio}, "${stance}" 구간에 해당합니다.`,
+      intent: (label) => `이 증거에서 이 방법의 입장: ${label}.`,
+      changes: (list) => `다음의 경우 판단이 바뀝니다: ${list}.`,
+      noChanges: "방법 자체의 규칙 안에서 판단을 움직일 조건은 제시되지 않았습니다.",
+      disagree: "동결된 사실에 대한 단일 방법 실행이며 예측이 아닙니다. 애널리스트 좌석과의 차이는 방법의 적용 범위 차이이지 정정이 아닙니다.",
+      declineWhat: (list) => `이 방법은 ${list}이 필요하지만 시점 일치 기록이 이를 모두 담고 있지 않았습니다.`,
+      declineWhy: "대체값으로 메우지 않고 기권합니다. 방법이 계산하지 않은 숫자는 방법의 답이 아니기 때문입니다.",
+    },
+  });
+}
+
+/**
+ * Compose the five fields for a seat that reached a stance.
+ *
+ * `result` is the frozen `structured_decision.result`; `policy` is the seat's decision policy,
+ * which supplies the human-readable condition ids the result refers to by index.
+ */
+export function voiceFromDecision({ result, policy, factPack, language = "English" } = {}) {
+  const copy = copyFor(language);
+  const facts = new Map((factPack?.facts || []).map((fact) => [fact.fact_id, fact]));
+  const stance = result?.common_projection?.stance || "out_of_scope";
+
+  const readIds = [...new Set([
+    ...(policy?.scoring?.rules || []).flatMap((rule) => factsInCondition(rule.condition)),
+    ...(policy?.hard_vetoes || []).flatMap((veto) => factsInCondition(veto.condition)),
+    ...(policy?.eligibility?.all || []).flatMap((check) => factsInCondition(check.condition)),
+  ])].filter((id) => facts.has(id));
+  const readList = readIds.slice(0, MAX_ITEMS)
+    .map((id) => `${id} = ${readableValue(facts.get(id))}`).join("; ");
+
+  const computed = (result?.computations?.trace || [])
+    .filter((step) => step.status === "computed" && finite(step.value))
+    .slice(0, MAX_ITEMS)
+    .map((step) => `${step.output_id} = ${Number(step.value.toFixed(4))}`)
+    .join("; ");
+
+  // The executor publishes the rules it evaluated already split into hits, misses and the ones
+  // it could not compute. Reading its own split rather than re-deriving one is what keeps this
+  // text unable to disagree with the verdict it describes.
+  const scoring = result?.score || {};
+  const hits = scoring.hits || [];
+  const misses = scoring.misses || [];
+  const uncomputable = scoring.uncomputable || [];
+  const evaluated = [...hits, ...misses, ...uncomputable];
+  // The runtime anonymises rule ids so the decision layer cannot recognise the seat. A reader
+  // is not the decision layer: map each anonymous id back to the readable name in the seat's
+  // own policy, which lists its rules in the same order the executor evaluated them.
+  const readableRuleIds = new Map((policy?.scoring?.rules || [])
+    .map((rule, index) => [index, rule.rule_id])
+    .filter(([, id]) => typeof id === "string"));
+  const anonOrder = new Map(evaluated
+    .map((rule) => rule.rule_id)
+    .filter(Boolean)
+    .map((id, index) => [id, index]));
+  const ruleName = (rule) => {
+    const anon = rule.rule_id || rule.id;
+    const readable = readableRuleIds.get(anonOrder.get(anon));
+    return readable || anon || "rule";
+  };
+
+  const vetoes = (result?.vetoes_triggered || []).map((veto) => veto.veto_id).filter(Boolean);
+
+  const whatISee = [
+    readList ? copy.readFacts(readList) : copy.noFacts,
+    computed ? copy.computed(computed) : "",
+  ].filter(Boolean).join(" ");
+
+  const howItReads = [
+    vetoes.length ? copy.veto(vetoes.join("; ")) : "",
+    evaluated.length
+      ? copy.hits(hits.length, evaluated.length, hits.map(ruleName).join("; ") || "—")
+      : copy.noRules,
+    misses.length ? copy.misses(misses.map(ruleName).join("; ")) : "",
+    finite(result?.common_projection?.score_ratio)
+      ? copy.band(stance, Number(result.common_projection.score_ratio.toFixed(3)))
+      : "",
+  ].filter(Boolean).join(" ");
+
+  const changes = [
+    ...misses.map(ruleName),
+    ...uncomputable.map(ruleName),
+    ...vetoes,
+  ].slice(0, MAX_ITEMS);
+
+  return {
+    what_i_see: whatISee,
+    how_my_method_reads_it: howItReads,
+    would_i_act: copy.intent(defaultIntentForStance(stance)),
+    what_changes_my_mind: changes.length ? copy.changes(changes.join("; ")) : copy.noChanges,
+    where_i_disagree: copy.disagree,
+  };
+}
+
+/** The same five fields for a seat that could not run, so an abstention is also readable. */
+export function voiceFromDecline({ eligibility, language = "English" } = {}) {
+  const copy = copyFor(language);
+  const missing = (eligibility?.missing_required_fact_types || []).slice(0, MAX_ITEMS).join("; ");
+  const present = (eligibility?.present_required_fact_types || []).slice(0, MAX_ITEMS).join("; ");
+  return {
+    what_i_see: present ? copy.readFacts(present) : copy.noFacts,
+    how_my_method_reads_it: copy.declineWhat(missing),
+    would_i_act: copy.intent(defaultIntentForStance("out_of_scope")),
+    what_changes_my_mind: missing ? copy.changes(missing) : copy.noChanges,
+    where_i_disagree: copy.declineWhy,
+  };
+}

package/mcp/lib/xbrl-series.mjs

@@ -29,9 +29,14 @@ export const MAX_ALIGNMENT_DRIFT_DAYS = 45;
 /**
  * Concept aliases, ordered by preference, on top of the ones sec.mjs already publishes.
  *
- * Aliases inside one entry are the same economic quantity under different taxonomies. They
- * are never a fallback to a different concept: total liabilities is not reconstructed from
- * an equity subtraction, and a missing depreciation tag stays missing.
+ * Aliases inside one entry are the same economic quantity under different taxonomies. They are
+ * never a fallback to a different concept: a missing depreciation tag stays missing.
+ *
+ * Total liabilities has one sanctioned reconstruction and it is guarded. Subtracting equity
+ * from the balance-sheet total is wrong when the two tags disagree about non-controlling
+ * interests -- the difference then lands inside "liabilities", silently. Done against the
+ * INCLUDING-NCI equity tag the identity is exact, so that tag, and only that tag, may stand in
+ * where a filer never tags `Liabilities` directly. See `totalLiabilitiesFor`.
  */
 export const FUNDAMENTAL_CONCEPTS = Object.freeze({
   revenue: { tags: CONCEPTS.revenue, unit: "USD" },
@@ -50,6 +55,8 @@ export const FUNDAMENTAL_CONCEPTS = Object.freeze({
   },
   current_assets: { tags: ["AssetsCurrent"], unit: "USD" },
   total_liabilities: { tags: ["Liabilities"], unit: "USD" },
+  liabilities_and_equity: { tags: ["LiabilitiesAndStockholdersEquity"], unit: "USD" },
+  equity_including_nci: { tags: ["StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest"], unit: "USD" },
   goodwill: { tags: ["Goodwill"], unit: "USD" },
   intangibles: { tags: ["IntangibleAssetsNetExcludingGoodwill", "FiniteLivedIntangibleAssetsNet"], unit: "USD" },
   cash: {