alphacouncil-agent 0.5.5 → 0.8.0

package/mcp/lib/orchestrator.mjs

@@ -13,6 +13,7 @@ import { debateFromCodex, dryDebate, dryPacket, extractJson, managerFallback, me
 import { mapLimit, runCodex } from "./codex.mjs";
 import { debatePrompt, masterPrompt, selectedMasters, taskPrompt } from "./prompts.mjs";
 import { resolveSeatWeights } from "./weights.mjs";
+import { declinedOpinion, planMasters, reconcileOpinion } from "./personas-v2/bridge.mjs";
 
 export function visibleRun(args) {
   const symbol = safeSymbol(args.symbol);
@@ -80,21 +81,83 @@ export function visibleAgentSpecs(run, userPrompt = "") {
     ].filter(Boolean).join("\n"),
     output_contract: isChineseLanguage(run.language) ? "只返回一个 JSON debate packet。" : `Return one JSON debate packet with reader-facing fields in ${run.language}.`,
   }));
-  const master_agents = selectedMasters(run).map((id) => ({
+  // The deterministic pass runs first and settles, for free, every seat whose method cannot
+  // reach this security. Spawning an agent for a lens that has already declined is how the
+  // previous design produced ten confident essays over a screen that computed nothing.
+  const plan = planMasters(run, selectedMasters(run));
+  const zh = isChineseLanguage(run.language);
+  const master_agents = plan.to_run.map(({ id, decision }) => ({
     role: id,
+    engine: decision ? "v2_method_model" : "v1_prompt",
     title: `AlphaCouncil Agent ${run.symbol} ${id}`,
     prompt_template: [
       masterPrompt(id, run),
       "",
-      isChineseLanguage(run.language)
+      decision ? deterministicVerdictBlock(decision, zh) : "",
+      "",
+      zh
         ? "主线程必须先粘贴已完成的 Evidence JSON，再运行这个大师议席；大师在证据之后、辩论之前运行。"
         : "The main thread must paste the completed Evidence JSON first. Masters run after the evidence stage and before the debate.",
     ].filter(Boolean).join("\n"),
-    output_contract: isChineseLanguage(run.language)
+    output_contract: zh
       ? "只返回一个 JSON master opinion。"
       : `Return one JSON master opinion with reader-facing fields in ${run.language}.`,
   }));
-  return { evidence_agents, master_agents, debate_agents };
+  // A declined seat is settled here rather than skipped: it is written straight into the
+  // run as an out_of_scope opinion, so the completeness gate is satisfied and no agent is
+  // ever spawned for a method that cannot look.
+  if (plan.declined.length) {
+    const byId = new Map((run.master_opinions || []).map((o) => [o.master, o]));
+    for (const { id, decision } of plan.declined) {
+      if (!byId.has(id)) byId.set(id, declinedOpinion(run, id, decision));
+    }
+    run.master_opinions = selectedMasters(run).map((id) => byId.get(id)).filter(Boolean);
+  }
+  return {
+    evidence_agents,
+    master_agents,
+    debate_agents,
+    // Recorded, not hidden: a reader must be able to tell a method that judged from a method
+    // that could not look, and neither from a seat that was never offered.
+    master_decisions: plan.decisions,
+    masters_declined: plan.declined.map(({ id, decision }) => ({
+      master: id,
+      stance: decision.stance,
+      reason: decision.reason,
+      unmet: decision.eligibility?.unmet || [],
+    })),
+  };
+}
+
+/**
+ * The stance is already decided. The prompt says so, in the run's language, so the model
+ * writes an explanation rather than a verdict.
+ */
+function deterministicVerdictBlock(decision, zh) {
+  const hits = (decision.score?.hits || []).map((h) => `${h.id}=${h.actual} (>=${h.threshold}, +${h.points})`).join("; ") || "none";
+  const misses = (decision.score?.misses || []).map((m) => `${m.id}=${m.actual}`).join("; ") || "none";
+  const uncomputable = (decision.score?.uncomputable || []).map((u) => u.id).join("; ") || "none";
+  return zh
+    ? [
+      "## 已确定的判决（由确定性政策产生，你不能推翻）",
+      `- 立场：${decision.stance}（依据：${decision.reason}）`,
+      `- 得分：${decision.score?.score ?? "—"}/${decision.score?.max_possible ?? "—"}，覆盖率 ${Math.round((decision.score?.coverage || 0) * 100)}%`,
+      `- 命中：${hits}`,
+      `- 未命中：${misses}`,
+      `- 无法计算（既不算命中也不算未命中）：${uncomputable}`,
+      "",
+      "你的任务是解释这个判决为什么成立、它最可能错在哪里、以及什么证据会推翻它。**不要给出与上面不同的 stance**；如果你认为它错了，把理由写进 disagreements。",
+    ].join("\n")
+    : [
+      "## Settled verdict (produced by the deterministic policy; you cannot overturn it)",
+      `- Stance: ${decision.stance} (basis: ${decision.reason})`,
+      `- Score: ${decision.score?.score ?? "—"}/${decision.score?.max_possible ?? "—"}, coverage ${Math.round((decision.score?.coverage || 0) * 100)}%`,
+      `- Hits: ${hits}`,
+      `- Misses: ${misses}`,
+      `- Uncomputable (neither a hit nor a miss): ${uncomputable}`,
+      "",
+      "Explain why this verdict holds, where it is most likely wrong, and what evidence would overturn it. **Do not return a different stance**; if you think it is wrong, put the reason in disagreements.",
+    ].join("\n");
 }
 
 export function recordMasterOpinion(args) {
@@ -107,20 +170,23 @@ export function recordMasterOpinion(args) {
     throw invalidParams(`master ${args.master} was not selected for this run. Selected: ${allowed.join(", ") || "none"}`);
   }
   const dir = runPath(run.run_id);
-  const opinion = normalizeMasterOpinion(
+  const normalized = normalizeMasterOpinion(
     { ...(args.packet || {}), thread_id: args.thread_id },
     args.master,
     run,
     rawRecordText(args.packet),
   );
+  // A narrated stance that disagrees with the arithmetic does not get to win quietly. The
+  // deterministic verdict stands and the disagreement is preserved on the record.
+  const { opinion, overridden } = reconcileOpinion(run, args.master, normalized);
   const byId = new Map((run.master_opinions || []).map((item) => [item.master, item]));
   byId.set(args.master, opinion);
   run.master_opinions = allowed.map((id) => byId.get(id)).filter(Boolean);
   writeJson(join(dir, `${args.master}.json`), opinion);
   saveRun(run);
   writeJson(join(dir, "evidence.json"), run);
-  appendEvent(run, "master_opinion_recorded", { master: args.master, stance: opinion.stance });
-  return { run, opinion, recorded: run.master_opinions.length, expected: allowed.length };
+  appendEvent(run, "master_opinion_recorded", { master: args.master, stance: opinion.stance, overridden });
+  return { run, opinion, overridden, recorded: run.master_opinions.length, expected: allowed.length };
 }
 
 export function visibleStatusAfterPacket(run) {

package/mcp/lib/packets.mjs

@@ -217,6 +217,47 @@ export function managerFallback(run, userPrompt = "") {
   }, "portfolio_manager", run);
 }
 
+/**
+ * Common ways a caller says a stance that is not one of the four we store.
+ *
+ * Mapping these is not politeness. An unmapped value used to fall through to "cautious",
+ * which is a real stance carrying real weight -- so a caller writing "avoid" got a seat
+ * that looked deliberate and voted. Ten such seats render as unanimity that no master
+ * produced.
+ */
+const STANCE_SYNONYMS = new Map([
+  ["long", "constructive"], ["bullish", "constructive"], ["buy", "constructive"],
+  ["positive", "constructive"], ["overweight", "constructive"],
+  ["neutral", "cautious"], ["hold", "cautious"], ["mixed", "cautious"], ["wait", "cautious"],
+  ["short", "opposed"], ["bearish", "opposed"], ["sell", "opposed"], ["avoid", "opposed"],
+  ["negative", "opposed"], ["underweight", "opposed"],
+  ["n/a", "out_of_scope"], ["na", "out_of_scope"], ["skip", "out_of_scope"],
+  ["abstain", "out_of_scope"], ["unknown", "out_of_scope"],
+]);
+
+/**
+ * Never silently invent a stance.
+ *
+ * Anything we cannot map becomes `out_of_scope`, which weights.mjs already treats as
+ * carrying zero weight. Guessing "cautious" for an unrecognised value manufactures a
+ * confident-looking seat out of a caller's typo; declining to score it does not.
+ */
+export function coerceStance(value, masterId = "") {
+  if (MASTER_STANCES.includes(value)) return value;
+  if (typeof value === "string") {
+    const mapped = STANCE_SYNONYMS.get(value.trim().toLowerCase());
+    if (mapped) return mapped;
+  }
+  if (value !== undefined && value !== null && value !== "") {
+    process.emitWarning(
+      `alphacouncil: unrecognised master stance ${JSON.stringify(value)}`
+      + `${masterId ? ` from ${masterId}` : ""}; recorded as out_of_scope (zero weight). `
+      + `Allowed: ${MASTER_STANCES.join(", ")}.`
+    );
+  }
+  return "out_of_scope";
+}
+
 /**
  * A master's opinion. Deliberately NOT a debate packet: a master issues no rating and
  * declares no winner. out_of_scope is a first-class stance -- "by my method this name is
@@ -229,7 +270,7 @@ export function normalizeMasterOpinion(packet, masterId, run, raw = "") {
     symbol: run.symbol,
     as_of: run.as_of,
     verdict: typeof packet?.verdict === "string" ? packet.verdict : "",
-    stance: MASTER_STANCES.includes(packet?.stance) ? packet.stance : "cautious",
+    stance: coerceStance(packet?.stance, masterId),
     summary: typeof packet?.summary === "string" ? packet.summary : raw.slice(0, LIMITS.CLEAN_LOG_BYTES),
     key_findings: list(packet?.key_findings),
     disagreements: list(packet?.disagreements),

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

@@ -0,0 +1,148 @@
+/**
+ * Experiments whose job is to prove the bench decorative.
+ *
+ * A feature that cannot fail its own test is a decoration. These are the cheapest and most
+ * decisive of the battery in docs/persona-v2-spec.md:
+ *
+ *   name swap   -- change only the label. A real method does not notice.
+ *   policy swap -- run Taleb's policy under Buffett's name. A real system follows the
+ *                  policy; a performance follows the name.
+ *
+ * They are deterministic because the layer under test is deterministic: no model is called,
+ * so a difference in outcome can only come from the module that was swapped.
+ */
+
+import { decide } from "./policy.mjs";
+
+/** Fields a decision may legitimately carry that are identity rather than judgment. */
+const IDENTITY_FIELDS = new Set(["persona_id"]);
+
+/** The judgment, with identity stripped, so two decisions can be compared as verdicts. */
+export function judgmentOf(decision) {
+  const copy = {};
+  for (const [key, value] of Object.entries(decision || {})) {
+    if (IDENTITY_FIELDS.has(key)) continue;
+    copy[key] = value;
+  }
+  return JSON.stringify(copy);
+}
+
+/**
+ * Rename a pack without touching a single rule.
+ *
+ * If the verdict moves, the differentiation was in the label. In the deterministic layer
+ * that is a structural guarantee rather than a hope, and that is the point of testing it
+ * here: it pins the guarantee before the narrative layer, which cannot offer one, is added.
+ */
+export function nameSwap(pack, newId = "master_impostor", newName = "Impostor Method Model") {
+  return { ...pack, persona_id: newId, display_name: { ...pack.display_name, en: newName } };
+}
+
+/** Keep the identity, take the other model's decision policy. */
+export function policySwap(pack, donor) {
+  return { ...pack, decision_policy: donor.decision_policy, _policy_from: donor.persona_id };
+}
+
+/** Keep the identity and policy, take the other model's evidence. */
+export function evidenceSwap(factsA, factsB) {
+  return [factsB, factsA];
+}
+
+/**
+ * @returns {{stable: boolean, before: string, after: string}} stable === the verdict did
+ * not move when only the name did. `false` means the system is acting.
+ */
+export function runNameSwap(pack, facts) {
+  const before = decide(pack, facts);
+  const after = decide(nameSwap(pack), facts);
+  return {
+    experiment: "name_swap",
+    stable: judgmentOf(before) === judgmentOf(after),
+    before: before.stance,
+    after: after.stance,
+    persona_id_before: before.persona_id,
+    persona_id_after: after.persona_id,
+  };
+}
+
+/**
+ * @returns {{follows_policy: boolean}} true when the verdict tracked the donor policy
+ * rather than the host name.
+ */
+export function runPolicySwap(host, donor, facts) {
+  const hostOwn = decide(host, facts);
+  const donorOwn = decide(donor, facts);
+  const hybrid = decide(policySwap(host, donor), facts);
+  return {
+    experiment: "policy_swap",
+    host: host.persona_id,
+    donor: donor.persona_id,
+    host_stance: hostOwn.stance,
+    donor_stance: donorOwn.stance,
+    hybrid_stance: hybrid.stance,
+    follows_policy: judgmentOf(hybrid) === judgmentOf(donorOwn),
+    follows_name: judgmentOf(hybrid) === judgmentOf(hostOwn) && judgmentOf(donorOwn) !== judgmentOf(hostOwn),
+  };
+}
+
+/**
+ * Do these models actually see different securities?
+ *
+ * Pairwise agreement across a case set. Compared against a model's agreement with itself,
+ * this is what separates a bench from a chorus: if two models agree as often as one model
+ * agrees with itself, the personas produced no differentiation and the report has to say so
+ * rather than presenting them as independent seats.
+ */
+export function pairwiseAgreement(packs, cases) {
+  const rows = [];
+  for (let i = 0; i < packs.length; i += 1) {
+    for (let j = i + 1; j < packs.length; j += 1) {
+      let same = 0;
+      for (const facts of cases) {
+        if (decide(packs[i], facts).stance === decide(packs[j], facts).stance) same += 1;
+      }
+      rows.push({ a: packs[i].persona_id, b: packs[j].persona_id, agreement: cases.length ? same / cases.length : 0 });
+    }
+  }
+  const mean = rows.length ? rows.reduce((sum, r) => sum + r.agreement, 0) / rows.length : 0;
+  return { pairs: rows, mean_agreement: mean };
+}
+
+/**
+ * Self-consistency of the deterministic layer is 1 by construction. It is computed rather
+ * than asserted so the same diagnostic keeps working once a narrative layer -- which has no
+ * such guarantee -- sits on top of it.
+ */
+export function selfConsistency(pack, cases, repeats = 3) {
+  let agree = 0;
+  let total = 0;
+  for (const facts of cases) {
+    const first = decide(pack, facts).stance;
+    for (let r = 1; r < repeats; r += 1) {
+      total += 1;
+      if (decide(pack, facts).stance === first) agree += 1;
+    }
+  }
+  return total ? agree / total : 1;
+}
+
+/**
+ * The verdict the report must print.
+ *
+ * `none` means the seats cannot be told apart and must not be presented as a bench. The
+ * threshold is a margin, not a hope: differentiation counts only when models disagree with
+ * each other appreciably more than a model disagrees with itself.
+ */
+export function differentiation(packs, cases, { margin = 0.15 } = {}) {
+  const pairwise = pairwiseAgreement(packs, cases);
+  const self = packs.length ? packs.reduce((sum, p) => sum + selfConsistency(p, cases), 0) / packs.length : 1;
+  const gap = self - pairwise.mean_agreement;
+  const verdict = gap >= margin * 2 ? "effective" : gap >= margin ? "weak" : "none";
+  return {
+    self_consistency: self,
+    mean_pairwise_agreement: pairwise.mean_agreement,
+    gap,
+    verdict,
+    pairs: pairwise.pairs,
+  };
+}

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

@@ -0,0 +1,187 @@
+/**
+ * Where Persona v2 meets a live run.
+ *
+ * The grounding block a run already assembles carries almost everything a deterministic
+ * gate needs; it is simply shaped for prompts rather than for predicates. This maps it onto
+ * the fact paths the packs address, and nothing here invents a value: a field the grounding
+ * does not carry stays absent, so the gate declines rather than guesses.
+ *
+ * A pack with no v2 manifest is not an error. Masters that have not been migrated keep
+ * running as v1 prompt personas, and the run records which of the two produced each seat so
+ * a reader is never left to assume.
+ */
+
+import { loadPacks } from "./loader.mjs";
+import { decide } from "./policy.mjs";
+import { sliceFor } from "./slice.mjs";
+
+let cached = null;
+export function packs() {
+  if (!cached) cached = loadPacks();
+  return cached;
+}
+export function resetPacks() { cached = null; }
+
+/**
+ * Grounding -> the fact shape packs address.
+ *
+ * `screen.rules_computed` is the load-bearing one: a 20-F filer yields zero computable
+ * rules, which is exactly the condition a financial-series method must decline on.
+ */
+export function factsFromRun(run) {
+  const g = run?.grounding || {};
+  const screen = g.screen || {};
+  const metrics = {};
+  for (const metric of screen.metrics || []) {
+    if (metric && typeof metric.rule === "string" && metric.value !== undefined) metrics[metric.rule] = metric.value;
+  }
+  const options = g.options || {};
+  return {
+    symbol: run?.symbol,
+    as_of: run?.as_of,
+    quote: g.quote || {},
+    filer: {
+      ...(g.filer || {}),
+      // The screen only computes anything when SEC structured financials cover the filer.
+      structured_financials: Number(screen.rules_computed || 0) > 0,
+    },
+    screen: {
+      rules_computed: Number(screen.rules_computed || 0),
+      rules_total: Number(screen.rules_total || 0),
+      metrics,
+    },
+    options: {
+      chain_available: Boolean(options.atm_iv || options.term_structure || options.expiries),
+      atm_iv: options.atm_iv,
+      // Mapped only where the snapshot genuinely carries them. Realized volatility, and so
+      // the implied-versus-realized gap and any friction-adjusted edge, need a history the
+      // chain does not have -- which is why IV percentile is uncomputable too. Those paths
+      // stay absent, the rules that read them score as uncomputable, and a volatility method
+      // handed a bare snapshot correctly finds too little of itself to run.
+      skew_25d_points: options.skew_25d_put_minus_call_points ?? options.skew_25d_points,
+      expiry_covers_next_event: options.expiry_covers_next_event,
+      realized_minus_implied_vol_points: options.realized_minus_implied_vol_points,
+      net_edge_vol_points: options.net_edge_vol_points,
+    },
+    macro: g.macro || {},
+  };
+}
+
+/**
+ * The deterministic pass over every selected master, before a single agent is spawned.
+ *
+ * Seats that cannot look are settled here for free. `to_run` is what still needs a model;
+ * `declined` is what does not, and both are recorded so the report can show the difference
+ * between a method that judged and a method that could not.
+ */
+export function planMasters(run, masterIds) {
+  const reg = packs();
+  const facts = factsFromRun(run);
+  const decisions = [];
+  const to_run = [];
+  const declined = [];
+  // No grounding is not the same as a screen that computed nothing. A run that was never
+  // grounded has not been measured, so the gate has no facts to judge on and must not read
+  // their absence as a failing result -- doing so would silence the whole bench on every
+  // run that skips grounding.
+  const grounded = Boolean(run?.grounding && typeof run.grounding === "object");
+  for (const id of masterIds || []) {
+    const pack = reg.get(id);
+    if (!pack || !grounded) { to_run.push({ id, engine: "v1_prompt" }); continue; }
+    const decision = decide(pack, facts);
+    decisions.push({ ...decision, persona_id: id, engine: "v2_method_model", kind: pack.kind });
+    if (decision.narratable) to_run.push({ id, engine: "v2_method_model", decision });
+    else declined.push({ id, engine: "v2_method_model", decision });
+  }
+  return { facts, decisions, to_run, declined };
+}
+
+/**
+ * A declined seat still has to report, because the completeness gate counts every selected
+ * master and a seat that is merely skipped would leave the run permanently incomplete.
+ *
+ * The deterministic pass already produced the verdict, so the opinion is written directly
+ * and no agent is spawned. That is the whole saving: the seat is accounted for, the reader
+ * sees why it could not look, and nothing was spent to find out.
+ */
+export function declinedOpinion(run, id, decision) {
+  const unmet = (decision.eligibility?.unmet || [])
+    .map((u) => `${u.requirement} [${u.reason}${u.actual !== undefined ? `: ${u.actual}` : ""}]`)
+    .join("; ");
+  const pack = packs().get(id);
+  const name = pack?.display_name?.en || id;
+  return {
+    master: id,
+    symbol: run.symbol,
+    as_of: run.as_of,
+    stance: "out_of_scope",
+    verdict: `${name} cannot evaluate ${run.symbol}: ${decision.reason}`,
+    summary: decision.reason === "eligibility"
+      ? `This method's entry requirements are not met for ${run.symbol}, so it returns no judgment. Unmet: ${unmet || "n/a"}. Declining is a conclusion, not an abstention, and it was reached deterministically without spending a model call.`
+      : `Too little of this method could be computed for ${run.symbol} to be judged rather than sampled (coverage ${Math.round((decision.score?.coverage || 0) * 100)}%), so it returns no judgment.`,
+    key_findings: [],
+    disagreements: [],
+    disqualifiers_triggered: (decision.eligibility?.unmet || []).map((u) => u.requirement),
+    what_would_change_my_mind: (decision.eligibility?.unmet || []).map((u) => `${u.requirement} becomes available and is met`),
+    source_ids: [],
+    confidence: "high",
+    engine: "v2_method_model",
+    deterministic_stance: "out_of_scope",
+    decision_reason: decision.reason,
+  };
+}
+
+/**
+ * What one v2 seat is allowed to read, and the deterministic verdict it must narrate.
+ *
+ * Handed to the agent so the prompt describes a decision it cannot overturn: the model
+ * explains, it does not choose.
+ */
+export function briefFor(run, masterId, evidencePackets) {
+  const pack = packs().get(masterId);
+  if (!pack) return null;
+  const facts = factsFromRun(run);
+  const decision = decide(pack, facts);
+  const slice = sliceFor(pack, { frozen: facts, packets: evidencePackets || run?.packets || [] });
+  return {
+    persona_id: masterId,
+    engine: "v2_method_model",
+    kind: pack.kind,
+    display_name: pack.display_name,
+    decision,
+    visible_tasks: slice.packets.map((p) => p.task),
+    excluded_tasks: slice.excluded,
+    admission_shortfall: pack.admission_shortfall,
+  };
+}
+
+/**
+ * A recorded opinion must not contradict the arithmetic that produced it.
+ *
+ * The model narrates; if its stance disagrees with the deterministic verdict, the
+ * deterministic one stands and the disagreement is recorded rather than resolved silently.
+ * This is the same rule that failed once already: a stance that survives normalization
+ * without being checked is how ten seats came to read `cautious`.
+ */
+export function reconcileOpinion(run, masterId, opinion) {
+  const pack = packs().get(masterId);
+  // Same rule as the planner: an ungrounded run has no arithmetic to reconcile against, so
+  // the narrated stance is all there is and overriding it would be inventing a verdict.
+  if (!pack || !run?.grounding) return { opinion, engine: "v1_prompt", overridden: false };
+  const decision = decide(pack, factsFromRun(run));
+  if (opinion?.stance === decision.stance) {
+    return { opinion: { ...opinion, engine: "v2_method_model", deterministic_stance: decision.stance }, engine: "v2_method_model", overridden: false };
+  }
+  return {
+    engine: "v2_method_model",
+    overridden: true,
+    opinion: {
+      ...opinion,
+      stance: decision.stance,
+      engine: "v2_method_model",
+      deterministic_stance: decision.stance,
+      narrated_stance: opinion?.stance,
+      override_reason: `the deterministic ${pack.persona_id} policy returned ${decision.stance} (${decision.reason}); the narrated stance did not agree and does not govern`,
+    },
+  };
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Loads Persona v2 packs and enforces the admission bar in code.
+ *
+ * The bar is not a badge an author awards themselves. A pack that declares
+ * `kind: "method_model"` on a thin corpus is downgraded to `operator_lens` here, and the
+ * shortfall is carried on the pack so the report can say which one the reader is looking
+ * at. Letting a manifest self-certify would reproduce, one layer up, the exact failure this
+ * release exists to remove: a shape that looks like a judgment, holding none.
+ */
+
+import { readFileSync, readdirSync, existsSync, statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+/** Minimum corpus for a pack to carry a person's name. See docs/persona-v2-spec.md. */
+export const ADMISSION_BAR = Object.freeze({
+  propositions: 25,
+  primary_sources: 5,
+  decision_cases: 5,
+  failure_cases: 3,
+  vetoes: 10,
+  counterfactuals: 10,
+});
+
+export function defaultKnowledgeDir() {
+  return process.env.ALPHACOUNCIL_KNOWLEDGE_DIR
+    || fileURLToPath(new URL("../../../knowledge/masters/", import.meta.url));
+}
+
+/** Counted from the corpus, never from the manifest's own claim about itself. */
+export function countAdmission(pack) {
+  const sources = pack.sources || [];
+  return {
+    propositions: (pack.doctrine || []).length,
+    primary_sources: sources.filter((s) => s.grade === "A" || s.grade === "B").length,
+    decision_cases: (pack.decision_cases || []).length,
+    failure_cases: (pack.failure_cases || []).length
+      || (pack.doctrine || []).filter((d) => (d.counterexamples || []).length).length,
+    vetoes: (pack.decision_policy?.vetoes || []).length,
+    counterfactuals: (pack.counterfactuals || []).length,
+  };
+}
+
+export function admissionShortfall(counts) {
+  const short = {};
+  for (const [key, required] of Object.entries(ADMISSION_BAR)) {
+    const have = counts[key] || 0;
+    if (have < required) short[key] = { have, required };
+  }
+  return short;
+}
+
+/**
+ * A rule may only be defined by a grade A or B source. C supports, D stages, E is rejected.
+ * A doctrine entry citing nothing loadable is dropped rather than quietly kept.
+ */
+export function validatePack(pack, file = "") {
+  const errors = [];
+  const fail = (m) => errors.push(`${file}: ${m}`);
+  if (pack?.schema_version !== 2) fail(`schema_version must be 2, got ${JSON.stringify(pack?.schema_version)}`);
+  if (!/^[a-z0-9_]{2,48}$/.test(pack?.persona_id || "")) fail(`persona_id invalid: ${JSON.stringify(pack?.persona_id)}`);
+  if (!pack?.display_name?.en) fail("display_name.en is required");
+  if (pack?.display_name?.en && !/model|lens/i.test(pack.display_name.en)) {
+    // Naming discipline is a correctness property, not decoration: the product claim is a
+    // method, and a display name that reads as a person overstates it on every surface.
+    fail(`display_name.en must read as a method ("Buffett Method Model"), got ${JSON.stringify(pack.display_name.en)}`);
+  }
+  if (!pack?.decision_policy?.eligibility?.requires?.length) fail("decision_policy.eligibility.requires must be non-empty");
+  if (!pack?.decision_policy?.stance_bands?.length) fail("decision_policy.stance_bands must be non-empty");
+
+  const byId = new Map((pack?.sources || []).map((s) => [s.id, s]));
+  for (const rule of pack?.doctrine || []) {
+    if (!rule.source_ids?.length) { fail(`doctrine ${rule.rule_id}: no source_ids`); continue; }
+    const defining = rule.source_ids.filter((id) => ["A", "B"].includes(byId.get(id)?.grade));
+    if (!defining.length) fail(`doctrine ${rule.rule_id}: cites no grade A/B source, so it cannot define a rule`);
+    for (const id of rule.source_ids) if (!byId.has(id)) fail(`doctrine ${rule.rule_id}: unknown source ${id}`);
+  }
+  for (const rule of pack?.decision_policy?.scoring?.rules || []) {
+    if (!rule.provenance || rule.provenance.length < 8) {
+      fail(`scoring rule ${rule.id}: threshold has no provenance; determinism moves the uncertainty into the constant`);
+    }
+  }
+  const leak = pack?.memory_policy?.leak_rule;
+  if (leak && leak !== "public_at <= as_of AND memory_created_at <= as_of") {
+    fail("memory_policy.leak_rule must carry both clauses or a model reads the future through its own diary");
+  }
+  return errors;
+}
+
+/** Validates, counts, and downgrades kind when the corpus does not support the name. */
+export function loadPack(file) {
+  const pack = JSON.parse(readFileSync(file, "utf8"));
+  const errors = validatePack(pack, file);
+  if (errors.length) throw new Error(errors.join("\n"));
+  const counts = countAdmission(pack);
+  const shortfall = admissionShortfall(counts);
+  const qualifies = Object.keys(shortfall).length === 0;
+  return {
+    ...pack,
+    admission_counted: counts,
+    admission_shortfall: shortfall,
+    // The manifest's own `kind` is advisory. This one is enforced.
+    kind: qualifies ? "method_model" : "operator_lens",
+    kind_declared: pack.kind,
+  };
+}
+
+export function loadPacks({ dir = defaultKnowledgeDir() } = {}) {
+  if (!existsSync(dir)) return { packs: [], get: () => undefined };
+  const packs = [];
+  for (const entry of readdirSync(dir)) {
+    const manifest = join(dir, entry, "manifest.json");
+    if (statSync(join(dir, entry)).isDirectory() && existsSync(manifest)) packs.push(loadPack(manifest));
+  }
+  packs.sort((a, b) => a.persona_id.localeCompare(b.persona_id));
+  const index = new Map(packs.map((p) => [p.persona_id, p]));
+  return { packs, get: (id) => index.get(id) };
+}