@tangle-network/agent-knowledge 1.10.0 → 1.11.0

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as SourceRegistry, f as KnowledgeEvent, g as KnowledgeEventType, h as KnowledgePage, b as KnowledgeGraph, i as KnowledgeLintFinding, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as KnowledgeWriteParseResult } from './types-C17sAROL.js';
 export { C as ClaimRef, n as KnowledgeBaseCandidate, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-C17sAROL.js';
-import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard } from '@tangle-network/agent-eval';
+import { R as RunRetrievalImprovementLoopResult, a as RunRetrievalImprovementLoopOptions, b as RetrievalConfig } from './index-Cj5jRXOz.js';
+export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, c as BuildRetrievalEvalDispatchOptions, d as BuildRetrievalParameterCandidatesOptions, I as INDUSTRY_MEMORY_BENCHMARKS, e as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, f as KnowledgeAnswerBenchmarkTaskKind, g as KnowledgeBenchmarkArtifact, h as KnowledgeBenchmarkCase, i as KnowledgeBenchmarkCaseBase, j as KnowledgeBenchmarkDistribution, k as KnowledgeBenchmarkEvaluation, l as KnowledgeBenchmarkFamily, m as KnowledgeBenchmarkReport, n as KnowledgeBenchmarkResponder, o as KnowledgeBenchmarkScenario, p as KnowledgeBenchmarkSliceSummary, q as KnowledgeBenchmarkSource, r as KnowledgeBenchmarkSpec, s as KnowledgeBenchmarkSplit, t as KnowledgeBenchmarkTaskKind, u as KnowledgeClaimMatcher, v as KnowledgeMemoryBenchmarkCase, w as KnowledgeMemoryBenchmarkTaskKind, x as KnowledgeMemoryEvent, y as KnowledgeMemoryFactMatcher, z as KnowledgeRetrievalBenchmarkCase, A as KnowledgeRetrievalBenchmarkQrel, C as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, D as MemoryAdapterBenchmarkRankingRow, E as RetrievalEvalArtifact, F as RetrievalEvalRetriever, G as RetrievalEvalRetrieverInput, H as RetrievalEvalRetrieverResult, J as RetrievalEvalScenario, L as RetrievalGoldTarget, N as RetrievalMetricSummary, O as RetrievalMetricWeights, P as RetrievalParameterSearchSpace, Q as RetrievalParameterSweepProposerOptions, S as RetrievalRecallJudgeOptions, T as RetrievedKnowledgeHit, U as RetrievedSourceSpan, V as RunKnowledgeBenchmarkSuiteOptions, W as RunKnowledgeBenchmarkSuiteResult, X as RunMemoryAdapterBenchmarkOptions, Y as RunMemoryAdapterBenchmarkResult, Z as buildFirstPartyMemoryLifecycleBenchmarkCases, _ as buildIndustryMemoryBenchmarkSmokeCases, $ as buildIndustryRagBenchmarkSmokeCases, a0 as buildKnowledgeBenchmarkScenarios, a1 as buildRetrievalBenchmarkCasesFromQrels, a2 as buildRetrievalEvalDispatch, a3 as buildRetrievalParameterCandidates, a4 as createInMemoryBenchmarkAdapter, a5 as createMemoryAdapterBenchmarkResponder, a6 as createNoopMemoryBenchmarkAdapter, a7 as isKnowledgeMemoryBenchmarkCase, a8 as knowledgeBenchmarkJudge, a9 as parseKnowledgeBenchmarkJsonl, aa as parseKnowledgeBenchmarkQrels, ab as renderKnowledgeBenchmarkReportMarkdown, ac as respondToIndustryMemoryBenchmarkSmokeCase, ad as respondToIndustryRagBenchmarkSmokeCase, ae as retrievalConfigFromSurface, af as retrievalConfigSurface, ag as retrievalParameterSweepProposer, ah as retrievalRecallJudge, ai as runKnowledgeBenchmarkSuite, aj as runMemoryAdapterBenchmark, ak as runRetrievalImprovementLoop, al as scoreKnowledgeBenchmarkArtifact, am as scoreMemoryBenchmarkArtifact, an as scoreRetrievalArtifact, ao as summarizeKnowledgeBenchmarkCampaign } from './index-Cj5jRXOz.js';
 import { KnowledgeFragment } from './sources/index.js';
 export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from './sources/index.js';
-export { AgentMemoryAdapter, AgentMemoryContext, AgentMemoryHit, AgentMemoryHitSchema, AgentMemoryKind, AgentMemoryKindSchema, AgentMemoryScope, AgentMemoryScopeSchema, AgentMemorySearchOptions, AgentMemoryWriteInput, AgentMemoryWriteInputSchema, AgentMemoryWriteResult, Neo4jAgentMemoryAdapterOptions, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, memoryHitToSourceRecord, memoryWriteResultToSourceRecord, renderMemoryContext } from './memory/index.js';
-import { Budget, ExecutorConfig, SuperviseOptions, DeliverableSpec, SupervisedResult } from '@tangle-network/agent-runtime/loops';
+import { JsonValue, Scenario, JudgeConfig } from '@tangle-network/agent-eval/campaign';
+export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, Neo4jAgentMemoryAdapterOptions, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, memoryHitToSourceRecord, memoryWriteResultToSourceRecord, renderMemoryContext } from './memory/index.js';
+export { A as AgentMemoryAdapter, b as AgentMemoryContext, c as AgentMemoryHit, d as AgentMemoryKind, a as AgentMemoryScope, e as AgentMemorySearchOptions, f as AgentMemoryWriteInput, g as AgentMemoryWriteResult, R as RetrievalHoldoutBypassReason, h as RetrievalHoldoutCallContext, i as RetrievalHoldoutConfig, j as RetrievalHoldoutEligibleItem, k as RetrievalHoldoutEvent, l as RetrievalHoldoutOffPolicyOptions, m as RetrievalHoldoutOffPolicyResult, n as RetrievalHoldoutResult, o as RetrievalHoldoutSessionState, p as RetrievalHoldoutSessionSummary, q as applyRetrievalHoldout, r as applySessionStickyRetrievalHoldout, s as deterministicRng, t as emitRetrievalHoldoutBypass, u as resetRetrievalHoldoutRegistry, v as retrievalHoldoutConfigHash, w as toOffPolicyTrajectory } from './types-CjqPcTTK.js';
 import { z } from 'zod';
