@tangle-network/agent-knowledge 1.1.1 → 1.3.0

package/dist/index.js

@@ -10,6 +10,7 @@ import {
   SourceRecordSchema,
   WIKILINK_REGEX,
   addSourcePath,
+  addSourceText,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
   buildKnowledgeGraph,
@@ -31,126 +32,113 @@ import {
   parseKnowledgeWriteBlocks,
   reciprocalRankFusion,
   searchKnowledge,
-  sha256,
-  slugify,
   sourceRegistryPath,
-  stableId,
   textSourceAdapter,
   tokenizeQuery,
   validateKnowledgeIndex,
   writeJson,
   writeKnowledgeIndex,
   writeSourceRegistry
-} from "./chunk-JWGMOXAT.js";
+} from "./chunk-HKYD765Q.js";
+import {
+  IRS_DIMENSION_HINTS,
+  MAX_RESPONSE_BYTES,
+  MIN_REQUEST_GAP_MS,
+  POLITE_USER_AGENT,
+  __resetHttpThrottle,
+  createCornellLiiSource,
+  createIrsPublicationsSource,
+  createStateSosSource,
+  extractLinks,
+  firstMatch,
+  htmlToText,
+  innerHtmlById,
+  looksLikeBlockPage,
+  politeFetch
+} from "./chunk-WCYW2GDA.js";
+import {
+  sha256,
+  slugify,
+  stableId
+} from "./chunk-YMKHCTS2.js";
 
-// src/events.ts
-function createKnowledgeEvent(input) {
-  const createdAt = (input.now ?? (() => /* @__PURE__ */ new Date()))().toISOString();
+// src/changes.ts
+function detectChanges(prev, next, options = {}) {
+  const skipUnverifiable = options.skipUnverifiable ?? true;
+  const warnings = [];
+  const { map: prevMap, warnings: prevWarn } = indexFragments(prev, skipUnverifiable, "prev");
+  const { map: nextMap, warnings: nextWarn } = indexFragments(next, skipUnverifiable, "next");
+  warnings.push(...prevWarn, ...nextWarn);
+  const changes = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [id, nextFragment] of nextMap) {
+    seen.add(id);
+    const prevFragment = prevMap.get(id);
+    if (!prevFragment) {
+      changes.push({
+        fragmentId: id,
+        kind: "added",
+        diff: { after: nextFragment.body },
+        affectedDimensions: dedup(nextFragment.dimensionHints),
+        url: nextFragment.provenance.url,
+        detectedAt: nextFragment.provenance.sourceUpdatedAt
+      });
+      continue;
+    }
+    if (prevFragment.bodyHash !== nextFragment.bodyHash) {
+      changes.push({
+        fragmentId: id,
+        kind: "modified",
+        diff: { before: prevFragment.body, after: nextFragment.body },
+        affectedDimensions: dedup([...prevFragment.dimensionHints, ...nextFragment.dimensionHints]),
+        url: nextFragment.provenance.url,
+        detectedAt: nextFragment.provenance.sourceUpdatedAt
+      });
+    }
+  }
+  for (const [id, prevFragment] of prevMap) {
+    if (seen.has(id)) continue;
+    changes.push({
+      fragmentId: id,
+      kind: "removed",
+      diff: { before: prevFragment.body },
+      affectedDimensions: dedup(prevFragment.dimensionHints),
+      url: prevFragment.provenance.url,
+      detectedAt: prevFragment.provenance.sourceUpdatedAt
+    });
+  }
+  const filtered = options.filterDimensions ? changes.filter((c) => c.affectedDimensions.some((d) => options.filterDimensions?.includes(d))) : changes;
   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
+    changes: filtered,
+    summary: {
+      added: filtered.filter((c) => c.kind === "added").length,
+      removed: filtered.filter((c) => c.kind === "removed").length,
+      modified: filtered.filter((c) => c.kind === "modified").length
+    },
+    warnings
   };
 }
