@remnic/core 10.0.3 → 10.0.5

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

package/src/correction/correction-classify.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Correction classify completion: short timeout, caller abort, gateway fallback.
+ */
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+
+import { isAbortError } from "../abort-error.js";
+import type { PluginConfig } from "../types.js";
+import { type CorrectionClassifyDeps, completeCorrectionClassify } from "./correction-classify.js";
+
+const MESSAGES = [{ role: "user" as const, content: "the old fact is a duplicate" }];
+
+function config(over: Partial<PluginConfig> = {}): PluginConfig {
+  return {
+    localLlmEnabled: true,
+    localLlmFallback: true,
+    modelSource: "plugin",
+    correctionClassifyTimeoutMs: 40,
+    ...over,
+  } as PluginConfig;
+}
+
+function hangUntilAbort(): CorrectionClassifyDeps["localLlm"] {
+  return {
+    chatCompletion: (_messages, options) =>
+      new Promise((resolve) => {
+        const finish = () => resolve(null);
+        if (options?.signal?.aborted) {
+          finish();
+          return;
+        }
+        options?.signal?.addEventListener("abort", finish, { once: true });
+      }),
+  };
+}
+
+test("classify falls back after the local attempt times out", async () => {
+  let fallbackCalls = 0;
+  let localSignal: AbortSignal | undefined;
+  const deps: CorrectionClassifyDeps = {
+    config: config(),
+    localLlm: {
+      chatCompletion: (_messages, options) =>
+        new Promise((resolve) => {
+          localSignal = options?.signal;
+          const finish = () => resolve(null);
+          if (options?.signal?.aborted) {
+            finish();
+            return;
+          }
+          options?.signal?.addEventListener("abort", finish, { once: true });
+        }),
+    },
+    fallbackChat: async () => {
+      fallbackCalls += 1;
+      return { content: '{"classification":"outdated","confidence":0.8,"actions":[]}', modelUsed: "gateway" };
+    },
+  };
+  const content = await completeCorrectionClassify(MESSAGES, deps);
+  assert.equal(fallbackCalls, 1);
+  assert.equal(localSignal?.aborted, true);
+  assert.match(content ?? "", /outdated/);
+});
+
+test("classify cancels on caller abort and does not call the fallback", async () => {
+  let fallbackCalls = 0;
+  const caller = new AbortController();
+  const deps: CorrectionClassifyDeps = {
+    config: config({ correctionClassifyTimeoutMs: 30_000 }),
+    localLlm: hangUntilAbort(),
+    fallbackChat: async () => {
+      fallbackCalls += 1;
+      return { content: "should-not-run", modelUsed: "gateway" };
+    },
+  };
+  const pending = completeCorrectionClassify(MESSAGES, deps, caller.signal);
+  caller.abort();
+  await assert.rejects(pending, (err: unknown) => isAbortError(err));
+  assert.equal(fallbackCalls, 0);
+});
+
+test("classify uses the fallback when the local LLM returns null", async () => {
+  let localCalls = 0;
+  let fallbackCalls = 0;
+  const deps: CorrectionClassifyDeps = {
+    config: config(),
+    localLlm: {
+      chatCompletion: async () => {
+        localCalls += 1;
+        return null;
+      },
+    },
+    fallbackChat: async () => {
+      fallbackCalls += 1;
+      return { content: '{"ok":true}', modelUsed: "gateway" };
+    },
+  };
+  const content = await completeCorrectionClassify(MESSAGES, deps);
+  assert.equal(localCalls, 1);
+  assert.equal(fallbackCalls, 1);
+  assert.equal(content, '{"ok":true}');
+});
+
+test("classify does not call the fallback when the local LLM returns content", async () => {
+  let fallbackCalls = 0;
+  const deps: CorrectionClassifyDeps = {
+    config: config(),
+    localLlm: { chatCompletion: async () => ({ content: "local-json" }) },
+    fallbackChat: async () => {
+      fallbackCalls += 1;
+      return { content: "gateway", modelUsed: "gateway" };
+    },
+  };
+  assert.equal(await completeCorrectionClassify(MESSAGES, deps), "local-json");
+  assert.equal(fallbackCalls, 0);
+});
+
+test("gateway modelSource skips the local LLM", async () => {
+  let localCalls = 0;
+  const deps: CorrectionClassifyDeps = {
+    config: config({ modelSource: "gateway", localLlmEnabled: true }),
+    localLlm: {
+      chatCompletion: async () => {
+        localCalls += 1;
+        return { content: "local" };
+      },
+    },
+    fallbackChat: async () => ({ content: "gateway-primary", modelUsed: "gateway" }),
+  };
+  assert.equal(await completeCorrectionClassify(MESSAGES, deps), "gateway-primary");
+  assert.equal(localCalls, 0);
+});
+
+test("no configured gateway models return null without waiting out the classify timeout", async () => {
+  const started = Date.now();
+  const content = await completeCorrectionClassify(MESSAGES, {
+    config: config({ localLlmEnabled: false }),
+    localLlm: {
+      chatCompletion: async () => {
+        throw new Error("local must not run");
+      },
+    },
+  });
+  assert.equal(content, null);
+  assert.ok(Date.now() - started < 1000, `no-models path took ${Date.now() - started}ms`);
+});
+
+test("a fallback attempt timeout returns null instead of an abort", async () => {
+  const deps: CorrectionClassifyDeps = {
+    config: config({ localLlmEnabled: false, correctionClassifyTimeoutMs: 40 }),
+    localLlm: {
+      chatCompletion: async () => {
+        throw new Error("local must not run");
+      },
+    },
+    fallbackChat: (_messages, options) =>
+      new Promise((_resolve, reject) => {
+        const fail = () => {
+          const err = new Error("fallback attempt aborted");
+          err.name = "AbortError";
+          reject(err);
+        };
+        if (options.signal?.aborted) {
+          fail();
+          return;
+        }
+        options.signal?.addEventListener("abort", fail, { once: true });
+      }),
+  };
+  assert.equal(await completeCorrectionClassify(MESSAGES, deps), null);
+});
+
+test("localLlmFallback false does not call the gateway after a local miss", async () => {
+  let fallbackCalls = 0;
+  const deps: CorrectionClassifyDeps = {
+    config: config({ localLlmFallback: false }),
+    localLlm: { chatCompletion: async () => null },
+    fallbackChat: async () => {
+      fallbackCalls += 1;
+      return { content: "nope", modelUsed: "gateway" };
+    },
+  };
+  await assert.rejects(() => completeCorrectionClassify(MESSAGES, deps), /fallback disabled/);
+  assert.equal(fallbackCalls, 0);
+});

