@tangle-network/agent-knowledge 0.1.1 → 1.1.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { c as KnowledgeWriteParseResult, S as SourceRecord, d as KnowledgePage, e as SourceRegistry, b as KnowledgeGraph, f as KnowledgeIndex, g as KnowledgeSearchResult, h as KnowledgeLintFinding, i as KnowledgeBaseCandidate } from './types-C1FBNRIN.js';
-export { C as ClaimRef, j as KnowledgeClaim, K as KnowledgeGraphEdge, a as KnowledgeGraphNode, k as KnowledgeId, l as KnowledgePolicy, m as KnowledgeRelation, n as KnowledgeUnit, o as KnowledgeWriteBlock, p as SourceAnchor } from './types-C1FBNRIN.js';
-import { MultiShotVariant, MultiShotOptimizationConfig, MultiShotRunner, MultiShotScorer, MultiShotMutateAdapter, MultiShotOptimizationResult } from '@tangle-network/agent-eval';
+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-CWbf3JSE.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-CWbf3JSE.js';
+import { z } from 'zod';
+import { MultiShotVariant, MultiShotOptimizationConfig, MultiShotRunner, MultiShotScorer, MultiShotMutateAdapter, MultiShotOptimizationResult, ReleaseConfidenceScorecard, RunRecord, KnowledgeRequirementCategory, KnowledgeAcquisitionMode, KnowledgeImportance, KnowledgeFreshness, KnowledgeSensitivity, KnowledgeRequirement, KnowledgeBundle, KnowledgeReadinessReport, UserQuestion, DataAcquisitionPlan } from '@tangle-network/agent-eval';
 
 declare function sha256(text: string): string;
 declare function slugify(input: string): string;
