@tangle-network/agent-knowledge 1.9.0 → 1.11.0

package/dist/index.d.ts

@@ -1,11 +1,15 @@
-import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as KnowledgeEventType, f as KnowledgeEvent, g as KnowledgePage, b as KnowledgeGraph, h as KnowledgeLintFinding, i as KnowledgeWriteBlock, j as KnowledgeClaim, k as KnowledgeRelease, l as SourceRegistry, m as KnowledgeWriteParseResult } from './types-BEDGlXB-.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-BEDGlXB-.js';
+import { S as SourceRecord, c as KnowledgeIndex, d as KnowledgeSearchResult, e as SourceRegistry, f as KnowledgeEvent, g as KnowledgeEventType, h as KnowledgePage, b as KnowledgeGraph, i as KnowledgeLintFinding, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as KnowledgeWriteParseResult } from './types-C17sAROL.js';
+export { C as ClaimRef, n as KnowledgeBaseCandidate, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-C17sAROL.js';
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard } from '@tangle-network/agent-eval';
+import { R as RunRetrievalImprovementLoopResult, a as RunRetrievalImprovementLoopOptions, b as RetrievalConfig } from './index-Cj5jRXOz.js';
+export { B as BuildRetrievalBenchmarkCasesFromQrelsOptions, c as BuildRetrievalEvalDispatchOptions, d as BuildRetrievalParameterCandidatesOptions, I as INDUSTRY_MEMORY_BENCHMARKS, e as INDUSTRY_RAG_BENCHMARKS, K as KnowledgeAnswerBenchmarkCase, f as KnowledgeAnswerBenchmarkTaskKind, g as KnowledgeBenchmarkArtifact, h as KnowledgeBenchmarkCase, i as KnowledgeBenchmarkCaseBase, j as KnowledgeBenchmarkDistribution, k as KnowledgeBenchmarkEvaluation, l as KnowledgeBenchmarkFamily, m as KnowledgeBenchmarkReport, n as KnowledgeBenchmarkResponder, o as KnowledgeBenchmarkScenario, p as KnowledgeBenchmarkSliceSummary, q as KnowledgeBenchmarkSource, r as KnowledgeBenchmarkSpec, s as KnowledgeBenchmarkSplit, t as KnowledgeBenchmarkTaskKind, u as KnowledgeClaimMatcher, v as KnowledgeMemoryBenchmarkCase, w as KnowledgeMemoryBenchmarkTaskKind, x as KnowledgeMemoryEvent, y as KnowledgeMemoryFactMatcher, z as KnowledgeRetrievalBenchmarkCase, A as KnowledgeRetrievalBenchmarkQrel, C as KnowledgeRetrievalBenchmarkQuery, M as MemoryAdapterBenchmarkCandidate, D as MemoryAdapterBenchmarkRankingRow, E as RetrievalEvalArtifact, F as RetrievalEvalRetriever, G as RetrievalEvalRetrieverInput, H as RetrievalEvalRetrieverResult, J as RetrievalEvalScenario, L as RetrievalGoldTarget, N as RetrievalMetricSummary, O as RetrievalMetricWeights, P as RetrievalParameterSearchSpace, Q as RetrievalParameterSweepProposerOptions, S as RetrievalRecallJudgeOptions, T as RetrievedKnowledgeHit, U as RetrievedSourceSpan, V as RunKnowledgeBenchmarkSuiteOptions, W as RunKnowledgeBenchmarkSuiteResult, X as RunMemoryAdapterBenchmarkOptions, Y as RunMemoryAdapterBenchmarkResult, Z as buildFirstPartyMemoryLifecycleBenchmarkCases, _ as buildIndustryMemoryBenchmarkSmokeCases, $ as buildIndustryRagBenchmarkSmokeCases, a0 as buildKnowledgeBenchmarkScenarios, a1 as buildRetrievalBenchmarkCasesFromQrels, a2 as buildRetrievalEvalDispatch, a3 as buildRetrievalParameterCandidates, a4 as createInMemoryBenchmarkAdapter, a5 as createMemoryAdapterBenchmarkResponder, a6 as createNoopMemoryBenchmarkAdapter, a7 as isKnowledgeMemoryBenchmarkCase, a8 as knowledgeBenchmarkJudge, a9 as parseKnowledgeBenchmarkJsonl, aa as parseKnowledgeBenchmarkQrels, ab as renderKnowledgeBenchmarkReportMarkdown, ac as respondToIndustryMemoryBenchmarkSmokeCase, ad as respondToIndustryRagBenchmarkSmokeCase, ae as retrievalConfigFromSurface, af as retrievalConfigSurface, ag as retrievalParameterSweepProposer, ah as retrievalRecallJudge, ai as runKnowledgeBenchmarkSuite, aj as runMemoryAdapterBenchmark, ak as runRetrievalImprovementLoop, al as scoreKnowledgeBenchmarkArtifact, am as scoreMemoryBenchmarkArtifact, an as scoreRetrievalArtifact, ao as summarizeKnowledgeBenchmarkCampaign } from './index-Cj5jRXOz.js';
 import { KnowledgeFragment } from './sources/index.js';
 export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from './sources/index.js';
-import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
-export { AgentMemoryAdapter, AgentMemoryContext, AgentMemoryHit, AgentMemoryHitSchema, AgentMemoryKind, AgentMemoryKindSchema, AgentMemoryScope, AgentMemoryScopeSchema, AgentMemorySearchOptions, AgentMemoryWriteInput, AgentMemoryWriteInputSchema, AgentMemoryWriteResult, Neo4jAgentMemoryAdapterOptions, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, memoryHitToSourceRecord, memoryWriteResultToSourceRecord, renderMemoryContext } from './memory/index.js';
-import { Budget, ExecutorConfig, SuperviseOptions, DeliverableSpec, SupervisedResult } from '@tangle-network/agent-runtime/loops';
+import { JsonValue, Scenario, JudgeConfig } from '@tangle-network/agent-eval/campaign';
+export { AgentMemoryHitSchema, AgentMemoryKindSchema, AgentMemoryScopeSchema, AgentMemoryWriteInputSchema, Neo4jAgentMemoryAdapterOptions, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, memoryHitToSourceRecord, memoryWriteResultToSourceRecord, renderMemoryContext } from './memory/index.js';
+export { A as AgentMemoryAdapter, b as AgentMemoryContext, c as AgentMemoryHit, d as AgentMemoryKind, a as AgentMemoryScope, e as AgentMemorySearchOptions, f as AgentMemoryWriteInput, g as AgentMemoryWriteResult, R as RetrievalHoldoutBypassReason, h as RetrievalHoldoutCallContext, i as RetrievalHoldoutConfig, j as RetrievalHoldoutEligibleItem, k as RetrievalHoldoutEvent, l as RetrievalHoldoutOffPolicyOptions, m as RetrievalHoldoutOffPolicyResult, n as RetrievalHoldoutResult, o as RetrievalHoldoutSessionState, p as RetrievalHoldoutSessionSummary, q as applyRetrievalHoldout, r as applySessionStickyRetrievalHoldout, s as deterministicRng, t as emitRetrievalHoldoutBypass, u as resetRetrievalHoldoutRegistry, v as retrievalHoldoutConfigHash, w as toOffPolicyTrajectory } from './types-CjqPcTTK.js';
 import { z } from 'zod';
