@tangle-network/agent-knowledge 1.9.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,140 +28,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 +118,1493 @@ 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;
-/**
- * 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)
- * );
- * ```
+ * `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 D1Adapter {
-    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
-    upsert(record: FreshnessRecord): Promise<void>;
-    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
+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>;
 }
-declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
-
-interface ParsedFrontmatter {
-    frontmatter: Record<string, unknown>;
-    body: string;
+/** 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;
 }
-declare function parseFrontmatter(content: string): ParsedFrontmatter;
-declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
-
-declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
-
-declare function sha256(text: string): string;
-declare function slugify(input: string): string;
-declare function stableId(prefix: string, content: string): string;
-
-declare function buildKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
-declare function writeKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
-
-interface KnowledgeInspection {
-    pageCount: number;
-    sourceCount: number;
-    expiredSourceCount: number;
-    staleSourceCount: number;
-    edgeCount: number;
-    findingCount: number;
-    blockingFindingCount: number;
-    topPages: Array<{
-        path: string;
-        title: string;
-        degree: number;
-        sources: number;
-    }>;
-    sourceFreshness: SourceFreshnessInspection[];
-    findings: KnowledgeLintFinding[];
+/** 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;
 }
-interface SourceFreshnessInspection {
-    id: string;
-    title?: string;
-    uri: string;
-    status: 'fresh' | 'expired' | 'unknown';
-    validUntil?: string;
-    lastVerifiedAt?: string;
+/** A single rejected source plus the reason the driver gave. */
+interface RejectedSource {
+    source: ResearchSourceProposal;
+    reason: string;
 }
