@tangle-network/agent-knowledge 1.8.0 → 1.10.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-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, AnalystSeverity, AnalystFinding, RunRecord, ReleaseTraceEvidence, GateDecision, ReleaseConfidenceScorecard, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
 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 { z } from 'zod';
@@ -28,6 +28,588 @@ interface SourceAdapter {
 declare const textSourceAdapter: SourceAdapter;
 declare function mediaTypeFor(uri: string): string;
 
+interface KnowledgeReadinessSpec {
+    id: string;
+    description: string;
+    query: string;
+    requiredFor: string[];
+    category: KnowledgeRequirementCategory;
+    acquisitionMode: KnowledgeAcquisitionMode;
+    importance: KnowledgeImportance;
+    freshness: KnowledgeFreshness;
+    sensitivity: KnowledgeSensitivity;
+    confidenceNeeded: number;
+    fallbackPolicy?: KnowledgeRequirement['fallbackPolicy'];
+    minSources?: number;
+    minHits?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Defaults applied by `defineReadinessSpec` when the caller omits the field.
+ *
+ * These are deliberately conservative: a domain-specific topic that an agent
+ * needs grounded to a high-confidence threshold from at least one authoritative
+ * source. Override any field to specialise (e.g. `freshness: 'daily'` for a
+ * topic that must reflect today's regulatory state).
+ */
+declare const READINESS_SPEC_DEFAULTS: {
+    readonly category: "domain_specific";
+    readonly acquisitionMode: "search_web";
+    readonly importance: "high";
+    readonly freshness: "monthly";
+    readonly sensitivity: "public";
+    readonly confidenceNeeded: 0.7;
+    readonly minSources: 1;
+    readonly minHits: 2;
+};
+/**
+ * Inputs accepted by `defineReadinessSpec`. The four fields the caller cannot
+ * sanely default (id, description, query, requiredFor) are required; everything
+ * else is optional and pulls from `READINESS_SPEC_DEFAULTS`.
+ */
+type DefineReadinessSpecInput = Pick<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'> & Partial<Omit<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'>>;
+/**
+ * Builder that returns a fully-typed `KnowledgeReadinessSpec` from a slim input.
+ *
+ * Motivation: `KnowledgeReadinessSpec` has eleven required fields. Most of them
+ * (category, acquisition mode, importance, freshness, sensitivity, confidence
+ * threshold, source/hit minima) have a clear default for domain-specific KB
+ * topics — agents end up copy-pasting the same boilerplate across every spec.
+ * This helper collapses that boilerplate while keeping every field overridable.
+ *
+ * @example
+ * defineReadinessSpec({
+ *   id: 'coop/intent-grounding',
+ *   description: 'Required grounding for coop pack intent stage',
+ *   query: 'flock size space ventilation predator',
+ *   requiredFor: ['IntentIntakeAgent', 'requirements'],
+ * })
+ *
+ * @example  // override defaults where the topic demands it
+ * defineReadinessSpec({
+ *   id: 'medical/dosing',
+ *   description: 'Dosing guidance for compounding pharmacy',
+ *   query: 'compounding dose schedule',
+ *   requiredFor: ['DosingAgent'],
+ *   importance: 'blocking',
+ *   freshness: 'daily',
+ *   sensitivity: 'private',
+ *   confidenceNeeded: 0.95,
+ *   minSources: 3,
+ * })
+ */
+declare function defineReadinessSpec(input: DefineReadinessSpecInput): KnowledgeReadinessSpec;
+interface BuildEvalKnowledgeBundleOptions {
+    taskId: string;
+    index: KnowledgeIndex;
+    specs: KnowledgeReadinessSpec[];
+    userAnswers?: Record<string, string>;
+    searchLimit?: number;
+    metadata?: Record<string, unknown>;
+    now?: Date;
+}
+interface EvalKnowledgeBundleBuildResult {
+    bundle: KnowledgeBundle;
+    report: KnowledgeReadinessReport;
+    requirements: KnowledgeRequirement[];
+    searchResultsByRequirement: Record<string, KnowledgeSearchResult[]>;
+    questions: UserQuestion[];
+    acquisitionPlans: DataAcquisitionPlan[];
+}
+declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
+
+interface AddSourceOptions {
+    copyIntoRaw?: boolean;
+    adapters?: SourceAdapter[];
+    now?: () => Date;
+}
+interface AddSourceTextInput {
+    uri: string;
+    text: string;
+    title?: string;
+    mediaType?: string;
+    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;
+
+/**
+ * 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;
+}
+/** 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.
+ *
+ * `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;
+}
+/**
+ * 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.
+ */
+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 TwoAgentResearchLoopOptions {
+    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: TwoAgentResearchRound) => 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;
+    };
+}
+interface TwoAgentResearchLoopResult {
+    root: string;
+    goal: string;
+    rounds: number;
+    ready: boolean;
+    index: KnowledgeIndex;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    steps: TwoAgentResearchRound[];
+}
+/**
+ * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
+ *
+ * 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.
+ */
+declare function runTwoAgentResearchLoop(options: TwoAgentResearchLoopOptions): Promise<TwoAgentResearchLoopResult>;
+/**
+ * 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[];
+
+/**
+ * Real web-research worker + verifying driver for `runTwoAgentResearchLoop`.
+ *
+ * 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;
+}
+/**
+ * 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;
+    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;
+
+/**
+ * Adaptive verifier mode for `runTwoAgentResearchLoop`.
+ *
+ * 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.
  *
@@ -132,125 +714,173 @@ declare function stripFrontmatter(content: 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;
-    query: string;
-    requiredFor: string[];
-    category: KnowledgeRequirementCategory;
-    acquisitionMode: KnowledgeAcquisitionMode;
-    importance: KnowledgeImportance;
-    freshness: KnowledgeFreshness;
-    sensitivity: KnowledgeSensitivity;
-    confidenceNeeded: number;
-    fallbackPolicy?: KnowledgeRequirement['fallbackPolicy'];
-    minSources?: number;
-    minHits?: number;
-    metadata?: Record<string, unknown>;
-}
 /**
- * Defaults applied by `defineReadinessSpec` when the caller omits the field.
+ * Claim-grounding mode for `runTwoAgentResearchLoop`.
  *
- * These are deliberately conservative: a domain-specific topic that an agent
- * needs grounded to a high-confidence threshold from at least one authoritative
- * source. Override any field to specialise (e.g. `freshness: 'daily'` for a
- * topic that must reflect today's regulatory state).
+ * The two-agent loop's existing verifier judges a source's on-topic RELEVANCE
+ * (is this page about the goal?). On the topic sets we have measured, its
+ * cleanliness win is dominated by DE-DUPLICATION — which a deterministic
+ * content-hash / canonical-URL check captures at ~none of the LLM premium (see
+ * `docs/results/cost-quality.md`). That makes the LLM verifier look expensive
+ * for what a cheap rule already does.
+ *
+ * Claim-grounding targets a DIFFERENT, harder error band: a citation that is
+ * relevant and unique but **misattributed** — the page is on-topic, the URL is
+ * real, yet the specific CLAIM the source is cited for does NOT actually appear
+ * in the page. This is the citation-fabrication failure mode of LLM research:
+ * the model writes a plausible sentence and hangs a real URL off it that never
+ * says any such thing. Neither de-dup nor a relevance judge catches it (both can
+ * pass a misattributed-but-on-topic page); only checking the claim against the
+ * fetched text does.
+ *
+ * The check is EXECUTABLE GROUND TRUTH, not another LLM opinion: the worker
+ * attaches the specific claim it is citing the source for, and the verifier
+ * tests whether that claim is PRESENT (verbatim, normalized, or as a sufficient
+ * content-word overlap / close paraphrase) in the `htmlToText` output of the
+ * page the worker actually fetched. A claim that is not grounded is rejected as
+ * misattributed. Because the oracle is deterministic text presence — not a model
+ * call — it is a deployable, non-oracle verifier: it can run in production with
+ * zero inference cost, OR be composed with the LLM relevance verifier so the
+ * loop rejects BOTH off-topic AND misattributed sources.
+ *
+ * This module is content-free and any-topic: it adds (1) a way for a proposal to
+ * carry the claim it is cited for, (2) the `groundClaimInText` oracle, and (3) a
+ * `ResearchDriver` that gates on grounding. It composes the existing
+ * `ResearchDriver` / `ResearchSourceProposal` contracts and the shipped
+ * `htmlToText`; it reinvents none of them.
  */
-declare const READINESS_SPEC_DEFAULTS: {
-    readonly category: "domain_specific";
-    readonly acquisitionMode: "search_web";
-    readonly importance: "high";
-    readonly freshness: "monthly";
-    readonly sensitivity: "public";
-    readonly confidenceNeeded: 0.7;
-    readonly minSources: 1;
-    readonly minHits: 2;
-};
+
 /**
- * Inputs accepted by `defineReadinessSpec`. The four fields the caller cannot
- * sanely default (id, description, query, requiredFor) are required; everything
- * else is optional and pulls from `READINESS_SPEC_DEFAULTS`.
+ * 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.
  */
-type DefineReadinessSpecInput = Pick<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'> & Partial<Omit<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'>>;
+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;
+}
 /**
- * Builder that returns a fully-typed `KnowledgeReadinessSpec` from a slim input.
+ * THE ORACLE. Is `claim` grounded in `pageText` (the `htmlToText` output of the
+ * page the worker fetched)? Deterministic, no model call:
  *
- * Motivation: `KnowledgeReadinessSpec` has eleven required fields. Most of them
- * (category, acquisition mode, importance, freshness, sensitivity, confidence
- * threshold, source/hit minima) have a clear default for domain-specific KB
- * topics — agents end up copy-pasting the same boilerplate across every spec.
- * This helper collapses that boilerplate while keeping every field overridable.
+ *   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.
  *
- * @example
- * defineReadinessSpec({
- *   id: 'coop/intent-grounding',
- *   description: 'Required grounding for coop pack intent stage',
- *   query: 'flock size space ventilation predator',
- *   requiredFor: ['IntentIntakeAgent', 'requirements'],
- * })
+ * 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.
  *
- * @example  // override defaults where the topic demands it
- * defineReadinessSpec({
- *   id: 'medical/dosing',
- *   description: 'Dosing guidance for compounding pharmacy',
- *   query: 'compounding dose schedule',
- *   requiredFor: ['DosingAgent'],
- *   importance: 'blocking',
- *   freshness: 'daily',
- *   sensitivity: 'private',
- *   confidenceNeeded: 0.95,
- *   minSources: 3,
- * })
+ * The returned function matches `ResearchDriver['verifySource']`, so it drops
+ * straight into `runTwoAgentResearchLoop` 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;
+}
+/**
+ * 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 defineReadinessSpec(input: DefineReadinessSpecInput): KnowledgeReadinessSpec;
-interface BuildEvalKnowledgeBundleOptions {
+declare function createClaimDecorator(options?: WorkerClaimDecorationOptions): (source: ResearchSourceProposal, goal: string) => Promise<ResearchSourceProposal>;
+
+interface DiscoveryTask {
+    id: string;
+    goal: string;
+    query?: string;
+    sourceHints?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface DiscoveryResult {
     taskId: string;
-    index: KnowledgeIndex;
-    specs: KnowledgeReadinessSpec[];
-    userAnswers?: Record<string, string>;
-    searchLimit?: number;
+    summary: string;
+    sourceUris?: string[];
+    claims?: Array<{
+        text: string;
+        sourceUri?: string;
+        confidence?: number;
+    }>;
+    followUpTasks?: DiscoveryTask[];
     metadata?: Record<string, unknown>;
-    now?: Date;
 }
-interface EvalKnowledgeBundleBuildResult {
-    bundle: KnowledgeBundle;
-    report: KnowledgeReadinessReport;
-    requirements: KnowledgeRequirement[];
-    searchResultsByRequirement: Record<string, KnowledgeSearchResult[]>;
-    questions: UserQuestion[];
-    acquisitionPlans: DataAcquisitionPlan[];
+interface KnowledgeDiscoveryWorker {
+    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
 }
-declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
+interface KnowledgeDiscoveryDispatcher {
+    dispatch(tasks: DiscoveryTask[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryResult[]>;
+}
+declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
 
 interface KnowledgeEventQuery {
     type?: KnowledgeEventType;
@@ -604,26 +1234,6 @@ interface KnowledgeReleaseInput {
 }
 declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
 
-interface AddSourceOptions {
-    copyIntoRaw?: boolean;
-    adapters?: SourceAdapter[];
-    now?: () => Date;
-}
-interface AddSourceTextInput {
-    uri: string;
-    text: string;
-    title?: string;
-    mediaType?: string;
-    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;
 }
@@ -996,198 +1606,6 @@ 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;
-}
-/** 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.
- *
- * `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;
-}
-/**
- * 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.
- */
-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 TwoAgentResearchLoopOptions {
-    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: TwoAgentResearchRound) => 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;
-    };
-}
-interface TwoAgentResearchLoopResult {
-    root: string;
-    goal: string;
-    rounds: number;
-    ready: boolean;
-    index: KnowledgeIndex;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: TwoAgentResearchRound[];
-}
-/**
- * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
- *
- * 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.
- */
-declare function runTwoAgentResearchLoop(options: TwoAgentResearchLoopOptions): Promise<TwoAgentResearchLoopResult>;
-/**
- * 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[];
-
 declare const WIKILINK_REGEX: RegExp;
 declare function extractWikilinks(content: string): string[];
 declare function normalizeLinkTarget(target: string): string;
@@ -1195,4 +1613,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 RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, 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 D1Adapter, type DedupReason, type DefineReadinessSpecInput, type DetectChangesOptions, type DetectChangesResult, type DiscoveryResult, type DiscoveryTask, type DriverResearchContext, type EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type GroundClaimOptions, type GroundingResult, type KbStore, KnowledgeBaseCandidateSchema, type KnowledgeChange, type KnowledgeChangeKind, type KnowledgeChunk, KnowledgeClaim, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeFragment, type KnowledgeFreshnessStore, type KnowledgeGap, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseInput, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, RESEARCH_SUPERVISOR_SYSTEM_PROMPT, type RejectedSource, type ResearchContribution, type ResearchDriver, type ResearchSourceProposal, type ResearchSupervisorOptions, type ResearchWorker, type RouterClient, RouterError, type RouterUsage, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type SourceVerdict, type SourceVerificationContext, type TangleRouterOptions, type TriageClass, type TwoAgentResearchLoopOptions, type TwoAgentResearchLoopResult, type TwoAgentResearchRound, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, type VerifyingDriverOptions, WIKILINK_REGEX, type WebResearchWorkerOptions, type WebSearchHit, type WorkerClaimDecorationOptions, type WorkerResearchContext, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, canonicalizeUrl, chunkMarkdown, citedClaimKey, citedClaimOf, contentKey, createAdaptiveResearchDriver, createClaimDecorator, createClaimGroundingVerifier, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, createTangleRouterClient, createVerifyingResearchDriver, createWebResearchWorker, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, groundClaimInText, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReadinessDeliverable, knowledgeReleaseReport, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeResearchLoop, runResearchSupervisor, runTwoAgentResearchLoop, searchKnowledge, sha256, slugify, sourceMatchesGaps, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, triageSource, validateKnowledgeIndex, withCitedClaim, writeJson, writeKnowledgeIndex, writeSourceRegistry };