@remnic/core 1.1.31 → 9.3.515

package/src/calibration.ts

@@ -84,6 +84,29 @@ export interface CorrectionMemory {
   tags: string[];
 }
 
+const CALIBRATION_RULE_TYPES = new Set([
+  "model_tendency",
+  "user_expectation",
+  "scope_boundary",
+  "verification_required",
+]);
+
+function parseConfidence(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.max(0, Math.min(1, value));
+}
+
+function parseEvidenceIds(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
 /**
  * Exported for entity-contamination R-11 regression coverage (#682
  * PR 2/3 — codex review).  Tests can drive the real correction-reading
@@ -235,21 +258,42 @@ export async function synthesizeCalibrationRules(
     if (!Array.isArray(parsed.rules)) return [];
 
     const now = new Date().toISOString();
-    return parsed.rules
-      .filter((r: any) => r.condition && r.calibration && r.modelTendency)
-      .map((r: any) => ({
-        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 : [],
+    const rawRules: unknown[] = Array.isArray(parsed.rules) ? parsed.rules : [];
+    return rawRules
+      .map((r: unknown): CalibrationRule | undefined => {
+        if (!r || typeof r !== "object" || Array.isArray(r)) return undefined;
+        const raw = r as Record<string, unknown>;
+        const ruleType = nonEmptyString(raw.ruleType);
+        const condition = nonEmptyString(raw.condition);
+        const modelTendency = nonEmptyString(raw.modelTendency);
+        const calibration = nonEmptyString(raw.calibration);
+        const confidence = parseConfidence(raw.confidence);
+        if (
+          !ruleType ||
+          !CALIBRATION_RULE_TYPES.has(ruleType) ||
+          !condition ||
+          !modelTendency ||
+          !calibration ||
+          confidence === undefined
+        ) {
+          return undefined;
+        }
+        const evidenceCorrectionIds = parseEvidenceIds(raw.evidenceIds);
+        return {
+          id: `cal-${createHash("sha256").update(condition + calibration).digest("hex").slice(0, 12)}`,
+          ruleType: ruleType as CalibrationRule["ruleType"],
+          condition,
+          modelTendency,
+          userExpectation: nonEmptyString(raw.userExpectation) ?? "",
+          calibration,
+          confidence,
+          evidenceCount: evidenceCorrectionIds.length,
+          evidenceCorrectionIds,
         createdAt: now,
         lastReinforcedAt: now,
-      }));
+        };
+      })
+      .filter((rule): rule is CalibrationRule => !!rule);
   } catch {
     log.warn("[calibration] failed to parse LLM response");
     return [];

package/src/causal-consolidation.test.ts

@@ -0,0 +1,214 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { deriveCausalPromotionCandidates } from "./causal-consolidation.js";
+import type { CausalTrajectoryRecord } from "./causal-trajectory.js";
+
+function trajectory(
+  id: string,
+  sessionKey: string,
+  outcomeKind: CausalTrajectoryRecord["outcomeKind"] = "success",
+): CausalTrajectoryRecord {
+  return {
+    schemaVersion: 1,
+    trajectoryId: id,
+    recordedAt: "2026-05-21T00:00:00.000Z",
+    sessionKey,
+    goal: "fix the recurring benchmark issue",
+    actionSummary: "run the focused regression and patch the boundary",
+    observationSummary: "the regression captured the failure",
+    outcomeKind,
+    outcomeSummary: outcomeKind === "success" ? "the fix passed" : "the fix did not pass",
+  };
+}
+
+async function withTrajectoryStore<T>(
+  trajectories: CausalTrajectoryRecord[],
+  run: (dirs: { memoryDir: string; storeDir: string }) => Promise<T>,
+): Promise<T> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-causal-consolidation-"));
+  const storeDir = path.join(root, "causal-store");
+  const trajectoriesDir = path.join(storeDir, "trajectories", "2026-05-21");
+  await mkdir(trajectoriesDir, { recursive: true });
+  for (const record of trajectories) {
+    await writeFile(
+      path.join(trajectoriesDir, `${record.trajectoryId}.json`),
+      JSON.stringify(record, null, 2),
+      "utf8",
+    );
+  }
+  try {
+    return await run({ memoryDir: root, storeDir });
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function llmStub() {
+  let calls = 0;
+  return {
+    get calls() {
+      return calls;
+    },
+    isAvailable() {
+      return true;
+    },
+    async chatCompletion() {
+      calls += 1;
+      return {
+        content: JSON.stringify({
+          rules: [
+            {
+              content: "Prefer focused regressions before broad benchmark reruns.",
+              category: "rule",
+              confidence: 0.9,
+              evidence: ["t1", "t2"],
+            },
+          ],
+          preferences: [],
+        }),
+      };
+    },
+  };
+}
+
+function llmWithContent(content: string) {
+  let calls = 0;
+  return {
+    get calls() {
+      return calls;
+    },
+    isAvailable() {
+      return true;
+    },
+    async chatCompletion() {
+      calls += 1;
+      return { content };
+    },
+  };
+}
+
+test("deriveCausalPromotionCandidates enforces minSessions before LLM consolidation", async () => {
+  const llm = llmStub();
+  await withTrajectoryStore(
+    [trajectory("t1", "same"), trajectory("t2", "same"), trajectory("t3", "same")],
+    async ({ memoryDir, storeDir }) => {
+      const candidates = await deriveCausalPromotionCandidates({
+        memoryDir,
+        causalTrajectoryStoreDir: storeDir,
+        config: { minRecurrence: 3, minSessions: 2, successThreshold: 0.7 },
+        llmClient: llm,
+      });
+
+      assert.deepEqual(candidates, []);
+      assert.equal(llm.calls, 0);
+    },
+  );
+});
+
+test("deriveCausalPromotionCandidates enforces successThreshold before LLM consolidation", async () => {
+  const llm = llmStub();
+  await withTrajectoryStore(
+    [
+      trajectory("t1", "a", "success"),
+      trajectory("t2", "b", "failure"),
+      trajectory("t3", "c", "failure"),
+    ],
+    async ({ memoryDir, storeDir }) => {
+      const candidates = await deriveCausalPromotionCandidates({
+        memoryDir,
+        causalTrajectoryStoreDir: storeDir,
+        config: { minRecurrence: 3, minSessions: 2, successThreshold: 0.7 },
+        llmClient: llm,
+      });
+
+      assert.deepEqual(candidates, []);
+      assert.equal(llm.calls, 0);
+    },
+  );
+});
+
+test("deriveCausalPromotionCandidates calls LLM when recurrence session and success gates pass", async () => {
+  const llm = llmStub();
+  await withTrajectoryStore(
+    [
+      trajectory("t1", "a", "success"),
+      trajectory("t2", "b", "success"),
+      trajectory("t3", "c", "partial"),
+    ],
+    async ({ memoryDir, storeDir }) => {
+      const candidates = await deriveCausalPromotionCandidates({
+        memoryDir,
+        causalTrajectoryStoreDir: storeDir,
+        config: { minRecurrence: 3, minSessions: 2, successThreshold: 0.7 },
+        llmClient: llm,
+      });
+
+      assert.equal(llm.calls, 1);
+      assert.equal(candidates.length, 1);
+      assert.equal(candidates[0]?.content, "Prefer focused regressions before broad benchmark reruns.");
+    },
+  );
+});
+
+test("deriveCausalPromotionCandidates validates LLM-derived rule fields", async () => {
+  const llm = llmWithContent(JSON.stringify({
+    rules: [
+      {
+        content: "This invalid category must be dropped.",
+        category: "bad",
+        confidence: 0.9,
+        evidence: ["t1"],
+      },
+      {
+        content: "This invalid confidence must be dropped.",
+        category: "rule",
+        confidence: "0.9",
+        evidence: ["t2"],
+      },
+      {
+        content: "Clamp high confidence and filter evidence values.",
+        category: "rule",
+        confidence: 999,
+        evidence: [123, "t1", "", "t2"],
+      },
+    ],
+    preferences: [
+      {
+        statement: "Drop invalid preference confidence.",
+        confidence: null,
+        evidence: ["t3"],
+      },
+      {
+        statement: "The user prefers narrow verification claims.",
+        confidence: 0.8,
+        evidence: "t3",
+      },
+    ],
+  }));
+
+  await withTrajectoryStore(
+    [
+      trajectory("t1", "a", "success"),
+      trajectory("t2", "b", "success"),
+      trajectory("t3", "c", "partial"),
+    ],
+    async ({ memoryDir, storeDir }) => {
+      const candidates = await deriveCausalPromotionCandidates({
+        memoryDir,
+        causalTrajectoryStoreDir: storeDir,
+        config: { minRecurrence: 3, minSessions: 2, successThreshold: 0.7 },
+        llmClient: llm,
+      });
+
+      assert.equal(candidates.length, 2);
+      assert.equal(candidates[0]?.score, 1);
+      assert.deepEqual(candidates[0]?.provenance, ["t1", "t2"]);
+      assert.equal(candidates[1]?.category, "preference");
+      assert.deepEqual(candidates[1]?.provenance, []);
+    },
+  );
+});

package/src/causal-consolidation.ts

@@ -17,7 +17,7 @@ import { resolveCausalTrajectoryStoreDir, type CausalTrajectoryRecord } from "./
 import { readChainIndex, resolveChainsDir, type CausalChainIndex, type CausalEdge } from "./causal-chain.js";
 import { listJsonFiles, readJsonFile } from "./json-store.js";
 import { isRecord } from "./store-contract.js";
-import { FallbackLlmClient } from "./fallback-llm.js";
+import { FallbackLlmClient, fallbackLlmRuntimeContextFromConfig } from "./fallback-llm.js";
 import type { GatewayConfig, MemoryFile, PluginConfig } from "./types.js";
 import path from "node:path";
 import { log } from "./logger.js";
@@ -31,7 +31,7 @@ export interface CausalPatternCandidate {
   id: string;
   sourceType: "causal-pattern";
   subject: string;
-  category: "principle" | "rule";
+  category: "principle" | "rule" | "preference";
   content: string;
   score: number;
   rationale: string;
@@ -61,6 +61,16 @@ export interface LlmConsolidationResult {
   }>;
 }
 
+const CAUSAL_RULE_CATEGORIES = new Set(["rule", "principle", "preference"]);
+
+interface ConsolidationLlmClient {
+  isAvailable(agentId?: string): boolean;
+  chatCompletion(
+    messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+    options?: { temperature?: number; maxTokens?: number; agentId?: string },
+  ): Promise<{ content: string } | null>;
+}
+
 // ─── Trajectory Reading ──────────────────────────────────────────────────────
 
 async function readAllTrajectories(
@@ -177,7 +187,7 @@ If no clear patterns exist, return {"rules": [], "preferences": []}.`;
 
 async function consolidateWithLlm(
   context: string,
-  llm: FallbackLlmClient,
+  llm: ConsolidationLlmClient,
   agentId?: string,
 ): Promise<LlmConsolidationResult> {
   const response = await llm.chatCompletion(
@@ -199,13 +209,15 @@ async function consolidateWithLlm(
     if (fenceMatch) jsonStr = fenceMatch[1];
 
     const parsed = JSON.parse(jsonStr);
+    const rawRules: unknown[] = Array.isArray(parsed.rules) ? parsed.rules : [];
+    const rawPreferences: unknown[] = Array.isArray(parsed.preferences) ? parsed.preferences : [];
     return {
-      rules: Array.isArray(parsed.rules) ? parsed.rules.filter(
-        (r: any) => typeof r.content === "string" && r.content.length > 5,
-      ) : [],
-      preferences: Array.isArray(parsed.preferences) ? parsed.preferences.filter(
-        (p: any) => typeof p.statement === "string" && p.statement.length > 5,
-      ) : [],
+      rules: rawRules
+        .map(parseLlmRule)
+        .filter((rule): rule is LlmConsolidationResult["rules"][number] => !!rule),
+      preferences: rawPreferences
+        .map(parseLlmPreference)
+        .filter((pref): pref is LlmConsolidationResult["preferences"][number] => !!pref),
     };
   } catch {
     log.warn("[cmc] failed to parse LLM consolidation response");
@@ -223,11 +235,54 @@ function stablePatternId(content: string): string {
   return `causal-pattern:${digest}`;
 }
 
+function parseConfidence(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  return Math.max(0, Math.min(1, value));
+}
+
+function parseEvidence(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((item): item is string => typeof item === "string" && item.trim().length > 0);
+}
+
+function parseLlmRule(raw: unknown): LlmConsolidationResult["rules"][number] | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const r = raw as Record<string, unknown>;
+  const content = typeof r.content === "string" ? r.content.trim() : "";
+  const category = typeof r.category === "string" ? r.category : "";
+  const confidence = parseConfidence(r.confidence);
+  if (content.length <= 5 || !CAUSAL_RULE_CATEGORIES.has(category) || confidence === undefined) {
+    return undefined;
+  }
+  return {
+    content,
+    category: category as "rule" | "principle" | "preference",
+    confidence,
+    evidence: parseEvidence(r.evidence),
+  };
+}
+
+function parseLlmPreference(raw: unknown): LlmConsolidationResult["preferences"][number] | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const p = raw as Record<string, unknown>;
+  const statement = typeof p.statement === "string" ? p.statement.trim() : "";
+  const confidence = parseConfidence(p.confidence);
+  if (statement.length <= 5 || confidence === undefined) return undefined;
+  return {
+    statement,
+    confidence,
+    evidence: parseEvidence(p.evidence),
+  };
+}
+
 function llmResultToCandidates(result: LlmConsolidationResult): CausalPatternCandidate[] {
   const candidates: CausalPatternCandidate[] = [];
 
   for (const rule of result.rules) {
-    const category = rule.category === "principle" ? "principle" : "rule";
+    const category =
+      rule.category === "principle" || rule.category === "preference"
+        ? rule.category
+        : "rule";
     candidates.push({
       id: stablePatternId(rule.content),
       sourceType: "causal-pattern",
@@ -243,9 +298,65 @@ function llmResultToCandidates(result: LlmConsolidationResult): CausalPatternCan
     });
   }
 
+  for (const preference of result.preferences) {
+    candidates.push({
+      id: stablePatternId(preference.statement),
+      sourceType: "causal-pattern",
+      subject: preference.statement.slice(0, 80),
+      category: "preference",
+      content: preference.statement,
+      score: Math.min(1, preference.confidence ?? 0.7),
+      rationale: "LLM-identified preference from cross-session trajectory analysis",
+      outcome: null,
+      provenance: (preference.evidence ?? []).slice(0, 5),
+      agent: null,
+      workflow: null,
+    });
+  }
+
   return candidates;
 }
 
+function normalizePositiveInteger(value: number, fallback: number): number {
+  return Number.isFinite(value) && value > 0 ? Math.floor(value) : fallback;
+}
+
+function normalizeSuccessThreshold(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) return 0;
+  return Math.min(1, value);
+}
+
+function trajectorySuccessScore(trajectory: CausalTrajectoryRecord): number {
+  if (trajectory.outcomeKind === "success") return 1;
+  if (trajectory.outcomeKind === "partial") return 0.5;
+  return 0;
+}
+
+function averageSuccessScore(trajectories: CausalTrajectoryRecord[]): number {
+  if (trajectories.length === 0) return 0;
+  const total = trajectories.reduce((sum, trajectory) => sum + trajectorySuccessScore(trajectory), 0);
+  return total / trajectories.length;
+}
+
+function passesConsolidationGates(
+  trajectories: CausalTrajectoryRecord[],
+  config: ConsolidationConfig,
+): boolean {
+  const minRecurrence = normalizePositiveInteger(config.minRecurrence, 1);
+  if (trajectories.length < minRecurrence) return false;
+
+  const minSessions = normalizePositiveInteger(config.minSessions, 1);
+  const sessionCount = new Set(trajectories.map((trajectory) => trajectory.sessionKey)).size;
+  if (sessionCount < minSessions) return false;
+
+  const successThreshold = normalizeSuccessThreshold(config.successThreshold);
+  if (successThreshold > 0 && averageSuccessScore(trajectories) < successThreshold) {
+    return false;
+  }
+
+  return true;
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -260,10 +371,11 @@ export async function deriveCausalPromotionCandidates(options: {
   gatewayAgentId?: string;
   workspaceDir?: string;
   pluginConfig?: PluginConfig;
+  llmClient?: ConsolidationLlmClient;
 }): Promise<CausalPatternCandidate[]> {
   try {
     const trajectories = await readAllTrajectories(options.memoryDir, options.causalTrajectoryStoreDir);
-    if (trajectories.length < options.config.minRecurrence) return [];
+    if (!passesConsolidationGates(trajectories, options.config)) return [];
 
     const chainsDir = resolveChainsDir(options.memoryDir, options.causalTrajectoryStoreDir);
     const chainIndex = await readChainIndex(chainsDir);
@@ -280,9 +392,14 @@ export async function deriveCausalPromotionCandidates(options: {
     }
 
     // If no LLM available, fall back to empty (no deterministic fallback)
-    const llm = new FallbackLlmClient(options.gatewayConfig, {
-      workspaceDir: options.pluginConfig?.workspaceDir ?? options.workspaceDir,
-    });
+    const llm = options.llmClient ?? new FallbackLlmClient(
+      options.gatewayConfig,
+      options.pluginConfig
+        ? fallbackLlmRuntimeContextFromConfig(options.pluginConfig, {
+            workspaceDir: options.workspaceDir ?? options.pluginConfig.workspaceDir,
+          })
+        : { workspaceDir: options.workspaceDir },
+    );
     if (!llm.isAvailable(options.gatewayAgentId)) {
       log.debug("[cmc] no LLM available for consolidation — skipping");
       return [];

package/src/causal-retrieval.ts

@@ -8,7 +8,7 @@
  */
 
 import type { CausalTrajectoryRecord } from "./causal-trajectory.js";
-import { searchCausalTrajectories } from "./causal-trajectory.js";
+import { readCausalTrajectoryRecords, searchCausalTrajectories } from "./causal-trajectory.js";
 import {
   readChainIndex,
   resolveChainsDir,
@@ -158,6 +158,16 @@ function formatRetrievalResult(result: CausalRetrievalResult): string {
   return `- ${direction} ${result.summary}${edgeInfo}${counterfactual}`;
 }
 
+function formatConnectedTrajectorySummary(
+  trajectoryId: string,
+  depth: number,
+  trajectoriesById: Map<string, CausalTrajectoryRecord>,
+): string {
+  const record = trajectoriesById.get(trajectoryId);
+  if (!record) return `Depth ${depth}: trajectory ${trajectoryId.slice(0, 12)}`;
+  return `Depth ${depth}: [${record.outcomeKind}] ${record.goal} → ${record.outcomeSummary}`;
+}
+
 export function formatCausalRetrievalSection(
   results: CausalRetrievalResult[],
   maxChars: number,
@@ -220,6 +230,9 @@ export async function retrieveCausalChains(options: {
 
     if (Object.keys(chainIndex.edges).length === 0) return null;
 
+    const { trajectories } = await readCausalTrajectoryRecords({ memoryDir, causalTrajectoryStoreDir });
+    const trajectoriesById = new Map(trajectories.map((trajectory) => [trajectory.trajectoryId, trajectory]));
+
     // 3. Walk chains from each seed
     const allResults: CausalRetrievalResult[] = [];
 
@@ -250,7 +263,7 @@ export async function retrieveCausalChains(options: {
           edgeType: u.edgeType,
           edgeConfidence: u.edgeConfidence,
           isCounterfactual: u.isCounterfactual,
-          summary: `Depth ${u.depth}: trajectory ${u.trajectoryId.slice(0, 12)}`,
+          summary: formatConnectedTrajectorySummary(u.trajectoryId, u.depth, trajectoriesById),
         });
       }
 
@@ -270,7 +283,7 @@ export async function retrieveCausalChains(options: {
           edgeType: d.edgeType,
           edgeConfidence: d.edgeConfidence,
           isCounterfactual: d.isCounterfactual,
-          summary: `Depth ${d.depth}: trajectory ${d.trajectoryId.slice(0, 12)}`,
+          summary: formatConnectedTrajectorySummary(d.trajectoryId, d.depth, trajectoriesById),
         });
       }
     }

package/src/citations.test.ts

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { buildCitationGuidance, parseOaiMemCitation } from "./citations.js";
+
+function citationBlock(entries: string[]): string {
+  return [
+    "<oai-mem-citation>",
+    "<citation_entries>",
+    ...entries,
+    "</citation_entries>",
+    "<rollout_ids>",
+    "rollout-1",
+    "</rollout_ids>",
+    "</oai-mem-citation>",
+  ].join("\n");
+}
+
+test("parseOaiMemCitation skips zero-based and reversed line ranges", () => {
+  const parsed = parseOaiMemCitation(citationBlock([
+    "memory.md:0-1|note=[zero start]",
+    "memory.md:1-0|note=[zero end]",
+    "memory.md:10-1|note=[reversed]",
+    "memory.md:1-1|note=[single]",
+    "memory.md:1-5|note=[range]",
+  ]));
+
+  assert.deepEqual(
+    parsed?.entries.map((entry) => ({
+      path: entry.path,
+      lineStart: entry.lineStart,
+      lineEnd: entry.lineEnd,
+      note: entry.note,
+    })),
+    [
+      { path: "memory.md", lineStart: 1, lineEnd: 1, note: "single" },
+      { path: "memory.md", lineStart: 1, lineEnd: 5, note: "range" },
+    ],
+  );
+  assert.deepEqual(parsed?.rolloutIds, ["rollout-1"]);
+});
+
+test("buildCitationGuidance omits metadata with invalid line ranges", () => {
+  const guidance = buildCitationGuidance([
+    {
+      memoryId: "bad-zero",
+      path: "bad-zero.md",
+      lineStart: 0,
+      lineEnd: 1,
+      rolloutId: "bad-rollout",
+      noteDefault: "invalid",
+    },
+    {
+      memoryId: "bad-reversed",
+      path: "bad-reversed.md",
+      lineStart: 10,
+      lineEnd: 1,
+      noteDefault: "invalid",
+    },
+    {
+      memoryId: "good",
+      path: "good.md",
+      lineStart: 1,
+      lineEnd: 3,
+      rolloutId: "good-rollout",
+      noteDefault: "valid",
+    },
+  ]);
+
+  assert.match(guidance, /good\.md:1-3\|note=\[valid\]/);
+  assert.match(guidance, /good-rollout/);
+  assert.doesNotMatch(guidance, /bad-zero/);
+  assert.doesNotMatch(guidance, /bad-reversed/);
+  assert.doesNotMatch(guidance, /bad-rollout/);
+});