@remnic/core 1.0.0

package/dist/calibration.js

@@ -0,0 +1,239 @@
+import {
+  FallbackLlmClient
+} from "./chunk-KT4NEUNF.js";
+import "./chunk-LU3GQNDQ.js";
+import "./chunk-Y27UJK6V.js";
+import "./chunk-UZB5KHKX.js";
+import "./chunk-MARWOCVP.js";
+import {
+  log
+} from "./chunk-KWBU5S5U.js";
+import {
+  listJsonFiles
+} from "./chunk-LPSF4OQH.js";
+
+// src/calibration.ts
+import { createHash } from "crypto";
+import path from "path";
+import { mkdir, readFile, writeFile } from "fs/promises";
+function calibrationDir(memoryDir) {
+  return path.join(memoryDir, "state", "calibration");
+}
+function calibrationIndexPath(memoryDir) {
+  return path.join(calibrationDir(memoryDir), "calibration-index.json");
+}
+async function readCalibrationIndex(memoryDir) {
+  try {
+    const raw = JSON.parse(await readFile(calibrationIndexPath(memoryDir), "utf8"));
+    return {
+      rules: Array.isArray(raw.rules) ? raw.rules : [],
+      updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      totalCorrectionsAnalyzed: typeof raw.totalCorrectionsAnalyzed === "number" ? raw.totalCorrectionsAnalyzed : 0
+    };
+  } catch {
+    return { rules: [], updatedAt: (/* @__PURE__ */ new Date()).toISOString(), totalCorrectionsAnalyzed: 0 };
+  }
+}
+async function writeCalibrationIndex(memoryDir, index) {
+  const dir = calibrationDir(memoryDir);
+  await mkdir(dir, { recursive: true });
+  index.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+  await writeFile(calibrationIndexPath(memoryDir), JSON.stringify(index, null, 2), "utf8");
+}
+async function readCorrections(memoryDir) {
+  const correctionsDir = path.join(memoryDir, "corrections");
+  const files = await listJsonFiles(correctionsDir).catch(() => {
+    return [];
+  });
+  const factsDir = path.join(memoryDir, "facts");
+  try {
+    const { readdir } = await import("fs/promises");
+    const dayDirs = (await readdir(factsDir)).filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d));
+    for (const day of dayDirs) {
+      const dayPath = path.join(factsDir, day);
+      const dayFiles = (await readdir(dayPath)).filter((f) => f.startsWith("correction-") && f.endsWith(".md")).map((f) => path.join(dayPath, f));
+      files.push(...dayFiles);
+    }
+  } catch {
+  }
+  try {
+    const { readdir } = await import("fs/promises");
+    const corrFiles = (await readdir(correctionsDir)).filter((f) => f.endsWith(".md")).map((f) => path.join(correctionsDir, f));
+    files.push(...corrFiles);
+  } catch {
+  }
+  const corrections = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const filePath of files) {
+    try {
+      const raw = await readFile(filePath, "utf8");
+      const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+      if (!fmMatch) continue;
+      const content = fmMatch[2].trim();
+      if (!content || content.length < 10) continue;
+      const idMatch = fmMatch[1].match(/^id:\s*(.+)$/m);
+      const id = idMatch?.[1]?.trim() ?? path.basename(filePath, ".md");
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const confMatch = fmMatch[1].match(/^confidence:\s*(.+)$/m);
+      const confidence = confMatch ? parseFloat(confMatch[1]) : 0.9;
+      const entityMatch = fmMatch[1].match(/^entityRef:\s*(.+)$/m);
+      const entityRefs = entityMatch ? [entityMatch[1].trim()] : [];
+      corrections.push({ id, content, created: "", confidence, entityRefs, tags: [] });
+    } catch {
+    }
+  }
+  return corrections;
+}
+var CLUSTER_PROMPT = `You are analyzing user corrections to an AI assistant. Each correction represents a moment where the assistant's prediction of what the user wanted was WRONG.
+
+Your job: Group these corrections into clusters where the SAME TYPE of misunderstanding is happening. Then for each cluster, synthesize a CalibrationRule.
+
+A CalibrationRule describes:
+- condition: When does this type of mistake happen?
+- modelTendency: What does the model tend to assume or do wrong?
+- userExpectation: What does the user actually want instead?
+- calibration: How should the model adjust its behavior?
+- ruleType: One of "model_tendency", "user_expectation", "scope_boundary", "verification_required"
+
+Focus on PATTERNS, not individual corrections. A cluster needs at least 2 corrections to be worth a rule.
+
+Output valid JSON only:
+{
+  "rules": [
+    {
+      "ruleType": "model_tendency",
+      "condition": "When discussing project scope or task boundaries",
+      "modelTendency": "The model tends to assume broader scope than the user intends",
+      "userExpectation": "The user prefers narrow, specific task definitions and wants to be asked before scope expansion",
+      "calibration": "When uncertain about scope, ask for clarification rather than assuming. Default to the narrower interpretation.",
+      "confidence": 0.85,
+      "evidenceIds": ["correction-id-1", "correction-id-2"]
+    }
+  ]
+}`;
+async function synthesizeCalibrationRules(corrections, llm, existingRules, agentId) {
+  if (corrections.length < 2) return [];
+  const correctionText = corrections.slice(0, 50).map((c, i) => `[${c.id}] ${c.content}`).join("\n\n");
+  const existingRulesText = existingRules.length > 0 ? `
+
+Existing calibration rules (avoid duplicating these):
+${existingRules.map((r) => `- ${r.condition}: ${r.calibration}`).join("\n")}` : "";
+  const response = await llm.chatCompletion(
+    [
+      { role: "system", content: CLUSTER_PROMPT },
+      { role: "user", content: `Here are ${corrections.length} corrections from this user:
+
+${correctionText}${existingRulesText}` }
+    ],
+    { temperature: 0.3, maxTokens: 3e3, agentId }
+  );
+  if (!response?.content) return [];
+  try {
+    let jsonStr = response.content.trim();
+    const fenceMatch = jsonStr.match(/```(?:json)?\s*\n?([\s\S]*?)\n?\s*```/);
+    if (fenceMatch) jsonStr = fenceMatch[1];
+    const parsed = JSON.parse(jsonStr);
+    if (!Array.isArray(parsed.rules)) return [];
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    return parsed.rules.filter((r) => r.condition && r.calibration && r.modelTendency).map((r) => ({
+      id: `cal-${createHash("sha256").update(r.condition + r.calibration).digest("hex").slice(0, 12)}`,
+      ruleType: r.ruleType ?? "model_tendency",
+      condition: String(r.condition),
+      modelTendency: String(r.modelTendency),
+      userExpectation: String(r.userExpectation ?? ""),
+      calibration: String(r.calibration),
+      confidence: typeof r.confidence === "number" ? r.confidence : 0.7,
+      evidenceCount: Array.isArray(r.evidenceIds) ? r.evidenceIds.length : 1,
+      evidenceCorrectionIds: Array.isArray(r.evidenceIds) ? r.evidenceIds : [],
+      createdAt: now,
+      lastReinforcedAt: now
+    }));
+  } catch {
+    log.warn("[calibration] failed to parse LLM response");
+    return [];
+  }
+}
+function buildCalibrationRecallSection(rules, query, maxChars = 1200) {
+  if (rules.length === 0) return null;
+  const lines = [
+    "## Model Calibration (learned from past corrections)",
+    "",
+    "Adjustments for this specific user, learned from patterns in their corrections:",
+    ""
+  ];
+  let totalChars = lines.join("\n").length;
+  for (const rule of rules) {
+    const line = `- **${rule.condition}**: ${rule.modelTendency} \u2192 Instead: ${rule.calibration}`;
+    if (totalChars + line.length + 1 > maxChars) break;
+    lines.push(line);
+    totalChars += line.length + 1;
+  }
+  if (lines.length <= 4) return null;
+  lines.push("");
+  return lines.join("\n");
+}
+async function runCalibrationConsolidation(options) {
+  try {
+    const llm = new FallbackLlmClient(options.gatewayConfig);
+    if (!llm.isAvailable(options.gatewayAgentId)) {
+      log.debug("[calibration] no LLM available \u2014 skipping consolidation");
+      return [];
+    }
+    const corrections = await readCorrections(options.memoryDir);
+    if (corrections.length < 3) {
+      log.debug(`[calibration] only ${corrections.length} corrections \u2014 need at least 3`);
+      return [];
+    }
+    const existingIndex = await readCalibrationIndex(options.memoryDir);
+    const newRules = await synthesizeCalibrationRules(corrections, llm, existingIndex.rules, options.gatewayAgentId);
+    if (newRules.length === 0) {
+      log.debug("[calibration] no new calibration rules synthesized");
+      return existingIndex.rules;
+    }
+    const ruleMap = new Map(existingIndex.rules.map((r) => [r.id, r]));
+    for (const rule of newRules) {
+      if (ruleMap.has(rule.id)) {
+        const existing = ruleMap.get(rule.id);
+        existing.lastReinforcedAt = (/* @__PURE__ */ new Date()).toISOString();
+        existing.evidenceCount += rule.evidenceCount;
+        existing.confidence = Math.min(1, existing.confidence + 0.05);
+      } else {
+        ruleMap.set(rule.id, rule);
+      }
+    }
+    const allRules = [...ruleMap.values()];
+    await writeCalibrationIndex(options.memoryDir, {
+      rules: allRules,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      totalCorrectionsAnalyzed: corrections.length
+    });
+    log.debug(`[calibration] synthesized ${newRules.length} new rule(s), ${allRules.length} total`);
+    return allRules;
+  } catch (error) {
+    log.warn(`[calibration] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+async function runCalibrationIfEnabled(options) {
+  if (!options.calibrationEnabled) {
+    return [];
+  }
+  return runCalibrationConsolidation({
+    memoryDir: options.memoryDir,
+    gatewayConfig: options.gatewayConfig
+  });
+}
+async function getCalibrationRulesForRecall(memoryDir) {
+  const index = await readCalibrationIndex(memoryDir);
+  return index.rules;
+}
+export {
+  buildCalibrationRecallSection,
+  getCalibrationRulesForRecall,
+  readCalibrationIndex,
+  runCalibrationConsolidation,
+  runCalibrationIfEnabled,
+  synthesizeCalibrationRules
+};
+//# sourceMappingURL=calibration.js.map

package/dist/calibration.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/calibration.ts"],"sourcesContent":["/**\n * calibration.ts — Prediction-Error-Driven Model-User Calibration\n *\n * Analyzes patterns in user corrections to identify systematic miscalibration\n * between the model's predictions and the user's actual expectations.\n * During consolidation, replays chains of similar corrections through an LLM\n * to synthesize CalibrationRules that adjust model behavior for this specific user.\n *\n * Inspired by:\n * - Cerebellar motor calibration (prediction errors drive lasting adjustments)\n * - Temporal difference learning (dopamine signals prediction error)\n * - Tesla FSD shadow mode (divergence between prediction and reality = training signal)\n */\n\nimport { createHash } from \"node:crypto\";\nimport path from \"node:path\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { FallbackLlmClient } from \"./fallback-llm.js\";\nimport type { GatewayConfig, MemoryFile } from \"./types.js\";\nimport { listJsonFiles, readJsonFile } from \"./json-store.js\";\nimport { isRecord } from \"./store-contract.js\";\nimport { log } from \"./logger.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport interface CalibrationRule {\n  id: string;\n  ruleType: \"model_tendency\" | \"user_expectation\" | \"scope_boundary\" | \"verification_required\";\n  condition: string;\n  modelTendency: string;\n  userExpectation: string;\n  calibration: string;\n  confidence: number;\n  evidenceCount: number;\n  evidenceCorrectionIds: string[];\n  createdAt: string;\n  lastReinforcedAt: string;\n}\n\nexport interface CalibrationIndex {\n  rules: CalibrationRule[];\n  updatedAt: string;\n  totalCorrectionsAnalyzed: number;\n}\n\n// ─── Storage ─────────────────────────────────────────────────────────────────\n\nfunction calibrationDir(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", \"calibration\");\n}\n\nfunction calibrationIndexPath(memoryDir: string): string {\n  return path.join(calibrationDir(memoryDir), \"calibration-index.json\");\n}\n\nexport async function readCalibrationIndex(memoryDir: string): Promise<CalibrationIndex> {\n  try {\n    const raw = JSON.parse(await readFile(calibrationIndexPath(memoryDir), \"utf8\"));\n    return {\n      rules: Array.isArray(raw.rules) ? raw.rules : [],\n      updatedAt: typeof raw.updatedAt === \"string\" ? raw.updatedAt : new Date().toISOString(),\n      totalCorrectionsAnalyzed: typeof raw.totalCorrectionsAnalyzed === \"number\" ? raw.totalCorrectionsAnalyzed : 0,\n    };\n  } catch {\n    return { rules: [], updatedAt: new Date().toISOString(), totalCorrectionsAnalyzed: 0 };\n  }\n}\n\nasync function writeCalibrationIndex(memoryDir: string, index: CalibrationIndex): Promise<void> {\n  const dir = calibrationDir(memoryDir);\n  await mkdir(dir, { recursive: true });\n  index.updatedAt = new Date().toISOString();\n  await writeFile(calibrationIndexPath(memoryDir), JSON.stringify(index, null, 2), \"utf8\");\n}\n\n// ─── Correction Reading ──────────────────────────────────────────────────────\n\ninterface CorrectionMemory {\n  id: string;\n  content: string;\n  created: string;\n  confidence: number;\n  entityRefs: string[];\n  tags: string[];\n}\n\nasync function readCorrections(memoryDir: string): Promise<CorrectionMemory[]> {\n  const correctionsDir = path.join(memoryDir, \"corrections\");\n  const files = await listJsonFiles(correctionsDir).catch(() => {\n    // Corrections might be in facts/ directories too\n    return [] as string[];\n  });\n\n  // Also scan facts directories for correction-category files\n  const factsDir = path.join(memoryDir, \"facts\");\n  try {\n    const { readdir } = await import(\"node:fs/promises\");\n    const dayDirs = (await readdir(factsDir)).filter((d: string) => /^\\d{4}-\\d{2}-\\d{2}$/.test(d));\n    for (const day of dayDirs) {\n      const dayPath = path.join(factsDir, day);\n      const dayFiles = (await readdir(dayPath))\n        .filter((f: string) => f.startsWith(\"correction-\") && f.endsWith(\".md\"))\n        .map((f: string) => path.join(dayPath, f));\n      files.push(...dayFiles);\n    }\n  } catch {\n    // facts dir might not exist\n  }\n\n  // Also check the dedicated corrections directory\n  try {\n    const { readdir } = await import(\"node:fs/promises\");\n    const corrFiles = (await readdir(correctionsDir))\n      .filter((f: string) => f.endsWith(\".md\"))\n      .map((f: string) => path.join(correctionsDir, f));\n    files.push(...corrFiles);\n  } catch {\n    // corrections dir might not exist\n  }\n\n  const corrections: CorrectionMemory[] = [];\n  const seen = new Set<string>();\n\n  for (const filePath of files) {\n    try {\n      const raw = await readFile(filePath, \"utf8\");\n\n      // Parse frontmatter\n      const fmMatch = raw.match(/^---\\n([\\s\\S]*?)\\n---\\n([\\s\\S]*)$/);\n      if (!fmMatch) continue;\n\n      const content = fmMatch[2].trim();\n      if (!content || content.length < 10) continue;\n\n      // Extract id from frontmatter\n      const idMatch = fmMatch[1].match(/^id:\\s*(.+)$/m);\n      const id = idMatch?.[1]?.trim() ?? path.basename(filePath, \".md\");\n\n      if (seen.has(id)) continue;\n      seen.add(id);\n\n      const confMatch = fmMatch[1].match(/^confidence:\\s*(.+)$/m);\n      const confidence = confMatch ? parseFloat(confMatch[1]) : 0.9;\n\n      const entityMatch = fmMatch[1].match(/^entityRef:\\s*(.+)$/m);\n      const entityRefs = entityMatch ? [entityMatch[1].trim()] : [];\n\n      corrections.push({ id, content, created: \"\", confidence, entityRefs, tags: [] });\n    } catch {\n      // skip unparseable files\n    }\n  }\n\n  return corrections;\n}\n\n// ─── LLM-Assisted Clustering and Replay ──────────────────────────────────────\n\nconst CLUSTER_PROMPT = `You are analyzing user corrections to an AI assistant. Each correction represents a moment where the assistant's prediction of what the user wanted was WRONG.\n\nYour job: Group these corrections into clusters where the SAME TYPE of misunderstanding is happening. Then for each cluster, synthesize a CalibrationRule.\n\nA CalibrationRule describes:\n- condition: When does this type of mistake happen?\n- modelTendency: What does the model tend to assume or do wrong?\n- userExpectation: What does the user actually want instead?\n- calibration: How should the model adjust its behavior?\n- ruleType: One of \"model_tendency\", \"user_expectation\", \"scope_boundary\", \"verification_required\"\n\nFocus on PATTERNS, not individual corrections. A cluster needs at least 2 corrections to be worth a rule.\n\nOutput valid JSON only:\n{\n  \"rules\": [\n    {\n      \"ruleType\": \"model_tendency\",\n      \"condition\": \"When discussing project scope or task boundaries\",\n      \"modelTendency\": \"The model tends to assume broader scope than the user intends\",\n      \"userExpectation\": \"The user prefers narrow, specific task definitions and wants to be asked before scope expansion\",\n      \"calibration\": \"When uncertain about scope, ask for clarification rather than assuming. Default to the narrower interpretation.\",\n      \"confidence\": 0.85,\n      \"evidenceIds\": [\"correction-id-1\", \"correction-id-2\"]\n    }\n  ]\n}`;\n\nexport async function synthesizeCalibrationRules(\n  corrections: CorrectionMemory[],\n  llm: FallbackLlmClient,\n  existingRules: CalibrationRule[],\n  agentId?: string,\n): Promise<CalibrationRule[]> {\n  if (corrections.length < 2) return [];\n\n  // Format corrections for the LLM\n  const correctionText = corrections\n    .slice(0, 50) // limit to avoid huge prompts\n    .map((c, i) => `[${c.id}] ${c.content}`)\n    .join(\"\\n\\n\");\n\n  const existingRulesText = existingRules.length > 0\n    ? `\\n\\nExisting calibration rules (avoid duplicating these):\\n${existingRules.map((r) => `- ${r.condition}: ${r.calibration}`).join(\"\\n\")}`\n    : \"\";\n\n  const response = await llm.chatCompletion(\n    [\n      { role: \"system\", content: CLUSTER_PROMPT },\n      { role: \"user\", content: `Here are ${corrections.length} corrections from this user:\\n\\n${correctionText}${existingRulesText}` },\n    ],\n    { temperature: 0.3, maxTokens: 3000, agentId },\n  );\n\n  if (!response?.content) return [];\n\n  try {\n    let jsonStr = response.content.trim();\n    const fenceMatch = jsonStr.match(/```(?:json)?\\s*\\n?([\\s\\S]*?)\\n?\\s*```/);\n    if (fenceMatch) jsonStr = fenceMatch[1];\n\n    const parsed = JSON.parse(jsonStr);\n    if (!Array.isArray(parsed.rules)) return [];\n\n    const now = new Date().toISOString();\n    return parsed.rules\n      .filter((r: any) => r.condition && r.calibration && r.modelTendency)\n      .map((r: any) => ({\n        id: `cal-${createHash(\"sha256\").update(r.condition + r.calibration).digest(\"hex\").slice(0, 12)}`,\n        ruleType: r.ruleType ?? \"model_tendency\",\n        condition: String(r.condition),\n        modelTendency: String(r.modelTendency),\n        userExpectation: String(r.userExpectation ?? \"\"),\n        calibration: String(r.calibration),\n        confidence: typeof r.confidence === \"number\" ? r.confidence : 0.7,\n        evidenceCount: Array.isArray(r.evidenceIds) ? r.evidenceIds.length : 1,\n        evidenceCorrectionIds: Array.isArray(r.evidenceIds) ? r.evidenceIds : [],\n        createdAt: now,\n        lastReinforcedAt: now,\n      }));\n  } catch {\n    log.warn(\"[calibration] failed to parse LLM response\");\n    return [];\n  }\n}\n\n// ─── Recall Section ──────────────────────────────────────────────────────────\n\n/**\n * Build a recall section from calibration rules relevant to the current query.\n * Uses the LLM to select which rules apply to the current context.\n */\nexport function buildCalibrationRecallSection(\n  rules: CalibrationRule[],\n  query: string,\n  maxChars: number = 1200,\n): string | null {\n  if (rules.length === 0) return null;\n\n  // Simple relevance: include all rules (they're already filtered to this user)\n  // In production, could use embedding similarity to filter\n  const lines: string[] = [\n    \"## Model Calibration (learned from past corrections)\",\n    \"\",\n    \"Adjustments for this specific user, learned from patterns in their corrections:\",\n    \"\",\n  ];\n\n  let totalChars = lines.join(\"\\n\").length;\n\n  for (const rule of rules) {\n    const line = `- **${rule.condition}**: ${rule.modelTendency} → Instead: ${rule.calibration}`;\n    if (totalChars + line.length + 1 > maxChars) break;\n    lines.push(line);\n    totalChars += line.length + 1;\n  }\n\n  if (lines.length <= 4) return null;\n  lines.push(\"\");\n  return lines.join(\"\\n\");\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Run the full calibration pipeline:\n * 1. Read all corrections\n * 2. Send to LLM for clustering and rule synthesis\n * 3. Merge with existing rules\n * 4. Write updated index\n */\nexport async function runCalibrationConsolidation(options: {\n  memoryDir: string;\n  gatewayConfig?: GatewayConfig;\n  gatewayAgentId?: string;\n}): Promise<CalibrationRule[]> {\n  try {\n    const llm = new FallbackLlmClient(options.gatewayConfig);\n    if (!llm.isAvailable(options.gatewayAgentId)) {\n      log.debug(\"[calibration] no LLM available — skipping consolidation\");\n      return [];\n    }\n\n    const corrections = await readCorrections(options.memoryDir);\n    if (corrections.length < 3) {\n      log.debug(`[calibration] only ${corrections.length} corrections — need at least 3`);\n      return [];\n    }\n\n    const existingIndex = await readCalibrationIndex(options.memoryDir);\n\n    const newRules = await synthesizeCalibrationRules(corrections, llm, existingIndex.rules, options.gatewayAgentId);\n    if (newRules.length === 0) {\n      log.debug(\"[calibration] no new calibration rules synthesized\");\n      return existingIndex.rules;\n    }\n\n    // Merge: keep existing rules, add new ones (deduplicate by id)\n    const ruleMap = new Map(existingIndex.rules.map((r) => [r.id, r]));\n    for (const rule of newRules) {\n      if (ruleMap.has(rule.id)) {\n        // Reinforce existing rule\n        const existing = ruleMap.get(rule.id)!;\n        existing.lastReinforcedAt = new Date().toISOString();\n        existing.evidenceCount += rule.evidenceCount;\n        existing.confidence = Math.min(1, existing.confidence + 0.05);\n      } else {\n        ruleMap.set(rule.id, rule);\n      }\n    }\n\n    const allRules = [...ruleMap.values()];\n    await writeCalibrationIndex(options.memoryDir, {\n      rules: allRules,\n      updatedAt: new Date().toISOString(),\n      totalCorrectionsAnalyzed: corrections.length,\n    });\n\n    log.debug(`[calibration] synthesized ${newRules.length} new rule(s), ${allRules.length} total`);\n    return allRules;\n  } catch (error) {\n    log.warn(`[calibration] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);\n    return [];\n  }\n}\n\n/**\n * Standalone entry point for calibration consolidation that can be called\n * independently of weekly compounding. The compounding engine's\n * `synthesizeWeekly()` is one trigger, but orchestrators or periodic\n * maintenance jobs should call this directly so calibration is not gated\n * on weekly compounding being enabled.\n */\nexport async function runCalibrationIfEnabled(options: {\n  memoryDir: string;\n  calibrationEnabled: boolean;\n  gatewayConfig?: GatewayConfig;\n}): Promise<CalibrationRule[]> {\n  if (!options.calibrationEnabled) {\n    return [];\n  }\n  return runCalibrationConsolidation({\n    memoryDir: options.memoryDir,\n    gatewayConfig: options.gatewayConfig,\n  });\n}\n\n/**\n * Get calibration rules for recall injection.\n * Reads the pre-computed calibration index.\n */\nexport async function getCalibrationRulesForRecall(\n  memoryDir: string,\n): Promise<CalibrationRule[]> {\n  const index = await readCalibrationIndex(memoryDir);\n  return index.rules;\n}\n"],"mappings":"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","names":[]}

package/dist/causal-behavior.d.ts

@@ -0,0 +1,79 @@
+import { CausalChainIndex } from './causal-chain.js';
+import { MemoryCategory } from './types.js';
+import './causal-trajectory.js';
+import './objective-state.js';
+
+/**
+ * preference-consolidator.ts — IRC Preference Consolidation for Engram
+ *
+ * Post-extraction pass that synthesizes preference and correction memories
+ * into explicit preference statements. These statements are formatted to
+ * match the expected answer patterns in memory benchmarks (e.g., LongMemEval)
+ * and provide clear behavioral context during recall.
+ *
+ * The key insight: Engram extracts preferences as factual statements like
+ * "The user uses Adobe Premiere Pro for video editing." But benchmarks
+ * expect preference statements like "The user would prefer resources
+ * specifically tailored to Adobe Premiere Pro." This module bridges that gap.
+ */
+
+interface ConsolidatedPreference {
+    /** Synthesized preference statement */
+    statement: string;
+    /** Source memory IDs */
+    sourceIds: string[];
+    /** Category of the source memories */
+    category: MemoryCategory;
+    /** Confidence (max of sources) */
+    confidence: number;
+    /** Keywords for matching during recall */
+    keywords: string[];
+}
+
+/**
+ * causal-behavior.ts — CMC Phase 4: Implicit Behavioral Preference Learning
+ *
+ * Extracts behavioral signals from causal chain analysis. Unlike explicit
+ * preference extraction (which reads text), this derives preferences from
+ * patterns of action: what goals recur, what actions succeed repeatedly,
+ * what outcomes are consistently pursued.
+ *
+ * Key insight: "Preferences are recurring causal pathways."
+ */
+
+type CausalBehaviorSignalType = "topic_revisitation" | "action_pattern" | "outcome_preference" | "phrasing_style";
+interface CausalBehaviorSignal {
+    signalType: CausalBehaviorSignalType;
+    pattern: string;
+    frequency: number;
+    sessionCount: number;
+    confidence: number;
+    trajectoryIds: string[];
+}
+interface BehaviorConfig {
+    minFrequency: number;
+    minSessions: number;
+    confidenceThreshold: number;
+}
+/**
+ * Convert behavioral signals into ConsolidatedPreference entries
+ * that can be merged with existing IRC preference output.
+ */
+declare function synthesizeCausalPreferences(signals: CausalBehaviorSignal[], confidenceThreshold: number): ConsolidatedPreference[];
+/**
+ * Compute the causal impact score for a memory based on its
+ * presence in causal chains. Used in lifecycle heat/decay.
+ *
+ * Formula: 0.1 * incomingEdges + 0.15 * outgoingEdges, clamped to [0, 0.3]
+ */
+declare function computeCausalImpactScore(memoryId: string, chainIndex: CausalChainIndex): number;
+/**
+ * Extract all behavioral signals from causal trajectories and chain analysis.
+ */
+declare function extractCausalBehaviorSignals(options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    config: BehaviorConfig;
+}): Promise<CausalBehaviorSignal[]>;
+
+export { type BehaviorConfig, type CausalBehaviorSignal, type CausalBehaviorSignalType, computeCausalImpactScore, extractCausalBehaviorSignals, synthesizeCausalPreferences };

package/dist/causal-behavior.js

@@ -0,0 +1,190 @@
+import {
+  readChainIndex,
+  resolveChainsDir
+} from "./chunk-NTTLPF7F.js";
+import "./chunk-M5KEYE5E.js";
+import {
+  normalizeRecallTokens
+} from "./chunk-DT5TVLJE.js";
+import {
+  log
+} from "./chunk-KWBU5S5U.js";
+import {
+  isRecord
+} from "./chunk-DGXUHMOV.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-LPSF4OQH.js";
+
+// src/causal-behavior.ts
+import path from "path";
+function detectTopicRevisitation(trajectories, config) {
+  const goalGroups = /* @__PURE__ */ new Map();
+  for (const t of trajectories) {
+    const tokens = normalizeRecallTokens(t.goal, []).sort().join(" ");
+    if (!tokens) continue;
+    const group = goalGroups.get(tokens) ?? { sessions: /* @__PURE__ */ new Set(), trajectoryIds: [], goal: t.goal };
+    group.sessions.add(t.sessionKey);
+    group.trajectoryIds.push(t.trajectoryId);
+    goalGroups.set(tokens, group);
+  }
+  const signals = [];
+  for (const [_key, group] of goalGroups) {
+    if (group.trajectoryIds.length < config.minFrequency) continue;
+    if (group.sessions.size < config.minSessions) continue;
+    signals.push({
+      signalType: "topic_revisitation",
+      pattern: group.goal,
+      frequency: group.trajectoryIds.length,
+      sessionCount: group.sessions.size,
+      confidence: Math.min(1, 0.5 + group.sessions.size / 10),
+      trajectoryIds: group.trajectoryIds.slice(0, 10)
+    });
+  }
+  return signals;
+}
+function detectActionPatterns(trajectories, config) {
+  const actionGroups = /* @__PURE__ */ new Map();
+  for (const t of trajectories) {
+    const tokens = normalizeRecallTokens(t.actionSummary, []).sort().join(" ");
+    if (!tokens) continue;
+    const group = actionGroups.get(tokens) ?? {
+      sessions: /* @__PURE__ */ new Set(),
+      trajectoryIds: [],
+      action: t.actionSummary,
+      successCount: 0,
+      totalCount: 0
+    };
+    group.sessions.add(t.sessionKey);
+    group.trajectoryIds.push(t.trajectoryId);
+    group.totalCount++;
+    if (t.outcomeKind === "success") group.successCount++;
+    actionGroups.set(tokens, group);
+  }
+  const signals = [];
+  for (const [_key, group] of actionGroups) {
+    if (group.totalCount < Math.max(config.minFrequency, 4)) continue;
+    if (group.sessions.size < config.minSessions) continue;
+    const successRate = group.successCount / group.totalCount;
+    if (successRate < 0.8) continue;
+    signals.push({
+      signalType: "action_pattern",
+      pattern: group.action,
+      frequency: group.totalCount,
+      sessionCount: group.sessions.size,
+      confidence: Math.min(1, 0.6 + successRate * 0.3),
+      trajectoryIds: group.trajectoryIds.slice(0, 10)
+    });
+  }
+  return signals;
+}
+function detectOutcomePreferences(trajectories, chainIndex, config) {
+  const retrySuccesses = /* @__PURE__ */ new Map();
+  const trajectoryMap = new Map(trajectories.map((t) => [t.trajectoryId, t]));
+  for (const [edgeId, edge] of Object.entries(chainIndex.edges)) {
+    if (edge.edgeType !== "retry") continue;
+    const from = trajectoryMap.get(edge.fromTrajectoryId);
+    const to = trajectoryMap.get(edge.toTrajectoryId);
+    if (!from || !to) continue;
+    if (from.outcomeKind !== "failure" || to.outcomeKind !== "success") continue;
+    const goalTokens = normalizeRecallTokens(from.goal, []).sort().join(" ");
+    const group = retrySuccesses.get(goalTokens) ?? {
+      sessions: /* @__PURE__ */ new Set(),
+      trajectoryIds: [],
+      goal: from.goal,
+      count: 0
+    };
+    group.sessions.add(from.sessionKey);
+    group.sessions.add(to.sessionKey);
+    group.trajectoryIds.push(from.trajectoryId, to.trajectoryId);
+    group.count++;
+    retrySuccesses.set(goalTokens, group);
+  }
+  const signals = [];
+  for (const [_key, group] of retrySuccesses) {
+    if (group.count < config.minFrequency) continue;
+    if (group.sessions.size < config.minSessions) continue;
+    signals.push({
+      signalType: "outcome_preference",
+      pattern: group.goal,
+      frequency: group.count,
+      sessionCount: group.sessions.size,
+      confidence: Math.min(1, 0.7 + group.count / 20),
+      trajectoryIds: [...new Set(group.trajectoryIds)].slice(0, 10)
+    });
+  }
+  return signals;
+}
+function synthesizeCausalPreferences(signals, confidenceThreshold) {
+  const preferences = [];
+  for (const signal of signals) {
+    if (signal.confidence < confidenceThreshold) continue;
+    let statement;
+    switch (signal.signalType) {
+      case "topic_revisitation":
+        statement = `The user frequently works on: ${signal.pattern}. This topic has been revisited across ${signal.sessionCount} sessions.`;
+        break;
+      case "action_pattern":
+        statement = `The user prefers this approach: ${signal.pattern}. This action pattern has been successful ${signal.frequency} times.`;
+        break;
+      case "outcome_preference":
+        statement = `The user persistently pursues: ${signal.pattern}. They retry until successful, indicating strong preference.`;
+        break;
+      case "phrasing_style":
+        statement = `The user's phrasing pattern: ${signal.pattern}`;
+        break;
+    }
+    preferences.push({
+      statement,
+      sourceIds: signal.trajectoryIds.slice(0, 5),
+      category: "preference",
+      confidence: signal.confidence,
+      keywords: normalizeRecallTokens(signal.pattern, []).slice(0, 10)
+    });
+  }
+  return preferences;
+}
+function computeCausalImpactScore(memoryId, chainIndex) {
+  const incoming = chainIndex.incoming[memoryId]?.length ?? 0;
+  const outgoing = chainIndex.outgoing[memoryId]?.length ?? 0;
+  const raw = 0.1 * incoming + 0.15 * outgoing;
+  return Math.min(0.3, Math.max(0, raw));
+}
+async function extractCausalBehaviorSignals(options) {
+  try {
+    const { memoryDir, causalTrajectoryStoreDir, config: behaviorConfig } = options;
+    const root = causalTrajectoryStoreDir ? path.join(memoryDir, causalTrajectoryStoreDir) : path.join(memoryDir, "state", "causal-trajectories");
+    const trajectoriesDir = path.join(root, "trajectories");
+    const files = await listJsonFiles(trajectoriesDir).catch(() => []);
+    const trajectories = [];
+    for (const filePath of files) {
+      try {
+        const raw = await readJsonFile(filePath);
+        if (isRecord(raw) && typeof raw.trajectoryId === "string") {
+          trajectories.push(raw);
+        }
+      } catch {
+      }
+    }
+    if (trajectories.length === 0) return [];
+    const chainsDir = resolveChainsDir(memoryDir, causalTrajectoryStoreDir);
+    const chainIndex = await readChainIndex(chainsDir);
+    const signals = [
+      ...detectTopicRevisitation(trajectories, behaviorConfig),
+      ...detectActionPatterns(trajectories, behaviorConfig),
+      ...detectOutcomePreferences(trajectories, chainIndex, behaviorConfig)
+    ];
+    log.debug(`[cmc] extracted ${signals.length} behavioral signal(s) from ${trajectories.length} trajectories`);
+    return signals;
+  } catch (error) {
+    log.warn(`[cmc] behavioral signal extraction failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+export {
+  computeCausalImpactScore,
+  extractCausalBehaviorSignals,
+  synthesizeCausalPreferences
+};
+//# sourceMappingURL=causal-behavior.js.map

package/dist/causal-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/causal-behavior.ts"],"sourcesContent":["/**\n * causal-behavior.ts — CMC Phase 4: Implicit Behavioral Preference Learning\n *\n * Extracts behavioral signals from causal chain analysis. Unlike explicit\n * preference extraction (which reads text), this derives preferences from\n * patterns of action: what goals recur, what actions succeed repeatedly,\n * what outcomes are consistently pursued.\n *\n * Key insight: \"Preferences are recurring causal pathways.\"\n */\n\nimport type { CausalTrajectoryRecord } from \"./causal-trajectory.js\";\nimport type { CausalChainIndex } from \"./causal-chain.js\";\nimport { readChainIndex, resolveChainsDir } from \"./causal-chain.js\";\nimport { normalizeRecallTokens } from \"./recall-tokenization.js\";\nimport { topicOverlapScore } from \"./boxes.js\";\nimport { listJsonFiles, readJsonFile } from \"./json-store.js\";\nimport { isRecord } from \"./store-contract.js\";\nimport type { ConsolidatedPreference } from \"./compounding/preference-consolidator.js\";\nimport path from \"node:path\";\nimport { log } from \"./logger.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport type CausalBehaviorSignalType =\n  | \"topic_revisitation\"\n  | \"action_pattern\"\n  | \"outcome_preference\"\n  | \"phrasing_style\";\n\nexport interface CausalBehaviorSignal {\n  signalType: CausalBehaviorSignalType;\n  pattern: string;\n  frequency: number;\n  sessionCount: number;\n  confidence: number;\n  trajectoryIds: string[];\n}\n\nexport interface BehaviorConfig {\n  minFrequency: number;\n  minSessions: number;\n  confidenceThreshold: number;\n}\n\n// ─── Signal Extraction ───────────────────────────────────────────────────────\n\n/**\n * Detect topic revisitation: same goal fingerprint appearing in 3+ sessions.\n */\nfunction detectTopicRevisitation(\n  trajectories: CausalTrajectoryRecord[],\n  config: BehaviorConfig,\n): CausalBehaviorSignal[] {\n  const goalGroups = new Map<string, { sessions: Set<string>; trajectoryIds: string[]; goal: string }>();\n\n  for (const t of trajectories) {\n    const tokens = normalizeRecallTokens(t.goal, []).sort().join(\" \");\n    if (!tokens) continue;\n    const group = goalGroups.get(tokens) ?? { sessions: new Set(), trajectoryIds: [], goal: t.goal };\n    group.sessions.add(t.sessionKey);\n    group.trajectoryIds.push(t.trajectoryId);\n    goalGroups.set(tokens, group);\n  }\n\n  const signals: CausalBehaviorSignal[] = [];\n  for (const [_key, group] of goalGroups) {\n    if (group.trajectoryIds.length < config.minFrequency) continue;\n    if (group.sessions.size < config.minSessions) continue;\n\n    signals.push({\n      signalType: \"topic_revisitation\",\n      pattern: group.goal,\n      frequency: group.trajectoryIds.length,\n      sessionCount: group.sessions.size,\n      confidence: Math.min(1, 0.5 + (group.sessions.size / 10)),\n      trajectoryIds: group.trajectoryIds.slice(0, 10),\n    });\n  }\n\n  return signals;\n}\n\n/**\n * Detect action patterns: same action with >= 80% success rate, 4+ occurrences.\n */\nfunction detectActionPatterns(\n  trajectories: CausalTrajectoryRecord[],\n  config: BehaviorConfig,\n): CausalBehaviorSignal[] {\n  const actionGroups = new Map<string, {\n    sessions: Set<string>;\n    trajectoryIds: string[];\n    action: string;\n    successCount: number;\n    totalCount: number;\n  }>();\n\n  for (const t of trajectories) {\n    const tokens = normalizeRecallTokens(t.actionSummary, []).sort().join(\" \");\n    if (!tokens) continue;\n    const group = actionGroups.get(tokens) ?? {\n      sessions: new Set(),\n      trajectoryIds: [],\n      action: t.actionSummary,\n      successCount: 0,\n      totalCount: 0,\n    };\n    group.sessions.add(t.sessionKey);\n    group.trajectoryIds.push(t.trajectoryId);\n    group.totalCount++;\n    if (t.outcomeKind === \"success\") group.successCount++;\n    actionGroups.set(tokens, group);\n  }\n\n  const signals: CausalBehaviorSignal[] = [];\n  for (const [_key, group] of actionGroups) {\n    if (group.totalCount < Math.max(config.minFrequency, 4)) continue;\n    if (group.sessions.size < config.minSessions) continue;\n    const successRate = group.successCount / group.totalCount;\n    if (successRate < 0.8) continue;\n\n    signals.push({\n      signalType: \"action_pattern\",\n      pattern: group.action,\n      frequency: group.totalCount,\n      sessionCount: group.sessions.size,\n      confidence: Math.min(1, 0.6 + (successRate * 0.3)),\n      trajectoryIds: group.trajectoryIds.slice(0, 10),\n    });\n  }\n\n  return signals;\n}\n\n/**\n * Detect outcome preferences: consistent retry patterns leading to success.\n * When a trajectory fails and is retried (via chain edges) successfully,\n * it indicates a strong preference for that outcome.\n */\nfunction detectOutcomePreferences(\n  trajectories: CausalTrajectoryRecord[],\n  chainIndex: CausalChainIndex,\n  config: BehaviorConfig,\n): CausalBehaviorSignal[] {\n  const retrySuccesses = new Map<string, {\n    sessions: Set<string>;\n    trajectoryIds: string[];\n    goal: string;\n    count: number;\n  }>();\n\n  const trajectoryMap = new Map(trajectories.map((t) => [t.trajectoryId, t]));\n\n  for (const [edgeId, edge] of Object.entries(chainIndex.edges)) {\n    if (edge.edgeType !== \"retry\") continue;\n\n    const from = trajectoryMap.get(edge.fromTrajectoryId);\n    const to = trajectoryMap.get(edge.toTrajectoryId);\n    if (!from || !to) continue;\n    if (from.outcomeKind !== \"failure\" || to.outcomeKind !== \"success\") continue;\n\n    const goalTokens = normalizeRecallTokens(from.goal, []).sort().join(\" \");\n    const group = retrySuccesses.get(goalTokens) ?? {\n      sessions: new Set(),\n      trajectoryIds: [],\n      goal: from.goal,\n      count: 0,\n    };\n    group.sessions.add(from.sessionKey);\n    group.sessions.add(to.sessionKey);\n    group.trajectoryIds.push(from.trajectoryId, to.trajectoryId);\n    group.count++;\n    retrySuccesses.set(goalTokens, group);\n  }\n\n  const signals: CausalBehaviorSignal[] = [];\n  for (const [_key, group] of retrySuccesses) {\n    if (group.count < config.minFrequency) continue;\n    if (group.sessions.size < config.minSessions) continue;\n\n    signals.push({\n      signalType: \"outcome_preference\",\n      pattern: group.goal,\n      frequency: group.count,\n      sessionCount: group.sessions.size,\n      confidence: Math.min(1, 0.7 + (group.count / 20)),\n      trajectoryIds: [...new Set(group.trajectoryIds)].slice(0, 10),\n    });\n  }\n\n  return signals;\n}\n\n// ─── Preference Synthesis ────────────────────────────────────────────────────\n\n/**\n * Convert behavioral signals into ConsolidatedPreference entries\n * that can be merged with existing IRC preference output.\n */\nexport function synthesizeCausalPreferences(\n  signals: CausalBehaviorSignal[],\n  confidenceThreshold: number,\n): ConsolidatedPreference[] {\n  const preferences: ConsolidatedPreference[] = [];\n\n  for (const signal of signals) {\n    if (signal.confidence < confidenceThreshold) continue;\n\n    let statement: string;\n    switch (signal.signalType) {\n      case \"topic_revisitation\":\n        statement = `The user frequently works on: ${signal.pattern}. This topic has been revisited across ${signal.sessionCount} sessions.`;\n        break;\n      case \"action_pattern\":\n        statement = `The user prefers this approach: ${signal.pattern}. This action pattern has been successful ${signal.frequency} times.`;\n        break;\n      case \"outcome_preference\":\n        statement = `The user persistently pursues: ${signal.pattern}. They retry until successful, indicating strong preference.`;\n        break;\n      case \"phrasing_style\":\n        statement = `The user's phrasing pattern: ${signal.pattern}`;\n        break;\n    }\n\n    preferences.push({\n      statement,\n      sourceIds: signal.trajectoryIds.slice(0, 5),\n      category: \"preference\",\n      confidence: signal.confidence,\n      keywords: normalizeRecallTokens(signal.pattern, []).slice(0, 10),\n    });\n  }\n\n  return preferences;\n}\n\n// ─── Causal Impact Score ─────────────────────────────────────────────────────\n\n/**\n * Compute the causal impact score for a memory based on its\n * presence in causal chains. Used in lifecycle heat/decay.\n *\n * Formula: 0.1 * incomingEdges + 0.15 * outgoingEdges, clamped to [0, 0.3]\n */\nexport function computeCausalImpactScore(\n  memoryId: string,\n  chainIndex: CausalChainIndex,\n): number {\n  // Memory IDs don't directly map to trajectory IDs, but trajectory-based\n  // memories may reference their source trajectory ID. For now, check\n  // if the memoryId appears as a trajectory ID in the chain index.\n  const incoming = chainIndex.incoming[memoryId]?.length ?? 0;\n  const outgoing = chainIndex.outgoing[memoryId]?.length ?? 0;\n  const raw = 0.1 * incoming + 0.15 * outgoing;\n  return Math.min(0.3, Math.max(0, raw));\n}\n\n// ─── Public API ──────────────────────────────────────────────────────────────\n\n/**\n * Extract all behavioral signals from causal trajectories and chain analysis.\n */\nexport async function extractCausalBehaviorSignals(options: {\n  memoryDir: string;\n  causalTrajectoryStoreDir?: string;\n  config: BehaviorConfig;\n}): Promise<CausalBehaviorSignal[]> {\n  try {\n    const { memoryDir, causalTrajectoryStoreDir, config: behaviorConfig } = options;\n\n    // Read all trajectories\n    const root = causalTrajectoryStoreDir\n      ? path.join(memoryDir, causalTrajectoryStoreDir)\n      : path.join(memoryDir, \"state\", \"causal-trajectories\");\n    const trajectoriesDir = path.join(root, \"trajectories\");\n    const files = await listJsonFiles(trajectoriesDir).catch(() => [] as string[]);\n\n    const trajectories: CausalTrajectoryRecord[] = [];\n    for (const filePath of files) {\n      try {\n        const raw = await readJsonFile(filePath);\n        if (isRecord(raw) && typeof raw.trajectoryId === \"string\") {\n          trajectories.push(raw as unknown as CausalTrajectoryRecord);\n        }\n      } catch {\n        // skip\n      }\n    }\n\n    if (trajectories.length === 0) return [];\n\n    // Read chain index\n    const chainsDir = resolveChainsDir(memoryDir, causalTrajectoryStoreDir);\n    const chainIndex = await readChainIndex(chainsDir);\n\n    // Extract all signal types\n    const signals: CausalBehaviorSignal[] = [\n      ...detectTopicRevisitation(trajectories, behaviorConfig),\n      ...detectActionPatterns(trajectories, behaviorConfig),\n      ...detectOutcomePreferences(trajectories, chainIndex, behaviorConfig),\n    ];\n\n    log.debug(`[cmc] extracted ${signals.length} behavioral signal(s) from ${trajectories.length} trajectories`);\n    return signals;\n  } catch (error) {\n    log.warn(`[cmc] behavioral signal extraction failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);\n    return [];\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAmBA,OAAO,UAAU;AA+BjB,SAAS,wBACP,cACA,QACwB;AACxB,QAAM,aAAa,oBAAI,IAA8E;AAErG,aAAW,KAAK,cAAc;AAC5B,UAAM,SAAS,sBAAsB,EAAE,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG;AAChE,QAAI,CAAC,OAAQ;AACb,UAAM,QAAQ,WAAW,IAAI,MAAM,KAAK,EAAE,UAAU,oBAAI,IAAI,GAAG,eAAe,CAAC,GAAG,MAAM,EAAE,KAAK;AAC/F,UAAM,SAAS,IAAI,EAAE,UAAU;AAC/B,UAAM,cAAc,KAAK,EAAE,YAAY;AACvC,eAAW,IAAI,QAAQ,KAAK;AAAA,EAC9B;AAEA,QAAM,UAAkC,CAAC;AACzC,aAAW,CAAC,MAAM,KAAK,KAAK,YAAY;AACtC,QAAI,MAAM,cAAc,SAAS,OAAO,aAAc;AACtD,QAAI,MAAM,SAAS,OAAO,OAAO,YAAa;AAE9C,YAAQ,KAAK;AAAA,MACX,YAAY;AAAA,MACZ,SAAS,MAAM;AAAA,MACf,WAAW,MAAM,cAAc;AAAA,MAC/B,cAAc,MAAM,SAAS;AAAA,MAC7B,YAAY,KAAK,IAAI,GAAG,MAAO,MAAM,SAAS,OAAO,EAAG;AAAA,MACxD,eAAe,MAAM,cAAc,MAAM,GAAG,EAAE;AAAA,IAChD,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAKA,SAAS,qBACP,cACA,QACwB;AACxB,QAAM,eAAe,oBAAI,IAMtB;AAEH,aAAW,KAAK,cAAc;AAC5B,UAAM,SAAS,sBAAsB,EAAE,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG;AACzE,QAAI,CAAC,OAAQ;AACb,UAAM,QAAQ,aAAa,IAAI,MAAM,KAAK;AAAA,MACxC,UAAU,oBAAI,IAAI;AAAA,MAClB,eAAe,CAAC;AAAA,MAChB,QAAQ,EAAE;AAAA,MACV,cAAc;AAAA,MACd,YAAY;AAAA,IACd;AACA,UAAM,SAAS,IAAI,EAAE,UAAU;AAC/B,UAAM,cAAc,KAAK,EAAE,YAAY;AACvC,UAAM;AACN,QAAI,EAAE,gBAAgB,UAAW,OAAM;AACvC,iBAAa,IAAI,QAAQ,KAAK;AAAA,EAChC;AAEA,QAAM,UAAkC,CAAC;AACzC,aAAW,CAAC,MAAM,KAAK,KAAK,cAAc;AACxC,QAAI,MAAM,aAAa,KAAK,IAAI,OAAO,cAAc,CAAC,EAAG;AACzD,QAAI,MAAM,SAAS,OAAO,OAAO,YAAa;AAC9C,UAAM,cAAc,MAAM,eAAe,MAAM;AAC/C,QAAI,cAAc,IAAK;AAEvB,YAAQ,KAAK;AAAA,MACX,YAAY;AAAA,MACZ,SAAS,MAAM;AAAA,MACf,WAAW,MAAM;AAAA,MACjB,cAAc,MAAM,SAAS;AAAA,MAC7B,YAAY,KAAK,IAAI,GAAG,MAAO,cAAc,GAAI;AAAA,MACjD,eAAe,MAAM,cAAc,MAAM,GAAG,EAAE;AAAA,IAChD,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAOA,SAAS,yBACP,cACA,YACA,QACwB;AACxB,QAAM,iBAAiB,oBAAI,IAKxB;AAEH,QAAM,gBAAgB,IAAI,IAAI,aAAa,IAAI,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC;AAE1E,aAAW,CAAC,QAAQ,IAAI,KAAK,OAAO,QAAQ,WAAW,KAAK,GAAG;AAC7D,QAAI,KAAK,aAAa,QAAS;AAE/B,UAAM,OAAO,cAAc,IAAI,KAAK,gBAAgB;AACpD,UAAM,KAAK,cAAc,IAAI,KAAK,cAAc;AAChD,QAAI,CAAC,QAAQ,CAAC,GAAI;AAClB,QAAI,KAAK,gBAAgB,aAAa,GAAG,gBAAgB,UAAW;AAEpE,UAAM,aAAa,sBAAsB,KAAK,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG;AACvE,UAAM,QAAQ,eAAe,IAAI,UAAU,KAAK;AAAA,MAC9C,UAAU,oBAAI,IAAI;AAAA,MAClB,eAAe,CAAC;AAAA,MAChB,MAAM,KAAK;AAAA,MACX,OAAO;AAAA,IACT;AACA,UAAM,SAAS,IAAI,KAAK,UAAU;AAClC,UAAM,SAAS,IAAI,GAAG,UAAU;AAChC,UAAM,cAAc,KAAK,KAAK,cAAc,GAAG,YAAY;AAC3D,UAAM;AACN,mBAAe,IAAI,YAAY,KAAK;AAAA,EACtC;AAEA,QAAM,UAAkC,CAAC;AACzC,aAAW,CAAC,MAAM,KAAK,KAAK,gBAAgB;AAC1C,QAAI,MAAM,QAAQ,OAAO,aAAc;AACvC,QAAI,MAAM,SAAS,OAAO,OAAO,YAAa;AAE9C,YAAQ,KAAK;AAAA,MACX,YAAY;AAAA,MACZ,SAAS,MAAM;AAAA,MACf,WAAW,MAAM;AAAA,MACjB,cAAc,MAAM,SAAS;AAAA,MAC7B,YAAY,KAAK,IAAI,GAAG,MAAO,MAAM,QAAQ,EAAG;AAAA,MAChD,eAAe,CAAC,GAAG,IAAI,IAAI,MAAM,aAAa,CAAC,EAAE,MAAM,GAAG,EAAE;AAAA,IAC9D,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAQO,SAAS,4BACd,SACA,qBAC0B;AAC1B,QAAM,cAAwC,CAAC;AAE/C,aAAW,UAAU,SAAS;AAC5B,QAAI,OAAO,aAAa,oBAAqB;AAE7C,QAAI;AACJ,YAAQ,OAAO,YAAY;AAAA,MACzB,KAAK;AACH,oBAAY,iCAAiC,OAAO,OAAO,0CAA0C,OAAO,YAAY;AACxH;AAAA,MACF,KAAK;AACH,oBAAY,mCAAmC,OAAO,OAAO,6CAA6C,OAAO,SAAS;AAC1H;AAAA,MACF,KAAK;AACH,oBAAY,kCAAkC,OAAO,OAAO;AAC5D;AAAA,MACF,KAAK;AACH,oBAAY,gCAAgC,OAAO,OAAO;AAC1D;AAAA,IACJ;AAEA,gBAAY,KAAK;AAAA,MACf;AAAA,MACA,WAAW,OAAO,cAAc,MAAM,GAAG,CAAC;AAAA,MAC1C,UAAU;AAAA,MACV,YAAY,OAAO;AAAA,MACnB,UAAU,sBAAsB,OAAO,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,EAAE;AAAA,IACjE,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAUO,SAAS,yBACd,UACA,YACQ;AAIR,QAAM,WAAW,WAAW,SAAS,QAAQ,GAAG,UAAU;AAC1D,QAAM,WAAW,WAAW,SAAS,QAAQ,GAAG,UAAU;AAC1D,QAAM,MAAM,MAAM,WAAW,OAAO;AACpC,SAAO,KAAK,IAAI,KAAK,KAAK,IAAI,GAAG,GAAG,CAAC;AACvC;AAOA,eAAsB,6BAA6B,SAIf;AAClC,MAAI;AACF,UAAM,EAAE,WAAW,0BAA0B,QAAQ,eAAe,IAAI;AAGxE,UAAM,OAAO,2BACT,KAAK,KAAK,WAAW,wBAAwB,IAC7C,KAAK,KAAK,WAAW,SAAS,qBAAqB;AACvD,UAAM,kBAAkB,KAAK,KAAK,MAAM,cAAc;AACtD,UAAM,QAAQ,MAAM,cAAc,eAAe,EAAE,MAAM,MAAM,CAAC,CAAa;AAE7E,UAAM,eAAyC,CAAC;AAChD,eAAW,YAAY,OAAO;AAC5B,UAAI;AACF,cAAM,MAAM,MAAM,aAAa,QAAQ;AACvC,YAAI,SAAS,GAAG,KAAK,OAAO,IAAI,iBAAiB,UAAU;AACzD,uBAAa,KAAK,GAAwC;AAAA,QAC5D;AAAA,MACF,QAAQ;AAAA,MAER;AAAA,IACF;AAEA,QAAI,aAAa,WAAW,EAAG,QAAO,CAAC;AAGvC,UAAM,YAAY,iBAAiB,WAAW,wBAAwB;AACtE,UAAM,aAAa,MAAM,eAAe,SAAS;AAGjD,UAAM,UAAkC;AAAA,MACtC,GAAG,wBAAwB,cAAc,cAAc;AAAA,MACvD,GAAG,qBAAqB,cAAc,cAAc;AAAA,MACpD,GAAG,yBAAyB,cAAc,YAAY,cAAc;AAAA,IACtE;AAEA,QAAI,MAAM,mBAAmB,QAAQ,MAAM,8BAA8B,aAAa,MAAM,eAAe;AAC3G,WAAO;AAAA,EACT,SAAS,OAAO;AACd,QAAI,KAAK,0DAA0D,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,CAAC,EAAE;AAC3H,WAAO,CAAC;AAAA,EACV;AACF;","names":[]}

package/dist/causal-chain.d.ts

@@ -0,0 +1,61 @@
+import { CausalTrajectoryRecord } from './causal-trajectory.js';
+import './objective-state.js';
+
+/**
+ * causal-chain.ts — Cross-session causal chain persistence for CMC.
+ *
+ * Stitches causal trajectories across session boundaries by detecting
+ * when a trajectory in one session follows up on a trajectory from
+ * another session. Persists edges in a graph index for later retrieval.
+ */
+
+interface CausalEdge {
+    schemaVersion: 1;
+    edgeId: string;
+    fromTrajectoryId: string;
+    toTrajectoryId: string;
+    edgeType: "follow_up_to_goal" | "retry" | "continuation" | "correction";
+    confidence: number;
+    stitchMethod: "lexical" | "entity" | "temporal" | "explicit";
+    createdAt: string;
+    metadata?: Record<string, string>;
+}
+interface CausalChainIndex {
+    outgoing: Record<string, string[]>;
+    incoming: Record<string, string[]>;
+    edges: Record<string, CausalEdge>;
+    updatedAt: string;
+}
+interface StitchConfig {
+    lookbackDays: number;
+    minScore: number;
+    maxEdgesPerTrajectory: number;
+}
+interface StitchCandidate {
+    trajectory: CausalTrajectoryRecord;
+    score: number;
+    edgeType: CausalEdge["edgeType"];
+    stitchMethod: CausalEdge["stitchMethod"];
+}
+declare function validateCausalEdge(raw: unknown): CausalEdge;
+declare function makeEdgeId(fromId: string, toId: string): string;
+declare function resolveChainsDir(memoryDir: string, causalTrajectoryStoreDir?: string): string;
+declare function readChainIndex(chainsDir: string): Promise<CausalChainIndex>;
+declare function writeChainIndex(chainsDir: string, index: CausalChainIndex): Promise<void>;
+/**
+ * Score how strongly a candidate trajectory from another session
+ * relates to the new trajectory being recorded.
+ */
+declare function scoreStitchCandidate(newTrajectory: CausalTrajectoryRecord, candidate: CausalTrajectoryRecord): StitchCandidate;
+/**
+ * After a new trajectory is recorded, attempt to stitch it to
+ * existing trajectories from other sessions.
+ */
+declare function stitchCausalChain(options: {
+    memoryDir: string;
+    causalTrajectoryStoreDir?: string;
+    newTrajectory: CausalTrajectoryRecord;
+    config: StitchConfig;
+}): Promise<CausalEdge[]>;
+
+export { type CausalChainIndex, type CausalEdge, type StitchCandidate, type StitchConfig, makeEdgeId, readChainIndex, resolveChainsDir, scoreStitchCandidate, stitchCausalChain, validateCausalEdge, writeChainIndex };