+import '@tangle-network/agent-eval/rl';
 
 interface SourceAdapterInput {
     uri: string;
@@ -28,140 +32,6 @@ interface SourceAdapter {
 declare const textSourceAdapter: SourceAdapter;
 declare function mediaTypeFor(uri: string): string;
 
-/**
- * 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[];
-}
-declare function detectChanges(prev: KnowledgeFragment[], next: KnowledgeFragment[], options?: DetectChangesOptions): DetectChangesResult;
-
-interface ChunkingOptions {
-    targetChars: number;
-    maxChars: number;
-    minChars: number;
-    overlapChars: number;
-}
-interface KnowledgeChunk {
-    index: number;
-    text: string;
-    headingPath: string;
-    charStart: number;
-    charEnd: number;
-    oversized: boolean;
-}
-declare function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[];
-declare function stripFrontmatter(content: string): {
-    body: string;
-    bodyOffset: number;
-};
-
-interface DiscoveryTask {
-    id: string;
-    goal: string;
-    query?: string;
-    sourceHints?: string[];
-    metadata?: Record<string, unknown>;
-}
-interface DiscoveryResult {
-    taskId: string;
-    summary: string;
-    sourceUris?: string[];
-    claims?: Array<{
-        text: string;
-        sourceUri?: string;
-        confidence?: number;
-    }>;
-    followUpTasks?: DiscoveryTask[];
-    metadata?: Record<string, unknown>;
-}
-interface KnowledgeDiscoveryWorker {
-    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
-}
-interface KnowledgeDiscoveryDispatcher {
-    dispatch(tasks: DiscoveryTask[], options?: {
-        concurrency?: number;
-        signal?: AbortSignal;
-    }): Promise<DiscoveryResult[]>;
-}
-declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
-
 interface KnowledgeReadinessSpec {
     id: string;
     description: string;
@@ -252,1059 +122,2356 @@ interface EvalKnowledgeBundleBuildResult {
 }
 declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
 
-interface KnowledgeEventQuery {
-    type?: KnowledgeEventType;
-    target?: string;
-    limit?: number;
+interface AddSourceOptions {
+    copyIntoRaw?: boolean;
+    adapters?: SourceAdapter[];
+    now?: () => Date;
 }
-declare function createKnowledgeEvent(input: {
-    type: KnowledgeEventType;
-    actor?: string;
-    target?: string;
+interface AddSourceTextInput {
+    uri: string;
+    text: string;
+    title?: string;
+    mediaType?: string;
+    validUntil?: string;
+    lastVerifiedAt?: string;
     metadata?: Record<string, unknown>;
-    now?: () => Date;
-}): KnowledgeEvent;
+}
+declare function loadSourceRegistry(root: string): Promise<SourceRegistry>;
+declare function writeSourceRegistry(root: string, registry: SourceRegistry): Promise<void>;
+declare function addSourcePath(root: string, sourcePath: string, options?: AddSourceOptions): Promise<SourceRecord[]>;
+declare function addSourceText(root: string, input: AddSourceTextInput, options?: Pick<AddSourceOptions, 'adapters' | 'now'>): Promise<SourceRecord>;
+declare function sourceRegistryPath(root: string): 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.
+ * A knowledge gap the loop surfaces from `scoreKnowledgeReadiness`. The worker
+ * targets these; the driver folds the unfilled remainder into the worker's next
+ * prompt and runs its own gap-fill pass over them.
  */
-/** Identity for one freshness record. */
-interface FreshnessKey {
-    workspaceId: string;
-    sourceId: string;
-}
-/** 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;
-}
-/** 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[]>;
-}
-interface FreshnessRecord {
-    workspaceId: string;
-    sourceId: string;
-    lastRefreshedAt: string;
-    contentHash?: string;
-}
-interface FileSystemFreshnessStoreOptions {
-    /**
-     * Knowledge root. The store writes to `<root>/.agent-knowledge/freshness.json`,
-     * mirroring the convention used by `sources.json`.
-     */
-    root: string;
+interface KnowledgeGap {
+    /** Readiness-spec id this gap belongs to. */
+    id: string;
+    /** Human-readable description of what's missing. */
+    description: string;
+    /** The search query the readiness check ran for this requirement. */
+    query: string;
+    /** True when the gap blocks readiness (vs. a soft, non-blocking gap). */
+    blocking: boolean;
 }
+/** A new source the worker (or driver) discovered and wants to add to the KB. */
+type ResearchSourceProposal = AddSourceTextInput;
 /**
- * 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.
+ * What a research agent contributes in one round. Both the worker and (when
+ * `driverResearches` is on) the driver produce this shape — the worker ADDS
+ * primary findings, the driver gap-FILLS the ones the worker missed.
  *
- * Concurrent writes from a single process serialize through `writeQueue`.
- * Cross-process concurrency is undefined; the consuming app should run the
- * cron in a single worker.
- */
-declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
+ * `proposalText` is the safe write-protocol text (`---FILE: knowledge/...---`
+ * blocks). The loop only applies it AFTER the driver has verified the round's
+ * sources, so a rejected source never reaches the curated pages.
+ */
+interface ResearchContribution {
+    /** Immutable sources to register (the raw evidence). */
+    sources?: ResearchSourceProposal[];
+    /** Safe write-protocol text producing curated `knowledge/*.md` pages. */
+    proposalText?: string;
+    /**
+     * Build the page write-protocol text FROM the sources the driver accepted —
+     * the curated, citing pages the readiness gate searches. Receives the
+     * registered `SourceRecord`s (with their assigned ids, so a page's frontmatter
+     * `sources:` can cite them). Returns `---FILE: knowledge/...---` block text or
+     * `undefined`. Runs after verification, so a page never cites a rejected
+     * source. Concatenated after any static `proposalText`.
+     */
+    buildPages?: (acceptedSources: SourceRecord[]) => string | undefined;
+    /** Free-form research transcript — products can persist this. */
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Context handed to the worker each round. */
+interface WorkerResearchContext {
+    root: string;
+    goal: string;
+    round: number;
+    index: KnowledgeIndex;
+    /** Gaps the readiness gate currently reports — what the worker should close. */
+    gaps: KnowledgeGap[];
+    /** Steer text the driver folded in from the previous round's remaining gaps. */
+    steer?: string;
+    readiness: EvalKnowledgeBundleBuildResult;
+    signal?: AbortSignal;
+}
+/** Context handed to the driver's verifier for one candidate source. */
+interface SourceVerificationContext {
+    root: string;
+    goal: string;
+    round: number;
+    index: KnowledgeIndex;
+    gaps: KnowledgeGap[];
+    /** Sources already accepted earlier THIS round (in-round dedup). */
+    acceptedThisRound: ResearchSourceProposal[];
+    signal?: AbortSignal;
+}
+/** A single rejected source plus the reason the driver gave. */
+interface RejectedSource {
+    source: ResearchSourceProposal;
+    reason: string;
+}
+/** Context handed to the driver's gap-fill pass (only when `driverResearches`). */
+interface DriverResearchContext {
+    root: string;
+    goal: string;
+    round: number;
+    index: KnowledgeIndex;
+    /** Gaps STILL open after the worker's accepted contribution applied. */
+    remainingGaps: KnowledgeGap[];
+    readiness: EvalKnowledgeBundleBuildResult;
+    signal?: AbortSignal;
+}
 /**
- * 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 differentiated driver role.
  *
- * The expected schema:
+ * - `verifySource` — the gate the worker's additions pass before they commit.
+ *   Return `{ accept: true }` to keep a source or `{ accept: false, reason }`
+ *   to reject it (not real / not relevant / duplicate). The loop dedups exact
+ *   duplicates (same `uri` already in the KB or accepted this round) BEFORE
+ *   calling this, so the verifier only sees genuinely-new candidates.
+ * - `research` — the driver's OWN gap-fill pass over the gaps the worker left
+ *   open. Only invoked when `driverResearches` is true.
+ * - `foldGaps` — turn the remaining gaps into a steer string for the worker's
+ *   next prompt. Defaults to a compact bulleted list when omitted.
+ */
+interface ResearchDriver {
+    verifySource(source: ResearchSourceProposal, ctx: SourceVerificationContext): Promise<SourceVerdict> | SourceVerdict;
+    research?(ctx: DriverResearchContext): Promise<ResearchContribution> | ResearchContribution;
+    foldGaps?(gaps: KnowledgeGap[]): string;
+}
+type SourceVerdict = {
+    accept: true;
+} | {
+    accept: false;
+    reason: string;
+};
+/** The worker: primary research targeting the round's gaps. */
+type ResearchWorker = (ctx: WorkerResearchContext) => Promise<ResearchContribution> | ResearchContribution;
+interface VerifiedResearchLoopOptions {
+    root: string;
+    goal: string;
+    worker: ResearchWorker;
+    driver: ResearchDriver;
+    /**
+     * When false (default), the driver ONLY verifies + gates — a pure coordinator
+     * that contributes no research of its own (the "doesn't participate in the
+     * work" mode). When true, the driver also runs its `research` gap-fill pass
+     * each round over the gaps the worker left open.
+     */
+    driverResearches?: boolean;
+    maxRounds?: number;
+    actor?: string;
+    /** Readiness specs define the gate; an empty list means the loop never gates. */
+    readinessSpecs?: KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
+    signal?: AbortSignal;
+    onRound?: (round: VerifiedResearchRound) => Promise<void> | void;
+}
+interface VerifiedResearchRound {
+    round: number;
+    /** Gaps reported at the START of the round (what the worker targeted). */
+    gaps: KnowledgeGap[];
+    /** Worker sources accepted by the driver and written to the KB. */
+    acceptedWorkerSources: SourceRecord[];
+    /** Worker sources the driver rejected (with reasons) — never written. */
+    rejectedWorkerSources: RejectedSource[];
+    /** Sources the driver itself added in its gap-fill pass. */
+    driverSources: SourceRecord[];
+    /** Curated pages written this round (worker proposal + driver proposal). */
+    writtenPages: string[];
+    readiness?: EvalKnowledgeBundleBuildResult;
+    /** True once the readiness gate reports no blocking gaps. */
+    ready: boolean;
+    event: KnowledgeEvent;
+    notes: {
+        worker?: string;
+        driver?: string;
+    };
+}
+interface VerifiedResearchLoopResult {
+    root: string;
+    goal: string;
+    rounds: number;
+    ready: boolean;
+    index: KnowledgeIndex;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    steps: VerifiedResearchRound[];
+}
+/**
+ * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
  *
- * ```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)
- * );
- * ```
+ * Both agents research to grow ONE knowledge base. The roles are differentiated:
+ *
+ * - **WORKER** = primary research. Each round it reads the open gaps, discovers
+ *   new sources, and proposes additions (`sources` + `proposalText`). It ADDS.
+ * - **DRIVER** = the verifier / gap-filler / gate. It (1) VERIFIES the worker's
+ *   sources before they commit — dedup against the KB, then `verifySource`
+ *   rejects ones that aren't real/relevant; (2) GAP-FILLS the gaps the worker
+ *   missed with its own research pass (when `driverResearches`); (3) folds the
+ *   remaining gaps into the worker's next prompt; and (4) GATES on
+ *   `scoreKnowledgeReadiness` — the loop stops as soon as there are no blocking
+ *   gaps.
+ *
+ * Set `driverResearches: false` (default) for the pure-coordinator mode: the
+ * driver only verifies + gates and contributes no research itself.
+ *
+ * Composes existing atoms — `initKnowledgeBase`, `addSourceText`,
+ * `applyKnowledgeWriteBlocks`, `buildEvalKnowledgeBundle` (the readiness gate),
+ * and `searchKnowledge` — and reinvents none of them.
  */
-interface D1Adapter {
-    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
-    upsert(record: FreshnessRecord): Promise<void>;
-    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
+declare function runVerifiedResearchLoop(options: VerifiedResearchLoopOptions): Promise<VerifiedResearchLoopResult>;
+/**
+ * Helper for verifiers: does the candidate source's text/title overlap any page
+ * the readiness search returns for a gap query? A cheap relevance heuristic the
+ * driver can compose into `verifySource` (real verifiers can do more).
+ */
+declare function sourceMatchesGaps(source: ResearchSourceProposal, index: KnowledgeIndex, gaps: KnowledgeGap[]): KnowledgeSearchResult[];
+/** @deprecated Renamed to {@link runVerifiedResearchLoop}. */
+declare const runTwoAgentResearchLoop: typeof runVerifiedResearchLoop;
+/** @deprecated Renamed to {@link VerifiedResearchLoopOptions}. */
+type TwoAgentResearchLoopOptions = VerifiedResearchLoopOptions;
+/** @deprecated Renamed to {@link VerifiedResearchLoopResult}. */
+type TwoAgentResearchLoopResult = VerifiedResearchLoopResult;
+/** @deprecated Renamed to {@link VerifiedResearchRound}. */
+type TwoAgentResearchRound = VerifiedResearchRound;
+
+/**
+ * Real web-research worker + verifying driver for `runVerifiedResearchLoop`.
+ *
+ * This is the GENERAL, any-topic implementation behind the two-agent research
+ * loop's live arm. Given the open knowledge gaps the readiness gate surfaces,
+ * the worker:
+ *
+ *   1. asks an LLM (glm-5.2 by default) to turn each gap into focused web
+ *      search queries,
+ *   2. runs a REAL web search over the Tangle router (`POST /v1/search` — the
+ *      same endpoint `tcloud mcp`'s `web_search` tool forwards to), so there is
+ *      no hardcoded corpus,
+ *   3. fetches the top results with the repo's polite, cached `politeFetch` and
+ *      reduces each page to text with `htmlToText`,
+ *   4. proposes the readable, verifiable pages as `ResearchSourceProposal`s plus
+ *      a `buildPages` that writes citing `knowledge/*.md` pages from the sources
+ *      the driver accepts.
+ *
+ * The verifying DRIVER is the differentiated role from the two-agent loop: a
+ * second LLM pass that judges each fetched source's on-topic relevance to the
+ * goal + open gaps and rejects off-topic / spam / already-covered material. The
+ * worker ADDS; the driver GATES. Together they build a cleaner knowledge base
+ * than a single agent at the same compute budget.
+ *
+ * Dependency-free on purpose: it talks to the router over `fetch` directly with
+ * the published OpenAI-compatible chat shape and the `/v1/search` shape, so it
+ * works whether or not the `tcloud` CLI is installed. Point it at any router by
+ * passing `baseUrl`; supply the key via `apiKey` or `TANGLE_API_KEY`.
+ */
+
+/** One live web result, as the router's `/v1/search` returns it. */
+interface WebSearchHit {
+    title: string;
+    url: string;
+    snippet?: string;
 }
-declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
+/**
+ * The two router capabilities the worker/driver need. Injectable so tests can
+ * stub the network; the default talks to the live Tangle router over `fetch`.
+ */
+interface RouterClient {
+    /** Live web search — returns title/url/snippet hits. */
+    search(query: string, opts?: {
+        maxResults?: number;
+    }): Promise<WebSearchHit[]>;
+    /** Chat completion — returns the assistant message's visible text. */
+    chat(messages: {
+        role: 'system' | 'user';
+        content: string;
+    }[], maxTokens?: number): Promise<string>;
+    /** Cumulative cost (chat + search) since this client was created. */
+    usage(): RouterUsage;
+}
+/**
+ * Cumulative router cost — the per-arm signal the A/B reports ALONGSIDE quality,
+ * so "2.3 fewer sources" can be read against the token/$/latency it cost. A
+ * two-agent round is one worker pass plus N `verifySource` LLM calls; counting
+ * each call here is what surfaces that the two-agent loop spends more inference
+ * than its "equal passes" budget implies.
+ */
+interface RouterUsage {
+    chatCalls: number;
+    searchCalls: number;
+    promptTokens: number;
+    completionTokens: number;
+    usd: number;
+    wallMs: number;
+}
+interface TangleRouterOptions {
+    /** Router base URL. Defaults to `https://router.tangle.tools/v1`. */
+    baseUrl?: string;
+    /** Bearer key. Defaults to `process.env.TANGLE_API_KEY`. */
+    apiKey?: string;
+    /** Chat model id. Defaults to `glm-5.2`. */
+    model?: string;
+    /** Optional preferred search provider (exa | you | perplexity | …). */
+    searchProvider?: string;
+    /**
+     * Retries on a TRANSIENT upstream status (502/503/504/429) with exponential
+     * backoff. Default 4. A 4xx that isn't 429, and a 401, are NOT retried — those
+     * are not transient. After the budget is exhausted the call still fails loud
+     * with the original `RouterError`, so the fail-closed contract holds; this only
+     * stops a single upstream-capacity blip from voiding a whole multi-topic run.
+     */
+    maxRetries?: number;
+    /** Base backoff in ms (doubled each retry, ±25% jitter). Default 1500. */
+    retryBaseMs?: number;
+    signal?: AbortSignal;
+}
+/** A small error so a failed router call fails loud rather than returning junk. */
+declare class RouterError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Build a dependency-free Tangle router client over `fetch`. This is the same
+ * wire surface the `tcloud` SDK + `tcloud mcp` use (`/v1/search` for web search,
+ * `/v1/chat/completions` for chat) so it needs no CLI installed.
+ */
+declare function createTangleRouterClient(options?: TangleRouterOptions): RouterClient;
+interface WebResearchWorkerOptions {
+    /** Router client. Defaults to a live Tangle router client from env creds. */
+    router?: RouterClient;
+    router_options?: TangleRouterOptions;
+    /** Max search queries the LLM may form per gap. Default 2. */
+    queriesPerGap?: number;
+    /** Max web results fetched per query. Default 3. */
+    resultsPerQuery?: number;
+    /** Hard cap on sources proposed per round (across all gaps). Default 6. */
+    maxSourcesPerRound?: number;
+    /** Disk cache dir for `politeFetch`. Optional; speeds repeat runs. */
+    cacheDir?: string;
+    /** Minimum readable text length to keep a fetched page. Default 200. */
+    minTextChars?: number;
+    /** Max chars of page text stored per source (keeps pages bounded). Default 4000. */
+    maxTextChars?: number;
+}
+/**
+ * The real web-research worker. Conforms to the loop's `ResearchWorker`
+ * contract: given the open gaps, it returns the sources it found plus a
+ * `buildPages` that emits citing pages from the sources the driver accepted.
+ */
+declare function createWebResearchWorker(options?: WebResearchWorkerOptions): ResearchWorker;
+interface VerifyingDriverOptions {
+    router?: RouterClient;
+    router_options?: TangleRouterOptions;
+    /**
+     * When the LLM verdict can't be parsed, default to REJECT (fail-closed) so a
+     * model hiccup never poisons the KB with an unverified source. Set `true` to
+     * accept-on-parse-failure only if you have a reason to. Default false.
+     */
+    acceptOnParseFailure?: boolean;
+}
+/**
+ * The verifying driver: a real LLM pass that judges each candidate source's
+ * on-topic relevance to the goal + open gaps and whether it duplicates material
+ * already accepted this round. This is the differentiated coordinator role — it
+ * GATES the worker's additions; it adds nothing itself.
+ *
+ * The loop already dedups exact-uri duplicates and only calls this on genuinely
+ * new candidates, so the verifier focuses on relevance + near-duplicate
+ * judgement, not bookkeeping.
+ */
+declare function createVerifyingResearchDriver(options?: VerifyingDriverOptions): ResearchDriver;
 
-interface ParsedFrontmatter {
-    frontmatter: Record<string, unknown>;
+/**
+ * Adaptive verifier mode for `runVerifiedResearchLoop`.
+ *
+ * The cost/quality A/B (`docs/results/cost-quality.md`) found the LLM relevance
+ * verifier's cleanliness win is dominated by DE-DUPLICATION — which a
+ * deterministic content-hash / canonical-URL check captures at ~none of the LLM
+ * premium — and that an LLM check only earns its dollar on the off-scope tail.
+ * The honest production move it names is: do the cheap deterministic work first,
+ * spend the LLM only where it pays. This module is that driver.
+ *
+ * Per candidate source the adaptive driver runs THREE stages, cheapest first,
+ * and stops at the first that decides:
+ *
+ *   1. DEDUP ($0, no LLM). Reject a source whose CONTENT (normalized-text hash)
+ *      or whose CANONICAL URL matches one already accepted this round or already
+ *      in the knowledge base. This is the de-dup the relevance judge was being
+ *      paid to do; doing it deterministically is free and exact.
+ *
+ *   2. HEURISTIC TRIAGE ($0, no LLM). For a unique survivor, a cheap host /
+ *      title / length signal classifies it as clearly-keep, clearly-drop, or
+ *      AMBIGUOUS. Clear cases are resolved without a model: an authoritative host
+ *      (arxiv, *.edu, *.gov, official docs) with a substantial readable body is
+ *      kept; an obvious spam/listicle/marketing title or a too-thin body is
+ *      dropped. Only genuinely ambiguous survivors fall through.
+ *
+ *   3. LLM ESCALATION ($, one call). ONLY the ambiguous survivors reach the LLM
+ *      `verifySource` — the shipped `createVerifyingResearchDriver` relevance
+ *      judge. This is where the verifier earns its premium: the off-scope tail a
+ *      cheap rule can't adjudicate.
+ *
+ * The result is the cost/quality frontier point the doc predicted: most of the
+ * cleanliness (dedup + clear drops) at a fraction of the LLM $/calls (only the
+ * ambiguous tail pays). It is a real `ResearchDriver` — same contract the
+ * two-agent loop already gates on — and reuses `sha256`, the relevance verifier,
+ * and the index; it reinvents none of them.
+ */
+
+/**
+ * Canonicalize a URL for duplicate detection: lowercase host, strip a leading
+ * `www.`, drop the scheme, the fragment, a trailing slash, and tracking query
+ * params (`utm_*`, `ref`, `fbclid`, `gclid`, …). Two URLs that differ only by
+ * those decorations canonicalize to the same key, so the dedup stage treats them
+ * as the same source. Falls back to the lowercased raw string when the input is
+ * not a parseable absolute URL (so non-http identifiers still dedup by equality).
+ */
+declare function canonicalizeUrl(uri: string): string;
+/**
+ * A stable content key for a fetched page: the sha256 of its normalized text
+ * (lowercased, punctuation/whitespace collapsed). Two pages whose readable body
+ * is the same modulo formatting collide here, so the dedup stage rejects a
+ * mirror/syndication of an already-accepted source even when the URL differs.
+ */
+declare function contentKey(text: string): string;
+/** Why the deterministic dedup stage rejected a candidate (for audit/notes). */
+type DedupReason = 'duplicate-url' | 'duplicate-content';
+/** The cheap-triage classification of a unique survivor. */
+type TriageClass = 'keep' | 'drop' | 'ambiguous';
+/** One source's adaptive routing decision, for instrumentation and the doc. */
+interface AdaptiveDecision {
+    uri: string;
+    /** The stage that decided this source: dedup | heuristic | llm. */
+    stage: 'dedup' | 'heuristic' | 'llm';
+    accepted: boolean;
+    /** The triage class assigned (set once past dedup). */
+    triage?: TriageClass;
+    reason?: string;
+}
+/** Running tally of where the adaptive driver spent its decisions. */
+interface AdaptiveStats {
+    total: number;
+    /** Rejected by deterministic dedup (URL or content). $0. */
+    dedupRejected: number;
+    /** Kept by the cheap heuristic without an LLM call. $0. */
+    heuristicKept: number;
+    /** Dropped by the cheap heuristic without an LLM call. $0. */
+    heuristicDropped: number;
+    /** Escalated to the LLM relevance verifier ($ — the only paid stage). */
+    llmCalls: number;
+    /** Of the escalations, how many the LLM accepted. */
+    llmAccepted: number;
+    decisions: AdaptiveDecision[];
+}
+interface AdaptiveDriverOptions {
+    /** Router client for the LLM escalation. Defaults to a live client from env. */
+    router?: RouterClient;
+    router_options?: TangleRouterOptions;
+    /** Passed through to the escalation relevance verifier. */
+    verifying?: Pick<VerifyingDriverOptions, 'acceptOnParseFailure'>;
+    /**
+     * Hosts an authoritative source lives on. A unique survivor on one of these,
+     * with a substantial body, is KEPT deterministically (no LLM). Suffix-matched
+     * against the canonical host, so `arxiv.org` matches `export.arxiv.org`. The
+     * defaults cover papers, official docs, and standards bodies.
+     */
+    authoritativeHosts?: string[];
+    /**
+     * Title/snippet patterns that mark obvious spam / listicle / marketing — a
+     * unique survivor matching one is DROPPED deterministically (no LLM).
+     */
+    spamPatterns?: RegExp[];
+    /**
+     * Below this many readable chars a survivor is too thin to be a real reference
+     * and is dropped deterministically. Default 400.
+     */
+    minBodyChars?: number;
+    /**
+     * A survivor whose body is at or above this many chars AND on an authoritative
+     * host is kept without an LLM call. Default 600.
+     */
+    substantialBodyChars?: number;
+    /** Receives each routing decision as it is made (for live instrumentation). */
+    onDecision?: (decision: AdaptiveDecision) => void;
+}
+/**
+ * Classify a UNIQUE survivor (already past dedup) with cheap host/title/length
+ * signals only — no LLM. Returns `keep`, `drop`, or `ambiguous`. `ambiguous` is
+ * the residue the LLM is reserved for: on-topic-looking pages on unknown hosts
+ * with a plausible body, which a host/title rule cannot adjudicate.
+ */
+declare function triageSource(source: ResearchSourceProposal, options: {
+    authoritativeHosts: string[];
+    spamPatterns: RegExp[];
+    minBodyChars: number;
+    substantialBodyChars: number;
+}): {
+    triage: TriageClass;
+    reason: string;
+};
+interface AdaptiveResearchDriver {
+    verifySource(source: ResearchSourceProposal, ctx: SourceVerificationContext): Promise<SourceVerdict>;
+    /** Live tally of where decisions were spent — the cost/quality instrumentation. */
+    stats(): AdaptiveStats;
+}
+/**
+ * Build the adaptive verifier. The deterministic stages (dedup + heuristic
+ * triage) cost $0; only AMBIGUOUS survivors escalate to the LLM relevance
+ * verifier. `stats()` exposes where every decision was spent so the A/B can read
+ * the LLM $/calls the adaptive driver saved against the cleanliness it kept.
+ *
+ * Dedup state is kept on the driver instance: it tracks the canonical URLs and
+ * content hashes it has ACCEPTED, plus those it sees in the verification
+ * context's `acceptedThisRound` and the KB index. Use one driver per loop run.
+ */
+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). */
+    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;
+
+interface ChunkingOptions {
+    targetChars: number;
+    maxChars: number;
+    minChars: number;
+    overlapChars: number;
+}
+interface KnowledgeChunk {
+    index: number;
+    text: string;
+    headingPath: string;
+    charStart: number;
+    charEnd: number;
+    oversized: boolean;
+}
+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 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;
+}
+/**
+ * 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';
+}
+/**
+ * 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;
 }
-declare function parseFrontmatter(content: string): ParsedFrontmatter;
-declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
-
-declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
+/**
+ * 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>;
 
-declare function sha256(text: string): string;
-declare function slugify(input: string): string;
-declare function stableId(prefix: string, content: string): string;
+/**
+ * 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.
+ */
 
-declare function buildKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
-declare function writeKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
+/**
+ * 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 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 SourceFreshnessInspection {
+interface DiscoveryTask {
     id: string;
-    title?: string;
-    uri: string;
-    status: 'fresh' | 'expired' | 'unknown';
-    validUntil?: string;
-    lastVerifiedAt?: string;
+    goal: string;
+    query?: string;
+    sourceHints?: string[];
+    metadata?: Record<string, unknown>;
 }
-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;
+interface DiscoveryResult {
+    taskId: string;
+    summary: string;
+    sourceUris?: string[];
+    claims?: Array<{
+        text: string;
+        sourceUri?: string;
+        confidence?: number;
     }>;
+    followUpTasks?: DiscoveryTask[];
+    metadata?: Record<string, unknown>;
 }
-declare function explainKnowledgeTarget(index: KnowledgeIndex, target: string): KnowledgeExplanation;
-
-interface KbStore {
-    putSource(source: SourceRecord): Promise<void>;
-    getSource(id: string): Promise<SourceRecord | null>;
-    listSources(): Promise<SourceRecord[]>;
-    putPage(page: KnowledgePage): Promise<void>;
-    getPage(idOrPath: string): Promise<KnowledgePage | null>;
-    listPages(): Promise<KnowledgePage[]>;
-    putIndex(index: KnowledgeIndex): Promise<void>;
-    getIndex(): Promise<KnowledgeIndex | null>;
-    putEvent(event: KnowledgeEvent): Promise<void>;
-    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
-}
-declare class MemoryKbStore implements KbStore {
-    private readonly sources;
-    private readonly pages;
-    private readonly events;
-    private index;
-    putSource(source: SourceRecord): Promise<void>;
-    getSource(id: string): Promise<SourceRecord | null>;
-    listSources(): Promise<SourceRecord[]>;
-    putPage(page: KnowledgePage): Promise<void>;
-    getPage(idOrPath: string): Promise<KnowledgePage | null>;
-    listPages(): Promise<KnowledgePage[]>;
-    putIndex(index: KnowledgeIndex): Promise<void>;
-    getIndex(): Promise<KnowledgeIndex | null>;
-    putEvent(event: KnowledgeEvent): Promise<void>;
-    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
+interface KnowledgeDiscoveryWorker {
+    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
 }
-declare class FileSystemKbStore extends MemoryKbStore {
-    private readonly dir;
-    constructor(dir: string);
-    putIndex(index: KnowledgeIndex): Promise<void>;
-    getIndex(): Promise<KnowledgeIndex | null>;
-    putEvent(event: KnowledgeEvent): Promise<void>;
+interface KnowledgeDiscoveryDispatcher {
+    dispatch(tasks: DiscoveryTask[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryResult[]>;
 }
+declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
 
-declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
-
-interface ApplyWriteBlocksResult {
-    written: string[];
-    warnings: string[];
+interface KnowledgeEventQuery {
+    type?: KnowledgeEventType;
+    target?: string;
+    limit?: number;
 }
-declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
-declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
+declare function createKnowledgeEvent(input: {
+    type: KnowledgeEventType;
+    actor?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+    now?: () => Date;
+}): KnowledgeEvent;
 
 /**
- * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
+ * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
+ * was last successfully refreshed, and reports staleness against a TTL.
  *
- * Closes the failure → wiki side of the recursive-self-improvement
- * loop: a knowledge-gap or knowledge-poisoning finding produced by an
- * analyst becomes a concrete proposal an operator (or auto-merge bot)
- * can review and apply. The bridge is intentionally lossless on the
- * fail-loud side — a finding the parser can't classify returns a
- * `KnowledgeProposalParseError` rather than a silent skip, so the
- * loop never accepts an underspecified edit.
+ * The contract is intentionally minimal — just enough to drive a cron loop:
  *
- * Subject grammar this bridge understands (analyst-side convention,
- * stamped in the kind prompts):
+ *   ```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() })
+ *     }
+ *   }
+ *   ```
  *
- *   agent-knowledge:wiki:<page-slug>            create / update page
- *   agent-knowledge:wiki:<page-slug>#<heading>  insert section under page
- *   agent-knowledge:claim:<topic>               draft claim row
- *   agent-knowledge:raw:<source-id>             lift raw → curated
- *   agent-knowledge:stale:<page-slug>           mark page superseded
+ * Per-tenant isolation is enforced by `workspaceId` keying — there is no
+ * global mutable state across workspaces.
  *
- * Anything else (websearch:outdated:*, tool-doc:*, system-prompt:*,
- * memory:*) is NOT a knowledge-base concern and returns `null` so the
- * loop's improvement-applier handles it.
+ * 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.
  */
-
-interface KnowledgeProposal {
-    /**
-     * Stable id derived from the finding so cross-run diffs share an
-     * identity. Re-proposing the same finding produces the same id.
-     */
-    id: string;
-    /** The finding that generated this proposal — useful for audit + revert. */
-    sourceFindingId: string;
-    /** What the proposal does. */
-    kind: 'create-page' | 'update-page' | 'append-section' | 'create-claim' | 'lift-raw' | 'mark-stale';
-    /** Locus on disk (page slug or claim topic). */
-    locus: string;
-    /**
-     * Page write blocks the standard `applyKnowledgeWriteBlocks` consumer
-     * accepts. Empty for proposals that don't change page text (e.g.
-     * `create-claim` produces a `claim` field instead).
-     */
-    writeBlocks: KnowledgeWriteBlock[];
-    /**
-     * Granular claim draft for proposals whose unit-of-change is a claim
-     * row rather than a whole page. `status: 'draft'` until reviewed.
-     */
-    claim?: KnowledgeClaim;
-    /** Per-proposal metadata: severity, confidence, source span. */
-    metadata: {
-        severity: AnalystSeverity;
-        confidence: number;
-        evidence_uri?: string;
-        analyst_id: string;
-    };
+/** Identity for one freshness record. */
+interface FreshnessKey {
+    workspaceId: string;
+    sourceId: string;
 }
-declare class KnowledgeProposalParseError extends Error {
-    readonly findingId: string;
-    readonly subject: string;
-    constructor(findingId: string, subject: string, message: string);
+/** 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;
+}
+/** 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[]>;
+}
+interface FreshnessRecord {
+    workspaceId: string;
+    sourceId: string;
+    lastRefreshedAt: string;
+    contentHash?: string;
+}
+interface FileSystemFreshnessStoreOptions {
+    /**
+     * Knowledge root. The store writes to `<root>/.agent-knowledge/freshness.json`,
+     * mirroring the convention used by `sources.json`.
+     */
+    root: string;
 }
 /**
- * Convert one `AnalystFinding` into a knowledge proposal. Returns
- * `null` when the finding's locus isn't a knowledge-base concern
- * (`websearch:outdated:*`, `tool-doc:*`, `system-prompt:*`,
- * `memory:*`, missing subject). Throws when the locus IS a
- * knowledge-base concern but is malformed — that's a bug in the
- * analyst prompt and should fail loud.
+ * 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.
  *
- * Caller convention: feed the function the analyst's full findings
- * list and filter out the `null`s; the orchestrator passes the
- * remaining proposals to the existing review / apply pipeline.
+ * Concurrent writes from a single process serialize through `writeQueue`.
+ * Cross-process concurrency is undefined; the consuming app should run the
+ * cron in a single worker.
  */
-declare function proposeFromFinding(finding: AnalystFinding): KnowledgeProposal | null;
+declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
 /**
- * Plural convenience: filter + map across an entire findings batch
- * with one call. Parse errors collect into `errors[]`; the loop
- * decides per-error whether to abort or continue.
+ * 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 ProposeFromFindingsResult {
-    proposals: KnowledgeProposal[];
-    skipped: number;
-    errors: KnowledgeProposalParseError[];
+interface D1Adapter {
+    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
+    upsert(record: FreshnessRecord): Promise<void>;
+    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
 }
-declare function proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): ProposeFromFindingsResult;
+declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
 
-interface KnowledgeReleaseReport {
-    release: KnowledgeRelease;
-    scorecard: ReleaseConfidenceScorecard;
-    candidateRuns: RunRecord[];
-    baselineRuns: RunRecord[];
-}
-/**
- * Campaign-native release report. The caller (a consumer's KB self-improvement
- * loop) supplies the candidate/baseline `RunRecord[]` (e.g. via
- * `campaignToRunRecords`) + optional per-instance `ReleaseTraceEvidence` + the
- * gate decision; this folds them into a `ReleaseConfidenceScorecard` + a
- * `KnowledgeRelease`. Release confidence is computed from run records + traces,
- * independent of any optimizer result shape.
- */
-interface KnowledgeReleaseInput {
-    candidateId: string;
-    baselineId?: string;
-    candidateRuns: RunRecord[];
-    baselineRuns?: RunRecord[];
-    traces?: ReleaseTraceEvidence[];
-    gateDecision?: GateDecision | null;
-    /**
-     * True when a held-out split was evaluated (drives the holdout threshold).
-     *
-     * Constraint: the substrate gate keys the holdout requirement off a scenario
-     * corpus, which this run-only report does not carry. With `hasHoldout: true`
-     * the gate fails closed (`missing_holdout_split`) even when holdout RunRecords
-     * are supplied. Callers that gate on a real held-out split should drive
-     * `evaluateReleaseConfidence` directly with a dataset/scenarios.
-     */
-    hasHoldout?: boolean;
-    /** Candidate is the search-best variant — a promotion precondition. Default true. */
-    promotedIsBest?: boolean;
-    createdAt?: string;
-    minScore?: number;
+interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
 }
-declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
 
-interface AddSourceOptions {
-    copyIntoRaw?: boolean;
-    adapters?: SourceAdapter[];
-    now?: () => Date;
+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 AddSourceTextInput {
-    uri: string;
-    text: string;
+interface SourceFreshnessInspection {
+    id: string;
     title?: string;
-    mediaType?: string;
+    uri: string;
+    status: 'fresh' | 'expired' | 'unknown';
     validUntil?: string;
     lastVerifiedAt?: string;
-    metadata?: Record<string, unknown>;
-}
-declare function loadSourceRegistry(root: string): Promise<SourceRegistry>;
-declare function writeSourceRegistry(root: string, registry: SourceRegistry): Promise<void>;
-declare function addSourcePath(root: string, sourcePath: string, options?: AddSourceOptions): Promise<SourceRecord[]>;
-declare function addSourceText(root: string, input: AddSourceTextInput, options?: Pick<AddSourceOptions, 'adapters' | 'now'>): Promise<SourceRecord>;
-declare function sourceRegistryPath(root: string): string;
-
-interface ValidateKnowledgeOptions {
-    strict?: boolean;
-}
-interface ValidateKnowledgeResult {
-    ok: boolean;
-    findings: KnowledgeLintFinding[];
-}
-declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
-
-interface KnowledgeResearchLoopContext {
-    root: string;
-    goal: string;
-    iteration: number;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    previousSteps: KnowledgeResearchLoopStep[];
-    signal?: AbortSignal;
-}
-interface KnowledgeResearchLoopDecision {
-    /**
-     * Free-form notes from the researcher. Keep this human-readable; products can
-     * store it as the research transcript.
-     */
-    notes?: string;
-    /**
-     * Local files to register as immutable sources before applying proposals.
-     */
-    sourcePaths?: string[];
-    /**
-     * Textual source artifacts discovered by an agent, browser worker, connector,
-     * or deep-research process.
-     */
-    sourceTexts?: AddSourceTextInput[];
-    /**
-     * Safe write protocol text. The loop parses and applies only accepted
-     * `---FILE: knowledge/...---` blocks.
-     */
-    proposalText?: string;
-    /**
-     * The researcher decides when the wiki is good enough. The loop deliberately
-     * does not encode a domain-specific definition of "done".
-     */
-    done?: boolean;
-    metadata?: Record<string, unknown>;
-}
-interface KnowledgeResearchLoopStep {
-    iteration: number;
-    notes?: string;
-    addedSources: SourceRecord[];
-    applied?: ApplyWriteBlocksResult;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    event: KnowledgeEvent;
-    done: boolean;
-    metadata?: Record<string, unknown>;
 }
-interface RunKnowledgeResearchLoopOptions {
-    root: string;
-    goal: string;
-    maxIterations?: number;
-    actor?: string;
-    strict?: ValidateKnowledgeOptions['strict'];
-    readinessSpecs?: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
-    signal?: AbortSignal;
-    step(context: KnowledgeResearchLoopContext): Promise<KnowledgeResearchLoopDecision> | KnowledgeResearchLoopDecision;
-    onStep?: (step: KnowledgeResearchLoopStep) => Promise<void> | void;
-}
-interface KnowledgeResearchLoopResult {
-    root: string;
-    goal: string;
-    iterations: number;
-    done: boolean;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: KnowledgeResearchLoopStep[];
-}
-type KnowledgeControlLoopState = KnowledgeResearchLoopContext;
-type KnowledgeControlLoopAction = KnowledgeResearchLoopDecision;
-type KnowledgeControlLoopActionResult = KnowledgeResearchLoopStep;
-interface KnowledgeControlLoopAdapterOptions {
-    root: string;
-    goal: string;
-    actor?: string;
-    strict?: ValidateKnowledgeOptions['strict'];
-    readinessSpecs?: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
-}
-type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoopState, KnowledgeControlLoopAction, KnowledgeControlLoopActionResult, ControlEvalResult>, 'intent' | 'observe' | 'validate' | 'act' | 'shouldStop'>;
-/**
- * Adapter for running knowledge growth through `agent-eval`'s generic control
- * runtime. The caller still owns `decide`: that can be a proposer agent,
- * reviewer agent, deterministic policy, or a composition of all three.
- */
-declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
-declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
+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;
 
 /**
- * Default standing instructions for a research supervisor. It does NOT solve the
- * research itself — it DECOMPOSES the goal into sub-topics and spawns one
- * researcher per sub-topic over the live `Scope`, widening/narrowing until the
- * readiness gate (the deliverable check) reports the knowledge base is ready.
+ * 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.
  */
-declare const RESEARCH_SUPERVISOR_SYSTEM_PROMPT: string;
-interface ResearchSupervisorOptions {
-    /** Where the knowledge base lives. The deliverable check reads readiness here. */
-    root: string;
-    /** The research goal handed to the supervisor as its task. */
-    goal: string;
+/** 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;
     /**
-     * Readiness specs define DONE: the supervisor's deliverable check passes once
-     * `scoreKnowledgeReadiness` reports no blocking gaps over the live KB. Required
-     * — without a gate the supervisor would never know when to stop.
+     * The 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.
      */
-    readinessSpecs: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    /** The conserved compute pool for the whole supervised run. */
-    budget: Budget;
+    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[];
     /**
-     * WHERE researcher workers run — the caller's real backend seam (sandbox with
-     * a `sandboxClient`, or router/cli/bridge). The supervisor spawns researchers
-     * on this backend; assembling the seam (creds, sandbox SDK) is the caller's,
-     * so there is no fabricated default.
+     * 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.
      */
-    backend: ExecutorConfig;
-    /** Harness for the researcher worker profile (default `researcherProfile`'s). */
-    harness?: string;
-    /** The supervisor brain's router model. */
-    supervisorModel?: string;
-    /** Custom supervisor instructions. Defaults to {@link RESEARCH_SUPERVISOR_SYSTEM_PROMPT}. */
-    supervisorSystemPrompt?: string;
-    /** Extra `supervise()` knobs (perWorker, maxLiveWorkers, router, allowedModels, …). */
-    superviseOptions?: Partial<Omit<SuperviseOptions, 'budget' | 'backend' | 'deliverable'>>;
+    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[];
 }
 /**
- * Build the deliverable (completion oracle) for a research supervisor: "settled
- * ⟺ the knowledge base is ready". It re-reads the KB from disk and runs the
- * readiness gate, so the supervisor stops on the REAL grounded state — not on a
- * worker's self-report.
+ * 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 function knowledgeReadinessDeliverable(options: Pick<ResearchSupervisorOptions, 'root' | 'goal' | 'readinessSpecs' | 'readinessTaskId' | 'readiness'>): DeliverableSpec<unknown>;
+declare const investmentThesisSet: CompanyEvalCase[];
 /**
- * A research supervisor: a SUPERVISOR brain creates the topology dynamically —
- * how many researchers, split by sub-topic — over the `Scope`, with the
- * knowledge-readiness gate as its stop condition.
- *
- * This is a thin wrapper over `supervise(profile, goal, opts)`. It composes the
- * existing pieces and builds nothing new: the researcher `AgentProfile` (from
- * `researcherProfile`) is the worker shape the supervisor spawns, and
- * `knowledgeReadinessDeliverable` (over `scoreKnowledgeReadiness`) is the
- * completion oracle that decides when the KB is ready.
- *
- * Needs creds (a real supervisor router brain + a worker backend), so it is the
- * LIVE path. The offline two-agent loop is `runTwoAgentResearchLoop`.
+ * 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 runResearchSupervisor(options: ResearchSupervisorOptions): Promise<SupervisedResult<unknown>>;
-
-declare const SourceAnchorSchema: z.ZodObject<{
-    id: z.ZodString;
-    sourceId: z.ZodString;
-    label: z.ZodOptional<z.ZodString>;
-    page: z.ZodOptional<z.ZodNumber>;
-    lineStart: z.ZodOptional<z.ZodNumber>;
-    lineEnd: z.ZodOptional<z.ZodNumber>;
-    charStart: z.ZodOptional<z.ZodNumber>;
-    charEnd: z.ZodOptional<z.ZodNumber>;
-    timestampMs: z.ZodOptional<z.ZodNumber>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-declare const SourceRecordSchema: z.ZodObject<{
-    id: z.ZodString;
-    uri: z.ZodString;
-    title: z.ZodOptional<z.ZodString>;
-    mediaType: z.ZodOptional<z.ZodString>;
-    contentHash: z.ZodString;
-    text: z.ZodOptional<z.ZodString>;
-    anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        sourceId: z.ZodString;
-        label: z.ZodOptional<z.ZodString>;
-        page: z.ZodOptional<z.ZodNumber>;
-        lineStart: z.ZodOptional<z.ZodNumber>;
-        lineEnd: z.ZodOptional<z.ZodNumber>;
-        charStart: z.ZodOptional<z.ZodNumber>;
-        charEnd: z.ZodOptional<z.ZodNumber>;
-        timestampMs: z.ZodOptional<z.ZodNumber>;
-        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    }, z.core.$strip>>>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    createdAt: z.ZodString;
-}, z.core.$strip>;
-declare const KnowledgePageSchema: z.ZodObject<{
-    id: z.ZodString;
-    path: z.ZodString;
-    title: z.ZodString;
-    text: z.ZodString;
-    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    sourceIds: z.ZodArray<z.ZodString>;
-    tags: z.ZodArray<z.ZodString>;
-    outLinks: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
-declare const KnowledgeGraphNodeSchema: z.ZodObject<{
-    id: z.ZodString;
-    title: z.ZodString;
-    path: z.ZodString;
-    tags: z.ZodArray<z.ZodString>;
-    sourceIds: z.ZodArray<z.ZodString>;
-    outDegree: z.ZodNumber;
-    inDegree: z.ZodNumber;
-}, z.core.$strip>;
-declare const KnowledgeGraphEdgeSchema: z.ZodObject<{
-    source: z.ZodString;
-    target: z.ZodString;
-    weight: z.ZodNumber;
-    reasons: z.ZodArray<z.ZodString>;
-}, z.core.$strip>;
-declare const KnowledgeIndexSchema: z.ZodObject<{
-    root: z.ZodString;
-    generatedAt: z.ZodString;
-    sources: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        uri: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-        mediaType: z.ZodOptional<z.ZodString>;
-        contentHash: z.ZodString;
-        text: z.ZodOptional<z.ZodString>;
-        anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            sourceId: z.ZodString;
-            label: z.ZodOptional<z.ZodString>;
-            page: z.ZodOptional<z.ZodNumber>;
-            lineStart: z.ZodOptional<z.ZodNumber>;
-            lineEnd: z.ZodOptional<z.ZodNumber>;
-            charStart: z.ZodOptional<z.ZodNumber>;
-            charEnd: z.ZodOptional<z.ZodNumber>;
-            timestampMs: z.ZodOptional<z.ZodNumber>;
-            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, z.core.$strip>>>;
-        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        createdAt: z.ZodString;
-    }, z.core.$strip>>;
-    pages: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        path: z.ZodString;
-        title: z.ZodString;
-        text: z.ZodString;
-        frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-        sourceIds: z.ZodArray<z.ZodString>;
-        tags: z.ZodArray<z.ZodString>;
-        outLinks: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
-    graph: z.ZodObject<{
-        nodes: z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            title: z.ZodString;
-            path: z.ZodString;
-            tags: z.ZodArray<z.ZodString>;
-            sourceIds: z.ZodArray<z.ZodString>;
-            outDegree: z.ZodNumber;
-            inDegree: z.ZodNumber;
-        }, z.core.$strip>>;
-        edges: z.ZodArray<z.ZodObject<{
-            source: z.ZodString;
-            target: z.ZodString;
-            weight: z.ZodNumber;
-            reasons: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>>;
-    }, z.core.$strip>;
-}, z.core.$strip>;
-declare const KnowledgeEventSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodEnum<{
-        "source.added": "source.added";
-        "proposal.applied": "proposal.applied";
-        "index.built": "index.built";
-        "lint.run": "lint.run";
-        "optimization.run": "optimization.run";
-        "release.promoted": "release.promoted";
-        "release.rejected": "release.rejected";
-    }>;
-    createdAt: z.ZodString;
-    actor: z.ZodOptional<z.ZodString>;
-    target: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-declare const KnowledgeBaseCandidateSchema: z.ZodObject<{
-    id: z.ZodString;
-    units: z.ZodArray<z.ZodObject<{
-        id: z.ZodString;
-        title: z.ZodString;
-        text: z.ZodString;
-        claims: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodString;
-            text: z.ZodString;
-            refs: z.ZodArray<z.ZodObject<{
-                sourceId: z.ZodString;
-                anchorId: z.ZodOptional<z.ZodString>;
-                quote: z.ZodOptional<z.ZodString>;
-            }, z.core.$strip>>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            status: z.ZodOptional<z.ZodEnum<{
-                draft: "draft";
-                active: "active";
-                superseded: "superseded";
-                rejected: "rejected";
-            }>>;
-            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, z.core.$strip>>>;
-        relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            sourceId: z.ZodString;
-            targetId: z.ZodString;
-            predicate: z.ZodString;
-            weight: z.ZodOptional<z.ZodNumber>;
-            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        }, z.core.$strip>>>;
-        sourceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        updatedAt: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    retrievalPolicy: z.ZodOptional<z.ZodString>;
-    synthesisPolicy: z.ZodOptional<z.ZodString>;
-    questionPolicy: z.ZodOptional<z.ZodString>;
-    updatePolicy: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-
-declare function searchKnowledge(index: KnowledgeIndex, query: string, limit?: number): KnowledgeSearchResult[];
-declare function tokenizeQuery(query: string): string[];
-declare function reciprocalRankFusion(rankLists: string[][], k?: number): Map<string, number>;
+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>;
 
-interface KnowledgeLayout {
-    root: string;
-    knowledgeDir: string;
-    rawSourcesDir: string;
-    sourceRegistryPath: string;
-    indexPath: string;
-    logPath: string;
-    cacheDir: string;
-}
-declare function layoutFor(root: string): KnowledgeLayout;
 /**
- * Filenames that `initKnowledgeBase` writes as human-navigation scaffolding.
- * These are excluded from the page index — they exist on disk so authors can
- * curate their vault, but they are not searchable content.
+ * The INVESTMENT-THESIS research task.
  *
- * Add new scaffold filenames here (and only here) to keep lint, validate, viz,
- * and the indexer consistent.
- */
-declare const SCAFFOLD_PAGE_BASENAMES: readonly string[];
-/**
- * True when a knowledge-relative path points at a scaffold file rather than
- * authored content. Accepts both repo-relative paths (`knowledge/index.md`)
- * and any nested `<dir>/index.md` or `<dir>/log.md` (for example
- * `knowledge/concepts/index.md`) so subdirectory README-style scaffolds are
- * also excluded.
+ * 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.
  */
-declare function isScaffoldPath(path: string): boolean;
-declare function initKnowledgeBase(root: string): Promise<KnowledgeLayout>;
-declare function loadKnowledgePages(root: string): Promise<KnowledgePage[]>;
-declare function writeJson(path: string, value: unknown): Promise<void>;
 
-/**
- * A knowledge gap the loop surfaces from `scoreKnowledgeReadiness`. The worker
- * targets these; the driver folds the unfilled remainder into the worker's next
- * prompt and runs its own gap-fill pass over them.
- */
-interface KnowledgeGap {
-    /** Readiness-spec id this gap belongs to. */
-    id: string;
-    /** Human-readable description of what's missing. */
-    description: string;
-    /** The search query the readiness check ran for this requirement. */
-    query: string;
-    /** True when the gap blocks readiness (vs. a soft, non-blocking gap). */
-    blocking: boolean;
+/** 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;
 }
-/** A new source the worker (or driver) discovered and wants to add to the KB. */
-type ResearchSourceProposal = AddSourceTextInput;
 /**
- * What a research agent contributes in one round. Both the worker and (when
- * `driverResearches` is on) the driver produce this shape — the worker ADDS
- * primary findings, the driver gap-FILLS the ones the worker missed.
+ * 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).
  *
- * `proposalText` is the safe write-protocol text (`---FILE: knowledge/...---`
- * blocks). The loop only applies it AFTER the driver has verified the round's
- * sources, so a rejected source never reaches the curated pages.
+ * `minSources` is set above 1 so the readiness gate stays UNMET after a single
+ * fetch and the loop runs multiple rounds — the depth-driving driver needs >1
+ * round to steer, exactly as the ML-exam multi-round probe established.
+ */
+declare function thesisReadinessSpecs(input: ThesisTaskInput): KnowledgeReadinessSpec[];
+interface ThesisRunOptions {
+    /** The KB root the loop writes into. */
+    root: string;
+    /** Shared router client (web search + chat). Defaults to env creds. */
+    router: RouterClient;
+    /** The driver — verify/dedup or research-driving. The loop's coordinator. */
+    driver: ResearchDriver;
+    /** Round budget. Default 3 (the depth-driving driver needs >1). */
+    maxRounds?: number;
+    /** Worker tuning forwarded to `createWebResearchWorker`. */
+    workerOptions?: Omit<WebResearchWorkerOptions, 'router'>;
+    /** Max tokens for the synthesis pass. Default 1600 (above glm-5.2's reasoning floor). */
+    synthesisMaxTokens?: number;
+    signal?: AbortSignal;
+}
+interface ThesisRunResult {
+    loop: VerifiedResearchLoopResult;
+    /** The synthesized thesis text. */
+    thesis: string;
+    /** Path of the thesis page written into the KB. */
+    thesisPath: string;
+}
+/**
+ * Run the full thesis task: drive the two-agent loop to research the company AS
+ * OF the cutoff, then synthesize + write the thesis page. Returns the loop result
+ * + the thesis text + the page path. The caller grades the KB with
+ * `materialFactsSurfaced(root, checklist)` — the checklist is never passed here.
  */
-interface ResearchContribution {
-    /** Immutable sources to register (the raw evidence). */
-    sources?: ResearchSourceProposal[];
-    /** Safe write-protocol text producing curated `knowledge/*.md` pages. */
+declare function runInvestmentThesisTask(input: ThesisTaskInput, options: ThesisRunOptions): Promise<ThesisRunResult>;
+
+interface ApplyWriteBlocksResult {
+    written: string[];
+    warnings: string[];
+}
+declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
+declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
+
+interface ValidateKnowledgeOptions {
+    strict?: boolean;
+}
+interface ValidateKnowledgeResult {
+    ok: boolean;
+    findings: KnowledgeLintFinding[];
+}
+declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+
+interface KnowledgeResearchLoopContext {
+    root: string;
+    goal: string;
+    iteration: number;
+    index: KnowledgeIndex;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    previousSteps: KnowledgeResearchLoopStep[];
+    signal?: AbortSignal;
+}
+interface KnowledgeResearchLoopDecision {
+    /**
+     * Free-form notes from the researcher. Keep this human-readable; products can
+     * store it as the research transcript.
+     */
+    notes?: string;
+    /**
+     * Local files to register as immutable sources before applying proposals.
+     */
+    sourcePaths?: string[];
+    /**
+     * Textual source artifacts discovered by an agent, browser worker, connector,
+     * or deep-research process.
+     */
+    sourceTexts?: AddSourceTextInput[];
+    /**
+     * Safe write protocol text. The loop parses and applies only accepted
+     * `---FILE: knowledge/...---` blocks.
+     */
     proposalText?: string;
     /**
-     * Build the page write-protocol text FROM the sources the driver accepted —
-     * the curated, citing pages the readiness gate searches. Receives the
-     * registered `SourceRecord`s (with their assigned ids, so a page's frontmatter
-     * `sources:` can cite them). Returns `---FILE: knowledge/...---` block text or
-     * `undefined`. Runs after verification, so a page never cites a rejected
-     * source. Concatenated after any static `proposalText`.
+     * The researcher decides when the wiki is good enough. The loop deliberately
+     * does not encode a domain-specific definition of "done".
      */
-    buildPages?: (acceptedSources: SourceRecord[]) => string | undefined;
-    /** Free-form research transcript — products can persist this. */
+    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>;
 }
-/** Context handed to the worker each round. */
-interface WorkerResearchContext {
+interface RunKnowledgeResearchLoopOptions {
     root: string;
     goal: string;
-    round: number;
-    index: KnowledgeIndex;
-    /** Gaps the readiness gate currently reports — what the worker should close. */
-    gaps: KnowledgeGap[];
-    /** Steer text the driver folded in from the previous round's remaining gaps. */
-    steer?: string;
-    readiness: EvalKnowledgeBundleBuildResult;
+    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;
 }
-/** Context handed to the driver's verifier for one candidate source. */
-interface SourceVerificationContext {
+interface KnowledgeResearchLoopResult {
     root: string;
     goal: string;
-    round: number;
+    iterations: number;
+    done: boolean;
     index: KnowledgeIndex;
-    gaps: KnowledgeGap[];
-    /** Sources already accepted earlier THIS round (in-round dedup). */
-    acceptedThisRound: ResearchSourceProposal[];
-    signal?: AbortSignal;
-}
-/** A single rejected source plus the reason the driver gave. */
-interface RejectedSource {
-    source: ResearchSourceProposal;
-    reason: string;
+    lintFindings: KnowledgeLintFinding[];
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    steps: KnowledgeResearchLoopStep[];
 }
-/** Context handed to the driver's gap-fill pass (only when `driverResearches`). */
-interface DriverResearchContext {
+type KnowledgeControlLoopState = KnowledgeResearchLoopContext;
+type KnowledgeControlLoopAction = KnowledgeResearchLoopDecision;
+type KnowledgeControlLoopActionResult = KnowledgeResearchLoopStep;
+interface KnowledgeControlLoopAdapterOptions {
     root: string;
     goal: string;
-    round: number;
-    index: KnowledgeIndex;
-    /** Gaps STILL open after the worker's accepted contribution applied. */
-    remainingGaps: KnowledgeGap[];
-    readiness: EvalKnowledgeBundleBuildResult;
-    signal?: AbortSignal;
+    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'>;
 /**
- * The differentiated driver role.
- *
- * - `verifySource` — the gate the worker's additions pass before they commit.
- *   Return `{ accept: true }` to keep a source or `{ accept: false, reason }`
- *   to reject it (not real / not relevant / duplicate). The loop dedups exact
- *   duplicates (same `uri` already in the KB or accepted this round) BEFORE
- *   calling this, so the verifier only sees genuinely-new candidates.
- * - `research` — the driver's OWN gap-fill pass over the gaps the worker left
- *   open. Only invoked when `driverResearches` is true.
- * - `foldGaps` — turn the remaining gaps into a steer string for the worker's
- *   next prompt. Defaults to a compact bulleted list when omitted.
+ * 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.
  */
-interface ResearchDriver {
-    verifySource(source: ResearchSourceProposal, ctx: SourceVerificationContext): Promise<SourceVerdict> | SourceVerdict;
-    research?(ctx: DriverResearchContext): Promise<ResearchContribution> | ResearchContribution;
-    foldGaps?(gaps: KnowledgeGap[]): string;
+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>;
 }
-type SourceVerdict = {
-    accept: true;
-} | {
-    accept: false;
+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;
-};
-/** The worker: primary research targeting the round's gaps. */
-type ResearchWorker = (ctx: WorkerResearchContext) => Promise<ResearchContribution> | ResearchContribution;
-interface TwoAgentResearchLoopOptions {
+    metadata?: Record<string, JsonValue>;
+}
+interface RagKnowledgeResearchOptions extends Omit<RunKnowledgeResearchLoopOptions, 'goal' | 'signal' | 'step'> {
+    goal?: string;
+    step?: RunKnowledgeResearchLoopOptions['step'];
+}
+interface RunRagKnowledgeImprovementLoopOptions {
+    goal: string;
+    retrieval?: RunRetrievalImprovementLoopOptions;
+    diagnose?: (input: RagDiagnosisInput) => MaybePromise$1<readonly RagGapFinding[]>;
+    acquireKnowledge?: (input: RagKnowledgeAcquisitionInput) => MaybePromise$1<KnowledgeResearchLoopDecision>;
+    knowledgeResearch?: RagKnowledgeResearchOptions;
+    updateKnowledge?: (input: RagKnowledgeUpdateInput) => MaybePromise$1<RagKnowledgeUpdateResult>;
+    evaluateAnswers?: (input: RagAnswerQualityInput) => MaybePromise$1<RagAnswerQualityResult>;
+    promote?: (input: RagPromotionInput) => MaybePromise$1<RagPromotionResult>;
+    enabledPhases?: readonly RagKnowledgeImprovementPhase[];
+    requiredPhases?: readonly RagKnowledgeImprovementPhase[];
+    signal?: AbortSignal;
+    now?: () => Date;
+}
+interface RunRagKnowledgeImprovementLoopResult {
+    goal: string;
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    retrieval?: RunRetrievalImprovementLoopResult;
+    findings: readonly RagGapFinding[];
+    acquisition?: KnowledgeResearchLoopDecision;
+    knowledgeUpdate?: RagKnowledgeUpdateResult;
+    answerQuality?: RagAnswerQualityResult;
+    promotion?: RagPromotionResult;
+}
+type MaybePromise$1<T> = T | Promise<T>;
+declare function runRagKnowledgeImprovementLoop(options: RunRagKnowledgeImprovementLoopOptions): Promise<RunRagKnowledgeImprovementLoopResult>;
+
+type RagEvalProvider = 'agent-knowledge' | 'ragas' | 'deepeval' | 'trulens' | 'ragchecker' | 'custom';
+type RagEvalMetricKey = 'context_precision' | 'context_recall' | 'context_relevance' | 'context_sufficiency' | 'faithfulness' | 'groundedness' | 'answer_relevance' | 'answer_correctness' | 'citation_support' | 'abstention' | 'unsupported_answer_rate';
+type RagEvalSlice = 'known-answer' | 'paraphrase' | 'distractor' | 'freshness' | 'multi-source' | 'unanswerable' | 'long-tail' | 'custom';
+interface RagEvalContext {
+    id: string;
+    text: string;
+    rank?: number;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+    stale?: boolean;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagEvalCitation {
+    id: string;
+    claimId?: string;
+    contextId?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+    quote?: string;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagEvalClaim {
+    id: string;
+    text: string;
+    citationIds?: readonly string[];
+    metadata?: Record<string, JsonValue>;
+}
+interface RagRequiredContext {
+    id?: string;
+    text?: string;
+    pageId?: string;
+    sourceId?: string;
+    anchorId?: string;
+}
+interface RagAnswerEvalScenario extends Scenario {
+    kind: 'rag-answer-eval';
+    query: string;
+    referenceAnswer?: string;
+    expectedClaims?: readonly string[];
+    forbiddenClaims?: readonly string[];
+    requiredContext?: readonly RagRequiredContext[];
+    unanswerable?: boolean;
+    requireCitations?: boolean;
+    slices?: readonly RagEvalSlice[];
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+}
+interface ExternalRagEvalScore {
+    provider: RagEvalProvider | string;
+    scores: Record<string, number>;
+    reasons?: Record<string, string>;
+    metadata?: Record<string, JsonValue>;
+}
+interface RagAnswerEvalArtifact {
+    query: string;
+    answer: string;
+    contexts: readonly RagEvalContext[];
+    claims?: readonly RagEvalClaim[];
+    citations?: readonly RagEvalCitation[];
+    abstained?: boolean;
+    durationMs?: number;
+    costUsd?: number;
+    externalScores?: readonly ExternalRagEvalScore[];
+    metadata?: Record<string, JsonValue>;
+}
+interface RagAnswerMetricSummary {
+    metrics: Record<RagEvalMetricKey, number>;
+    composite: number;
+    passed: boolean;
+    findings: readonly RagGapFinding[];
+    claimCount: number;
+    supportedClaimCount: number;
+    citedClaimCount: number;
+    supportedCitationCount: number;
+    matchedRequiredContextCount: number;
+    requiredContextCount: number;
+    providerScores: Record<string, Record<RagEvalMetricKey, number>>;
+}
+interface RagAnswerQualityJudgeOptions {
+    name?: string;
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+    weights?: Partial<Record<RagEvalMetricKey, number>>;
+    externalScorePolicy?: 'prefer-external' | 'deterministic-first';
+    minClaimSupport?: number;
+}
+interface RagAnswerEvalCase {
+    scenario: RagAnswerEvalScenario;
+    artifact: RagAnswerEvalArtifact;
+}
+interface RagAnswerQualityHookOptions {
+    scenarios: readonly RagAnswerEvalScenario[];
+    run: (scenario: RagAnswerEvalScenario) => MaybePromise<RagAnswerEvalArtifact>;
+    externalEvaluator?: (item: RagAnswerEvalCase) => MaybePromise<ExternalRagEvalScore | readonly ExternalRagEvalScore[] | undefined>;
+    thresholds?: Partial<Record<RagEvalMetricKey, number>>;
+    weights?: Partial<Record<RagEvalMetricKey, number>>;
+}
+interface RagCalibrationOptions {
+    scenario: RagAnswerEvalScenario;
+    strong: RagAnswerEvalArtifact;
+    weak: RagAnswerEvalArtifact;
+    judge?: JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
+    minStrongScore?: number;
+    maxWeakScore?: number;
+    signal?: AbortSignal;
+}
+interface RagCalibrationResult {
+    passed: boolean;
+    strongScore: number;
+    weakScore: number;
+    gap: number;
+}
+interface KnowledgeBaseQualityOptions {
+    now?: Date;
+    strict?: boolean;
+    minCitationRate?: number;
+    maxStaleSourceRate?: number;
+}
+interface KnowledgeBaseQualityReport {
+    ok: boolean;
+    metrics: {
+        page_count: number;
+        source_count: number;
+        citation_rate: number;
+        source_backed_page_rate: number;
+        stale_source_rate: number;
+        duplicate_source_hash_rate: number;
+        lint_error_count: number;
+        lint_warning_count: number;
+    };
+    findings: readonly RagGapFinding[];
+}
+type MaybePromise<T> = T | Promise<T>;
+declare function ragAnswerQualityJudge(options?: RagAnswerQualityJudgeOptions): JudgeConfig<RagAnswerEvalArtifact, RagAnswerEvalScenario>;
+declare function scoreRagAnswerArtifact(artifact: RagAnswerEvalArtifact, scenario: RagAnswerEvalScenario, options?: RagAnswerQualityJudgeOptions): RagAnswerMetricSummary;
+declare function diagnoseRagAnswerFailure(metrics: Record<RagEvalMetricKey, number>, scenario: RagAnswerEvalScenario, thresholds?: Partial<Record<RagEvalMetricKey, number>>): RagGapFinding[];
+declare function createRagAnswerQualityHook(options: RagAnswerQualityHookOptions): () => Promise<RagAnswerQualityResult>;
+declare function calibrateRagAnswerJudge(options: RagCalibrationOptions): Promise<RagCalibrationResult>;
+declare function normalizeExternalRagScores(scores: readonly ExternalRagEvalScore[]): Record<string, Record<RagEvalMetricKey, number>>;
+declare function toRagasEvaluationRows(cases: readonly RagAnswerEvalCase[]): {
+    user_input: string;
+    response: string;
+    retrieved_contexts: string[];
+    reference: string | undefined;
+    reference_contexts: string[];
+}[];
+declare function toDeepEvalTestCases(cases: readonly RagAnswerEvalCase[]): {
+    input: string;
+    actual_output: string;
+    expected_output: string | undefined;
+    retrieval_context: string[];
+    context: string[];
+}[];
+declare function toTruLensRecords(cases: readonly RagAnswerEvalCase[]): {
+    input: string;
+    output: string;
+    context: string;
+}[];
+declare function toRagCheckerRecords(cases: readonly RagAnswerEvalCase[]): {
+    query_id: string;
+    query: string;
+    gt_answer: string | undefined;
+    response: string;
+    retrieved_context: {
+        doc_id: string;
+        text: string;
+    }[];
+    claims: string[];
+}[];
+declare function scoreKnowledgeBaseIndex(index: KnowledgeIndex, options?: KnowledgeBaseQualityOptions): KnowledgeBaseQualityReport;
+
+type KnowledgeImprovementStatus = 'running' | 'candidate-ready' | 'promoted' | 'rejected' | 'blocked';
+interface KnowledgeImprovementMetric {
+    score: number;
+    passed: boolean;
+    dimensions?: Record<string, number>;
+    notes?: string;
+}
+interface KnowledgeImprovementEvaluationInput {
+    runId: string;
+    iteration: number;
+    root: string;
+    baselineRoot: string;
+    candidateRoot: string;
+    baselineIndex: KnowledgeIndex;
+    candidateIndex: KnowledgeIndex;
+    baseHash: string;
+    candidateHash: string;
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    kbQuality: KnowledgeBaseQualityReport;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
+    signal?: AbortSignal;
+}
+type KnowledgeImprovementEvaluator = (input: KnowledgeImprovementEvaluationInput) => Promise<KnowledgeImprovementMetric> | KnowledgeImprovementMetric;
+interface KnowledgeImprovementLifecycleRecord {
+    stage: 'candidate-update' | 'candidate-evaluation';
+    phases: readonly RagKnowledgeImprovementPhaseResult[];
+    findingCount: number;
+    retrievalWinnerConfig?: RetrievalConfig;
+    answerQuality?: RagAnswerQualityResult;
+    promotionDecision?: RagPromotionResult;
+}
+interface KnowledgeImprovementCandidateRecord {
+    iteration: number;
+    candidateId: string;
+    candidateRoot: string;
+    baseHash: string;
+    candidateHash?: string;
+    status: KnowledgeImprovementStatus;
+    createdAt: string;
+    updatedAt: string;
+    validation?: ValidateKnowledgeResult;
+    kbQuality?: KnowledgeBaseQualityReport;
+    readinessBlockingMissing?: number;
+    evaluation?: KnowledgeImprovementMetric;
+    lifecycle?: readonly KnowledgeImprovementLifecycleRecord[];
+    retrievalWinnerConfig?: RetrievalConfig;
+    answerQuality?: RagAnswerQualityResult;
+    promotionDecision?: RagPromotionResult;
+    notes?: string;
+}
+interface KnowledgeImprovementRunState {
+    version: 1;
+    runId: string;
     root: string;
     goal: string;
-    worker: ResearchWorker;
-    driver: ResearchDriver;
-    /**
-     * When false (default), the driver ONLY verifies + gates — a pure coordinator
-     * that contributes no research of its own (the "doesn't participate in the
-     * work" mode). When true, the driver also runs its `research` gap-fill pass
-     * each round over the gaps the worker left open.
-     */
-    driverResearches?: boolean;
-    maxRounds?: number;
-    actor?: string;
-    /** Readiness specs define the gate; an empty list means the loop never gates. */
+    status: KnowledgeImprovementStatus;
+    baseHash: string;
+    createdAt: string;
+    updatedAt: string;
+    ownerId?: string;
+    candidates: KnowledgeImprovementCandidateRecord[];
+    promotedCandidateId?: string;
+    blockedReason?: string;
+}
+interface KnowledgeImprovementResult {
+    runId: string;
+    runDir: string;
+    state: KnowledgeImprovementRunState;
+    candidate?: KnowledgeImprovementCandidateRecord;
+    lifecycle?: RunRagKnowledgeImprovementLoopResult;
+    promoted: boolean;
+    blocked: boolean;
+}
+interface KnowledgeImprovementRetrievalOptions extends Omit<RunRetrievalImprovementLoopOptions, 'index' | 'runDir'> {
+    runDir?: RunRetrievalImprovementLoopOptions['runDir'];
+}
+interface KnowledgeImprovementUpdateInput extends RagKnowledgeUpdateInput {
+    runId: string;
+    iteration: number;
+    candidateId: string;
+    root: string;
+    baselineRoot: string;
+    candidateRoot: string;
+    baseHash: string;
+}
+type KnowledgeImprovementUpdate = (input: KnowledgeImprovementUpdateInput) => Promise<RagKnowledgeUpdateResult> | RagKnowledgeUpdateResult;
+interface KnowledgeImprovementOptions {
+    root: string;
+    goal: string;
+    runId?: string;
+    runDir?: string;
+    ownerId?: string;
+    leaseTtlMs?: number;
+    resume?: boolean;
+    promote?: boolean;
+    maxCandidates?: number;
+    candidateResearchIterations?: number;
+    strict?: ValidateKnowledgeOptions['strict'];
     readinessSpecs?: KnowledgeReadinessSpec[];
     readinessTaskId?: string;
     readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    sourceOptions?: Pick<AddSourceOptions, 'adapters' | 'now'>;
+    kbQuality?: KnowledgeBaseQualityOptions;
+    step?: RunKnowledgeResearchLoopOptions['step'];
+    knowledgeResearch?: Omit<RagKnowledgeResearchOptions, 'root'>;
+    retrieval?: KnowledgeImprovementRetrievalOptions;
+    diagnose?: NonNullable<RunRagKnowledgeImprovementLoopOptions['diagnose']>;
+    acquireKnowledge?: NonNullable<RunRagKnowledgeImprovementLoopOptions['acquireKnowledge']>;
+    updateKnowledge?: KnowledgeImprovementUpdate;
+    evaluateAnswers?: NonNullable<RunRagKnowledgeImprovementLoopOptions['evaluateAnswers']>;
+    decidePromotion?: NonNullable<RunRagKnowledgeImprovementLoopOptions['promote']>;
+    enabledPhases?: readonly RagKnowledgeImprovementPhase[];
+    requiredPhases?: readonly RagKnowledgeImprovementPhase[];
+    evaluate?: KnowledgeImprovementEvaluator;
     signal?: AbortSignal;
-    onRound?: (round: TwoAgentResearchRound) => Promise<void> | void;
+    now?: () => Date;
+    onState?: (state: KnowledgeImprovementRunState) => Promise<void> | void;
 }
-interface TwoAgentResearchRound {
-    round: number;
-    /** Gaps reported at the START of the round (what the worker targeted). */
-    gaps: KnowledgeGap[];
-    /** Worker sources accepted by the driver and written to the KB. */
-    acceptedWorkerSources: SourceRecord[];
-    /** Worker sources the driver rejected (with reasons) — never written. */
-    rejectedWorkerSources: RejectedSource[];
-    /** Sources the driver itself added in its gap-fill pass. */
-    driverSources: SourceRecord[];
-    /** Curated pages written this round (worker proposal + driver proposal). */
-    writtenPages: string[];
-    readiness?: EvalKnowledgeBundleBuildResult;
-    /** True once the readiness gate reports no blocking gaps. */
-    ready: boolean;
-    event: KnowledgeEvent;
-    notes: {
-        worker?: string;
-        driver?: string;
-    };
+declare function knowledgeImprovementRunId(root: string, goal: string): string;
+declare function knowledgeImprovementRunDir(root: string, runId: string): string;
+declare function loadKnowledgeImprovementState(root: string, runId: string, runDir?: string): Promise<KnowledgeImprovementRunState | null>;
+declare function improveKnowledgeBase(options: KnowledgeImprovementOptions): Promise<KnowledgeImprovementResult>;
+declare function hashKnowledgeBase(root: string): Promise<string>;
+
+interface KbStore {
+    putSource(source: SourceRecord): Promise<void>;
+    getSource(id: string): Promise<SourceRecord | null>;
+    listSources(): Promise<SourceRecord[]>;
+    putPage(page: KnowledgePage): Promise<void>;
+    getPage(idOrPath: string): Promise<KnowledgePage | null>;
+    listPages(): Promise<KnowledgePage[]>;
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getIndex(): Promise<KnowledgeIndex | null>;
+    putEvent(event: KnowledgeEvent): Promise<void>;
+    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
 }
-interface TwoAgentResearchLoopResult {
-    root: string;
-    goal: string;
-    rounds: number;
-    ready: boolean;
-    index: KnowledgeIndex;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: TwoAgentResearchRound[];
+declare class MemoryKbStore implements KbStore {
+    private readonly sources;
+    private readonly pages;
+    private readonly events;
+    private index;
+    putSource(source: SourceRecord): Promise<void>;
+    getSource(id: string): Promise<SourceRecord | null>;
+    listSources(): Promise<SourceRecord[]>;
+    putPage(page: KnowledgePage): Promise<void>;
+    getPage(idOrPath: string): Promise<KnowledgePage | null>;
+    listPages(): Promise<KnowledgePage[]>;
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getIndex(): Promise<KnowledgeIndex | null>;
+    putEvent(event: KnowledgeEvent): Promise<void>;
+    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
+}
+declare class FileSystemKbStore extends MemoryKbStore {
+    private readonly dir;
+    constructor(dir: string);
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getIndex(): Promise<KnowledgeIndex | null>;
+    putEvent(event: KnowledgeEvent): Promise<void>;
 }
+
+declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
+
 /**
- * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
- *
- * Both agents research to grow ONE knowledge base. The roles are differentiated:
+ * `materialFactsSurfaced` — the held-out investment-research METRIC.
  *
- * - **WORKER** = primary research. Each round it reads the open gaps, discovers
- *   new sources, and proposes additions (`sources` + `proposalText`). It ADDS.
- * - **DRIVER** = the verifier / gap-filler / gate. It (1) VERIFIES the worker's
- *   sources before they commit — dedup against the KB, then `verifySource`
- *   rejects ones that aren't real/relevant; (2) GAP-FILLS the gaps the worker
- *   missed with its own research pass (when `driverResearches`); (3) folds the
- *   remaining gaps into the worker's next prompt; and (4) GATES on
- *   `scoreKnowledgeReadiness` — the loop stops as soon as there are no blocking
- *   gaps.
+ * Given a knowledge base a research loop built for a company and the company's
+ * HELD-OUT material-fact checklist (`tests/eval/investment-thesis-set.ts`, never
+ * shown to the loop), this returns the FRACTION of checklist items the KB's
+ * pages surface + ground. The check is the same `$0`, model-free, deterministic
+ * substring grader the loop's checklist already ships (`gradeFactAgainstText` /
+ * `gradeCompanyAgainstText`) — so the answer key never reaches a model the loop
+ * could observe, exactly the firewall the ML deep-question exam uses.
  *
- * Set `driverResearches: false` (default) for the pure-coordinator mode: the
- * driver only verifies + gates and contributes no research itself.
+ * The ONLY thing this file adds over the raw grader is the KB→text join: it reads
+ * the curated pages (and the raw source text) the loop wrote and hands their
+ * concatenation to the grader. That join mirrors `kbText` in the research-quality
+ * A/B (research-driving-ab.test.ts) so the thesis metric and the ML-exam metric
+ * read a KB the same way.
  *
- * Composes existing atoms — `initKnowledgeBase`, `addSourceText`,
- * `applyKnowledgeWriteBlocks`, `buildEvalKnowledgeBundle` (the readiness gate),
- * and `searchKnowledge` — and reinvents none of them.
+ * WHY pages AND source text: an honest thesis surfaces a buried fact in its
+ * curated thesis PAGE (the judgment), but a loop whose page is thin while its
+ * fetched filings are rich should still get credit for what it actually pulled.
+ * Grading the union is the faithful, not the lenient, choice — it rewards the
+ * loop that REACHED the filing even if its synthesis was terse, and it cannot
+ * manufacture a hit the underlying evidence does not contain.
  */
-declare function runTwoAgentResearchLoop(options: TwoAgentResearchLoopOptions): Promise<TwoAgentResearchLoopResult>;
+
+/** Per-fact grade plus the fact's id/lens, for the audit trail. */
+interface FactResult {
+    id: string;
+    lens: CompanyEvalCase['facts'][number]['lens'];
+    surfaced: boolean;
+    groupsFound: number;
+    groupsTotal: number;
+    foundLabels: string[];
+}
+/** The metric's result for one company: the surfaced fraction + the per-fact trail. */
+interface MaterialFactsResult {
+    ticker: string;
+    company: string;
+    /** Held-out facts the KB surfaced + grounded. */
+    surfaced: number;
+    /** Total held-out facts for this company (the denominator). */
+    total: number;
+    /** `surfaced / total` in [0, 1]. */
+    fraction: number;
+    /** Per-fact grade, in checklist order, for the doc / audit. */
+    perFact: FactResult[];
+}
 /**
- * Helper for verifiers: does the candidate source's text/title overlap any page
- * the readiness search returns for a gap query? A cheap relevance heuristic the
- * driver can compose into `verifySource` (real verifiers can do more).
+ * Join a KB index into the single text blob the grader scans: every curated PAGE
+ * (title + body) followed by every raw SOURCE (title + fetched text). This is the
+ * text read AFTER the loop finished — it is never handed to the loop. Identical
+ * in spirit to `kbText` in the research-quality A/B so both metrics read a KB the
+ * same way.
  */
-declare function sourceMatchesGaps(source: ResearchSourceProposal, index: KnowledgeIndex, gaps: KnowledgeGap[]): KnowledgeSearchResult[];
+declare function kbIndexToText(index: KnowledgeIndex): string;
+/**
+ * Grade one company's KB against its held-out material-fact checklist, given the
+ * KB's already-joined text. The pure core — no I/O — so calibration can score a
+ * hand-written shallow/deep thesis string directly and the live path can score a
+ * real KB. Returns the surfaced FRACTION plus the per-fact audit trail.
+ */
+declare function materialFactsSurfacedInText(company: CompanyEvalCase, kbText: string): MaterialFactsResult;
+/**
+ * `materialFactsSurfaced(kb, checklist)` — the metric in its KB-reading form.
+ *
+ * `kb` is EITHER a knowledge-base root directory (the loop wrote pages there) or
+ * an already-built `KnowledgeIndex`. `checklist` is the company's held-out
+ * `CompanyEvalCase`. Returns the surfaced fraction + per-fact trail.
+ *
+ * The checklist is HELD OUT by construction: it lives in the test eval set, is
+ * never passed to the loop, and is read only here, after the loop finished.
+ */
+declare function materialFactsSurfaced(kb: string | KnowledgeIndex, checklist: CompanyEvalCase): Promise<MaterialFactsResult>;
 
 /**
- * Real web-research worker + verifying driver for `runTwoAgentResearchLoop`.
+ * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
  *
- * This is the GENERAL, any-topic implementation behind the two-agent research
- * loop's live arm. Given the open knowledge gaps the readiness gate surfaces,
- * the worker:
+ * Closes the failure → wiki side of the recursive-self-improvement
+ * loop: a knowledge-gap or knowledge-poisoning finding produced by an
+ * analyst becomes a concrete proposal an operator (or auto-merge bot)
+ * can review and apply. The bridge is intentionally lossless on the
+ * fail-loud side — a finding the parser can't classify returns a
+ * `KnowledgeProposalParseError` rather than a silent skip, so the
+ * loop never accepts an underspecified edit.
  *
- *   1. asks an LLM (glm-5.2 by default) to turn each gap into focused web
- *      search queries,
- *   2. runs a REAL web search over the Tangle router (`POST /v1/search` — the
- *      same endpoint `tcloud mcp`'s `web_search` tool forwards to), so there is
- *      no hardcoded corpus,
- *   3. fetches the top results with the repo's polite, cached `politeFetch` and
- *      reduces each page to text with `htmlToText`,
- *   4. proposes the readable, verifiable pages as `ResearchSourceProposal`s plus
- *      a `buildPages` that writes citing `knowledge/*.md` pages from the sources
- *      the driver accepts.
+ * Subject grammar this bridge understands (analyst-side convention,
+ * stamped in the kind prompts):
  *
- * The verifying DRIVER is the differentiated role from the two-agent loop: a
- * second LLM pass that judges each fetched source's on-topic relevance to the
- * goal + open gaps and rejects off-topic / spam / already-covered material. The
- * worker ADDS; the driver GATES. Together they build a cleaner knowledge base
- * than a single agent at the same compute budget.
+ *   agent-knowledge:wiki:<page-slug>            create / update page
+ *   agent-knowledge:wiki:<page-slug>#<heading>  insert section under page
+ *   agent-knowledge:claim:<topic>               draft claim row
+ *   agent-knowledge:raw:<source-id>             lift raw → curated
+ *   agent-knowledge:stale:<page-slug>           mark page superseded
  *
- * Dependency-free on purpose: it talks to the router over `fetch` directly with
- * the published OpenAI-compatible chat shape and the `/v1/search` shape, so it
- * works whether or not the `tcloud` CLI is installed. Point it at any router by
- * passing `baseUrl`; supply the key via `apiKey` or `TANGLE_API_KEY`.
+ * Anything else (websearch:outdated:*, tool-doc:*, system-prompt:*,
+ * memory:*) is NOT a knowledge-base concern and returns `null` so the
+ * loop's improvement-applier handles it.
  */
 
-/** One live web result, as the router's `/v1/search` returns it. */
-interface WebSearchHit {
-    title: string;
-    url: string;
-    snippet?: string;
+interface KnowledgeProposal {
+    /**
+     * Stable id derived from the finding so cross-run diffs share an
+     * identity. Re-proposing the same finding produces the same id.
+     */
+    id: string;
+    /** The finding that generated this proposal — useful for audit + revert. */
+    sourceFindingId: string;
+    /** What the proposal does. */
+    kind: 'create-page' | 'update-page' | 'append-section' | 'create-claim' | 'lift-raw' | 'mark-stale';
+    /** Locus on disk (page slug or claim topic). */
+    locus: string;
+    /**
+     * Page write blocks the standard `applyKnowledgeWriteBlocks` consumer
+     * accepts. Empty for proposals that don't change page text (e.g.
+     * `create-claim` produces a `claim` field instead).
+     */
+    writeBlocks: KnowledgeWriteBlock[];
+    /**
+     * Granular claim draft for proposals whose unit-of-change is a claim
+     * row rather than a whole page. `status: 'draft'` until reviewed.
+     */
+    claim?: KnowledgeClaim;
+    /** Per-proposal metadata: severity, confidence, source span. */
+    metadata: {
+        severity: AnalystSeverity;
+        confidence: number;
+        evidence_uri?: string;
+        analyst_id: string;
+    };
+}
+declare class KnowledgeProposalParseError extends Error {
+    readonly findingId: string;
+    readonly subject: string;
+    constructor(findingId: string, subject: string, message: string);
 }
 /**
- * The two router capabilities the worker/driver need. Injectable so tests can
- * stub the network; the default talks to the live Tangle router over `fetch`.
+ * Convert one `AnalystFinding` into a knowledge proposal. Returns
+ * `null` when the finding's locus isn't a knowledge-base concern
+ * (`websearch:outdated:*`, `tool-doc:*`, `system-prompt:*`,
+ * `memory:*`, missing subject). Throws when the locus IS a
+ * knowledge-base concern but is malformed — that's a bug in the
+ * analyst prompt and should fail loud.
+ *
+ * Caller convention: feed the function the analyst's full findings
+ * list and filter out the `null`s; the orchestrator passes the
+ * remaining proposals to the existing review / apply pipeline.
  */
-interface RouterClient {
-    /** Live web search — returns title/url/snippet hits. */
-    search(query: string, opts?: {
-        maxResults?: number;
-    }): Promise<WebSearchHit[]>;
-    /** Chat completion — returns the assistant message's visible text. */
-    chat(messages: {
-        role: 'system' | 'user';
-        content: string;
-    }[], maxTokens?: number): Promise<string>;
+declare function proposeFromFinding(finding: AnalystFinding): KnowledgeProposal | null;
+/**
+ * Plural convenience: filter + map across an entire findings batch
+ * with one call. Parse errors collect into `errors[]`; the loop
+ * decides per-error whether to abort or continue.
+ */
+interface ProposeFromFindingsResult {
+    proposals: KnowledgeProposal[];
+    skipped: number;
+    errors: KnowledgeProposalParseError[];
 }
-interface TangleRouterOptions {
-    /** Router base URL. Defaults to `https://router.tangle.tools/v1`. */
-    baseUrl?: string;
-    /** Bearer key. Defaults to `process.env.TANGLE_API_KEY`. */
-    apiKey?: string;
-    /** Chat model id. Defaults to `glm-5.2`. */
-    model?: string;
-    /** Optional preferred search provider (exa | you | perplexity | …). */
-    searchProvider?: string;
-    signal?: AbortSignal;
+declare function proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): ProposeFromFindingsResult;
+
+interface EvaluateKnowledgeBaseReadinessOptions {
+    root: string;
+    goal: string;
+    readinessSpecs?: readonly KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    strict?: ValidateKnowledgeOptions['strict'];
+    kbQuality?: KnowledgeBaseQualityOptions;
 }
-/** A small error so a failed router call fails loud rather than returning junk. */
-declare class RouterError extends Error {
-    readonly status: number;
-    constructor(status: number, message: string);
+interface KnowledgeBaseReadinessEvaluation {
+    ready: boolean;
+    summary: string;
+    index: KnowledgeIndex;
+    validation: ValidateKnowledgeResult;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    kbQuality: KnowledgeBaseQualityReport;
+    dimensions: {
+        validation: number;
+        kb_quality: number;
+        blocking_readiness: number;
+    };
+}
+declare function evaluateKnowledgeBaseReadiness(options: EvaluateKnowledgeBaseReadinessOptions): Promise<KnowledgeBaseReadinessEvaluation>;
+
+interface KnowledgeReleaseReport {
+    release: KnowledgeRelease;
+    scorecard: ReleaseConfidenceScorecard;
+    candidateRuns: RunRecord[];
+    baselineRuns: RunRecord[];
 }
 /**
- * Build a dependency-free Tangle router client over `fetch`. This is the same
- * wire surface the `tcloud` SDK + `tcloud mcp` use (`/v1/search` for web search,
- * `/v1/chat/completions` for chat) so it needs no CLI installed.
+ * Campaign-native release report. The caller (a consumer's KB self-improvement
+ * loop) supplies the candidate/baseline `RunRecord[]` (e.g. via
+ * `campaignToRunRecords`) + optional per-instance `ReleaseTraceEvidence` + the
+ * gate decision; this folds them into a `ReleaseConfidenceScorecard` + a
+ * `KnowledgeRelease`. Release confidence is computed from run records + traces,
+ * independent of any optimizer result shape.
+ */
+interface KnowledgeReleaseInput {
+    candidateId: string;
+    baselineId?: string;
+    candidateRuns: RunRecord[];
+    baselineRuns?: RunRecord[];
+    traces?: ReleaseTraceEvidence[];
+    gateDecision?: GateDecision | null;
+    /**
+     * True when a held-out split was evaluated (drives the holdout threshold).
+     *
+     * Constraint: the substrate gate keys the holdout requirement off a scenario
+     * corpus, which this run-only report does not carry. With `hasHoldout: true`
+     * the gate fails closed (`missing_holdout_split`) even when holdout RunRecords
+     * are supplied. Callers that gate on a real held-out split should drive
+     * `evaluateReleaseConfidence` directly with a dataset/scenarios.
+     */
+    hasHoldout?: boolean;
+    /** Candidate is the search-best variant — a promotion precondition. Default true. */
+    promotedIsBest?: boolean;
+    createdAt?: string;
+    minScore?: number;
+}
+declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
+
+/**
+ * Research-DRIVING driver for `runVerifiedResearchLoop`.
+ *
+ * The shipped drivers all FILTER the worker's sources:
+ *   - `createVerifyingResearchDriver` judges on-topic relevance,
+ *   - `createAdaptiveResearchDriver` dedups then triages then escalates,
+ *   - `createClaimGroundingVerifier` rejects misattributed citations.
+ *
+ * This driver does the OPPOSITE job: instead of narrowing the worker's output,
+ * it DRIVES the research DEEPER each round. Its value is not "fewer sources" —
+ * it is "more answered, better-corroborated sub-questions". Concretely, each
+ * round it:
+ *
+ *   1. EXTRACTS the key claims from the worker's new sources (one LLM pass per
+ *      source, in `verifySource`; falls back to a deterministic sentence-pull
+ *      when the model is unavailable so a round never silently extracts nothing).
+ *   2. TRACKS each claim's support — the set of INDEPENDENT sources (by canonical
+ *      host) that assert it — and detects CONTRADICTIONS between a new claim and
+ *      one already on the ledger.
+ *   3. GENERATES the next round's DEEP sub-questions from the accumulated claims,
+ *      in four kinds — comparative ("how does X's tradeoff differ from Y's?"),
+ *      mechanism ("under what precise condition does X fail?"), gap ("what
+ *      specific result is missing?"), and contradiction ("does any source
+ *      challenge claim Z?").
+ *   4. FLAGS weakly-supported claims (only ONE independent source) and
+ *      contradicted claims as INVALIDATION targets and demands the worker find
+ *      corroborating / refuting evidence for them.
+ *   5. FOLDS the deep sub-questions + invalidation challenges into the worker's
+ *      next prompt via the loop's `foldGaps` → `steer` channel — that is the
+ *      mechanism that drives DEPTH and VALIDATION rather than breadth.
+ *
+ * COMPLETION (`isComplete` / the `done` judgment the caller gates on) does NOT
+ * look at source COUNT. It is done only when every deep sub-question it raised
+ * has been addressed AND every key claim is either supported by >= 2 independent
+ * sources OR explicitly marked CONTESTED (a contradiction the loop surfaced and
+ * could not resolve). A KB with twenty sources all asserting one unchallenged
+ * claim is NOT done; a KB whose handful of claims are each corroborated or
+ * contested IS.
+ *
+ * It reuses `runVerifiedResearchLoop` (it is a plain `ResearchDriver`), the web
+ * worker, `sha256` (claim identity), `canonicalizeUrl` (independent-source
+ * identity), and the `RouterClient` chat surface; it reinvents none of them.
  */
-declare function createTangleRouterClient(options?: TangleRouterOptions): RouterClient;
-interface WebResearchWorkerOptions {
-    /** Router client. Defaults to a live Tangle router client from env creds. */
+
+/** The four deep sub-question kinds the driver generates to drive depth. */
+type DeepQuestionKind = 'comparative' | 'mechanism' | 'gap' | 'contradiction';
+/** A deep sub-question the driver folds into the worker's next prompt. */
+interface DeepQuestion {
+    kind: DeepQuestionKind;
+    text: string;
+    /** sha256-derived stable id, so "addressed" can be tracked across rounds. */
+    id: string;
+    /** Claim id(s) this question interrogates (for contradiction/mechanism kinds). */
+    claimIds: string[];
+    /** True once a later round's evidence addressed it (see `markAddressed`). */
+    addressed: boolean;
+    /** The round this question was raised in. */
+    raisedRound: number;
+}
+/** One tracked claim plus the independent sources that assert it. */
+interface TrackedClaim {
+    id: string;
+    /** The claim text as first extracted (kept for prompts/audit). */
+    text: string;
+    /** Canonical hosts of the INDEPENDENT sources that assert this claim. */
+    supportingHosts: Set<string>;
+    /** Source URIs that assert this claim (provenance; may share a host). */
+    supportingUris: string[];
+    /** Claim ids this claim was found to CONTRADICT (and vice versa). */
+    contradicts: Set<string>;
+    /**
+     * CONTESTED = a contradiction the loop surfaced but could not resolve to a
+     * single supported claim. A contested claim counts as "settled enough to be
+     * done" (we report the disagreement) even with < 2 independent sources.
+     */
+    contested: boolean;
+    firstSeenRound: number;
+}
+/** The driver's accumulated research state — the completion oracle reads this. */
+interface ResearchDrivingState {
+    /** Every claim extracted from the worker's sources, by id. */
+    claims: TrackedClaim[];
+    /** Every deep sub-question raised, by id. */
+    questions: DeepQuestion[];
+    /** Claims with exactly one independent source AND not contested. */
+    weaklySupported: TrackedClaim[];
+    /** Claims supported by >= 2 independent sources. */
+    corroborated: TrackedClaim[];
+    /** Claims marked contested (a surfaced, unresolved contradiction). */
+    contested: TrackedClaim[];
+    /** Deep questions still unaddressed. */
+    openQuestions: DeepQuestion[];
+    /** How many rounds the driver has folded steer for. */
+    rounds: number;
+}
+interface ResearchDrivingDriverOptions {
+    /** Router client for claim extraction + deep-question generation. */
     router?: RouterClient;
     router_options?: TangleRouterOptions;
-    /** Max search queries the LLM may form per gap. Default 2. */
-    queriesPerGap?: number;
-    /** Max web results fetched per query. Default 3. */
-    resultsPerQuery?: number;
-    /** Hard cap on sources proposed per round (across all gaps). Default 6. */
-    maxSourcesPerRound?: number;
-    /** Disk cache dir for `politeFetch`. Optional; speeds repeat runs. */
-    cacheDir?: string;
-    /** Minimum readable text length to keep a fetched page. Default 200. */
-    minTextChars?: number;
-    /** Max chars of page text stored per source (keeps pages bounded). Default 4000. */
-    maxTextChars?: number;
+    /**
+     * A claim is CORROBORATED at this many INDEPENDENT supporting sources (distinct
+     * canonical hosts). Default 2 — the task's ">= 2 independent sources" bar.
+     */
+    minIndependentSources?: number;
+    /** Max deep sub-questions to fold into one round's steer. Default 6. */
+    maxQuestionsPerRound?: number;
+    /** Max claims to extract from a single source. Default 3. */
+    maxClaimsPerSource?: number;
+    /**
+     * When the extractor LLM is unavailable, fall back to a deterministic claim
+     * pull (the source's leading sentences) so the driver still drives. Default
+     * true. Set false to require the model (claims will be empty without it).
+     */
+    deterministicFallback?: boolean;
+    /** Observe each round's generated steer (for instrumentation / the script). */
+    onSteer?: (steer: ResearchDrivingSteer) => void;
+}
+/** What the driver folded into one round's worker prompt, surfaced for audit. */
+interface ResearchDrivingSteer {
+    round: number;
+    deepQuestions: DeepQuestion[];
+    /** Claims it demanded corroborating/refuting evidence for this round. */
+    invalidationTargets: TrackedClaim[];
+    /** The readiness gaps it interleaved (passed through from the loop). */
+    gaps: KnowledgeGap[];
+    /** The full steer text handed to the worker. */
+    text: string;
 }
 /**
- * The real web-research worker. Conforms to the loop's `ResearchWorker`
- * contract: given the open gaps, it returns the sources it found plus a
- * `buildPages` that emits citing pages from the sources the driver accepted.
+ * The research-driving driver. It is a `ResearchDriver` (drops straight into
+ * `runVerifiedResearchLoop`) PLUS a completion oracle and live state, mirroring
+ * how `createAdaptiveResearchDriver` exposes `stats()`.
  */
-declare function createWebResearchWorker(options?: WebResearchWorkerOptions): ResearchWorker;
-interface VerifyingDriverOptions {
-    router?: RouterClient;
-    router_options?: TangleRouterOptions;
+interface ResearchDrivingDriver extends ResearchDriver {
+    /** Live snapshot of the claim ledger + deep questions. */
+    researchState(): ResearchDrivingState;
     /**
-     * When the LLM verdict can't be parsed, default to REJECT (fail-closed) so a
-     * model hiccup never poisons the KB with an unverified source. Set `true` to
-     * accept-on-parse-failure only if you have a reason to. Default false.
+     * The completion oracle — gate `done` on THIS, not on source count. True when
+     * every deep sub-question is addressed AND every claim is corroborated
+     * (>= `minIndependentSources` independent sources) or explicitly contested.
+     * False while any claim is weakly-supported or any deep question is open.
+     * Returns false before any claim has been seen (nothing researched yet).
      */
-    acceptOnParseFailure?: boolean;
+    isComplete(): boolean;
+    /**
+     * The last round's generated steer, or undefined before the first fold. Useful
+     * to assert the driver produced deeper questions / invalidation challenges.
+     */
+    lastSteer(): ResearchDrivingSteer | undefined;
+}
+declare function createResearchDrivingDriver(options?: ResearchDrivingDriverOptions): ResearchDrivingDriver;
+
+declare const SourceAnchorSchema: z.ZodObject<{
+    id: z.ZodString;
+    sourceId: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    lineStart: z.ZodOptional<z.ZodNumber>;
+    lineEnd: z.ZodOptional<z.ZodNumber>;
+    charStart: z.ZodOptional<z.ZodNumber>;
+    charEnd: z.ZodOptional<z.ZodNumber>;
+    timestampMs: z.ZodOptional<z.ZodNumber>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const SourceRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    uri: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    mediaType: z.ZodOptional<z.ZodString>;
+    contentHash: z.ZodString;
+    text: z.ZodOptional<z.ZodString>;
+    anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        sourceId: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        page: z.ZodOptional<z.ZodNumber>;
+        lineStart: z.ZodOptional<z.ZodNumber>;
+        lineEnd: z.ZodOptional<z.ZodNumber>;
+        charStart: z.ZodOptional<z.ZodNumber>;
+        charEnd: z.ZodOptional<z.ZodNumber>;
+        timestampMs: z.ZodOptional<z.ZodNumber>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
+declare const KnowledgePageSchema: z.ZodObject<{
+    id: z.ZodString;
+    path: z.ZodString;
+    title: z.ZodString;
+    text: z.ZodString;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    sourceIds: z.ZodArray<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    outLinks: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const KnowledgeGraphNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    path: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    sourceIds: z.ZodArray<z.ZodString>;
+    outDegree: z.ZodNumber;
+    inDegree: z.ZodNumber;
+}, z.core.$strip>;
+declare const KnowledgeGraphEdgeSchema: z.ZodObject<{
+    source: z.ZodString;
+    target: z.ZodString;
+    weight: z.ZodNumber;
+    reasons: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+declare const KnowledgeIndexSchema: z.ZodObject<{
+    root: z.ZodString;
+    generatedAt: z.ZodString;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        uri: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        contentHash: z.ZodString;
+        text: z.ZodOptional<z.ZodString>;
+        anchors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            sourceId: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            page: z.ZodOptional<z.ZodNumber>;
+            lineStart: z.ZodOptional<z.ZodNumber>;
+            lineEnd: z.ZodOptional<z.ZodNumber>;
+            charStart: z.ZodOptional<z.ZodNumber>;
+            charEnd: z.ZodOptional<z.ZodNumber>;
+            timestampMs: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
+    pages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        path: z.ZodString;
+        title: z.ZodString;
+        text: z.ZodString;
+        frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        sourceIds: z.ZodArray<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        outLinks: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    graph: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+            path: z.ZodString;
+            tags: z.ZodArray<z.ZodString>;
+            sourceIds: z.ZodArray<z.ZodString>;
+            outDegree: z.ZodNumber;
+            inDegree: z.ZodNumber;
+        }, z.core.$strip>>;
+        edges: z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            target: z.ZodString;
+            weight: z.ZodNumber;
+            reasons: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+declare const KnowledgeEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        "source.added": "source.added";
+        "proposal.applied": "proposal.applied";
+        "index.built": "index.built";
+        "lint.run": "lint.run";
+        "optimization.run": "optimization.run";
+        "release.promoted": "release.promoted";
+        "release.rejected": "release.rejected";
+    }>;
+    createdAt: z.ZodString;
+    actor: z.ZodOptional<z.ZodString>;
+    target: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const KnowledgeBaseCandidateSchema: z.ZodObject<{
+    id: z.ZodString;
+    units: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        text: z.ZodString;
+        claims: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+            refs: z.ZodArray<z.ZodObject<{
+                sourceId: z.ZodString;
+                anchorId: z.ZodOptional<z.ZodString>;
+                quote: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            confidence: z.ZodOptional<z.ZodNumber>;
+            status: z.ZodOptional<z.ZodEnum<{
+                draft: "draft";
+                active: "active";
+                superseded: "superseded";
+                rejected: "rejected";
+            }>>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        relations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            sourceId: z.ZodString;
+            targetId: z.ZodString;
+            predicate: z.ZodString;
+            weight: z.ZodOptional<z.ZodNumber>;
+            metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>>>;
+        sourceIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    retrievalPolicy: z.ZodOptional<z.ZodString>;
+    synthesisPolicy: z.ZodOptional<z.ZodString>;
+    questionPolicy: z.ZodOptional<z.ZodString>;
+    updatePolicy: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+
+declare function searchKnowledge(index: KnowledgeIndex, query: string, limit?: number): KnowledgeSearchResult[];
+declare function tokenizeQuery(query: string): string[];
+declare function reciprocalRankFusion(rankLists: string[][], k?: number): Map<string, number>;
+
+interface KnowledgeLayout {
+    root: string;
+    knowledgeDir: string;
+    rawSourcesDir: string;
+    sourceRegistryPath: string;
+    indexPath: string;
+    logPath: string;
+    cacheDir: string;
 }
+declare function layoutFor(root: string): KnowledgeLayout;
 /**
- * The verifying driver: a real LLM pass that judges each candidate source's
- * on-topic relevance to the goal + open gaps and whether it duplicates material
- * already accepted this round. This is the differentiated coordinator role — it
- * GATES the worker's additions; it adds nothing itself.
+ * Filenames that `initKnowledgeBase` writes as human-navigation scaffolding.
+ * These are excluded from the page index — they exist on disk so authors can
+ * curate their vault, but they are not searchable content.
  *
- * The loop already dedups exact-uri duplicates and only calls this on genuinely
- * new candidates, so the verifier focuses on relevance + near-duplicate
- * judgement, not bookkeeping.
+ * Add new scaffold filenames here (and only here) to keep lint, validate, viz,
+ * and the indexer consistent.
  */
-declare function createVerifyingResearchDriver(options?: VerifyingDriverOptions): ResearchDriver;
+declare const SCAFFOLD_PAGE_BASENAMES: readonly string[];
+/**
+ * True when a knowledge-relative path points at a scaffold file rather than
+ * authored content. Accepts both repo-relative paths (`knowledge/index.md`)
+ * and any nested `<dir>/index.md` or `<dir>/log.md` (for example
+ * `knowledge/concepts/index.md`) so subdirectory README-style scaffolds are
+ * also excluded.
+ */
+declare function isScaffoldPath(path: string): boolean;
+declare function initKnowledgeBase(root: string): Promise<KnowledgeLayout>;
+declare function loadKnowledgePages(root: string): Promise<KnowledgePage[]>;
+declare function writeJson(path: string, value: unknown): Promise<void>;
 
 declare const WIKILINK_REGEX: RegExp;
 declare function extractWikilinks(content: string): string[];
@@ -1313,4 +2480,4 @@ declare function normalizeLinkTarget(target: string): string;
 declare function isSafeKnowledgePath(path: string, allowedPrefixes?: string[]): boolean;
 declare function parseKnowledgeWriteBlocks(text: string, allowedPrefixes?: string[]): KnowledgeWriteParseResult;
 
-export { type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type D1Adapter, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchSourceProposal, type ResearchSupervisorOptions, type ResearchWorker, type RouterClient, RouterError, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReadinessDeliverable, knowledgeReleaseReport, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeResearchLoop, runResearchSupervisor, runTwoAgentResearchLoop, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+export { type AdaptiveDecision, type AdaptiveDriverOptions, type AdaptiveResearchDriver, type AdaptiveStats, type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type ClaimGroundingDriverOptions, type CompanyEvalCase, type D1Adapter, type DedupReason, type DeepQuestion, type DeepQuestionKind, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type EvaluateKnowledgeBaseReadinessOptions, type ExpectedGroup, type ExternalRagEvalScore, type FactResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeBaseQualityOptions, type KnowledgeBaseQualityReport, type KnowledgeBaseReadinessEvaluation, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, type KnowledgeImprovementCandidateRecord, type KnowledgeImprovementEvaluationInput, type KnowledgeImprovementEvaluator, type KnowledgeImprovementLifecycleRecord, type KnowledgeImprovementMetric, type KnowledgeImprovementOptions, type KnowledgeImprovementResult, type KnowledgeImprovementRetrievalOptions, type KnowledgeImprovementRunState, type KnowledgeImprovementStatus, type KnowledgeImprovementUpdate, type KnowledgeImprovementUpdateInput, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, type MaterialFact, type MaterialFactLens, type MaterialFactsResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RagAnswerEvalArtifact, type RagAnswerEvalCase, type RagAnswerEvalScenario, type RagAnswerMetricSummary, type RagAnswerQualityHookOptions, type RagAnswerQualityInput, type RagAnswerQualityJudgeOptions, type RagAnswerQualityResult, type RagCalibrationOptions, type RagCalibrationResult, type RagDiagnosisInput, type RagEvalCitation, type RagEvalClaim, type RagEvalContext, type RagEvalMetricKey, type RagEvalProvider, type RagEvalSlice, type RagGapFinding, type RagGapKind, type RagGapSeverity, type RagKnowledgeAcquisitionInput, type RagKnowledgeImprovementPhase, type RagKnowledgeImprovementPhaseResult, type RagKnowledgeImprovementPhaseStatus, type RagKnowledgeResearchOptions, type RagKnowledgeUpdateInput, type RagKnowledgeUpdateResult, type RagPhaseInputBase, type RagPromotionInput, type RagPromotionResult, type RagRequiredContext, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchDrivingDriver, type ResearchDrivingDriverOptions, type ResearchDrivingState, type ResearchDrivingSteer, type ResearchSourceProposal, type ResearchWorker, RetrievalConfig, type RouterClient, RouterError, type RouterUsage, type RunKnowledgeResearchLoopOptions, type RunRagKnowledgeImprovementLoopOptions, type RunRagKnowledgeImprovementLoopResult, RunRetrievalImprovementLoopOptions, RunRetrievalImprovementLoopResult, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type ThesisRunOptions, type ThesisRunResult, type ThesisTaskInput, type TrackedClaim, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifiedResearchLoopOptions, type VerifiedResearchLoopResult, type VerifiedResearchRound, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, calibrateRagAnswerJudge, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createCollectionResearchDriver, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createRagAnswerQualityHook, createResearchDrivingDriver, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, diagnoseRagAnswerFailure, evaluateKnowledgeBaseReadiness, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, gradeCompanyAgainstText, gradeFactAgainstText, groundClaimInText, hashKnowledgeBase, improveKnowledgeBase, initKnowledgeBase, inspectKnowledgeIndex, investmentThesisSet, isSafeKnowledgePath, isScaffoldPath, kbIndexToText, knowledgeImprovementRunDir, knowledgeImprovementRunId, knowledgeReleaseReport, layoutFor, lensDistribution, lintKnowledgeIndex, loadKnowledgeImprovementState, loadKnowledgePages, loadSourceRegistry, materialFactsSurfaced, materialFactsSurfacedInText, mediaTypeFor, normalizeExternalRagScores, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, ragAnswerQualityJudge, reciprocalRankFusion, runInvestmentThesisTask, runKnowledgeResearchLoop, runRagKnowledgeImprovementLoop, runTwoAgentResearchLoop, runVerifiedResearchLoop, scoreKnowledgeBaseIndex, scoreRagAnswerArtifact, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, thesisReadinessSpecs, toDeepEvalTestCases, toRagCheckerRecords, toRagasEvaluationRows, toTruLensRecords, tokenizeQuery, totalMaterialFacts, triageSource, validateKnowledgeIndex, withCitedClaim, writeJson, writeKnowledgeIndex, writeSourceRegistry };