@remnic/core 10.0.4 → 10.0.6

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;
+    })(),
+  };
+}

package/src/correction/correction-contract.ts

@@ -51,6 +51,12 @@ export interface CorrectionRequest {
    * planner only sees the ALREADY-AUTHORIZED namespace.
    */
   namespace?: string;
+  /**
+   * Winner memory id. When set, `targetIds` must be exactly the duplicate
+   * (the loser). The planner skips classification and drafts one recoverable
+   * supersede — no hard delete, no replacement write.
+   */
+  duplicateOf?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -103,8 +109,11 @@ export const MEMORY_CATEGORIES: readonly MemoryCategory[] = [
 ];
 
 export type CorrectionAction =
-  /** Outdated: a new fact replaces the loser. */
-  | { kind: "supersede"; loserId: string; replacement?: MemoryDraft }
+  /**
+   * Outdated: a new fact replaces the loser, or `winnerId` records an
+   * existing memory as the replacement without writing a new one.
+   */
+  | { kind: "supersede"; loserId: string; replacement?: MemoryDraft; winnerId?: string }
   /** Incomplete / minor-wrong: a versioned edit to an existing memory. */
   | { kind: "edit"; memoryId: string; patch: string }
   /** Wrong: retire + tombstone. */
@@ -213,6 +222,9 @@ export const CORRECTION_TEXT_MAX = 10_000;
 /** Maximum supported redaction pattern length (§34 — bounded patterns). */
 export const REDACTION_PATTERN_MAX = 256;
 
+/** Maximum memory-id length for `duplicateOf` / explicit targets. */
+export const CORRECTION_MEMORY_ID_MAX = 512;
+
 /**
  * Validate a {@link CorrectionRequest}'s invariants. Returns the cleaned
  * request or throws with a field-specific message (rule 51 — list valid
@@ -234,25 +246,47 @@ export function validateCorrectionRequest(request: CorrectionRequest): Correctio
   const targetIds = Array.isArray(request.targetIds)
     ? request.targetIds.filter((id): id is string => typeof id === "string" && id.length > 0)
     : undefined;
-  if (targetIds !== undefined && targetIds.length === 0) {
-    // An empty array is treated as "not provided" so callers can forward
-    // optional fields without a separate presence flag.
-    return {
-      text,
-      ...(request.sessionKey ? { sessionKey: request.sessionKey } : {}),
-      ...(request.principal ? { principal: request.principal } : {}),
-      ...(request.namespace ? { namespace: request.namespace } : {}),
-    };
+  const normalizedTargets = targetIds !== undefined && targetIds.length === 0 ? undefined : targetIds;
+  const duplicateOf = readDuplicateOf(request.duplicateOf);
+  if (duplicateOf) {
+    if (!normalizedTargets || normalizedTargets.length !== 1) {
+      throw new CorrectionContractError(
+        "CorrectionRequest.duplicateOf requires exactly one targetIds entry (the duplicate memory).",
+      );
+    }
+    if (normalizedTargets[0] === duplicateOf) {
+      throw new CorrectionContractError(
+        "CorrectionRequest.duplicateOf must be a different memory from targetIds.",
+      );
+    }
   }
   return {
     text,
-    ...(targetIds ? { targetIds } : {}),
+    ...(normalizedTargets ? { targetIds: normalizedTargets } : {}),
+    ...(duplicateOf ? { duplicateOf } : {}),
     ...(request.sessionKey ? { sessionKey: request.sessionKey } : {}),
     ...(request.principal ? { principal: request.principal } : {}),
     ...(request.namespace ? { namespace: request.namespace } : {}),
   };
 }
 
+function readDuplicateOf(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") {
+    throw new CorrectionContractError("CorrectionRequest.duplicateOf must be a memory id string.");
+  }
+  const id = value.trim();
+  if (id.length === 0 || id !== value) {
+    throw new CorrectionContractError("CorrectionRequest.duplicateOf must be a non-empty memory id.");
+  }
+  if (id.length > CORRECTION_MEMORY_ID_MAX) {
+    throw new CorrectionContractError(
+      `CorrectionRequest.duplicateOf exceeds the ${CORRECTION_MEMORY_ID_MAX}-character limit (${id.length}).`,
+    );
+  }
+  return id;
+}
+
 /**
  * Validate a redaction pattern (§34 — bounded, literal-or-safe-regex; reject
  * catastrophic patterns). Returns the cleaned pattern or throws.
@@ -377,8 +411,21 @@ export function validateCorrectionAction(action: unknown): asserts action is Cor
       if (typeof a.loserId !== "string" || a.loserId.length === 0) {
         throw new CorrectionContractError("supersede.loserId is required.");
       }
-      if (a.replacement !== undefined && a.replacement !== null) {
-        validateMemoryDraft(a.replacement);
+      {
+        const hasReplacement = a.replacement !== undefined && a.replacement !== null;
+        const hasWinner = a.winnerId !== undefined && a.winnerId !== null;
+        if (hasWinner) {
+          if (typeof a.winnerId !== "string" || a.winnerId.trim().length === 0 || a.winnerId !== a.winnerId.trim()) {
+            throw new CorrectionContractError("supersede.winnerId must be a non-empty memory id.");
+          }
+          if (a.winnerId === a.loserId) {
+            throw new CorrectionContractError("supersede.winnerId must differ from loserId.");
+          }
+          if (hasReplacement) {
+            throw new CorrectionContractError("supersede.winnerId cannot be combined with a replacement draft.");
+          }
+        }
+        if (hasReplacement) validateMemoryDraft(a.replacement);
       }
       break;
     case "edit":

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

@@ -35,7 +35,7 @@ import { CorrectionExecutor, CORRECTION_ERROR_MAX, sanitizeErrorMessage, type Ex
 
 interface FakeState {
   /** memoryId → current memory state. */
-  memories: Map<string, ExecutorMemory & { status: string; supersededBy?: string; validUntil?: string }>;
+  memories: Map<string, ExecutorMemory & { status: string; supersededBy?: string; validUntil?: string; lineage?: string[] }>;
   tombstones: Array<{ reason: string; sourceMemoryId: string; rawContent: string; supersessionKey?: string; supersessionKeys?: string[]; contentHash?: string }>;
   redactionRules: string[];
   auditRecords: Array<{ planId: string; outcome: CorrectionOutcome }>;
@@ -98,7 +98,7 @@ function makeExecutorDeps(state: FakeState, opts: { biTemporalEnabled?: boolean;
     getMemory: async (_ns, memoryId) => {
       const m = state.memories.get(memoryId);
       if (!m) return null;
-      const { status: _s, supersededBy: _sb, validUntil: _v, ...rest } = m;
+      const { supersededBy: _sb, validUntil: _v, ...rest } = m;
       return rest;
     },
     writeReplacement: async (namespace, draft) => {
@@ -1589,3 +1589,103 @@ test("#1678: sanitizeErrorMessage strips absolute paths and caps length", () =>
   assert.ok(!atPath.includes("secret.txt"), "path suffix must be consumed: " + atPath);
   assert.ok(atPath.includes("<path>"), "must leave <path> placeholder: " + atPath);
 });
+
+test("winnerId supersede leaves the loser recoverable and the winner unchanged", async () => {
+  await withTempDir(async (dir) => {
+    const candidates = new Map<string, PlannerCandidate>([
+      ["mem-loser", { memoryId: "mem-loser", path: "facts/mem-loser.md", content: "duplicate", excerpt: "duplicate", score: 1 }],
+      ["mem-winner", { memoryId: "mem-winner", path: "facts/mem-winner.md", content: "canonical", excerpt: "canonical", score: 1 }],
+    ]);
+    const state: FakeState = {
+      memories: new Map([
+        ["mem-loser", fakeMemory({ memoryId: "mem-loser", content: "duplicate", rawContent: "duplicate raw" })],
+        ["mem-winner", fakeMemory({ memoryId: "mem-winner", content: "canonical", rawContent: "canonical raw" })],
+      ]),
+      tombstones: [],
+      redactionRules: [],
+      auditRecords: [],
+      propagateCalls: 0,
+      writtenReplacements: [],
+    };
+    const planner = new CorrectionPlanner({
+      ...makePlannerDeps(dir, candidates),
+      inspectMemory: async ({ memoryId }) => {
+        const candidate = candidates.get(memoryId);
+        if (!candidate) return null;
+        return { candidate, status: "active" };
+      },
+    });
+    const plan = await planner.plan(
+      { text: "duplicate", targetIds: ["mem-loser"], duplicateOf: "mem-winner" },
+      ["default"],
+    );
+    assert.equal(plan.actions.length, 1);
+    const executor = new CorrectionExecutor(makeExecutorDeps(state), planner);
+    const outcome = await executor.apply("default", plan.planId, { confirm: true });
+    assert.equal(outcome.status, "applied");
+    const loser = state.memories.get("mem-loser");
+    const winner = state.memories.get("mem-winner");
+    assert.ok(loser, "loser file remains");
+    assert.equal(loser?.status, "superseded");
+    assert.equal(loser?.supersededBy, "mem-winner");
+    assert.equal(loser?.lineage, undefined);
+    assert.equal(winner?.status, "active");
+    assert.equal(winner?.content, "canonical");
+    assert.equal(state.writtenReplacements.length, 0);
+    assert.equal(state.tombstones.length, 1);
+    assert.equal(state.tombstones[0]?.reason, "supersession");
+    assert.equal(state.tombstones[0]?.sourceMemoryId, "mem-loser");
+  });
+});
+
+test("winnerId supersede fails closed when the winner is no longer active", async () => {
+  await withTempDir(async (dir) => {
+    const candidates = new Map<string, PlannerCandidate>([
+      ["mem-loser", { memoryId: "mem-loser", path: "facts/mem-loser.md", content: "duplicate", excerpt: "duplicate", score: 1 }],
+    ]);
+    const state: FakeState = {
+      memories: new Map([
+        ["mem-loser", fakeMemory({ memoryId: "mem-loser", content: "duplicate" })],
+        ["mem-winner", fakeMemory({ memoryId: "mem-winner", content: "canonical", status: "superseded" })],
+      ]),
+      tombstones: [],
+      redactionRules: [],
+      auditRecords: [],
+      propagateCalls: 0,
+      writtenReplacements: [],
+    };
+    const planner = new CorrectionPlanner({
+      ...makePlannerDeps(dir, candidates),
+      inspectMemory: async ({ memoryId }) => {
+        if (memoryId === "mem-winner") {
+          return {
+            candidate: {
+              memoryId,
+              path: "facts/mem-winner.md",
+              content: "canonical",
+              excerpt: "canonical",
+              score: 1,
+            },
+            status: "active",
+          };
+        }
+        const candidate = candidates.get(memoryId);
+        if (!candidate) return null;
+        return { candidate, status: "active" };
+      },
+    });
+    const plan = await planner.plan(
+      { text: "duplicate", targetIds: ["mem-loser"], duplicateOf: "mem-winner" },
+      ["default"],
+    );
+    const outcome = await new CorrectionExecutor(makeExecutorDeps(state), planner).apply(
+      "default",
+      plan.planId,
+      { confirm: true },
+    );
+    assert.equal(outcome.results[0]?.status, "failed");
+    assert.match(outcome.results[0]?.error ?? "", /winner is not active/);
+    assert.equal(state.memories.get("mem-loser")?.status, "active");
+    assert.equal(state.tombstones.length, 0);
+  });
+});