@remnic/core 10.0.4 → 10.0.6

package/src/access-cli.ts

@@ -207,6 +207,7 @@ function usage(): string {
     "Correct options (issue #1580 — one plan/apply pipeline for all corrections):",
     "  --text \"<correction>\"          plan a correction from natural language",
     "  --id <memoryId> (repeatable)   explicit target memory ids",
+    "  --duplicate-of <memoryId>      winner id; requires exactly one --id (skips the classifier)",
     "  --apply                        apply a pending plan (requires --plan-id + --confirm)",
     "  --plan-id <id>                 the plan to apply or discard",
     "  --confirm                      confirm the apply (safety guard, rule 48)",
@@ -297,6 +298,7 @@ const COMMAND_SPECS: Record<CommandName, CommandSpec> = {
     valueOptions: new Set([
       "text",
       "id",
+      "duplicate-of",
       "plan-id",
       "namespace",
       "session-key",
@@ -830,6 +832,7 @@ async function runCorrect(args: ParsedArgs, preferredId?: string): Promise<void>
   // so schema validation + namespace policy reach this path (same as MCP/HTTP).
   const text = requireOption(args, "text");
   const targetIds = getAllOptions(args, "id");
+  const duplicateOf = getLastOption(args, "duplicate-of");
   const planOp = getOperation("memory_correct_plan");
   if (!planOp) {
     throw new Error("access-boundary: operation not registered: memory_correct_plan");
@@ -838,6 +841,7 @@ async function runCorrect(args: ParsedArgs, preferredId?: string): Promise<void>
     {
       text,
       ...(targetIds.length > 0 ? { targetIds } : {}),
+      ...(duplicateOf ? { duplicateOf } : {}),
       ...(sessionKey ? { sessionKey } : {}),
       ...(namespace ? { namespace } : {}),
     },

package/src/access-http.ts

@@ -1999,6 +1999,7 @@ export class EngramAccessHttpServer extends ReviewDeckAccessHttpBase {
       const output = (await op.run(this.gatedBodyNamespace(req, body), {
         service: this.service,
         authenticatedPrincipal: this.resolveRequestPrincipal(req),
+        ...(abortSignal ? { abortSignal } : {}),
       })) as { result: unknown };
       this.recordWriteRateLimitHit(req);
       this.respondJson(res, 200, output.result);

package/src/access-mcp-correction-tools.ts

@@ -0,0 +1,56 @@
+/**
+ * Correction MCP tool descriptors.
+ *
+ * Extracted from access-mcp.ts (over its fileSizeGrandfather ceiling) so
+ * `duplicateOf` can land without growing that file. Aliases are applied by
+ * the caller via withToolAliases.
+ */
+import type { McpTool } from "./access-mcp.js";
+
+export const correctionMcpTools: McpTool[] = [
+  {
+    name: "engram.memory_correct_plan",
+    description:
+      "Plan a memory correction from a plain-language statement. Returns a CorrectionPlan with a diff preview; apply via memory_correct_apply. Pass duplicateOf plus one targetIds entry to supersede that duplicate without calling the classifier.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: {
+          type: "string",
+          description: 'The natural-language correction (e.g. "we migrated to MySQL in March").',
+        },
+        targetIds: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Optional explicit target memory ids. When omitted, the planner searches. With duplicateOf, pass exactly the duplicate id.",
+        },
+        duplicateOf: {
+          type: "string",
+          description:
+            "Optional winner memory id. Requires targetIds to be exactly the duplicate. Skips classification and drafts one recoverable supersede (no hard delete) linking the duplicate to this id.",
+        },
+        sessionKey: { type: "string", description: "Session identifier for namespace resolution." },
+        namespace: { type: "string", description: "Optional explicit namespace (validated by policy)." },
+      },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "engram.memory_correct_apply",
+    description:
+      "Apply a planned memory correction by planId. Requires confirm: true when correction.applyRequiresConfirm is on (default).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "The plan id returned by memory_correct_plan." },
+        confirm: { type: "boolean", description: "Must be true to apply (safety guard)." },
+        sessionKey: { type: "string", description: "Session identifier for namespace resolution." },
+        namespace: { type: "string", description: "Optional explicit namespace (validated by policy)." },
+      },
+      required: ["planId"],
+      additionalProperties: false,
+    },
+  },
+];

package/src/access-mcp.ts

@@ -1,4 +1,5 @@
 import { sharedContextMcpTools } from "./access-mcp-shared-context-tools.js";
+import { correctionMcpTools } from "./access-mcp-correction-tools.js";
 import { randomUUID } from "node:crypto";
 import {
   MCP_ADMIN_OPS_MIGRATED_OPERATIONS,
@@ -2133,56 +2134,10 @@ export class EngramMcpServer {
       this.tools = [...this.tools, ...deltaTools];
     }
     if (this.correctionVisible) {
-      // Correction Contract (issue #1580) — one plan/apply pipeline for every
-      // memory correction. Both tools dispatch through the boundary operations
-      // (memory_correct_plan / memory_correct_apply) which delegate to the
-      // CorrectionService.
-      const planTool = withToolAliases(
-        {
-          name: "engram.memory_correct_plan",
-          description:
-            "Plan a memory correction from a plain-language statement (issue #1580). Returns a CorrectionPlan with a diff preview; apply via memory_correct_apply.",
-          inputSchema: {
-            type: "object",
-            properties: {
-              text: {
-                type: "string",
-                description: 'The natural-language correction (e.g. "we migrated to MySQL in March").',
-              },
-              targetIds: {
-                type: "array",
-                items: { type: "string" },
-                description: "Optional explicit target memory ids. When omitted, the planner searches.",
-              },
-              sessionKey: { type: "string", description: "Session identifier for namespace resolution." },
-              namespace: { type: "string", description: "Optional explicit namespace (validated by policy)." },
-            },
-            required: ["text"],
-            additionalProperties: false,
-          },
-        },
-        this.emitLegacyTools
-      );
-      const applyTool = withToolAliases(
-        {
-          name: "engram.memory_correct_apply",
-          description:
-            "Apply a planned memory correction by planId (issue #1580). Requires confirm: true when correction.applyRequiresConfirm is on (default).",
-          inputSchema: {
-            type: "object",
-            properties: {
-              planId: { type: "string", description: "The plan id returned by memory_correct_plan." },
-              confirm: { type: "boolean", description: "Must be true to apply (safety guard, rule 48)." },
-              sessionKey: { type: "string", description: "Session identifier for namespace resolution." },
-              namespace: { type: "string", description: "Optional explicit namespace (validated by policy)." },
-            },
-            required: ["planId"],
-            additionalProperties: false,
-          },
-        },
-        this.emitLegacyTools
+      const correctionTools = correctionMcpTools.flatMap((tool) =>
+        withToolAliases(tool, this.emitLegacyTools),
       );
-      this.tools = [...this.tools, ...planTool, ...applyTool];
+      this.tools = [...this.tools, ...correctionTools];
     }
     if (this.chatVisible) {
       const chatTools = withToolAliases(

package/src/access-operations.ts

@@ -384,6 +384,7 @@ const memoryCorrectPlanSchema = z.preprocess(
   z.object({
     text: z.string().trim().min(1).max(10_000),
     targetIds: z.array(z.string().trim().min(1).max(512)).optional(),
+    duplicateOf: z.string().trim().min(1).max(512).optional(),
     sessionKey: z.string().trim().max(512).optional(),
     namespace: z.string().trim().max(256).optional(),
   }),
@@ -392,6 +393,7 @@ const memoryCorrectPlanSchema = z.preprocess(
 export interface MemoryCorrectPlanInput {
   text: string;
   targetIds?: string[];
+  duplicateOf?: string;
   sessionKey?: string;
   namespace?: string;
 }
@@ -414,6 +416,7 @@ export const memoryCorrectPlanOperation = defineOperation<
         {
           text: input.text,
           ...(input.targetIds ? { targetIds: input.targetIds } : {}),
+          ...(input.duplicateOf ? { duplicateOf: input.duplicateOf } : {}),
           ...(input.sessionKey ? { sessionKey: input.sessionKey } : {}),
           ...(input.namespace ? { namespace: input.namespace } : {}),
           ...(ctx.authenticatedPrincipal ? { principal: ctx.authenticatedPrincipal } : {}),

package/src/access-service.ts

@@ -3349,24 +3349,6 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
           return Promise.resolve(false);
         }
       },
-      // Wire the orchestrator's extraction LLM so classify+draft actually
-      // drafts actions instead of always hitting the deterministic fallback
-      // (review thread PG5). The planner's classifyAndDraft already falls back
-      // on any LLM outage, so returning null (LLM disabled/cooldown) or a
-      // thrown error both degrade safely to the deterministic path (rule 13).
-      llmComplete: async ({ system, user }) => {
-        const result = await this.orchestrator.localLlm.chatCompletion(
-          [
-            { role: "system", content: system },
-            { role: "user", content: user },
-          ],
-          { operation: "correction-classify", priority: "background" }
-        );
-        if (!result) {
-          throw new Error("correction classify+draft: local LLM unavailable (disabled or in cooldown)");
-        }
-        return result.content;
-      },
     });
     this._correctionService = service;
     return service;
@@ -3389,11 +3371,20 @@ export class EngramAccessService extends SupportPassportAccessServiceBase {
   }
 
   async correctionPlan(request: CorrectionRequest, opts?: { abortSignal?: AbortSignal }): Promise<CorrectionPlan> {
+    let next = request;
     if (request.targetIds?.some((id) => isHandleToken(id))) {
-      const targetIds = request.targetIds.map((id) => this.resolveMemoryIdOrHandleInput(id, request.sessionKey));
-      return this.correctionService().plan({ ...request, targetIds }, opts);
+      next = {
+        ...next,
+        targetIds: request.targetIds.map((id) => this.resolveMemoryIdOrHandleInput(id, request.sessionKey)),
+      };
+    }
+    if (request.duplicateOf && isHandleToken(request.duplicateOf)) {
+      next = {
+        ...next,
+        duplicateOf: this.resolveMemoryIdOrHandleInput(request.duplicateOf, request.sessionKey),
+      };
     }
-    return this.correctionService().plan(request, opts);
+    return this.correctionService().plan(next, opts);
   }
 
   async correctionApply(

package/src/calibration-local-llm.test.ts

@@ -0,0 +1,361 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { calibrationConsolidationInput, readCalibrationIndex, runCalibrationConsolidation } from "./calibration.js";
+import { parseConfig } from "./config.js";
+import { type LoggerBackend, initLogger, resetLogger } from "./logger.js";
+import type { GatewayConfig } from "./types.js";
+
+/**
+ * Gateway-less calibration (standalone daemon): no gateway model chain, so
+ * consolidation must call the configured local LLM and surface skips above
+ * debug. These tests drive the real LocalLlmClient against a loopback stub.
+ */
+
+interface CapturedRequest {
+  method: string;
+  path: string;
+  body: string;
+  headers: http.IncomingHttpHeaders;
+}
+
+interface StubServer {
+  url: string;
+  requests: CapturedRequest[];
+  close(): Promise<void>;
+}
+
+function startServer(handle: (req: CapturedRequest, res: http.ServerResponse) => void): Promise<StubServer> {
+  const requests: CapturedRequest[] = [];
+  const server = http.createServer((req, res) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => {
+      const captured: CapturedRequest = {
+        method: req.method ?? "",
+        path: req.url ?? "",
+        body: Buffer.concat(chunks).toString("utf8"),
+        headers: req.headers,
+      };
+      requests.push(captured);
+      handle(captured, res);
+    });
+  });
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address() as AddressInfo;
+      resolve({
+        url: `http://127.0.0.1:${port}/v1`,
+        requests,
+        close: () => new Promise((done) => server.close(() => done())),
+      });
+    });
+  });
+}
+
+function json(res: http.ServerResponse, body: unknown): void {
+  res.writeHead(200, { "content-type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+function ruleJson(condition: string): string {
+  return JSON.stringify({
+    rules: [
+      {
+        ruleType: "scope_boundary",
+        condition,
+        modelTendency: "It expands the task",
+        userExpectation: "Stay inside the request",
+        calibration: "Ask before widening the task.",
+        confidence: 0.8,
+        evidenceIds: ["correction-1", "correction-2"],
+      },
+    ],
+  });
+}
+
+function chatCompletionBody(content: string): unknown {
+  return { choices: [{ message: { content } }] };
+}
+
+async function writeCorrections(memoryDir: string, count: number): Promise<void> {
+  const dir = path.join(memoryDir, "corrections");
+  await mkdir(dir, { recursive: true });
+  for (let i = 1; i <= count; i += 1) {
+    const body = [
+      "---",
+      `id: correction-${i}`,
+      "confidence: 0.9",
+      "---",
+      "",
+      `Correction ${i}: the model assumed a broader scope than the user stated for task ${i}.`,
+      "",
+    ].join("\n");
+    await writeFile(path.join(dir, `correction-${i}.md`), body, "utf8");
+  }
+}
+
+function captureLogs(debug = true): { lines: Array<{ level: string; msg: string }> } {
+  const lines: Array<{ level: string; msg: string }> = [];
+  const backend: LoggerBackend = {
+    info(msg) {
+      lines.push({ level: "info", msg: String(msg) });
+    },
+    warn(msg) {
+      lines.push({ level: "warn", msg: String(msg) });
+    },
+    error(msg) {
+      lines.push({ level: "error", msg: String(msg) });
+    },
+    debug(msg) {
+      lines.push({ level: "debug", msg: String(msg) });
+    },
+  };
+  initLogger(backend, debug);
+  return { lines };
+}
+
+function gatewayConfig(baseUrl: string): GatewayConfig {
+  return {
+    agents: { defaults: { model: { primary: "stub/calibration-gateway" } } },
+    models: {
+      providers: {
+        stub: {
+          baseUrl,
+          api: "openai-completions",
+          apiKey: "gateway-test-key",
+          models: [],
+        },
+      },
+    },
+  };
+}
+
+test.describe("gateway-less calibration", { concurrency: false }, () => {
+  test("plugin mode supplies localLlm settings and leaves the gateway chain unset", () => {
+    const config = parseConfig({
+      memoryDir: "/tmp/remnic-cal-plugin",
+      modelSource: "plugin",
+      localLlmEnabled: true,
+      localLlmModel: "daemon-calibration-model",
+      gatewayAgentId: "ignored-in-plugin-mode",
+      taskModelChain: { primary: "stub/ignored" },
+    });
+    const input = calibrationConsolidationInput(config);
+    assert.equal(input.pluginConfig, config);
+    assert.equal(input.pluginConfig.localLlmModel, "daemon-calibration-model");
+    assert.equal(input.pluginConfig.localLlmEnabled, true);
+    assert.equal(input.gatewayAgentId, undefined);
+    assert.equal(input.modelChain, undefined);
+    assert.equal(input.gatewayConfig, undefined);
+  });
+
+  test("gateway mode keeps the agent and task chain on the calibration input", () => {
+    const config = parseConfig({
+      memoryDir: "/tmp/remnic-cal-gateway-input",
+      modelSource: "gateway",
+      gatewayAgentId: "agent-a",
+      taskModelChain: { primary: "stub/calibration-gateway" },
+    });
+    const input = calibrationConsolidationInput(config);
+    assert.equal(input.gatewayAgentId, "agent-a");
+    assert.deepEqual(input.modelChain, { primary: "stub/calibration-gateway" });
+    assert.equal(input.pluginConfig, config);
+  });
+
+  test("uses the daemon localLlm* settings when no gateway model chain exists", async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cal-local-"));
+    const logs = captureLogs();
+    const server = await startServer((req, res) => {
+      if (req.method === "GET" && req.path === "/") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("Ollama is running");
+        return;
+      }
+      if (req.method === "POST" && req.path === "/v1/chat/completions") {
+        json(res, chatCompletionBody(ruleJson("When the daemon has no gateway chain")));
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+    try {
+      await writeCorrections(memoryDir, 3);
+      const pluginConfig = parseConfig({
+        memoryDir,
+        modelSource: "plugin",
+        localLlmEnabled: true,
+        localLlmUrl: server.url,
+        localLlmModel: "daemon-calibration-model",
+        localLlmHeaders: { "X-Remnic-Local": "calibration" },
+        localLlmApiKey: "local-test-key",
+        localLlmAuthHeader: true,
+      });
+      const rules = await runCalibrationConsolidation({
+        memoryDir,
+        workspaceDir: memoryDir,
+        pluginConfig,
+      });
+
+      assert.equal(rules.length, 1);
+      assert.equal(rules[0]?.condition, "When the daemon has no gateway chain");
+      const stored = await readCalibrationIndex(memoryDir);
+      assert.equal(stored.rules.length, 1);
+      assert.equal(stored.totalCorrectionsAnalyzed, 3);
+
+      const completion = server.requests.find((req) => req.method === "POST" && req.path === "/v1/chat/completions");
+      assert.ok(completion, "local LLM chat completion was not called");
+      const body = JSON.parse(completion.body) as { model?: string };
+      assert.equal(body.model, "daemon-calibration-model");
+      assert.equal(completion.headers["x-remnic-local"], "calibration");
+      assert.equal(completion.headers.authorization, "Bearer local-test-key");
+      assert.ok(
+        logs.lines.some((line) => line.level === "info" && line.msg.includes("model=daemon-calibration-model"))
+      );
+      assert.equal(
+        logs.lines.some((line) => line.msg.includes("no LLM available")),
+        false
+      );
+    } finally {
+      resetLogger();
+      await server.close();
+      await rm(memoryDir, { recursive: true, force: true });
+    }
+  });
+
+  test("warns and skips when neither a gateway chain nor a local LLM is configured", async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cal-skip-"));
+    const logs = captureLogs(true);
+    try {
+      await writeCorrections(memoryDir, 3);
+      const pluginConfig = parseConfig({
+        memoryDir,
+        modelSource: "plugin",
+        localLlmEnabled: false,
+      });
+      const rules = await runCalibrationConsolidation({
+        memoryDir,
+        workspaceDir: memoryDir,
+        pluginConfig,
+      });
+      assert.deepEqual(rules, []);
+      const stored = await readCalibrationIndex(memoryDir);
+      assert.equal(stored.rules.length, 0);
+      assert.ok(logs.lines.some((line) => line.level === "warn" && line.msg.includes("no LLM available")));
+      assert.equal(
+        logs.lines.some((line) => line.level === "debug" && line.msg.includes("no LLM available")),
+        false
+      );
+    } finally {
+      resetLogger();
+      await rm(memoryDir, { recursive: true, force: true });
+    }
+  });
+
+  test("logs a short correction set at info", async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cal-few-"));
+    const logs = captureLogs(true);
+    const server = await startServer((req, res) => {
+      if (req.method === "GET" && req.path === "/") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("Ollama is running");
+        return;
+      }
+      res.writeHead(500);
+      res.end();
+    });
+    try {
+      await writeCorrections(memoryDir, 1);
+      const pluginConfig = parseConfig({
+        memoryDir,
+        modelSource: "plugin",
+        localLlmEnabled: true,
+        localLlmUrl: server.url,
+        localLlmModel: "daemon-calibration-model",
+      });
+      const rules = await runCalibrationConsolidation({
+        memoryDir,
+        workspaceDir: memoryDir,
+        pluginConfig,
+      });
+      assert.deepEqual(rules, []);
+      assert.equal(
+        server.requests.some((req) => req.method === "POST"),
+        false,
+        "synthesis must not call the LLM before the correction minimum"
+      );
+      assert.ok(logs.lines.some((line) => line.level === "info" && line.msg.includes("need at least 3")));
+      assert.equal(
+        logs.lines.some((line) => line.level === "debug" && line.msg.includes("need at least 3")),
+        false
+      );
+    } finally {
+      resetLogger();
+      await server.close();
+      await rm(memoryDir, { recursive: true, force: true });
+    }
+  });
+
+  test("keeps the gateway chain when one is configured", async () => {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-cal-gateway-"));
+    const logs = captureLogs();
+    const local = await startServer((req, res) => {
+      if (req.method === "GET" && req.path === "/") {
+        res.writeHead(200, { "content-type": "text/plain" });
+        res.end("Ollama is running");
+        return;
+      }
+      if (req.method === "POST") {
+        json(res, chatCompletionBody(ruleJson("When the local model was used by mistake")));
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+    const gateway = await startServer((req, res) => {
+      if (req.method === "POST" && req.path === "/v1/chat/completions") {
+        json(res, chatCompletionBody(ruleJson("When the gateway chain is present")));
+        return;
+      }
+      res.writeHead(404);
+      res.end();
+    });
+    try {
+      await writeCorrections(memoryDir, 3);
+      const pluginConfig = parseConfig({
+        memoryDir,
+        modelSource: "plugin",
+        localLlmEnabled: true,
+        localLlmUrl: local.url,
+        localLlmModel: "daemon-calibration-model",
+      });
+      const rules = await runCalibrationConsolidation({
+        memoryDir,
+        workspaceDir: memoryDir,
+        gatewayConfig: gatewayConfig(gateway.url),
+        pluginConfig,
+      });
+      assert.equal(rules.length, 1);
+      assert.equal(rules[0]?.condition, "When the gateway chain is present");
+      assert.equal(local.requests.length, 0);
+      assert.equal(
+        gateway.requests.filter((req) => req.method === "POST" && req.path === "/v1/chat/completions").length,
+        1
+      );
+      assert.equal(
+        logs.lines.some((line) => line.msg.includes("using configured local LLM")),
+        false
+      );
+    } finally {
+      resetLogger();
+      await local.close();
+      await gateway.close();
+      await rm(memoryDir, { recursive: true, force: true });
+    }
+  });
+});