@tangle-network/agent-knowledge 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,14 +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 { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as SourceRegistry, f as KnowledgeEvent, g as KnowledgeLintFinding, h as KnowledgeEventType, i as KnowledgePage, b as KnowledgeGraph, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as KnowledgeWriteParseResult } from './types-6x0OpfW6.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-6x0OpfW6.js';
 import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult, RunRecord, AnalystSeverity, AnalystFinding, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard } from '@tangle-network/agent-eval';
-import { R as RunRetrievalImprovementLoopResult, a as RunRetrievalImprovementLoopOptions } from './index-BLxw1I_F.js';
-export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, b as BuildRetrievalEvalDispatchOptions, c as BuildRetrievalParameterCandidatesOptions, I as INDUSTRY_MEMORY_BENCHMARKS, d as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, e as KnowledgeAnswerBenchmarkTaskKind, f as KnowledgeBenchmarkArtifact, g as KnowledgeBenchmarkCase, h as KnowledgeBenchmarkCaseBase, i as KnowledgeBenchmarkDistribution, j as KnowledgeBenchmarkEvaluation, k as KnowledgeBenchmarkFamily, l as KnowledgeBenchmarkReport, m as KnowledgeBenchmarkResponder, n as KnowledgeBenchmarkScenario, o as KnowledgeBenchmarkSliceSummary, p as KnowledgeBenchmarkSource, q as KnowledgeBenchmarkSpec, r as KnowledgeBenchmarkSplit, s as KnowledgeBenchmarkTaskKind, t as KnowledgeClaimMatcher, u as KnowledgeMemoryBenchmarkCase, v as KnowledgeMemoryBenchmarkTaskKind, w as KnowledgeMemoryEvent, x as KnowledgeMemoryFactMatcher, y as KnowledgeRetrievalBenchmarkCase, z as KnowledgeRetrievalBenchmarkQrel, A as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, C as MemoryAdapterBenchmarkRankingRow, D as RetrievalConfig, 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-BLxw1I_F.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';
+import { AgentCandidateKnowledgeRef } from '@tangle-network/agent-interface';
 import { z } from 'zod';
 import { JsonValue, Scenario, JudgeConfig } from '@tangle-network/agent-eval/campaign';