-declare function inspectKnowledgeIndex(index: KnowledgeIndex, options?: {
-    now?: Date;
-}): KnowledgeInspection;
-interface KnowledgeExplanation {
-    target: string;
-    page?: KnowledgePage;
-    sources: Array<{
-        id: string;
-        title?: string;
-        uri: string;
-    }>;
-    links: string[];
-    inbound: string[];
-    related: Array<{
-        path: string;
-        title: string;
-        score: number;
-    }>;
+/** 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;
 }
-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[]>;
+/**
+ * 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;
 }
-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[]>;
+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;
 }
-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 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 lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
-
-interface ApplyWriteBlocksResult {
-    written: string[];
-    warnings: string[];
+interface TwoAgentResearchLoopResult {
+    root: string;
+    goal: string;
+    rounds: number;
+    ready: boolean;
+    index: KnowledgeIndex;
+    readiness?: EvalKnowledgeBundleBuildResult;
+    steps: TwoAgentResearchRound[];
 }
-declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
-declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
-
 /**
- * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
+ * Two-agent (driver + worker) sibling of `runKnowledgeResearchLoop`.
  *
- * 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.
+ * Both agents research to grow ONE knowledge base. The roles are differentiated:
  *
- * Subject grammar this bridge understands (analyst-side convention,
- * stamped in the kind prompts):
+ * - **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.
  *
- *   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
+ * Set `driverResearches: false` (default) for the pure-coordinator mode: the
+ * driver only verifies + gates and contributes no research itself.
  *
- * 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.
+ * 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[];
 
-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);
-}
 /**
- * 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.
+ * Real web-research worker + verifying driver for `runTwoAgentResearchLoop`.
  *
- * 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.
+ * 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`.
  */
-declare function proposeFromFinding(finding: AnalystFinding): KnowledgeProposal | null;
+
+/** One live web result, as the router's `/v1/search` returns it. */
+interface WebSearchHit {
+    title: string;
+    url: string;
+    snippet?: string;
+}
 /**
- * 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.
+ * 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 ProposeFromFindingsResult {
-    proposals: KnowledgeProposal[];
-    skipped: number;
-    errors: KnowledgeProposalParseError[];
+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;
 }
-declare function proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): ProposeFromFindingsResult;
-
-interface KnowledgeReleaseReport {
-    release: KnowledgeRelease;
-    scorecard: ReleaseConfidenceScorecard;
-    candidateRuns: RunRecord[];
-    baselineRuns: RunRecord[];
+/**
+ * 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);
 }
 /**
- * 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.
+ * 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.
  */
-interface KnowledgeReleaseInput {
-    candidateId: string;
-    baselineId?: string;
-    candidateRuns: RunRecord[];
-    baselineRuns?: RunRecord[];
-    traces?: ReleaseTraceEvidence[];
-    gateDecision?: GateDecision | null;
+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;
     /**
-     * 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.
+     * 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.
      */
-    hasHoldout?: boolean;
-    /** Candidate is the search-best variant — a promotion precondition. Default true. */
-    promotedIsBest?: boolean;
-    createdAt?: string;
-    minScore?: number;
+    acceptOnParseFailure?: boolean;
 }
-declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
+/**
+ * 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 AddSourceOptions {
-    copyIntoRaw?: boolean;
-    adapters?: SourceAdapter[];
-    now?: () => Date;
-}
-interface AddSourceTextInput {
+/**
+ * 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;
-    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;
+    /** 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;
 }
-interface ValidateKnowledgeResult {
-    ok: boolean;
-    findings: KnowledgeLintFinding[];
+/**
+ * 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;
 }
-declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+/**
+ * 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;
 
-interface KnowledgeResearchLoopContext {
-    root: string;
-    goal: string;
-    iteration: number;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    previousSteps: KnowledgeResearchLoopStep[];
-    signal?: AbortSignal;
-}
-interface KnowledgeResearchLoopDecision {
+/**
+ * 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;
     /**
-     * Free-form notes from the researcher. Keep this human-readable; products can
-     * store it as the research transcript.
+     * 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.
      */
-    notes?: string;
+    diff?: {
+        before?: string;
+        after?: string;
+    };
     /**
-     * Local files to register as immutable sources before applying proposals.
+     * Eval dimensions to re-score. Computed as the union of both fragments'
+     * `dimensionHints`. The eval cron treats this as a set of campaign tags.
      */
-    sourcePaths?: string[];
+    affectedDimensions: string[];
+    /** URL of the affected authority page (from whichever side has it). */
+    url?: string;
     /**
-     * Textual source artifacts discovered by an agent, browser worker, connector,
-     * or deep-research process.
+     * 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.
      */
-    sourceTexts?: AddSourceTextInput[];
+    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 {
     /**
-     * Safe write protocol text. The loop parses and applies only accepted
-     * `---FILE: knowledge/...---` blocks.
+     * 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.
      */
-    proposalText?: string;
+    skipUnverifiable?: boolean;
     /**
-     * The researcher decides when the wiki is good enough. The loop deliberately
-     * does not encode a domain-specific definition of "done".
+     * 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.
      */
-    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;
+    filterDimensions?: string[];
 }
-interface KnowledgeResearchLoopResult {
-    root: string;
-    goal: string;
-    iterations: number;
-    done: boolean;
-    index: KnowledgeIndex;
-    lintFindings: KnowledgeLintFinding[];
-    validation: ValidateKnowledgeResult;
-    readiness?: EvalKnowledgeBundleBuildResult;
-    steps: KnowledgeResearchLoopStep[];
+declare function detectChanges(prev: KnowledgeFragment[], next: KnowledgeFragment[], options?: DetectChangesOptions): DetectChangesResult;
+
+interface ChunkingOptions {
+    targetChars: number;
+    maxChars: number;
+    minChars: number;
+    overlapChars: number;
 }
-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'>;
+interface KnowledgeChunk {
+    index: number;
+    text: string;
+    headingPath: string;
+    charStart: number;
+    charEnd: number;
+    oversized: boolean;
 }
-type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoopState, KnowledgeControlLoopAction, KnowledgeControlLoopActionResult, ControlEvalResult>, 'intent' | 'observe' | 'validate' | 'act' | 'shouldStop'>;
+declare function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[];
+declare function stripFrontmatter(content: string): {
+    body: string;
+    bodyOffset: number;
+};
+
 /**
- * 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.
+ * Claim-grounding mode for `runTwoAgentResearchLoop`.
+ *
+ * The two-agent loop's existing verifier judges a source's on-topic RELEVANCE
+ * (is this page about the goal?). On the topic sets we have measured, its
+ * cleanliness win is dominated by DE-DUPLICATION — which a deterministic
+ * content-hash / canonical-URL check captures at ~none of the LLM premium (see
+ * `docs/results/cost-quality.md`). That makes the LLM verifier look expensive
+ * for what a cheap rule already does.
+ *
+ * Claim-grounding targets a DIFFERENT, harder error band: a citation that is
+ * relevant and unique but **misattributed** — the page is on-topic, the URL is
+ * real, yet the specific CLAIM the source is cited for does NOT actually appear
+ * in the page. This is the citation-fabrication failure mode of LLM research:
+ * the model writes a plausible sentence and hangs a real URL off it that never
+ * says any such thing. Neither de-dup nor a relevance judge catches it (both can
+ * pass a misattributed-but-on-topic page); only checking the claim against the
+ * fetched text does.
+ *
+ * The check is EXECUTABLE GROUND TRUTH, not another LLM opinion: the worker
+ * attaches the specific claim it is citing the source for, and the verifier
+ * tests whether that claim is PRESENT (verbatim, normalized, or as a sufficient
+ * content-word overlap / close paraphrase) in the `htmlToText` output of the
+ * page the worker actually fetched. A claim that is not grounded is rejected as
+ * misattributed. Because the oracle is deterministic text presence — not a model
+ * call — it is a deployable, non-oracle verifier: it can run in production with
+ * zero inference cost, OR be composed with the LLM relevance verifier so the
+ * loop rejects BOTH off-topic AND misattributed sources.
+ *
+ * This module is content-free and any-topic: it adds (1) a way for a proposal to
+ * carry the claim it is cited for, (2) the `groundClaimInText` oracle, and (3) a
+ * `ResearchDriver` that gates on grounding. It composes the existing
+ * `ResearchDriver` / `ResearchSourceProposal` contracts and the shipped
+ * `htmlToText`; it reinvents none of them.
  */
-declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
-declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
 
 /**
- * Default standing instructions for a research supervisor. It does NOT solve the
- * research itself — it DECOMPOSES the goal into sub-topics and spawns one
- * researcher per sub-topic over the live `Scope`, widening/narrowing until the
- * readiness gate (the deliverable check) reports the knowledge base is ready.
+ * 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 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;
+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';
     /**
-     * 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.
+     * Fraction of the claim's content words found in the page text. 1 for a
+     * verbatim/normalized hit; the measured overlap otherwise.
      */
-    readinessSpecs: KnowledgeReadinessSpec[];
-    readinessTaskId?: string;
-    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
-    /** The conserved compute pool for the whole supervised run. */
-    budget: Budget;
+    overlap: number;
+    /** Content words present in the claim but NOT in the page text. */
+    missingWords: string[];
+}
+interface GroundClaimOptions {
     /**
-     * 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 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.
      */
-    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'>>;
+    minOverlap?: number;
+    /**
+     * Content words shorter than this are ignored (drops "the", "of", "is", …)
+     * and never count toward overlap. Default 3.
+     */
+    minWordLength?: number;
 }
 /**
- * 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 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 knowledgeReadinessDeliverable(options: Pick<ResearchSupervisorOptions, 'root' | 'goal' | 'readinessSpecs' | 'readinessTaskId' | 'readiness'>): DeliverableSpec<unknown>;
+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 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.
+ * 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.
  *
- * Needs creds (a real supervisor router brain + a worker backend), so it is the
- * LIVE path. The offline two-agent loop is `runTwoAgentResearchLoop`.
+ * The returned function matches `ResearchDriver['verifySource']`, so it drops
+ * straight into `runTwoAgentResearchLoop` as `{ verifySource: createClaimGroundingVerifier(...) }`.
  */
-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>;
-
-interface KnowledgeLayout {
-    root: string;
-    knowledgeDir: string;
-    rawSourcesDir: string;
-    sourceRegistryPath: string;
-    indexPath: string;
-    logPath: string;
-    cacheDir: string;
+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 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.
+ * 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.
  *
- * 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.
+ * 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 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 function createClaimDecorator(options?: WorkerClaimDecorationOptions): (source: ResearchSourceProposal, goal: string) => Promise<ResearchSourceProposal>;
 
-/**
- * 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. */
+interface DiscoveryTask {
     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;
+    goal: string;
+    query?: string;
+    sourceHints?: string[];
+    metadata?: Record<string, unknown>;
 }
-/** 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;
+interface DiscoveryResult {
+    taskId: string;
+    summary: string;
+    sourceUris?: string[];
+    claims?: Array<{
+        text: string;
+        sourceUri?: string;
+        confidence?: number;
+    }>;
+    followUpTasks?: DiscoveryTask[];
     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;
+interface KnowledgeDiscoveryWorker {
+    run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
 }
-/** A single rejected source plus the reason the driver gave. */
-interface RejectedSource {
-    source: ResearchSourceProposal;
-    reason: string;
+interface KnowledgeDiscoveryDispatcher {
+    dispatch(tasks: DiscoveryTask[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryResult[]>;
 }
-/** 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;
+declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
+
+interface KnowledgeEventQuery {
+    type?: KnowledgeEventType;
+    target?: string;
+    limit?: number;
 }
+declare function createKnowledgeEvent(input: {
+    type: KnowledgeEventType;
+    actor?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+    now?: () => Date;
+}): KnowledgeEvent;
+
 /**
- * The differentiated driver role.
+ * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
+ * was last successfully refreshed, and reports staleness against a TTL.
  *
- * - `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.
+ * 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.
  */
-interface ResearchDriver {
-    verifySource(source: ResearchSourceProposal, ctx: SourceVerificationContext): Promise<SourceVerdict> | SourceVerdict;
-    research?(ctx: DriverResearchContext): Promise<ResearchContribution> | ResearchContribution;
-    foldGaps?(gaps: KnowledgeGap[]): string;
+/** Identity for one freshness record. */
+interface FreshnessKey {
+    workspaceId: string;
+    sourceId: 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;
+/** TTL bound for staleness checks. */
+interface FreshnessTtl extends FreshnessKey {
+    /** Milliseconds — `Date.now() - last() > ttlMs` ⇒ stale. */
+    ttlMs: number;
+    /** Injected clock for deterministic tests; defaults to system time. */
+    now?: Date;
 }
-interface 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;
-    };
+/** Mark argument. */
+interface FreshnessMark extends FreshnessKey {
+    when: Date;
+    /** Optional content hash captured at refresh time; aids debugging. */
+    contentHash?: string;
 }
-interface TwoAgentResearchLoopResult {
+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;
-    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.
+ * 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.
  *
- * 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).
+ * 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 sourceMatchesGaps(source: ResearchSourceProposal, index: KnowledgeIndex, gaps: KnowledgeGap[]): KnowledgeSearchResult[];
-
+declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
 /**
- * Real web-research worker + verifying driver for `runTwoAgentResearchLoop`.
+ * 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.
  *
- * 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:
+ * The expected schema:
  *
- *   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`.
+ * ```sql
+ * CREATE TABLE knowledge_freshness (
+ *   workspace_id     TEXT NOT NULL,
+ *   source_id        TEXT NOT NULL,
+ *   last_refreshed_at TEXT NOT NULL,
+ *   content_hash     TEXT,
+ *   PRIMARY KEY (workspace_id, source_id)
+ * );
+ * ```
  */
+interface D1Adapter {
+    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
+    upsert(record: FreshnessRecord): Promise<void>;
+    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
+}
+declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
 
-/** One live web result, as the router's `/v1/search` returns it. */
-interface WebSearchHit {
-    title: string;
-    url: string;
-    snippet?: string;
+interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: 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>;
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
+
+declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
+
+declare function sha256(text: string): string;
+declare function slugify(input: string): string;
+declare function stableId(prefix: string, content: string): string;
+
+declare function buildKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
+declare function writeKnowledgeIndex(root: string): Promise<KnowledgeIndex>;
+
+interface KnowledgeInspection {
+    pageCount: number;
+    sourceCount: number;
+    expiredSourceCount: number;
+    staleSourceCount: number;
+    edgeCount: number;
+    findingCount: number;
+    blockingFindingCount: number;
+    topPages: Array<{
+        path: string;
+        title: string;
+        degree: number;
+        sources: number;
+    }>;
+    sourceFreshness: SourceFreshnessInspection[];
+    findings: KnowledgeLintFinding[];
 }
-interface 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;
+interface SourceFreshnessInspection {
+    id: string;
+    title?: string;
+    uri: string;
+    status: 'fresh' | 'expired' | 'unknown';
+    validUntil?: string;
+    lastVerifiedAt?: string;
 }
-/** 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);
+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;
+    }>;
 }
-/**
- * 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;
+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[]>;
+}
+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[];
+
+interface ApplyWriteBlocksResult {
+    written: string[];
+    warnings: string[];
 }
+declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
+declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
+
 /**
- * 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.
+ * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
+ *
+ * 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.
+ *
+ * Subject grammar this bridge understands (analyst-side convention,
+ * stamped in the kind prompts):
+ *
+ *   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
+ *
+ * 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.
  */
-declare function createWebResearchWorker(options?: WebResearchWorkerOptions): ResearchWorker;
-interface VerifyingDriverOptions {
-    router?: RouterClient;
-    router_options?: TangleRouterOptions;
+
+interface KnowledgeProposal {
     /**
-     * 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.
+     * Stable id derived from the finding so cross-run diffs share an
+     * identity. Re-proposing the same finding produces the same id.
      */
-    acceptOnParseFailure?: boolean;
+    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 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.
+ * 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.
  *
- * 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.
+ * 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.
  */
-declare function createVerifyingResearchDriver(options?: VerifyingDriverOptions): ResearchDriver;
+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[];
+}
+declare function proposeFromFindings(findings: ReadonlyArray<AnalystFinding>): ProposeFromFindingsResult;
+
+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;
+}
+declare function knowledgeReleaseReport(input: KnowledgeReleaseInput): KnowledgeReleaseReport;
+
+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>;
+
+/**
+ * Default standing instructions for a research supervisor. It does NOT solve the
+ * research itself — it DECOMPOSES the goal into sub-topics and spawns one
+ * researcher per sub-topic over the live `Scope`, widening/narrowing until the
+ * readiness gate (the deliverable check) reports the knowledge base is ready.
+ */
+declare const RESEARCH_SUPERVISOR_SYSTEM_PROMPT: string;
+interface ResearchSupervisorOptions {
+    /** Where the knowledge base lives. The deliverable check reads readiness here. */
+    root: string;
+    /** The research goal handed to the supervisor as its task. */
+    goal: string;
+    /**
+     * 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.
+     */
+    readinessSpecs: KnowledgeReadinessSpec[];
+    readinessTaskId?: string;
+    readiness?: Omit<BuildEvalKnowledgeBundleOptions, 'taskId' | 'index' | 'specs'>;
+    /** The conserved compute pool for the whole supervised run. */
+    budget: Budget;
+    /**
+     * 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.
+     */
+    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'>>;
+}
+/**
+ * Build the deliverable (completion oracle) for a research supervisor: "settled
+ * ⟺ the knowledge base is ready". It re-reads the KB from disk and runs the
+ * readiness gate, so the supervisor stops on the REAL grounded state — not on a
+ * worker's self-report.
+ */
+declare function knowledgeReadinessDeliverable(options: Pick<ResearchSupervisorOptions, 'root' | 'goal' | 'readinessSpecs' | 'readinessTaskId' | 'readiness'>): DeliverableSpec<unknown>;
+/**
+ * A research supervisor: a SUPERVISOR brain creates the topology dynamically —
+ * how many researchers, split by sub-topic — over the `Scope`, with the
+ * knowledge-readiness gate as its stop condition.
+ *
+ * This is a thin wrapper over `supervise(profile, goal, opts)`. It composes the
+ * existing pieces and builds nothing new: the researcher `AgentProfile` (from
+ * `researcherProfile`) is the worker shape the supervisor spawns, and
+ * `knowledgeReadinessDeliverable` (over `scoreKnowledgeReadiness`) is the
+ * completion oracle that decides when the KB is ready.
+ *
+ * Needs creds (a real supervisor router brain + a worker backend), so it is the
+ * LIVE path. The offline two-agent loop is `runTwoAgentResearchLoop`.
+ */
+declare function runResearchSupervisor(options: ResearchSupervisorOptions): Promise<SupervisedResult<unknown>>;
+
+declare 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;
+/**
+ * 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.
+ *
+ * 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.
+ */
+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 +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 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 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 };