@@ -48,6 +49,255 @@ interface ApplyWriteBlocksResult {
 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;
+}
+declare function createKnowledgeEvent(input: {
+    type: KnowledgeEventType;
+    actor?: string;
+    target?: string;
+    metadata?: Record<string, unknown>;
+    now?: () => Date;
+}): KnowledgeEvent;
+
+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>;
+}
+
+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 ChunkingOptions {
     targetChars: number;
     maxChars: number;
@@ -78,6 +328,23 @@ interface KnowledgeLayout {
     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>;
@@ -136,6 +403,15 @@ interface KnowledgeExplanation {
 }
 declare function explainKnowledgeTarget(index: KnowledgeIndex, target: string): KnowledgeExplanation;
 
+interface ValidateKnowledgeOptions {
+    strict?: boolean;
+}
+interface ValidateKnowledgeResult {
+    ok: boolean;
+    findings: KnowledgeLintFinding[];
+}
+declare function validateKnowledgeIndex(index: KnowledgeIndex, options?: ValidateKnowledgeOptions): ValidateKnowledgeResult;
+
 type KnowledgeBaseVariant = MultiShotVariant<KnowledgeBaseCandidate>;
 interface KnowledgeOptimizationConfig extends Omit<MultiShotOptimizationConfig<KnowledgeBaseCandidate>, 'runner' | 'scorer' | 'mutateAdapter' | 'target'> {
     target?: string;
@@ -150,4 +426,50 @@ declare function knowledgeVariantFromCandidate(candidate: KnowledgeBaseCandidate
     generation?: number;
 }): KnowledgeBaseVariant;
 
-export { type AddSourceOptions, type ApplyWriteBlocksResult, type ChunkingOptions, KnowledgeBaseCandidate, type KnowledgeBaseVariant, type KnowledgeChunk, type KnowledgeExplanation, KnowledgeGraph, KnowledgeIndex, type KnowledgeInspection, type KnowledgeLayout, KnowledgeLintFinding, type KnowledgeOptimizationConfig, KnowledgePage, KnowledgeSearchResult, KnowledgeWriteParseResult, type ParsedFrontmatter, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceRecord, SourceRegistry, WIKILINK_REGEX, addSourcePath, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, knowledgeVariantFromCandidate, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, reciprocalRankFusion, runKnowledgeBaseOptimization, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, writeJson, writeKnowledgeIndex, writeSourceRegistry };
+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 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>;
+}
+interface BuildEvalKnowledgeBundleOptions {
+    taskId: string;
+    index: KnowledgeIndex;
+    specs: KnowledgeReadinessSpec[];
+    userAnswers?: Record<string, string>;
+    searchLimit?: number;
+    metadata?: Record<string, unknown>;
+}
+interface EvalKnowledgeBundleBuildResult {
+    bundle: KnowledgeBundle;
+    report: KnowledgeReadinessReport;
+    requirements: KnowledgeRequirement[];
+    searchResultsByRequirement: Record<string, KnowledgeSearchResult[]>;
+    questions: UserQuestion[];
+    acquisitionPlans: DataAcquisitionPlan[];
+}
+declare function buildEvalKnowledgeBundle(options: BuildEvalKnowledgeBundleOptions): EvalKnowledgeBundleBuildResult;
+
+export { type AddSourceOptions, type ApplyWriteBlocksResult, type BuildEvalKnowledgeBundleOptions, type ChunkingOptions, type DiscoveryResult, type DiscoveryTask, type EvalKnowledgeBundleBuildResult, FileSystemKbStore, type KbStore, KnowledgeBaseCandidate, KnowledgeBaseCandidateSchema, type KnowledgeBaseVariant, type KnowledgeChunk, 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, KnowledgeSearchResult, KnowledgeWriteParseResult, MemoryKbStore, type ParsedFrontmatter, SCAFFOLD_PAGE_BASENAMES, type SourceAdapter, type SourceAdapterInput, type SourceAdapterOutput, SourceAnchorSchema, SourceRecord, SourceRecordSchema, SourceRegistry, type ValidateKnowledgeOptions, type ValidateKnowledgeResult, WIKILINK_REGEX, addSourcePath, applyKnowledgeWriteBlocks, applyKnowledgeWriteBlocksFile, buildEvalKnowledgeBundle, buildKnowledgeGraph, buildKnowledgeIndex, chunkMarkdown, createKnowledgeEvent, createLocalDiscoveryDispatcher, explainKnowledgeTarget, extractWikilinks, formatFrontmatter, initKnowledgeBase, inspectKnowledgeIndex, isSafeKnowledgePath, isScaffoldPath, knowledgeReleaseReportFromOptimization, knowledgeVariantFromCandidate, layoutFor, lintKnowledgeIndex, loadKnowledgePages, loadSourceRegistry, mediaTypeFor, normalizeLinkTarget, parseFrontmatter, parseKnowledgeWriteBlocks, reciprocalRankFusion, runKnowledgeBaseOptimization, searchKnowledge, sha256, slugify, sourceRegistryPath, stableId, stripFrontmatter, textSourceAdapter, tokenizeQuery, validateKnowledgeIndex, writeJson, writeKnowledgeIndex, writeSourceRegistry };

package/dist/index.js

@@ -1,4 +1,13 @@
 import {
+  KnowledgeBaseCandidateSchema,
+  KnowledgeEventSchema,
+  KnowledgeGraphEdgeSchema,
+  KnowledgeGraphNodeSchema,
+  KnowledgeIndexSchema,
+  KnowledgePageSchema,
+  SCAFFOLD_PAGE_BASENAMES,
+  SourceAnchorSchema,
+  SourceRecordSchema,
   WIKILINK_REGEX,
   addSourcePath,
   applyKnowledgeWriteBlocks,
@@ -11,6 +20,7 @@ import {
   initKnowledgeBase,
   inspectKnowledgeIndex,
   isSafeKnowledgePath,
+  isScaffoldPath,
   layoutFor,
   lintKnowledgeIndex,
   loadKnowledgePages,
@@ -27,10 +37,121 @@ import {
   stableId,
   textSourceAdapter,
   tokenizeQuery,
+  validateKnowledgeIndex,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-XDXIBHPS.js";
+} from "./chunk-BEFAI2HO.js";
+
+// src/events.ts
+function createKnowledgeEvent(input) {
+  const createdAt = (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+  return {
+    id: stableId("evt", `${input.type}:${input.target ?? ""}:${createdAt}:${JSON.stringify(input.metadata ?? {})}`),
+    type: input.type,
+    createdAt,
+    actor: input.actor,
+    target: input.target,
+    metadata: input.metadata
+  };
+}
+
+// src/kb-store.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+var MemoryKbStore = class {
+  sources = /* @__PURE__ */ new Map();
+  pages = /* @__PURE__ */ new Map();
+  events = [];
+  index = null;
+  async putSource(source) {
+    this.sources.set(source.id, clone(source));
+  }
+  async getSource(id) {
+    return clone(this.sources.get(id) ?? null);
+  }
+  async listSources() {
+    return [...this.sources.values()].map(clone);
+  }
+  async putPage(page) {
+    this.pages.set(page.id, clone(page));
+  }
+  async getPage(idOrPath) {
+    return clone(this.pages.get(idOrPath) ?? [...this.pages.values()].find((page) => page.path === idOrPath) ?? null);
+  }
+  async listPages() {
+    return [...this.pages.values()].map(clone);
+  }
+  async putIndex(index) {
+    this.index = clone(index);
+  }
+  async getIndex() {
+    if (this.index) return clone(this.index);
+    const pages = await this.listPages();
+    const sources = await this.listSources();
+    return { root: "memory", generatedAt: (/* @__PURE__ */ new Date()).toISOString(), sources, pages, graph: buildKnowledgeGraph(pages) };
+  }
+  async putEvent(event) {
+    this.events.push(clone(event));
+  }
+  async listEvents(query = {}) {
+    let out = this.events;
+    if (query.type) out = out.filter((event) => event.type === query.type);
+    if (query.target) out = out.filter((event) => event.target === query.target);
+    out = [...out].sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return out.slice(-(query.limit ?? out.length)).map(clone);
+  }
+};
+var FileSystemKbStore = class extends MemoryKbStore {
+  constructor(dir) {
+    super();
+    this.dir = dir;
+  }
+  dir;
+  async putIndex(index) {
+    await super.putIndex(index);
+    await writeJson2(join(this.dir, "index.json"), index);
+  }
+  async getIndex() {
+    try {
+      return JSON.parse(await readFile(join(this.dir, "index.json"), "utf8"));
+    } catch {
+      return await super.getIndex();
+    }
+  }
+  async putEvent(event) {
+    await super.putEvent(event);
+    const events = await this.listEvents();
+    await writeJson2(join(this.dir, "events.json"), events);
+  }
+};
+async function writeJson2(path, value) {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+}
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+// src/discovery.ts
+function createLocalDiscoveryDispatcher(worker) {
+  return {
+    async dispatch(tasks, options = {}) {
+      const concurrency = Math.max(1, options.concurrency ?? 4);
+      const results = [];
+      let cursor = 0;
+      async function runNext() {
+        while (cursor < tasks.length) {
+          if (options.signal?.aborted) throw new Error("Discovery dispatch aborted");
+          const task = tasks[cursor++];
+          results.push(await worker.run(task, options.signal));
+        }
+      }
+      await Promise.all(Array.from({ length: Math.min(concurrency, tasks.length) }, runNext));
+      return results.sort((a, b) => tasks.findIndex((task) => task.id === a.taskId) - tasks.findIndex((task) => task.id === b.taskId));
+    }
+  };
+}
 
 // src/chunking.ts
 var DEFAULT_OPTIONS = {
@@ -179,20 +300,159 @@ function knowledgeVariantFromCandidate(candidate, options = {}) {
     payload: candidate
   };
 }
+
+// src/release.ts
+import {
+  evaluateReleaseConfidence,
+  releaseTraceEvidenceFromMultiShotTrials,
+  validateRunRecord
+} from "@tangle-network/agent-eval";
+function knowledgeReleaseReportFromOptimization(result, options = {}) {
+  const trials = result.evolution.generations.flatMap((generation) => generation.trials);
+  const traceEvidence = releaseTraceEvidenceFromMultiShotTrials(trials);
+  const runRecords = (options.runRecords ?? [
+    ...result.gate?.candidateRuns ?? [],
+    ...result.gate?.baselineRuns ?? []
+  ]).map(validateRunRecord);
+  const scorecard = evaluateReleaseConfidence({
+    target: "agent-knowledge-base",
+    candidateId: result.promotedVariant.id,
+    baselineId: "baseline",
+    traces: traceEvidence,
+    runs: runRecords,
+    gateDecision: result.gate?.decision ?? null,
+    thresholds: {
+      requireCorpus: false,
+      requireHoldout: Boolean(result.gate),
+      minHoldoutRuns: result.gate ? 1 : 0,
+      minSearchRuns: 1,
+      minMeanScore: options.minScore ?? 0.7
+    }
+  });
+  const release = {
+    id: stableId("krel", `${result.promotedVariant.id}:${options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()}`),
+    candidateId: result.promotedVariant.id,
+    createdAt: options.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+    promoted: scorecard.status !== "fail" && result.promotedVariant.id === result.searchBestVariant.id,
+    scorecard,
+    runRecordIds: runRecords.map((record) => record.runId)
+  };
+  return {
+    release,
+    scorecard,
+    candidateRuns: result.gate?.candidateRuns ?? [],
+    baselineRuns: result.gate?.baselineRuns ?? []
+  };
+}
+
+// src/eval-readiness.ts
+import {
+  acquisitionPlansForKnowledgeGaps,
+  scoreKnowledgeReadiness,
+  userQuestionsForKnowledgeGaps
+} from "@tangle-network/agent-eval";
+function buildEvalKnowledgeBundle(options) {
+  const searchLimit = options.searchLimit ?? 5;
+  const searchResultsByRequirement = {};
+  const requirements = options.specs.map((spec) => {
+    const results = searchKnowledge(options.index, spec.query, searchLimit);
+    searchResultsByRequirement[spec.id] = results;
+    return requirementFromSearch(spec, results);
+  });
+  const report = scoreKnowledgeReadiness({
+    taskId: options.taskId,
+    requirements,
+    userAnswers: options.userAnswers,
+    evidenceIds: requirements.flatMap((requirement) => requirement.evidenceIds),
+    claimIds: [],
+    wikiPageIds: unique(requirements.flatMap((requirement) => pageIdsFromResults(searchResultsByRequirement[requirement.id] ?? []))),
+    metadata: options.metadata
+  });
+  const questions = userQuestionsForKnowledgeGaps(report.blockingMissingRequirements);
+  const acquisitionPlans = acquisitionPlansForKnowledgeGaps([
+    ...report.blockingMissingRequirements,
+    ...report.nonBlockingGaps
+  ]);
+  return {
+    bundle: report.bundle,
+    report,
+    requirements,
+    searchResultsByRequirement,
+    questions,
+    acquisitionPlans
+  };
+}
+function requirementFromSearch(spec, results) {
+  const hitCount = results.length;
+  const sourceIds = unique(results.flatMap((result) => result.page.sourceIds));
+  const bestScore = results[0]?.normalizedScore ?? 0;
+  const sourceCoverage = spec.minSources ? Math.min(1, sourceIds.length / spec.minSources) : sourceIds.length > 0 ? 1 : 0;
+  const hitCoverage = spec.minHits ? Math.min(1, hitCount / spec.minHits) : hitCount > 0 ? 1 : 0;
+  const currentConfidence = round(Math.min(bestScore, sourceCoverage, hitCoverage));
+  return {
+    id: spec.id,
+    description: spec.description,
+    requiredFor: spec.requiredFor,
+    category: spec.category,
+    acquisitionMode: spec.acquisitionMode,
+    importance: spec.importance,
+    freshness: spec.freshness,
+    sensitivity: spec.sensitivity,
+    confidenceNeeded: spec.confidenceNeeded,
+    currentConfidence,
+    evidenceIds: unique([
+      ...sourceIds.map((sourceId) => `source:${sourceId}`),
+      ...results.map((result) => `page:${result.page.id}`)
+    ]),
+    fallbackPolicy: spec.fallbackPolicy ?? (spec.importance === "blocking" ? "block" : "continue_with_caveat"),
+    metadata: {
+      ...spec.metadata,
+      query: spec.query,
+      hitCount,
+      sourceCount: sourceIds.length,
+      bestNormalizedScore: bestScore
+    }
+  };
+}
+function pageIdsFromResults(results) {
+  return results.map((result) => result.page.id);
+}
+function unique(items) {
+  return [...new Set(items)];
+}
+function round(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
 export {
+  FileSystemKbStore,
+  KnowledgeBaseCandidateSchema,
+  KnowledgeEventSchema,
+  KnowledgeGraphEdgeSchema,
+  KnowledgeGraphNodeSchema,
+  KnowledgeIndexSchema,
+  KnowledgePageSchema,
+  MemoryKbStore,
+  SCAFFOLD_PAGE_BASENAMES,
+  SourceAnchorSchema,
+  SourceRecordSchema,
   WIKILINK_REGEX,
   addSourcePath,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
+  buildEvalKnowledgeBundle,
   buildKnowledgeGraph,
   buildKnowledgeIndex,
   chunkMarkdown,
+  createKnowledgeEvent,
+  createLocalDiscoveryDispatcher,
   explainKnowledgeTarget,
   extractWikilinks,
   formatFrontmatter,
   initKnowledgeBase,
   inspectKnowledgeIndex,
   isSafeKnowledgePath,
+  isScaffoldPath,
+  knowledgeReleaseReportFromOptimization,
   knowledgeVariantFromCandidate,
   layoutFor,
   lintKnowledgeIndex,
@@ -212,6 +472,7 @@ export {
   stripFrontmatter,
   textSourceAdapter,
   tokenizeQuery,
+  validateKnowledgeIndex,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry