@remnic/core 10.0.4 → 10.0.5

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/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>"}