@remnic/core 10.0.3 → 10.0.5

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

package/src/correction/correction-executor.ts

@@ -68,6 +68,8 @@ export interface ExecutorMemory {
   entityRef?: string;
   /** Raw content used for the tombstone hash (rule 23). */
   rawContent: string;
+  /** Frontmatter status. Absent is treated as active. */
+  status?: string;
 }
 
 export interface ExecutorDeps {
@@ -486,13 +488,29 @@ export class CorrectionExecutor {
         if (action.replacement && !replacementResult) {
           continue;
         }
+        if (action.winnerId && !action.replacement) {
+          const winner = await this.deps.getMemory(namespace, action.winnerId, abortSignal);
+          const winnerStatus = winner ? (winner.status ?? "active") : undefined;
+          if (!winner || winnerStatus !== "active") {
+            results.push({
+              action,
+              status: "failed",
+              error: winner
+                ? `supersede winner is not active: ${action.winnerId} (${winnerStatus})`
+                : `supersede winner not found: ${action.winnerId}`,
+            });
+            continue;
+          }
+        }
         await this.retireAndTombstone(
           namespace,
           action,
           "supersession",
           results,
           appliedTouched,
-          { supersededBy: replacementResult?.memoryId },
+          {
+            supersededBy: replacementResult?.memoryId ?? action.winnerId,
+          },
           abortSignal
         );
         if (results.at(-1)?.status === "applied") {

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

@@ -38,6 +38,8 @@ interface StubState {
   writeReplacementCalls: number;
   propagateCalls: number;
   retireCalls: number;
+  statusById?: Map<string, string>;
+  classifyCalls?: number;
 }
 
 function makeCandidate(over: Partial<PlannerCandidate> & { memoryId: string }): PlannerCandidate {
@@ -72,12 +74,18 @@ function makeDeps(stateDir: string, state: StubState, opts: { maxAffected?: numb
       }
       return out;
     },
+    inspectMemory: async ({ memoryId }) => {
+      const candidate = state.candidatesById.get(memoryId);
+      if (!candidate) return null;
+      return { candidate, status: state.statusById?.get(memoryId) ?? "active" };
+    },
     expandNeighbors: async ({ seedIds }) => {
       // No neighbors in the stub; return the seeds themselves so neighbor
       // expansion is exercised but produces no surprises.
       return seedIds.map((id) => state.candidatesById.get(id)).filter((c): c is PlannerCandidate => c !== undefined);
     },
     classifyAndDraft: async ({ text, candidates }) => {
+      state.classifyCalls = (state.classifyCalls ?? 0) + 1;
       return typeof state.llmResult === "function"
         ? state.llmResult(text, candidates)
         : state.llmResult;
@@ -787,3 +795,136 @@ test("#1713: recoverStaleApplyingPlans recovers pre-fix plans immediately at exp
     assert.equal(recovered.length, 1, "pre-fix plan at expiry must be recovered immediately");
   });
 });
+
+test("duplicateOf skips the LLM and drafts one recoverable supersede linked to the winner", async () => {
+  await withTempDir(async (dir) => {
+    const state: StubState = {
+      candidatesById: new Map([
+        ["mem-loser", makeCandidate({ memoryId: "mem-loser", content: "duplicate fact" })],
+        ["mem-winner", makeCandidate({ memoryId: "mem-winner", content: "canonical fact" })],
+      ]),
+      llmResult: () => {
+        throw new Error("classifyAndDraft must not run in duplicate mode");
+      },
+      writeReplacementCalls: 0,
+      propagateCalls: 0,
+      retireCalls: 0,
+    };
+    const plan = await new CorrectionPlanner(makeDeps(dir, state)).plan(
+      { text: "mem-loser duplicates mem-winner", targetIds: ["mem-loser"], duplicateOf: "mem-winner" },
+      ["default"],
+    );
+    assert.equal(state.classifyCalls ?? 0, 0);
+    assert.equal(plan.actions.length, 1);
+    assert.deepEqual(plan.actions[0], { kind: "supersede", loserId: "mem-loser", winnerId: "mem-winner" });
+    assert.equal(plan.classification, "outdated");
+    assert.equal(plan.confidence, 1);
+    assert.equal(plan.affected.length, 1);
+    assert.equal(plan.affected[0]?.memoryId, "mem-loser");
+    assert.equal(plan.request.duplicateOf, "mem-winner");
+  });
+});
+
+test("a model-selected winnerId outside the located set is dropped", async () => {
+  await withTempDir(async (dir) => {
+    const state: StubState = {
+      candidatesById: new Map([
+        ["mem-loser", makeCandidate({ memoryId: "mem-loser", content: "duplicate fact" })],
+        ["mem-winner", makeCandidate({ memoryId: "mem-winner", content: "canonical fact" })],
+      ]),
+      llmResult: {
+        classification: "outdated",
+        confidence: 0.9,
+        actions: [{ kind: "supersede", loserId: "mem-loser", winnerId: "mem-not-located" }],
+        relevance: [{ memoryId: "mem-loser", why: "duplicate" }],
+        warnings: [],
+      },
+      writeReplacementCalls: 0,
+      propagateCalls: 0,
+      retireCalls: 0,
+    };
+    const plan = await new CorrectionPlanner(makeDeps(dir, state)).plan(
+      { text: "retire the duplicate", targetIds: ["mem-loser"] },
+      ["default"],
+    );
+    assert.equal(plan.actions.length, 0);
+    assert.match(plan.warnings.join(" "), /outside the located candidate set/);
+  });
+});
+
+test("a model-selected winnerId inside the located set is kept", async () => {
+  await withTempDir(async (dir) => {
+    const state: StubState = {
+      candidatesById: new Map([
+        ["mem-loser", makeCandidate({ memoryId: "mem-loser", content: "duplicate fact" })],
+        ["mem-winner", makeCandidate({ memoryId: "mem-winner", content: "canonical fact" })],
+      ]),
+      llmResult: {
+        classification: "outdated",
+        confidence: 0.9,
+        actions: [{ kind: "supersede", loserId: "mem-loser", winnerId: "mem-winner" }],
+        relevance: [{ memoryId: "mem-loser", why: "duplicate" }],
+        warnings: [],
+      },
+      writeReplacementCalls: 0,
+      propagateCalls: 0,
+      retireCalls: 0,
+    };
+    const plan = await new CorrectionPlanner(makeDeps(dir, state)).plan(
+      { text: "retire the duplicate", targetIds: ["mem-loser", "mem-winner"] },
+      ["default"],
+    );
+    assert.deepEqual(plan.actions, [{ kind: "supersede", loserId: "mem-loser", winnerId: "mem-winner" }]);
+  });
+});
+
+test("duplicateOf rejects same id, missing memories, inactive memories, and a target list that is not exactly one", async () => {
+  await withTempDir(async (dir) => {
+    const state: StubState = {
+      candidatesById: new Map([
+        ["mem-loser", makeCandidate({ memoryId: "mem-loser" })],
+        ["mem-winner", makeCandidate({ memoryId: "mem-winner" })],
+        ["mem-old", makeCandidate({ memoryId: "mem-old" })],
+      ]),
+      statusById: new Map([["mem-old", "superseded"]]),
+      llmResult: { classification: "outdated", confidence: 1, actions: [], relevance: [], warnings: [] },
+      writeReplacementCalls: 0,
+      propagateCalls: 0,
+      retireCalls: 0,
+    };
+    const planner = new CorrectionPlanner(makeDeps(dir, state));
+    await assert.rejects(
+      () => planner.plan({ text: "same", targetIds: ["mem-loser"], duplicateOf: "mem-loser" }, ["default"]),
+      /different memory from targetIds/,
+    );
+    await assert.rejects(
+      () => planner.plan({ text: "missing loser", targetIds: ["missing"], duplicateOf: "mem-winner" }, ["default"]),
+      /target memory not found: missing/,
+    );
+    await assert.rejects(
+      () => planner.plan({ text: "missing winner", targetIds: ["mem-loser"], duplicateOf: "missing-winner" }, ["default"]),
+      /duplicateOf memory not found: missing-winner/,
+    );
+    await assert.rejects(
+      () => planner.plan({ text: "inactive loser", targetIds: ["mem-old"], duplicateOf: "mem-winner" }, ["default"]),
+      /target memory is not active: mem-old \(superseded\)/,
+    );
+    state.statusById = new Map([["mem-winner", "forgotten"]]);
+    await assert.rejects(
+      () => planner.plan({ text: "inactive winner", targetIds: ["mem-loser"], duplicateOf: "mem-winner" }, ["default"]),
+      /duplicateOf memory is not active: mem-winner \(forgotten\)/,
+    );
+    await assert.rejects(
+      () => planner.plan({ text: "no target", duplicateOf: "mem-winner" }, ["default"]),
+      /exactly one targetIds entry/,
+    );
+    await assert.rejects(
+      () => planner.plan(
+        { text: "two targets", targetIds: ["mem-loser", "mem-winner"], duplicateOf: "mem-winner" },
+        ["default"],
+      ),
+      /exactly one targetIds entry/,
+    );
+    assert.equal(state.classifyCalls ?? 0, 0);
+  });
+});

package/src/correction/correction-planner.ts

@@ -7,9 +7,11 @@
  *      error, rule 34). Else: search via the injected search path scoped to
  *      the caller's readable namespaces, plus 1-hop entity-graph neighbors of
  *      top hits. Cap candidates at `maxAffected`.
- *   2. CLASSIFY + DRAFT via one LLM call (Responses API only, gotcha 1). On
- *      LLM failure → deterministic fallback plan (rule 13): classification
- *      `outdated`, `confidence: 0`, empty actions, warning set.
+ *   2. CLASSIFY + DRAFT via one LLM call (Responses API only, gotcha 1),
+ *      unless `duplicateOf` is set — that path skips the LLM and drafts one
+ *      recoverable supersede. On LLM failure → deterministic fallback plan
+ *      (rule 13): classification `outdated`, `confidence: 0`, empty actions.
+ *      A caller abort throws instead of falling back.
  *   3. RENDER DIFF by materializing what each action would do, using the
  *      injected diff renderer (page-versioning — reuse, don't fork).
  *   4. PERSIST the plan atomically under
@@ -81,6 +83,16 @@ export interface PlannerDeps {
     targetIds: readonly string[];
     namespaces: readonly string[];
   }): Promise<PlannerCandidate[]>;
+  /**
+   * Inspect one memory for duplicate-mode validation. Absent means "not
+   * found" (including outside the readable namespaces). A missing method
+   * falls back to {@link resolveTargets}, which reports inactive memories
+   * as not found.
+   */
+  inspectMemory?(request: {
+    memoryId: string;
+    namespaces: readonly string[];
+  }): Promise<PlannerMemoryInspection | null>;
   /**
    * One-hop entity-graph neighbors of the supplied candidates. Returns the
    * union (deduped by memoryId); neighbors not already in `seedIds` only.
@@ -99,6 +111,7 @@ export interface PlannerDeps {
   classifyAndDraft(request: {
     text: string;
     candidates: PlannerCandidate[];
+    abortSignal?: AbortSignal;
   }): Promise<LlmClassificationResult>;
   /**
    * Render a human-readable diff preview for the planned actions, using
@@ -120,6 +133,13 @@ export interface PlannerDeps {
   now(): Date;
 }
 
+/** One memory inspected for an explicit duplicate supersede. */
+export interface PlannerMemoryInspection {
+  candidate: PlannerCandidate;
+  /** Omitted status is treated as active (older files leave it unset). */
+  status?: string;
+}
+
 /** Result of the single LLM classify+draft call. */
 export interface LlmClassificationResult {
   classification: CorrectionClassification;
@@ -177,10 +197,15 @@ export class CorrectionPlanner {
       );
     }
 
-    // 1. LOCATE
-    const located = await this.locateCandidates(cleaned, namespaces, abortSignal);
+    // 1. LOCATE — duplicateOf skips search and the classifier.
+    const explicitDuplicate = cleaned.duplicateOf
+      ? await this.planExplicitDuplicate(cleaned, namespaces, abortSignal)
+      : null;
+    const located = explicitDuplicate
+      ? { candidates: [explicitDuplicate.loser] }
+      : await this.locateCandidates(cleaned, namespaces, abortSignal);
     throwIfAborted(abortSignal, "correction planning aborted");
-    if (located.candidates.length === 0) {
+    if (!explicitDuplicate && located.candidates.length === 0) {
       // No candidates AND no explicit targets → empty plan is valid (the user
       // can still discard). But explicit-target-not-found was already raised
       // inside locateCandidates (rule 34).
@@ -191,10 +216,13 @@ export class CorrectionPlanner {
     }
 
     // 2. CLASSIFY + DRAFT
-    const llm = await this.deps.classifyAndDraft({
-      text: cleaned.text,
-      candidates: located.candidates,
-    });
+    const llm = explicitDuplicate
+      ? explicitDuplicate.llm
+      : await this.deps.classifyAndDraft({
+          text: cleaned.text,
+          candidates: located.candidates,
+          abortSignal,
+        });
     throwIfAborted(abortSignal, "correction planning aborted");
 
     // Validate every action shape before persisting — the adapter is trusted
@@ -235,6 +263,7 @@ export class CorrectionPlanner {
     // absent from the candidate set and warn.
     const candidateIds = new Set(located.candidates.map((c) => c.memoryId));
     if (llm.actions.length > 0 && candidateIds.size > 0) {
+      const explicitWinner = cleaned.duplicateOf;
       const filtered = llm.actions.filter((action) => {
         const id =
           action.kind === "supersede"
@@ -242,7 +271,19 @@ export class CorrectionPlanner {
             : action.kind === "edit" || action.kind === "retract" || action.kind === "rescope"
               ? action.memoryId
               : null;
-        return id === null || candidateIds.has(id);
+        if (id !== null && !candidateIds.has(id)) return false;
+        // A model-picked winner must be a located candidate. duplicateOf is
+        // the exception: that winner was validated as an active memory and is
+        // intentionally not part of the mutated set.
+        if (
+          action.kind === "supersede" &&
+          action.winnerId &&
+          action.winnerId !== explicitWinner &&
+          !candidateIds.has(action.winnerId)
+        ) {
+          return false;
+        }
+        return true;
       });
       if (filtered.length < llm.actions.length) {
         const dropped = llm.actions.length - filtered.length;
@@ -290,6 +331,71 @@ export class CorrectionPlanner {
     return this.persist(plan, abortSignal);
   }
 
+  private async planExplicitDuplicate(
+    request: CorrectionRequest,
+    namespaces: readonly string[],
+    abortSignal?: AbortSignal,
+  ): Promise<{ loser: PlannerCandidate; llm: LlmClassificationResult }> {
+    const winnerId = request.duplicateOf;
+    if (!winnerId || !request.targetIds || request.targetIds.length !== 1) {
+      throw new CorrectionContractError(
+        "CorrectionRequest.duplicateOf requires exactly one targetIds entry (the duplicate memory).",
+      );
+    }
+    if (request.targetIds[0] === winnerId) {
+      throw new CorrectionContractError(
+        "CorrectionRequest.duplicateOf must be a different memory from targetIds.",
+      );
+    }
+    const loserId = request.targetIds[0];
+    const loser = await this.inspectDuplicateParty(loserId, namespaces, "target");
+    throwIfAborted(abortSignal, "correction planning aborted");
+    await this.inspectDuplicateParty(winnerId, namespaces, "duplicateOf");
+    throwIfAborted(abortSignal, "correction planning aborted");
+    return {
+      loser,
+      llm: {
+        classification: "outdated",
+        confidence: 1,
+        actions: [{ kind: "supersede", loserId, winnerId }],
+        relevance: [{
+          memoryId: loserId,
+          why: `duplicate of ${winnerId}; recoverable supersede`,
+        }],
+        warnings: [],
+      },
+    };
+  }
+
+  private async inspectDuplicateParty(
+    memoryId: string,
+    namespaces: readonly string[],
+    role: "target" | "duplicateOf",
+  ): Promise<PlannerCandidate> {
+    const notFound = role === "target"
+      ? `target memory not found: ${memoryId}`
+      : `duplicateOf memory not found: ${memoryId}`;
+    const inactive = (status: string) => role === "target"
+      ? `target memory is not active: ${memoryId} (${status})`
+      : `duplicateOf memory is not active: ${memoryId} (${status})`;
+    if (this.deps.inspectMemory) {
+      const found = await this.deps.inspectMemory({ memoryId, namespaces });
+      if (!found) throw new CorrectionContractError(notFound);
+      const status = found.status && found.status.length > 0 ? found.status : "active";
+      if (status !== "active") throw new CorrectionContractError(inactive(status));
+      return found.candidate;
+    }
+    try {
+      const resolved = await this.deps.resolveTargets({ targetIds: [memoryId], namespaces });
+      const candidate = resolved.find((item) => item.memoryId === memoryId) ?? resolved[0];
+      if (!candidate) throw new CorrectionContractError(notFound);
+      return candidate;
+    } catch (err) {
+      if (err instanceof CorrectionContractError) throw new CorrectionContractError(notFound);
+      throw err;
+    }
+  }
+
   private async locateCandidates(
     request: CorrectionRequest,
     namespaces: readonly string[],

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

@@ -39,7 +39,7 @@ function extractToolNames(response: unknown): Set<string> {
 }
 
 interface MockCalls {
-  planRequests: Array<{ text: string; targetIds?: string[]; principal?: string; abortSignal?: AbortSignal }>;
+  planRequests: Array<{ text: string; targetIds?: string[]; duplicateOf?: string; principal?: string; abortSignal?: AbortSignal }>;
   applyRequests: Array<{ planId: string; confirm: boolean; principal?: string; abortSignal?: AbortSignal }>;
 }
 
@@ -54,6 +54,7 @@ function makeMockService(
       req: {
         text: string;
         targetIds?: string[];
+        duplicateOf?: string;
         principal?: string;
       },
       opts?: { abortSignal?: AbortSignal },
@@ -128,6 +129,26 @@ test("tools/list gate: correction tools present when correctionVisible on (defau
   assert.equal(names.has("engram.memory_correct_apply"), true, "apply tool must be present by default");
   assert.equal(names.has("remnic_memory_correct_plan"), true, "plan alias must be present");
   assert.equal(names.has("remnic_memory_correct_apply"), true, "apply alias must be present");
+  const tools = (response as { result?: { tools?: Array<{ name?: string; inputSchema?: { properties?: Record<string, unknown> } }> } }).result?.tools ?? [];
+  const planTool = tools.find((tool) => tool.name === "engram.memory_correct_plan");
+  assert.ok(planTool?.inputSchema?.properties?.duplicateOf, "plan schema must advertise duplicateOf");
+});
+
+test("MCP surface: memory_correct_plan forwards duplicateOf", async () => {
+  const { service, calls } = makeMockService(STUB_PLAN, STUB_OUTCOME);
+  const server = new EngramMcpServer(service, { emitLegacyTools: true, correctionVisible: true });
+  await server.handleRequest({
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: {
+      name: "engram.memory_correct_plan",
+      arguments: { text: "duplicate", targetIds: ["mem-loser"], duplicateOf: "mem-winner" },
+    },
+  });
+  assert.equal(calls.planRequests.length, 1);
+  assert.deepEqual(calls.planRequests[0]?.targetIds, ["mem-loser"]);
+  assert.equal(calls.planRequests[0]?.duplicateOf, "mem-winner");
 });
 
 // ---------------------------------------------------------------------------