+import '@tangle-network/agent-eval/rl';
 
 interface SourceAdapterInput {
     uri: string;
@@ -248,7 +252,7 @@ type SourceVerdict = {
 };
 /** The worker: primary research targeting the round's gaps. */
 type ResearchWorker = (ctx: WorkerResearchContext) => Promise<ResearchContribution> | ResearchContribution;
-interface TwoAgentResearchLoopOptions {
+interface VerifiedResearchLoopOptions {
     root: string;
     goal: string;
     worker: ResearchWorker;
@@ -268,9 +272,9 @@ interface TwoAgentResearchLoopOptions {
     readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
     sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
     signal?: AbortSignal;
-    onRound?: (round: TwoAgentResearchRound) => Promise<void> | void;
+    onRound?: (round: VerifiedResearchRound) => Promise<void> | void;
 }
-interface TwoAgentResearchRound {
+interface VerifiedResearchRound {
     round: number;
     /** Gaps reported at the START of the round (what the worker targeted). */
     gaps: KnowledgeGap[];
@@ -291,14 +295,14 @@ interface TwoAgentResearchRound {
         driver?: string;
     };
 }
-interface TwoAgentResearchLoopResult {
+interface VerifiedResearchLoopResult {
     root: string;
     goal: string;
     rounds: number;
     ready: boolean;
     index: KnowledgeIndex;
     readiness?: EvalKnowledgeBundleBuildResult;
-    steps: TwoAgentResearchRound[];
+    steps: VerifiedResearchRound[];
 }
 /**
  * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
@@ -322,16 +326,24 @@ interface TwoAgentResearchLoopResult {
  * `applyKnowledgeWriteBlocks`, `buildEvalKnowledgeBundle` (the readiness gate),
  * and `searchKnowledge` — and reinvents none of them.
  */
-declare function runTwoAgentResearchLoop(options: TwoAgentResearchLoopOptions): Promise<TwoAgentResearchLoopResult>;
+declare function runVerifiedResearchLoop(options: VerifiedResearchLoopOptions): Promise<VerifiedResearchLoopResult>;
 /**
  * Helper for verifiers: does the candidate source's text/title overlap any page
  * the readiness search returns for a gap query? A cheap relevance heuristic the
  * driver can compose into `verifySource` (real verifiers can do more).
  */
 declare function sourceMatchesGaps(source: ResearchSourceProposal, index: KnowledgeIndex, gaps: KnowledgeGap[]): KnowledgeSearchResult[];
+/** @deprecated Renamed to {@link runVerifiedResearchLoop}. */
+declare const runTwoAgentResearchLoop: typeof runVerifiedResearchLoop;
+/** @deprecated Renamed to {@link VerifiedResearchLoopOptions}. */
+type TwoAgentResearchLoopOptions = VerifiedResearchLoopOptions;
+/** @deprecated Renamed to {@link VerifiedResearchLoopResult}. */
+type TwoAgentResearchLoopResult = VerifiedResearchLoopResult;
+/** @deprecated Renamed to {@link VerifiedResearchRound}. */
+type TwoAgentResearchRound = VerifiedResearchRound;
 
 /**
- * Real web-research worker + verifying driver for `runTwoAgentResearchLoop`.
+ * Real web-research worker + verifying driver for `runVerifiedResearchLoop`.
  *
  * This is the GENERAL, any-topic implementation behind the two-agent research
  * loop's live arm. Given the open knowledge gaps the readiness gate surfaces,
@@ -407,6 +419,16 @@ interface TangleRouterOptions {
     model?: string;
     /** Optional preferred search provider (exa | you | perplexity | …). */
     searchProvider?: string;
+    /**
+     * Retries on a TRANSIENT upstream status (502/503/504/429) with exponential
+     * backoff. Default 4. A 4xx that isn't 429, and a 401, are NOT retried — those
+     * are not transient. After the budget is exhausted the call still fails loud
+     * with the original `RouterError`, so the fail-closed contract holds; this only
+     * stops a single upstream-capacity blip from voiding a whole multi-topic run.
+     */
+    maxRetries?: number;
+    /** Base backoff in ms (doubled each retry, ±25% jitter). Default 1500. */
+    retryBaseMs?: number;
     signal?: AbortSignal;
 }
 /** A small error so a failed router call fails loud rather than returning junk. */
@@ -466,7 +488,7 @@ interface VerifyingDriverOptions {
 declare function createVerifyingResearchDriver(options?: VerifyingDriverOptions): ResearchDriver;
 
 /**
- * Adaptive verifier mode for `runTwoAgentResearchLoop`.
+ * Adaptive verifier mode for `runVerifiedResearchLoop`.
  *
  * The cost/quality A/B (`docs/results/cost-quality.md`) found the LLM relevance
  * verifier's cleanliness win is dominated by DE-DUPLICATION — which a
@@ -715,7 +737,7 @@ declare function stripFrontmatter(content: string): {
 };
 
 /**
- * Claim-grounding mode for `runTwoAgentResearchLoop`.
+ * Claim-grounding mode for `runVerifiedResearchLoop`.
  *
  * The two-agent loop's existing verifier judges a source's on-topic RELEVANCE
  * (is this page about the goal?). On the topic sets we have measured, its
@@ -828,7 +850,7 @@ interface ClaimGroundingDriverOptions extends GroundClaimOptions {
  * composes a relevance verifier after grounding passes.
  *
  * The returned function matches `ResearchDriver['verifySource']`, so it drops
- * straight into `runTwoAgentResearchLoop` as `{ verifySource: createClaimGroundingVerifier(...) }`.
+ * straight into `runVerifiedResearchLoop` as `{ verifySource: createClaimGroundingVerifier(...) }`.
  */
 declare function createClaimGroundingVerifier(options?: ClaimGroundingDriverOptions): (source: ResearchSourceProposal, ctx: SourceVerificationContext) => Promise<SourceVerdict>;
 interface WorkerClaimDecorationOptions {
@@ -852,6 +874,41 @@ interface WorkerClaimDecorationOptions {
  */
 declare function createClaimDecorator(options?: WorkerClaimDecorationOptions): (source: ResearchSourceProposal, goal: string) => Promise<ResearchSourceProposal>;
 
+/**
+ * The SINGLE-AGENT COLLECTION driver — the blind-collection baseline (Arm A).
+ *
+ * This is the honest null the depth A/B is measured against. The other drivers
+ * spend extra inference to do something differentiated:
+ *   - `createVerifyingResearchDriver` runs an LLM gate per source (Arm B),
+ *   - `createResearchDrivingDriver` extracts claims, tracks corroboration, and
+ *     synthesizes deep follow-up questions to drive depth (Arm C).
+ *
+ * This driver does NONE of that. It is a pass-through: it accepts every source
+ * the worker proposes and contributes no research, no gating, and no steering of
+ * its own. The loop still dedups exact-uri duplicates before calling
+ * `verifySource` (that is the loop's job, not the driver's), and the default
+ * `foldGaps` (a plain bulleted list of the still-open readiness gaps) still folds
+ * the gaps into the worker's next prompt — so the worker keeps researching, but
+ * NOTHING intelligent sits between the worker and the knowledge base.
+ *
+ * In other words: ONE agent (the worker) collects sources round after round, and
+ * the "driver" is an inert rubber stamp. That is exactly what "single-agent
+ * collection" means — the topology with zero coordinator intelligence — so its
+ * material-facts score is the floor every other arm must beat to justify its
+ * extra inference cost.
+ *
+ * It adds NO router calls of its own: `verifySource` is a synchronous accept and
+ * `foldGaps` is omitted so the loop uses its built-in gap list. So Arm A's cost
+ * is the worker's cost alone — the cleanest possible blind-collection baseline.
+ */
+
+/**
+ * Build the single-agent collection driver. Accepts every source; never gates,
+ * never researches, never steers beyond the loop's default open-gap list. The
+ * worker is the only agent that thinks.
+ */
+declare function createCollectionResearchDriver(): ResearchDriver;
+
 interface DiscoveryTask {
     id: string;
     goal: string;
@@ -1065,6 +1122,740 @@ interface KnowledgeExplanation {
 }
 declare function explainKnowledgeTarget(index: KnowledgeIndex, target: string): KnowledgeExplanation;
 
+/**
+ * HELD-OUT INVESTMENT-RESEARCH EVAL SET.
+ *
+ * The point of this file is the same FIREWALL the deep-question exam uses
+ * (`tests/loops/held-out-exam.ts`): the material facts and their checkable
+ * fragments are NEVER shown to a research loop. A loop is told only the company
+ * + ticker + a research-as-of CUTOFF date, and asked to write an investment
+ * thesis. AFTER it finishes, we grade the thesis it produced against THESE
+ * facts — facts it never saw — so a high score is thesis QUALITY (it surfaced
+ * the buried, material, non-obvious drivers) and not teaching-to-the-test.
+ *
+ * Each fact is a DEPTH fact by construction: a single ticker / company-name web
+ * search does NOT surface it. They are the things buried in the filings or
+ * knowable from then-available primary sources that a thorough analyst flags and
+ * a one-shot search misses — customer/revenue/deposit concentration, a debt
+ * maturity wall, a margin-trend reversal, a governance / related-party item, a
+ * specific competitive or regulatory risk, an off-balance-sheet loss.
+ *
+ * THREE HARD RULES, enforced by how the data was gathered (see
+ * docs/eval/investment-material-facts.md for the per-item provenance + the
+ * curation-bias disclosure):
+ *
+ *   1. SPECIFIC + CHECKABLE. Each fact carries `expected` keyword groups — the
+ *      specific number / name / phrase — so a deterministic, model-free
+ *      substring grader (`gradeFactAgainstText`) can score "did the thesis
+ *      surface it". $0, reproducible, and it cannot leak the answer key into a
+ *      model the loop could observe.
+ *
+ *   2. DERIVED FROM REAL FETCHED EVIDENCE. Every fact records the primary source
+ *      it came from (`sourceUrl`, an SEC EDGAR 10-K) and the literal `evidence`
+ *      value read out of that document. Nothing here is invented; an item that
+ *      could not be independently sourced was DROPPED, not guessed (the drop log
+ *      is in the doc).
+ *
+ *   3. KNOWABLE AT THE CUTOFF. Every fact was disclosed in, or computable from, a
+ *      document available on or before the company's `cutoff` date. Post-cutoff
+ *      hindsight (the eventual bankruptcy / collapse) is NOT a checklist item —
+ *      it is recorded separately as `knownOutcome`, purely for the reader, and is
+ *      never graded.
+ *
+ * Grading mirrors the deep-question exam exactly: a fact is SURFACED when the
+ * thesis text contains at least `minGroups` of its expected groups; a group is
+ * satisfied when ANY of its `anyOf` fragments appears (case-insensitive
+ * substring), so a faithful thesis phrased in its own words still grades as a
+ * hit. `anyOf` groups model synonyms; the load-bearing tokens are the specific
+ * numbers / names.
+ */
+/** A required answer component: satisfied when any synonym fragment is present. */
+interface ExpectedGroup {
+    /** Human label for the component (for the doc / audit). */
+    label: string;
+    /** Case-insensitive substring fragments; any one present satisfies the group. */
+    anyOf: string[];
+}
+/** Lens the fact belongs to — so a set can be checked for category coverage. */
+type MaterialFactLens = 'concentration' | 'leverage' | 'margin-trend' | 'liquidity' | 'capital-return' | 'governance' | 'off-balance-sheet' | 'regulatory';
+/** One held-out material fact with a checkable expected answer + its provenance. */
+interface MaterialFact {
+    /** Stable id, `ticker/fN`. */
+    id: string;
+    /** Which analyst lens this fact exercises. For coverage + the doc. */
+    lens: MaterialFactLens;
+    /**
+     * The material fact, in plain words — for the doc/audit. NEVER shown to a loop.
+     * This is the thing a thorough analyst would flag and a ticker search misses.
+     */
+    fact: string;
+    /**
+     * The checkable answer as required keyword GROUPS. The thesis text must contain
+     * at least `minGroups` of these groups (default: all). A group is satisfied
+     * when ANY of its `anyOf` fragments appears (case-insensitive substring).
+     */
+    expected: ExpectedGroup[];
+    /**
+     * Minimum number of `expected` groups the thesis must contain to count the
+     * fact SURFACED. Default = all groups (the strict bar). Lowered (and documented
+     * inline) only when the fact is genuinely satisfiable by a subset.
+     */
+    minGroups?: number;
+    /**
+     * PROVENANCE. The primary source URL this fact was read from — an SEC EDGAR
+     * 10-K primary document, fetched live during curation.
+     */
+    sourceUrl: string;
+    /**
+     * The literal value / phrase read out of `sourceUrl` that grounds the fact.
+     * This is the "cite the actual filing + the value" requirement — verbatim or
+     * near-verbatim from the filing, with the figure.
+     */
+    evidence: string;
+}
+/** A company + the cutoff a loop researches as-of + its held-out material facts. */
+interface CompanyEvalCase {
+    /** Ticker as of the cutoff. */
+    ticker: string;
+    /** Legal name as of the cutoff (what the loop is told to research). */
+    company: string;
+    /** SEC Central Index Key (CIK), zero-stripped — the EDGAR filer id. */
+    cik: string;
+    /**
+     * Research-as-of date (ISO). The loop must reason as if it is this date; every
+     * `evidence` value was knowable on or before it. >= 18 months before this set
+     * was curated, so the outcome is known but is NOT a checklist item.
+     */
+    cutoff: string;
+    /** Sector, for coverage / the curation-bias disclosure. */
+    sector: string;
+    /**
+     * The known POST-cutoff outcome — recorded for the reader ONLY, never graded.
+     * Keeping it out of `facts` is what makes the set hindsight-free.
+     */
+    knownOutcome: string;
+    /** The held-out material facts for this company. */
+    facts: MaterialFact[];
+}
+/**
+ * The eval set. 5 public companies, 5-8 held-out material facts each, every fact
+ * grounded in a primary SEC EDGAR 10-K filed on or before the cutoff.
+ *
+ * CURATION-BIAS DISCLOSURE (full version in the doc): all five are companies
+ * whose buried risks later materialized, because that is where the material-vs-
+ * surface distinction is sharpest AND where the figures are easy to verify after
+ * the fact. This biases the set toward downside risks (two of the eight lenses,
+ * concentration + leverage, dominate) and toward distressed names. A production
+ * eval would balance these with companies whose buried facts were POSITIVE
+ * drivers and with survivors. This set is honest about that and reports the lens
+ * distribution so the bias is measurable, not hidden.
+ */
+declare const investmentThesisSet: CompanyEvalCase[];
+/**
+ * Grade ONE material fact against an investment thesis's full text. Returns
+ * whether the thesis SURFACED it plus which expected groups were found. The
+ * check is a deterministic case-insensitive substring scan — $0, model-free,
+ * reproducible — so the eval never leaks into a model the loop could observe.
+ */
+declare function gradeFactAgainstText(fact: MaterialFact, thesisText: string): {
+    surfaced: boolean;
+    groupsFound: number;
+    groupsTotal: number;
+    foundLabels: string[];
+};
+/** Grade a whole company's thesis text: how many of its held-out facts it surfaces. */
+declare function gradeCompanyAgainstText(company: CompanyEvalCase, thesisText: string): {
+    surfaced: number;
+    total: number;
+    perFact: ReturnType<typeof gradeFactAgainstText>[];
+};
+/** Total held-out facts across the set (the denominator the doc reports). */
+declare function totalMaterialFacts(set?: CompanyEvalCase[]): number;
+/** Count facts per lens across the set — used to report (and bound) curation bias. */
+declare function lensDistribution(set?: CompanyEvalCase[]): Record<MaterialFactLens, number>;
+
+/**
+ * The INVESTMENT-THESIS research task.
+ *
+ * Given `{ company, ticker, cik, cutoff }`, drive the SAME two-agent research
+ * loop the ML deep-question A/B uses (`runVerifiedResearchLoop` + the real web
+ * worker) to research the company AS OF the cutoff — web + SEC EDGAR, both public
+ * — and produce an investment-thesis PAGE in the knowledge base: a judgment, the
+ * drivers, and the risks, grounded in what it fetched.
+ *
+ * This file builds NOTHING new for the loop: it composes the existing worker +
+ * driver + loop, supplies the readiness specs that steer the worker toward the
+ * filing-level evidence (the analyst lenses), then writes a synthesis thesis page
+ * the metric (`materialFactsSurfaced`) grades against the HELD-OUT checklist.
+ *
+ * THE FIREWALL: the task is told ONLY company + ticker + cutoff (+ the generic
+ * analyst-lens readiness specs every company gets). It is NEVER shown the
+ * checklist. The checklist is read only afterward, by the metric. So a high score
+ * is research depth, not teaching-to-the-test.
+ */
+
+/** The minimal brief a thesis run is given — the firewall boundary. */
+interface ThesisTaskInput {
+    /** Legal name as of the cutoff — what the loop researches. */
+    company: string;
+    /** Ticker as of the cutoff. */
+    ticker: string;
+    /** SEC Central Index Key (CIK), zero-stripped — the EDGAR filer id. */
+    cik: string;
+    /** Research-as-of date (ISO). The loop must reason as if it is this date. */
+    cutoff: string;
+    /** Sector, for the readiness query context (NOT a checklist hint). */
+    sector?: string;
+}
+/**
+ * The generic analyst-lens readiness specs every company gets. They are the ONLY
+ * thing the loop is told about WHAT to look for, and they name the LENSES a
+ * thorough analyst checks (balance-sheet risk, concentration, leverage, margins,
+ * liquidity, governance, regulatory) and where they live (the latest SEC 10-K) —
+ * NOT the answers. They steer the worker's web/EDGAR search toward the filing,
+ * not toward the held-out facts (which the loop never sees).
+ *
+ * `minSources` is set above 1 so the readiness gate stays UNMET after a single
+ * fetch and the loop runs multiple rounds — the depth-driving driver needs >1
+ * round to steer, exactly as the ML-exam multi-round probe established.
+ */
+declare function thesisReadinessSpecs(input: ThesisTaskInput): KnowledgeReadinessSpec[];
+interface ThesisRunOptions {
+    /** The KB root the loop writes into. */
+    root: string;
+    /** Shared router client (web search + chat). Defaults to env creds. */
+    router: RouterClient;
+    /** The driver — verify/dedup or research-driving. The loop's coordinator. */
+    driver: ResearchDriver;
+    /** Round budget. Default 3 (the depth-driving driver needs >1). */
+    maxRounds?: number;
+    /** Worker tuning forwarded to `createWebResearchWorker`. */
+    workerOptions?: Omit<WebResearchWorkerOptions, 'router'>;
+    /** Max tokens for the synthesis pass. Default 1600 (above glm-5.2's reasoning floor). */
+    synthesisMaxTokens?: number;
+    signal?: AbortSignal;
+}
+interface ThesisRunResult {
+    loop: VerifiedResearchLoopResult;
+    /** The synthesized thesis text. */
+    thesis: string;
+    /** Path of the thesis page written into the KB. */
+    thesisPath: string;
+}
+/**
+ * Run the full thesis task: drive the two-agent loop to research the company AS
+ * OF the cutoff, then synthesize + write the thesis page. Returns the loop result
+ * + the thesis text + the page path. The caller grades the KB with
+ * `materialFactsSurfaced(root, checklist)` — the checklist is never passed here.
+ */
+declare function runInvestmentThesisTask(input: ThesisTaskInput, options: ThesisRunOptions): Promise<ThesisRunResult>;
+
+interface ApplyWriteBlocksResult {
+    written: string[];
+    warnings: string[];
+}
+declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
+declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
+
+interface ValidateKnowledgeOptions {
+    strict?: boolean;
+}
+interface ValidateKnowledgeResult {
+    ok: boolean;
+    findings: KnowledgeLintFinding[];
+}
+declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+
+interface KnowledgeResearchLoopContext {
+    root: string;
+    goal: string;
+    iteration: number;
+    index: KnowledgeIndex;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    previousSteps: KnowledgeResearchLoopStep[];
+    signal?: AbortSignal;
+}
+interface KnowledgeResearchLoopDecision {
+    /**
+     * Free-form notes from the researcher. Keep this human-readable; products can
+     * store it as the research transcript.
+     */
+    notes?: string;
+    /**
+     * Local files to register as immutable sources before applying proposals.
+     */
+    sourcePaths?: string[];
+    /**
+     * Textual source artifacts discovered by an agent, browser worker, connector,
+     * or deep-research process.
+     */
+    sourceTexts?: AddSourceTextInput[];
+    /**
+     * Safe write protocol text. The loop parses and applies only accepted
+     * `---FILE: knowledge/...---` blocks.
+     */
+    proposalText?: string;
+    /**
+     * The researcher decides when the wiki is good enough. The loop deliberately
+     * does not encode a domain-specific definition of "done".
+     */
+    done?: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeResearchLoopStep {
+    iteration: number;
+    notes?: string;
+    addedSources: SourceRecord[];
+    applied?: ApplyWriteBlocksResult;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    event: KnowledgeEvent;
+    done: boolean;
+    metadata?: Record<string, unknown>;
+}
+interface RunKnowledgeResearchLoopOptions {
+    root: string;
+    goal: string;
+    maxIterations?: number;
+    actor?: string;
+    strict?: ValidateKnowledgeOptions['strict'];
+    readinessSpecs?: KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
+    signal?: AbortSignal;
+    step(context: KnowledgeResearchLoopContext): Promise<KnowledgeResearchLoopDecision> | KnowledgeResearchLoopDecision;
+    onStep?: (step: KnowledgeResearchLoopStep) => Promise<void> | void;
+}
+interface KnowledgeResearchLoopResult {
+    root: string;
+    goal: string;
+    iterations: number;
+    done: boolean;
+    index: KnowledgeIndex;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    steps: KnowledgeResearchLoopStep[];
+}
+type KnowledgeControlLoopState = KnowledgeResearchLoopContext;
+type KnowledgeControlLoopAction = KnowledgeResearchLoopDecision;
+type KnowledgeControlLoopActionResult = KnowledgeResearchLoopStep;
+interface KnowledgeControlLoopAdapterOptions {
+    root: string;
+    goal: string;
+    actor?: string;
+    strict?: ValidateKnowledgeOptions['strict'];
+    readinessSpecs?: KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
+}
+type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoopState, KnowledgeControlLoopAction, KnowledgeControlLoopActionResult, ControlEvalResult>, 'intent' | 'observe' | 'validate' | 'act' | 'shouldStop'>;
+/**
+ * Adapter for running knowledge growth through `agent-eval`'s generic control
+ * runtime. The caller still owns `decide`: that can be a proposer agent,
+ * reviewer agent, deterministic policy, or a composition of all three.
+ */
+declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
+declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
+
+type RagKnowledgeImprovementPhase = 'retrieval-tuning' | 'gap-diagnosis' | 'knowledge-acquisition' | 'knowledge-update' | 'answer-quality' | 'promotion';
+type RagKnowledgeImprovementPhaseStatus = 'completed' | 'skipped' | 'failed';
+type RagGapKind = 'missing-source' | 'stale-source' | 'retrieval-miss' | 'retrieval-noise' | 'chunking-mismatch' | 'missing-multihop-evidence' | 'generator-unsupported-claim' | 'citation-mismatch' | 'incorrect-abstention' | 'unknown';
+type RagGapSeverity = 'info' | 'warning' | 'error' | 'critical';
+interface RagGapFinding {
+    id: string;
+    kind: RagGapKind;
+    severity: RagGapSeverity;
+    message: string;
+    scenarioId?: string;
+    evidence?: Record<string, JsonValue>;
+}
+interface RagKnowledgeImprovementPhaseResult {
+    phase: RagKnowledgeImprovementPhase;
+    status: RagKnowledgeImprovementPhaseStatus;
+    summary: string;
+    startedAt: string;
+    finishedAt: string;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagPhaseInputBase {
+    goal: string;
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    signal?: AbortSignal;
+}
+interface RagDiagnosisInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+}
+interface RagKnowledgeAcquisitionInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+}
+interface RagKnowledgeUpdateInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+}
+interface RagKnowledgeUpdateResult {
+    applied: boolean;
+    summary: string;
+    research?: KnowledgeResearchLoopResult;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagAnswerQualityInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+}
+interface RagAnswerQualityResult {
+    passed: boolean;
+    metrics: Record<string, number>;
+    findings?: readonly RagGapFinding[];
+    metadata?: Record<string, JsonValue>;
+}
+interface RagPromotionInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+    answerQuality?: RagAnswerQualityResult;
+}
+interface RagPromotionResult {
+    promoted: boolean;
+    reason: string;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagKnowledgeResearchOptions extends Omit<RunKnowledgeResearchLoopOptions, 'goal' | 'signal' | 'step'> {
+    goal?: string;
+    step?: RunKnowledgeResearchLoopOptions['step'];
+}
+interface RunRagKnowledgeImprovementLoopOptions {
+    goal: string;
+    retrieval?: RunRetrievalImprovementLoopOptions;
+    diagnose?: (input: RagDiagnosisInput) => MaybePromise$1<readonly RagGapFinding[]>;
+    acquireKnowledge?: (input: RagKnowledgeAcquisitionInput) => MaybePromise$1<KnowledgeResearchLoopDecision>;
+    knowledgeResearch?: RagKnowledgeResearchOptions;
+    updateKnowledge?: (input: RagKnowledgeUpdateInput) => MaybePromise$1<RagKnowledgeUpdateResult>;
+    evaluateAnswers?: (input: RagAnswerQualityInput) => MaybePromise$1<RagAnswerQualityResult>;
+    promote?: (input: RagPromotionInput) => MaybePromise$1<RagPromotionResult>;
+    enabledPhases?: readonly RagKnowledgeImprovementPhase[];
+    requiredPhases?: readonly RagKnowledgeImprovementPhase[];
+    signal?: AbortSignal;
+    now?: () => Date;
+}
+interface RunRagKnowledgeImprovementLoopResult {
+    goal: string;
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+    answerQuality?: RagAnswerQualityResult;
+    promotion?: RagPromotionResult;
+}
+type MaybePromise$1<T> = T | Promise<T>;
+declare function runRagKnowledgeImprovementLoop(options: RunRagKnowledgeImprovementLoopOptions): Promise<RunRagKnowledgeImprovementLoopResult>;
+
+type RagEvalProvider = 'agent-knowledge' | 'ragas' | 'deepeval' | 'trulens' | 'ragchecker' | 'custom';
+type RagEvalMetricKey = 'context_precision' | 'context_recall' | 'context_relevance' | 'context_sufficiency' | 'faithfulness' | 'groundedness' | 'answer_relevance' | 'answer_correctness' | 'citation_support' | 'abstention' | 'unsupported_answer_rate';
+type RagEvalSlice = 'known-answer' | 'paraphrase' | 'distractor' | 'freshness' | 'multi-source' | 'unanswerable' | 'long-tail' | 'custom';
+interface RagEvalContext {
+    id: string;
+    text: string;
+    rank?: number;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+    stale?: boolean;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagEvalCitation {
+    id: string;
+    claimId?: string;
+    contextId?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+    quote?: string;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagEvalClaim {
+    id: string;
+    text: string;
+    citationIds?: readonly string[];
+    metadata?: Record<string, JsonValue>;
+}
+interface RagRequiredContext {
+    id?: string;
+    text?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+}
+interface RagAnswerEvalScenario extends Scenario {
+    kind: 'rag-answer-eval';
+    query: string;
+    referenceAnswer?: string;
+    expectedClaims?: readonly string[];
+    forbiddenClaims?: readonly string[];
+    requiredContext?: readonly RagRequiredContext[];
+    unanswerable?: boolean;
+    requireCitations?: boolean;
+    slices?: readonly RagEvalSlice[];
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+}
+interface ExternalRagEvalScore {
+    provider: RagEvalProvider | string;
+    scores: Record<string, number>;
+    reasons?: Record<string, string>;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagAnswerEvalArtifact {
+    query: string;
+    answer: string;
+    contexts: readonly RagEvalContext[];
+    claims?: readonly RagEvalClaim[];
+    citations?: readonly RagEvalCitation[];
+    abstained?: boolean;
+    durationMs?: number;
+    costUsd?: number;
+    externalScores?: readonly ExternalRagEvalScore[];
+    metadata?: Record<string, JsonValue>;
+}
+interface RagAnswerMetricSummary {
+    metrics: Record<RagEvalMetricKey, number>;
+    composite: number;
+    passed: boolean;
+    findings: readonly RagGapFinding[];
+    claimCount: number;
+    supportedClaimCount: number;
+    citedClaimCount: number;
+    supportedCitationCount: number;
+    matchedRequiredContextCount: number;
+    requiredContextCount: number;
+    providerScores: Record<string, Record<RagEvalMetricKey, number>>;
+}
+interface RagAnswerQualityJudgeOptions {
+    name?: string;
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+    weights?: Partial<Record<RagEvalMetricKey, number>>;
+    externalScorePolicy?: 'prefer-external' | 'deterministic-first';
+    minClaimSupport?: number;
+}
+interface RagAnswerEvalCase {
+    scenario: RagAnswerEvalScenario;
+    artifact: RagAnswerEvalArtifact;
+}
+interface RagAnswerQualityHookOptions {
+    scenarios: readonly RagAnswerEvalScenario[];
+    run: (scenario: RagAnswerEvalScenario) => MaybePromise<RagAnswerEvalArtifact>;
+    externalEvaluator?: (item: RagAnswerEvalCase) => MaybePromise<ExternalRagEvalScore | readonly ExternalRagEvalScore[] | undefined>;
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+    weights?: Partial<Record<RagEvalMetricKey, number>>;
+}
+interface RagCalibrationOptions {
+    scenario: RagAnswerEvalScenario;
+    strong: RagAnswerEvalArtifact;
+    weak: RagAnswerEvalArtifact;
+    judge?: JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
+    minStrongScore?: number;
+    maxWeakScore?: number;
+    signal?: AbortSignal;
+}
+interface RagCalibrationResult {
+    passed: boolean;
+    strongScore: number;
+    weakScore: number;
+    gap: number;
+}
+interface KnowledgeBaseQualityOptions {
+    now?: Date;
+    strict?: boolean;
+    minCitationRate?: number;
+    maxStaleSourceRate?: number;
+}
+interface KnowledgeBaseQualityReport {
+    ok: boolean;
+    metrics: {
+        page_count: number;
+        source_count: number;
+        citation_rate: number;
+        source_backed_page_rate: number;
+        stale_source_rate: number;
+        duplicate_source_hash_rate: number;
+        lint_error_count: number;
+        lint_warning_count: number;
+    };
+    findings: readonly RagGapFinding[];
+}
+type MaybePromise<T> = T | Promise<T>;
+declare function ragAnswerQualityJudge(options?: RagAnswerQualityJudgeOptions): JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
+declare function scoreRagAnswerArtifact(artifact: RagAnswerEvalArtifact, scenario: RagAnswerEvalScenario, options?: RagAnswerQualityJudgeOptions): RagAnswerMetricSummary;
+declare function diagnoseRagAnswerFailure(metrics: Record<RagEvalMetricKey, number>, scenario: RagAnswerEvalScenario, thresholds?: Partial<Record<RagEvalMetricKey, number>>): RagGapFinding[];
+declare function createRagAnswerQualityHook(options: RagAnswerQualityHookOptions): () => Promise<RagAnswerQualityResult>;
+declare function calibrateRagAnswerJudge(options: RagCalibrationOptions): Promise<RagCalibrationResult>;
+declare function normalizeExternalRagScores(scores: readonly ExternalRagEvalScore[]): Record<string, Record<RagEvalMetricKey, number>>;
+declare function toRagasEvaluationRows(cases: readonly RagAnswerEvalCase[]): {
+    user_input: string;
+    response: string;
+    retrieved_contexts: string[];
+    reference: string | undefined;
+    reference_contexts: string[];
+}[];
+declare function toDeepEvalTestCases(cases: readonly RagAnswerEvalCase[]): {
+    input: string;
+    actual_output: string;
+    expected_output: string | undefined;
+    retrieval_context: string[];
+    context: string[];
+}[];
+declare function toTruLensRecords(cases: readonly RagAnswerEvalCase[]): {
+    input: string;
+    output: string;
+    context: string;
+}[];
+declare function toRagCheckerRecords(cases: readonly RagAnswerEvalCase[]): {
+    query_id: string;
+    query: string;
+    gt_answer: string | undefined;
+    response: string;
+    retrieved_context: {
+        doc_id: string;
+        text: string;
+    }[];
+    claims: string[];
+}[];
+declare function scoreKnowledgeBaseIndex(index: KnowledgeIndex, options?: KnowledgeBaseQualityOptions): KnowledgeBaseQualityReport;
+
+type KnowledgeImprovementStatus = 'running' | 'candidate-ready' | 'promoted' | 'rejected' | 'blocked';
+interface KnowledgeImprovementMetric {
+    score: number;
+    passed: boolean;
+    dimensions?: Record<string, number>;
+    notes?: string;
+}
+interface KnowledgeImprovementEvaluationInput {
+    runId: string;
+    iteration: number;
+    root: string;
+    baselineRoot: string;
+    candidateRoot: string;
+    baselineIndex: KnowledgeIndex;
+    candidateIndex: KnowledgeIndex;
+    baseHash: string;
+    candidateHash: string;
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    kbQuality: KnowledgeBaseQualityReport;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
+    signal?: AbortSignal;
+}
+type KnowledgeImprovementEvaluator = (input: KnowledgeImprovementEvaluationInput) => Promise<KnowledgeImprovementMetric> | KnowledgeImprovementMetric;
+interface KnowledgeImprovementLifecycleRecord {
+    stage: 'candidate-update' | 'candidate-evaluation';
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    findingCount: number;
+    retrievalWinnerConfig?: RetrievalConfig;
+    answerQuality?: RagAnswerQualityResult;
+    promotionDecision?: RagPromotionResult;
+}
+interface KnowledgeImprovementCandidateRecord {
+    iteration: number;
+    candidateId: string;
+    candidateRoot: string;
+    baseHash: string;
+    candidateHash?: string;
+    status: KnowledgeImprovementStatus;
+    createdAt: string;
+    updatedAt: string;
+    validation?: ValidateKnowledgeResult;
+    kbQuality?: KnowledgeBaseQualityReport;
+    readinessBlockingMissing?: number;
+    evaluation?: KnowledgeImprovementMetric;
+    lifecycle?: readonly KnowledgeImprovementLifecycleRecord[];
+    retrievalWinnerConfig?: RetrievalConfig;
+    answerQuality?: RagAnswerQualityResult;
+    promotionDecision?: RagPromotionResult;
+    notes?: string;
+}
+interface KnowledgeImprovementRunState {
+    version: 1;
+    runId: string;
+    root: string;
+    goal: string;
+    status: KnowledgeImprovementStatus;
+    baseHash: string;
+    createdAt: string;
+    updatedAt: string;
+    ownerId?: string;
+    candidates: KnowledgeImprovementCandidateRecord[];
+    promotedCandidateId?: string;
+    blockedReason?: string;
+}
+interface KnowledgeImprovementResult {
+    runId: string;
+    runDir: string;
+    state: KnowledgeImprovementRunState;
+    candidate?: KnowledgeImprovementCandidateRecord;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
+    promoted: boolean;
+    blocked: boolean;
+}
+interface KnowledgeImprovementRetrievalOptions extends Omit<RunRetrievalImprovementLoopOptions, 'index' | 'runDir'> {
+    runDir?: RunRetrievalImprovementLoopOptions['runDir'];
+}
+interface KnowledgeImprovementUpdateInput extends RagKnowledgeUpdateInput {
+    runId: string;
+    iteration: number;
+    candidateId: string;
+    root: string;
+    baselineRoot: string;
+    candidateRoot: string;
+    baseHash: string;
+}
+type KnowledgeImprovementUpdate = (input: KnowledgeImprovementUpdateInput) => Promise<RagKnowledgeUpdateResult> | RagKnowledgeUpdateResult;
+interface KnowledgeImprovementOptions {
+    root: string;
+    goal: string;
+    runId?: string;
+    runDir?: string;
+    ownerId?: string;
+    leaseTtlMs?: number;
+    resume?: boolean;
+    promote?: boolean;
+    maxCandidates?: number;
+    candidateResearchIterations?: number;
+    strict?: ValidateKnowledgeOptions['strict'];
+    readinessSpecs?: KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    kbQuality?: KnowledgeBaseQualityOptions;
+    step?: RunKnowledgeResearchLoopOptions['step'];
+    knowledgeResearch?: Omit<RagKnowledgeResearchOptions, 'root'>;
+    retrieval?: KnowledgeImprovementRetrievalOptions;
+    diagnose?: NonNullable<RunRagKnowledgeImprovementLoopOptions['diagnose']>;
+    acquireKnowledge?: NonNullable<RunRagKnowledgeImprovementLoopOptions['acquireKnowledge']>;
+    updateKnowledge?: KnowledgeImprovementUpdate;
+    evaluateAnswers?: NonNullable<RunRagKnowledgeImprovementLoopOptions['evaluateAnswers']>;
+    decidePromotion?: NonNullable<RunRagKnowledgeImprovementLoopOptions['promote']>;
+    enabledPhases?: readonly RagKnowledgeImprovementPhase[];
+    requiredPhases?: readonly RagKnowledgeImprovementPhase[];
+    evaluate?: KnowledgeImprovementEvaluator;
+    signal?: AbortSignal;
+    now?: () => Date;
+    onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
+}
+declare function knowledgeImprovementRunId(root: string, goal: string): string;
+declare function knowledgeImprovementRunDir(root: string, runId: string): string;
+declare function loadKnowledgeImprovementState(root: string, runId: string, runDir?: string): Promise<KnowledgeImprovementRunState | null>;
+declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
+declare function hashKnowledgeBase(root: string): Promise<string>;
+
 interface KbStore {
     putSource(source: SourceRecord): Promise<void>;
     getSource(id: string): Promise<SourceRecord | null>;
@@ -1103,12 +1894,79 @@ declare class FileSystemKbStore extends MemoryKbStore {
 
 declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
 
-interface ApplyWriteBlocksResult {
-    written: string[];
-    warnings: string[];
+/**
+ * `materialFactsSurfaced` — the held-out investment-research METRIC.
+ *
+ * Given a knowledge base a research loop built for a company and the company's
+ * HELD-OUT material-fact checklist (`tests/eval/investment-thesis-set.ts`, never
+ * shown to the loop), this returns the FRACTION of checklist items the KB's
+ * pages surface + ground. The check is the same `$0`, model-free, deterministic
+ * substring grader the loop's checklist already ships (`gradeFactAgainstText` /
+ * `gradeCompanyAgainstText`) — so the answer key never reaches a model the loop
+ * could observe, exactly the firewall the ML deep-question exam uses.
+ *
+ * The ONLY thing this file adds over the raw grader is the KB→text join: it reads
+ * the curated pages (and the raw source text) the loop wrote and hands their
+ * concatenation to the grader. That join mirrors `kbText` in the research-quality
+ * A/B (research-driving-ab.test.ts) so the thesis metric and the ML-exam metric
+ * read a KB the same way.
+ *
+ * WHY pages AND source text: an honest thesis surfaces a buried fact in its
+ * curated thesis PAGE (the judgment), but a loop whose page is thin while its
+ * fetched filings are rich should still get credit for what it actually pulled.
+ * Grading the union is the faithful, not the lenient, choice — it rewards the
+ * loop that REACHED the filing even if its synthesis was terse, and it cannot
+ * manufacture a hit the underlying evidence does not contain.
+ */
+
+/** Per-fact grade plus the fact's id/lens, for the audit trail. */
+interface FactResult {
+    id: string;
+    lens: CompanyEvalCase['facts'][number]['lens'];
+    surfaced: boolean;
+    groupsFound: number;
+    groupsTotal: number;
+    foundLabels: string[];
+}
+/** The metric's result for one company: the surfaced fraction + the per-fact trail. */
+interface MaterialFactsResult {
+    ticker: string;
+    company: string;
+    /** Held-out facts the KB surfaced + grounded. */
+    surfaced: number;
+    /** Total held-out facts for this company (the denominator). */
+    total: number;
+    /** `surfaced / total` in [0, 1]. */
+    fraction: number;
+    /** Per-fact grade, in checklist order, for the doc / audit. */
+    perFact: FactResult[];
 }
-declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
-declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
+/**
+ * Join a KB index into the single text blob the grader scans: every curated PAGE
+ * (title + body) followed by every raw SOURCE (title + fetched text). This is the
+ * text read AFTER the loop finished — it is never handed to the loop. Identical
+ * in spirit to `kbText` in the research-quality A/B so both metrics read a KB the
+ * same way.
+ */
+declare function kbIndexToText(index: KnowledgeIndex): string;
+/**
+ * Grade one company's KB against its held-out material-fact checklist, given the
+ * KB's already-joined text. The pure core — no I/O — so calibration can score a
+ * hand-written shallow/deep thesis string directly and the live path can score a
+ * real KB. Returns the surfaced FRACTION plus the per-fact audit trail.
+ */
+declare function materialFactsSurfacedInText(company: CompanyEvalCase, kbText: string): MaterialFactsResult;
+/**
+ * `materialFactsSurfaced(kb, checklist)` — the metric in its KB-reading form.
+ *
+ * `kb` is EITHER a knowledge-base root directory (the loop wrote pages there) or
+ * an already-built `KnowledgeIndex`. `checklist` is the company's held-out
+ * `CompanyEvalCase`. Returns the surfaced fraction + per-fact trail.
+ *
+ * The checklist is HELD OUT by construction: it lives in the test eval set, is
+ * never passed to the loop, and is read only here, after the loop finished.
+ */
+declare function materialFactsSurfaced(kb: string | KnowledgeIndex, checklist: CompanyEvalCase): Promise<MaterialFactsResult>;
 
 /**
  * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
@@ -1196,6 +2054,30 @@ interface ProposeFromFindingsResult {
 }
 declare function proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): ProposeFromFindingsResult;
 
+interface EvaluateKnowledgeBaseReadinessOptions {
+    root: string;
+    goal: string;
+    readinessSpecs?: readonly KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    strict?: ValidateKnowledgeOptions['strict'];
+    kbQuality?: KnowledgeBaseQualityOptions;
+}
+interface KnowledgeBaseReadinessEvaluation {
+    ready: boolean;
+    summary: string;
+    index: KnowledgeIndex;
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    kbQuality: KnowledgeBaseQualityReport;
+    dimensions: {
+        validation: number;
+        kb_quality: number;
+        blocking_readiness: number;
+    };
+}
+declare function evaluateKnowledgeBaseReadiness(options: EvaluateKnowledgeBaseReadinessOptions): Promise<KnowledgeBaseReadinessEvaluation>;
+
 interface KnowledgeReleaseReport {
     release: KnowledgeRelease;
     scorecard: ReleaseConfidenceScorecard;
@@ -1234,172 +2116,157 @@ interface KnowledgeReleaseInput {
 }
 declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
 
-interface ValidateKnowledgeOptions {
-    strict?: boolean;
-}
-interface ValidateKnowledgeResult {
-    ok: boolean;
-    findings: KnowledgeLintFinding[];
-}
-declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+/**
+ * Research-DRIVING driver for `runVerifiedResearchLoop`.
+ *
+ * The shipped drivers all FILTER the worker's sources:
+ *   - `createVerifyingResearchDriver` judges on-topic relevance,
+ *   - `createAdaptiveResearchDriver` dedups then triages then escalates,
+ *   - `createClaimGroundingVerifier` rejects misattributed citations.
+ *
+ * This driver does the OPPOSITE job: instead of narrowing the worker's output,
+ * it DRIVES the research DEEPER each round. Its value is not "fewer sources" —
+ * it is "more answered, better-corroborated sub-questions". Concretely, each
+ * round it:
+ *
+ *   1. EXTRACTS the key claims from the worker's new sources (one LLM pass per
+ *      source, in `verifySource`; falls back to a deterministic sentence-pull
+ *      when the model is unavailable so a round never silently extracts nothing).
+ *   2. TRACKS each claim's support — the set of INDEPENDENT sources (by canonical
+ *      host) that assert it — and detects CONTRADICTIONS between a new claim and
+ *      one already on the ledger.
+ *   3. GENERATES the next round's DEEP sub-questions from the accumulated claims,
+ *      in four kinds — comparative ("how does X's tradeoff differ from Y's?"),
+ *      mechanism ("under what precise condition does X fail?"), gap ("what
+ *      specific result is missing?"), and contradiction ("does any source
+ *      challenge claim Z?").
+ *   4. FLAGS weakly-supported claims (only ONE independent source) and
+ *      contradicted claims as INVALIDATION targets and demands the worker find
+ *      corroborating / refuting evidence for them.
+ *   5. FOLDS the deep sub-questions + invalidation challenges into the worker's
+ *      next prompt via the loop's `foldGaps` → `steer` channel — that is the
+ *      mechanism that drives DEPTH and VALIDATION rather than breadth.
+ *
+ * COMPLETION (`isComplete` / the `done` judgment the caller gates on) does NOT
+ * look at source COUNT. It is done only when every deep sub-question it raised
+ * has been addressed AND every key claim is either supported by >= 2 independent
+ * sources OR explicitly marked CONTESTED (a contradiction the loop surfaced and
+ * could not resolve). A KB with twenty sources all asserting one unchallenged
+ * claim is NOT done; a KB whose handful of claims are each corroborated or
+ * contested IS.
+ *
+ * It reuses `runVerifiedResearchLoop` (it is a plain `ResearchDriver`), the web
+ * worker, `sha256` (claim identity), `canonicalizeUrl` (independent-source
+ * identity), and the `RouterClient` chat surface; it reinvents none of them.
+ */
 
-interface KnowledgeResearchLoopContext {
-    root: string;
-    goal: string;
-    iteration: number;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    previousSteps: KnowledgeResearchLoopStep[];
-    signal?: AbortSignal;
-}
-interface KnowledgeResearchLoopDecision {
-    /**
-     * Free-form notes from the researcher. Keep this human-readable; products can
-     * store it as the research transcript.
-     */
-    notes?: string;
+/** The four deep sub-question kinds the driver generates to drive depth. */
+type DeepQuestionKind = 'comparative' | 'mechanism' | 'gap' | 'contradiction';
+/** A deep sub-question the driver folds into the worker's next prompt. */
+interface DeepQuestion {
+    kind: DeepQuestionKind;
+    text: string;
+    /** sha256-derived stable id, so "addressed" can be tracked across rounds. */
+    id: string;
+    /** Claim id(s) this question interrogates (for contradiction/mechanism kinds). */
+    claimIds: string[];
+    /** True once a later round's evidence addressed it (see `markAddressed`). */
+    addressed: boolean;
+    /** The round this question was raised in. */
+    raisedRound: number;
+}
+/** One tracked claim plus the independent sources that assert it. */
+interface TrackedClaim {
+    id: string;
+    /** The claim text as first extracted (kept for prompts/audit). */
+    text: string;
+    /** Canonical hosts of the INDEPENDENT sources that assert this claim. */
+    supportingHosts: Set<string>;
+    /** Source URIs that assert this claim (provenance; may share a host). */
+    supportingUris: string[];
+    /** Claim ids this claim was found to CONTRADICT (and vice versa). */
+    contradicts: Set<string>;
     /**
-     * Local files to register as immutable sources before applying proposals.
+     * CONTESTED = a contradiction the loop surfaced but could not resolve to a
+     * single supported claim. A contested claim counts as "settled enough to be
+     * done" (we report the disagreement) even with < 2 independent sources.
      */
-    sourcePaths?: string[];
+    contested: boolean;
+    firstSeenRound: number;
+}
+/** The driver's accumulated research state — the completion oracle reads this. */
+interface ResearchDrivingState {
+    /** Every claim extracted from the worker's sources, by id. */
+    claims: TrackedClaim[];
+    /** Every deep sub-question raised, by id. */
+    questions: DeepQuestion[];
+    /** Claims with exactly one independent source AND not contested. */
+    weaklySupported: TrackedClaim[];
+    /** Claims supported by >= 2 independent sources. */
+    corroborated: TrackedClaim[];
+    /** Claims marked contested (a surfaced, unresolved contradiction). */
+    contested: TrackedClaim[];
+    /** Deep questions still unaddressed. */
+    openQuestions: DeepQuestion[];
+    /** How many rounds the driver has folded steer for. */
+    rounds: number;
+}
+interface ResearchDrivingDriverOptions {
+    /** Router client for claim extraction + deep-question generation. */
+    router?: RouterClient;
+    router_options?: TangleRouterOptions;
     /**
-     * Textual source artifacts discovered by an agent, browser worker, connector,
-     * or deep-research process.
+     * A claim is CORROBORATED at this many INDEPENDENT supporting sources (distinct
+     * canonical hosts). Default 2 — the task's ">= 2 independent sources" bar.
      */
-    sourceTexts?: AddSourceTextInput[];
+    minIndependentSources?: number;
+    /** Max deep sub-questions to fold into one round's steer. Default 6. */
+    maxQuestionsPerRound?: number;
+    /** Max claims to extract from a single source. Default 3. */
+    maxClaimsPerSource?: number;
     /**
-     * Safe write protocol text. The loop parses and applies only accepted
-     * `---FILE: knowledge/...---` blocks.
+     * When the extractor LLM is unavailable, fall back to a deterministic claim
+     * pull (the source's leading sentences) so the driver still drives. Default
+     * true. Set false to require the model (claims will be empty without it).
      */
-    proposalText?: string;
-    /**
-     * The researcher decides when the wiki is good enough. The loop deliberately
-     * does not encode a domain-specific definition of "done".
-     */
-    done?: boolean;
-    metadata?: Record<string, unknown>;
+    deterministicFallback?: boolean;
+    /** Observe each round's generated steer (for instrumentation / the script). */
+    onSteer?: (steer: ResearchDrivingSteer) => void;
 }
-interface KnowledgeResearchLoopStep {
-    iteration: number;
-    notes?: string;
-    addedSources: SourceRecord[];
-    applied?: ApplyWriteBlocksResult;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    event: KnowledgeEvent;
-    done: boolean;
-    metadata?: Record<string, unknown>;
-}
-interface RunKnowledgeResearchLoopOptions {
-    root: string;
-    goal: string;
-    maxIterations?: number;
-    actor?: string;
-    strict?: ValidateKnowledgeOptions['strict'];
-    readinessSpecs?: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
-    signal?: AbortSignal;
-    step(context: KnowledgeResearchLoopContext): Promise<KnowledgeResearchLoopDecision> | KnowledgeResearchLoopDecision;
-    onStep?: (step: KnowledgeResearchLoopStep) => Promise<void> | void;
-}
-interface KnowledgeResearchLoopResult {
-    root: string;
-    goal: string;
-    iterations: number;
-    done: boolean;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: KnowledgeResearchLoopStep[];
-}
-type KnowledgeControlLoopState = KnowledgeResearchLoopContext;
-type KnowledgeControlLoopAction = KnowledgeResearchLoopDecision;
-type KnowledgeControlLoopActionResult = KnowledgeResearchLoopStep;
-interface KnowledgeControlLoopAdapterOptions {
-    root: string;
-    goal: string;
-    actor?: string;
-    strict?: ValidateKnowledgeOptions['strict'];
-    readinessSpecs?: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
+/** What the driver folded into one round's worker prompt, surfaced for audit. */
+interface ResearchDrivingSteer {
+    round: number;
+    deepQuestions: DeepQuestion[];
+    /** Claims it demanded corroborating/refuting evidence for this round. */
+    invalidationTargets: TrackedClaim[];
+    /** The readiness gaps it interleaved (passed through from the loop). */
+    gaps: KnowledgeGap[];
+    /** The full steer text handed to the worker. */
+    text: string;
 }
-type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoopState, KnowledgeControlLoopAction, KnowledgeControlLoopActionResult, ControlEvalResult>, 'intent' | 'observe' | 'validate' | 'act' | 'shouldStop'>;
 /**
- * Adapter for running knowledge growth through `agent-eval`'s generic control
- * runtime. The caller still owns `decide`: that can be a proposer agent,
- * reviewer agent, deterministic policy, or a composition of all three.
+ * The research-driving driver. It is a `ResearchDriver` (drops straight into
+ * `runVerifiedResearchLoop`) PLUS a completion oracle and live state, mirroring
+ * how `createAdaptiveResearchDriver` exposes `stats()`.
  */
-declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
-declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
-
-/**
- * Default standing instructions for a research supervisor. It does NOT solve the
- * research itself — it DECOMPOSES the goal into sub-topics and spawns one
- * researcher per sub-topic over the live `Scope`, widening/narrowing until the
- * readiness gate (the deliverable check) reports the knowledge base is ready.
- */
-declare const RESEARCH_SUPERVISOR_SYSTEM_PROMPT: string;
-interface ResearchSupervisorOptions {
-    /** Where the knowledge base lives. The deliverable check reads readiness here. */
-    root: string;
-    /** The research goal handed to the supervisor as its task. */
-    goal: string;
+interface ResearchDrivingDriver extends ResearchDriver {
+    /** Live snapshot of the claim ledger + deep questions. */
+    researchState(): ResearchDrivingState;
     /**
-     * Readiness specs define DONE: the supervisor's deliverable check passes once
-     * `scoreKnowledgeReadiness` reports no blocking gaps over the live KB. Required
-     * — without a gate the supervisor would never know when to stop.
+     * The completion oracle — gate `done` on THIS, not on source count. True when
+     * every deep sub-question is addressed AND every claim is corroborated
+     * (>= `minIndependentSources` independent sources) or explicitly contested.
+     * False while any claim is weakly-supported or any deep question is open.
+     * Returns false before any claim has been seen (nothing researched yet).
      */
-    readinessSpecs: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    /** The conserved compute pool for the whole supervised run. */
-    budget: Budget;
+    isComplete(): boolean;
     /**
-     * WHERE researcher workers run — the caller's real backend seam (sandbox with
-     * a `sandboxClient`, or router/cli/bridge). The supervisor spawns researchers
-     * on this backend; assembling the seam (creds, sandbox SDK) is the caller's,
-     * so there is no fabricated default.
+     * The last round's generated steer, or undefined before the first fold. Useful
+     * to assert the driver produced deeper questions / invalidation challenges.
      */
-    backend: ExecutorConfig;
-    /** Harness for the researcher worker profile (default `researcherProfile`'s). */
-    harness?: string;
-    /** The supervisor brain's router model. */
-    supervisorModel?: string;
-    /** Custom supervisor instructions. Defaults to {@link RESEARCH_SUPERVISOR_SYSTEM_PROMPT}. */
-    supervisorSystemPrompt?: string;
-    /** Extra `supervise()` knobs (perWorker, maxLiveWorkers, router, allowedModels, …). */
-    superviseOptions?: Partial<Omit<SuperviseOptions, 'budget' | 'backend' | 'deliverable'>>;
+    lastSteer(): ResearchDrivingSteer | undefined;
 }
-/**
- * Build the deliverable (completion oracle) for a research supervisor: "settled
- * ⟺ the knowledge base is ready". It re-reads the KB from disk and runs the
- * readiness gate, so the supervisor stops on the REAL grounded state — not on a
- * worker's self-report.
- */
-declare function knowledgeReadinessDeliverable(options: Pick<ResearchSupervisorOptions, 'root' | 'goal' | 'readinessSpecs' | 'readinessTaskId' | 'readiness'>): DeliverableSpec<unknown>;
-/**
- * A research supervisor: a SUPERVISOR brain creates the topology dynamically —
- * how many researchers, split by sub-topic — over the `Scope`, with the
- * knowledge-readiness gate as its stop condition.
- *
- * This is a thin wrapper over `supervise(profile, goal, opts)`. It composes the
- * existing pieces and builds nothing new: the researcher `AgentProfile` (from
- * `researcherProfile`) is the worker shape the supervisor spawns, and
- * `knowledgeReadinessDeliverable` (over `scoreKnowledgeReadiness`) is the
- * completion oracle that decides when the KB is ready.
- *
- * Needs creds (a real supervisor router brain + a worker backend), so it is the
- * LIVE path. The offline two-agent loop is `runTwoAgentResearchLoop`.
- */
-declare function runResearchSupervisor(options: ResearchSupervisorOptions): Promise<SupervisedResult<unknown>>;
+declare function createResearchDrivingDriver(options?: ResearchDrivingDriverOptions): ResearchDrivingDriver;
 
 declare const SourceAnchorSchema: z.ZodObject<{
     id: z.ZodString;
@@ -1613,4 +2480,4 @@ declare function normalizeLinkTarget(target: string): string;
 declare function isSafeKnowledgePath(path: string, allowedPrefixes?: string[]): boolean;
 declare function parseKnowledgeWriteBlocks(text: string, allowedPrefixes?: string[]): KnowledgeWriteParseResult;
 
-export { type AdaptiveDecision, type AdaptiveDriverOptions, type AdaptiveResearchDriver, type AdaptiveStats, type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type ClaimGroundingDriverOptions, type D1Adapter, type DedupReason, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchSourceProposal, type ResearchSupervisorOptions, type ResearchWorker, type RouterClient, RouterError, type RouterUsage, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, groundClaimInText, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReadinessDeliverable, knowledgeReleaseReport, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeResearchLoop, runResearchSupervisor, runTwoAgentResearchLoop, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, triageSource, validateKnowledgeIndex, withCitedClaim, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+export { type AdaptiveDecision, type AdaptiveDriverOptions, type AdaptiveResearchDriver, type AdaptiveStats, type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type ClaimGroundingDriverOptions, type CompanyEvalCase, type D1Adapter, type DedupReason, type DeepQuestion, type DeepQuestionKind, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type EvaluateKnowledgeBaseReadinessOptions, type ExpectedGroup, type ExternalRagEvalScore, type FactResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeBaseQualityOptions, type KnowledgeBaseQualityReport, type KnowledgeBaseReadinessEvaluation, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, type KnowledgeImprovementCandidateRecord, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementLifecycleRecord, type KnowledgeImprovementMetric, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, type KnowledgeImprovementStatus, type KnowledgeImprovementUpdate, type KnowledgeImprovementUpdateInput, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, type MaterialFact, type MaterialFactLens, type MaterialFactsResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RagAnswerEvalArtifact, type RagAnswerEvalCase, type RagAnswerEvalScenario, type RagAnswerMetricSummary, type RagAnswerQualityHookOptions, type RagAnswerQualityInput, type RagAnswerQualityJudgeOptions, type RagAnswerQualityResult, type RagCalibrationOptions, type RagCalibrationResult, type RagDiagnosisInput, type RagEvalCitation, type RagEvalClaim, type RagEvalContext, type RagEvalMetricKey, type RagEvalProvider, type RagEvalSlice, type RagGapFinding, type RagGapKind, type RagGapSeverity, type RagKnowledgeAcquisitionInput, type RagKnowledgeImprovementPhase, type RagKnowledgeImprovementPhaseResult, type RagKnowledgeImprovementPhaseStatus, type RagKnowledgeResearchOptions, type RagKnowledgeUpdateInput, type RagKnowledgeUpdateResult, type RagPhaseInputBase, type RagPromotionInput, type RagPromotionResult, type RagRequiredContext, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, RetrievalConfig, type RouterClient, RouterError, type RouterUsage, type RunKnowledgeResearchLoopOptions, type RunRagKnowledgeImprovementLoopOptions, type RunRagKnowledgeImprovementLoopResult, RunRetrievalImprovementLoopOptions, RunRetrievalImprovementLoopResult, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type ThesisRunOptions, type ThesisRunResult, type ThesisTaskInput, type TrackedClaim, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifiedResearchLoopOptions, type VerifiedResearchLoopResult, type VerifiedResearchRound, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createRagAnswerQualityHook, createResearchDrivingDriver, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, diagnoseRagAnswerFailure, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, gradeCompanyAgainstText, gradeFactAgainstText, groundClaimInText, hashKnowledgeBase, improveKnowledgeBase, initKnowledgeBase, inspectKnowledgeIndex, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, runInvestmentThesisTask, runKnowledgeResearchLoop, runRagKnowledgeImprovementLoop, runTwoAgentResearchLoop, runVerifiedResearchLoop, scoreKnowledgeBaseIndex, scoreRagAnswerArtifact, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, thesisReadinessSpecs, toDeepEvalTestCases, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, writeJson, writeKnowledgeIndex, writeSourceRegistry };