+import { R as RunRetrievalImprovementLoopResult, a as RunRetrievalImprovementLoopOptions } from './index-BHQk7jOT.js';
+export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, b as BuildRetrievalEvalDispatchOptions, c as BuildRetrievalParameterCandidatesOptions, I as INDUSTRY_MEMORY_BENCHMARKS, d as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, e as KnowledgeAnswerBenchmarkTaskKind, f as KnowledgeBenchmarkArtifact, g as KnowledgeBenchmarkCase, h as KnowledgeBenchmarkCaseBase, i as KnowledgeBenchmarkDistribution, j as KnowledgeBenchmarkEvaluation, k as KnowledgeBenchmarkFamily, l as KnowledgeBenchmarkReport, m as KnowledgeBenchmarkResponder, n as KnowledgeBenchmarkScenario, o as KnowledgeBenchmarkSliceSummary, p as KnowledgeBenchmarkSource, q as KnowledgeBenchmarkSpec, r as KnowledgeBenchmarkSplit, s as KnowledgeBenchmarkTaskKind, t as KnowledgeClaimMatcher, u as KnowledgeMemoryBenchmarkCase, v as KnowledgeMemoryBenchmarkTaskKind, w as KnowledgeMemoryEvent, x as KnowledgeMemoryFactMatcher, y as KnowledgeRetrievalBenchmarkCase, z as KnowledgeRetrievalBenchmarkQrel, A as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, C as MemoryAdapterBenchmarkRankingRow, D as RetrievalConfig, 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-BHQk7jOT.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 { 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';
+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-BFRyr390.js';
 import '@tangle-network/agent-eval/rl';
 
 interface SourceAdapterInput {
@@ -632,1383 +633,1384 @@ interface AdaptiveResearchDriver {
  */
 declare function createAdaptiveResearchDriver(options?: AdaptiveDriverOptions): AdaptiveResearchDriver;
 
-/**
- * Change detection across snapshots of one source's fragments.
- *
- * The output drives the continuous-ingestion loop: each `KnowledgeChange`
- * carries the eval dimensions affected (`affectedDimensions`), which an
- * agent-eval campaign scheduler consumes to decide which campaigns to
- * re-run. Three change kinds:
- *
- *   - `added` — fragment id appears in `next` but not `prev`.
- *   - `removed` — fragment id appears in `prev` but not `next`. Typical
- *     trigger: an authority retires a Wex slug, or a state SOS reorganises
- *     its forms catalogue.
- *   - `modified` — fragment id appears in both, body hash differs. This
- *     is the dominant change kind in practice — the Ryan-LLC v. FTC
- *     vacatur case manifests as a `modified` on the Wex non-compete
- *     fragment, NOT as a removed one.
- *
- * Unverifiable fragments are filtered out before diffing — comparing a
- * captcha-blocked snapshot against a real one would falsely fire every
- * fragment as removed. The caller can inspect the raw lists if they want
- * to surface block-page failures.
- *
- * Within-snapshot duplicate ids are an upstream bug; this function picks
- * the LAST one and emits a diagnostic via the `warnings` field.
- *
- * @stable
- */
-type KnowledgeChangeKind = 'added' | 'removed' | 'modified';
-interface KnowledgeChange {
-    /** Source-scoped id (matches `KnowledgeFragment.id`). */
-    fragmentId: string;
-    kind: KnowledgeChangeKind;
-    /**
-     * For `added`: full body of the new fragment.
-     * For `removed`: full body of the prior fragment.
-     * For `modified`: unified-diff-style payload `{ before, after }` body strings.
-     */
-    diff?: {
-        before?: string;
-        after?: string;
-    };
-    /**
-     * Eval dimensions to re-score. Computed as the union of both fragments'
-     * `dimensionHints`. The eval cron treats this as a set of campaign tags.
-     */
-    affectedDimensions: string[];
-    /** URL of the affected authority page (from whichever side has it). */
-    url?: string;
-    /**
-     * Source-attested change time. For `modified`, takes the NEXT fragment's
-     * `sourceUpdatedAt`. For `removed`, takes the PRIOR fragment's
-     * `sourceUpdatedAt`. For `added`, takes the NEXT fragment's
-     * `sourceUpdatedAt`. Consumers index changes by this date.
-     */
-    detectedAt: string;
-}
-interface DetectChangesResult {
-    changes: KnowledgeChange[];
-    /** Counts by kind — handy for dashboards. */
-    summary: {
-        added: number;
-        removed: number;
-        modified: number;
-    };
-    /** Non-fatal diagnostics (duplicate ids, dropped unverifiable fragments). */
+interface ApplyWriteBlocksResult {
+    written: string[];
     warnings: string[];
 }
-interface DetectChangesOptions {
-    /**
-     * When true (default), unverifiable fragments are dropped from both
-     * sides before comparison. Set false ONLY when debugging block-page
-     * issues — comparing against unverifiable content emits false
-     * `removed`/`modified` changes.
-     */
-    skipUnverifiable?: boolean;
-    /**
-     * When provided, only changes whose `affectedDimensions` intersect this
-     * set are returned. Useful for cron loops that schedule per-dimension
-     * eval campaigns and only care about a subset.
-     */
-    filterDimensions?: string[];
-}
-declare function detectChanges(prev: KnowledgeFragment[], next: KnowledgeFragment[], options?: DetectChangesOptions): DetectChangesResult;
+declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
+declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
 
-interface ChunkingOptions {
-    targetChars: number;
-    maxChars: number;
-    minChars: number;
-    overlapChars: number;
+interface ValidateKnowledgeOptions {
+    strict?: boolean;
 }
-interface KnowledgeChunk {
-    index: number;
-    text: string;
-    headingPath: string;
-    charStart: number;
-    charEnd: number;
-    oversized: boolean;
+interface ValidateKnowledgeResult {
+    ok: boolean;
+    findings: KnowledgeLintFinding[];
 }
-declare function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[];
-declare function stripFrontmatter(content: string): {
-    body: string;
-    bodyOffset: number;
-};
-
-/**
- * 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
- * cleanliness win is dominated by DE-DUPLICATION — which a deterministic
- * content-hash / canonical-URL check captures at ~none of the LLM premium (see
- * `docs/results/cost-quality.md`). That makes the LLM verifier look expensive
- * for what a cheap rule already does.
- *
- * Claim-grounding targets a DIFFERENT, harder error band: a citation that is
- * relevant and unique but **misattributed** — the page is on-topic, the URL is
- * real, yet the specific CLAIM the source is cited for does NOT actually appear
- * in the page. This is the citation-fabrication failure mode of LLM research:
- * the model writes a plausible sentence and hangs a real URL off it that never
- * says any such thing. Neither de-dup nor a relevance judge catches it (both can
- * pass a misattributed-but-on-topic page); only checking the claim against the
- * fetched text does.
- *
- * The check is EXECUTABLE GROUND TRUTH, not another LLM opinion: the worker
- * attaches the specific claim it is citing the source for, and the verifier
- * tests whether that claim is PRESENT (verbatim, normalized, or as a sufficient
- * content-word overlap / close paraphrase) in the `htmlToText` output of the
- * page the worker actually fetched. A claim that is not grounded is rejected as
- * misattributed. Because the oracle is deterministic text presence — not a model
- * call — it is a deployable, non-oracle verifier: it can run in production with
- * zero inference cost, OR be composed with the LLM relevance verifier so the
- * loop rejects BOTH off-topic AND misattributed sources.
- *
- * This module is content-free and any-topic: it adds (1) a way for a proposal to
- * carry the claim it is cited for, (2) the `groundClaimInText` oracle, and (3) a
- * `ResearchDriver` that gates on grounding. It composes the existing
- * `ResearchDriver` / `ResearchSourceProposal` contracts and the shipped
- * `htmlToText`; it reinvents none of them.
- */
+declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
 
-/**
- * Metadata key under which a proposal carries the specific claim it is cited
- * for. The worker sets `metadata[citedClaimKey] = '<the claim>'`; the
- * claim-grounding driver reads it and checks it against the fetched page text.
- */
-declare const citedClaimKey = "citedClaim";
-/** Read the cited claim a proposal carries, if any. */
-declare function citedClaimOf(source: ResearchSourceProposal): string | undefined;
-/** Attach a cited claim to a proposal (immutably returns a new proposal). */
-declare function withCitedClaim(source: ResearchSourceProposal, claim: string): ResearchSourceProposal;
-interface GroundingResult {
-    /** True when the claim is sufficiently present in the page text. */
-    grounded: boolean;
-    /** How the claim matched (or why it didn't). For audit/notes. */
-    mode: 'verbatim' | 'normalized' | 'overlap' | 'absent' | 'empty-claim' | 'empty-text';
+interface KnowledgeResearchLoopContext {
+    root: string;
+    goal: string;
+    iteration: number;
+    index: KnowledgeIndex;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    previousSteps: KnowledgeResearchLoopStep[];
+    signal?: AbortSignal;
+}
+interface KnowledgeResearchLoopDecision {
     /**
-     * Fraction of the claim's content words found in the page text. 1 for a
-     * verbatim/normalized hit; the measured overlap otherwise.
+     * Free-form notes from the researcher. Keep this human-readable; products can
+     * store it as the research transcript.
      */
-    overlap: number;
-    /** Content words present in the claim but NOT in the page text. */
-    missingWords: string[];
-}
-interface GroundClaimOptions {
+    notes?: string;
     /**
-     * Minimum fraction of the claim's content words that must appear in the page
-     * text to count as a close paraphrase when there is no verbatim/normalized
-     * hit. Default 0.7 — a high bar, because a misattribution is exactly a claim
-     * whose specific words the page does not contain.
+     * Local files to register as immutable sources before applying proposals.
      */
-    minOverlap?: number;
+    sourcePaths?: string[];
     /**
-     * Content words shorter than this are ignored (drops "the", "of", "is", …)
-     * and never count toward overlap. Default 3.
+     * Textual source artifacts discovered by an agent, browser worker, connector,
+     * or deep-research process.
      */
-    minWordLength?: number;
-}
-/**
- * THE ORACLE. Is `claim` grounded in `pageText` (the `htmlToText` output of the
- * page the worker fetched)? Deterministic, no model call:
- *
- *   1. verbatim — the claim string appears as-is (case-insensitive).
- *   2. normalized — the claim appears after collapsing punctuation/whitespace
- *      on both sides (so "5.4x" vs "5.4 x", smart quotes, etc. still match).
- *   3. overlap — a close paraphrase: at least `minOverlap` of the claim's
- *      substantive content words appear in the page text. A misattributed page
- *      fails here because the SPECIFIC words the claim asserts are absent.
- *
- * Returns the match mode, the measured overlap, and the missing content words —
- * enough for the driver to give a precise rejection reason and for a test/doc to
- * audit WHY a claim grounded or didn't.
- */
-declare function groundClaimInText(claim: string, pageText: string, options?: GroundClaimOptions): GroundingResult;
-interface ClaimGroundingDriverOptions extends GroundClaimOptions {
+    sourceTexts?: AddSourceTextInput[];
     /**
-     * Optional second verifier to compose AFTER grounding passes. When set, a
-     * source must BOTH ground its claim AND pass this verifier (e.g. the LLM
-     * relevance driver's `verifySource`). Lets the loop reject off-topic AND
-     * misattributed sources in one driver. Omit for the pure, zero-inference
-     * grounding gate.
+     * Safe write protocol text. The loop parses and applies only accepted
+     * `---FILE: knowledge/...---` blocks.
      */
-    relevanceVerifier?: (source: ResearchSourceProposal, ctx: SourceVerificationContext) => Promise<SourceVerdict> | SourceVerdict;
+    proposalText?: string;
     /**
-     * What to do when a proposal carries NO cited claim. `'reject'` (default) is
-     * fail-closed: in claim-grounding mode every source must declare what it is
-     * cited for, so an un-annotated source is treated as ungrounded. `'accept'`
-     * lets un-annotated sources through to the relevance verifier (if any) —
-     * useful when mixing annotated and legacy proposals.
+     * The researcher decides when the wiki is good enough. The loop deliberately
+     * does not encode a domain-specific definition of "done".
      */
-    onMissingClaim?: 'reject' | 'accept';
-}
-/**
- * A `ResearchDriver`-shaped verifier (just the `verifySource` arm) that gates on
- * CLAIM GROUNDING: it rejects a source whose cited claim is not present in its
- * fetched page text — a misattributed / fabricated citation — and (optionally)
- * composes a relevance verifier after grounding passes.
- *
- * The returned function matches `ResearchDriver['verifySource']`, so it drops
- * straight into `runVerifiedResearchLoop` as `{ verifySource: createClaimGroundingVerifier(...) }`.
- */
-declare function createClaimGroundingVerifier(options?: ClaimGroundingDriverOptions): (source: ResearchSourceProposal, ctx: SourceVerificationContext) => Promise<SourceVerdict>;
-interface WorkerClaimDecorationOptions {
-    router?: RouterClient;
-    router_options?: TangleRouterOptions;
-    /** Max output tokens for the claim-extraction call. Default 1200 (glm floor). */
-    maxTokens?: number;
+    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'>;
 /**
- * Ask an LLM to state, for one source, the single specific factual claim a
- * researcher would cite THIS page for toward the goal. Used to DECORATE the
- * sources a relevance-only worker produced with the claim a citation would make,
- * so the claim-grounding verifier has something executable to check. The model
- * is told to ground the claim in the provided excerpt; the verifier then checks
- * it against the FULL page text independently — the model does not get to mark
- * its own homework.
- *
- * Returns the proposal annotated via `withCitedClaim`, or the original proposal
- * unchanged if the model returns nothing parseable (the verifier's
- * `onMissingClaim` policy then decides).
- */
-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.
+ * 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 createCollectionResearchDriver(): ResearchDriver;
+declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
+declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
 
-interface DiscoveryTask {
+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;
-    query?: string;
-    sourceHints?: string[];
-    metadata?: Record<string, unknown>;
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    signal?: AbortSignal;
 }
-interface DiscoveryResult {
-    taskId: string;
+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;
-    sourceUris?: string[];
-    claims?: Array<{
-        text: string;
-        sourceUri?: string;
-        confidence?: number;
-    }>;
-    followUpTasks?: DiscoveryTask[];
-    metadata?: Record<string, unknown>;
+    research?: KnowledgeResearchLoopResult;
+    metadata?: Record<string, JsonValue>;
 }
-interface KnowledgeDiscoveryWorker {
-    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
+interface RagAnswerQualityInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
 }
-interface KnowledgeDiscoveryDispatcher {
-    dispatch(tasks: DiscoveryTask[], options?: {
-        concurrency?: number;
-        signal?: AbortSignal;
-    }): Promise<DiscoveryResult[]>;
+interface RagAnswerQualityResult {
+    passed: boolean;
+    metrics: Record<string, number>;
+    findings?: readonly RagGapFinding[];
+    metadata?: Record<string, JsonValue>;
 }
-type DiscoveryLoopStopReason = 'complete' | 'max-rounds' | 'max-tasks' | 'aborted';
-interface DiscoveryLoopRound {
-    round: number;
-    tasks: DiscoveryTask[];
-    results: DiscoveryResult[];
-    queuedFollowUps: DiscoveryTask[];
+interface RagPromotionInput extends RagPhaseInputBase {
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+    answerQuality?: RagAnswerQualityResult;
 }
-interface DiscoveryLoopResult {
-    stopReason: DiscoveryLoopStopReason;
-    tasksDispatched: number;
-    results: DiscoveryResult[];
-    rounds: DiscoveryLoopRound[];
-    /** Tasks retained, not dropped, when a configured limit stops the loop. */
-    pendingTasks: DiscoveryTask[];
-    /** Structurally identical task identities ignored to prevent cycles. */
-    duplicateTaskIds: string[];
+interface RagPromotionResult {
+    promoted: boolean;
+    reason: string;
+    metadata?: Record<string, JsonValue>;
 }
-interface RunDiscoveryLoopOptions {
-    dispatcher: KnowledgeDiscoveryDispatcher;
-    initialTasks: readonly DiscoveryTask[];
-    /** Maximum follow-up depth including the initial dispatch. Default 3. */
-    maxRounds?: number;
-    /** Maximum tasks dispatched across all rounds. Default 24. */
-    maxTasks?: number;
-    /** Forwarded to the dispatcher. Default 4. */
-    concurrency?: number;
+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;
-    onRound?: (round: DiscoveryLoopRound) => Promise<void> | void;
+    now?: () => Date;
 }
-/**
- * Dispatch discovery tasks and recursively pursue worker-proposed follow-ups.
- *
- * The runner owns only bounded scheduling and accounting. Workers own search,
- * source verification, and domain-specific candidate shapes.
- */
-declare function runDiscoveryLoop(options: RunDiscoveryLoopOptions): Promise<DiscoveryLoopResult>;
-declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
-
-interface KnowledgeEventQuery {
-    type?: KnowledgeEventType;
-    target?: string;
-    limit?: number;
+interface RunRagKnowledgeImprovementLoopResult {
+    goal: string;
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+    answerQuality?: RagAnswerQualityResult;
+    promotion?: RagPromotionResult;
 }
-declare function createKnowledgeEvent(input: {
-    type: KnowledgeEventType;
-    actor?: string;
-    target?: string;
-    metadata?: Record<string, unknown>;
-    now?: () => Date;
-}): KnowledgeEvent;
+type MaybePromise$1<T> = T | Promise<T>;
+declare function runRagKnowledgeImprovementLoop(options: RunRagKnowledgeImprovementLoopOptions): Promise<RunRagKnowledgeImprovementLoopResult>;
 
-/**
- * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
- * was last successfully refreshed, and reports staleness against a TTL.
- *
- * The contract is intentionally minimal — just enough to drive a cron loop:
- *
- *   ```ts
- *   const store = createFileSystemFreshnessStore({ root: '.agent-knowledge' })
- *   for (const source of sources) {
- *     if (await store.stale({ workspaceId, sourceId: source.id, ttlMs: DAY })) {
- *       const fragments = await source.fetch({ cacheDir })
- *       await persistFragments(fragments)
- *       await store.mark({ workspaceId, sourceId: source.id, when: new Date() })
- *     }
- *   }
- *   ```
- *
- * Per-tenant isolation is enforced by `workspaceId` keying — there is no
- * global mutable state across workspaces.
- *
- * Two adapters ship in-package:
- *
- *   - `createFileSystemFreshnessStore` — JSON file under the knowledge root,
- *     mirrors the layout convention already used by `sources.json`.
- *   - `createD1FreshnessStoreStub` — adapter scaffold for Cloudflare D1 /
- *     Postgres. Production consumers should implement the `D1Adapter`
- *     interface inside their own app; this stub exists to anchor the shape.
- *
- * @stable contract — interface is frozen at 0.x within this major.
- * @stable filesystem adapter
- * @experimental D1 stub — interface will evolve as real consumers wire it.
- */
-/** Identity for one freshness record. */
-interface FreshnessKey {
-    workspaceId: string;
-    sourceId: string;
+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>;
 }
-/** TTL bound for staleness checks. */
-interface FreshnessTtl extends FreshnessKey {
-    /** Milliseconds — `Date.now() - last() > ttlMs` ⇒ stale. */
-    ttlMs: number;
-    /** Injected clock for deterministic tests; defaults to system time. */
-    now?: Date;
+interface RagEvalCitation {
+    id: string;
+    claimId?: string;
+    contextId?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+    quote?: string;
+    metadata?: Record<string, JsonValue>;
 }
-/** Mark argument. */
-interface FreshnessMark extends FreshnessKey {
-    when: Date;
-    /** Optional content hash captured at refresh time; aids debugging. */
-    contentHash?: string;
+interface RagEvalClaim {
+    id: string;
+    text: string;
+    citationIds?: readonly string[];
+    metadata?: Record<string, JsonValue>;
 }
-interface KnowledgeFreshnessStore {
-    /** Last refresh time, or null if never refreshed. */
-    last(key: FreshnessKey): Promise<Date | null>;
-    /** Record a successful refresh. */
-    mark(input: FreshnessMark): Promise<void>;
-    /** True iff `last(key)` is null or older than `ttlMs`. */
-    stale(input: FreshnessTtl): Promise<boolean>;
-    /** All records for a workspace — useful for dashboards / debugging. */
-    list(workspaceId: string): Promise<FreshnessRecord[]>;
+interface RagRequiredContext {
+    id?: string;
+    text?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
 }
-interface FreshnessRecord {
-    workspaceId: string;
-    sourceId: string;
-    lastRefreshedAt: string;
-    contentHash?: 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 FileSystemFreshnessStoreOptions {
-    /**
-     * Knowledge root. The store writes to `<root>/.agent-knowledge/freshness.json`,
-     * mirroring the convention used by `sources.json`.
-     */
-    root: string;
+interface ExternalRagEvalScore {
+    provider: RagEvalProvider | string;
+    scores: Record<string, number>;
+    reasons?: Record<string, string>;
+    metadata?: Record<string, JsonValue>;
 }
-/**
- * Filesystem-backed implementation. Single JSON file per knowledge root,
- * indexed by `${workspaceId}::${sourceId}`. Reads parse on every call —
- * cron tick rate is well below the cost of one JSON parse.
- *
- * Writes share the package-wide filesystem lock, so multiple workers cannot
- * overwrite one another or run through an interrupted knowledge promotion.
- */
-declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
-/**
- * D1 / Postgres adapter scaffold. Production consumers implement
- * `D1Adapter` against their own driver (better-sqlite3, postgres,
- * Cloudflare D1 binding, ...). This factory wires the adapter to the
- * `KnowledgeFreshnessStore` interface.
- *
- * The expected schema:
- *
- * ```sql
- * CREATE TABLE knowledge_freshness (
- *   workspace_id     TEXT NOT NULL,
- *   source_id        TEXT NOT NULL,
- *   last_refreshed_at TEXT NOT NULL,
- *   content_hash     TEXT,
- *   PRIMARY KEY (workspace_id, source_id)
- * );
- * ```
- */
-interface D1Adapter {
-    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
-    upsert(record: FreshnessRecord): Promise<void>;
-    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
+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>;
 }
-declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
-
-interface ParsedFrontmatter {
-    frontmatter: Record<string, unknown>;
-    body: string;
+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>>;
 }
-declare function parseFrontmatter(content: string): ParsedFrontmatter;
-declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
-
-declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
-
-declare function sha256(text: string): string;
-declare function slugify(input: string): string;
-declare function stableId(prefix: string, content: string): string;
-
-declare function buildKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
-declare function writeKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
-
-interface KnowledgeInspection {
-    pageCount: number;
-    sourceCount: number;
-    expiredSourceCount: number;
-    staleSourceCount: number;
-    edgeCount: number;
-    findingCount: number;
-    blockingFindingCount: number;
-    topPages: Array<{
-        path: string;
-        title: string;
-        degree: number;
-        sources: number;
-    }>;
-    sourceFreshness: SourceFreshnessInspection[];
-    findings: KnowledgeLintFinding[];
+interface RagAnswerQualityJudgeOptions {
+    name?: string;
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+    weights?: Partial<Record<RagEvalMetricKey, number>>;
+    externalScorePolicy?: 'prefer-external' | 'deterministic-first';
+    minClaimSupport?: number;
 }
-interface SourceFreshnessInspection {
-    id: string;
-    title?: string;
-    uri: string;
-    status: 'fresh' | 'expired' | 'unknown';
-    validUntil?: string;
-    lastVerifiedAt?: string;
+interface RagAnswerEvalCase {
+    scenario: RagAnswerEvalScenario;
+    artifact: RagAnswerEvalArtifact;
 }
-declare function inspectKnowledgeIndex(index: KnowledgeIndex, options?: {
+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;
-}): KnowledgeInspection;
-interface KnowledgeExplanation {
-    target: string;
-    page?: KnowledgePage;
-    sources: Array<{
-        id: string;
-        title?: string;
-        uri: string;
-    }>;
-    links: string[];
-    inbound: string[];
-    related: Array<{
-        path: string;
-        title: string;
-        score: number;
-    }>;
+    strict?: boolean;
+    minCitationRate?: number;
+    maxStaleSourceRate?: number;
 }
-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[];
+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[];
 }
-/**
- * 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.
- */
+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;
 
-/** 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;
+type KnowledgeImprovementStatus = 'running' | 'candidate-ready' | 'promoted' | 'rejected' | 'blocked';
+interface KnowledgeImprovementMetricProvenanceBase {
+    evaluator: string;
+    version: 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. */
+type KnowledgeImprovementMetricProvenance = (KnowledgeImprovementMetricProvenanceBase & {
+    method: 'deterministic';
+}) | (KnowledgeImprovementMetricProvenanceBase & {
+    method: 'sampled' | 'composite';
+    corpusHash: string;
+    runRecords: RunRecord[];
+}) | (KnowledgeImprovementMetricProvenanceBase & {
+    method: 'model';
+    model: string;
+    corpusHash: string;
+    runRecords: RunRecord[];
+});
+interface KnowledgeImprovementMetric {
+    score: number;
+    passed: boolean;
+    dimensions?: Record<string, number>;
+    notes?: string;
+    provenance: KnowledgeImprovementMetricProvenance;
+}
+interface KnowledgeImprovementEvaluationInput {
+    runId: string;
+    iteration: number;
     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;
+    baselineRoot: string;
+    candidateRoot: string;
+    baselineIndex: KnowledgeIndex;
+    candidateIndex: KnowledgeIndex;
+    baseHash: string;
+    candidateHash: string;
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    kbQuality: KnowledgeBaseQualityReport;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
     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[];
+type KnowledgeImprovementEvaluator = (input: KnowledgeImprovementEvaluationInput) => Promise<KnowledgeImprovementMetric> | KnowledgeImprovementMetric;
+interface KnowledgeImprovementCandidateRecord {
+    iteration: number;
+    candidateId: string;
+    baseHash: string;
+    candidateHash?: string;
+    evidenceHash?: string;
+    promotionPlanHash?: string;
+    status: KnowledgeImprovementStatus;
+    createdAt: string;
+    updatedAt: string;
 }
-declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
-
-interface KnowledgeResearchLoopContext {
+interface KnowledgeImprovementRunState {
+    runId: string;
     root: string;
     goal: string;
-    iteration: number;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    previousSteps: KnowledgeResearchLoopStep[];
-    signal?: AbortSignal;
+    status: KnowledgeImprovementStatus;
+    baseHash: string;
+    createdAt: string;
+    updatedAt: string;
+    ownerId?: string;
+    candidates: KnowledgeImprovementCandidateRecord[];
+    promotedCandidateId?: string;
+    blockedReason?: string;
 }
-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 KnowledgeImprovementResult {
+    runId: string;
+    state: KnowledgeImprovementRunState;
+    candidate?: KnowledgeImprovementCandidateRecord;
+    evaluation?: KnowledgeImprovementMetric;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
+    promoted: boolean;
+    blocked: boolean;
 }
-interface KnowledgeResearchLoopStep {
-    iteration: number;
-    notes?: string;
-    addedSources: SourceRecord[];
-    applied?: ApplyWriteBlocksResult;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    event: KnowledgeEvent;
-    done: boolean;
-    metadata?: Record<string, unknown>;
+declare const KnowledgeImprovementRunStateSchema: z.ZodObject<{
+    runId: z.ZodString;
+    root: z.ZodString;
+    goal: z.ZodString;
+    status: z.ZodEnum<{
+        rejected: "rejected";
+        promoted: "promoted";
+        running: "running";
+        "candidate-ready": "candidate-ready";
+        blocked: "blocked";
+    }>;
+    baseHash: z.ZodString;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+    ownerId: z.ZodOptional<z.ZodString>;
+    candidates: z.ZodArray<z.ZodObject<{
+        iteration: z.ZodNumber;
+        candidateId: z.ZodString;
+        baseHash: z.ZodString;
+        candidateHash: z.ZodOptional<z.ZodString>;
+        evidenceHash: z.ZodOptional<z.ZodString>;
+        promotionPlanHash: z.ZodOptional<z.ZodString>;
+        status: z.ZodEnum<{
+            rejected: "rejected";
+            promoted: "promoted";
+            running: "running";
+            "candidate-ready": "candidate-ready";
+            blocked: "blocked";
+        }>;
+        createdAt: z.ZodISODateTime;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    promotedCandidateId: z.ZodOptional<z.ZodString>;
+    blockedReason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const KnowledgeImprovementEvidenceSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"knowledge-improvement-evidence">;
+    runId: z.ZodString;
+    candidateId: z.ZodString;
+    iteration: z.ZodNumber;
+    goalHash: z.ZodString;
+    baseHash: z.ZodString;
+    candidateHash: z.ZodString;
+    promotionPlanHash: z.ZodString;
+    validation: z.ZodUnknown;
+    readiness: z.ZodNullable<z.ZodUnknown>;
+    kbQuality: z.ZodUnknown;
+    evaluation: z.ZodObject<{
+        score: z.ZodNumber;
+        passed: z.ZodBoolean;
+        dimensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        notes: z.ZodOptional<z.ZodString>;
+        provenance: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            evaluator: z.ZodString;
+            version: z.ZodString;
+            method: z.ZodLiteral<"deterministic">;
+        }, z.core.$strict>, z.ZodObject<{
+            evaluator: z.ZodString;
+            version: z.ZodString;
+            method: z.ZodEnum<{
+                composite: "composite";
+                sampled: "sampled";
+            }>;
+            corpusHash: z.ZodString;
+            runRecords: z.ZodArray<z.ZodCustom<RunRecord, RunRecord>>;
+        }, z.core.$strict>, z.ZodObject<{
+            evaluator: z.ZodString;
+            version: z.ZodString;
+            method: z.ZodLiteral<"model">;
+            model: z.ZodString;
+            corpusHash: z.ZodString;
+            runRecords: z.ZodArray<z.ZodCustom<RunRecord, RunRecord>>;
+        }, z.core.$strict>], "method">;
+    }, z.core.$strict>;
+    lifecycle: z.ZodNullable<z.ZodUnknown>;
+}, z.core.$strict>;
+type KnowledgeImprovementEvidence = z.infer<typeof KnowledgeImprovementEvidenceSchema>;
+/** Portable identity of one measured candidate. Paths and mutable run state are deliberately excluded. */
+declare const KnowledgeImprovementCandidateRefSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"knowledge-improvement-candidate">;
+    runId: z.ZodString;
+    candidateId: z.ZodString;
+    goalHash: z.ZodString;
+    baseHash: z.ZodString;
+    candidateHash: z.ZodString;
+    evidenceHash: z.ZodString;
+    promotionPlanHash: z.ZodString;
+}, z.core.$strict>;
+type KnowledgeImprovementCandidateRef = z.infer<typeof KnowledgeImprovementCandidateRefSchema>;
+interface PromoteKnowledgeCandidateOptions {
+    root: string;
+    candidate: KnowledgeImprovementCandidateRef;
+    ownerId?: string;
+    leaseTtlMs?: number;
+    now?: () => Date;
+    onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
 }
-interface RunKnowledgeResearchLoopOptions {
+interface UseKnowledgeImprovementCandidateOptions {
     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;
+    candidate: KnowledgeImprovementCandidateRef;
 }
-interface KnowledgeResearchLoopResult {
+interface ResolvedKnowledgeImprovementCandidate {
     root: string;
-    goal: string;
-    iterations: number;
-    done: boolean;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: KnowledgeResearchLoopStep[];
+    candidate: KnowledgeImprovementCandidateRef;
+    evaluation: KnowledgeImprovementMetric;
 }
-type KnowledgeControlLoopState = KnowledgeResearchLoopContext;
-type KnowledgeControlLoopAction = KnowledgeResearchLoopDecision;
-type KnowledgeControlLoopActionResult = KnowledgeResearchLoopStep;
-interface KnowledgeControlLoopAdapterOptions {
+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;
-    actor?: string;
+    runId?: string;
+    ownerId?: string;
+    leaseTtlMs?: number;
+    resume?: boolean;
+    maxCandidates?: number;
+    candidateResearchIterations?: number;
     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;
+    kbQuality?: KnowledgeBaseQualityOptions;
     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>;
+    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;
 }
-interface RunRagKnowledgeImprovementLoopResult {
-    goal: string;
-    phases: readonly RagKnowledgeImprovementPhaseResult[];
-    retrieval?: RunRetrievalImprovementLoopResult;
-    findings: readonly RagGapFinding[];
-    acquisition?: KnowledgeResearchLoopDecision;
-    knowledgeUpdate?: RagKnowledgeUpdateResult;
-    answerQuality?: RagAnswerQualityResult;
-    promotion?: RagPromotionResult;
+declare function knowledgeImprovementRunId(root: string, goal: string): string;
+declare function knowledgeImprovementRunDir(root: string, runId: string): string;
+declare function loadKnowledgeImprovementState(root: string, runId: string): Promise<KnowledgeImprovementRunState | null>;
+/** Freeze the exact knowledge bytes and measured evidence a later approval may promote. */
+declare function knowledgeImprovementCandidateRef(result: Pick<KnowledgeImprovementResult, 'runId' | 'state' | 'candidate'>): KnowledgeImprovementCandidateRef;
+/** Use one measured snapshot while its directory identity remains open and stable. */
+declare function withKnowledgeImprovementCandidate<T>(options: UseKnowledgeImprovementCandidateOptions, use: (candidate: ResolvedKnowledgeImprovementCandidate) => Promise<T> | T): Promise<T>;
+/** Promote one previously measured candidate without rerunning research or evaluation. */
+declare function promoteKnowledgeCandidate(options: PromoteKnowledgeCandidateOptions): Promise<KnowledgeImprovementResult>;
+declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
+interface KnowledgeImprovementEvent extends Record<string, unknown> {
+    at: string;
+    type: string;
+}
+declare function loadKnowledgeImprovementEvents(root: string, runId: string): Promise<KnowledgeImprovementEvent[]>;
+declare function hashKnowledgeBase(root: string): Promise<string>;
+
+/** Convert a measured knowledge candidate into the shared review and execution identity. */
+declare function toAgentCandidateKnowledgeRef(candidate: KnowledgeImprovementCandidateRef): AgentCandidateKnowledgeRef;
+/** Recover agent-knowledge's candidate identity from the shared contract. */
+declare function fromAgentCandidateKnowledgeRef(candidate: AgentCandidateKnowledgeRef): KnowledgeImprovementCandidateRef;
+
+/**
+ * Change detection across snapshots of one source's fragments.
+ *
+ * The output drives the continuous-ingestion loop: each `KnowledgeChange`
+ * carries the eval dimensions affected (`affectedDimensions`), which an
+ * agent-eval campaign scheduler consumes to decide which campaigns to
+ * re-run. Three change kinds:
+ *
+ *   - `added` — fragment id appears in `next` but not `prev`.
+ *   - `removed` — fragment id appears in `prev` but not `next`. Typical
+ *     trigger: an authority retires a Wex slug, or a state SOS reorganises
+ *     its forms catalogue.
+ *   - `modified` — fragment id appears in both, body hash differs. This
+ *     is the dominant change kind in practice — the Ryan-LLC v. FTC
+ *     vacatur case manifests as a `modified` on the Wex non-compete
+ *     fragment, NOT as a removed one.
+ *
+ * Unverifiable fragments are filtered out before diffing — comparing a
+ * captcha-blocked snapshot against a real one would falsely fire every
+ * fragment as removed. The caller can inspect the raw lists if they want
+ * to surface block-page failures.
+ *
+ * Within-snapshot duplicate ids are an upstream bug; this function picks
+ * the LAST one and emits a diagnostic via the `warnings` field.
+ *
+ * @stable
+ */
+type KnowledgeChangeKind = 'added' | 'removed' | 'modified';
+interface KnowledgeChange {
+    /** Source-scoped id (matches `KnowledgeFragment.id`). */
+    fragmentId: string;
+    kind: KnowledgeChangeKind;
+    /**
+     * For `added`: full body of the new fragment.
+     * For `removed`: full body of the prior fragment.
+     * For `modified`: unified-diff-style payload `{ before, after }` body strings.
+     */
+    diff?: {
+        before?: string;
+        after?: string;
+    };
+    /**
+     * Eval dimensions to re-score. Computed as the union of both fragments'
+     * `dimensionHints`. The eval cron treats this as a set of campaign tags.
+     */
+    affectedDimensions: string[];
+    /** URL of the affected authority page (from whichever side has it). */
+    url?: string;
+    /**
+     * Source-attested change time. For `modified`, takes the NEXT fragment's
+     * `sourceUpdatedAt`. For `removed`, takes the PRIOR fragment's
+     * `sourceUpdatedAt`. For `added`, takes the NEXT fragment's
+     * `sourceUpdatedAt`. Consumers index changes by this date.
+     */
+    detectedAt: string;
+}
+interface DetectChangesResult {
+    changes: KnowledgeChange[];
+    /** Counts by kind — handy for dashboards. */
+    summary: {
+        added: number;
+        removed: number;
+        modified: number;
+    };
+    /** Non-fatal diagnostics (duplicate ids, dropped unverifiable fragments). */
+    warnings: string[];
+}
+interface DetectChangesOptions {
+    /**
+     * When true (default), unverifiable fragments are dropped from both
+     * sides before comparison. Set false ONLY when debugging block-page
+     * issues — comparing against unverifiable content emits false
+     * `removed`/`modified` changes.
+     */
+    skipUnverifiable?: boolean;
+    /**
+     * When provided, only changes whose `affectedDimensions` intersect this
+     * set are returned. Useful for cron loops that schedule per-dimension
+     * eval campaigns and only care about a subset.
+     */
+    filterDimensions?: string[];
 }
-type MaybePromise$1<T> = T | Promise<T>;
-declare function runRagKnowledgeImprovementLoop(options: RunRagKnowledgeImprovementLoopOptions): Promise<RunRagKnowledgeImprovementLoopResult>;
+declare function detectChanges(prev: KnowledgeFragment[], next: KnowledgeFragment[], options?: DetectChangesOptions): DetectChangesResult;
 
-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 ChunkingOptions {
+    targetChars: number;
+    maxChars: number;
+    minChars: number;
+    overlapChars: number;
 }
-interface RagEvalClaim {
-    id: string;
+interface KnowledgeChunk {
+    index: number;
     text: string;
-    citationIds?: readonly string[];
-    metadata?: Record<string, JsonValue>;
+    headingPath: string;
+    charStart: number;
+    charEnd: number;
+    oversized: boolean;
 }
-interface RagRequiredContext {
-    id?: string;
-    text?: string;
-    pageId?: string;
-    sourceId?: string;
-    anchorId?: string;
+declare function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[];
+declare function stripFrontmatter(content: string): {
+    body: string;
+    bodyOffset: number;
+};
+
+/**
+ * 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
+ * cleanliness win is dominated by DE-DUPLICATION — which a deterministic
+ * content-hash / canonical-URL check captures at ~none of the LLM premium (see
+ * `docs/results/cost-quality.md`). That makes the LLM verifier look expensive
+ * for what a cheap rule already does.
+ *
+ * Claim-grounding targets a DIFFERENT, harder error band: a citation that is
+ * relevant and unique but **misattributed** — the page is on-topic, the URL is
+ * real, yet the specific CLAIM the source is cited for does NOT actually appear
+ * in the page. This is the citation-fabrication failure mode of LLM research:
+ * the model writes a plausible sentence and hangs a real URL off it that never
+ * says any such thing. Neither de-dup nor a relevance judge catches it (both can
+ * pass a misattributed-but-on-topic page); only checking the claim against the
+ * fetched text does.
+ *
+ * The check is EXECUTABLE GROUND TRUTH, not another LLM opinion: the worker
+ * attaches the specific claim it is citing the source for, and the verifier
+ * tests whether that claim is PRESENT (verbatim, normalized, or as a sufficient
+ * content-word overlap / close paraphrase) in the `htmlToText` output of the
+ * page the worker actually fetched. A claim that is not grounded is rejected as
+ * misattributed. Because the oracle is deterministic text presence — not a model
+ * call — it is a deployable, non-oracle verifier: it can run in production with
+ * zero inference cost, OR be composed with the LLM relevance verifier so the
+ * loop rejects BOTH off-topic AND misattributed sources.
+ *
+ * This module is content-free and any-topic: it adds (1) a way for a proposal to
+ * carry the claim it is cited for, (2) the `groundClaimInText` oracle, and (3) a
+ * `ResearchDriver` that gates on grounding. It composes the existing
+ * `ResearchDriver` / `ResearchSourceProposal` contracts and the shipped
+ * `htmlToText`; it reinvents none of them.
+ */
+
+/**
+ * Metadata key under which a proposal carries the specific claim it is cited
+ * for. The worker sets `metadata[citedClaimKey] = '<the claim>'`; the
+ * claim-grounding driver reads it and checks it against the fetched page text.
+ */
+declare const citedClaimKey = "citedClaim";
+/** Read the cited claim a proposal carries, if any. */
+declare function citedClaimOf(source: ResearchSourceProposal): string | undefined;
+/** Attach a cited claim to a proposal (immutably returns a new proposal). */
+declare function withCitedClaim(source: ResearchSourceProposal, claim: string): ResearchSourceProposal;
+interface GroundingResult {
+    /** True when the claim is sufficiently present in the page text. */
+    grounded: boolean;
+    /** How the claim matched (or why it didn't). For audit/notes. */
+    mode: 'verbatim' | 'normalized' | 'overlap' | 'absent' | 'empty-claim' | 'empty-text';
+    /**
+     * Fraction of the claim's content words found in the page text. 1 for a
+     * verbatim/normalized hit; the measured overlap otherwise.
+     */
+    overlap: number;
+    /** Content words present in the claim but NOT in the page text. */
+    missingWords: 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 GroundClaimOptions {
+    /**
+     * Minimum fraction of the claim's content words that must appear in the page
+     * text to count as a close paraphrase when there is no verbatim/normalized
+     * hit. Default 0.7 — a high bar, because a misattribution is exactly a claim
+     * whose specific words the page does not contain.
+     */
+    minOverlap?: number;
+    /**
+     * Content words shorter than this are ignored (drops "the", "of", "is", …)
+     * and never count toward overlap. Default 3.
+     */
+    minWordLength?: number;
 }
-interface ExternalRagEvalScore {
-    provider: RagEvalProvider | string;
-    scores: Record<string, number>;
-    reasons?: Record<string, string>;
-    metadata?: Record<string, JsonValue>;
+/**
+ * THE ORACLE. Is `claim` grounded in `pageText` (the `htmlToText` output of the
+ * page the worker fetched)? Deterministic, no model call:
+ *
+ *   1. verbatim — the claim string appears as-is (case-insensitive).
+ *   2. normalized — the claim appears after collapsing punctuation/whitespace
+ *      on both sides (so "5.4x" vs "5.4 x", smart quotes, etc. still match).
+ *   3. overlap — a close paraphrase: at least `minOverlap` of the claim's
+ *      substantive content words appear in the page text. A misattributed page
+ *      fails here because the SPECIFIC words the claim asserts are absent.
+ *
+ * Returns the match mode, the measured overlap, and the missing content words —
+ * enough for the driver to give a precise rejection reason and for a test/doc to
+ * audit WHY a claim grounded or didn't.
+ */
+declare function groundClaimInText(claim: string, pageText: string, options?: GroundClaimOptions): GroundingResult;
+interface ClaimGroundingDriverOptions extends GroundClaimOptions {
+    /**
+     * Optional second verifier to compose AFTER grounding passes. When set, a
+     * source must BOTH ground its claim AND pass this verifier (e.g. the LLM
+     * relevance driver's `verifySource`). Lets the loop reject off-topic AND
+     * misattributed sources in one driver. Omit for the pure, zero-inference
+     * grounding gate.
+     */
+    relevanceVerifier?: (source: ResearchSourceProposal, ctx: SourceVerificationContext) => Promise<SourceVerdict> | SourceVerdict;
+    /**
+     * What to do when a proposal carries NO cited claim. `'reject'` (default) is
+     * fail-closed: in claim-grounding mode every source must declare what it is
+     * cited for, so an un-annotated source is treated as ungrounded. `'accept'`
+     * lets un-annotated sources through to the relevance verifier (if any) —
+     * useful when mixing annotated and legacy proposals.
+     */
+    onMissingClaim?: 'reject' | 'accept';
 }
-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>;
+/**
+ * A `ResearchDriver`-shaped verifier (just the `verifySource` arm) that gates on
+ * CLAIM GROUNDING: it rejects a source whose cited claim is not present in its
+ * fetched page text — a misattributed / fabricated citation — and (optionally)
+ * composes a relevance verifier after grounding passes.
+ *
+ * The returned function matches `ResearchDriver['verifySource']`, so it drops
+ * straight into `runVerifiedResearchLoop` as `{ verifySource: createClaimGroundingVerifier(...) }`.
+ */
+declare function createClaimGroundingVerifier(options?: ClaimGroundingDriverOptions): (source: ResearchSourceProposal, ctx: SourceVerificationContext) => Promise<SourceVerdict>;
+interface WorkerClaimDecorationOptions {
+    router?: RouterClient;
+    router_options?: TangleRouterOptions;
+    /** Max output tokens for the claim-extraction call. Default 1200 (glm floor). */
+    maxTokens?: number;
 }
-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>>;
+/**
+ * Ask an LLM to state, for one source, the single specific factual claim a
+ * researcher would cite THIS page for toward the goal. Used to DECORATE the
+ * sources a relevance-only worker produced with the claim a citation would make,
+ * so the claim-grounding verifier has something executable to check. The model
+ * is told to ground the claim in the provided excerpt; the verifier then checks
+ * it against the FULL page text independently — the model does not get to mark
+ * its own homework.
+ *
+ * Returns the proposal annotated via `withCitedClaim`, or the original proposal
+ * unchanged if the model returns nothing parseable (the verifier's
+ * `onMissingClaim` policy then decides).
+ */
+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;
+    query?: string;
+    sourceHints?: string[];
+    metadata?: Record<string, unknown>;
 }
-interface RagAnswerQualityJudgeOptions {
-    name?: string;
-    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
-    weights?: Partial<Record<RagEvalMetricKey, number>>;
-    externalScorePolicy?: 'prefer-external' | 'deterministic-first';
-    minClaimSupport?: number;
+interface DiscoveryResult {
+    taskId: string;
+    summary: string;
+    sourceUris?: string[];
+    claims?: Array<{
+        text: string;
+        sourceUri?: string;
+        confidence?: number;
+    }>;
+    followUpTasks?: DiscoveryTask[];
+    metadata?: Record<string, unknown>;
 }
-interface RagAnswerEvalCase {
-    scenario: RagAnswerEvalScenario;
-    artifact: RagAnswerEvalArtifact;
+interface KnowledgeDiscoveryWorker {
+    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
 }
-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 KnowledgeDiscoveryDispatcher {
+    dispatch(tasks: DiscoveryTask[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryResult[]>;
 }
-interface RagCalibrationOptions {
-    scenario: RagAnswerEvalScenario;
-    strong: RagAnswerEvalArtifact;
-    weak: RagAnswerEvalArtifact;
-    judge?: JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
-    minStrongScore?: number;
-    maxWeakScore?: number;
-    signal?: AbortSignal;
+type DiscoveryLoopStopReason = 'complete' | 'max-rounds' | 'max-tasks' | 'aborted';
+interface DiscoveryLoopRound {
+    round: number;
+    tasks: DiscoveryTask[];
+    results: DiscoveryResult[];
+    queuedFollowUps: DiscoveryTask[];
 }
-interface RagCalibrationResult {
-    passed: boolean;
-    strongScore: number;
-    weakScore: number;
-    gap: number;
+interface DiscoveryLoopResult {
+    stopReason: DiscoveryLoopStopReason;
+    tasksDispatched: number;
+    results: DiscoveryResult[];
+    rounds: DiscoveryLoopRound[];
+    /** Tasks retained, not dropped, when a configured limit stops the loop. */
+    pendingTasks: DiscoveryTask[];
+    /** Structurally identical task identities ignored to prevent cycles. */
+    duplicateTaskIds: string[];
 }
-interface KnowledgeBaseQualityOptions {
-    now?: Date;
-    strict?: boolean;
-    minCitationRate?: number;
-    maxStaleSourceRate?: number;
+interface RunDiscoveryLoopOptions {
+    dispatcher: KnowledgeDiscoveryDispatcher;
+    initialTasks: readonly DiscoveryTask[];
+    /** Maximum follow-up depth including the initial dispatch. Default 3. */
+    maxRounds?: number;
+    /** Maximum tasks dispatched across all rounds. Default 24. */
+    maxTasks?: number;
+    /** Forwarded to the dispatcher. Default 4. */
+    concurrency?: number;
+    signal?: AbortSignal;
+    onRound?: (round: DiscoveryLoopRound) => Promise<void> | void;
 }
-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[];
+/**
+ * Dispatch discovery tasks and recursively pursue worker-proposed follow-ups.
+ *
+ * The runner owns only bounded scheduling and accounting. Workers own search,
+ * source verification, and domain-specific candidate shapes.
+ */
+declare function runDiscoveryLoop(options: RunDiscoveryLoopOptions): Promise<DiscoveryLoopResult>;
+declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
+
+interface KnowledgeEventQuery {
+    type?: KnowledgeEventType;
+    target?: string;
+    limit?: number;
 }
-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;
+declare function createKnowledgeEvent(input: {
+    type: KnowledgeEventType;
+    actor?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+    now?: () => Date;
+}): KnowledgeEvent;
 
-type KnowledgeImprovementStatus = 'running' | 'candidate-ready' | 'promoted' | 'rejected' | 'blocked';
-interface KnowledgeImprovementMetricProvenanceBase {
-    evaluator: string;
-    version: string;
+/**
+ * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
+ * was last successfully refreshed, and reports staleness against a TTL.
+ *
+ * The contract is intentionally minimal — just enough to drive a cron loop:
+ *
+ *   ```ts
+ *   const store = createFileSystemFreshnessStore({ root: '.agent-knowledge' })
+ *   for (const source of sources) {
+ *     if (await store.stale({ workspaceId, sourceId: source.id, ttlMs: DAY })) {
+ *       const fragments = await source.fetch({ cacheDir })
+ *       await persistFragments(fragments)
+ *       await store.mark({ workspaceId, sourceId: source.id, when: new Date() })
+ *     }
+ *   }
+ *   ```
+ *
+ * Per-tenant isolation is enforced by `workspaceId` keying — there is no
+ * global mutable state across workspaces.
+ *
+ * Two adapters ship in-package:
+ *
+ *   - `createFileSystemFreshnessStore` — JSON file under the knowledge root,
+ *     mirrors the layout convention already used by `sources.json`.
+ *   - `createD1FreshnessStoreStub` — adapter scaffold for Cloudflare D1 /
+ *     Postgres. Production consumers should implement the `D1Adapter`
+ *     interface inside their own app; this stub exists to anchor the shape.
+ *
+ * @stable contract — interface is frozen at 0.x within this major.
+ * @stable filesystem adapter
+ * @experimental D1 stub — interface will evolve as real consumers wire it.
+ */
+/** Identity for one freshness record. */
+interface FreshnessKey {
+    workspaceId: string;
+    sourceId: string;
 }
-type KnowledgeImprovementMetricProvenance = (KnowledgeImprovementMetricProvenanceBase & {
-    method: 'deterministic';
-}) | (KnowledgeImprovementMetricProvenanceBase & {
-    method: 'sampled' | 'composite';
-    corpusHash: string;
-    runRecords: RunRecord[];
-}) | (KnowledgeImprovementMetricProvenanceBase & {
-    method: 'model';
-    model: string;
-    corpusHash: string;
-    runRecords: RunRecord[];
-});
-interface KnowledgeImprovementMetric {
-    score: number;
-    passed: boolean;
-    dimensions?: Record<string, number>;
-    notes?: string;
-    provenance: KnowledgeImprovementMetricProvenance;
+/** TTL bound for staleness checks. */
+interface FreshnessTtl extends FreshnessKey {
+    /** Milliseconds — `Date.now() - last() > ttlMs` ⇒ stale. */
+    ttlMs: number;
+    /** Injected clock for deterministic tests; defaults to system time. */
+    now?: Date;
 }
-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;
+/** Mark argument. */
+interface FreshnessMark extends FreshnessKey {
+    when: Date;
+    /** Optional content hash captured at refresh time; aids debugging. */
+    contentHash?: string;
+}
+interface KnowledgeFreshnessStore {
+    /** Last refresh time, or null if never refreshed. */
+    last(key: FreshnessKey): Promise<Date | null>;
+    /** Record a successful refresh. */
+    mark(input: FreshnessMark): Promise<void>;
+    /** True iff `last(key)` is null or older than `ttlMs`. */
+    stale(input: FreshnessTtl): Promise<boolean>;
+    /** All records for a workspace — useful for dashboards / debugging. */
+    list(workspaceId: string): Promise<FreshnessRecord[]>;
 }
-type KnowledgeImprovementEvaluator = (input: KnowledgeImprovementEvaluationInput) => Promise<KnowledgeImprovementMetric> | KnowledgeImprovementMetric;
-interface KnowledgeImprovementCandidateRecord {
-    iteration: number;
-    candidateId: string;
-    baseHash: string;
-    candidateHash?: string;
-    evidenceHash?: string;
-    promotionPlanHash?: string;
-    status: KnowledgeImprovementStatus;
-    createdAt: string;
-    updatedAt: string;
+interface FreshnessRecord {
+    workspaceId: string;
+    sourceId: string;
+    lastRefreshedAt: string;
+    contentHash?: string;
 }
-interface KnowledgeImprovementRunState {
-    schemaVersion: 1;
-    runId: string;
+interface FileSystemFreshnessStoreOptions {
+    /**
+     * Knowledge root. The store writes to `<root>/.agent-knowledge/freshness.json`,
+     * mirroring the convention used by `sources.json`.
+     */
     root: string;
-    goal: string;
-    status: KnowledgeImprovementStatus;
-    baseHash: string;
-    createdAt: string;
-    updatedAt: string;
-    ownerId?: string;
-    candidates: KnowledgeImprovementCandidateRecord[];
-    promotedCandidateId?: string;
-    blockedReason?: string;
 }
-interface KnowledgeImprovementResult {
-    runId: string;
-    state: KnowledgeImprovementRunState;
-    candidate?: KnowledgeImprovementCandidateRecord;
-    evaluation?: KnowledgeImprovementMetric;
-    lifecycle?: RunRagKnowledgeImprovementLoopResult;
-    promoted: boolean;
-    blocked: boolean;
+/**
+ * Filesystem-backed implementation. Single JSON file per knowledge root,
+ * indexed by `${workspaceId}::${sourceId}`. Reads parse on every call —
+ * cron tick rate is well below the cost of one JSON parse.
+ *
+ * Writes share the package-wide filesystem lock, so multiple workers cannot
+ * overwrite one another or run through an interrupted knowledge promotion.
+ */
+declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
+/**
+ * D1 / Postgres adapter scaffold. Production consumers implement
+ * `D1Adapter` against their own driver (better-sqlite3, postgres,
+ * Cloudflare D1 binding, ...). This factory wires the adapter to the
+ * `KnowledgeFreshnessStore` interface.
+ *
+ * The expected schema:
+ *
+ * ```sql
+ * CREATE TABLE knowledge_freshness (
+ *   workspace_id     TEXT NOT NULL,
+ *   source_id        TEXT NOT NULL,
+ *   last_refreshed_at TEXT NOT NULL,
+ *   content_hash     TEXT,
+ *   PRIMARY KEY (workspace_id, source_id)
+ * );
+ * ```
+ */
+interface D1Adapter {
+    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
+    upsert(record: FreshnessRecord): Promise<void>;
+    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
 }
-declare const KnowledgeImprovementRunStateSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    runId: z.ZodString;
-    root: z.ZodString;
-    goal: z.ZodString;
-    status: z.ZodEnum<{
-        rejected: "rejected";
-        promoted: "promoted";
-        running: "running";
-        "candidate-ready": "candidate-ready";
-        blocked: "blocked";
+declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
+
+interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
+}
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
+
+declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
+
+declare function sha256(text: string): string;
+declare function slugify(input: string): string;
+declare function stableId(prefix: string, content: string): string;
+
+declare function buildKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
+declare function writeKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
+
+interface KnowledgeInspection {
+    pageCount: number;
+    sourceCount: number;
+    expiredSourceCount: number;
+    staleSourceCount: number;
+    edgeCount: number;
+    findingCount: number;
+    blockingFindingCount: number;
+    topPages: Array<{
+        path: string;
+        title: string;
+        degree: number;
+        sources: number;
     }>;
-    baseHash: z.ZodString;
-    createdAt: z.ZodISODateTime;
-    updatedAt: z.ZodISODateTime;
-    ownerId: z.ZodOptional<z.ZodString>;
-    candidates: z.ZodArray<z.ZodObject<{
-        iteration: z.ZodNumber;
-        candidateId: z.ZodString;
-        baseHash: z.ZodString;
-        candidateHash: z.ZodOptional<z.ZodString>;
-        evidenceHash: z.ZodOptional<z.ZodString>;
-        promotionPlanHash: z.ZodOptional<z.ZodString>;
-        status: z.ZodEnum<{
-            rejected: "rejected";
-            promoted: "promoted";
-            running: "running";
-            "candidate-ready": "candidate-ready";
-            blocked: "blocked";
-        }>;
-        createdAt: z.ZodISODateTime;
-        updatedAt: z.ZodISODateTime;
-    }, z.core.$strict>>;
-    promotedCandidateId: z.ZodOptional<z.ZodString>;
-    blockedReason: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>;
-declare const KnowledgeImprovementEvidenceSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    kind: z.ZodLiteral<"knowledge-improvement-evidence">;
-    runId: z.ZodString;
-    candidateId: z.ZodString;
-    iteration: z.ZodNumber;
-    goalHash: z.ZodString;
-    baseHash: z.ZodString;
-    candidateHash: z.ZodString;
-    promotionPlanHash: z.ZodString;
-    validation: z.ZodUnknown;
-    readiness: z.ZodNullable<z.ZodUnknown>;
-    kbQuality: z.ZodUnknown;
-    evaluation: z.ZodObject<{
-        score: z.ZodNumber;
-        passed: z.ZodBoolean;
-        dimensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
-        notes: z.ZodOptional<z.ZodString>;
-        provenance: z.ZodDiscriminatedUnion<[z.ZodObject<{
-            evaluator: z.ZodString;
-            version: z.ZodString;
-            method: z.ZodLiteral<"deterministic">;
-        }, z.core.$strict>, z.ZodObject<{
-            evaluator: z.ZodString;
-            version: z.ZodString;
-            method: z.ZodEnum<{
-                composite: "composite";
-                sampled: "sampled";
-            }>;
-            corpusHash: z.ZodString;
-            runRecords: z.ZodArray<z.ZodCustom<RunRecord, RunRecord>>;
-        }, z.core.$strict>, z.ZodObject<{
-            evaluator: z.ZodString;
-            version: z.ZodString;
-            method: z.ZodLiteral<"model">;
-            model: z.ZodString;
-            corpusHash: z.ZodString;
-            runRecords: z.ZodArray<z.ZodCustom<RunRecord, RunRecord>>;
-        }, z.core.$strict>], "method">;
-    }, z.core.$strict>;
-    lifecycle: z.ZodNullable<z.ZodUnknown>;
-}, z.core.$strict>;
-type KnowledgeImprovementEvidence = z.infer<typeof KnowledgeImprovementEvidenceSchema>;
-/** Portable identity of one measured candidate. Paths and mutable run state are deliberately excluded. */
-declare const KnowledgeImprovementCandidateRefSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
-    kind: z.ZodLiteral<"knowledge-improvement-candidate">;
-    runId: z.ZodString;
-    candidateId: z.ZodString;
-    goalHash: z.ZodString;
-    baseHash: z.ZodString;
-    candidateHash: z.ZodString;
-    evidenceHash: z.ZodString;
-    promotionPlanHash: z.ZodString;
-}, z.core.$strict>;
-type KnowledgeImprovementCandidateRef = z.infer<typeof KnowledgeImprovementCandidateRefSchema>;
-interface PromoteKnowledgeCandidateOptions {
-    root: string;
-    candidate: KnowledgeImprovementCandidateRef;
-    ownerId?: string;
-    leaseTtlMs?: number;
-    now?: () => Date;
-    onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
+    sourceFreshness: SourceFreshnessInspection[];
+    findings: KnowledgeLintFinding[];
 }
-interface UseKnowledgeImprovementCandidateOptions {
-    root: string;
-    candidate: KnowledgeImprovementCandidateRef;
+interface SourceFreshnessInspection {
+    id: string;
+    title?: string;
+    uri: string;
+    status: 'fresh' | 'expired' | 'unknown';
+    validUntil?: string;
+    lastVerifiedAt?: string;
+}
+declare function inspectKnowledgeIndex(index: KnowledgeIndex, options?: {
+    now?: Date;
+}): KnowledgeInspection;
+interface KnowledgeExplanation {
+    target: string;
+    page?: KnowledgePage;
+    sources: Array<{
+        id: string;
+        title?: string;
+        uri: string;
+    }>;
+    links: string[];
+    inbound: string[];
+    related: Array<{
+        path: string;
+        title: string;
+        score: number;
+    }>;
+}
+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[];
 }
-interface ResolvedKnowledgeImprovementCandidate {
-    root: string;
-    candidate: KnowledgeImprovementCandidateRef;
-    evaluation: KnowledgeImprovementMetric;
+/** 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;
 }
-interface KnowledgeImprovementRetrievalOptions extends Omit<RunRetrievalImprovementLoopOptions, 'index' | 'runDir'> {
-    runDir?: RunRetrievalImprovementLoopOptions['runDir'];
+/** 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[];
 }
-interface KnowledgeImprovementUpdateInput extends RagKnowledgeUpdateInput {
-    runId: string;
-    iteration: number;
-    candidateId: string;
-    root: string;
-    baselineRoot: string;
-    candidateRoot: string;
-    baseHash: string;
+/**
+ * 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;
 }
-type KnowledgeImprovementUpdate = (input: KnowledgeImprovementUpdateInput) => Promise<RagKnowledgeUpdateResult> | RagKnowledgeUpdateResult;
-interface KnowledgeImprovementOptions {
+/**
+ * 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;
-    goal: string;
-    runId?: string;
-    ownerId?: string;
-    leaseTtlMs?: number;
-    resume?: 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;
+    /** 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;
-    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): Promise<KnowledgeImprovementRunState | null>;
-/** Freeze the exact knowledge bytes and measured evidence a later approval may promote. */
-declare function knowledgeImprovementCandidateRef(result: Pick<KnowledgeImprovementResult, 'runId' | 'state' | 'candidate'>): KnowledgeImprovementCandidateRef;
-/** Use one measured snapshot while its directory identity remains open and stable. */
-declare function withKnowledgeImprovementCandidate<T>(options: UseKnowledgeImprovementCandidateOptions, use: (candidate: ResolvedKnowledgeImprovementCandidate) => Promise<T> | T): Promise<T>;
-/** Promote one previously measured candidate without rerunning research or evaluation. */
-declare function promoteKnowledgeCandidate(options: PromoteKnowledgeCandidateOptions): Promise<KnowledgeImprovementResult>;
-declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
-interface KnowledgeImprovementEvent extends Record<string, unknown> {
-    at: string;
-    type: string;
+interface ThesisRunResult {
+    loop: VerifiedResearchLoopResult;
+    /** The synthesized thesis text. */
+    thesis: string;
+    /** Path of the thesis page written into the KB. */
+    thesisPath: string;
 }
-declare function loadKnowledgeImprovementEvents(root: string, runId: string): Promise<KnowledgeImprovementEvent[]>;
-declare function hashKnowledgeBase(root: string): Promise<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 KbStore {
     putSource(source: SourceRecord): Promise<void>;
@@ -2662,4 +2664,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 CompanyEvalCase, type D1Adapter, type DedupReason, type DeepQuestion, type DeepQuestionKind, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryLoopResult, type DiscoveryLoopRound, type DiscoveryLoopStopReason, 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 KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, 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 PendingKnowledgeMutation, type PromoteKnowledgeCandidateOptions, 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 RecoverPendingKnowledgeMutationOptions, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, type ResolvedKnowledgeImprovementCandidate, type RouterClient, RouterError, type RouterUsage, type RunDiscoveryLoopOptions, 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 UseKnowledgeImprovementCandidateOptions, 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, inspectPendingKnowledgeMutation, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, runDiscoveryLoop, 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, withKnowledgeImprovementCandidate, 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 DiscoveryLoopResult, type DiscoveryLoopRound, type DiscoveryLoopStopReason, 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 KnowledgeImprovementCandidateRef, KnowledgeImprovementCandidateRefSchema, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementEvent, type KnowledgeImprovementEvidence, KnowledgeImprovementEvidenceSchema, type KnowledgeImprovementMetric, type KnowledgeImprovementMetricProvenance, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, KnowledgeImprovementRunStateSchema, 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 PendingKnowledgeMutation, type PromoteKnowledgeCandidateOptions, 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 RecoverPendingKnowledgeMutationOptions, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, type ResolvedKnowledgeImprovementCandidate, type RouterClient, RouterError, type RouterUsage, type RunDiscoveryLoopOptions, 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 UseKnowledgeImprovementCandidateOptions, 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, fromAgentCandidateKnowledgeRef, gradeCompanyAgainstText, gradeFactAgainstText, groundClaimInText, hashKnowledgeBase, improveKnowledgeBase, initKnowledgeBase, inspectKnowledgeIndex, inspectPendingKnowledgeMutation, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementCandidateRef, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementEvents, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, promoteKnowledgeCandidate, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, recoverPendingKnowledgeMutation, runDiscoveryLoop, runInvestmentThesisTask, runKnowledgeResearchLoop, runRagKnowledgeImprovementLoop, runTwoAgentResearchLoop, runVerifiedResearchLoop, scoreKnowledgeBaseIndex, scoreRagAnswerArtifact, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, thesisReadinessSpecs, toAgentCandidateKnowledgeRef, toDeepEvalTestCases, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, withKnowledgeImprovementCandidate, writeJson, writeKnowledgeIndex, writeSourceRegistry };