@tangle-network/agent-knowledge 1.10.0 → 1.11.0

package/dist/index.js

@@ -30,28 +30,30 @@ import {
   normalizeLinkTarget,
   parseFrontmatter,
   parseKnowledgeWriteBlocks,
-  reciprocalRankFusion,
-  searchKnowledge,
   sourceRegistryPath,
   stringMetadata,
   textSourceAdapter,
-  tokenizeQuery,
   validateKnowledgeIndex,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-WWY5FTKQ.js";
+} from "./chunk-W6VWYTNH.js";
 import {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
   AgentMemoryScopeSchema,
   AgentMemoryWriteInputSchema,
+  applyRetrievalHoldout,
+  applySessionStickyRetrievalHoldout,
   createNeo4jAgentMemoryAdapter,
   defaultGetMemoryContext,
-  memoryHitToSourceRecord,
-  memoryWriteResultToSourceRecord,
-  renderMemoryContext
-} from "./chunk-U6KQ4FS3.js";
+  deterministicRng,
+  emitRetrievalHoldoutBypass,
+  renderMemoryContext,
+  resetRetrievalHoldoutRegistry,
+  retrievalHoldoutConfigHash,
+  toOffPolicyTrajectory
+} from "./chunk-VN2OGUUP.js";
 import {
   IRS_DIMENSION_HINTS,
   MAX_RESPONSE_BYTES,
@@ -68,19 +70,74 @@ import {
   looksLikeBlockPage,
   politeFetch
 } from "./chunk-WCYW2GDA.js";
+import {
+  INDUSTRY_MEMORY_BENCHMARKS,
+  INDUSTRY_RAG_BENCHMARKS,
+  buildFirstPartyMemoryLifecycleBenchmarkCases,
+  buildIndustryMemoryBenchmarkSmokeCases,
+  buildIndustryRagBenchmarkSmokeCases,
+  buildKnowledgeBenchmarkScenarios,
+  buildRetrievalBenchmarkCasesFromQrels,
+  buildRetrievalEvalDispatch,
+  buildRetrievalParameterCandidates,
+  createInMemoryBenchmarkAdapter,
+  createMemoryAdapterBenchmarkResponder,
+  createNoopMemoryBenchmarkAdapter,
+  isKnowledgeMemoryBenchmarkCase,
+  knowledgeBenchmarkJudge,
+  parseKnowledgeBenchmarkJsonl,
+  parseKnowledgeBenchmarkQrels,
+  renderKnowledgeBenchmarkReportMarkdown,
+  respondToIndustryMemoryBenchmarkSmokeCase,
+  respondToIndustryRagBenchmarkSmokeCase,
+  retrievalConfigFromSurface,
+  retrievalConfigSurface,
+  retrievalParameterSweepProposer,
+  retrievalRecallJudge,
+  runKnowledgeBenchmarkSuite,
+  runMemoryAdapterBenchmark,
+  runRetrievalImprovementLoop,
+  scoreKnowledgeBenchmarkArtifact,
+  scoreMemoryBenchmarkArtifact,
+  scoreRetrievalArtifact,
+  summarizeKnowledgeBenchmarkCampaign
+} from "./chunk-ULXZI235.js";
+import {
+  reciprocalRankFusion,
+  searchKnowledge,
+  tokenizeQuery
+} from "./chunk-DQ3PDMDP.js";
+import {
+  memoryHitToSourceRecord,
+  memoryWriteResultToSourceRecord
+} from "./chunk-XVU5FFQA.js";
 import {
   sha256,
   slugify,
   stableId
 } from "./chunk-YMKHCTS2.js";
-import {
-  researcherProfile
-} from "./chunk-MU5CEOGE.js";
 
 // src/web-research-worker.ts
 var DEFAULT_MODEL = "glm-5.2";
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 var MIN_MAX_TOKENS = 1200;
+var transientStatuses = /* @__PURE__ */ new Set([429, 502, 503, 504]);
+async function fetchWithRetry(url, init, opts) {
+  let lastRes;
+  for (let attempt = 0; attempt <= opts.maxRetries; attempt += 1) {
+    if (opts.signal?.aborted) throw new RouterError(0, "aborted");
+    const res = await fetch(url, init);
+    if (res.ok || !transientStatuses.has(res.status)) return res;
+    lastRes = res;
+    if (attempt === opts.maxRetries) break;
+    await res.text().catch(() => "");
+    const backoff = opts.retryBaseMs * 2 ** attempt;
+    const jitter = backoff * (0.75 + Math.random() * 0.5);
+    await new Promise((resolve) => setTimeout(resolve, jitter));
+  }
+  if (lastRes) return lastRes;
+  throw new RouterError(0, "fetchWithRetry produced no response");
+}
 var RouterError = class extends Error {
   constructor(status, message) {
     super(`router ${status}: ${message}`);
@@ -96,6 +153,8 @@ function createTangleRouterClient(options = {}) {
     throw new RouterError(401, "no TANGLE_API_KEY (pass apiKey or set the env var)");
   }
   const model = options.model ?? DEFAULT_MODEL;
+  const maxRetries = Math.max(0, options.maxRetries ?? 4);
+  const retryBaseMs = Math.max(1, options.retryBaseMs ?? 1500);
   const headers = {
     "Content-Type": "application/json",
     Authorization: `Bearer ${apiKey}`
@@ -112,16 +171,20 @@ function createTangleRouterClient(options = {}) {
   return {
     async search(query, opts) {
       const t0 = Date.now();
-      const res = await fetch(`${baseUrl}/search`, {
-        method: "POST",
-        headers,
-        signal: options.signal,
-        body: JSON.stringify({
-          query,
-          ...options.searchProvider ? { provider: options.searchProvider } : {},
-          ...opts?.maxResults != null ? { maxResults: opts.maxResults } : {}
-        })
-      });
+      const res = await fetchWithRetry(
+        `${baseUrl}/search`,
+        {
+          method: "POST",
+          headers,
+          signal: options.signal,
+          body: JSON.stringify({
+            query,
+            ...options.searchProvider ? { provider: options.searchProvider } : {},
+            ...opts?.maxResults != null ? { maxResults: opts.maxResults } : {}
+          })
+        },
+        { maxRetries, retryBaseMs, signal: options.signal }
+      );
       acc.searchCalls += 1;
       acc.wallMs += Date.now() - t0;
       if (!res.ok) {
@@ -133,12 +196,16 @@ function createTangleRouterClient(options = {}) {
     async chat(messages, maxTokens) {
       const max_tokens = Math.max(MIN_MAX_TOKENS, maxTokens ?? MIN_MAX_TOKENS);
       const t0 = Date.now();
-      const res = await fetch(`${baseUrl}/chat/completions`, {
-        method: "POST",
-        headers,
-        signal: options.signal,
-        body: JSON.stringify({ model, messages, max_tokens, temperature: 0.2, stream: false })
-      });
+      const res = await fetchWithRetry(
+        `${baseUrl}/chat/completions`,
+        {
+          method: "POST",
+          headers,
+          signal: options.signal,
+          body: JSON.stringify({ model, messages, max_tokens, temperature: 0.2, stream: false })
+        },
+        { maxRetries, retryBaseMs, signal: options.signal }
+      );
       if (!res.ok) {
         throw new RouterError(res.status, await res.text().catch(() => res.statusText));
       }
@@ -929,6 +996,15 @@ ${excerpt}`,
   };
 }
 
+// src/collection-research-driver.ts
+function createCollectionResearchDriver() {
+  return {
+    verifySource(_source) {
+      return { accept: true };
+    }
+  };
+}
+
 // src/discovery.ts
 function createLocalDiscoveryDispatcher(worker) {
   return {
@@ -1179,331 +1255,739 @@ function buildKey(key) {
   return `${key.workspaceId}::${key.sourceId}`;
 }
 
-// src/kb-store.ts
-import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname2, join as join2 } from "path";
-var MemoryKbStore = class {
-  sources = /* @__PURE__ */ new Map();
-  pages = /* @__PURE__ */ new Map();
-  events = [];
-  index = null;
-  async putSource(source) {
-    this.sources.set(source.id, clone(source));
-  }
-  async getSource(id) {
-    return clone(this.sources.get(id) ?? null);
-  }
-  async listSources() {
-    return [...this.sources.values()].map(clone);
-  }
-  async putPage(page) {
-    this.pages.set(page.id, clone(page));
-  }
-  async getPage(idOrPath) {
-    return clone(
-      this.pages.get(idOrPath) ?? [...this.pages.values()].find((page) => page.path === idOrPath) ?? null
-    );
-  }
-  async listPages() {
-    return [...this.pages.values()].map(clone);
-  }
-  async putIndex(index) {
-    this.index = clone(index);
-  }
-  async getIndex() {
-    if (this.index) return clone(this.index);
-    const pages = await this.listPages();
-    const sources = await this.listSources();
-    return {
-      root: "memory",
-      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      sources,
-      pages,
-      graph: buildKnowledgeGraph(pages)
-    };
-  }
-  async putEvent(event) {
-    this.events.push(clone(event));
-  }
-  async listEvents(query = {}) {
-    let out = this.events;
-    if (query.type) out = out.filter((event) => event.type === query.type);
-    if (query.target) out = out.filter((event) => event.target === query.target);
-    out = [...out].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
-    return out.slice(-(query.limit ?? out.length)).map(clone);
-  }
-};
-var FileSystemKbStore = class extends MemoryKbStore {
-  constructor(dir) {
-    super();
-    this.dir = dir;
-  }
-  dir;
-  async putIndex(index) {
-    await super.putIndex(index);
-    await writeJson2(join2(this.dir, "index.json"), index);
-  }
-  async getIndex() {
-    try {
-      return JSON.parse(await readFile2(join2(this.dir, "index.json"), "utf8"));
-    } catch {
-      return await super.getIndex();
-    }
-  }
-  async putEvent(event) {
-    await super.putEvent(event);
-    const events = await this.listEvents();
-    await writeJson2(join2(this.dir, "events.json"), events);
-  }
-};
-async function writeJson2(path, value) {
-  await mkdir2(dirname2(path), { recursive: true });
-  await writeFile2(path, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-}
-function clone(value) {
-  return value == null ? value : JSON.parse(JSON.stringify(value));
-}
-
-// src/propose-from-finding.ts
-var KnowledgeProposalParseError = class extends Error {
-  constructor(findingId, subject, message) {
-    super(`proposeFromFinding(${findingId}, subject=${subject}): ${message}`);
-    this.findingId = findingId;
-    this.subject = subject;
-    this.name = "KnowledgeProposalParseError";
-  }
-  findingId;
-  subject;
-};
-function proposeFromFinding(finding) {
-  if (!finding.subject) return null;
-  if (!finding.subject.startsWith("agent-knowledge:")) return null;
-  const rest = finding.subject.slice("agent-knowledge:".length);
-  const [kindPart, ...locusParts] = rest.split(":");
-  const locus = locusParts.join(":");
-  if (!kindPart || !locus) {
-    throw new KnowledgeProposalParseError(
-      finding.finding_id,
-      finding.subject,
-      "expected `agent-knowledge:<kind>:<locus>` shape"
-    );
+// src/investment-thesis-set.ts
+var investmentThesisSet = [
+  {
+    ticker: "SIVB",
+    company: "SVB Financial Group",
+    cik: "719739",
+    cutoff: "2023-02-24",
+    sector: "Banking",
+    knownOutcome: "Failed in a deposit run and was placed in FDIC receivership on March 10, 2023; the holding company filed Chapter 11 on March 17, 2023.",
+    facts: [
+      {
+        id: "SIVB/f1",
+        lens: "off-balance-sheet",
+        fact: "Held-to-maturity (HTM) securities carried at $91.3B amortized cost had a fair value of only $76.2B \u2014 a ~$15.1B unrealized loss that, because the portfolio is HTM, never touched earnings or equity and sat only in the footnotes.",
+        expected: [
+          {
+            label: "HTM securities",
+            anyOf: ["held-to-maturity", "held to maturity", "htm"]
+          },
+          {
+            label: "large unrealized loss (~$15B) / fair value gap",
+            anyOf: [
+              "15.1",
+              "15.2",
+              "$15 billion",
+              "15 billion",
+              "76,169",
+              "76.2 billion",
+              "91,321",
+              "unrealized loss",
+              "below amortized cost",
+              "fair value"
+            ]
+          }
+        ],
+        minGroups: 2,
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: 'Balance sheet (Dec 31, 2022): "Held-to-maturity securities, at amortized cost ... 91,321" with parenthetical "(fair value of $ 76,169 ...)". The gap = $91,321M - $76,169M = ~$15,152M unrealized loss, disclosed only in the notes.'
+      },
+      {
+        id: "SIVB/f2",
+        lens: "off-balance-sheet",
+        fact: "The HTM unrealized loss (~$15.1B) was roughly equal to the company's entire $16.0B total stockholders' equity \u2014 a mark-to-market wipeout hidden by HTM accounting.",
+        expected: [
+          {
+            label: "loss near/exceeds total equity",
+            anyOf: [
+              "equity",
+              "capital",
+              "insolvent",
+              "wipe out",
+              "exceeds",
+              "nearly all",
+              "tangible book",
+              "16,004",
+              "16 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: `"Total SVBFG stockholders' equity 16,004" (Dec 31, 2022). The ~$15.15B HTM unrealized loss is ~95% of the $16.0B reported equity.`
+      },
+      {
+        id: "SIVB/f3",
+        lens: "concentration",
+        fact: "Estimated uninsured deposits in U.S. offices were $151.5B at year-end 2022 \u2014 the run-prone funding base; a high share of total deposits exceeded the FDIC limit.",
+        expected: [
+          {
+            label: "large uninsured deposit base",
+            anyOf: [
+              "uninsured deposit",
+              "above the fdic",
+              "exceed the fdic",
+              "exceeds the fdic",
+              "151.5",
+              "$151 billion",
+              "fdic insurance limit"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: '"As of December 31, 2022 ... the amount of estimated uninsured deposits in U.S. offices that exceed the FDIC insurance limit were $151.5 billion".'
+      },
+      {
+        id: "SIVB/f4",
+        lens: "margin-trend",
+        fact: "Cheap noninterest-bearing demand deposits fell 20 percentage points in one year \u2014 to 47% of total deposits from 67% \u2014 meaning funding costs were set to rise sharply as clients moved to interest-bearing accounts.",
+        expected: [
+          {
+            label: "deposit mix shift to costlier funding",
+            anyOf: [
+              "noninterest-bearing",
+              "non-interest-bearing",
+              "noninterest bearing",
+              "deposit mix",
+              "funding cost",
+              "cost of deposits",
+              "interest-bearing",
+              "47 percent",
+              "20 percentage"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: '"Noninterest-bearing demand deposits to total deposits decreased by 20 percentage points to 47 percent as of December 31, 2022, compared to ... 2021."'
+      },
+      {
+        id: "SIVB/f5",
+        lens: "concentration",
+        fact: 'The deposit and loan base was concentrated in a single client type \u2014 the "innovation economy" (venture-backed technology and life-science startups) \u2014 so a downturn in venture funding would hit deposits and credit simultaneously.',
+        expected: [
+          {
+            label: "concentration in tech / startups / innovation economy",
+            anyOf: [
+              "innovation economy",
+              "technology",
+              "life science",
+              "venture",
+              "startup",
+              "early-stage",
+              "concentrat",
+              "single industry",
+              "sector concentration"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: 'The 10-K repeatedly frames the franchise around clients in "the innovation economy" (technology, life science / healthcare, and the venture firms that back them) \u2014 a single-sector deposit + credit concentration.'
+      },
+      {
+        id: "SIVB/f6",
+        lens: "off-balance-sheet",
+        fact: "Available-for-sale (AFS) securities of $28.6B amortized cost were marked to a $26.1B fair value \u2014 a ~$2.5B loss that DID flow through equity (AOCI), the visible tip of a much larger unrealized-loss iceberg dominated by the footnote-only HTM book.",
+        expected: [
+          {
+            label: "AFS unrealized loss / AOCI",
+            anyOf: [
+              "available-for-sale",
+              "available for sale",
+              "afs",
+              "aoci",
+              "accumulated other comprehensive",
+              "28,602",
+              "26,069",
+              "2.5 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm",
+        evidence: '"Available-for-sale securities, at fair value (cost of $ 28,602 ...) 26,069" \u2014 a ~$2.5B AFS unrealized loss carried in AOCI, separate from and much smaller than the HTM gap.'
+      }
+    ]
+  },
+  {
+    ticker: "BBBY",
+    company: "Bed Bath & Beyond Inc.",
+    cik: "886158",
+    cutoff: "2022-04-21",
+    sector: "Specialty retail",
+    knownOutcome: "Filed for Chapter 11 bankruptcy on April 23, 2023; shareholders were wiped out.",
+    facts: [
+      {
+        id: "BBBY/f1",
+        lens: "capital-return",
+        fact: 'The company had repurchased ~$11.685B of its own stock since 2004 \u2014 including $574.9M in fiscal 2021 alone, "two years ahead of schedule" \u2014 draining the balance sheet of a business that was losing money.',
+        expected: [
+          {
+            label: "massive buyback program",
+            anyOf: [
+              "repurchas",
+              "buyback",
+              "buy back",
+              "share repurchase",
+              "11.685",
+              "$11.7 billion",
+              "574.9",
+              "$575 million"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm",
+        evidence: '"Since 2004 through the end of Fiscal 2021, we have repurchased approximately $11.685 billion of our common stock"; FY2021 alone "completed share repurchases of $574.9 million ... two years ahead of schedule."'
+      },
+      {
+        id: "BBBY/f2",
+        lens: "liquidity",
+        fact: "Operating cash flow collapsed to just $17.9M in FY2021, down from $268.1M and $590.9M in the two prior years \u2014 a near-total loss of internally generated cash while it kept buying back stock.",
+        expected: [
+          {
+            label: "operating cash flow collapse",
+            anyOf: [
+              "operating cash flow",
+              "cash from operations",
+              "cash provided by operating",
+              "cash flow from operations",
+              "17.9",
+              "17,854",
+              "declining cash flow",
+              "cash generation"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm",
+        evidence: 'Statement of cash flows: "Net cash provided by operating activities 17,854 268,108 590,941" (FY2021 / FY2020 / FY2019, $ thousands).'
+      },
+      {
+        id: "BBBY/f3",
+        lens: "liquidity",
+        fact: "Total shareholders' equity fell ~86% in one year \u2014 from $1.277B to $174.1M \u2014 as losses plus buybacks ate the equity cushion.",
+        expected: [
+          {
+            label: "equity erosion",
+            anyOf: [
+              "shareholders\u2019 equity",
+              "shareholders' equity",
+              "stockholders equity",
+              "book value",
+              "equity",
+              "net worth",
+              "174.1",
+              "174,145",
+              "eroded"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm",
+        evidence: `"Total shareholders' equity 174,145 1,276,936" (FY2021 vs FY2020, $ thousands) \u2014 an ~86% decline in one year.`
+      },
+      {
+        id: "BBBY/f4",
+        lens: "liquidity",
+        fact: "The company posted a $559.6M net loss in FY2021 \u2014 yet spent $574.9M on buybacks the same year, i.e. it returned more cash to shareholders than it had, let alone earned.",
+        expected: [
+          {
+            label: "net loss FY2021",
+            anyOf: [
+              "net loss",
+              "unprofitable",
+              "lost money",
+              "losing money",
+              "559.6",
+              "559,623",
+              "$560 million"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm",
+        evidence: '"Net loss $ ( 559,623 )" for fiscal 2021 ($ thousands).'
+      },
+      {
+        id: "BBBY/f5",
+        lens: "margin-trend",
+        fact: "Merchandise inventories rose to $1.725B even as sales fell \u2014 inventory building into a demand decline, a classic markdown-risk and cash-trap signal.",
+        expected: [
+          {
+            label: "inventory building into falling demand",
+            anyOf: [
+              "inventor",
+              "merchandise inventories",
+              "overstock",
+              "markdown",
+              "1,725",
+              "1.7 billion",
+              "stockpile"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm",
+        evidence: '"Merchandise inventories 1,725,410 1,671,909" ($ thousands) \u2014 inventory grew year over year while comparable sales declined.'
+      }
+    ]
+  },
+  {
+    ticker: "CVNA",
+    company: "Carvana Co.",
+    cik: "1690820",
+    cutoff: "2023-02-23",
+    sector: "Auto e-commerce",
+    knownOutcome: "The stock fell ~98% from its 2021 peak; the company narrowly avoided bankruptcy via a 2023 debt-exchange that cut and extended its obligations.",
+    facts: [
+      {
+        id: "CVNA/f1",
+        lens: "leverage",
+        fact: "Total debt had grown to $8.39B by year-end 2022 (from $5.45B) \u2014 a debt load far larger than the equity base, built up funding growth and the ADESA deal.",
+        expected: [
+          {
+            label: "large/growing debt load",
+            anyOf: [
+              "total debt",
+              "long-term debt",
+              "leverage",
+              "highly leveraged",
+              "debt load",
+              "8,391",
+              "8.4 billion",
+              "$8.4 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm",
+        evidence: '"Total debt 8,391 5,447" (Dec 31, 2022 vs 2021, $ millions).'
+      },
+      {
+        id: "CVNA/f2",
+        lens: "leverage",
+        fact: "Interest expense nearly tripled to $486M in 2022 (from $176M) \u2014 debt-service was consuming cash a still-unprofitable company did not have.",
+        expected: [
+          {
+            label: "rising interest burden",
+            anyOf: [
+              "interest expense",
+              "interest cost",
+              "debt service",
+              "cost of debt",
+              "486",
+              "interest burden"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm",
+        evidence: '"Interest expense 486 176" (FY2022 vs FY2021, $ millions).'
+      },
+      {
+        id: "CVNA/f3",
+        lens: "leverage",
+        fact: "In May 2022 Carvana bought ADESA's U.S. physical auction business for ~$2.2B in cash \u2014 a debt-funded acquisition that stretched the balance sheet right as used-car demand turned.",
+        expected: [
+          {
+            label: "ADESA acquisition ~$2.2B",
+            anyOf: ["adesa", "2.2 billion", "$2.2 billion", "physical auction", "acquisition"]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm",
+        evidence: `"physical auction business of ADESA US Auction, LLC for approximately $2.2 billion in cash (the 'ADESA Acquisition')", closed 2022-05-09.`
+      },
+      {
+        id: "CVNA/f4",
+        lens: "governance",
+        fact: "Carvana leases hubs and properties from DriveTime \u2014 a company controlled by founder/CEO Ernest Garcia III and his father Ernest Garcia II \u2014 a recurring related-party arrangement with the controlling family.",
+        expected: [
+          {
+            label: "related-party with founder family / DriveTime",
+            anyOf: [
+              "related party",
+              "related-party",
+              "drivetime",
+              "garcia",
+              "controlled by",
+              "affiliate of",
+              "conflict of interest"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm",
+        evidence: 'Related Party Transactions note: lease agreements with "DriveTime Automotive Group", a related party "due to Ernest Garcia II, Ernest Garcia III, and entities controlled by one or both of them".'
+      },
+      {
+        id: "CVNA/f5",
+        lens: "liquidity",
+        fact: "The 2022 net loss was $2.894B \u2014 a loss far wider than prior years, showing the unit economics had not turned even at scale.",
+        expected: [
+          {
+            label: "large net loss FY2022",
+            anyOf: [
+              "net loss",
+              "unprofitable",
+              "losing money",
+              "cash burn",
+              "2,894",
+              "2.9 billion",
+              "$2.9 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm",
+        evidence: '"Net loss $ (2,894 ..." for fiscal 2022 ($ millions).'
+      }
+    ]
+  },
+  {
+    ticker: "PTON",
+    company: "Peloton Interactive, Inc.",
+    cik: "1639825",
+    cutoff: "2022-09-07",
+    sector: "Consumer fitness hardware",
+    knownOutcome: "The stock fell ~95% from its 2021 peak; the founder-CEO departed, the company underwent mass layoffs and a multi-year turnaround through fiscal 2024.",
+    facts: [
+      {
+        id: "PTON/f1",
+        lens: "margin-trend",
+        fact: "Connected Fitness (hardware) gross margin turned NEGATIVE \u2014 to (11)% in FY2022 \u2014 meaning Peloton lost money on every bike/tread it sold before any operating cost; revenue growth was masking a broken unit economics.",
+        expected: [
+          {
+            label: "negative / collapsing hardware gross margin",
+            anyOf: [
+              "gross margin",
+              "negative margin",
+              "gross profit",
+              "margin compression",
+              "losing money on each",
+              "below cost",
+              "(11)",
+              "-11",
+              "negative gross"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: 'MD&A "Gross Profit, and Gross Margin" table: Connected Fitness "Gross Margin decreased to (11)" percent in fiscal 2022 \u2014 a negative hardware gross margin.'
+      },
+      {
+        id: "PTON/f2",
+        lens: "liquidity",
+        fact: "Inventories climbed to $1.105B as pandemic demand normalized \u2014 a glut of unsold equipment that tied up cash and risked markdowns.",
+        expected: [
+          {
+            label: "inventory glut",
+            anyOf: [
+              "inventor",
+              "overstock",
+              "excess inventory",
+              "glut",
+              "markdown",
+              "unsold",
+              "1,104",
+              "1.1 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: '"Inventories, net 1,104.5 937" (FY2022 vs FY2021, $ millions).'
+      },
+      {
+        id: "PTON/f3",
+        lens: "governance",
+        fact: "A dual-class structure gives Class B holders 20 votes per share vs 1 for Class A \u2014 concentrating control with insiders/founders and limiting public shareholders' say.",
+        expected: [
+          {
+            label: "dual-class super-voting control",
+            anyOf: [
+              "dual-class",
+              "dual class",
+              "class b",
+              "20 votes",
+              "super-voting",
+              "supervoting",
+              "voting control",
+              "multiple votes per share"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: '"Class B common stock has 20 votes per share and our Class A common stock has one vote per share."'
+      },
+      {
+        id: "PTON/f4",
+        lens: "liquidity",
+        fact: "Peloton reported a $2.827B net loss in FY2022 \u2014 an order-of-magnitude wider loss than the prior year, signaling the demand normalization had broken the model, not just dented it.",
+        expected: [
+          {
+            label: "large net loss FY2022",
+            anyOf: [
+              "net loss",
+              "unprofitable",
+              "losing money",
+              "cash burn",
+              "2,827",
+              "2.8 billion",
+              "$2.8 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: '"Net loss $ (2,827 ..." for fiscal 2022 ($ millions).'
+      },
+      {
+        id: "PTON/f5",
+        lens: "regulatory",
+        fact: "Peloton was running a CPSC recall of its Tread+ treadmill (tied to injuries and a child death) \u2014 an open product-safety and legal exposure beyond the demand story.",
+        expected: [
+          {
+            label: "Tread+ / CPSC recall exposure",
+            anyOf: [
+              "recall",
+              "cpsc",
+              "consumer product safety",
+              "tread+",
+              "tread plus",
+              "product safety",
+              "injuries",
+              "safety"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: `"recall on Tread+, which we are conducting in collaboration with the Consumer Product Safety Commission ('CPSC')"; the Tread product recalls "in the fourth quarter of fiscal 2021 continued to impact" results.`
+      },
+      {
+        id: "PTON/f6",
+        lens: "leverage",
+        fact: "Peloton was locked into ~$334M of manufacturing purchase commitments even as demand fell \u2014 contractual inventory it had to take on regardless of whether it could sell it.",
+        expected: [
+          {
+            label: "locked-in purchase commitments",
+            anyOf: [
+              "purchase commitment",
+              "purchase obligation",
+              "minimum purchase",
+              "take-or-pay",
+              "committed to purchase",
+              "334",
+              "manufacturing commitment"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm",
+        evidence: '"purchase commitments related to the manufacture of Peloton products were estimated to be approximately $334" million.'
+      }
+    ]
+  },
+  {
+    ticker: "SI",
+    company: "Silvergate Capital Corporation",
+    cik: "1312109",
+    cutoff: "2022-02-28",
+    sector: "Banking (digital-asset)",
+    knownOutcome: "After the FTX collapse triggered a deposit run, Silvergate announced a voluntary wind-down of Silvergate Bank and liquidation in March 2023.",
+    facts: [
+      {
+        id: "SI/f1",
+        lens: "concentration",
+        fact: "About 99.5% of total deposits were noninterest-bearing \u2014 essentially all funding was non-term money that could leave on demand, an extreme run-risk masked by very low funding cost.",
+        expected: [
+          {
+            label: "almost all deposits noninterest-bearing / on-demand",
+            anyOf: [
+              "noninterest bearing",
+              "noninterest-bearing",
+              "non-interest-bearing",
+              "demand deposit",
+              "no term",
+              "on demand",
+              "99.5",
+              "99 percent",
+              "leave at any time"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm",
+        evidence: '"noninterest bearing deposits as a percentage of total deposits was 99.5% as of December 31, 2021."'
+      },
+      {
+        id: "SI/f2",
+        lens: "concentration",
+        fact: "Roughly 58% of deposits came from digital-currency EXCHANGES alone \u2014 a handful of correlated crypto counterparties whose own troubles would pull deposits out together.",
+        expected: [
+          {
+            label: "deposits concentrated in crypto exchanges",
+            anyOf: [
+              "digital currency exchange",
+              "crypto exchange",
+              "exchanges represent",
+              "counterpart",
+              "concentrat",
+              "58%",
+              "58 percent",
+              "approximately 58"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm",
+        evidence: '"Deposits from digital currency exchanges represent approximately 58%" of deposits.'
+      },
+      {
+        id: "SI/f3",
+        lens: "concentration",
+        fact: "The entire deposit franchise was tied to a single, volatile industry \u2014 digital-currency (crypto) customers \u2014 so a crypto downturn was a direct, undiversified funding shock.",
+        expected: [
+          {
+            // The buried, depth signal is the CONCENTRATION framing — that the
+            // whole deposit base is one undiversified industry bet — NOT the bare
+            // fact that it banks crypto (a one-line ticker summary has that). So
+            // bare "crypto" / "digital asset" are excluded; the load-bearing
+            // tokens are the concentration / single-industry / undiversified
+            // characterization or the filing's own "digital currency customers".
+            label: 'single-industry deposit CONCENTRATION (not just "it banks crypto")',
+            anyOf: [
+              "digital currency customers",
+              "single industry",
+              "one industry",
+              "single volatile industry",
+              "sector concentration",
+              "undiversified",
+              "concentrat"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm",
+        evidence: `The 10-K's strategy and risk factors center the bank on "digital currency customers" and "the concentration of our deposits" in that single industry.`
+      },
+      {
+        id: "SI/f4",
+        lens: "liquidity",
+        fact: "Total deposits had ballooned to $14.3B (from $10.4B) \u2014 fast, hot-money growth from the crypto boom that could reverse just as fast.",
+        expected: [
+          {
+            // The depth signal is the SIZE/character of the deposit base — the
+            // specific $14.3B figure or the explicit hot-money / volatile-deposit
+            // characterization — NOT bare "total deposits" / "grew rapidly", which
+            // any growth-story summary trips. Those generic phrases are excluded.
+            label: "specific hot-money deposit base ($14.3B / volatile)",
+            anyOf: [
+              "hot money",
+              "hot-money",
+              "volatile deposit",
+              "could reverse",
+              "14.3 billion",
+              "14,290",
+              "$14.3b",
+              "$14 billion"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm",
+        evidence: '"Total deposits $ 14,290,628" ... prior year "$ 10,411,278" ($ thousands).'
+      },
+      {
+        id: "SI/f5",
+        lens: "concentration",
+        fact: "The franchise hinged on a single proprietary product \u2014 the Silvergate Exchange Network (SEN), a payment network built exclusively for the digital-currency industry \u2014 so its competitive moat and its deposit base were the SAME crypto-dependent bet, not two diversified ones.",
+        expected: [
+          {
+            // The depth signal is naming the SPECIFIC proprietary product (the
+            // Silvergate Exchange Network / SEN) and that the moat and the deposit
+            // base are the same single bet — NOT bare "proprietary" / "payment
+            // network", which a generic crypto-bank summary mentions. Those bare
+            // terms are excluded; the SEN name or the single-product framing is
+            // load-bearing.
+            label: 'names the SEN single-product dependence (not generic "payment network")',
+            anyOf: [
+              "silvergate exchange network",
+              "the sen",
+              "sen)",
+              "sen'",
+              "single product",
+              "single-product",
+              "core product",
+              "one product",
+              "same bet"
+            ]
+          }
+        ],
+        sourceUrl: "https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm",
+        evidence: `"Silvergate Exchange Network ('SEN'), our proprietary, virtually instantaneous payment network for participants in the digital currency industry" \u2014 the bank's differentiator and its deposit magnet are the same crypto-only product.`
+      }
+    ]
   }
-  const baseMeta = {
-    severity: finding.severity,
-    confidence: finding.confidence,
-    evidence_uri: finding.evidence_refs[0]?.uri,
-    analyst_id: finding.analyst_id
+];
+function gradeFactAgainstText(fact, thesisText) {
+  const haystack = thesisText.toLowerCase();
+  const found = fact.expected.filter(
+    (group) => group.anyOf.some((fragment) => haystack.includes(fragment.toLowerCase()))
+  );
+  const minGroups = fact.minGroups ?? fact.expected.length;
+  return {
+    surfaced: found.length >= minGroups,
+    groupsFound: found.length,
+    groupsTotal: fact.expected.length,
+    foundLabels: found.map((group) => group.label)
   };
-  switch (kindPart) {
-    case "wiki":
-      return wikiProposal(finding, locus, baseMeta);
-    case "claim":
-      return claimProposal(finding, locus, baseMeta);
-    case "raw":
-      return liftRawProposal(finding, locus, baseMeta);
-    case "stale":
-      return markStaleProposal(finding, locus, baseMeta);
-    default:
-      throw new KnowledgeProposalParseError(
-        finding.finding_id,
-        finding.subject,
-        `unknown kind "${kindPart}" (expected one of: wiki | claim | raw | stale)`
-      );
-  }
 }
-function wikiProposal(finding, locus, metadata) {
-  const hashIdx = locus.indexOf("#");
-  const pageSlug = hashIdx >= 0 ? locus.slice(0, hashIdx) : locus;
-  const heading = hashIdx >= 0 ? locus.slice(hashIdx + 1) : null;
-  const path = `knowledge/${ensureSlug(pageSlug)}.md`;
-  const body = renderWikiBody(finding, pageSlug, heading);
+function gradeCompanyAgainstText(company, thesisText) {
+  const perFact = company.facts.map((fact) => gradeFactAgainstText(fact, thesisText));
   return {
-    id: `prop-${finding.finding_id}`,
-    sourceFindingId: finding.finding_id,
-    kind: heading ? "append-section" : "create-page",
-    locus: pageSlug,
-    writeBlocks: [{ path, content: body }],
-    metadata
+    surfaced: perFact.filter((result) => result.surfaced).length,
+    total: company.facts.length,
+    perFact
   };
 }
-function claimProposal(finding, locus, metadata) {
-  const refs = finding.evidence_refs.filter((r) => r.uri).map((r) => ({
-    sourceId: `analyst-finding:${finding.finding_id}`,
-    anchorId: r.uri,
-    quote: r.excerpt
-  }));
-  const claim = {
-    id: `claim-${finding.finding_id}`,
-    text: finding.recommended_action ?? finding.claim,
-    refs,
-    confidence: finding.confidence,
-    status: "draft",
-    metadata: {
-      analyst_id: finding.analyst_id,
-      source_finding_id: finding.finding_id,
-      topic: locus
+function totalMaterialFacts(set = investmentThesisSet) {
+  return set.reduce((sum, company) => sum + company.facts.length, 0);
+}
+function lensDistribution(set = investmentThesisSet) {
+  const dist = {};
+  for (const company of set) {
+    for (const fact of company.facts) {
+      dist[fact.lens] = (dist[fact.lens] ?? 0) + 1;
     }
-  };
+  }
+  return dist;
+}
+
+// src/investment-thesis-task.ts
+import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
+import { join as join2 } from "path";
+
+// src/material-facts-metric.ts
+function kbIndexToText(index) {
+  const pageText = index.pages.map((page) => `${page.title}
+${page.text}`).join("\n\n");
+  const sourceText = index.sources.map((source) => `${source.title ?? ""}
+${source.text ?? ""}`).join("\n\n");
+  return `${pageText}
+
+${sourceText}`;
+}
+function materialFactsSurfacedInText(company, kbText) {
+  const grade = gradeCompanyAgainstText(company, kbText);
+  const perFact = company.facts.map((fact) => {
+    const r = gradeFactAgainstText(fact, kbText);
+    return {
+      id: fact.id,
+      lens: fact.lens,
+      surfaced: r.surfaced,
+      groupsFound: r.groupsFound,
+      groupsTotal: r.groupsTotal,
+      foundLabels: r.foundLabels
+    };
+  });
   return {
-    id: `prop-${finding.finding_id}`,
-    sourceFindingId: finding.finding_id,
-    kind: "create-claim",
-    locus,
-    writeBlocks: [],
-    claim,
-    metadata
+    ticker: company.ticker,
+    company: company.company,
+    surfaced: grade.surfaced,
+    total: grade.total,
+    fraction: grade.total === 0 ? 0 : grade.surfaced / grade.total,
+    perFact
   };
 }
-function liftRawProposal(finding, sourceId, metadata) {
-  const path = `knowledge/${ensureSlug(sourceId)}.md`;
-  const body = [
-    "---",
-    `title: ${sourceId}`,
-    `source: ${sourceId}`,
-    `status: draft`,
-    `lifted_from_finding: ${finding.finding_id}`,
-    "---",
-    "",
-    "## Why this page exists",
-    "",
-    finding.claim,
-    "",
-    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
-    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
-  ].join("\n");
-  return {
-    id: `prop-${finding.finding_id}`,
-    sourceFindingId: finding.finding_id,
-    kind: "lift-raw",
-    locus: sourceId,
-    writeBlocks: [{ path, content: body }],
-    metadata
-  };
-}
-function markStaleProposal(finding, pageSlug, metadata) {
-  const path = `knowledge/${ensureSlug(pageSlug)}.stale.md`;
-  const body = [
-    "---",
-    `title: ${pageSlug} (marked stale)`,
-    `status: superseded`,
-    `superseded_by_finding: ${finding.finding_id}`,
-    `confidence: ${finding.confidence}`,
-    "---",
-    "",
-    "## Why marked stale",
-    "",
-    finding.claim,
-    "",
-    ...finding.rationale ? ["## Evidence", "", finding.rationale, ""] : [],
-    ...finding.recommended_action ? ["## Action", "", finding.recommended_action, ""] : []
-  ].join("\n");
-  return {
-    id: `prop-${finding.finding_id}`,
-    sourceFindingId: finding.finding_id,
-    kind: "mark-stale",
-    locus: pageSlug,
-    writeBlocks: [{ path, content: body }],
-    metadata
-  };
-}
-function proposeFromFindings(findings) {
-  const proposals = [];
-  const errors = [];
-  let skipped = 0;
-  for (const f of findings) {
-    try {
-      const p = proposeFromFinding(f);
-      if (p) proposals.push(p);
-      else skipped += 1;
-    } catch (err) {
-      if (err instanceof KnowledgeProposalParseError) errors.push(err);
-      else throw err;
-    }
-  }
-  return { proposals, skipped, errors };
-}
-function ensureSlug(s) {
-  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 200) || "untitled";
-}
-function renderWikiBody(finding, slug, heading) {
-  const title = humanize(slug);
-  if (heading) {
-    return [
-      `## ${heading}`,
-      "",
-      finding.claim,
-      "",
-      ...finding.rationale ? ["### Rationale", "", finding.rationale, ""] : [],
-      ...finding.recommended_action ? ["### Action", "", finding.recommended_action, ""] : [],
-      `_Drafted from finding ${finding.finding_id} (confidence ${finding.confidence.toFixed(2)})._`
-    ].join("\n");
-  }
-  return [
-    "---",
-    `title: ${title}`,
-    `status: draft`,
-    `drafted_from_finding: ${finding.finding_id}`,
-    `confidence: ${finding.confidence}`,
-    "---",
-    "",
-    `# ${title}`,
-    "",
-    finding.claim,
-    "",
-    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
-    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
-  ].join("\n");
-}
-function humanize(slug) {
-  return slug.split("-").filter(Boolean).map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ") || slug;
-}
-
-// src/release.ts
-import {
-  evaluateReleaseConfidence,
-  validateRunRecord
-} from "@tangle-network/agent-eval";
-function knowledgeReleaseReport(input) {
-  const baselineRuns = input.baselineRuns ?? [];
-  const runRecords = [...input.candidateRuns, ...baselineRuns].map(validateRunRecord);
-  const scorecard = evaluateReleaseConfidence({
-    target: "agent-knowledge-base",
-    candidateId: input.candidateId,
-    baselineId: input.baselineId ?? "baseline",
-    traces: input.traces ?? [],
-    runs: runRecords,
-    gateDecision: input.gateDecision ?? null,
-    thresholds: {
-      requireCorpus: false,
-      // The report gates on RunRecord-level outcomes, not on a separate scenario
-      // corpus (KnowledgeReleaseInput carries no dataset/scenarios). The scenario
-      // floor must therefore be 0 — otherwise the corpus axis fails closed on a
-      // dimension the report has no way to satisfy, masking the run-based gate.
-      minScenarioCount: 0,
-      requireHoldout: input.hasHoldout ?? false,
-      minHoldoutRuns: input.hasHoldout ? 1 : 0,
-      minSearchRuns: 1,
-      minMeanScore: input.minScore ?? 0.7
-    }
-  });
-  const release = {
-    id: stableId("krel", `${input.candidateId}:${input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}`),
-    candidateId: input.candidateId,
-    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
-    promoted: scorecard.status !== "fail" && (input.promotedIsBest ?? true),
-    scorecard,
-    runRecordIds: runRecords.map((record) => record.runId)
-  };
-  return { release, scorecard, candidateRuns: input.candidateRuns, baselineRuns };
+async function materialFactsSurfaced(kb, checklist) {
+  const index = typeof kb === "string" ? await buildKnowledgeIndex(kb) : kb;
+  return materialFactsSurfacedInText(checklist, kbIndexToText(index));
 }
 
-// src/research-loop.ts
-import {
-  blockingKnowledgeEval,
-  objectiveEval
-} from "@tangle-network/agent-eval";
-
 // src/readiness-helpers.ts
 function readinessFor(options, index) {
   if (!options.readinessSpecs?.length) return void 0;
@@ -1515,228 +1999,26 @@ function readinessFor(options, index) {
   });
 }
 
-// src/research-loop.ts
-function createKnowledgeControlLoopAdapter(options) {
-  let initialized = false;
-  const appliedSteps = [];
-  return {
-    intent: options.goal,
-    async observe({ history, abortSignal }) {
-      if (abortSignal.aborted) throw new Error("Knowledge control loop aborted");
-      if (!initialized) {
-        await initKnowledgeBase(options.root);
-        initialized = true;
-      }
-      const index = await buildKnowledgeIndex(options.root);
-      const validation = validateKnowledgeIndex(index, { strict: options.strict });
-      const lintFindings = lintKnowledgeIndex(index);
-      const readiness = readinessFor(options, index);
-      return {
-        root: options.root,
-        goal: options.goal,
-        iteration: history.length + 1,
-        index,
-        lintFindings,
-        validation,
-        readiness,
-        previousSteps: [...appliedSteps],
-        signal: abortSignal
-      };
-    },
-    validate({ state }) {
-      const errorFindings = state.validation.findings.filter(
-        (finding) => finding.severity === "error"
-      );
-      const evals = [
-        objectiveEval({
-          id: "knowledge-valid",
-          passed: state.validation.ok,
-          severity: "critical",
-          detail: state.validation.ok ? "Knowledge index is valid." : "Knowledge index has validation errors.",
-          metadata: { findings: state.validation.findings }
-        }),
-        objectiveEval({
-          id: "knowledge-lint-errors",
-          passed: errorFindings.length === 0,
-          severity: "error",
-          detail: errorFindings.length === 0 ? "No lint errors." : `${errorFindings.length} lint error(s).`,
-          metadata: { findings: errorFindings }
-        })
-      ];
-      if (state.readiness) evals.push(blockingKnowledgeEval(state.readiness.report));
-      return evals;
-    },
-    shouldStop() {
-      return { stop: false, pass: false, reason: "knowledge driver owns stop decisions" };
-    },
-    async act(action, ctx) {
-      const step = await applyKnowledgeResearchDecision(options, action, ctx.state.iteration);
-      appliedSteps.push(step);
-      return step;
-    }
-  };
-}
-async function runKnowledgeResearchLoop(options) {
-  const maxIterations = Math.max(1, options.maxIterations ?? 3);
+// src/two-agent-research-loop.ts
+async function runVerifiedResearchLoop(options) {
+  const maxRounds = Math.max(1, options.maxRounds ?? 3);
   await initKnowledgeBase(options.root);
   const steps = [];
   let index = await buildKnowledgeIndex(options.root);
-  let validation = validateKnowledgeIndex(index, { strict: options.strict });
-  let lintFindings = lintKnowledgeIndex(index);
   let readiness = readinessFor(options, index);
-  let done = false;
-  for (let iteration = 1; iteration <= maxIterations; iteration++) {
-    if (options.signal?.aborted) throw new Error("Knowledge research loop aborted");
-    const decision = await options.step({
+  let ready = isReady(readiness?.report);
+  let steer;
+  for (let round2 = 1; round2 <= maxRounds && !ready; round2++) {
+    if (options.signal?.aborted) throw new Error("Two-agent research loop aborted");
+    const gaps = gapsFromReadiness(readiness);
+    const workerContribution = await options.worker({
       root: options.root,
       goal: options.goal,
-      iteration,
+      round: round2,
       index,
-      lintFindings,
-      validation,
-      readiness,
-      previousSteps: steps,
-      signal: options.signal
-    });
-    done = Boolean(decision.done);
-    const step = await applyKnowledgeResearchDecision(options, decision, iteration);
-    index = await buildKnowledgeIndex(options.root);
-    validation = step.validation;
-    lintFindings = step.lintFindings;
-    readiness = step.readiness;
-    steps.push(step);
-    await options.onStep?.(step);
-    if (done) break;
-    if (!step.applied && step.addedSources.length === 0) break;
-  }
-  return {
-    root: options.root,
-    goal: options.goal,
-    iterations: steps.length,
-    done,
-    index,
-    lintFindings,
-    validation,
-    readiness,
-    steps
-  };
-}
-async function applyKnowledgeResearchDecision(options, decision, iteration = 1) {
-  const addedSources = [];
-  for (const sourcePath of decision.sourcePaths ?? []) {
-    addedSources.push(...await addSourcePath(options.root, sourcePath, options.sourceOptions));
-  }
-  for (const sourceText of decision.sourceTexts ?? []) {
-    addedSources.push(await addSourceText(options.root, sourceText, options.sourceOptions));
-  }
-  const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText) : void 0;
-  const index = await buildKnowledgeIndex(options.root);
-  const validation = validateKnowledgeIndex(index, { strict: options.strict });
-  const lintFindings = lintKnowledgeIndex(index);
-  const readiness = readinessFor(options, index);
-  const done = Boolean(decision.done);
-  const event = createKnowledgeEvent({
-    type: "research.iteration",
-    actor: options.actor,
-    target: options.root,
-    metadata: {
-      goal: options.goal,
-      iteration,
-      done,
-      addedSourceCount: addedSources.length,
-      written: applied?.written,
-      warningCount: applied?.warnings.length ?? 0,
-      errorCount: validation.findings.filter((finding) => finding.severity === "error").length
-    }
-  });
-  return {
-    iteration,
-    notes: decision.notes,
-    addedSources,
-    applied,
-    lintFindings,
-    validation,
-    readiness,
-    event,
-    done,
-    metadata: decision.metadata
-  };
-}
-
-// src/research-supervisor.ts
-import {
-  supervise
-} from "@tangle-network/agent-runtime/loops";
-var RESEARCH_SUPERVISOR_SYSTEM_PROMPT = [
-  "You are a research SUPERVISOR. You do not answer the research question yourself \u2014",
-  "you create and manage a team of researcher workers that grow ONE shared",
-  "knowledge base until it is ready.",
-  "",
-  "Each round:",
-  "  1. Read the goal and the gaps the readiness gate still reports.",
-  "  2. DECOMPOSE the open work into independent sub-topics. Spawn ONE researcher",
-  "     per sub-topic (spawn_agent) \u2014 split by sub-topic, never duplicate work.",
-  "     Spawn more researchers for a broad goal, fewer for a narrow one.",
-  "  3. Wait for the researchers to settle (await_event). Steer or re-spawn for",
-  "     the sub-topics that came back thin.",
-  "  4. STOP as soon as the deliverable check reports the knowledge base is ready.",
-  "",
-  "Conserve your budget: every spawn spends from one shared pool. Prefer a small",
-  "number of well-scoped researchers over a large fanout that re-covers the same",
-  "ground."
-].join("\n");
-function knowledgeReadinessDeliverable(options) {
-  return {
-    describe: `knowledge base at ${options.root} is ready for: ${options.goal}`,
-    async check() {
-      const index = await buildKnowledgeIndex(options.root);
-      const bundle = readinessFor(options, index);
-      return (bundle?.report.blockingMissingRequirements.length ?? 0) === 0;
-    }
-  };
-}
-async function runResearchSupervisor(options) {
-  await initKnowledgeBase(options.root);
-  const { profile: workerProfile } = researcherProfile({ harness: options.harness });
-  const baseInstructions = options.supervisorSystemPrompt ?? RESEARCH_SUPERVISOR_SYSTEM_PROMPT;
-  const workerContract = workerProfile.prompt?.systemPrompt;
-  const systemPrompt = workerContract ? `${baseInstructions}
-
-Each researcher worker you spawn follows this contract:
-${workerContract}` : baseInstructions;
-  const profile = {
-    name: "research-supervisor",
-    model: options.supervisorModel,
-    systemPrompt
-  };
-  return supervise(profile, options.goal, {
-    ...options.superviseOptions,
-    budget: options.budget,
-    backend: options.backend,
-    deliverable: knowledgeReadinessDeliverable(options)
-  });
-}
-
-// src/two-agent-research-loop.ts
-async function runTwoAgentResearchLoop(options) {
-  const maxRounds = Math.max(1, options.maxRounds ?? 3);
-  await initKnowledgeBase(options.root);
-  const steps = [];
-  let index = await buildKnowledgeIndex(options.root);
-  let readiness = readinessFor(options, index);
-  let ready = isReady(readiness?.report);
-  let steer;
-  for (let round2 = 1; round2 <= maxRounds && !ready; round2++) {
-    if (options.signal?.aborted) throw new Error("Two-agent research loop aborted");
-    const gaps = gapsFromReadiness(readiness);
-    const workerContribution = await options.worker({
-      root: options.root,
-      goal: options.goal,
-      round: round2,
-      index,
-      gaps,
-      steer,
-      readiness: requireReadiness(readiness, options),
+      gaps,
+      steer,
+      readiness: requireReadiness(readiness, options),
       signal: options.signal
     });
     const accepted = [];
@@ -1912,12 +2194,2481 @@ ${source.text}`.toLowerCase();
   }
   return hits;
 }
+var runTwoAgentResearchLoop = runVerifiedResearchLoop;
+
+// src/investment-thesis-task.ts
+function thesisReadinessSpecs(input) {
+  const c = input.company;
+  const t = input.ticker;
+  const filing = `${c} ${t} SEC 10-K annual report SEC.gov EDGAR filing`;
+  return [
+    defineReadinessSpec({
+      id: "thesis/filing",
+      description: `the most recent SEC 10-K annual report for ${c} (${t}) filed on or before ${input.cutoff}, from SEC EDGAR`,
+      query: filing,
+      requiredFor: ["ResearchAgent"],
+      importance: "blocking",
+      minSources: 2,
+      minHits: 1
+    }),
+    defineReadinessSpec({
+      id: "thesis/balance-sheet",
+      description: `${c} balance-sheet risks: securities marked below cost, unrealized losses, leverage / total debt, debt maturities, interest expense`,
+      query: `${c} ${t} 10-K balance sheet total debt unrealized losses interest expense leverage`,
+      requiredFor: ["ResearchAgent"],
+      importance: "blocking",
+      minSources: 2,
+      minHits: 1
+    }),
+    defineReadinessSpec({
+      id: "thesis/concentration-liquidity",
+      description: `${c} concentration + liquidity: customer / deposit / revenue concentration, uninsured deposits, operating cash flow, net loss, inventory, equity erosion`,
+      query: `${c} ${t} 10-K customer deposit concentration operating cash flow net loss inventory`,
+      requiredFor: ["ResearchAgent"],
+      importance: "blocking",
+      minSources: 2,
+      minHits: 1
+    }),
+    defineReadinessSpec({
+      id: "thesis/governance-regulatory",
+      description: `${c} governance + regulatory: related-party transactions, dual-class / super-voting control, buybacks / dividends, recalls, regulatory or legal exposure, margin trends`,
+      query: `${c} ${t} 10-K related party dual class share repurchase recall regulatory gross margin`,
+      requiredFor: ["ResearchAgent"],
+      importance: "blocking",
+      minSources: 2,
+      minHits: 1
+    })
+  ];
+}
+function thesisSynthesisMessages(input, kbText) {
+  const system = "You are a buy-side investment analyst writing a thesis memo. You are given the raw research your team gathered from public filings (SEC 10-K) and the web. Write a thesis that a thorough analyst would write: lead with your JUDGMENT, then the KEY DRIVERS, then the MATERIAL RISKS. Be specific and quantitative \u2014 name the actual figures, balance-sheet items, concentrations, leverage, margin trends, governance items, and regulatory exposures that appear in the research. Surface the buried, non-obvious drivers a one-line ticker summary misses. Ground every claim in the research provided; do NOT invent figures. If the research does not contain a figure, do not state it.";
+  const user = [
+    `Company: ${input.company} (${input.ticker})`,
+    `As-of date (reason as if it is this date): ${input.cutoff}`,
+    input.sector ? `Sector: ${input.sector}` : "",
+    "",
+    "Research gathered (filings + web excerpts):",
+    '"""',
+    kbText.slice(0, 24e3),
+    '"""',
+    "",
+    "Write the investment thesis now. Structure:",
+    "## Judgment",
+    "## Key drivers",
+    "## Material risks"
+  ].filter(Boolean).join("\n");
+  return [
+    { role: "system", content: system },
+    { role: "user", content: user }
+  ];
+}
+async function writeThesisPage(root, input, thesis) {
+  const { knowledgeDir } = layoutFor(root);
+  await mkdir2(knowledgeDir, { recursive: true });
+  const path = join2(knowledgeDir, `thesis-${input.ticker.toLowerCase()}.md`);
+  const body = [
+    "---",
+    `title: Investment thesis \u2014 ${input.company} (${input.ticker})`,
+    `ticker: ${input.ticker}`,
+    `cutoff: ${input.cutoff}`,
+    "kind: investment-thesis",
+    "---",
+    `# Investment thesis \u2014 ${input.company} (${input.ticker}), as of ${input.cutoff}`,
+    "",
+    thesis.trim(),
+    ""
+  ].join("\n");
+  await writeFile2(path, body, "utf8");
+  return path;
+}
+async function runInvestmentThesisTask(input, options) {
+  const worker = createWebResearchWorker({ ...options.workerOptions, router: options.router });
+  const goal = `${input.company} (${input.ticker}) investment thesis as of ${input.cutoff}`;
+  const loop = await runVerifiedResearchLoop({
+    root: options.root,
+    goal,
+    worker,
+    driver: options.driver,
+    readinessSpecs: thesisReadinessSpecs(input),
+    maxRounds: options.maxRounds ?? 3,
+    signal: options.signal
+  });
+  const index = await buildKnowledgeIndex(options.root);
+  const kbText = kbIndexToText(index);
+  const messages = thesisSynthesisMessages(input, kbText);
+  const thesis = await options.router.chat(messages, options.synthesisMaxTokens ?? 1600);
+  const thesisPath = await writeThesisPage(options.root, input, thesis);
+  return { loop, thesis, thesisPath };
+}
+
+// src/kb-improvement.ts
+import { cp, mkdir as mkdir3, open, readdir, readFile as readFile2, rename, rm, stat, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname2, join as join3, relative } from "path";
+
+// src/rag-eval.ts
+var defaultThresholds = {
+  context_precision: 0.5,
+  context_recall: 0.8,
+  context_relevance: 0.5,
+  context_sufficiency: 0.8,
+  faithfulness: 0.9,
+  answer_relevance: 0.7,
+  citation_support: 0.9,
+  abstention: 1,
+  unsupported_answer_rate: 0
+};
+var defaultWeights = {
+  context_relevance: 1,
+  context_sufficiency: 1,
+  faithfulness: 2,
+  answer_relevance: 1,
+  citation_support: 1,
+  abstention: 1
+};
+var metricAliases = {
+  answer_correctness: "answer_correctness",
+  answer_relevance: "answer_relevance",
+  answer_relevancy: "answer_relevance",
+  answerrelevancy: "answer_relevance",
+  context_precision: "context_precision",
+  context_recall: "context_recall",
+  context_relevance: "context_relevance",
+  context_relevancy: "context_relevance",
+  context_sufficiency: "context_sufficiency",
+  contextual_precision: "context_precision",
+  contextual_recall: "context_recall",
+  contextual_relevancy: "context_relevance",
+  faithfulness: "faithfulness",
+  groundedness: "groundedness",
+  claim_recall: "context_recall",
+  claim_precision: "faithfulness",
+  citation_support: "citation_support",
+  abstention: "abstention",
+  unsupported_answer_rate: "unsupported_answer_rate"
+};
+function ragAnswerQualityJudge(options = {}) {
+  return {
+    name: options.name ?? "rag-answer-quality",
+    dimensions: [
+      { key: "context_precision", description: "share of retrieved context that is useful" },
+      { key: "context_recall", description: "share of required evidence present in context" },
+      { key: "context_relevance", description: "context relevance to the query and answer target" },
+      { key: "context_sufficiency", description: "whether context is enough to answer" },
+      { key: "faithfulness", description: "share of answer claims supported by retrieved context" },
+      { key: "answer_relevance", description: "answer addresses the user query" },
+      { key: "answer_correctness", description: "answer contains expected claims" },
+      { key: "citation_support", description: "citations support the claims they cite" },
+      { key: "abstention", description: "answer abstains exactly when the case is unanswerable" }
+    ],
+    appliesTo: (scenario) => scenario.kind === "rag-answer-eval",
+    async score({ artifact, scenario }) {
+      const summary = scoreRagAnswerArtifact(artifact, scenario, options);
+      return {
+        dimensions: summary.metrics,
+        composite: summary.composite,
+        notes: summary.findings.map((finding) => finding.message).join("; ")
+      };
+    }
+  };
+}
+function scoreRagAnswerArtifact(artifact, scenario, options = {}) {
+  const claims = normalizeClaims(artifact);
+  const abstained = artifact.abstained ?? looksLikeAbstention(artifact.answer);
+  const requiredTargets = requiredContextTargets(scenario);
+  const matchedRequiredContextCount = requiredTargets.filter(
+    (target) => artifact.contexts.some((context) => contextMatchesTarget(context, target))
+  ).length;
+  const requiredContextCount = requiredTargets.length;
+  const contextRecall = requiredContextCount === 0 ? neutralScore(Boolean(scenario.unanswerable) || artifact.contexts.length > 0) : matchedRequiredContextCount / requiredContextCount;
+  const relevantContextCount = artifact.contexts.filter(
+    (context) => contextIsRelevant(context, scenario)
+  ).length;
+  const contextPrecision = artifact.contexts.length === 0 ? scenario.unanswerable ? 1 : 0 : relevantContextCount / artifact.contexts.length;
+  const contextRelevance = artifact.contexts.length === 0 ? scenario.unanswerable ? 1 : 0 : average(artifact.contexts.map((context) => contextRelevanceScore(context, scenario)));
+  const contextSufficiency = requiredContextCount === 0 ? contextRelevance : contextRecall;
+  const support = claims.map((claim) => claimSupport(claim.text, artifact.contexts, options));
+  const supportedClaimCount = support.filter(Boolean).length;
+  const faithfulness = claims.length === 0 ? abstained ? 1 : 0 : supportedClaimCount / Math.max(1, claims.length);
+  const citation = scoreCitations(claims, artifact, scenario, options);
+  const answerRelevance = scoreAnswerRelevance(artifact, scenario, abstained);
+  const answerCorrectness = scoreAnswerCorrectness(artifact, scenario, abstained);
+  const abstention = scenario.unanswerable ? abstained ? 1 : 0 : abstained ? 0 : 1;
+  const unsupportedAnswerRate = claims.length === 0 ? abstained ? 0 : 1 : 1 - supportedClaimCount / Math.max(1, claims.length);
+  const deterministicMetrics = {
+    context_precision: clamp01(contextPrecision),
+    context_recall: clamp01(contextRecall),
+    context_relevance: clamp01(contextRelevance),
+    context_sufficiency: clamp01(contextSufficiency),
+    faithfulness: clamp01(faithfulness),
+    groundedness: clamp01(faithfulness),
+    answer_relevance: clamp01(answerRelevance),
+    answer_correctness: clamp01(answerCorrectness),
+    citation_support: clamp01(citation.support),
+    abstention: clamp01(abstention),
+    unsupported_answer_rate: clamp01(unsupportedAnswerRate)
+  };
+  const providerScores = normalizeExternalRagScores(artifact.externalScores ?? []);
+  const metrics = mergeMetrics(deterministicMetrics, providerScores, options.externalScorePolicy);
+  const thresholds = { ...defaultThresholds, ...scenario.thresholds, ...options.thresholds };
+  const findings = diagnoseRagAnswerFailure(metrics, scenario, thresholds);
+  const composite = weightedComposite(metrics, options.weights ?? defaultWeights);
+  return {
+    metrics,
+    composite,
+    passed: findings.every(
+      (finding) => finding.severity !== "error" && finding.severity !== "critical"
+    ),
+    findings,
+    claimCount: claims.length,
+    supportedClaimCount,
+    citedClaimCount: citation.citedClaimCount,
+    supportedCitationCount: citation.supportedCitationCount,
+    matchedRequiredContextCount,
+    requiredContextCount,
+    providerScores
+  };
+}
+function diagnoseRagAnswerFailure(metrics, scenario, thresholds = defaultThresholds) {
+  const findings = [];
+  if (below(metrics.context_recall, thresholds.context_recall)) {
+    findings.push({
+      id: `${scenario.id}:context-recall`,
+      kind: scenario.slices?.includes("multi-source") ? "missing-multihop-evidence" : "retrieval-miss",
+      severity: "error",
+      scenarioId: scenario.id,
+      message: "Required evidence was not present in retrieved context.",
+      evidence: { context_recall: metrics.context_recall }
+    });
+  }
+  if (below(metrics.context_precision, thresholds.context_precision)) {
+    findings.push({
+      id: `${scenario.id}:context-precision`,
+      kind: "retrieval-noise",
+      severity: "warning",
+      scenarioId: scenario.id,
+      message: "Retrieved context contains too much irrelevant material.",
+      evidence: { context_precision: metrics.context_precision }
+    });
+  }
+  if (below(metrics.faithfulness, thresholds.faithfulness)) {
+    findings.push({
+      id: `${scenario.id}:faithfulness`,
+      kind: "generator-unsupported-claim",
+      severity: "error",
+      scenarioId: scenario.id,
+      message: "The answer contains claims not supported by retrieved context.",
+      evidence: { faithfulness: metrics.faithfulness }
+    });
+  }
+  if (below(metrics.citation_support, thresholds.citation_support)) {
+    findings.push({
+      id: `${scenario.id}:citation-support`,
+      kind: "citation-mismatch",
+      severity: "error",
+      scenarioId: scenario.id,
+      message: "Citations do not support the claims they are attached to.",
+      evidence: { citation_support: metrics.citation_support }
+    });
+  }
+  if (below(metrics.abstention, thresholds.abstention)) {
+    findings.push({
+      id: `${scenario.id}:abstention`,
+      kind: "incorrect-abstention",
+      severity: "error",
+      scenarioId: scenario.id,
+      message: scenario.unanswerable ? "The system answered a case marked unanswerable." : "The system abstained from an answerable case.",
+      evidence: { abstention: metrics.abstention }
+    });
+  }
+  return findings;
+}
+function createRagAnswerQualityHook(options) {
+  return async () => {
+    const summaries = [];
+    const findings = [];
+    for (const scenario of options.scenarios) {
+      const initialArtifact = await options.run(scenario);
+      const external = await options.externalEvaluator?.({ scenario, artifact: initialArtifact });
+      const artifact = external ? {
+        ...initialArtifact,
+        externalScores: [
+          ...initialArtifact.externalScores ?? [],
+          ...Array.isArray(external) ? external : [external]
+        ]
+      } : initialArtifact;
+      const summary = scoreRagAnswerArtifact(artifact, scenario, {
+        thresholds: options.thresholds,
+        weights: options.weights
+      });
+      summaries.push(summary);
+      findings.push(...summary.findings);
+    }
+    const metrics = aggregateRagAnswerMetrics(summaries);
+    return {
+      passed: findings.length === 0,
+      metrics,
+      findings,
+      metadata: { scenarioCount: options.scenarios.length }
+    };
+  };
+}
+async function calibrateRagAnswerJudge(options) {
+  const judge = options.judge ?? ragAnswerQualityJudge();
+  const strong = await judge.score({
+    artifact: options.strong,
+    scenario: options.scenario,
+    signal: options.signal ?? new AbortController().signal
+  });
+  const weak = await judge.score({
+    artifact: options.weak,
+    scenario: options.scenario,
+    signal: options.signal ?? new AbortController().signal
+  });
+  const strongScore = strong.composite;
+  const weakScore = weak.composite;
+  const minStrongScore = options.minStrongScore ?? 0.7;
+  const maxWeakScore = options.maxWeakScore ?? 0.3;
+  return {
+    passed: strongScore >= minStrongScore && weakScore <= maxWeakScore,
+    strongScore,
+    weakScore,
+    gap: strongScore - weakScore
+  };
+}
+function normalizeExternalRagScores(scores) {
+  const normalized = {};
+  for (const item of scores) {
+    const provider = item.provider || "custom";
+    const providerScores = normalized[provider] ?? {};
+    for (const [key, value] of Object.entries(item.scores)) {
+      const canonical = metricAliases[normalizeMetricName(key)];
+      if (!canonical) continue;
+      if (Number.isFinite(value)) providerScores[canonical] = clamp01(value);
+    }
+    normalized[provider] = providerScores;
+  }
+  return normalized;
+}
+function toRagasEvaluationRows(cases) {
+  return cases.map(({ scenario, artifact }) => ({
+    user_input: scenario.query,
+    response: artifact.answer,
+    retrieved_contexts: artifact.contexts.map((context) => context.text),
+    reference: scenario.referenceAnswer,
+    reference_contexts: requiredContextTexts(scenario)
+  }));
+}
+function toDeepEvalTestCases(cases) {
+  return cases.map(({ scenario, artifact }) => ({
+    input: scenario.query,
+    actual_output: artifact.answer,
+    expected_output: scenario.referenceAnswer,
+    retrieval_context: artifact.contexts.map((context) => context.text),
+    context: requiredContextTexts(scenario)
+  }));
+}
+function toTruLensRecords(cases) {
+  return cases.map(({ scenario, artifact }) => ({
+    input: scenario.query,
+    output: artifact.answer,
+    context: artifact.contexts.map((context) => context.text).join("\n\n")
+  }));
+}
+function toRagCheckerRecords(cases) {
+  return cases.map(({ scenario, artifact }) => ({
+    query_id: scenario.id,
+    query: scenario.query,
+    gt_answer: scenario.referenceAnswer,
+    response: artifact.answer,
+    retrieved_context: artifact.contexts.map((context) => ({
+      doc_id: context.id,
+      text: context.text
+    })),
+    claims: normalizeClaims(artifact).map((claim) => claim.text)
+  }));
+}
+function scoreKnowledgeBaseIndex(index, options = {}) {
+  const validation = validateKnowledgeIndex(index, { strict: options.strict });
+  const lintFindings = lintKnowledgeIndex(index);
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const staleSourceCount = index.sources.filter((source) => {
+    return source.validUntil ? Date.parse(source.validUntil) < now.getTime() : false;
+  }).length;
+  const sourceHashCounts = /* @__PURE__ */ new Map();
+  for (const source of index.sources) {
+    sourceHashCounts.set(source.contentHash, (sourceHashCounts.get(source.contentHash) ?? 0) + 1);
+  }
+  const duplicateSourceHashCount = [...sourceHashCounts.values()].filter(
+    (count) => count > 1
+  ).length;
+  const pagesWithInlineCitations = index.pages.filter(
+    (page) => sourceRefs(page.text).length > 0
+  ).length;
+  const pagesWithSources = index.pages.filter((page) => page.sourceIds.length > 0).length;
+  const metrics = {
+    page_count: index.pages.length,
+    source_count: index.sources.length,
+    citation_rate: index.pages.length === 0 ? 1 : pagesWithInlineCitations / index.pages.length,
+    source_backed_page_rate: index.pages.length === 0 ? 1 : pagesWithSources / index.pages.length,
+    stale_source_rate: index.sources.length === 0 ? 0 : staleSourceCount / index.sources.length,
+    duplicate_source_hash_rate: index.sources.length === 0 ? 0 : duplicateSourceHashCount / index.sources.length,
+    lint_error_count: validation.findings.filter((finding) => finding.severity === "error").length,
+    lint_warning_count: lintFindings.filter((finding) => finding.severity === "warning").length
+  };
+  const findings = [];
+  if (metrics.lint_error_count > 0) {
+    findings.push({
+      id: "kb:lint-errors",
+      kind: "unknown",
+      severity: "critical",
+      message: `${metrics.lint_error_count} validation error(s) in the knowledge index.`,
+      evidence: { lint_error_count: metrics.lint_error_count }
+    });
+  }
+  if (metrics.citation_rate < (options.minCitationRate ?? 0)) {
+    findings.push({
+      id: "kb:citation-rate",
+      kind: "missing-source",
+      severity: "error",
+      message: "Inline citation coverage is below the configured minimum.",
+      evidence: { citation_rate: metrics.citation_rate }
+    });
+  }
+  if (metrics.stale_source_rate > (options.maxStaleSourceRate ?? 1)) {
+    findings.push({
+      id: "kb:stale-source-rate",
+      kind: "stale-source",
+      severity: "error",
+      message: "Stale source rate exceeds the configured maximum.",
+      evidence: { stale_source_rate: metrics.stale_source_rate }
+    });
+  }
+  return { ok: findings.length === 0, metrics, findings };
+}
+function requiredContextTargets(scenario) {
+  if (scenario.requiredContext?.length) return [...scenario.requiredContext];
+  return (scenario.expectedClaims ?? []).map((text) => ({ text }));
+}
+function requiredContextTexts(scenario) {
+  return requiredContextTargets(scenario).flatMap((target) => target.text ? [target.text] : []);
+}
+function contextMatchesTarget(context, target) {
+  if (target.id && context.id === target.id) return true;
+  if (target.pageId && context.pageId === target.pageId) return true;
+  if (target.sourceId && context.sourceId === target.sourceId) return true;
+  if (target.anchorId && context.anchorId === target.anchorId) return true;
+  if (target.text && textSupportScore(target.text, context.text) >= 0.7) return true;
+  return false;
+}
+function contextIsRelevant(context, scenario) {
+  return contextRelevanceScore(context, scenario) >= 0.3;
+}
+function contextRelevanceScore(context, scenario) {
+  const targets = [
+    scenario.query,
+    scenario.referenceAnswer,
+    ...scenario.expectedClaims ?? [],
+    ...requiredContextTexts(scenario)
+  ].filter((value) => Boolean(value?.trim()));
+  if (targets.length === 0) return 1;
+  return Math.max(...targets.map((target) => textSupportScore(target, context.text)));
+}
+function claimSupport(claim, contexts, options) {
+  if (contexts.length === 0) return false;
+  const combined = contexts.map((context) => context.text).join("\n\n");
+  const deterministic = groundClaimInText(claim, combined, {
+    minOverlap: options.minClaimSupport ?? 0.7
+  });
+  return deterministic.grounded || textSupportScore(claim, combined) >= (options.minClaimSupport ?? 0.7);
+}
+function scoreCitations(claims, artifact, scenario, options) {
+  if (claims.length === 0)
+    return { support: scenario.unanswerable ? 1 : 0, citedClaimCount: 0, supportedCitationCount: 0 };
+  const citations = artifact.citations ?? [];
+  const citedClaims = claims.filter((claim) => citationsForClaim(claim, citations).length > 0);
+  if (citedClaims.length === 0) {
+    return {
+      support: scenario.requireCitations ? 0 : 1,
+      citedClaimCount: 0,
+      supportedCitationCount: 0
+    };
+  }
+  let supportedCitationCount = 0;
+  for (const claim of citedClaims) {
+    const citedContexts = contextsForClaim(claim, citations, artifact.contexts);
+    if (claimSupport(claim.text, citedContexts, options)) supportedCitationCount += 1;
+  }
+  return {
+    support: supportedCitationCount / citedClaims.length,
+    citedClaimCount: citedClaims.length,
+    supportedCitationCount
+  };
+}
+function citationsForClaim(claim, citations) {
+  const claimCitationIds = new Set(claim.citationIds ?? []);
+  return citations.filter((citation) => {
+    return citation.claimId === claim.id || citation.id && claimCitationIds.has(citation.id);
+  });
+}
+function contextsForClaim(claim, citations, contexts) {
+  const matchedCitations = citationsForClaim(claim, citations);
+  const matchedContexts = contexts.filter(
+    (context) => matchedCitations.some((citation) => {
+      if (citation.contextId && citation.contextId === context.id) return true;
+      if (citation.pageId && citation.pageId === context.pageId) return true;
+      if (citation.sourceId && citation.sourceId === context.sourceId) return true;
+      if (citation.anchorId && citation.anchorId === context.anchorId) return true;
+      return false;
+    })
+  );
+  return matchedContexts.length > 0 ? matchedContexts : contexts;
+}
+function scoreAnswerRelevance(artifact, scenario, abstained) {
+  if (scenario.unanswerable) return abstained ? 1 : 0;
+  if (abstained) return 0;
+  const targets = [
+    scenario.referenceAnswer,
+    ...scenario.expectedClaims ?? [],
+    scenario.query
+  ].filter((value) => Boolean(value?.trim()));
+  return Math.max(...targets.map((target) => textSupportScore(target, artifact.answer)));
+}
+function scoreAnswerCorrectness(artifact, scenario, abstained) {
+  if (scenario.unanswerable) return abstained ? 1 : 0;
+  const expected = scenario.expectedClaims ?? [];
+  const forbidden = scenario.forbiddenClaims ?? [];
+  const expectedScore = expected.length === 0 ? scoreAnswerRelevance(artifact, scenario, abstained) : average(expected.map((claim) => textSupportScore(claim, artifact.answer)));
+  const forbiddenPenalty = forbidden.length === 0 ? 0 : forbidden.filter((claim) => textSupportScore(claim, artifact.answer) >= 0.7).length / forbidden.length;
+  return clamp01(expectedScore * (1 - forbiddenPenalty));
+}
+function normalizeClaims(artifact) {
+  if (artifact.claims?.length) return [...artifact.claims];
+  return splitSentences(artifact.answer).map((text, index) => ({ id: `claim-${index + 1}`, text }));
+}
+function splitSentences(text) {
+  return text.split(/(?<=[.!?])\s+/).map((sentence) => sentence.trim()).filter((sentence) => sentence.length > 0 && !looksLikeAbstention(sentence));
+}
+function looksLikeAbstention(answer) {
+  const normalized = answer.toLowerCase();
+  return [
+    "i don't know",
+    "i do not know",
+    "not enough information",
+    "cannot answer",
+    "can't answer",
+    "insufficient information",
+    "no reliable answer"
+  ].some((phrase) => normalized.includes(phrase));
+}
+function mergeMetrics(deterministic, providerScores, policy = "prefer-external") {
+  if (policy === "deterministic-first") return deterministic;
+  const merged = { ...deterministic };
+  for (const scores of Object.values(providerScores)) {
+    for (const [key, value] of Object.entries(scores)) {
+      merged[key] = value;
+      if (key === "groundedness") merged.faithfulness = value;
+      if (key === "faithfulness") merged.groundedness = value;
+    }
+  }
+  return merged;
+}
+function aggregateRagAnswerMetrics(summaries) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const summary of summaries) {
+    for (const key of Object.keys(summary.metrics)) keys.add(key);
+  }
+  const out = {};
+  for (const key of [...keys].sort()) {
+    out[key] = average(summaries.map((summary) => summary.metrics[key]));
+  }
+  out.composite = average(summaries.map((summary) => summary.composite));
+  return out;
+}
+function weightedComposite(metrics, weights) {
+  let weighted = 0;
+  let total = 0;
+  for (const [key, weight] of Object.entries(weights)) {
+    if (!Number.isFinite(weight) || weight <= 0) continue;
+    const metric = metrics[key];
+    if (!Number.isFinite(metric)) continue;
+    const value = key === "unsupported_answer_rate" ? 1 - metric : metric;
+    weighted += value * weight;
+    total += weight;
+  }
+  return total === 0 ? 0 : weighted / total;
+}
+function normalizeMetricName(metric) {
+  return metric.trim().toLowerCase().replace(/[@/.-]+/g, "_").replace(/\s+/g, "_");
+}
+function textSupportScore(needle, haystack) {
+  const needleWords = contentWords2(needle);
+  if (needleWords.length === 0) return 0;
+  const haystackWords = new Set(contentWords2(haystack));
+  const present = needleWords.filter((word) => haystackWords.has(word));
+  return present.length / needleWords.length;
+}
+function contentWords2(text) {
+  const normalized = text.toLowerCase().replace(/[^\p{L}\p{N}\s]+/gu, " ").split(/\s+/).map((word) => stem(word.trim())).filter((word) => (word.length >= 3 || /^\d+$/.test(word)) && !stopwords2.has(word));
+  return [...new Set(normalized)];
+}
+function stem(word) {
+  if (word.endsWith("ies") && word.length > 4) return `${word.slice(0, -3)}y`;
+  if (word.endsWith("ing") && word.length > 5) return word.slice(0, -3);
+  if (word.endsWith("ed") && word.length > 4) return word.slice(0, -2);
+  if (word.endsWith("s") && word.length > 3) return word.slice(0, -1);
+  return word;
+}
+function sourceRefs(text) {
+  const refs = [];
+  const regex = /\[\^([A-Za-z0-9_-]+)(?:#([A-Za-z0-9_.:-]+))?\]/g;
+  let match = regex.exec(text);
+  while (match !== null) {
+    refs.push(match[0]);
+    match = regex.exec(text);
+  }
+  return refs;
+}
+function below(metric, threshold) {
+  return threshold !== void 0 && metric < threshold;
+}
+function neutralScore(condition) {
+  return condition ? 1 : 0;
+}
+function average(values) {
+  const finite = values.filter(Number.isFinite);
+  return finite.length === 0 ? 0 : finite.reduce((sum, value) => sum + value, 0) / finite.length;
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+var stopwords2 = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "as",
+  "by",
+  "at",
+  "from",
+  "that",
+  "this",
+  "these",
+  "those",
+  "it",
+  "its",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "has",
+  "have",
+  "had",
+  "can",
+  "will",
+  "would",
+  "should",
+  "may",
+  "might",
+  "not",
+  "no",
+  "than",
+  "then",
+  "over",
+  "under",
+  "about",
+  "into",
+  "their",
+  "they",
+  "them",
+  "what",
+  "when",
+  "where",
+  "who",
+  "why",
+  "how"
+]);
+
+// src/research-loop.ts
+import {
+  blockingKnowledgeEval,
+  objectiveEval
+} from "@tangle-network/agent-eval";
+function createKnowledgeControlLoopAdapter(options) {
+  let initialized = false;
+  const appliedSteps = [];
+  return {
+    intent: options.goal,
+    async observe({ history, abortSignal }) {
+      if (abortSignal.aborted) throw new Error("Knowledge control loop aborted");
+      if (!initialized) {
+        await initKnowledgeBase(options.root);
+        initialized = true;
+      }
+      const index = await buildKnowledgeIndex(options.root);
+      const validation = validateKnowledgeIndex(index, { strict: options.strict });
+      const lintFindings = lintKnowledgeIndex(index);
+      const readiness = readinessFor(options, index);
+      return {
+        root: options.root,
+        goal: options.goal,
+        iteration: history.length + 1,
+        index,
+        lintFindings,
+        validation,
+        readiness,
+        previousSteps: [...appliedSteps],
+        signal: abortSignal
+      };
+    },
+    validate({ state }) {
+      const errorFindings = state.validation.findings.filter(
+        (finding) => finding.severity === "error"
+      );
+      const evals = [
+        objectiveEval({
+          id: "knowledge-valid",
+          passed: state.validation.ok,
+          severity: "critical",
+          detail: state.validation.ok ? "Knowledge index is valid." : "Knowledge index has validation errors.",
+          metadata: { findings: state.validation.findings }
+        }),
+        objectiveEval({
+          id: "knowledge-lint-errors",
+          passed: errorFindings.length === 0,
+          severity: "error",
+          detail: errorFindings.length === 0 ? "No lint errors." : `${errorFindings.length} lint error(s).`,
+          metadata: { findings: errorFindings }
+        })
+      ];
+      if (state.readiness) evals.push(blockingKnowledgeEval(state.readiness.report));
+      return evals;
+    },
+    shouldStop() {
+      return { stop: false, pass: false, reason: "knowledge driver owns stop decisions" };
+    },
+    async act(action, ctx) {
+      const step = await applyKnowledgeResearchDecision(options, action, ctx.state.iteration);
+      appliedSteps.push(step);
+      return step;
+    }
+  };
+}
+async function runKnowledgeResearchLoop(options) {
+  const maxIterations = Math.max(1, options.maxIterations ?? 3);
+  await initKnowledgeBase(options.root);
+  const steps = [];
+  let index = await buildKnowledgeIndex(options.root);
+  let validation = validateKnowledgeIndex(index, { strict: options.strict });
+  let lintFindings = lintKnowledgeIndex(index);
+  let readiness = readinessFor(options, index);
+  let done = false;
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    if (options.signal?.aborted) throw new Error("Knowledge research loop aborted");
+    const decision = await options.step({
+      root: options.root,
+      goal: options.goal,
+      iteration,
+      index,
+      lintFindings,
+      validation,
+      readiness,
+      previousSteps: steps,
+      signal: options.signal
+    });
+    done = Boolean(decision.done);
+    const step = await applyKnowledgeResearchDecision(options, decision, iteration);
+    index = await buildKnowledgeIndex(options.root);
+    validation = step.validation;
+    lintFindings = step.lintFindings;
+    readiness = step.readiness;
+    steps.push(step);
+    await options.onStep?.(step);
+    if (done) break;
+    if (!step.applied && step.addedSources.length === 0) break;
+  }
+  return {
+    root: options.root,
+    goal: options.goal,
+    iterations: steps.length,
+    done,
+    index,
+    lintFindings,
+    validation,
+    readiness,
+    steps
+  };
+}
+async function applyKnowledgeResearchDecision(options, decision, iteration = 1) {
+  const addedSources = [];
+  for (const sourcePath of decision.sourcePaths ?? []) {
+    addedSources.push(...await addSourcePath(options.root, sourcePath, options.sourceOptions));
+  }
+  for (const sourceText of decision.sourceTexts ?? []) {
+    addedSources.push(await addSourceText(options.root, sourceText, options.sourceOptions));
+  }
+  const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText) : void 0;
+  const index = await buildKnowledgeIndex(options.root);
+  const validation = validateKnowledgeIndex(index, { strict: options.strict });
+  const lintFindings = lintKnowledgeIndex(index);
+  const readiness = readinessFor(options, index);
+  const done = Boolean(decision.done);
+  const event = createKnowledgeEvent({
+    type: "research.iteration",
+    actor: options.actor,
+    target: options.root,
+    metadata: {
+      goal: options.goal,
+      iteration,
+      done,
+      addedSourceCount: addedSources.length,
+      written: applied?.written,
+      warningCount: applied?.warnings.length ?? 0,
+      errorCount: validation.findings.filter((finding) => finding.severity === "error").length
+    }
+  });
+  return {
+    iteration,
+    notes: decision.notes,
+    addedSources,
+    applied,
+    lintFindings,
+    validation,
+    readiness,
+    event,
+    done,
+    metadata: decision.metadata
+  };
+}
+
+// src/rag-improvement-loop.ts
+async function runRagKnowledgeImprovementLoop(options) {
+  assertConfiguredRequiredPhases(options);
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const phases = [];
+  let retrieval;
+  let findings = [];
+  let acquisition;
+  let knowledgeUpdate;
+  let answerQuality;
+  let promotion;
+  if (phaseEnabled(options, "retrieval-tuning")) {
+    if (options.retrieval) {
+      retrieval = await runPhase(
+        phases,
+        now,
+        "retrieval-tuning",
+        async () => {
+          assertNotAborted(options.signal);
+          return runRetrievalImprovementLoop(options.retrieval);
+        },
+        summarizeRetrievalResult
+      );
+    } else {
+      skipPhase(phases, now, "retrieval-tuning", "no retrieval options provided");
+    }
+  }
+  if (phaseEnabled(options, "gap-diagnosis")) {
+    if (options.diagnose) {
+      findings = [
+        ...await runPhase(
+          phases,
+          now,
+          "gap-diagnosis",
+          async () => {
+            assertNotAborted(options.signal);
+            return options.diagnose({
+              goal: options.goal,
+              phases,
+              signal: options.signal,
+              retrieval
+            });
+          },
+          (diagnosed) => `${diagnosed.length} finding(s)`
+        )
+      ];
+    } else {
+      skipPhase(phases, now, "gap-diagnosis", "no diagnosis hook provided");
+    }
+  }
+  if (phaseEnabled(options, "knowledge-acquisition")) {
+    if (options.acquireKnowledge) {
+      acquisition = await runPhase(
+        phases,
+        now,
+        "knowledge-acquisition",
+        async () => {
+          assertNotAborted(options.signal);
+          return options.acquireKnowledge({
+            goal: options.goal,
+            phases,
+            signal: options.signal,
+            retrieval,
+            findings
+          });
+        },
+        summarizeAcquisitionDecision
+      );
+    } else {
+      skipPhase(phases, now, "knowledge-acquisition", "no acquisition hook provided");
+    }
+  }
+  if (phaseEnabled(options, "knowledge-update")) {
+    if (options.updateKnowledge) {
+      knowledgeUpdate = await runPhase(
+        phases,
+        now,
+        "knowledge-update",
+        async () => {
+          assertNotAborted(options.signal);
+          return options.updateKnowledge({
+            goal: options.goal,
+            phases,
+            signal: options.signal,
+            retrieval,
+            findings,
+            acquisition
+          });
+        },
+        (result) => result.summary
+      );
+    } else if (options.knowledgeResearch) {
+      knowledgeUpdate = await runPhase(
+        phases,
+        now,
+        "knowledge-update",
+        async () => {
+          assertNotAborted(options.signal);
+          return runKnowledgeResearchUpdate(options, acquisition);
+        },
+        (result) => result.summary
+      );
+    } else {
+      skipPhase(phases, now, "knowledge-update", "no update hook or research loop provided");
+    }
+  }
+  if (phaseEnabled(options, "answer-quality")) {
+    if (options.evaluateAnswers) {
+      answerQuality = await runPhase(
+        phases,
+        now,
+        "answer-quality",
+        async () => {
+          assertNotAborted(options.signal);
+          return options.evaluateAnswers({
+            goal: options.goal,
+            phases,
+            signal: options.signal,
+            retrieval,
+            findings,
+            acquisition,
+            knowledgeUpdate
+          });
+        },
+        summarizeAnswerQuality
+      );
+      findings = [...findings, ...answerQuality.findings ?? []];
+    } else {
+      skipPhase(phases, now, "answer-quality", "no answer-quality hook provided");
+    }
+  }
+  if (phaseEnabled(options, "promotion")) {
+    if (options.promote) {
+      promotion = await runPhase(
+        phases,
+        now,
+        "promotion",
+        async () => {
+          assertNotAborted(options.signal);
+          return options.promote({
+            goal: options.goal,
+            phases,
+            signal: options.signal,
+            retrieval,
+            findings,
+            acquisition,
+            knowledgeUpdate,
+            answerQuality
+          });
+        },
+        (result) => `${result.promoted ? "promoted" : "held"}: ${result.reason}`
+      );
+    } else {
+      skipPhase(phases, now, "promotion", "no promotion hook provided");
+    }
+  }
+  return {
+    goal: options.goal,
+    phases,
+    retrieval,
+    findings,
+    acquisition,
+    knowledgeUpdate,
+    answerQuality,
+    promotion
+  };
+}
+async function runKnowledgeResearchUpdate(options, acquisition) {
+  const research = options.knowledgeResearch;
+  if (!research) {
+    throw new Error("knowledgeResearch options are required to run the knowledge update phase");
+  }
+  const { goal, step, ...rest } = research;
+  const researchStep = step ?? acquisitionBackedResearchStep(acquisition);
+  const maxIterations = step ? rest.maxIterations : 1;
+  const result = await runKnowledgeResearchLoop({
+    ...rest,
+    goal: goal ?? options.goal,
+    maxIterations,
+    signal: options.signal,
+    step: researchStep
+  });
+  return {
+    applied: result.steps.some((stepResult) => {
+      return stepResult.addedSources.length > 0 || Boolean(stepResult.applied);
+    }),
+    summary: `${result.iterations} research iteration(s); done=${String(result.done)}`,
+    research: result
+  };
+}
+function acquisitionBackedResearchStep(acquisition) {
+  if (!acquisition) {
+    throw new Error(
+      "knowledgeResearch requires either a step hook or a knowledge-acquisition result to apply"
+    );
+  }
+  return () => ({ ...acquisition, done: acquisition.done ?? true });
+}
+async function runPhase(phases, now, phase, action, summarize) {
+  const startedAt = now().toISOString();
+  try {
+    const result = await action();
+    phases.push({
+      phase,
+      status: "completed",
+      summary: summarize(result),
+      startedAt,
+      finishedAt: now().toISOString()
+    });
+    return result;
+  } catch (error) {
+    phases.push({
+      phase,
+      status: "failed",
+      summary: error.message,
+      startedAt,
+      finishedAt: now().toISOString()
+    });
+    throw error;
+  }
+}
+function skipPhase(phases, now, phase, summary) {
+  const timestamp = now().toISOString();
+  phases.push({ phase, status: "skipped", summary, startedAt: timestamp, finishedAt: timestamp });
+}
+function summarizeRetrievalResult(result) {
+  return `${result.candidates.length} candidate(s); winner=${JSON.stringify(result.winnerConfig)}`;
+}
+function summarizeAcquisitionDecision(decision) {
+  const sourcePathCount = decision.sourcePaths?.length ?? 0;
+  const sourceTextCount = decision.sourceTexts?.length ?? 0;
+  const proposal = decision.proposalText ? "proposal" : "no proposal";
+  return `${sourcePathCount} path source(s), ${sourceTextCount} text source(s), ${proposal}`;
+}
+function summarizeAnswerQuality(result) {
+  const metrics = Object.entries(result.metrics).sort(([a], [b]) => a.localeCompare(b)).map(([key, value]) => `${key}=${formatMetric(value)}`).join(", ");
+  return `${result.passed ? "passed" : "failed"}${metrics ? `; ${metrics}` : ""}`;
+}
+function formatMetric(value) {
+  return Number.isFinite(value) ? value.toFixed(3) : String(value);
+}
+function phaseEnabled(options, phase) {
+  return !options.enabledPhases || options.enabledPhases.includes(phase);
+}
+function assertConfiguredRequiredPhases(options) {
+  for (const phase of options.requiredPhases ?? []) {
+    if (!phaseEnabled(options, phase)) {
+      throw new Error(`required phase ${phase} is not enabled`);
+    }
+    if (!phaseConfigured(options, phase)) {
+      throw new Error(requiredPhaseMessage(phase));
+    }
+  }
+}
+function phaseConfigured(options, phase) {
+  switch (phase) {
+    case "retrieval-tuning":
+      return Boolean(options.retrieval);
+    case "gap-diagnosis":
+      return Boolean(options.diagnose);
+    case "knowledge-acquisition":
+      return Boolean(options.acquireKnowledge);
+    case "knowledge-update":
+      return Boolean(options.updateKnowledge ?? options.knowledgeResearch);
+    case "answer-quality":
+      return Boolean(options.evaluateAnswers);
+    case "promotion":
+      return Boolean(options.promote);
+  }
+}
+function requiredPhaseMessage(phase) {
+  switch (phase) {
+    case "retrieval-tuning":
+      return "required phase retrieval-tuning requires retrieval options";
+    case "gap-diagnosis":
+      return "required phase gap-diagnosis requires a diagnose hook";
+    case "knowledge-acquisition":
+      return "required phase knowledge-acquisition requires an acquireKnowledge hook";
+    case "knowledge-update":
+      return "required phase knowledge-update requires updateKnowledge or knowledgeResearch";
+    case "answer-quality":
+      return "required phase answer-quality requires an evaluateAnswers hook";
+    case "promotion":
+      return "required phase promotion requires a promote hook";
+  }
+}
+function assertNotAborted(signal) {
+  if (signal?.aborted) {
+    throw new Error("RAG knowledge improvement loop aborted");
+  }
+}
+
+// src/kb-improvement.ts
+var DEFAULT_LEASE_TTL_MS = 15 * 60 * 1e3;
+var UPDATE_PHASES = [
+  "knowledge-acquisition",
+  "knowledge-update"
+];
+var EVALUATION_PHASES = [
+  "retrieval-tuning",
+  "gap-diagnosis",
+  "answer-quality",
+  "promotion"
+];
+function knowledgeImprovementRunId(root, goal) {
+  return stableId("kimpr", `${root}:${goal}`);
+}
+function knowledgeImprovementRunDir(root, runId) {
+  return join3(layoutFor(root).cacheDir, "improvements", runId);
+}
+async function loadKnowledgeImprovementState(root, runId, runDir = knowledgeImprovementRunDir(root, runId)) {
+  try {
+    return JSON.parse(await readFile2(statePath(runDir), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function improveKnowledgeBase(options) {
+  assertKnowledgeImprovementOptions(options);
+  const now = options.now ?? (() => /* @__PURE__ */ new Date());
+  const runId = options.runId ?? knowledgeImprovementRunId(options.root, options.goal);
+  const runDir = options.runDir ?? knowledgeImprovementRunDir(options.root, runId);
+  await initKnowledgeBase(options.root);
+  await mkdir3(runDir, { recursive: true });
+  const lease = await acquireRunLease(runDir, {
+    ownerId: options.ownerId ?? `pid-${process.pid}`,
+    ttlMs: options.leaseTtlMs ?? DEFAULT_LEASE_TTL_MS,
+    now
+  });
+  try {
+    let state = options.resume === false ? null : await loadKnowledgeImprovementState(options.root, runId, runDir);
+    if (!state) {
+      const baseHash = await hashKnowledgeBase(options.root);
+      state = {
+        version: 1,
+        runId,
+        root: options.root,
+        goal: options.goal,
+        status: "running",
+        baseHash,
+        createdAt: now().toISOString(),
+        updatedAt: now().toISOString(),
+        ownerId: lease.ownerId,
+        candidates: []
+      };
+      await saveState(runDir, state, options.onState);
+      await appendLedger(runDir, { type: "run.created", runId, baseHash });
+    }
+    if (state.status === "promoted") {
+      return { runId, runDir, state, promoted: true, blocked: false };
+    }
+    if (state.status === "blocked") {
+      return { runId, runDir, state, promoted: false, blocked: true };
+    }
+    const maxCandidates = Math.max(1, options.maxCandidates ?? 1);
+    let candidate = findActiveCandidate(state);
+    let lifecycle;
+    while (candidate?.status === "running" || !candidate && state.candidates.length < maxCandidates) {
+      if (!candidate) {
+        const currentHash2 = await hashKnowledgeBase(options.root);
+        if (currentHash2 !== state.baseHash) {
+          state = await blockRun(
+            runDir,
+            state,
+            `base changed before candidate creation: expected ${state.baseHash}, got ${currentHash2}`,
+            options.onState,
+            now
+          );
+          return { runId, runDir, state, promoted: false, blocked: true };
+        }
+        candidate = await createCandidateWorkspace(runDir, state, options.root, now);
+        state.candidates.push(candidate);
+        state.status = "running";
+        state.updatedAt = now().toISOString();
+        await saveState(runDir, state, options.onState);
+        await appendLedger(runDir, {
+          type: "candidate.created",
+          runId,
+          candidateId: candidate.candidateId,
+          iteration: candidate.iteration
+        });
+      }
+      lifecycle = await runCandidateLifecycle(runDir, runId, candidate, options, now);
+      candidate.status = "candidate-ready";
+      candidate.updatedAt = now().toISOString();
+      state.status = "candidate-ready";
+      state.updatedAt = now().toISOString();
+      await saveState(runDir, state, options.onState);
+      await appendLedger(runDir, {
+        type: "candidate.ready",
+        runId,
+        candidateId: candidate.candidateId
+      });
+    }
+    if (!candidate) {
+      state.status = "rejected";
+      state.updatedAt = now().toISOString();
+      await saveState(runDir, state, options.onState);
+      return { runId, runDir, state, promoted: false, blocked: false };
+    }
+    candidate = await evaluateCandidate(runDir, state, candidate, lifecycle, options, now);
+    state.updatedAt = now().toISOString();
+    await saveState(runDir, state, options.onState);
+    if (!candidate.evaluation?.passed) {
+      candidate.status = "rejected";
+      state.status = "rejected";
+      state.updatedAt = now().toISOString();
+      await saveState(runDir, state, options.onState);
+      await appendLedger(runDir, {
+        type: "candidate.rejected",
+        runId,
+        candidateId: candidate.candidateId
+      });
+      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: false };
+    }
+    if (options.promote === false) {
+      state.status = "candidate-ready";
+      state.updatedAt = now().toISOString();
+      await saveState(runDir, state, options.onState);
+      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: false };
+    }
+    const currentHash = await hashKnowledgeBase(options.root);
+    if (currentHash !== state.baseHash) {
+      state = await blockRun(
+        runDir,
+        state,
+        `base changed before promotion: expected ${state.baseHash}, got ${currentHash}`,
+        options.onState,
+        now
+      );
+      await appendLedger(runDir, {
+        type: "promotion.blocked",
+        runId,
+        candidateId: candidate.candidateId,
+        reason: state.blockedReason
+      });
+      return { runId, runDir, state, candidate, lifecycle, promoted: false, blocked: true };
+    }
+    await promoteCandidate(options.root, candidate.candidateRoot);
+    candidate.status = "promoted";
+    candidate.updatedAt = now().toISOString();
+    state.status = "promoted";
+    state.promotedCandidateId = candidate.candidateId;
+    state.updatedAt = now().toISOString();
+    await saveState(runDir, state, options.onState);
+    await appendLedger(runDir, {
+      type: "candidate.promoted",
+      runId,
+      candidateId: candidate.candidateId
+    });
+    return { runId, runDir, state, candidate, lifecycle, promoted: true, blocked: false };
+  } finally {
+    await lease.release();
+  }
+}
+function assertKnowledgeImprovementOptions(options) {
+  if (options.step && options.knowledgeResearch?.step) {
+    throw new Error("improveKnowledgeBase accepts either step or knowledgeResearch.step, not both");
+  }
+  const updateDrivers = [
+    Boolean(options.step ?? options.knowledgeResearch),
+    Boolean(options.updateKnowledge)
+  ].filter(Boolean).length;
+  if (updateDrivers > 1) {
+    throw new Error(
+      "improveKnowledgeBase accepts only one knowledge-update driver: knowledgeResearch or updateKnowledge"
+    );
+  }
+}
+async function runCandidateLifecycle(runDir, runId, candidate, options, now) {
+  const lifecycles = [];
+  if (shouldRunUpdateStage(options)) {
+    const updateLifecycle = await runRagKnowledgeImprovementLoop({
+      goal: options.goal,
+      acquireKnowledge: options.acquireKnowledge,
+      knowledgeResearch: candidateKnowledgeResearchOptions(candidate.candidateRoot, options),
+      updateKnowledge: candidateUpdateHook(runId, candidate, options),
+      enabledPhases: selectedStagePhases(options, UPDATE_PHASES),
+      requiredPhases: selectedStageRequiredPhases(options, UPDATE_PHASES),
+      signal: options.signal,
+      now
+    });
+    lifecycles.push(updateLifecycle);
+    recordLifecycle(candidate, "candidate-update", updateLifecycle);
+  }
+  if (shouldRunEvaluationStage(options)) {
+    const candidateIndex = await buildKnowledgeIndex(candidate.candidateRoot);
+    const evaluationLifecycle = await runRagKnowledgeImprovementLoop({
+      goal: options.goal,
+      retrieval: options.retrieval ? {
+        ...options.retrieval,
+        index: candidateIndex,
+        runDir: options.retrieval.runDir ?? join3(runDir, "retrieval", candidate.candidateId)
+      } : void 0,
+      diagnose: options.diagnose,
+      evaluateAnswers: options.evaluateAnswers,
+      promote: options.decidePromotion,
+      enabledPhases: selectedStagePhases(options, EVALUATION_PHASES),
+      requiredPhases: selectedStageRequiredPhases(options, EVALUATION_PHASES),
+      signal: options.signal,
+      now
+    });
+    lifecycles.push(evaluationLifecycle);
+    recordLifecycle(candidate, "candidate-evaluation", evaluationLifecycle);
+  }
+  return mergeLifecycleResults(options.goal, lifecycles);
+}
+function candidateKnowledgeResearchOptions(candidateRoot, options) {
+  if (!options.step && !options.knowledgeResearch) return void 0;
+  const { step: researchStep, ...rest } = options.knowledgeResearch ?? {};
+  const step = options.step ?? researchStep;
+  return {
+    ...rest,
+    root: candidateRoot,
+    step,
+    maxIterations: rest.maxIterations ?? (step ? options.candidateResearchIterations ?? 3 : void 0),
+    strict: rest.strict ?? options.strict,
+    readinessSpecs: rest.readinessSpecs ?? options.readinessSpecs,
+    readinessTaskId: rest.readinessTaskId ?? options.readinessTaskId,
+    readiness: rest.readiness ?? options.readiness
+  };
+}
+function candidateUpdateHook(runId, candidate, options) {
+  if (!options.updateKnowledge) return void 0;
+  return (input) => options.updateKnowledge({
+    ...input,
+    runId,
+    iteration: candidate.iteration,
+    candidateId: candidate.candidateId,
+    root: candidate.candidateRoot,
+    baselineRoot: options.root,
+    candidateRoot: candidate.candidateRoot,
+    baseHash: candidate.baseHash
+  });
+}
+function shouldRunUpdateStage(options) {
+  const phases = selectedStagePhases(options, UPDATE_PHASES);
+  if (phases.length === 0) return false;
+  return Boolean(
+    options.acquireKnowledge || options.step || options.knowledgeResearch || options.updateKnowledge || selectedStageRequiredPhases(options, UPDATE_PHASES).length > 0
+  );
+}
+function shouldRunEvaluationStage(options) {
+  const phases = selectedStagePhases(options, EVALUATION_PHASES);
+  if (phases.length === 0) return false;
+  return Boolean(
+    options.retrieval || options.diagnose || options.evaluateAnswers || options.decidePromotion || selectedStageRequiredPhases(options, EVALUATION_PHASES).length > 0
+  );
+}
+function selectedStagePhases(options, stagePhases) {
+  const requested = options.enabledPhases ?? stagePhases;
+  return requested.filter((phase) => stagePhases.includes(phase));
+}
+function selectedStageRequiredPhases(options, stagePhases) {
+  return (options.requiredPhases ?? []).filter((phase) => stagePhases.includes(phase));
+}
+function recordLifecycle(candidate, stage, lifecycle) {
+  const record = {
+    stage,
+    phases: lifecycle.phases,
+    findingCount: lifecycle.findings.length,
+    retrievalWinnerConfig: lifecycle.retrieval?.winnerConfig,
+    answerQuality: lifecycle.answerQuality,
+    promotionDecision: lifecycle.promotion
+  };
+  candidate.lifecycle = [...candidate.lifecycle ?? [], record];
+  candidate.retrievalWinnerConfig = lifecycle.retrieval?.winnerConfig ?? candidate.retrievalWinnerConfig;
+  candidate.answerQuality = lifecycle.answerQuality ?? candidate.answerQuality;
+  candidate.promotionDecision = lifecycle.promotion ?? candidate.promotionDecision;
+}
+function mergeLifecycleResults(goal, lifecycles) {
+  if (lifecycles.length === 0) return void 0;
+  return {
+    goal,
+    phases: lifecycles.flatMap((lifecycle) => lifecycle.phases),
+    retrieval: lastDefined(lifecycles.map((lifecycle) => lifecycle.retrieval)),
+    findings: lifecycles.flatMap((lifecycle) => lifecycle.findings),
+    acquisition: lastDefined(lifecycles.map((lifecycle) => lifecycle.acquisition)),
+    knowledgeUpdate: lastDefined(lifecycles.map((lifecycle) => lifecycle.knowledgeUpdate)),
+    answerQuality: lastDefined(lifecycles.map((lifecycle) => lifecycle.answerQuality)),
+    promotion: lastDefined(lifecycles.map((lifecycle) => lifecycle.promotion))
+  };
+}
+function lastDefined(values) {
+  for (let index = values.length - 1; index >= 0; index -= 1) {
+    if (values[index] !== void 0) return values[index];
+  }
+  return void 0;
+}
+async function evaluateCandidate(runDir, state, candidate, lifecycle, options, now) {
+  const [baselineIndex, candidateIndex] = await Promise.all([
+    buildKnowledgeIndex(options.root),
+    buildKnowledgeIndex(candidate.candidateRoot)
+  ]);
+  const validation = validateKnowledgeIndex(candidateIndex, { strict: options.strict });
+  const readiness = readinessFor(options, candidateIndex);
+  const kbQuality = scoreKnowledgeBaseIndex(candidateIndex, {
+    strict: options.strict,
+    ...options.kbQuality
+  });
+  const candidateHash = await hashKnowledgeBase(candidate.candidateRoot);
+  const metric = options.evaluate?.({
+    runId: state.runId,
+    iteration: candidate.iteration,
+    root: options.root,
+    baselineRoot: options.root,
+    candidateRoot: candidate.candidateRoot,
+    baselineIndex,
+    candidateIndex,
+    baseHash: state.baseHash,
+    candidateHash,
+    validation,
+    readiness,
+    kbQuality,
+    lifecycle,
+    signal: options.signal
+  }) ?? defaultKnowledgeImprovementMetric(
+    validation,
+    readiness,
+    options.readinessSpecs,
+    kbQuality,
+    lifecycle
+  );
+  candidate.validation = validation;
+  candidate.kbQuality = kbQuality;
+  candidate.readinessBlockingMissing = readiness?.report.blockingMissingRequirements.length;
+  candidate.evaluation = applyLifecycleFailures(normalizeMetric(await metric), lifecycle);
+  candidate.candidateHash = candidateHash;
+  candidate.updatedAt = now().toISOString();
+  await appendLedger(runDir, {
+    type: "candidate.evaluated",
+    runId: state.runId,
+    candidateId: candidate.candidateId,
+    score: candidate.evaluation.score,
+    passed: candidate.evaluation.passed
+  });
+  return candidate;
+}
+function defaultKnowledgeImprovementMetric(validation, readiness, readinessSpecs, kbQuality, lifecycle) {
+  const blockingMissing = readiness?.report.blockingMissingRequirements.length ?? 0;
+  const blockingTotal = readinessSpecs?.filter((spec) => spec.importance === "blocking").length ?? 0;
+  const blockingReadiness = blockingTotal === 0 ? 1 : Math.max(0, blockingTotal - blockingMissing) / blockingTotal;
+  const answerQuality = lifecycle?.answerQuality ? average2(Object.values(lifecycle.answerQuality.metrics).filter(Number.isFinite)) : 1;
+  const promotionDecision = lifecycle?.promotion ? lifecycle.promotion.promoted ? 1 : 0 : 1;
+  const dimensions = {
+    validation: validation.ok ? 1 : 0,
+    kb_quality: kbQuality.ok ? 1 : 0,
+    blocking_readiness: blockingReadiness,
+    answer_quality: answerQuality,
+    promotion_decision: promotionDecision
+  };
+  const failedReasons = [
+    validation.ok ? void 0 : "candidate validation failed",
+    kbQuality.ok ? void 0 : "candidate KB quality check failed",
+    blockingMissing === 0 ? void 0 : `${blockingMissing}/${blockingTotal} blocking knowledge requirements still missing`,
+    lifecycle?.answerQuality && !lifecycle.answerQuality.passed ? "answer quality failed" : void 0,
+    lifecycle?.promotion && !lifecycle.promotion.promoted ? `promotion decision held: ${lifecycle.promotion.reason}` : void 0
+  ].filter((reason) => Boolean(reason));
+  return {
+    score: average2(Object.values(dimensions)),
+    passed: failedReasons.length === 0,
+    dimensions,
+    notes: failedReasons.length === 0 ? "candidate passed configured checks" : failedReasons.join("; ")
+  };
+}
+function applyLifecycleFailures(metric, lifecycle) {
+  const reasons = [
+    metric.notes,
+    lifecycle?.answerQuality && !lifecycle.answerQuality.passed ? "answer quality failed" : void 0,
+    lifecycle?.promotion && !lifecycle.promotion.promoted ? `promotion decision held: ${lifecycle.promotion.reason}` : void 0
+  ].filter((reason) => Boolean(reason));
+  const forcedFailure = Boolean(lifecycle?.answerQuality && !lifecycle.answerQuality.passed) || Boolean(lifecycle?.promotion && !lifecycle.promotion.promoted);
+  return {
+    ...metric,
+    passed: metric.passed && !forcedFailure,
+    notes: reasons.length > 0 ? reasons.join("; ") : metric.notes
+  };
+}
+function normalizeMetric(metric) {
+  if (!Number.isFinite(metric.score) || metric.score < 0 || metric.score > 1) {
+    throw new Error(`knowledge improvement score must be in [0, 1], got ${String(metric.score)}`);
+  }
+  return { ...metric, passed: Boolean(metric.passed) };
+}
+async function createCandidateWorkspace(runDir, state, root, now) {
+  const iteration = state.candidates.length + 1;
+  const candidateId = stableId("kcand", `${state.runId}:${iteration}:${now().toISOString()}`);
+  const candidateRoot = join3(runDir, "candidates", candidateId, "workspace");
+  await copyKnowledgeWorkspace(root, candidateRoot);
+  const createdAt = now().toISOString();
+  return {
+    iteration,
+    candidateId,
+    candidateRoot,
+    baseHash: state.baseHash,
+    status: "running",
+    createdAt,
+    updatedAt: createdAt
+  };
+}
+function findActiveCandidate(state) {
+  return [...state.candidates].reverse().find((candidate) => candidate.status === "candidate-ready" || candidate.status === "running");
+}
+async function copyKnowledgeWorkspace(sourceRoot, targetRoot) {
+  await rm(targetRoot, { recursive: true, force: true });
+  await initKnowledgeBase(targetRoot);
+  await copyIfExists(join3(sourceRoot, "knowledge"), join3(targetRoot, "knowledge"));
+  await copyIfExists(join3(sourceRoot, "raw"), join3(targetRoot, "raw"));
+  await copyIfExists(
+    join3(layoutFor(sourceRoot).cacheDir, "sources.json"),
+    join3(layoutFor(targetRoot).cacheDir, "sources.json")
+  );
+  await writeKnowledgeIndex(targetRoot);
+}
+async function promoteCandidate(root, candidateRoot) {
+  await copyIfExists(join3(candidateRoot, "knowledge"), join3(root, "knowledge"), { replace: true });
+  await copyIfExists(join3(candidateRoot, "raw"), join3(root, "raw"), { replace: true });
+  await copyIfExists(
+    join3(layoutFor(candidateRoot).cacheDir, "sources.json"),
+    join3(layoutFor(root).cacheDir, "sources.json"),
+    { replace: true }
+  );
+  await writeKnowledgeIndex(root);
+}
+async function copyIfExists(source, target, options = {}) {
+  try {
+    await stat(source);
+  } catch {
+    return;
+  }
+  if (options.replace) await rm(target, { recursive: true, force: true });
+  await mkdir3(dirname2(target), { recursive: true });
+  await cp(source, target, { recursive: true });
+}
+async function hashKnowledgeBase(root) {
+  const entries = [];
+  for (const rel of ["knowledge", "raw"]) {
+    entries.push(...await hashTreeEntries(root, rel));
+  }
+  const sourceRegistry = relative(root, layoutFor(root).sourceRegistryPath).replace(/\\/g, "/");
+  entries.push(...await hashFileEntry(root, sourceRegistry));
+  entries.sort((a, b) => a.path.localeCompare(b.path));
+  return sha256(JSON.stringify(entries));
+}
+async function hashTreeEntries(root, relDir) {
+  const abs = join3(root, relDir);
+  try {
+    const s = await stat(abs);
+    if (!s.isDirectory()) return [];
+  } catch {
+    return [];
+  }
+  const out = [];
+  const entries = await readdir(abs, { withFileTypes: true });
+  for (const entry of entries) {
+    const rel = join3(relDir, entry.name).replace(/\\/g, "/");
+    if (entry.isDirectory()) out.push(...await hashTreeEntries(root, rel));
+    else if (entry.isFile()) out.push(...await hashFileEntry(root, rel));
+  }
+  return out;
+}
+async function hashFileEntry(root, rel) {
+  try {
+    const bytes = await readFile2(join3(root, rel));
+    return [{ path: rel, hash: sha256(bytes.toString("base64")) }];
+  } catch {
+    return [];
+  }
+}
+async function acquireRunLease(runDir, options) {
+  const path = join3(runDir, "run.lock");
+  const now = options.now();
+  const expiresAt = new Date(now.getTime() + options.ttlMs);
+  const payload = {
+    ownerId: options.ownerId,
+    acquiredAt: now.toISOString(),
+    expiresAt: expiresAt.toISOString(),
+    pid: process.pid
+  };
+  try {
+    const handle = await open(path, "wx");
+    try {
+      await handle.writeFile(`${JSON.stringify(payload, null, 2)}
+`, "utf8");
+    } finally {
+      await handle.close();
+    }
+  } catch (error) {
+    const code = error.code;
+    if (code !== "EEXIST") throw error;
+    const existing = await readLease(path);
+    if (existing && new Date(existing.expiresAt).getTime() > now.getTime()) {
+      throw new Error(
+        `knowledge improvement run is locked by ${existing.ownerId} until ${existing.expiresAt}`
+      );
+    }
+    await rm(path, { force: true });
+    return acquireRunLease(runDir, options);
+  }
+  return {
+    ownerId: options.ownerId,
+    path,
+    async release() {
+      const current = await readLease(path);
+      if (!current || current.ownerId === options.ownerId) await rm(path, { force: true });
+    }
+  };
+}
+async function readLease(path) {
+  try {
+    return JSON.parse(await readFile2(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function blockRun(runDir, state, reason, onState, now) {
+  state.status = "blocked";
+  state.blockedReason = reason;
+  state.updatedAt = now().toISOString();
+  await saveState(runDir, state, onState);
+  return state;
+}
+async function saveState(runDir, state, onState) {
+  await writeJsonAtomic(statePath(runDir), state);
+  await onState?.(state);
+}
+async function appendLedger(runDir, value) {
+  const row = { at: (/* @__PURE__ */ new Date()).toISOString(), ...value };
+  await mkdir3(runDir, { recursive: true });
+  await writeFile3(join3(runDir, "events.jsonl"), `${JSON.stringify(row)}
+`, { flag: "a" });
+}
+async function writeJsonAtomic(path, value) {
+  await mkdir3(dirname2(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile3(tmp, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+  await rename(tmp, path);
+}
+function statePath(runDir) {
+  return join3(runDir, "state.json");
+}
+function average2(values) {
+  const finite = values.filter(Number.isFinite);
+  if (finite.length === 0) return 0;
+  return finite.reduce((sum, value) => sum + value, 0) / finite.length;
+}
+
+// src/kb-store.ts
+import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname3, join as join4 } from "path";
+var MemoryKbStore = class {
+  sources = /* @__PURE__ */ new Map();
+  pages = /* @__PURE__ */ new Map();
+  events = [];
+  index = null;
+  async putSource(source) {
+    this.sources.set(source.id, clone(source));
+  }
+  async getSource(id) {
+    return clone(this.sources.get(id) ?? null);
+  }
+  async listSources() {
+    return [...this.sources.values()].map(clone);
+  }
+  async putPage(page) {
+    this.pages.set(page.id, clone(page));
+  }
+  async getPage(idOrPath) {
+    return clone(
+      this.pages.get(idOrPath) ?? [...this.pages.values()].find((page) => page.path === idOrPath) ?? null
+    );
+  }
+  async listPages() {
+    return [...this.pages.values()].map(clone);
+  }
+  async putIndex(index) {
+    this.index = clone(index);
+  }
+  async getIndex() {
+    if (this.index) return clone(this.index);
+    const pages = await this.listPages();
+    const sources = await this.listSources();
+    return {
+      root: "memory",
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sources,
+      pages,
+      graph: buildKnowledgeGraph(pages)
+    };
+  }
+  async putEvent(event) {
+    this.events.push(clone(event));
+  }
+  async listEvents(query = {}) {
+    let out = this.events;
+    if (query.type) out = out.filter((event) => event.type === query.type);
+    if (query.target) out = out.filter((event) => event.target === query.target);
+    out = [...out].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return out.slice(-(query.limit ?? out.length)).map(clone);
+  }
+};
+var FileSystemKbStore = class extends MemoryKbStore {
+  constructor(dir) {
+    super();
+    this.dir = dir;
+  }
+  dir;
+  async putIndex(index) {
+    await super.putIndex(index);
+    await writeJson2(join4(this.dir, "index.json"), index);
+  }
+  async getIndex() {
+    try {
+      return JSON.parse(await readFile3(join4(this.dir, "index.json"), "utf8"));
+    } catch {
+      return await super.getIndex();
+    }
+  }
+  async putEvent(event) {
+    await super.putEvent(event);
+    const events = await this.listEvents();
+    await writeJson2(join4(this.dir, "events.json"), events);
+  }
+};
+async function writeJson2(path, value) {
+  await mkdir4(dirname3(path), { recursive: true });
+  await writeFile4(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+// src/propose-from-finding.ts
+var KnowledgeProposalParseError = class extends Error {
+  constructor(findingId, subject, message) {
+    super(`proposeFromFinding(${findingId}, subject=${subject}): ${message}`);
+    this.findingId = findingId;
+    this.subject = subject;
+    this.name = "KnowledgeProposalParseError";
+  }
+  findingId;
+  subject;
+};
+function proposeFromFinding(finding) {
+  if (!finding.subject) return null;
+  if (!finding.subject.startsWith("agent-knowledge:")) return null;
+  const rest = finding.subject.slice("agent-knowledge:".length);
+  const [kindPart, ...locusParts] = rest.split(":");
+  const locus = locusParts.join(":");
+  if (!kindPart || !locus) {
+    throw new KnowledgeProposalParseError(
+      finding.finding_id,
+      finding.subject,
+      "expected `agent-knowledge:<kind>:<locus>` shape"
+    );
+  }
+  const baseMeta = {
+    severity: finding.severity,
+    confidence: finding.confidence,
+    evidence_uri: finding.evidence_refs[0]?.uri,
+    analyst_id: finding.analyst_id
+  };
+  switch (kindPart) {
+    case "wiki":
+      return wikiProposal(finding, locus, baseMeta);
+    case "claim":
+      return claimProposal(finding, locus, baseMeta);
+    case "raw":
+      return liftRawProposal(finding, locus, baseMeta);
+    case "stale":
+      return markStaleProposal(finding, locus, baseMeta);
+    default:
+      throw new KnowledgeProposalParseError(
+        finding.finding_id,
+        finding.subject,
+        `unknown kind "${kindPart}" (expected one of: wiki | claim | raw | stale)`
+      );
+  }
+}
+function wikiProposal(finding, locus, metadata) {
+  const hashIdx = locus.indexOf("#");
+  const pageSlug = hashIdx >= 0 ? locus.slice(0, hashIdx) : locus;
+  const heading = hashIdx >= 0 ? locus.slice(hashIdx + 1) : null;
+  const path = `knowledge/${ensureSlug(pageSlug)}.md`;
+  const body = renderWikiBody(finding, pageSlug, heading);
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: heading ? "append-section" : "create-page",
+    locus: pageSlug,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function claimProposal(finding, locus, metadata) {
+  const refs = finding.evidence_refs.filter((r) => r.uri).map((r) => ({
+    sourceId: `analyst-finding:${finding.finding_id}`,
+    anchorId: r.uri,
+    quote: r.excerpt
+  }));
+  const claim = {
+    id: `claim-${finding.finding_id}`,
+    text: finding.recommended_action ?? finding.claim,
+    refs,
+    confidence: finding.confidence,
+    status: "draft",
+    metadata: {
+      analyst_id: finding.analyst_id,
+      source_finding_id: finding.finding_id,
+      topic: locus
+    }
+  };
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "create-claim",
+    locus,
+    writeBlocks: [],
+    claim,
+    metadata
+  };
+}
+function liftRawProposal(finding, sourceId, metadata) {
+  const path = `knowledge/${ensureSlug(sourceId)}.md`;
+  const body = [
+    "---",
+    `title: ${sourceId}`,
+    `source: ${sourceId}`,
+    `status: draft`,
+    `lifted_from_finding: ${finding.finding_id}`,
+    "---",
+    "",
+    "## Why this page exists",
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "lift-raw",
+    locus: sourceId,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function markStaleProposal(finding, pageSlug, metadata) {
+  const path = `knowledge/${ensureSlug(pageSlug)}.stale.md`;
+  const body = [
+    "---",
+    `title: ${pageSlug} (marked stale)`,
+    `status: superseded`,
+    `superseded_by_finding: ${finding.finding_id}`,
+    `confidence: ${finding.confidence}`,
+    "---",
+    "",
+    "## Why marked stale",
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Evidence", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "mark-stale",
+    locus: pageSlug,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function proposeFromFindings(findings) {
+  const proposals = [];
+  const errors = [];
+  let skipped = 0;
+  for (const f of findings) {
+    try {
+      const p = proposeFromFinding(f);
+      if (p) proposals.push(p);
+      else skipped += 1;
+    } catch (err) {
+      if (err instanceof KnowledgeProposalParseError) errors.push(err);
+      else throw err;
+    }
+  }
+  return { proposals, skipped, errors };
+}
+function ensureSlug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 200) || "untitled";
+}
+function renderWikiBody(finding, slug, heading) {
+  const title = humanize(slug);
+  if (heading) {
+    return [
+      `## ${heading}`,
+      "",
+      finding.claim,
+      "",
+      ...finding.rationale ? ["### Rationale", "", finding.rationale, ""] : [],
+      ...finding.recommended_action ? ["### Action", "", finding.recommended_action, ""] : [],
+      `_Drafted from finding ${finding.finding_id} (confidence ${finding.confidence.toFixed(2)})._`
+    ].join("\n");
+  }
+  return [
+    "---",
+    `title: ${title}`,
+    `status: draft`,
+    `drafted_from_finding: ${finding.finding_id}`,
+    `confidence: ${finding.confidence}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+}
+function humanize(slug) {
+  return slug.split("-").filter(Boolean).map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ") || slug;
+}
+
+// src/readiness-check.ts
+async function evaluateKnowledgeBaseReadiness(options) {
+  const index = await buildKnowledgeIndex(options.root);
+  const validation = validateKnowledgeIndex(index, { strict: options.strict });
+  const readiness = readinessFor(
+    {
+      ...options,
+      readinessSpecs: options.readinessSpecs ? [...options.readinessSpecs] : void 0
+    },
+    index
+  );
+  const kbQuality = scoreKnowledgeBaseIndex(index, {
+    strict: options.strict,
+    ...options.kbQuality
+  });
+  const blockingMissing = readiness?.report.blockingMissingRequirements.length ?? 0;
+  const blockingTotal = options.readinessSpecs?.filter((spec) => spec.importance === "blocking").length ?? 0;
+  const blockingReadiness = blockingTotal === 0 ? 1 : Math.max(0, blockingTotal - blockingMissing) / blockingTotal;
+  const ready = validation.ok && kbQuality.ok && blockingMissing === 0;
+  const failures = [
+    validation.ok ? void 0 : `${validation.findings.length} validation finding(s)`,
+    kbQuality.ok ? void 0 : `${kbQuality.findings.length} KB quality finding(s)`,
+    blockingMissing === 0 ? void 0 : `${blockingMissing}/${blockingTotal} blocking readiness requirement(s) missing`
+  ].filter((failure) => Boolean(failure));
+  return {
+    ready,
+    summary: ready ? "knowledge base passed readiness checks" : failures.join("; "),
+    index,
+    validation,
+    readiness,
+    kbQuality,
+    dimensions: {
+      validation: validation.ok ? 1 : 0,
+      kb_quality: kbQuality.ok ? 1 : 0,
+      blocking_readiness: blockingReadiness
+    }
+  };
+}
+
+// src/release.ts
+import {
+  evaluateReleaseConfidence,
+  validateRunRecord
+} from "@tangle-network/agent-eval";
+function knowledgeReleaseReport(input) {
+  const baselineRuns = input.baselineRuns ?? [];
+  const runRecords = [...input.candidateRuns, ...baselineRuns].map(validateRunRecord);
+  const scorecard = evaluateReleaseConfidence({
+    target: "agent-knowledge-base",
+    candidateId: input.candidateId,
+    baselineId: input.baselineId ?? "baseline",
+    traces: input.traces ?? [],
+    runs: runRecords,
+    gateDecision: input.gateDecision ?? null,
+    thresholds: {
+      requireCorpus: false,
+      // The report gates on RunRecord-level outcomes, not on a separate scenario
+      // corpus (KnowledgeReleaseInput carries no dataset/scenarios). The scenario
+      // floor must therefore be 0 — otherwise the corpus axis fails closed on a
+      // dimension the report has no way to satisfy, masking the run-based gate.
+      minScenarioCount: 0,
+      requireHoldout: input.hasHoldout ?? false,
+      minHoldoutRuns: input.hasHoldout ? 1 : 0,
+      minSearchRuns: 1,
+      minMeanScore: input.minScore ?? 0.7
+    }
+  });
+  const release = {
+    id: stableId("krel", `${input.candidateId}:${input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}`),
+    candidateId: input.candidateId,
+    createdAt: input.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    promoted: scorecard.status !== "fail" && (input.promotedIsBest ?? true),
+    scorecard,
+    runRecordIds: runRecords.map((record) => record.runId)
+  };
+  return { release, scorecard, candidateRuns: input.candidateRuns, baselineRuns };
+}
+
+// src/research-driving-driver.ts
+function createResearchDrivingDriver(options = {}) {
+  const minIndependentSources = Math.max(2, options.minIndependentSources ?? 2);
+  const maxQuestionsPerRound = Math.max(1, options.maxQuestionsPerRound ?? 6);
+  const maxClaimsPerSource = Math.max(1, options.maxClaimsPerSource ?? 3);
+  const deterministicFallback = options.deterministicFallback ?? true;
+  const claims = /* @__PURE__ */ new Map();
+  const questions = /* @__PURE__ */ new Map();
+  let rounds = 0;
+  let lastSteer;
+  function resolveRouter2() {
+    return options.router ?? createTangleRouterClient(options.router_options);
+  }
+  function recordClaim(extracted, sourceUri, round2) {
+    const id = claimId(extracted.text);
+    const host = hostOf2(sourceUri);
+    const existing = claims.get(id);
+    if (existing) {
+      if (host) existing.supportingHosts.add(host);
+      if (!existing.supportingUris.includes(sourceUri)) existing.supportingUris.push(sourceUri);
+      linkContradiction(existing, extracted.contradictsExistingId);
+      return existing;
+    }
+    const tracked = {
+      id,
+      text: extracted.text.trim(),
+      supportingHosts: new Set(host ? [host] : []),
+      supportingUris: [sourceUri],
+      contradicts: /* @__PURE__ */ new Set(),
+      contested: false,
+      firstSeenRound: round2
+    };
+    linkContradiction(tracked, extracted.contradictsExistingId);
+    claims.set(id, tracked);
+    return tracked;
+  }
+  function linkContradiction(claim, otherId) {
+    if (!otherId || otherId === claim.id) return;
+    const other = claims.get(otherId);
+    if (!other) return;
+    claim.contradicts.add(otherId);
+    other.contradicts.add(claim.id);
+    claim.contested = true;
+    other.contested = true;
+  }
+  function independentSupport(claim) {
+    return claim.supportingHosts.size;
+  }
+  function isCorroborated(claim) {
+    return independentSupport(claim) >= minIndependentSources;
+  }
+  function isWeak(claim) {
+    return !isCorroborated(claim) && !claim.contested;
+  }
+  function snapshot() {
+    const all = [...claims.values()];
+    const allQuestions = [...questions.values()];
+    return {
+      claims: all,
+      questions: allQuestions,
+      weaklySupported: all.filter(isWeak),
+      corroborated: all.filter(isCorroborated),
+      contested: all.filter((claim) => claim.contested),
+      openQuestions: allQuestions.filter((question) => !question.addressed),
+      rounds
+    };
+  }
+  function markAddressed(newClaimTexts) {
+    for (const question of questions.values()) {
+      if (question.addressed) continue;
+      if (question.kind === "contradiction") {
+        const settled = question.claimIds.some((id) => {
+          const claim = claims.get(id);
+          return claim ? isCorroborated(claim) || claim.contested : false;
+        });
+        if (settled) question.addressed = true;
+        continue;
+      }
+      const qWords = contentWordSet(question.text);
+      if (qWords.size === 0) continue;
+      for (const text of newClaimTexts) {
+        const overlap = overlapFraction(qWords, contentWordSet(text));
+        if (overlap >= 0.5) {
+          question.addressed = true;
+          break;
+        }
+      }
+    }
+  }
+  return {
+    /**
+     * `verifySource` — the per-source hook. This driver does NOT filter for
+     * relevance/dedup (other drivers do that, and the loop already dedups exact
+     * uris). Its job here is to EXTRACT the source's claims and grow the ledger.
+     * It accepts every source that yields at least one extractable claim; it
+     * only rejects a source with NO extractable signal at all (empty/unusable),
+     * because such a source cannot drive the research and pollutes the KB.
+     */
+    async verifySource(source, ctx) {
+      const extracted = await extractClaims(source, ctx);
+      if (extracted.length === 0) {
+        return {
+          accept: false,
+          reason: "no extractable claim: source yields nothing to drive the research deeper"
+        };
+      }
+      const newTexts = [];
+      for (const claim of extracted) {
+        recordClaim(claim, source.uri, ctx.round);
+        newTexts.push(claim.text);
+      }
+      markAddressed(newTexts);
+      return { accept: true };
+    },
+    /**
+     * `foldGaps` — the DEPTH driver. Runs after the worker's contribution is
+     * applied each round. It builds the next round's steer from (1) the readiness
+     * gaps the loop still reports, (2) freshly generated DEEP sub-questions, and
+     * (3) INVALIDATION challenges for weakly-supported / contradicted claims.
+     */
+    foldGaps(gaps) {
+      rounds += 1;
+      const round2 = rounds;
+      const ledger = [...claims.values()];
+      const invalidationTargets = ledger.filter(
+        (claim) => isWeak(claim) || claim.contradicts.size > 0
+      );
+      const deepQuestions = synthesizeDeepQuestions(ledger, round2).slice(0, maxQuestionsPerRound);
+      for (const question of deepQuestions) {
+        if (!questions.has(question.id)) questions.set(question.id, question);
+      }
+      const text = buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependentSources);
+      lastSteer = { round: round2, deepQuestions, invalidationTargets, gaps, text };
+      options.onSteer?.(lastSteer);
+      return text;
+    },
+    researchState: snapshot,
+    isComplete() {
+      const all = [...claims.values()];
+      if (all.length === 0) return false;
+      const everyClaimSettled = all.every((claim) => isCorroborated(claim) || claim.contested);
+      const everyQuestionAddressed = [...questions.values()].every((question) => question.addressed);
+      return everyClaimSettled && everyQuestionAddressed;
+    },
+    lastSteer() {
+      return lastSteer;
+    }
+  };
+  async function extractClaims(source, ctx) {
+    const ledger = [...claims.values()];
+    const fromLlm = await extractClaimsWithLlm(source, ctx, ledger);
+    if (fromLlm.length > 0) return fromLlm.slice(0, maxClaimsPerSource);
+    if (deterministicFallback) return deterministicClaims(source).slice(0, maxClaimsPerSource);
+    return [];
+  }
+  async function extractClaimsWithLlm(source, ctx, ledger) {
+    let router;
+    try {
+      router = resolveRouter2();
+    } catch {
+      return [];
+    }
+    const excerpt = source.text.slice(0, 1800);
+    const ledgerLines = ledger.slice(0, 20).map((claim) => `- [${claim.id}] ${claim.text}`).join("\n");
+    const system = `You extract the KEY factual claims a researcher would cite a page for, and flag CONTRADICTIONS with claims already on the ledger. A claim is one concrete, checkable assertion using the page's own terms and numbers. Return ONLY a JSON array; each item is {"claim": string, "contradicts": string|null} where contradicts is the bracketed [id] of a ledger claim this page DIRECTLY contradicts, else null. Return at most ${maxClaimsPerSource} claims. No prose.`;
+    const user = [
+      `Research goal: ${ctx.goal}`,
+      `Page title: ${source.title ?? "(none)"}`,
+      ledgerLines ? `Claims already on the ledger:
+${ledgerLines}` : "Ledger is empty.",
+      `Page excerpt:
+${excerpt}`,
+      'Key claims as JSON [{"claim": "...", "contradicts": "[id]"|null}]:'
+    ].join("\n\n");
+    let raw = "";
+    try {
+      raw = await router.chat(
+        [
+          { role: "system", content: system },
+          { role: "user", content: user }
+        ],
+        1200
+      );
+    } catch {
+      return [];
+    }
+    return parseExtractedClaims(raw, ledger);
+  }
+  function deterministicClaims(source) {
+    const sentences = source.text.split(/(?<=[.!?])\s+/).map((sentence) => sentence.trim()).filter((sentence) => contentWordSet(sentence).size >= 3);
+    return sentences.slice(0, maxClaimsPerSource).map((text) => ({ text }));
+  }
+  function synthesizeDeepQuestions(ledger, round2) {
+    if (ledger.length === 0) return [];
+    const out = [];
+    for (const claim of ledger) {
+      for (const otherId of claim.contradicts) {
+        const other = ledger.find((entry) => entry.id === otherId);
+        if (!other || other.id < claim.id) continue;
+        out.push(
+          makeQuestion(
+            "contradiction",
+            `Does any independent source resolve the contradiction between "${truncate(claim.text)}" and "${truncate(other.text)}"? Find evidence that confirms or refutes one of them.`,
+            [claim.id, other.id],
+            round2
+          )
+        );
+      }
+    }
+    for (const claim of ledger.filter((entry) => !entry.contested)) {
+      if (claim.supportingHosts.size < minIndependentSources) {
+        out.push(
+          makeQuestion(
+            "gap",
+            `Only one independent source supports "${truncate(claim.text)}". What specific corroborating result, dataset, or independent measurement is missing to confirm it?`,
+            [claim.id],
+            round2
+          )
+        );
+      }
+    }
+    for (const claim of [...ledger].sort((a, b) => b.supportingHosts.size - a.supportingHosts.size).slice(0, 2)) {
+      out.push(
+        makeQuestion(
+          "mechanism",
+          `Under what precise condition does "${truncate(claim.text)}" stop holding? Find a source that states the mechanism, limit, or failure mode.`,
+          [claim.id],
+          round2
+        )
+      );
+    }
+    const ranked = [...ledger].sort((a, b) => b.supportingHosts.size - a.supportingHosts.size);
+    if (ranked.length >= 2 && ranked[0] && ranked[1]) {
+      out.push(
+        makeQuestion(
+          "comparative",
+          `How does the tradeoff in "${truncate(ranked[0].text)}" differ from "${truncate(ranked[1].text)}"? Find a source that compares them directly.`,
+          [ranked[0].id, ranked[1].id],
+          round2
+        )
+      );
+    }
+    const priority = {
+      contradiction: 0,
+      gap: 1,
+      mechanism: 2,
+      comparative: 3
+    };
+    return out.sort((a, b) => priority[a.kind] - priority[b.kind]);
+  }
+}
+function makeQuestion(kind, text, claimIds, raisedRound) {
+  return {
+    kind,
+    text,
+    id: `q_${sha256(`${kind}:${text}`).slice(0, 16)}`,
+    claimIds,
+    addressed: false,
+    raisedRound
+  };
+}
+function claimId(text) {
+  return `c_${sha256(normalizeText(text)).slice(0, 16)}`;
+}
+function hostOf2(uri) {
+  try {
+    return new URL(uri.trim()).hostname.toLowerCase().replace(/^www\./, "");
+  } catch {
+    return canonicalizeUrl(uri);
+  }
+}
+function normalizeText(text) {
+  return text.toLowerCase().replace(/[^\p{L}\p{N}\s]+/gu, " ").replace(/\s+/g, " ").trim();
+}
+var stopwords3 = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "and",
+  "or",
+  "but",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "as",
+  "by",
+  "at",
+  "from",
+  "that",
+  "this",
+  "these",
+  "those",
+  "it",
+  "its",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "has",
+  "have",
+  "had",
+  "can",
+  "will",
+  "would",
+  "should",
+  "may",
+  "might",
+  "not",
+  "no",
+  "than",
+  "then",
+  "over",
+  "under",
+  "about",
+  "into",
+  "their",
+  "they",
+  "them"
+]);
+function contentWordSet(text) {
+  return new Set(
+    normalizeText(text).split(" ").filter((word) => word.length >= 3 && !stopwords3.has(word))
+  );
+}
+function overlapFraction(a, b) {
+  if (a.size === 0) return 0;
+  let hits = 0;
+  for (const word of a) if (b.has(word)) hits += 1;
+  return hits / a.size;
+}
+function truncate(text, max = 140) {
+  const t = text.trim().replace(/\s+/g, " ");
+  return t.length <= max ? t : `${t.slice(0, max - 1)}\u2026`;
+}
+function parseExtractedClaims(raw, ledger) {
+  const text = raw.trim();
+  if (!text) return [];
+  const arrayMatch = text.match(/\[[\s\S]*\]/);
+  if (!arrayMatch) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(arrayMatch[0]);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  const ledgerIds = new Set(ledger.map((claim) => claim.id));
+  const out = [];
+  for (const item of parsed) {
+    if (!item || typeof item !== "object") continue;
+    const record = item;
+    if (typeof record.claim !== "string" || !record.claim.trim()) continue;
+    const contradictsId = extractBracketId(record.contradicts);
+    out.push({
+      text: record.claim.trim(),
+      contradictsExistingId: contradictsId && ledgerIds.has(contradictsId) ? contradictsId : void 0
+    });
+  }
+  return out;
+}
+function extractBracketId(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.toLowerCase() === "null") return void 0;
+  const bracket = trimmed.match(/\[([^\]]+)\]/);
+  const id = (bracket?.[1] ?? trimmed).trim();
+  return id.startsWith("c_") ? id : void 0;
+}
+function buildSteerText(gaps, deepQuestions, invalidationTargets, minIndependentSources) {
+  const lines = [];
+  lines.push(
+    "Do NOT just add more sources. Go DEEPER and VALIDATE. Address the following before adding breadth:"
+  );
+  if (deepQuestions.length > 0) {
+    lines.push("", "Deep sub-questions to answer this round:");
+    for (const question of deepQuestions) {
+      lines.push(`- (${question.kind}) ${question.text}`);
+    }
+  }
+  if (invalidationTargets.length > 0) {
+    lines.push(
+      "",
+      `Claims needing corroboration or refutation (each must reach >= ${minIndependentSources} INDEPENDENT sources, or be shown contested):`
+    );
+    for (const claim of invalidationTargets) {
+      const reason = claim.contradicts.size > 0 ? "CONTRADICTED by another source \u2014 find evidence that resolves it" : `only ${claim.supportingHosts.size} independent source \u2014 find a SECOND, independent corroborating source`;
+      lines.push(`- "${truncate(claim.text)}" \u2014 ${reason}`);
+    }
+  }
+  if (gaps.length > 0) {
+    lines.push("", "Readiness gaps still open:");
+    for (const gap of gaps) {
+      lines.push(`- (${gap.blocking ? "blocking" : "soft"}) ${gap.description} [${gap.id}]`);
+    }
+  }
+  return lines.join("\n");
+}
 export {
   AgentMemoryHitSchema,
   AgentMemoryKindSchema,
   AgentMemoryScopeSchema,
   AgentMemoryWriteInputSchema,
   FileSystemKbStore,
+  INDUSTRY_MEMORY_BENCHMARKS,
+  INDUSTRY_RAG_BENCHMARKS,
   IRS_DIMENSION_HINTS,
   KnowledgeBaseCandidateSchema,
   KnowledgeEventSchema,
@@ -1931,7 +4682,6 @@ export {
   MemoryKbStore,
   POLITE_USER_AGENT,
   READINESS_SPEC_DEFAULTS,
-  RESEARCH_SUPERVISOR_SYSTEM_PROMPT,
   RouterError,
   SCAFFOLD_PAGE_BASENAMES,
   SourceAnchorSchema,
@@ -1942,9 +4692,19 @@ export {
   addSourceText,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
+  applyRetrievalHoldout,
+  applySessionStickyRetrievalHoldout,
   buildEvalKnowledgeBundle,
+  buildFirstPartyMemoryLifecycleBenchmarkCases,
+  buildIndustryMemoryBenchmarkSmokeCases,
+  buildIndustryRagBenchmarkSmokeCases,
+  buildKnowledgeBenchmarkScenarios,
   buildKnowledgeGraph,
   buildKnowledgeIndex,
+  buildRetrievalBenchmarkCasesFromQrels,
+  buildRetrievalEvalDispatch,
+  buildRetrievalParameterCandidates,
+  calibrateRagAnswerJudge,
   canonicalizeUrl,
   chunkMarkdown,
   citedClaimKey,
@@ -1953,14 +4713,20 @@ export {
   createAdaptiveResearchDriver,
   createClaimDecorator,
   createClaimGroundingVerifier,
+  createCollectionResearchDriver,
   createCornellLiiSource,
   createD1FreshnessStoreStub,
   createFileSystemFreshnessStore,
+  createInMemoryBenchmarkAdapter,
   createIrsPublicationsSource,
   createKnowledgeControlLoopAdapter,
   createKnowledgeEvent,
   createLocalDiscoveryDispatcher,
+  createMemoryAdapterBenchmarkResponder,
   createNeo4jAgentMemoryAdapter,
+  createNoopMemoryBenchmarkAdapter,
+  createRagAnswerQualityHook,
+  createResearchDrivingDriver,
   createStateSosSource,
   createTangleRouterClient,
   createVerifyingResearchDriver,
@@ -1968,39 +4734,79 @@ export {
   defaultGetMemoryContext,
   defineReadinessSpec,
   detectChanges,
+  deterministicRng,
+  diagnoseRagAnswerFailure,
+  emitRetrievalHoldoutBypass,
+  evaluateKnowledgeBaseReadiness,
   explainKnowledgeTarget,
   extractLinks,
   extractWikilinks,
   firstMatch,
   formatFrontmatter,
+  gradeCompanyAgainstText,
+  gradeFactAgainstText,
   groundClaimInText,
+  hashKnowledgeBase,
   htmlToText,
+  improveKnowledgeBase,
   initKnowledgeBase,
   innerHtmlById,
   inspectKnowledgeIndex,
+  investmentThesisSet,
+  isKnowledgeMemoryBenchmarkCase,
   isSafeKnowledgePath,
   isScaffoldPath,
-  knowledgeReadinessDeliverable,
+  kbIndexToText,
+  knowledgeBenchmarkJudge,
+  knowledgeImprovementRunDir,
+  knowledgeImprovementRunId,
   knowledgeReleaseReport,
   layoutFor,
+  lensDistribution,
   lintKnowledgeIndex,
+  loadKnowledgeImprovementState,
   loadKnowledgePages,
   loadSourceRegistry,
   looksLikeBlockPage,
+  materialFactsSurfaced,
+  materialFactsSurfacedInText,
   mediaTypeFor,
   memoryHitToSourceRecord,
   memoryWriteResultToSourceRecord,
+  normalizeExternalRagScores,
   normalizeLinkTarget,
   parseFrontmatter,
+  parseKnowledgeBenchmarkJsonl,
+  parseKnowledgeBenchmarkQrels,
   parseKnowledgeWriteBlocks,
   politeFetch,
   proposeFromFinding,
   proposeFromFindings,
+  ragAnswerQualityJudge,
   reciprocalRankFusion,
+  renderKnowledgeBenchmarkReportMarkdown,
   renderMemoryContext,
+  resetRetrievalHoldoutRegistry,
+  respondToIndustryMemoryBenchmarkSmokeCase,
+  respondToIndustryRagBenchmarkSmokeCase,
+  retrievalConfigFromSurface,
+  retrievalConfigSurface,
+  retrievalHoldoutConfigHash,
+  retrievalParameterSweepProposer,
+  retrievalRecallJudge,
+  runInvestmentThesisTask,
+  runKnowledgeBenchmarkSuite,
   runKnowledgeResearchLoop,
-  runResearchSupervisor,
+  runMemoryAdapterBenchmark,
+  runRagKnowledgeImprovementLoop,
+  runRetrievalImprovementLoop,
   runTwoAgentResearchLoop,
+  runVerifiedResearchLoop,
+  scoreKnowledgeBaseIndex,
+  scoreKnowledgeBenchmarkArtifact,
+  scoreMemoryBenchmarkArtifact,
+  scoreRagAnswerArtifact,
+  scoreRetrievalArtifact,
   searchKnowledge,
   sha256,
   slugify,
@@ -2008,8 +4814,16 @@ export {
   sourceRegistryPath,
   stableId,
   stripFrontmatter,
+  summarizeKnowledgeBenchmarkCampaign,
   textSourceAdapter,
+  thesisReadinessSpecs,
+  toDeepEvalTestCases,
+  toOffPolicyTrajectory,
+  toRagCheckerRecords,
+  toRagasEvaluationRows,
+  toTruLensRecords,
   tokenizeQuery,
+  totalMaterialFacts,
   triageSource,
   validateKnowledgeIndex,
   withCitedClaim,