@tangle-network/agent-knowledge 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1,25 +1,9 @@
-import { c as KnowledgeWriteParseResult, S as SourceRecord, d as KnowledgeEventType, e as KnowledgeEvent, f as KnowledgePage, g as KnowledgeIndex, h as SourceRegistry, b as KnowledgeGraph, i as KnowledgeSearchResult, j as KnowledgeLintFinding, k as KnowledgeBaseCandidate, l as KnowledgeRelease } from './types-DTUp66Gr.js';
-export { C as ClaimRef, m as KnowledgeClaim, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, n as KnowledgeId, o as KnowledgePolicy, p as KnowledgeRelation, q as KnowledgeUnit, r as KnowledgeWriteBlock, s as SourceAnchor } from './types-DTUp66Gr.js';
+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 KnowledgeBaseCandidate, j as KnowledgeWriteBlock, k as KnowledgeClaim, l as KnowledgeRelease, m as SourceRegistry, n as KnowledgeWriteParseResult } from './types-CAeh7Lwb.js';
+export { C as ClaimRef, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, o as KnowledgeId, p as KnowledgePolicy, q as KnowledgeRelation, r as KnowledgeUnit, s as SourceAnchor } from './types-CAeh7Lwb.js';
+import { KnowledgeFragment } from './sources/index.js';
+export { CornellLiiSelector, CornellLiiSourceOptions, FetchOpts, FragmentProvenance, IRS_DIMENSION_HINTS, IrsPublicationsSourceOptions, KnowledgeSource, MAX_RESPONSE_BYTES, MIN_REQUEST_GAP_MS, POLITE_USER_AGENT, PoliteFetchOptions, PoliteFetchResult, StateSosEntity, StateSosSourceConfig, __resetHttpThrottle, createCornellLiiSource, createIrsPublicationsSource, createStateSosSource, extractLinks, firstMatch, htmlToText, innerHtmlById, looksLikeBlockPage, politeFetch } from './sources/index.js';
+import { KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, MultiShotVariant, MultiShotOptimizationConfig, MultiShotRunner, MultiShotScorer, MultiShotMutateAdapter, MultiShotOptimizationResult, AnalystSeverity, AnalystFinding, ReleaseConfidenceScorecard, RunRecord, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
 import { z } from 'zod';
-import { MultiShotVariant, MultiShotOptimizationConfig, MultiShotRunner, MultiShotScorer, MultiShotMutateAdapter, MultiShotOptimizationResult, ReleaseConfidenceScorecard, RunRecord, KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan, ControlRuntimeConfig, ControlEvalResult } from '@tangle-network/agent-eval';
-
-declare function sha256(text: string): string;
-declare function slugify(input: string): string;
-declare function stableId(prefix: string, content: string): string;
-
-interface ParsedFrontmatter {
-    frontmatter: Record<string, unknown>;
-    body: string;
-}
-declare function parseFrontmatter(content: string): ParsedFrontmatter;
-declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
-
-declare const WIKILINK_REGEX: RegExp;
-declare function extractWikilinks(content: string): string[];
-declare function normalizeLinkTarget(target: string): string;
-
-declare function isSafeKnowledgePath(path: string, allowedPrefixes?: string[]): boolean;
-declare function parseKnowledgeWriteBlocks(text: string, allowedPrefixes?: string[]): KnowledgeWriteParseResult;
 
 interface SourceAdapterInput {
     uri: string;
@@ -42,231 +26,109 @@ interface SourceAdapter {
 declare const textSourceAdapter: SourceAdapter;
 declare function mediaTypeFor(uri: string): string;
 
-interface ApplyWriteBlocksResult {
-    written: 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[];
 }
-declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
-declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
-
-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>;
-
-interface KnowledgeEventQuery {
-    type?: KnowledgeEventType;
-    target?: string;
-    limit?: number;
+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 createKnowledgeEvent(input: {
-    type: KnowledgeEventType;
-    actor?: string;
-    target?: string;
-    metadata?: Record<string, unknown>;
-    now?: () => Date;
-}): KnowledgeEvent;
+declare function detectChanges(prev: KnowledgeFragment[], next: KnowledgeFragment[], options?: DetectChangesOptions): DetectChangesResult;
 
-interface KbStore {
-    putSource(source: SourceRecord): Promise<void>;
-    getSource(id: string): Promise<SourceRecord | null>;
-    listSources(): Promise<SourceRecord[]>;
-    putPage(page: KnowledgePage): Promise<void>;
-    getPage(idOrPath: string): Promise<KnowledgePage | null>;
-    listPages(): Promise<KnowledgePage[]>;
-    putIndex(index: KnowledgeIndex): Promise<void>;
-    getIndex(): Promise<KnowledgeIndex | null>;
-    putEvent(event: KnowledgeEvent): Promise<void>;
-    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
-}
-declare class MemoryKbStore implements KbStore {
-    private readonly sources;
-    private readonly pages;
-    private readonly events;
-    private index;
-    putSource(source: SourceRecord): Promise<void>;
-    getSource(id: string): Promise<SourceRecord | null>;
-    listSources(): Promise<SourceRecord[]>;
-    putPage(page: KnowledgePage): Promise<void>;
-    getPage(idOrPath: string): Promise<KnowledgePage | null>;
-    listPages(): Promise<KnowledgePage[]>;
-    putIndex(index: KnowledgeIndex): Promise<void>;
-    getIndex(): Promise<KnowledgeIndex | null>;
-    putEvent(event: KnowledgeEvent): Promise<void>;
-    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
+interface ChunkingOptions {
+    targetChars: number;
+    maxChars: number;
+    minChars: number;
+    overlapChars: number;
 }
-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 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;
@@ -290,96 +152,241 @@ interface DiscoveryResult {
 interface KnowledgeDiscoveryWorker {
     run(task: DiscoveryTask, signal?: AbortSignal): Promise<DiscoveryResult> | DiscoveryResult;
 }
-interface KnowledgeDiscoveryDispatcher {
-    dispatch(tasks: DiscoveryTask[], options?: {
-        concurrency?: number;
-        signal?: AbortSignal;
-    }): Promise<DiscoveryResult[]>;
+interface KnowledgeDiscoveryDispatcher {
+    dispatch(tasks: DiscoveryTask[], options?: {
+        concurrency?: number;
+        signal?: AbortSignal;
+    }): Promise<DiscoveryResult[]>;
+}
+declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
+
+interface KnowledgeReadinessSpec {
+    id: string;
+    description: string;
+    query: string;
+    requiredFor: string[];
+    category: KnowledgeRequirementCategory;
+    acquisitionMode: KnowledgeAcquisitionMode;
+    importance: KnowledgeImportance;
+    freshness: KnowledgeFreshness;
+    sensitivity: KnowledgeSensitivity;
+    confidenceNeeded: number;
+    fallbackPolicy?: KnowledgeRequirement['fallbackPolicy'];
+    minSources?: number;
+    minHits?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Defaults applied by `defineReadinessSpec` when the caller omits the field.
+ *
+ * These are deliberately conservative: a domain-specific topic that an agent
+ * needs grounded to a high-confidence threshold from at least one authoritative
+ * source. Override any field to specialise (e.g. `freshness: 'daily'` for a
+ * topic that must reflect today's regulatory state).
+ */
+declare const READINESS_SPEC_DEFAULTS: {
+    readonly category: "domain_specific";
+    readonly acquisitionMode: "search_web";
+    readonly importance: "high";
+    readonly freshness: "monthly";
+    readonly sensitivity: "public";
+    readonly confidenceNeeded: 0.7;
+    readonly minSources: 1;
+    readonly minHits: 2;
+};
+/**
+ * Inputs accepted by `defineReadinessSpec`. The four fields the caller cannot
+ * sanely default (id, description, query, requiredFor) are required; everything
+ * else is optional and pulls from `READINESS_SPEC_DEFAULTS`.
+ */
+type DefineReadinessSpecInput = Pick<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'> & Partial<Omit<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'>>;
+/**
+ * Builder that returns a fully-typed `KnowledgeReadinessSpec` from a slim input.
+ *
+ * Motivation: `KnowledgeReadinessSpec` has eleven required fields. Most of them
+ * (category, acquisition mode, importance, freshness, sensitivity, confidence
+ * threshold, source/hit minima) have a clear default for domain-specific KB
+ * topics — agents end up copy-pasting the same boilerplate across every spec.
+ * This helper collapses that boilerplate while keeping every field overridable.
+ *
+ * @example
+ * defineReadinessSpec({
+ *   id: 'coop/intent-grounding',
+ *   description: 'Required grounding for coop pack intent stage',
+ *   query: 'flock size space ventilation predator',
+ *   requiredFor: ['IntentIntakeAgent', 'requirements'],
+ * })
+ *
+ * @example  // override defaults where the topic demands it
+ * defineReadinessSpec({
+ *   id: 'medical/dosing',
+ *   description: 'Dosing guidance for compounding pharmacy',
+ *   query: 'compounding dose schedule',
+ *   requiredFor: ['DosingAgent'],
+ *   importance: 'blocking',
+ *   freshness: 'daily',
+ *   sensitivity: 'private',
+ *   confidenceNeeded: 0.95,
+ *   minSources: 3,
+ * })
+ */
+declare function defineReadinessSpec(input: DefineReadinessSpecInput): KnowledgeReadinessSpec;
+interface BuildEvalKnowledgeBundleOptions {
+    taskId: string;
+    index: KnowledgeIndex;
+    specs: KnowledgeReadinessSpec[];
+    userAnswers?: Record<string, string>;
+    searchLimit?: number;
+    metadata?: Record<string, unknown>;
+    now?: Date;
+}
+interface EvalKnowledgeBundleBuildResult {
+    bundle: KnowledgeBundle;
+    report: KnowledgeReadinessReport;
+    requirements: KnowledgeRequirement[];
+    searchResultsByRequirement: Record<string, KnowledgeSearchResult[]>;
+    questions: UserQuestion[];
+    acquisitionPlans: DataAcquisitionPlan[];
 }
-declare function createLocalDiscoveryDispatcher(worker: KnowledgeDiscoveryWorker): KnowledgeDiscoveryDispatcher;
+declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
 
-interface ChunkingOptions {
-    targetChars: number;
-    maxChars: number;
-    minChars: number;
-    overlapChars: number;
-}
-interface KnowledgeChunk {
-    index: number;
-    text: string;
-    headingPath: string;
-    charStart: number;
-    charEnd: number;
-    oversized: boolean;
+interface KnowledgeEventQuery {
+    type?: KnowledgeEventType;
+    target?: string;
+    limit?: number;
 }
-declare function chunkMarkdown(content: string, options?: Partial<ChunkingOptions>): KnowledgeChunk[];
-declare function stripFrontmatter(content: string): {
-    body: string;
-    bodyOffset: number;
-};
+declare function createKnowledgeEvent(input: {
+    type: KnowledgeEventType;
+    actor?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+    now?: () => Date;
+}): KnowledgeEvent;
 
-interface KnowledgeLayout {
+/**
+ * Knowledge freshness store: tracks when each `(workspaceId, sourceId)` pair
+ * was last successfully refreshed, and reports staleness against a TTL.
+ *
+ * The contract is intentionally minimal — just enough to drive a cron loop:
+ *
+ *   ```ts
+ *   const store = createFileSystemFreshnessStore({ root: '.agent-knowledge' })
+ *   for (const source of sources) {
+ *     if (await store.stale({ workspaceId, sourceId: source.id, ttlMs: DAY })) {
+ *       const fragments = await source.fetch({ cacheDir })
+ *       await persistFragments(fragments)
+ *       await store.mark({ workspaceId, sourceId: source.id, when: new Date() })
+ *     }
+ *   }
+ *   ```
+ *
+ * Per-tenant isolation is enforced by `workspaceId` keying — there is no
+ * global mutable state across workspaces.
+ *
+ * Two adapters ship in-package:
+ *
+ *   - `createFileSystemFreshnessStore` — JSON file under the knowledge root,
+ *     mirrors the layout convention already used by `sources.json`.
+ *   - `createD1FreshnessStoreStub` — adapter scaffold for Cloudflare D1 /
+ *     Postgres. Production consumers should implement the `D1Adapter`
+ *     interface inside their own app; this stub exists to anchor the shape.
+ *
+ * @stable contract — interface is frozen at 0.x within this major.
+ * @stable filesystem adapter
+ * @experimental D1 stub — interface will evolve as real consumers wire it.
+ */
+/** Identity for one freshness record. */
+interface FreshnessKey {
+    workspaceId: string;
+    sourceId: string;
+}
+/** 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;
-    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.
+ * 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.
  *
- * Add new scaffold filenames here (and only here) to keep lint, validate, viz,
- * and the indexer consistent.
+ * 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 const SCAFFOLD_PAGE_BASENAMES: readonly string[];
+declare function createFileSystemFreshnessStore(options: FileSystemFreshnessStoreOptions): KnowledgeFreshnessStore;
 /**
- * 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.
+ * 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)
+ * );
+ * ```
  */
-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>;
-
-interface AddSourceOptions {
-    copyIntoRaw?: boolean;
-    adapters?: SourceAdapter[];
-    now?: () => Date;
+interface D1Adapter {
+    get(workspaceId: string, sourceId: string): Promise<FreshnessRecord | null>;
+    upsert(record: FreshnessRecord): Promise<void>;
+    listByWorkspace(workspaceId: string): Promise<FreshnessRecord[]>;
 }
-interface AddSourceTextInput {
-    uri: string;
-    text: string;
-    title?: string;
-    mediaType?: string;
-    validUntil?: string;
-    lastVerifiedAt?: string;
-    metadata?: Record<string, unknown>;
+declare function createD1FreshnessStoreStub(adapter: D1Adapter): KnowledgeFreshnessStore;
+
+interface ParsedFrontmatter {
+    frontmatter: Record<string, unknown>;
+    body: string;
 }
-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;
+declare function parseFrontmatter(content: string): ParsedFrontmatter;
+declare function formatFrontmatter(frontmatter: Record<string, unknown>, body: string): string;
 
 declare function buildKnowledgeGraph(pages: KnowledgePage[]): KnowledgeGraph;
 
-declare function searchKnowledge(index: KnowledgeIndex, query: string, limit?: number): KnowledgeSearchResult[];
-declare function tokenizeQuery(query: string): string[];
-declare function reciprocalRankFusion(rankLists: string[][], k?: number): Map<string, number>;
+declare function 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>;
 
-declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
-
 interface KnowledgeInspection {
     pageCount: number;
     sourceCount: number;
@@ -426,14 +433,43 @@ interface KnowledgeExplanation {
 }
 declare function explainKnowledgeTarget(index: KnowledgeIndex, target: string): KnowledgeExplanation;
 
-interface ValidateKnowledgeOptions {
-    strict?: boolean;
+interface KbStore {
+    putSource(source: SourceRecord): Promise<void>;
+    getSource(id: string): Promise<SourceRecord | null>;
+    listSources(): Promise<SourceRecord[]>;
+    putPage(page: KnowledgePage): Promise<void>;
+    getPage(idOrPath: string): Promise<KnowledgePage | null>;
+    listPages(): Promise<KnowledgePage[]>;
+    putIndex(index: KnowledgeIndex): Promise<void>;
+    getIndex(): Promise<KnowledgeIndex | null>;
+    putEvent(event: KnowledgeEvent): Promise<void>;
+    listEvents(query?: KnowledgeEventQuery): Promise<KnowledgeEvent[]>;
 }
-interface ValidateKnowledgeResult {
-    ok: boolean;
-    findings: KnowledgeLintFinding[];
+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 validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+
+declare function lintKnowledgeIndex(index: KnowledgeIndex): KnowledgeLintFinding[];
 
 type KnowledgeBaseVariant = MultiShotVariant<KnowledgeBaseCandidate>;
 interface KnowledgeOptimizationConfig extends Omit<MultiShotOptimizationConfig<KnowledgeBaseCandidate>, 'runner' | 'scorer' | 'mutateAdapter' | 'target'> {
@@ -449,107 +485,139 @@ declare function knowledgeVariantFromCandidate(candidate: KnowledgeBaseCandidate
     generation?: number;
 }): KnowledgeBaseVariant;
 
-interface KnowledgeReleaseReport {
-    release: KnowledgeRelease;
-    scorecard: ReleaseConfidenceScorecard;
-    candidateRuns: RunRecord[];
-    baselineRuns: RunRecord[];
+interface ApplyWriteBlocksResult {
+    written: string[];
+    warnings: string[];
 }
-declare function knowledgeReleaseReportFromOptimization(result: MultiShotOptimizationResult<KnowledgeBaseCandidate>, options?: {
-    runRecords?: RunRecord[];
-    createdAt?: string;
-    minScore?: number;
-}): KnowledgeReleaseReport;
+declare function applyKnowledgeWriteBlocks(root: string, proposalText: string): Promise<ApplyWriteBlocksResult>;
+declare function applyKnowledgeWriteBlocksFile(root: string, proposalPath: string): Promise<ApplyWriteBlocksResult>;
 
-interface KnowledgeReadinessSpec {
-    id: string;
-    description: string;
-    query: string;
-    requiredFor: string[];
-    category: KnowledgeRequirementCategory;
-    acquisitionMode: KnowledgeAcquisitionMode;
-    importance: KnowledgeImportance;
-    freshness: KnowledgeFreshness;
-    sensitivity: KnowledgeSensitivity;
-    confidenceNeeded: number;
-    fallbackPolicy?: KnowledgeRequirement['fallbackPolicy'];
-    minSources?: number;
-    minHits?: number;
-    metadata?: Record<string, unknown>;
-}
 /**
- * Defaults applied by `defineReadinessSpec` when the caller omits the field.
+ * Bridge from `AnalystFinding` (agent-eval) to knowledge proposals.
  *
- * These are deliberately conservative: a domain-specific topic that an agent
- * needs grounded to a high-confidence threshold from at least one authoritative
- * source. Override any field to specialise (e.g. `freshness: 'daily'` for a
- * topic that must reflect today's regulatory state).
+ * 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 const READINESS_SPEC_DEFAULTS: {
-    readonly category: "domain_specific";
-    readonly acquisitionMode: "search_web";
-    readonly importance: "high";
-    readonly freshness: "monthly";
-    readonly sensitivity: "public";
-    readonly confidenceNeeded: 0.7;
-    readonly minSources: 1;
-    readonly minHits: 2;
-};
+
+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);
+}
 /**
- * Inputs accepted by `defineReadinessSpec`. The four fields the caller cannot
- * sanely default (id, description, query, requiredFor) are required; everything
- * else is optional and pulls from `READINESS_SPEC_DEFAULTS`.
+ * Convert one `AnalystFinding` into a knowledge proposal. Returns
+ * `null` when the finding's locus isn't a knowledge-base concern
+ * (`websearch:outdated:*`, `tool-doc:*`, `system-prompt:*`,
+ * `memory:*`, missing subject). Throws when the locus IS a
+ * knowledge-base concern but is malformed — that's a bug in the
+ * analyst prompt and should fail loud.
+ *
+ * Caller convention: feed the function the analyst's full findings
+ * list and filter out the `null`s; the orchestrator passes the
+ * remaining proposals to the existing review / apply pipeline.
  */
-type DefineReadinessSpecInput = Pick<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'> & Partial<Omit<KnowledgeReadinessSpec, 'id' | 'description' | 'query' | 'requiredFor'>>;
+declare function proposeFromFinding(finding: AnalystFinding): KnowledgeProposal | null;
 /**
- * Builder that returns a fully-typed `KnowledgeReadinessSpec` from a slim input.
- *
- * Motivation: `KnowledgeReadinessSpec` has eleven required fields. Most of them
- * (category, acquisition mode, importance, freshness, sensitivity, confidence
- * threshold, source/hit minima) have a clear default for domain-specific KB
- * topics — agents end up copy-pasting the same boilerplate across every spec.
- * This helper collapses that boilerplate while keeping every field overridable.
- *
- * @example
- * defineReadinessSpec({
- *   id: 'coop/intent-grounding',
- *   description: 'Required grounding for coop pack intent stage',
- *   query: 'flock size space ventilation predator',
- *   requiredFor: ['IntentIntakeAgent', 'requirements'],
- * })
- *
- * @example  // override defaults where the topic demands it
- * defineReadinessSpec({
- *   id: 'medical/dosing',
- *   description: 'Dosing guidance for compounding pharmacy',
- *   query: 'compounding dose schedule',
- *   requiredFor: ['DosingAgent'],
- *   importance: 'blocking',
- *   freshness: 'daily',
- *   sensitivity: 'private',
- *   confidenceNeeded: 0.95,
- *   minSources: 3,
- * })
+ * 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.
  */
-declare function defineReadinessSpec(input: DefineReadinessSpecInput): KnowledgeReadinessSpec;
-interface BuildEvalKnowledgeBundleOptions {
-    taskId: string;
-    index: KnowledgeIndex;
-    specs: KnowledgeReadinessSpec[];
-    userAnswers?: Record<string, string>;
-    searchLimit?: number;
+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[];
+}
+declare function knowledgeReleaseReportFromOptimization(result: MultiShotOptimizationResult<KnowledgeBaseCandidate>, options?: {
+    runRecords?: RunRecord[];
+    createdAt?: string;
+    minScore?: number;
+}): KnowledgeReleaseReport;
+
+interface AddSourceOptions {
+    copyIntoRaw?: boolean;
+    adapters?: SourceAdapter[];
+    now?: () => Date;
+}
+interface AddSourceTextInput {
+    uri: string;
+    text: string;
+    title?: string;
+    mediaType?: string;
+    validUntil?: string;
+    lastVerifiedAt?: string;
     metadata?: Record<string, unknown>;
-    now?: Date;
 }
-interface EvalKnowledgeBundleBuildResult {
-    bundle: KnowledgeBundle;
-    report: KnowledgeReadinessReport;
-    requirements: KnowledgeRequirement[];
-    searchResultsByRequirement: Record<string, KnowledgeSearchResult[]>;
-    questions: UserQuestion[];
-    acquisitionPlans: DataAcquisitionPlan[];
+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;
 }
-declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
+interface ValidateKnowledgeResult {
+    ok: boolean;
+    findings: KnowledgeLintFinding[];
+}
+declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
 
 interface KnowledgeResearchLoopContext {
     root: string;
@@ -648,4 +716,216 @@ type KnowledgeControlLoopAdapter = Pick<ControlRuntimeConfig<KnowledgeControlLoo
 declare function createKnowledgeControlLoopAdapter(options: KnowledgeControlLoopAdapterOptions): KnowledgeControlLoopAdapter;
 declare function runKnowledgeResearchLoop(options: RunKnowledgeResearchLoopOptions): Promise<KnowledgeResearchLoopResult>;
 
-export { type AddSourceOptions, type AddSourceTextInput, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type DefineReadinessSpecInput, type DiscoveryResult, type DiscoveryTask, type EvalKnowledgeBundleBuildResult, FileSystemKbStore, type KbStore, KnowledgeBaseCandidate, KnowledgeBaseCandidateSchema, type KnowledgeBaseVariant, type KnowledgeChunk, type KnowledgeControlLoopAction, type KnowledgeControlLoopActionResult, type KnowledgeControlLoopAdapter, type KnowledgeControlLoopAdapterOptions, type KnowledgeControlLoopState, type KnowledgeDiscoveryDispatcher, type KnowledgeDiscoveryWorker, KnowledgeEvent, type KnowledgeEventQuery, KnowledgeEventSchema, KnowledgeEventType, type KnowledgeExplanation, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, type KnowledgeOptimizationConfig, KnowledgePage, KnowledgePageSchema, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, READINESS_SPEC_DEFAULTS, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, defineReadinessSpec, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReleaseReportFromOptimization, knowledgeVariantFromCandidate, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, reciprocalRankFusion, runKnowledgeBaseOptimization, runKnowledgeResearchLoop, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+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[];
+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 EvalKnowledgeBundleBuildResult, type FileSystemFreshnessStoreOptions, FileSystemKbStore, type FreshnessKey, type FreshnessMark, type FreshnessRecord, type FreshnessTtl, type KbStore, KnowledgeBaseCandidate, KnowledgeBaseCandidateSchema, type KnowledgeBaseVariant, 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, KnowledgeGraph, KnowledgeGraphEdgeSchema, KnowledgeGraphNodeSchema, KnowledgeIndex, KnowledgeIndexSchema, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, type KnowledgeOptimizationConfig, KnowledgePage, KnowledgePageSchema, type KnowledgeProposal, KnowledgeProposalParseError, type KnowledgeReadinessSpec, KnowledgeRelease, type KnowledgeReleaseReport, type KnowledgeResearchLoopContext, type KnowledgeResearchLoopDecision, type KnowledgeResearchLoopResult, type KnowledgeResearchLoopStep, KnowledgeSearchResult, KnowledgeWriteBlock, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, type ProposeFromFindingsResult, READINESS_SPEC_DEFAULTS, type RunKnowledgeResearchLoopOptions, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, type SourceFreshnessInspection, SourceRecord, SourceRecordSchema, SourceRegistry, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, addSourcePath, addSourceText, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createD1FreshnessStoreStub, createFileSystemFreshnessStore, createKnowledgeControlLoopAdapter, createKnowledgeEvent, createLocalDiscoveryDispatcher, defineReadinessSpec, detectChanges, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReleaseReportFromOptimization, knowledgeVariantFromCandidate, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, proposeFromFinding, proposeFromFindings, reciprocalRankFusion, runKnowledgeBaseOptimization, runKnowledgeResearchLoop, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };