@remnic/core 10.0.4 → 10.0.6

package/src/calibration.ts

@@ -13,14 +13,15 @@
  */
 
 import { createHash } from "node:crypto";
-import path from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { resolveLocalLlmCapabilities } from "./capabilities.js";
+import { OUTPUT_LANGUAGE_POLICY } from "./extraction-prompt.js";
 import { FallbackLlmClient } from "./fallback-llm.js";
-import type { AgentPersonaModelConfig, GatewayConfig, MemoryFile } from "./types.js";
-import { listJsonFiles, readJsonFile } from "./json-store.js";
-import { isRecord } from "./store-contract.js";
+import { listJsonFiles } from "./json-store.js";
+import { LocalLlmClient } from "./local-llm.js";
 import { log } from "./logger.js";
-import { OUTPUT_LANGUAGE_POLICY } from "./extraction-prompt.js";
+import type { AgentPersonaModelConfig, GatewayConfig, PluginConfig } from "./types.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -223,12 +224,57 @@ Output valid JSON only:
   ]
 }`;
 
+interface CalibrationChatClient {
+  chatCompletion(
+    messages: Array<{ role: "system" | "user" | "assistant"; content: string }>,
+    options?: {
+      temperature?: number;
+      maxTokens?: number;
+      agentId?: string;
+      modelChain?: AgentPersonaModelConfig;
+    }
+  ): Promise<{ content?: string | null } | null>;
+}
+
+interface CalibrationLlmOptions {
+  gatewayConfig?: GatewayConfig;
+  gatewayAgentId?: string;
+  modelChain?: AgentPersonaModelConfig;
+  workspaceDir?: string;
+  /** Plugin config. Supplies `localLlm*` settings when the gateway chain is empty. */
+  pluginConfig?: PluginConfig;
+}
+
+function resolveCalibrationChatClient(options: CalibrationLlmOptions): CalibrationChatClient | null {
+  const gateway = new FallbackLlmClient(options.gatewayConfig, {
+    workspaceDir: options.workspaceDir,
+  });
+  if (gateway.isAvailable({ agentId: options.gatewayAgentId, modelChain: options.modelChain })) {
+    return gateway;
+  }
+  const pluginConfig = options.pluginConfig;
+  if (pluginConfig && resolveLocalLlmCapabilities(pluginConfig).localLlm) {
+    log.info(`[calibration] using configured local LLM (model=${pluginConfig.localLlmModel})`);
+    const local = new LocalLlmClient(pluginConfig);
+    return {
+      chatCompletion(messages, chatOptions) {
+        return local.chatCompletion(messages, {
+          temperature: chatOptions?.temperature,
+          maxTokens: chatOptions?.maxTokens,
+        });
+      },
+    };
+  }
+  log.warn("[calibration] no LLM available — skipping consolidation");
+  return null;
+}
+
 export async function synthesizeCalibrationRules(
   corrections: CorrectionMemory[],
-  llm: FallbackLlmClient,
+  llm: CalibrationChatClient,
   existingRules: CalibrationRule[],
   agentId?: string,
-  modelChain?: AgentPersonaModelConfig,
+  modelChain?: AgentPersonaModelConfig
 ): Promise<CalibrationRule[]> {
   if (corrections.length < 2) return [];
 
@@ -238,16 +284,20 @@ export async function synthesizeCalibrationRules(
     .map((c, i) => `[${c.id}] ${c.content}`)
     .join("\n\n");
 
-  const existingRulesText = existingRules.length > 0
-    ? `\n\nExisting calibration rules (avoid duplicating these):\n${existingRules.map((r) => `- ${r.condition}: ${r.calibration}`).join("\n")}`
-    : "";
+  const existingRulesText =
+    existingRules.length > 0
+      ? `\n\nExisting calibration rules (avoid duplicating these):\n${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:\n\n${correctionText}${existingRulesText}` },
+      {
+        role: "user",
+        content: `Here are ${corrections.length} corrections from this user:\n\n${correctionText}${existingRulesText}`,
+      },
     ],
-    { temperature: 0.3, maxTokens: 3000, agentId, modelChain },
+    { temperature: 0.3, maxTokens: 3000, agentId, modelChain }
   );
 
   if (!response?.content) return [];
@@ -283,7 +333,10 @@ export async function synthesizeCalibrationRules(
         }
         const evidenceCorrectionIds = parseEvidenceIds(raw.evidenceIds);
         return {
-          id: `cal-${createHash("sha256").update(condition + calibration).digest("hex").slice(0, 12)}`,
+          id: `cal-${createHash("sha256")
+            .update(condition + calibration)
+            .digest("hex")
+            .slice(0, 12)}`,
           ruleType: ruleType as CalibrationRule["ruleType"],
           condition,
           modelTendency,
@@ -292,8 +345,8 @@ export async function synthesizeCalibrationRules(
           confidence,
           evidenceCount: evidenceCorrectionIds.length,
           evidenceCorrectionIds,
-        createdAt: now,
-        lastReinforcedAt: now,
+          createdAt: now,
+          lastReinforcedAt: now,
         };
       })
       .filter((rule): rule is CalibrationRule => !!rule);
@@ -341,6 +394,30 @@ export function buildCalibrationRecallSection(
 
 // ─── Public API ──────────────────────────────────────────────────────────────
 
+/**
+ * Options weekly compounding passes into calibration. Gateway agent and task
+ * chain fields stay limited to `modelSource: "gateway"`. `pluginConfig` carries
+ * the `localLlm*` settings used when that chain is empty.
+ */
+export function calibrationConsolidationInput(config: PluginConfig): {
+  memoryDir: string;
+  gatewayConfig?: GatewayConfig;
+  gatewayAgentId?: string;
+  modelChain?: AgentPersonaModelConfig;
+  workspaceDir?: string;
+  pluginConfig: PluginConfig;
+} {
+  const gateway = config.modelSource === "gateway";
+  return {
+    memoryDir: config.memoryDir,
+    gatewayConfig: config.gatewayConfig,
+    gatewayAgentId: gateway ? (config.gatewayAgentId || undefined) : undefined,
+    modelChain: gateway ? config.taskModelChain : undefined,
+    workspaceDir: config.workspaceDir,
+    pluginConfig: config,
+  };
+}
+
 /**
  * Run the full calibration pipeline:
  * 1. Read all corrections
@@ -354,27 +431,29 @@ export async function runCalibrationConsolidation(options: {
   gatewayAgentId?: string;
   modelChain?: AgentPersonaModelConfig;
   workspaceDir?: string;
+  pluginConfig?: PluginConfig;
 }): Promise<CalibrationRule[]> {
   try {
-    const llm = new FallbackLlmClient(options.gatewayConfig, {
-      workspaceDir: options.workspaceDir,
-    });
-    if (!llm.isAvailable({ agentId: options.gatewayAgentId, modelChain: options.modelChain })) {
-      log.debug("[calibration] no LLM available — skipping consolidation");
-      return [];
-    }
+    const llm = resolveCalibrationChatClient(options);
+    if (!llm) return [];
 
     const corrections = await readCorrections(options.memoryDir);
     if (corrections.length < 3) {
-      log.debug(`[calibration] only ${corrections.length} corrections — need at least 3`);
+      log.info(`[calibration] only ${corrections.length} corrections — need at least 3`);
       return [];
     }
 
     const existingIndex = await readCalibrationIndex(options.memoryDir);
 
-    const newRules = await synthesizeCalibrationRules(corrections, llm, existingIndex.rules, options.gatewayAgentId, options.modelChain);
+    const newRules = await synthesizeCalibrationRules(
+      corrections,
+      llm,
+      existingIndex.rules,
+      options.gatewayAgentId,
+      options.modelChain
+    );
     if (newRules.length === 0) {
-      log.debug("[calibration] no new calibration rules synthesized");
+      log.info("[calibration] no new calibration rules synthesized");
       return existingIndex.rules;
     }
 
@@ -402,7 +481,9 @@ export async function runCalibrationConsolidation(options: {
     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)}`);
+    log.warn(
+      `[calibration] consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`
+    );
     return [];
   }
 }
@@ -421,6 +502,7 @@ export async function runCalibrationIfEnabled(options: {
   gatewayAgentId?: string;
   modelChain?: AgentPersonaModelConfig;
   workspaceDir?: string;
+  pluginConfig?: PluginConfig;
 }): Promise<CalibrationRule[]> {
   if (!options.calibrationEnabled) {
     return [];
@@ -431,6 +513,7 @@ export async function runCalibrationIfEnabled(options: {
     gatewayAgentId: options.gatewayAgentId,
     modelChain: options.modelChain,
     workspaceDir: options.workspaceDir,
+    pluginConfig: options.pluginConfig,
   });
 }
 

package/src/compounding/engine.ts

@@ -552,14 +552,8 @@ export class CompoundingEngine {
     // PEDC: Run calibration consolidation during weekly synthesis
     if (resolveConsolidationCapabilities(this.config).calibration) {
       try {
-        const { runCalibrationConsolidation } = await import("../calibration.js");
-        const calRules = await runCalibrationConsolidation({
-          memoryDir: this.config.memoryDir,
-          gatewayConfig: this.config.gatewayConfig,
-          gatewayAgentId: this.config.modelSource === "gateway" ? (this.config.gatewayAgentId || undefined) : undefined,
-          modelChain: this.config.modelSource === "gateway" ? this.config.taskModelChain : undefined,
-          workspaceDir: this.config.workspaceDir,
-        });
+        const { calibrationConsolidationInput, runCalibrationConsolidation } = await import("../calibration.js");
+        const calRules = await runCalibrationConsolidation(calibrationConsolidationInput(this.config));
         log.debug(`[calibration] weekly synthesis produced ${calRules.length} calibration rule(s)`);
       } catch (error) {
         log.warn(`[calibration] weekly consolidation failed (non-fatal): ${error instanceof Error ? error.message : String(error)}`);

package/src/config.test.ts

@@ -2463,6 +2463,32 @@ test("parseConfig rejects invalid correction.planTtlHours instead of silently de
   assert.equal(parseConfig({}).correctionPlanTtlHours, 24, "absent → documented default");
 });
 
+test("parseConfig correction.classifyTimeoutMs defaults to 45000 and rejects invalid values", () => {
+  assert.equal(parseConfig({}).correctionClassifyTimeoutMs, 45_000);
+  assert.equal(parseConfig({ correction: { classifyTimeoutMs: 12000 } }).correctionClassifyTimeoutMs, 12_000);
+  assert.equal(
+    parseConfig({
+      correction: { classifyTimeoutMs: 8000 },
+      correctionClassifyTimeoutMs: 1000,
+    }).correctionClassifyTimeoutMs,
+    8000,
+    "nested correction.classifyTimeoutMs wins",
+  );
+  assert.equal(parseConfig({ correctionClassifyTimeoutMs: 15000 }).correctionClassifyTimeoutMs, 15_000);
+  for (const value of [0, -1, 3.7, "abc", 300_001, true]) {
+    assert.throws(
+      () => parseConfig({ correctionClassifyTimeoutMs: value } as Record<string, unknown>),
+      /Invalid correction\.classifyTimeoutMs/,
+      `correctionClassifyTimeoutMs=${JSON.stringify(value)} should throw`,
+    );
+    assert.throws(
+      () => parseConfig({ correction: { classifyTimeoutMs: value } } as Record<string, unknown>),
+      /Invalid correction\.classifyTimeoutMs/,
+      `nested classifyTimeoutMs=${JSON.stringify(value)} should throw`,
+    );
+  }
+});
+
 test("parseConfig correction.maxAffected rejects non-integers (Number.isInteger, #1678)", () => {
   // The error message says "integer" — 3.7 must be rejected, not silently floored to 3.
   for (const value of [3.7, 2.5, "1.5", 0.99]) {

package/src/config.ts

@@ -28,6 +28,7 @@ import type {
 import { parseBackgroundGeneration } from "./background-generation-config.js";
 import { parseSearchBackend } from "./config-search-backend.js";
 import { parseLocalLlmConfig } from "./local-llm-config.js";
+import { parseCorrectionConfig } from "./correction/correction-config.js";
 import { parseConvergeConfig } from "./converge-config.js";
 import { parseExternalWikiRecallGuard } from "./external-wiki-guard.js";
 import { log } from "./logger.js";
@@ -1855,66 +1856,9 @@ export function parseConfig(
     // (docs kept honest — review: wire resolver before exposing the gate).
     temporalBiTemporal: coerceBool(cfg.temporalBiTemporal) ?? false,
     temporalExpiredInInjection: coerceBool(cfg.temporalExpiredInInjection) ?? false,
-    // Correction Contract (issue #1580). Parsed here so operators can actually
-    // set the documented toggles/limits (review thread Txp): parseConfig builds
-    // an explicit output, so without these lines the raw `correction` block /
-    // flat legacy keys are dropped and the runtime always sees defaults. Nested
-    // `correction.<key>` wins; flat `correction<Key>` is the legacy fallback.
-    correctionEnabled: (() => {
-      const nested = (cfg.correction as Record<string, unknown> | undefined)?.enabled;
-      const raw = nested !== undefined ? nested : cfg.correctionEnabled;
-      if (raw === undefined || raw === null) return true;
-      const v = coerceBool(raw);
-      if (v === undefined) {
-        throw new Error(`Invalid correction.enabled: expected a boolean, got ${JSON.stringify(raw)}`);
-      }
-      return v;
-    })(),
-    correctionApplyRequiresConfirm: (() => {
-      const nested = (cfg.correction as Record<string, unknown> | undefined)?.applyRequiresConfirm;
-      const raw = nested !== undefined ? nested : cfg.correctionApplyRequiresConfirm;
-      if (raw === undefined || raw === null) return true;
-      const v = coerceBool(raw);
-      if (v === undefined) {
-        throw new Error(`Invalid correction.applyRequiresConfirm: expected a boolean, got ${JSON.stringify(raw)}`);
-      }
-      return v;
-    })(),
-    correctionMaxAffected: (() => {
-      const rawNested = (cfg.correction as Record<string, unknown> | undefined)?.maxAffected;
-      const raw = rawNested !== undefined ? rawNested : cfg.correctionMaxAffected;
-      if (raw === undefined || raw === null) return 10;
-      const n = coerceNumber(raw);
-      // #1678 (thread Oiup6): the error message says "integer" — enforce it
-      // with Number.isInteger so 3.7 is rejected rather than silently floored.
-      if (n === undefined || !Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
-        throw new Error(`Invalid correction.maxAffected: expected an integer >= 1, got ${JSON.stringify(raw)}`);
-      }
-      return n;
-    })(),
-    correctionPlanTtlHours: (() => {
-      const nested = (cfg.correction as Record<string, unknown> | undefined)?.planTtlHours;
-      const fromNested = nested !== undefined ? coerceNumber(nested) : undefined;
-      if (fromNested !== undefined && fromNested >= 1) return fromNested;
-      // #1678 (threads Ohtvi/Ohyvf): reject invalid (0/negative/non-numeric)
-      // instead of silently defaulting to 24h — completes the config-reject
-      // class already enforced for enabled/applyRequiresConfirm/maxAffected.
-      if (nested !== undefined && fromNested === undefined) {
-        throw new Error(`Invalid correction.planTtlHours: expected a number >= 1, got ${JSON.stringify(nested)}`);
-      }
-      if (fromNested !== undefined && fromNested < 1) {
-        throw new Error(`Invalid correction.planTtlHours: expected a number >= 1, got ${JSON.stringify(nested)}`);
-      }
-      const fromFlat = coerceNumber(cfg.correctionPlanTtlHours);
-      if (fromFlat !== undefined && fromFlat >= 1) return fromFlat;
-      if (cfg.correctionPlanTtlHours !== undefined && fromFlat === undefined) {
-        throw new Error(`Invalid correction.planTtlHours: expected a number >= 1, got ${JSON.stringify(cfg.correctionPlanTtlHours)}`);
-      }
-      if (fromFlat !== undefined && fromFlat < 1) {
-        throw new Error(`Invalid correction.planTtlHours: expected a number >= 1, got ${JSON.stringify(cfg.correctionPlanTtlHours)}`);
-      }
-      return 24;
-    })(),
+    // Correction Contract (#1580). Nested `correction.<key>` wins over flat
+    // `correction<Key>`. Parser lives in correction/correction-config.ts.
+    ...parseCorrectionConfig(cfg),
     // Passive correction capture (issue #1581). Parsed from
     // `correctionCapture.<key>` (nested) or flat legacy keys. Default "off" —
     // operators opt in (rule 48). Invalid mode → rejected listing options (rule 51).

package/src/correction/correction-access-wiring.ts

@@ -21,7 +21,7 @@
  */
 
 import path from "node:path";
-import { throwIfAborted } from "../abort-error.js";
+import { abortError, isAbortError, throwIfAborted } from "../abort-error.js";
 import { composeMemoryEnvelope, isMemoryCategory } from "../write-envelope.js";
 import { log } from "../logger.js";
 import { createHash } from "node:crypto";
@@ -48,6 +48,7 @@ import {
 } from "./correction-planner.js";
 import { type ExecutorDeps, type ExecutorMemory } from "./correction-executor.js";
 import { CorrectionService, type CorrectionServiceDeps } from "./correction-service.js";
+import { completeCorrectionClassify } from "./correction-classify.js";
 import { resolveRecallAuxiliaryCapabilities } from "../capabilities.js";
 import { isSupportPassportPrivateMemory } from "../support-passport/card-projection.js";
 
@@ -81,15 +82,15 @@ export interface CorrectionAccessWiring {
     principal?: string;
   }): Promise<boolean>;
   /**
-   * Optional LLM-complete callback (Responses API only — gotcha 1). When
-   * absent, the planner's classify+draft step falls back to deterministic
-   * mode (rule 13). The access-service wires the orchestrator's extraction
-   * LLM here once it exposes a public accessor; until then the contract
-   * ships with the safe fallback.
+   * Optional test override for classify+draft. Production leaves this unset
+   * and uses completeCorrectionClassify: a short per-attempt timeout, caller
+   * abort, then the gateway/fallback model. A caller abort propagates; every
+   * other failure becomes the deterministic empty-action plan.
    */
   llmComplete?(request: {
     system: string;
     user: string;
+    abortSignal?: AbortSignal;
   }): Promise<string>;
 }
 
@@ -144,10 +145,12 @@ function makePlannerDeps(
       searchMemories(wiring, text, namespaces, limit),
     resolveTargets: async ({ targetIds, namespaces }) =>
       resolveTargetMemories(wiring, targetIds, namespaces),
+    inspectMemory: async ({ memoryId, namespaces }) =>
+      inspectCorrectionMemory(wiring, memoryId, namespaces),
     expandNeighbors: async ({ seedIds, namespaces, limit }) =>
       expandEntityNeighbors(wiring, seedIds, namespaces, limit),
-    classifyAndDraft: async ({ text, candidates }) =>
-      classifyAndDraft(wiring, text, candidates),
+    classifyAndDraft: async ({ text, candidates, abortSignal }) =>
+      classifyAndDraft(wiring, text, candidates, abortSignal),
     renderDiff: async ({ candidates, actions }) =>
       renderCorrectionDiff(wiring, candidates, actions),
     storageDir: async (namespace) => (await wiring.orchestrator.getStorage(namespace)).dir,
@@ -294,22 +297,54 @@ async function classifyAndDraft(
   wiring: CorrectionAccessWiring,
   text: string,
   candidates: PlannerCandidate[],
+  abortSignal?: AbortSignal,
 ): Promise<LlmClassificationResult> {
-  // Route through the injected LLM callback (Responses API only — gotcha 1).
-  // On any failure (or when no callback is wired), return the deterministic
-  // fallback (rule 13) — the planner never throws on an LLM outage.
+  // Injected llmComplete stays as a test override. Production uses
+  // completeCorrectionClassify: short timeout, caller abort, gateway fallback.
+  // Abort throws. Every other failure is the deterministic empty-action plan.
   try {
-    if (!wiring.llmComplete) {
-      return fallbackClassification(candidates, "no LLM client available");
-    }
+    throwIfAborted(abortSignal, "correction classify aborted");
     const user = buildClassifyPrompt(text, candidates);
-    const raw = await wiring.llmComplete({ system: CLASSIFY_SYSTEM_PROMPT, user });
+    const raw = wiring.llmComplete
+      ? await wiring.llmComplete({ system: CLASSIFY_SYSTEM_PROMPT, user, abortSignal })
+      : await completeCorrectionClassify(
+          [
+            { role: "system", content: CLASSIFY_SYSTEM_PROMPT },
+            { role: "user", content: user },
+          ],
+          { config: wiring.orchestrator.config, localLlm: wiring.orchestrator.localLlm },
+          abortSignal,
+        );
+    if (raw == null) return fallbackClassification(candidates, "correction classify unavailable");
+    throwIfAborted(abortSignal, "correction classify aborted");
     return parseClassifyResponse(raw, candidates);
   } catch (err) {
+    if (isAbortError(err) || abortSignal?.aborted) {
+      throw isAbortError(err) ? err : abortError("correction classify aborted");
+    }
     return fallbackClassification(candidates, `LLM unavailable: ${errMsg(err)}`);
   }
 }
 
+async function inspectCorrectionMemory(
+  wiring: CorrectionAccessWiring,
+  memoryId: string,
+  namespaces: readonly string[],
+): Promise<{ candidate: PlannerCandidate; status: string } | null> {
+  for (const ns of namespaces) {
+    const storage = await wiring.orchestrator.getStorage(ns);
+    const memory = await storage.getMemoryByIdIncludingArchived(memoryId);
+    if (!memory || memory.frontmatter.id !== memoryId) continue;
+    const candidate = toCandidate(memory, ns, 1);
+    if (isSupportPassportPrivateMemory(memory)) return { candidate, status: "ineligible" };
+    if (typeof memory.frontmatter.archivedAt === "string" && memory.frontmatter.archivedAt.length > 0) {
+      return { candidate, status: "archived" };
+    }
+    return { candidate, status: memory.frontmatter.status ?? "active" };
+  }
+  return null;
+}
+
 async function renderCorrectionDiff(
   _wiring: CorrectionAccessWiring,
   candidates: PlannerCandidate[],
@@ -339,7 +374,10 @@ async function renderCorrectionDiff(
 function describeAfterState(action: CorrectionAction): string {
   switch (action.kind) {
     case "supersede":
-      return action.replacement?.content ?? "(superseded without replacement)";
+      return action.replacement?.content
+        ?? (action.winnerId
+          ? `(superseded by ${action.winnerId}; recoverable)`
+          : "(superseded without replacement)");
     case "edit":
       return action.patch;
     case "retract":
@@ -899,6 +937,7 @@ function toExecutorMemory(m: MemoryFile): ExecutorMemory {
     ...(typeof fm.contentHash === "string" && fm.contentHash.length > 0
       ? { contentHash: fm.contentHash }
       : {}),
+    status: fm.status ?? "active",
   } satisfies ExecutorMemory;
 }
 
@@ -987,6 +1026,7 @@ Given a correction statement and candidate memories, respond with a JSON object:
 
 Action shapes:
 - {"kind":"supersede","loserId":"<id>","replacement":{"content":"<new fact>"}}
+- {"kind":"supersede","loserId":"<id>","winnerId":"<existing id>"}
 - {"kind":"edit","memoryId":"<id>","patch":"<new full content>"}
 - {"kind":"retract","memoryId":"<id>"}
 - {"kind":"rescope","memoryId":"<id>","toNamespace":"<ns>"}