agentcache 0.2.4 → 0.3.1

package/dist/chunk-R4SJESNM.js

@@ -0,0 +1,684 @@
+import {
+  getDataDir,
+  getGitContext
+} from "./chunk-WHP4Z32Z.js";
+
+// src/knowledge/passes/3-canonicalizer.ts
+import { createHash } from "crypto";
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "need",
+  "must",
+  "to",
+  "of",
+  "in",
+  "for",
+  "on",
+  "with",
+  "at",
+  "by",
+  "from",
+  "as",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "and",
+  "but",
+  "or",
+  "nor",
+  "not",
+  "so",
+  "yet",
+  "all",
+  "each",
+  "every",
+  "both",
+  "few",
+  "more",
+  "most",
+  "i",
+  "we",
+  "you",
+  "they",
+  "he",
+  "she"
+]);
+var ANTONYM_MAP = [
+  [/\bnever\b/g, "forbidden"],
+  [/\bdon'?t\b/g, "forbidden"],
+  [/\bavoid\b/g, "forbidden"],
+  [/\bprohibit(ed)?\b/g, "forbidden"],
+  [/\balways\b/g, "required"],
+  [/\bmust\b/g, "required"],
+  [/\brequire(d)?\b/g, "required"],
+  [/\buse\b/g, "use"],
+  [/\bprefer\b/g, "use"]
+];
+function canonicalize(observations, existingCanonicalKeys) {
+  const canonicalized = observations.map((obs) => ({
+    ...obs,
+    canonicalKey: computeCanonicalKey(obs.content)
+  }));
+  const existingSet = new Set(existingCanonicalKeys || []);
+  const autoReinforced = [];
+  const needsClustering = [];
+  for (const obs of canonicalized) {
+    if (existingSet.has(obs.canonicalKey)) {
+      autoReinforced.push(obs);
+    } else {
+      needsClustering.push(obs);
+    }
+  }
+  return { observations: canonicalized, autoReinforced, needsClustering };
+}
+function computeCanonicalKey(content) {
+  let text = content.toLowerCase().trim();
+  for (const [pattern, replacement] of ANTONYM_MAP) {
+    text = text.replace(pattern, replacement);
+  }
+  text = text.replace(/[^\w\s]/g, " ");
+  const tokens = text.split(/\s+/).filter((t) => !STOP_WORDS.has(t) && t.length > 1).sort();
+  return tokens.join(" ");
+}
+function computeCanonicalHash(content) {
+  const key = computeCanonicalKey(content);
+  return createHash("sha256").update(key).digest("hex").slice(0, 16);
+}
+
+// src/knowledge/compiler.ts
+import { randomUUID as randomUUID3 } from "crypto";
+
+// src/knowledge/passes/1-extractor.ts
+import { randomUUID } from "crypto";
+var EXTRACT_PROMPT_VERSION = "extract-v1";
+function buildExtractionPrompt(events) {
+  const transcript = events.filter((e) => e.content || e.tool_name).map((e) => {
+    if (e.role) return `[${e.role}]: ${e.content}`;
+    if (e.tool_name) return `[tool:${e.tool_name}]: ${JSON.stringify(e.tool_input).slice(0, 500)}`;
+    return "";
+  }).filter(Boolean).join("\n");
+  return `You are a knowledge extraction engine. Analyze this coding session transcript and extract distinct learnings.
+
+Extract into four types:
+- rule: a standing instruction or constraint the developer expressed
+- lesson: a mistake made and what fixed it
+- decision: an architectural or design choice with rationale
+- context: current task state, open threads, what was left in progress
+
+Return ONLY valid JSON: { "observations": [{ "type": "rule"|"lesson"|"decision"|"context", "content": "...", "sourceQuote": "...", "confidence": "high"|"medium" }] }
+
+Only return high and medium confidence items. Ignore conversational noise, tool outputs, and implementation details that aren't generalizable.
+
+<transcript>
+${transcript}
+</transcript>`;
+}
+function parseExtractionResponse(text, sessionId, project) {
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return [];
+  const parsed = JSON.parse(jsonMatch[0]);
+  if (!parsed.observations || !Array.isArray(parsed.observations)) return [];
+  const now = Date.now();
+  return parsed.observations.filter((o) => o.type && o.content && o.confidence).filter((o) => ["high", "medium"].includes(o.confidence)).map((o) => ({
+    id: `obs_${randomUUID().slice(0, 8)}`,
+    sessionId,
+    timestamp: now,
+    type: o.type,
+    content: o.content,
+    sourceQuote: o.sourceQuote || "",
+    confidence: o.confidence,
+    project,
+    scope: o.scope || (o.type === "rule" || o.type === "lesson" ? "global" : "project")
+  }));
+}
+
+// src/knowledge/passes/2-normalizer.ts
+var FILLER_PATTERNS = [
+  /^i (noticed|realized|learned|found|discovered|think) that /i,
+  /^it (seems|appears|looks) (like|that) /i,
+  /^we should /i,
+  /^you should /i,
+  /^basically,? /i,
+  /^essentially,? /i,
+  /^actually,? /i
+];
+var IMPERATIVE_RULES = [
+  [/^you should never /i, "Never "],
+  [/^we should never /i, "Never "],
+  [/^don't ever /i, "Never "],
+  [/^never /i, "Never "],
+  [/^you should always /i, "Always "],
+  [/^we should always /i, "Always "],
+  [/^always /i, "Always "]
+];
+function normalize(observations) {
+  const normalized = observations.map((obs) => ({
+    ...obs,
+    content: normalizeContent(obs.content, obs.type)
+  }));
+  const seen = /* @__PURE__ */ new Set();
+  return normalized.filter((obs) => {
+    const key = obs.content.toLowerCase().trim();
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function normalizeContent(content, type) {
+  let text = content.trim();
+  for (const pattern of FILLER_PATTERNS) {
+    text = text.replace(pattern, "");
+  }
+  if (type === "rule") {
+    for (const [pattern, replacement] of IMPERATIVE_RULES) {
+      if (pattern.test(text)) {
+        text = text.replace(pattern, replacement);
+        break;
+      }
+    }
+  }
+  text = text.charAt(0).toUpperCase() + text.slice(1);
+  const firstSentenceEnd = text.search(/\. [A-Z]/);
+  if (firstSentenceEnd > 0) {
+    text = text.slice(0, firstSentenceEnd + 1);
+  }
+  return text;
+}
+
+// src/knowledge/passes/4-clusterer.ts
+var CLUSTER_PROMPT_VERSION = "cluster-v1";
+function buildClusteringPrompt(observations, existingItems) {
+  const obsJson = observations.map((o) => ({
+    id: o.id,
+    type: o.type,
+    content: o.content,
+    canonicalKey: o.canonicalKey
+  }));
+  const itemsJson = existingItems.filter((i) => i.status === "active").map((i) => ({
+    id: i.id,
+    type: i.type,
+    content: i.content,
+    canonicalHash: i.canonicalHash
+  }));
+  return `You are a knowledge clustering engine. Determine whether new observations create new knowledge or relate to existing items. Be conservative.
+
+For each observation, assign an action:
+CREATE    \u2014 genuinely new knowledge, no existing item covers it
+REINFORCE \u2014 confirms an existing item (provide targetKnowledgeItemId)
+SUPERSEDE \u2014 replaces/corrects an existing item (provide targetKnowledgeItemId)
+DEPRECATE \u2014 makes an existing item irrelevant (provide targetKnowledgeItemId)
+IGNORE    \u2014 duplicate, trivial, or too vague to keep
+
+New observations:
+${JSON.stringify(obsJson, null, 2)}
+
+Existing knowledge items:
+${JSON.stringify(itemsJson, null, 2)}
+
+Return ONLY valid JSON: { "clusters": [{ "observationId": "...", "action": "CREATE"|"REINFORCE"|"SUPERSEDE"|"DEPRECATE"|"IGNORE", "targetKnowledgeItemId": "..." (only if action targets an existing item), "reasoning": "..." }] }`;
+}
+function parseClusteringResponse(text, observations) {
+  const jsonMatch = text.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) {
+    return observations.map((o) => ({ observationId: o.id, action: "CREATE", reasoning: "Parse failure \u2014 defaulting to CREATE" }));
+  }
+  const parsed = JSON.parse(jsonMatch[0]);
+  if (!parsed.clusters || !Array.isArray(parsed.clusters)) {
+    return observations.map((o) => ({ observationId: o.id, action: "CREATE", reasoning: "Parse failure \u2014 defaulting to CREATE" }));
+  }
+  return parsed.clusters.map((c) => ({
+    observationId: c.observationId,
+    action: c.action || "CREATE",
+    targetKnowledgeItemId: c.targetKnowledgeItemId || void 0,
+    reasoning: c.reasoning || ""
+  }));
+}
+
+// src/knowledge/passes/5-contradiction.ts
+var CONTRADICTION_PROMPT_VERSION = "contradiction-v1";
+
+// src/knowledge/passes/6-compile.ts
+import { randomUUID as randomUUID2 } from "crypto";
+function calculateConfidence(count) {
+  if (count >= 7) return "high";
+  if (count >= 3) return "medium";
+  return "low";
+}
+function compileKnowledge(clusters, existingItems, observations, project, now) {
+  const itemMap = new Map(existingItems.map((i) => [i.id, { ...i }]));
+  const obsMap = new Map(observations.map((o) => [o.id, o]));
+  const result = {
+    created: [],
+    reinforced: [],
+    superseded: [],
+    deprecated: [],
+    ignored: 0
+  };
+  for (const cluster of clusters) {
+    const obs = obsMap.get(cluster.observationId);
+    if (!obs) continue;
+    switch (cluster.action) {
+      case "CREATE": {
+        const newItem = {
+          id: `ki_${randomUUID2().slice(0, 8)}`,
+          canonicalHash: computeCanonicalHash(obs.content),
+          type: obs.type,
+          title: obs.content.slice(0, 80),
+          content: obs.content,
+          confidence: "low",
+          observationCount: 1,
+          authority: "AUTO",
+          status: "active",
+          supersededById: void 0,
+          enforce: false,
+          project,
+          scope: obs.scope || (obs.type === "rule" || obs.type === "lesson" ? "global" : "project"),
+          createdAt: now,
+          updatedAt: now,
+          lastSeenAt: now,
+          metadata: {}
+        };
+        result.created.push(newItem);
+        break;
+      }
+      case "REINFORCE": {
+        const target = itemMap.get(cluster.targetKnowledgeItemId);
+        if (!target) break;
+        target.observationCount += 1;
+        target.lastSeenAt = now;
+        target.updatedAt = now;
+        target.confidence = calculateConfidence(target.observationCount);
+        result.reinforced.push(target);
+        break;
+      }
+      case "SUPERSEDE": {
+        const target = itemMap.get(cluster.targetKnowledgeItemId);
+        if (target) {
+          const newItem = {
+            id: `ki_${randomUUID2().slice(0, 8)}`,
+            canonicalHash: computeCanonicalHash(obs.content),
+            type: obs.type,
+            title: obs.content.slice(0, 80),
+            content: obs.content,
+            confidence: "low",
+            observationCount: 1,
+            authority: "AUTO",
+            status: "active",
+            supersededById: void 0,
+            enforce: false,
+            project,
+            scope: obs.scope || (obs.type === "rule" || obs.type === "lesson" ? "global" : "project"),
+            createdAt: now,
+            updatedAt: now,
+            lastSeenAt: now,
+            metadata: {}
+          };
+          target.status = "superseded";
+          target.updatedAt = now;
+          target.supersededById = newItem.id;
+          result.superseded.push(target);
+          result.created.push(newItem);
+        }
+        break;
+      }
+      case "DEPRECATE": {
+        const target = itemMap.get(cluster.targetKnowledgeItemId);
+        if (target) {
+          target.status = "deprecated";
+          target.updatedAt = now;
+          result.deprecated.push(target);
+        }
+        break;
+      }
+      case "IGNORE":
+        result.ignored += 1;
+        break;
+    }
+  }
+  return result;
+}
+
+// src/knowledge/passes/7-projector.ts
+import { mkdirSync, writeFileSync } from "fs";
+function projectToMarkdown(items, generatedDir, compilerVersion) {
+  mkdirSync(generatedDir, { recursive: true });
+  const active = items.filter((i) => i.status === "active");
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const header = (title) => `<!-- AUTO-GENERATED BY AGENTCACHE v${compilerVersion} \u2014 DO NOT EDIT -->
+<!-- Source of truth: .agentcache/agentcache.db -->
+<!-- Last compiled: ${timestamp} | ${active.length} active items -->
+
+# ${title}
+
+`;
+  const rules = active.filter((i) => i.type === "rule").sort((a, b) => confidenceOrder(b) - confidenceOrder(a));
+  const lessons = active.filter((i) => i.type === "lesson").sort((a, b) => confidenceOrder(b) - confidenceOrder(a));
+  const decisions = active.filter((i) => i.type === "decision").sort((a, b) => confidenceOrder(b) - confidenceOrder(a));
+  const context = active.filter((i) => i.type === "context").sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+  writeFileSync(
+    `${generatedDir}/RULES.md`,
+    header("Rules") + formatItems(rules),
+    "utf-8"
+  );
+  writeFileSync(
+    `${generatedDir}/LESSONS.md`,
+    header("Lessons") + formatItems(lessons),
+    "utf-8"
+  );
+  writeFileSync(
+    `${generatedDir}/DECISIONS.md`,
+    header("Decisions") + formatItems(decisions),
+    "utf-8"
+  );
+  writeFileSync(
+    `${generatedDir}/CONTEXT.md`,
+    header("Context") + formatItems(context),
+    "utf-8"
+  );
+}
+function confidenceOrder(item) {
+  switch (item.confidence) {
+    case "high":
+      return 3;
+    case "medium":
+      return 2;
+    case "low":
+      return 1;
+  }
+}
+function formatItems(items) {
+  if (items.length === 0) return "_No items yet._\n";
+  return items.map((i) => {
+    const badge = i.enforce ? " \u{1F6E1}\uFE0F" : "";
+    const conf = `(${i.confidence}, ${i.observationCount}\xD7)`;
+    return `- ${i.content}${badge} ${conf}`;
+  }).join("\n") + "\n";
+}
+
+// src/knowledge/passes/7b-skill-projector.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var MAX_SKILL_TOKENS = 5e3;
+var AVG_CHARS_PER_TOKEN = 4;
+var MAX_SKILL_CHARS = MAX_SKILL_TOKENS * AVG_CHARS_PER_TOKEN;
+function projectToSkills(items, projectRoot) {
+  const active = items.filter((i) => i.status === "active");
+  const globalItems = active.filter((i) => i.scope === "global");
+  const projectItems = active.filter((i) => i.scope === "project");
+  writeGlobalSkill(globalItems);
+  writeProjectSkill(projectItems, projectRoot);
+}
+function writeGlobalSkill(items) {
+  const skillDir = join(homedir(), ".agentcache", "skills", "developer-knowledge");
+  mkdirSync2(skillDir, { recursive: true });
+  const rules = items.filter((i) => i.type === "rule").sort(byConfidence);
+  const lessons = items.filter((i) => i.type === "lesson").sort(byConfidence);
+  const body = buildSkillBody(rules, lessons, [], []);
+  const content = buildSkillFile(
+    "developer-knowledge",
+    "Engineering rules and lessons learned across all projects \u2014 compiled automatically from coding sessions by AgentCache",
+    body
+  );
+  writeFileSync2(join(skillDir, "SKILL.md"), truncateToLimit(content), "utf-8");
+}
+function writeProjectSkill(items, projectRoot) {
+  if (!projectRoot || projectRoot === process.cwd()) return;
+  if (items.length === 0) return;
+  const skillDir = join(projectRoot, ".agentcache", "skills", "project-knowledge");
+  mkdirSync2(skillDir, { recursive: true });
+  const rules = items.filter((i) => i.type === "rule").sort(byConfidence);
+  const lessons = items.filter((i) => i.type === "lesson").sort(byConfidence);
+  const decisions = items.filter((i) => i.type === "decision").sort(byConfidence);
+  const context = items.filter((i) => i.type === "context").sort((a, b) => b.lastSeenAt - a.lastSeenAt);
+  const body = buildSkillBody(rules, lessons, decisions, context);
+  const content = buildSkillFile(
+    "project-knowledge",
+    "Project-specific decisions, rules, context, and lessons \u2014 compiled automatically from coding sessions by AgentCache",
+    body
+  );
+  writeFileSync2(join(skillDir, "SKILL.md"), truncateToLimit(content), "utf-8");
+}
+function buildSkillFile(name, description, body) {
+  return `---
+name: ${name}
+description: "${description}"
+---
+
+${body}`;
+}
+function buildSkillBody(rules, lessons, decisions, context) {
+  let out = "";
+  if (rules.length > 0) {
+    out += "## Rules\n\nFollow these without exception:\n\n";
+    out += rules.map((r) => `- ${r.content}${enforceTag(r)}`).join("\n") + "\n\n";
+  }
+  if (lessons.length > 0) {
+    out += "## Lessons\n\nPitfalls learned from past sessions:\n\n";
+    out += lessons.map((l) => `- ${l.content}`).join("\n") + "\n\n";
+  }
+  if (decisions.length > 0) {
+    out += "## Decisions\n\nArchitectural choices in effect \u2014 do not contradict:\n\n";
+    out += decisions.map((d) => `- ${d.content}`).join("\n") + "\n\n";
+  }
+  if (context.length > 0) {
+    out += "## Current Context\n\nActive project state (may be temporal):\n\n";
+    out += context.map((c) => `- ${c.content}`).join("\n") + "\n\n";
+  }
+  return out.trimEnd() + "\n";
+}
+function enforceTag(item) {
+  return item.enforce ? " [ENFORCED]" : "";
+}
+function byConfidence(a, b) {
+  const order = { high: 3, medium: 2, low: 1 };
+  return (order[b.confidence] || 0) - (order[a.confidence] || 0);
+}
+function truncateToLimit(content) {
+  if (content.length <= MAX_SKILL_CHARS) return content;
+  const lines = content.split("\n");
+  let result = "";
+  for (const line of lines) {
+    if ((result + line + "\n").length > MAX_SKILL_CHARS - 50) break;
+    result += line + "\n";
+  }
+  result += "\n<!-- Truncated to stay within 5000 token skill budget -->\n";
+  return result;
+}
+
+// src/knowledge/compiler.ts
+var COMPILER_VERSION = "0.1.0";
+function startCompile(events, sessionId, project, projectRoot, repo, transcriptPath) {
+  const git = getGitContext(projectRoot);
+  const session = {
+    id: sessionId,
+    project,
+    startedAt: Date.now() - 6e4,
+    endedAt: Date.now(),
+    gitBranch: git.branch,
+    gitCommit: git.commit,
+    provider: "agent",
+    model: "host-agent",
+    transcriptPath: transcriptPath || "",
+    observationCount: 0
+  };
+  repo.saveSession(session);
+  const prompt = buildExtractionPrompt(events);
+  return { sessionId, project, projectRoot, prompt };
+}
+function processExtraction(repo, responseText, sessionId, project, projectRoot) {
+  const rawObservations = parseExtractionResponse(responseText, sessionId, project);
+  const normalized = normalize(rawObservations);
+  const existingItems = repo.getKnowledgeItems(project, { status: "active" });
+  const existingKeys = existingItems.map((i) => computeCanonicalKey(i.content));
+  const canonicalized = canonicalize(normalized, existingKeys);
+  for (const obs of canonicalized.autoReinforced) {
+    const matchingItem = existingItems.find(
+      (item) => computeCanonicalKey(item.content) === obs.canonicalKey
+    );
+    if (matchingItem) {
+      const newCount = matchingItem.observationCount + 1;
+      const confidence = newCount >= 7 ? "high" : newCount >= 3 ? "medium" : "low";
+      repo.updateKnowledgeItem(matchingItem.id, {
+        observationCount: newCount,
+        lastSeenAt: Date.now(),
+        updatedAt: Date.now(),
+        confidence
+      });
+    }
+  }
+  repo.saveObservations(normalized);
+  if (canonicalized.needsClustering.length === 0) {
+    saveCompileRun(repo, sessionId, project, normalized.length, canonicalized.autoReinforced.length, 0, 0, 0, 0, 0, Date.now());
+    const activeItems = repo.getKnowledgeItems(project, { status: "active" });
+    projectToMarkdown(activeItems, getDataDir(), COMPILER_VERSION);
+    projectToSkills(activeItems, projectRoot);
+    return {
+      status: "complete",
+      diagnostics: formatDiagnostics(normalized.length, canonicalized.autoReinforced.length, 0, 0, 0, 0, 0, project, sessionId)
+    };
+  }
+  const clusteringPrompt = buildClusteringPrompt(canonicalized.needsClustering, existingItems);
+  return {
+    status: "needs_clustering",
+    clusteringPrompt,
+    sessionId
+  };
+}
+function processClustering(repo, responseText, sessionId, project, projectRoot) {
+  const startedAt = Date.now();
+  const existingItems = repo.getKnowledgeItems(project, { status: "active" });
+  const observations = repo.getObservations(project);
+  const sessionObs = observations.filter((o) => o.sessionId === sessionId);
+  const canonicalized = canonicalize(sessionObs);
+  const needsClustering = canonicalized.needsClustering;
+  const clusters = parseClusteringResponse(responseText, needsClustering);
+  const contradictions = [];
+  const supersedeActions = clusters.filter((c) => c.action === "SUPERSEDE");
+  for (const s of supersedeActions) {
+    if (s.targetKnowledgeItemId) {
+      const target = existingItems.find((i) => i.id === s.targetKnowledgeItemId);
+      if (target) {
+        contradictions.push({
+          id: `con_${randomUUID3().slice(0, 8)}`,
+          project,
+          itemAId: target.id,
+          itemBId: s.observationId,
+          topic: target.title.slice(0, 50),
+          description: `"${target.content}" superseded by new observation`,
+          recommendation: "keep_newer",
+          resolved: false,
+          createdAt: Date.now()
+        });
+      }
+    }
+  }
+  for (const c of contradictions) {
+    repo.saveContradiction(c);
+  }
+  const now = Date.now();
+  const compiled = compileKnowledge(clusters, existingItems, needsClustering, project, now);
+  for (const item of compiled.created) repo.saveKnowledgeItem(item);
+  for (const item of compiled.reinforced) {
+    repo.updateKnowledgeItem(item.id, {
+      observationCount: item.observationCount,
+      lastSeenAt: item.lastSeenAt,
+      updatedAt: item.updatedAt,
+      confidence: item.confidence
+    });
+  }
+  for (const item of compiled.superseded) {
+    repo.updateKnowledgeItem(item.id, {
+      status: item.status,
+      updatedAt: item.updatedAt,
+      supersededById: item.supersededById
+    });
+  }
+  for (const item of compiled.deprecated) {
+    repo.updateKnowledgeItem(item.id, { status: item.status, updatedAt: item.updatedAt });
+  }
+  const totalObs = sessionObs.length;
+  saveCompileRun(repo, sessionId, project, totalObs, 0, compiled.created.length, compiled.reinforced.length, compiled.superseded.length, compiled.deprecated.length, compiled.ignored, startedAt);
+  const activeItems = repo.getKnowledgeItems(project, { status: "active" });
+  projectToMarkdown(activeItems, getDataDir(), COMPILER_VERSION);
+  projectToSkills(activeItems, projectRoot);
+  return {
+    status: "complete",
+    diagnostics: formatDiagnostics(totalObs, 0, compiled.created.length, compiled.reinforced.length, compiled.superseded.length, compiled.deprecated.length, compiled.ignored, project, sessionId)
+  };
+}
+function saveCompileRun(repo, sessionId, project, observationsProcessed, autoReinforced, created, reinforced, superseded, deprecated, ignored, startedAt) {
+  const endedAt = Date.now();
+  const run = {
+    id: `cr_${randomUUID3().slice(0, 8)}`,
+    project,
+    sessionId,
+    compilerVersion: COMPILER_VERSION,
+    promptVersions: { extract: EXTRACT_PROMPT_VERSION, cluster: CLUSTER_PROMPT_VERSION, contradiction: CONTRADICTION_PROMPT_VERSION },
+    startedAt,
+    endedAt,
+    durationMs: endedAt - startedAt,
+    observationsProcessed,
+    knowledgeCreated: created,
+    knowledgeReinforced: reinforced + autoReinforced,
+    knowledgeDeprecated: deprecated,
+    knowledgeSuperseded: superseded,
+    knowledgeIgnored: ignored,
+    contradictionsDetected: 0,
+    diagnostics: ""
+  };
+  repo.saveCompileRun(run);
+}
+function formatDiagnostics(extracted, autoReinforced, created, reinforced, superseded, deprecated, ignored, project, sessionId) {
+  return [
+    `AgentCache Compiler v${COMPILER_VERSION}`,
+    `Project: ${project} | Session: ${sessionId}`,
+    `  ${extracted} observations processed`,
+    autoReinforced > 0 ? `  ${autoReinforced} auto-reinforced (no LLM needed)` : "",
+    `  ${created} new knowledge items`,
+    `  ${reinforced} reinforced`,
+    superseded > 0 ? `  ${superseded} superseded` : "",
+    deprecated > 0 ? `  ${deprecated} deprecated` : "",
+    ignored > 0 ? `  ${ignored} ignored` : ""
+  ].filter(Boolean).join("\n");
+}
+
+export {
+  computeCanonicalHash,
+  startCompile,
+  processExtraction,
+  processClustering
+};