package/src/correction/correction-classify.ts

@@ -0,0 +1,157 @@
+/**
+ * Correction classify completion: a short per-attempt budget, caller abort,
+ * and the same gateway/fallback client extraction uses when the local LLM
+ * is down or `modelSource` is `gateway`.
+ *
+ * Each attempt (local, then gateway) gets `correctionClassifyTimeoutMs`.
+ * A caller abort cancels the in-flight attempt and does not fall through.
+ * A local timeout, null, or error falls through when `localLlmFallback` is
+ * not false. Gateway mode skips the local client and uses the task chain
+ * as the primary path.
+ */
+import { abortError, isAbortError, throwIfAborted } from "../abort-error.js";
+import { resolveLocalLlmCapabilities } from "../capabilities.js";
+import { fallbackLlmRuntimeContextFromConfig } from "../fallback-llm-codex-subscription.js";
+import {
+  FallbackLlmClient,
+  type FallbackLlmOptions,
+  type FallbackLlmResponse,
+  gatewayTaskChainOptions,
+} from "../fallback-llm.js";
+import type { LocalLlmChatCompletionOptions } from "../local-llm-helpers.js";
+import type { PluginConfig } from "../types.js";
+import { DEFAULT_CORRECTION_CLASSIFY_TIMEOUT_MS, MAX_CORRECTION_CLASSIFY_TIMEOUT_MS } from "./correction-config.js";
+
+export interface CorrectionClassifyMessage {
+  role: "system" | "user" | "assistant";
+  content: string;
+}
+
+export interface CorrectionClassifyDeps {
+  config: PluginConfig;
+  localLlm: {
+    chatCompletion(
+      messages: Array<{ role: string; content: string }>,
+      options?: LocalLlmChatCompletionOptions
+    ): Promise<{ content: string } | null>;
+  };
+  /**
+   * Test seam. Production builds a {@link FallbackLlmClient} from config.
+   * Returning null is the no-models fast path.
+   */
+  fallbackChat?(
+    messages: CorrectionClassifyMessage[],
+    options: FallbackLlmOptions
+  ): Promise<FallbackLlmResponse | null>;
+}
+
+export async function completeCorrectionClassify(
+  messages: CorrectionClassifyMessage[],
+  deps: CorrectionClassifyDeps,
+  abortSignal?: AbortSignal
+): Promise<string | null> {
+  throwIfAborted(abortSignal, "correction classify aborted");
+  const timeoutMs = classifyTimeoutMs(deps.config);
+  const gatewayPrimary = deps.config.modelSource === "gateway";
+  const localEnabled = resolveLocalLlmCapabilities(deps.config).localLlm === true && !gatewayPrimary;
+
+  if (localEnabled) {
+    const localAttempt = startAttempt(abortSignal, timeoutMs);
+    try {
+      const local = await deps.localLlm.chatCompletion(messages, {
+        operation: "correction-classify",
+        priority: "background",
+        timeoutMs,
+        temperature: 0.2,
+        signal: localAttempt.signal,
+      });
+      if (abortSignal?.aborted) throw abortError("correction classify aborted");
+      if (local?.content) return local.content;
+      if (deps.config.localLlmFallback === false) {
+        throw new Error("correction classify: local LLM unavailable and fallback disabled");
+      }
+    } catch (err) {
+      if (abortSignal?.aborted) {
+        throw isAbortError(err) ? err : abortError("correction classify aborted");
+      }
+      // A timeout abort belongs to this attempt. Fall through unless the
+      // operator turned the gateway path off.
+      if (deps.config.localLlmFallback === false) {
+        if (isAbortError(err)) {
+          throw new Error("correction classify: local LLM timed out and fallback disabled");
+        }
+        throw err;
+      }
+    } finally {
+      localAttempt.dispose();
+    }
+  } else if (!gatewayPrimary && deps.config.localLlmFallback === false) {
+    throw new Error("correction classify: local LLM disabled and fallback disabled");
+  }
+
+  throwIfAborted(abortSignal, "correction classify aborted");
+  const fallbackAttempt = startAttempt(abortSignal, timeoutMs);
+  try {
+    const fallbackOptions: FallbackLlmOptions = {
+      temperature: 0.2,
+      timeoutMs,
+      signal: fallbackAttempt.signal,
+      ...gatewayTaskChainOptions(deps.config),
+    };
+    const fallback = deps.fallbackChat
+      ? await deps.fallbackChat(messages, fallbackOptions)
+      : await new FallbackLlmClient(
+          deps.config.gatewayConfig,
+          fallbackLlmRuntimeContextFromConfig(deps.config)
+        ).chatCompletion(messages, fallbackOptions);
+    if (abortSignal?.aborted) throw abortError("correction classify aborted");
+    return fallback?.content ?? null;
+  } catch (err) {
+    // The attempt signal aborts on its own budget. That is a finished miss
+    // (empty plan), not a caller disconnect — only the caller signal skips
+    // the empty-plan path.
+    if (abortSignal?.aborted) {
+      throw isAbortError(err) ? err : abortError("correction classify aborted");
+    }
+    if (isAbortError(err)) return null;
+    throw err;
+  } finally {
+    fallbackAttempt.dispose();
+  }
+}
+
+function classifyTimeoutMs(config: PluginConfig): number {
+  const configured = config.correctionClassifyTimeoutMs;
+  if (
+    typeof configured === "number" &&
+    Number.isInteger(configured) &&
+    configured >= 1 &&
+    configured <= MAX_CORRECTION_CLASSIFY_TIMEOUT_MS
+  ) {
+    return configured;
+  }
+  return DEFAULT_CORRECTION_CLASSIFY_TIMEOUT_MS;
+}
+
+function startAttempt(
+  caller: AbortSignal | undefined,
+  timeoutMs: number
+): { signal: AbortSignal; dispose: () => void } {
+  // A ref'd timer, not AbortSignal.timeout: that helper's timer is unref'd,
+  // so a classify wait would not keep a short-lived caller alive until the
+  // budget elapses.
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  const onCaller = (): void => controller.abort();
+  if (caller?.aborted) controller.abort();
+  else caller?.addEventListener("abort", onCaller, { once: true });
+  let disposed = false;
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    clearTimeout(timer);
+    caller?.removeEventListener("abort", onCaller);
+  };
+  controller.signal.addEventListener("abort", dispose, { once: true });
+  return { signal: controller.signal, dispose };
+}

package/src/correction/correction-config.ts

@@ -0,0 +1,93 @@
+/**
+ * Correction-contract config (issue #1580 plus classify timeout).
+ *
+ * Extracted from config.ts so the grandfathered parser file does not grow.
+ * Nested `correction.<key>` wins over the flat `correction<Key>` legacy key.
+ * Invalid values throw — they are never clamped or silently defaulted.
+ *
+ * Reads stay inline on `cfg` so the parsed-key extractor records the same
+ * paths the plugin schema declares.
+ */
+import { coerceBool, coerceNumber } from "../connectors/coerce.js";
+
+export const DEFAULT_CORRECTION_CLASSIFY_TIMEOUT_MS = 45_000;
+export const MAX_CORRECTION_CLASSIFY_TIMEOUT_MS = 300_000;
+
+export interface ParsedCorrectionConfig {
+  correctionEnabled: boolean;
+  correctionApplyRequiresConfirm: boolean;
+  correctionMaxAffected: number;
+  correctionPlanTtlHours: number;
+  correctionClassifyTimeoutMs: number;
+}
+
+export function parseCorrectionConfig(cfg: Record<string, unknown>): ParsedCorrectionConfig {
+  return {
+    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 value = coerceBool(raw);
+      if (value === undefined) {
+        throw new Error(`Invalid correction.enabled: expected a boolean, got ${JSON.stringify(raw)}`);
+      }
+      return value;
+    })(),
+    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 value = coerceBool(raw);
+      if (value === undefined) {
+        throw new Error(`Invalid correction.applyRequiresConfirm: expected a boolean, got ${JSON.stringify(raw)}`);
+      }
+      return value;
+    })(),
+    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);
+      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;
+      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;
+    })(),
+    correctionClassifyTimeoutMs: (() => {
+      const nested = (cfg.correction as Record<string, unknown> | undefined)?.classifyTimeoutMs;
+      const raw = nested !== undefined ? nested : cfg.correctionClassifyTimeoutMs;
+      if (raw === undefined || raw === null) return DEFAULT_CORRECTION_CLASSIFY_TIMEOUT_MS;
+      const n = coerceNumber(raw);
+      if (n === undefined || !Number.isInteger(n) || n < 1 || n > MAX_CORRECTION_CLASSIFY_TIMEOUT_MS) {
+        throw new Error(
+          `Invalid correction.classifyTimeoutMs: expected an integer from 1 to ${MAX_CORRECTION_CLASSIFY_TIMEOUT_MS}, got ${JSON.stringify(raw)}`
+        );
+      }
+      return n;
+    })(),
+  };
+}