-
-// 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();
+function indexFragments(fragments, skipUnverifiable, side) {
+  const map = /* @__PURE__ */ new Map();
+  const warnings = [];
+  let dropped = 0;
+  for (const fragment of fragments) {
+    if (skipUnverifiable && !fragment.provenance.verifiable) {
+      dropped += 1;
+      continue;
+    }
+    if (map.has(fragment.id)) {
+      warnings.push(`${side}: duplicate fragment id ${fragment.id} \u2014 keeping last`);
     }
+    map.set(fragment.id, fragment);
   }
-  async putEvent(event) {
-    await super.putEvent(event);
-    const events = await this.listEvents();
-    await writeJson2(join(this.dir, "events.json"), events);
+  if (dropped > 0) {
+    warnings.push(`${side}: dropped ${dropped} unverifiable fragment(s) before diff`);
   }
-};
-async function writeJson2(path, value) {
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(value, null, 2) + "\n", "utf8");
+  return { map, warnings };
 }
-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));
-    }
-  };
+function dedup(items) {
+  return [...new Set(items)];
 }
 
 // src/chunking.ts
@@ -197,12 +185,17 @@ function splitSections(body, bodyOffset) {
   const lines = body.split("\n");
   const sections = [];
   const headings = {};
-  let current = { lines: [], start: bodyOffset, headingPath: "" };
+  let current = {
+    lines: [],
+    start: bodyOffset,
+    headingPath: ""
+  };
   let cursor = bodyOffset;
   let fence = null;
   const flush = () => {
     const text = current.lines.join("\n");
-    if (text.trim() !== "") sections.push({ text, start: current.start, headingPath: current.headingPath });
+    if (text.trim() !== "")
+      sections.push({ text, start: current.start, headingPath: current.headingPath });
   };
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
@@ -282,66 +275,25 @@ ${chunk.text}`;
   return out;
 }
 
-// src/optimization.ts
-import {
-  runMultiShotOptimization
-} from "@tangle-network/agent-eval";
-async function runKnowledgeBaseOptimization(config) {
-  return runMultiShotOptimization({
-    ...config,
-    target: config.target ?? "agent-knowledge-base"
-  });
-}
-function knowledgeVariantFromCandidate(candidate, options = {}) {
+// src/discovery.ts
+function createLocalDiscoveryDispatcher(worker) {
   return {
-    id: options.id ?? candidate.id,
-    label: options.label ?? candidate.id,
-    generation: options.generation ?? 0,
-    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
+    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)
+      );
     }
-  });
-  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 ?? []
   };
 }
 
@@ -351,6 +303,22 @@ import {
   scoreKnowledgeReadiness,
   userQuestionsForKnowledgeGaps
 } from "@tangle-network/agent-eval";
+var READINESS_SPEC_DEFAULTS = {
+  category: "domain_specific",
+  acquisitionMode: "search_web",
+  importance: "high",
+  freshness: "monthly",
+  sensitivity: "public",
+  confidenceNeeded: 0.7,
+  minSources: 1,
+  minHits: 2
+};
+function defineReadinessSpec(input) {
+  return {
+    ...READINESS_SPEC_DEFAULTS,
+    ...input
+  };
+}
 function buildEvalKnowledgeBundle(options) {
   const searchLimit = options.searchLimit ?? 5;
   const now = options.now ?? /* @__PURE__ */ new Date();
@@ -366,7 +334,11 @@ function buildEvalKnowledgeBundle(options) {
     userAnswers: options.userAnswers,
     evidenceIds: requirements.flatMap((requirement) => requirement.evidenceIds),
     claimIds: [],
-    wikiPageIds: unique(requirements.flatMap((requirement) => pageIdsFromResults(searchResultsByRequirement[requirement.id] ?? []))),
+    wikiPageIds: unique(
+      requirements.flatMap(
+        (requirement) => pageIdsFromResults(searchResultsByRequirement[requirement.id] ?? [])
+      )
+    ),
     metadata: options.metadata
   });
   const questions = userQuestionsForKnowledgeGaps(report.blockingMissingRequirements);
@@ -423,7 +395,9 @@ function requirementFromSearch(index, spec, results, now) {
 }
 function sourceFreshness(sources, now) {
   if (sources.length === 0) return { score: 0, expiredSourceIds: [] };
-  const validUntilValues = sources.map((source) => source.validUntil ?? stringMetadata(source.metadata, "validUntil") ?? stringMetadata(source.metadata, "expiresAt")).filter(isIsoDate);
+  const validUntilValues = sources.map(
+    (source) => source.validUntil ?? stringMetadata(source.metadata, "validUntil") ?? stringMetadata(source.metadata, "expiresAt")
+  ).filter(isIsoDate);
   const lastVerifiedValues = sources.map((source) => source.lastVerifiedAt ?? stringMetadata(source.metadata, "lastVerifiedAt")).filter(isIsoDate);
   const expiredSourceIds = sources.filter((source) => {
     const validUntil = source.validUntil ?? stringMetadata(source.metadata, "validUntil") ?? stringMetadata(source.metadata, "expiresAt");
@@ -458,32 +432,657 @@ function unique(items) {
 function round(value) {
   return Math.round(value * 1e3) / 1e3;
 }
+
+// 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/freshness.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+function createFileSystemFreshnessStore(options) {
+  const path = join(options.root, ".agent-knowledge", "freshness.json");
+  let writeQueue = Promise.resolve();
+  const read = async () => {
+    try {
+      const text = await readFile(path, "utf8");
+      const parsed = JSON.parse(text);
+      return parsed.records ?? {};
+    } catch {
+      return {};
+    }
+  };
+  const write = async (records) => {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify({ records }, null, 2)}
+`, "utf8");
+  };
+  return {
+    async last(key) {
+      const records = await read();
+      const record = records[buildKey(key)];
+      return record ? new Date(record.lastRefreshedAt) : null;
+    },
+    async mark(input) {
+      writeQueue = writeQueue.then(async () => {
+        const records = await read();
+        records[buildKey(input)] = {
+          workspaceId: input.workspaceId,
+          sourceId: input.sourceId,
+          lastRefreshedAt: input.when.toISOString(),
+          contentHash: input.contentHash
+        };
+        await write(records);
+      });
+      await writeQueue;
+    },
+    async stale(input) {
+      const last = await this.last(input);
+      if (!last) return true;
+      const now = input.now ?? /* @__PURE__ */ new Date();
+      return now.getTime() - last.getTime() > input.ttlMs;
+    },
+    async list(workspaceId) {
+      const records = await read();
+      return Object.values(records).filter((r) => r.workspaceId === workspaceId);
+    }
+  };
+}
+function createD1FreshnessStoreStub(adapter) {
+  return {
+    async last(key) {
+      const record = await adapter.get(key.workspaceId, key.sourceId);
+      return record ? new Date(record.lastRefreshedAt) : null;
+    },
+    async mark(input) {
+      await adapter.upsert({
+        workspaceId: input.workspaceId,
+        sourceId: input.sourceId,
+        lastRefreshedAt: input.when.toISOString(),
+        contentHash: input.contentHash
+      });
+    },
+    async stale(input) {
+      const last = await this.last(input);
+      if (!last) return true;
+      const now = input.now ?? /* @__PURE__ */ new Date();
+      return now.getTime() - last.getTime() > input.ttlMs;
+    },
+    async list(workspaceId) {
+      return adapter.listByWorkspace(workspaceId);
+    }
+  };
+}
+function buildKey(key) {
+  return `${key.workspaceId}::${key.sourceId}`;
+}
+
+// src/kb-store.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname2, join as join2 } 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(join2(this.dir, "index.json"), index);
+  }
+  async getIndex() {
+    try {
+      return JSON.parse(await readFile2(join2(this.dir, "index.json"), "utf8"));
+    } catch {
+      return await super.getIndex();
+    }
+  }
+  async putEvent(event) {
+    await super.putEvent(event);
+    const events = await this.listEvents();
+    await writeJson2(join2(this.dir, "events.json"), events);
+  }
+};
+async function writeJson2(path, value) {
+  await mkdir2(dirname2(path), { recursive: true });
+  await writeFile2(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+// src/optimization.ts
+import {
+  runMultiShotOptimization
+} from "@tangle-network/agent-eval";
+async function runKnowledgeBaseOptimization(config) {
+  return runMultiShotOptimization({
+    ...config,
+    target: config.target ?? "agent-knowledge-base"
+  });
+}
+function knowledgeVariantFromCandidate(candidate, options = {}) {
+  return {
+    id: options.id ?? candidate.id,
+    label: options.label ?? candidate.id,
+    generation: options.generation ?? 0,
+    payload: candidate
+  };
+}
+
+// src/propose-from-finding.ts
+var KnowledgeProposalParseError = class extends Error {
+  constructor(findingId, subject, message) {
+    super(`proposeFromFinding(${findingId}, subject=${subject}): ${message}`);
+    this.findingId = findingId;
+    this.subject = subject;
+    this.name = "KnowledgeProposalParseError";
+  }
+  findingId;
+  subject;
+};
+function proposeFromFinding(finding) {
+  if (!finding.subject) return null;
+  if (!finding.subject.startsWith("agent-knowledge:")) return null;
+  const rest = finding.subject.slice("agent-knowledge:".length);
+  const [kindPart, ...locusParts] = rest.split(":");
+  const locus = locusParts.join(":");
+  if (!kindPart || !locus) {
+    throw new KnowledgeProposalParseError(
+      finding.finding_id,
+      finding.subject,
+      "expected `agent-knowledge:<kind>:<locus>` shape"
+    );
+  }
+  const baseMeta = {
+    severity: finding.severity,
+    confidence: finding.confidence,
+    evidence_uri: finding.evidence_refs[0]?.uri,
+    analyst_id: finding.analyst_id
+  };
+  switch (kindPart) {
+    case "wiki":
+      return wikiProposal(finding, locus, baseMeta);
+    case "claim":
+      return claimProposal(finding, locus, baseMeta);
+    case "raw":
+      return liftRawProposal(finding, locus, baseMeta);
+    case "stale":
+      return markStaleProposal(finding, locus, baseMeta);
+    default:
+      throw new KnowledgeProposalParseError(
+        finding.finding_id,
+        finding.subject,
+        `unknown kind "${kindPart}" (expected one of: wiki | claim | raw | stale)`
+      );
+  }
+}
+function wikiProposal(finding, locus, metadata) {
+  const hashIdx = locus.indexOf("#");
+  const pageSlug = hashIdx >= 0 ? locus.slice(0, hashIdx) : locus;
+  const heading = hashIdx >= 0 ? locus.slice(hashIdx + 1) : null;
+  const path = `knowledge/${ensureSlug(pageSlug)}.md`;
+  const body = renderWikiBody(finding, pageSlug, heading);
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: heading ? "append-section" : "create-page",
+    locus: pageSlug,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function claimProposal(finding, locus, metadata) {
+  const refs = finding.evidence_refs.filter((r) => r.uri).map((r) => ({
+    sourceId: `analyst-finding:${finding.finding_id}`,
+    anchorId: r.uri,
+    quote: r.excerpt
+  }));
+  const claim = {
+    id: `claim-${finding.finding_id}`,
+    text: finding.recommended_action ?? finding.claim,
+    refs,
+    confidence: finding.confidence,
+    status: "draft",
+    metadata: {
+      analyst_id: finding.analyst_id,
+      source_finding_id: finding.finding_id,
+      topic: locus
+    }
+  };
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "create-claim",
+    locus,
+    writeBlocks: [],
+    claim,
+    metadata
+  };
+}
+function liftRawProposal(finding, sourceId, metadata) {
+  const path = `knowledge/${ensureSlug(sourceId)}.md`;
+  const body = [
+    "---",
+    `title: ${sourceId}`,
+    `source: ${sourceId}`,
+    `status: draft`,
+    `lifted_from_finding: ${finding.finding_id}`,
+    "---",
+    "",
+    "## Why this page exists",
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "lift-raw",
+    locus: sourceId,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function markStaleProposal(finding, pageSlug, metadata) {
+  const path = `knowledge/${ensureSlug(pageSlug)}.stale.md`;
+  const body = [
+    "---",
+    `title: ${pageSlug} (marked stale)`,
+    `status: superseded`,
+    `superseded_by_finding: ${finding.finding_id}`,
+    `confidence: ${finding.confidence}`,
+    "---",
+    "",
+    "## Why marked stale",
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Evidence", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+  return {
+    id: `prop-${finding.finding_id}`,
+    sourceFindingId: finding.finding_id,
+    kind: "mark-stale",
+    locus: pageSlug,
+    writeBlocks: [{ path, content: body }],
+    metadata
+  };
+}
+function proposeFromFindings(findings) {
+  const proposals = [];
+  const errors = [];
+  let skipped = 0;
+  for (const f of findings) {
+    try {
+      const p = proposeFromFinding(f);
+      if (p) proposals.push(p);
+      else skipped += 1;
+    } catch (err) {
+      if (err instanceof KnowledgeProposalParseError) errors.push(err);
+      else throw err;
+    }
+  }
+  return { proposals, skipped, errors };
+}
+function ensureSlug(s) {
+  return s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 200) || "untitled";
+}
+function renderWikiBody(finding, slug, heading) {
+  const title = humanize(slug);
+  if (heading) {
+    return [
+      `## ${heading}`,
+      "",
+      finding.claim,
+      "",
+      ...finding.rationale ? ["### Rationale", "", finding.rationale, ""] : [],
+      ...finding.recommended_action ? ["### Action", "", finding.recommended_action, ""] : [],
+      `_Drafted from finding ${finding.finding_id} (confidence ${finding.confidence.toFixed(2)})._`
+    ].join("\n");
+  }
+  return [
+    "---",
+    `title: ${title}`,
+    `status: draft`,
+    `drafted_from_finding: ${finding.finding_id}`,
+    `confidence: ${finding.confidence}`,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    finding.claim,
+    "",
+    ...finding.rationale ? ["## Rationale", "", finding.rationale, ""] : [],
+    ...finding.recommended_action ? ["## Recommended action", "", finding.recommended_action, ""] : []
+  ].join("\n");
+}
+function humanize(slug) {
+  return slug.split("-").filter(Boolean).map((w) => w[0]?.toUpperCase() + w.slice(1)).join(" ") || slug;
+}
+
+// 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/research-loop.ts
+import {
+  blockingKnowledgeEval,
+  objectiveEval
+} from "@tangle-network/agent-eval";
+function createKnowledgeControlLoopAdapter(options) {
+  let initialized = false;
+  const appliedSteps = [];
+  return {
+    intent: options.goal,
+    async observe({ history, abortSignal }) {
+      if (abortSignal.aborted) throw new Error("Knowledge control loop aborted");
+      if (!initialized) {
+        await initKnowledgeBase(options.root);
+        initialized = true;
+      }
+      const index = await buildKnowledgeIndex(options.root);
+      const validation = validateKnowledgeIndex(index, { strict: options.strict });
+      const lintFindings = lintKnowledgeIndex(index);
+      const readiness = readinessFor(options, index);
+      return {
+        root: options.root,
+        goal: options.goal,
+        iteration: history.length + 1,
+        index,
+        lintFindings,
+        validation,
+        readiness,
+        previousSteps: [...appliedSteps],
+        signal: abortSignal
+      };
+    },
+    validate({ state }) {
+      const errorFindings = state.validation.findings.filter(
+        (finding) => finding.severity === "error"
+      );
+      const evals = [
+        objectiveEval({
+          id: "knowledge-valid",
+          passed: state.validation.ok,
+          severity: "critical",
+          detail: state.validation.ok ? "Knowledge index is valid." : "Knowledge index has validation errors.",
+          metadata: { findings: state.validation.findings }
+        }),
+        objectiveEval({
+          id: "knowledge-lint-errors",
+          passed: errorFindings.length === 0,
+          severity: "error",
+          detail: errorFindings.length === 0 ? "No lint errors." : `${errorFindings.length} lint error(s).`,
+          metadata: { findings: errorFindings }
+        })
+      ];
+      if (state.readiness) evals.push(blockingKnowledgeEval(state.readiness.report));
+      return evals;
+    },
+    shouldStop() {
+      return { stop: false, pass: false, reason: "knowledge driver owns stop decisions" };
+    },
+    async act(action, ctx) {
+      const step = await applyKnowledgeResearchDecision(options, action, ctx.state.iteration);
+      appliedSteps.push(step);
+      return step;
+    }
+  };
+}
+async function runKnowledgeResearchLoop(options) {
+  const maxIterations = Math.max(1, options.maxIterations ?? 3);
+  await initKnowledgeBase(options.root);
+  const steps = [];
+  let index = await buildKnowledgeIndex(options.root);
+  let validation = validateKnowledgeIndex(index, { strict: options.strict });
+  let lintFindings = lintKnowledgeIndex(index);
+  let readiness = readinessFor(options, index);
+  let done = false;
+  for (let iteration = 1; iteration <= maxIterations; iteration++) {
+    if (options.signal?.aborted) throw new Error("Knowledge research loop aborted");
+    const decision = await options.step({
+      root: options.root,
+      goal: options.goal,
+      iteration,
+      index,
+      lintFindings,
+      validation,
+      readiness,
+      previousSteps: steps,
+      signal: options.signal
+    });
+    done = Boolean(decision.done);
+    const step = await applyKnowledgeResearchDecision(options, decision, iteration);
+    index = await buildKnowledgeIndex(options.root);
+    validation = step.validation;
+    lintFindings = step.lintFindings;
+    readiness = step.readiness;
+    steps.push(step);
+    await options.onStep?.(step);
+    if (done) break;
+    if (!step.applied && step.addedSources.length === 0) break;
+  }
+  return {
+    root: options.root,
+    goal: options.goal,
+    iterations: steps.length,
+    done,
+    index,
+    lintFindings,
+    validation,
+    readiness,
+    steps
+  };
+}
+async function applyKnowledgeResearchDecision(options, decision, iteration = 1) {
+  const addedSources = [];
+  for (const sourcePath of decision.sourcePaths ?? []) {
+    addedSources.push(...await addSourcePath(options.root, sourcePath, options.sourceOptions));
+  }
+  for (const sourceText of decision.sourceTexts ?? []) {
+    addedSources.push(await addSourceText(options.root, sourceText, options.sourceOptions));
+  }
+  const applied = decision.proposalText ? await applyKnowledgeWriteBlocks(options.root, decision.proposalText) : void 0;
+  const index = await buildKnowledgeIndex(options.root);
+  const validation = validateKnowledgeIndex(index, { strict: options.strict });
+  const lintFindings = lintKnowledgeIndex(index);
+  const readiness = readinessFor(options, index);
+  const done = Boolean(decision.done);
+  const event = createKnowledgeEvent({
+    type: "research.iteration",
+    actor: options.actor,
+    target: options.root,
+    metadata: {
+      goal: options.goal,
+      iteration,
+      done,
+      addedSourceCount: addedSources.length,
+      written: applied?.written,
+      warningCount: applied?.warnings.length ?? 0,
+      errorCount: validation.findings.filter((finding) => finding.severity === "error").length
+    }
+  });
+  return {
+    iteration,
+    notes: decision.notes,
+    addedSources,
+    applied,
+    lintFindings,
+    validation,
+    readiness,
+    event,
+    done,
+    metadata: decision.metadata
+  };
+}
+function readinessFor(options, index) {
+  if (!options.readinessSpecs?.length) return void 0;
+  return buildEvalKnowledgeBundle({
+    ...options.readiness ?? {},
+    taskId: options.readinessTaskId ?? options.goal,
+    index,
+    specs: options.readinessSpecs
+  });
+}
 export {
   FileSystemKbStore,
+  IRS_DIMENSION_HINTS,
   KnowledgeBaseCandidateSchema,
   KnowledgeEventSchema,
   KnowledgeGraphEdgeSchema,
   KnowledgeGraphNodeSchema,
   KnowledgeIndexSchema,
   KnowledgePageSchema,
+  KnowledgeProposalParseError,
+  MAX_RESPONSE_BYTES,
+  MIN_REQUEST_GAP_MS,
   MemoryKbStore,
+  POLITE_USER_AGENT,
+  READINESS_SPEC_DEFAULTS,
   SCAFFOLD_PAGE_BASENAMES,
   SourceAnchorSchema,
   SourceRecordSchema,
   WIKILINK_REGEX,
+  __resetHttpThrottle,
   addSourcePath,
+  addSourceText,
   applyKnowledgeWriteBlocks,
   applyKnowledgeWriteBlocksFile,
   buildEvalKnowledgeBundle,
   buildKnowledgeGraph,
   buildKnowledgeIndex,
   chunkMarkdown,
+  createCornellLiiSource,
+  createD1FreshnessStoreStub,
+  createFileSystemFreshnessStore,
+  createIrsPublicationsSource,
+  createKnowledgeControlLoopAdapter,
   createKnowledgeEvent,
   createLocalDiscoveryDispatcher,
+  createStateSosSource,
+  defineReadinessSpec,
+  detectChanges,
   explainKnowledgeTarget,
+  extractLinks,
   extractWikilinks,
+  firstMatch,
   formatFrontmatter,
+  htmlToText,
   initKnowledgeBase,
+  innerHtmlById,
   inspectKnowledgeIndex,
   isSafeKnowledgePath,
   isScaffoldPath,
@@ -493,12 +1092,17 @@ export {
   lintKnowledgeIndex,
   loadKnowledgePages,
   loadSourceRegistry,
+  looksLikeBlockPage,
   mediaTypeFor,
   normalizeLinkTarget,
   parseFrontmatter,
   parseKnowledgeWriteBlocks,
+  politeFetch,
+  proposeFromFinding,
+  proposeFromFindings,
   reciprocalRankFusion,
   runKnowledgeBaseOptimization,
+  runKnowledgeResearchLoop,
   searchKnowledge,
   sha256,
   slugify,