@remnic/core 9.65.1 → 9.65.3

package/dist/chunk-I32NKXE2.js

@@ -0,0 +1,879 @@
+import {
+  judgeContradictionPairs,
+  resolveScanStorage
+} from "./chunk-Q4WONDMJ.js";
+import {
+  CONTRADICTION_VERBS,
+  PREFERENCE_DRIFT_VERBS,
+  computeMemoryContentHash,
+  readPair,
+  resolvePair,
+  writePairs
+} from "./chunk-CTVWELNK.js";
+import {
+  composeMemoryEnvelope
+} from "./chunk-RAIUTAZZ.js";
+import {
+  bumpMemoryCorpusVersionForDir
+} from "./chunk-XCB6QDL6.js";
+import {
+  readJsonFile,
+  writeJsonFileAtomic
+} from "./chunk-P77QX3ID.js";
+import {
+  log
+} from "./chunk-3WCASNQZ.js";
+
+// src/preferences/preference-drift.ts
+import path from "path";
+var DRIFT_ACTOR = "preference-drift";
+var DRIFT_RULE_VERSION = "preference-drift:1";
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var EVIDENCE_LOOKUP_LIMIT = 5;
+function driftMarkerPath(memoryDir) {
+  return path.join(memoryDir, "state", "preference-drift.json");
+}
+async function readPreferenceDriftMarker(memoryDir) {
+  try {
+    const raw = await readJsonFile(driftMarkerPath(memoryDir));
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+    const m = raw;
+    if (typeof m.lastRunAt !== "string") return null;
+    return {
+      schemaVersion: 1,
+      lastRunAt: m.lastRunAt,
+      lastApplyAt: typeof m.lastApplyAt === "string" ? m.lastApplyAt : null,
+      appliedCount: typeof m.appliedCount === "number" ? m.appliedCount : 0
+    };
+  } catch {
+    return null;
+  }
+}
+function tsMs(value) {
+  if (typeof value !== "string") return null;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : null;
+}
+var CANDIDATE_STATUSES = { active: true };
+function compareCandidates(a, b) {
+  const aMs = tsMs(a.frontmatter.created) ?? tsMs(a.frontmatter.updated) ?? 0;
+  const bMs = tsMs(b.frontmatter.created) ?? tsMs(b.frontmatter.updated) ?? 0;
+  if (aMs !== bMs) return aMs < bMs ? -1 : 1;
+  const aId = a.frontmatter.id ?? "";
+  const bId = b.frontmatter.id ?? "";
+  if (aId !== bId) return aId < bId ? -1 : 1;
+  return 0;
+}
+async function gatherEvidence(preference, lookup, byId, windowStartMs, nowMs) {
+  let raw;
+  try {
+    raw = await lookup(preference.content, EVIDENCE_LOOKUP_LIMIT);
+  } catch (err) {
+    log.debug("[preference-drift] evidence lookup failed", {
+      memoryId: preference.frontmatter.id,
+      error: err instanceof Error ? err.message : String(err)
+    });
+    return { ok: false, reason: "backend_unavailable" };
+  }
+  const hits = [];
+  const hitMemories = [];
+  for (const hit of raw) {
+    if (hit.id === preference.frontmatter.id) continue;
+    const memory = byId.get(hit.id);
+    if (!memory) continue;
+    const observedMs = tsMs(memory.frontmatter.updated) ?? tsMs(memory.frontmatter.created);
+    if (observedMs === null) continue;
+    if (observedMs < windowStartMs || observedMs >= nowMs) continue;
+    hits.push({
+      memoryId: hit.id,
+      score: hit.score,
+      observedAt: memory.frontmatter.updated ?? memory.frontmatter.created ?? ""
+    });
+    hitMemories.push(memory);
+  }
+  return { ok: true, hits, hitMemories };
+}
+function classifyFromVerdicts(verdicts) {
+  const contradiction = verdicts.find((v) => v.verdict === "contradicts");
+  if (contradiction) {
+    return {
+      classification: "drifted",
+      reason: `recent evidence points away from this preference: ${contradiction.rationale}`,
+      driftedAgainst: contradiction.memoryIdB
+    };
+  }
+  const restatement = verdicts.find((v) => v.verdict === "duplicates");
+  if (restatement) {
+    return {
+      classification: "corroborated",
+      reason: `recent evidence restates this preference: ${restatement.rationale}`
+    };
+  }
+  if (verdicts.some((v) => v.verdict === "needs-user")) {
+    return {
+      classification: "skipped",
+      skipped: "verification_unavailable",
+      reason: "recent evidence found but no judge verdict was available to classify it"
+    };
+  }
+  return {
+    classification: "stale",
+    reason: "recent evidence is independent of this preference \u2014 no corroboration either way"
+  };
+}
+async function runPreferenceDriftScan(deps) {
+  const startTime = Date.now();
+  const now = deps.now ?? /* @__PURE__ */ new Date();
+  const nowIso = now.toISOString();
+  const nowMs = now.getTime();
+  const mode = deps.apply === true ? "apply" : "shadow";
+  const cfg = deps.config.driftDetection;
+  const emptyCounts = {
+    corroborated: 0,
+    stale: 0,
+    drifted: 0,
+    skipped: 0
+  };
+  if (cfg?.enabled !== true) {
+    return {
+      schemaVersion: 1,
+      generatedAt: nowIso,
+      mode,
+      scanned: 0,
+      eligible: 0,
+      findings: [],
+      counts: emptyCounts,
+      appliedCount: 0,
+      reviewItemsOpened: 0,
+      elapsedMs: Date.now() - startTime,
+      skippedReason: "drift_disabled"
+    };
+  }
+  if (cfg.maxCandidatesPerRun === 0) {
+    return {
+      schemaVersion: 1,
+      generatedAt: nowIso,
+      mode,
+      scanned: 0,
+      eligible: 0,
+      findings: [],
+      counts: emptyCounts,
+      appliedCount: 0,
+      reviewItemsOpened: 0,
+      elapsedMs: Date.now() - startTime,
+      skippedReason: "scan_disabled"
+    };
+  }
+  const { storage, namespace } = await resolveScanStorage(deps, deps.namespace?.trim() || void 0);
+  const lookup = deps.embeddingLookupFactory ? deps.embeddingLookupFactory(storage) : deps.embeddingLookup;
+  let all;
+  try {
+    all = await storage.readAllMemories();
+  } catch (err) {
+    log.warn(
+      `[preference-drift] failed to read memories: ${err instanceof Error ? err.message : String(err)}`
+    );
+    all = [];
+  }
+  const byId = /* @__PURE__ */ new Map();
+  for (const m of all) {
+    const id = m.frontmatter.id;
+    if (typeof id === "string" && id.length > 0) byId.set(id, m);
+  }
+  const minAgeMs = cfg.minAgeDays * DAY_MS;
+  const eligible = all.filter((m) => {
+    const fm = m.frontmatter;
+    if (fm.category !== "preference") return false;
+    if (CANDIDATE_STATUSES[fm.status ?? "active"] !== true) return false;
+    if (typeof fm.id !== "string" || fm.id.length === 0) return false;
+    if (!m.content || m.content.trim().length === 0) return false;
+    const bornMs = tsMs(fm.created) ?? tsMs(fm.updated);
+    if (bornMs === null) return false;
+    return nowMs - bornMs >= minAgeMs;
+  });
+  const candidates = [...eligible].sort(compareCandidates).slice(0, cfg.maxCandidatesPerRun);
+  const report = {
+    schemaVersion: 1,
+    generatedAt: nowIso,
+    mode,
+    namespace,
+    scanned: candidates.length,
+    eligible: eligible.length,
+    findings: [],
+    counts: { ...emptyCounts },
+    appliedCount: 0,
+    reviewItemsOpened: 0,
+    elapsedMs: 0
+  };
+  const windowStartMs = nowMs - cfg.lookbackDays * DAY_MS;
+  const judgeCache = /* @__PURE__ */ new Map();
+  const driftedPairs = [];
+  const stamps = [];
+  for (const preference of candidates) {
+    const bornMs = tsMs(preference.frontmatter.created) ?? tsMs(preference.frontmatter.updated) ?? nowMs;
+    const finding = {
+      memoryId: preference.frontmatter.id,
+      classification: "stale",
+      ageDays: Math.floor((nowMs - bornMs) / DAY_MS),
+      lastCorroborated: preference.frontmatter.lastCorroborated ?? null,
+      reason: "",
+      evidence: []
+    };
+    if (!lookup) {
+      finding.classification = "skipped";
+      finding.skipped = "backend_unavailable";
+      finding.reason = "no evidence lookup is configured, so corroboration cannot be checked";
+      report.findings.push(finding);
+      report.counts.skipped += 1;
+      continue;
+    }
+    const evidence = await gatherEvidence(preference, lookup, byId, windowStartMs, nowMs);
+    if (!evidence.ok) {
+      finding.classification = "skipped";
+      finding.skipped = evidence.reason;
+      finding.reason = "evidence lookup backend was unavailable \u2014 not classified as stale";
+      report.findings.push(finding);
+      report.counts.skipped += 1;
+      continue;
+    }
+    finding.evidence = evidence.hits;
+    if (evidence.hits.length === 0) {
+      finding.classification = "stale";
+      finding.reason = `no corroborating evidence in the last ${cfg.lookbackDays} days`;
+      report.findings.push(finding);
+      report.counts.stale += 1;
+      stamps.push({ memory: preference, patch: { driftState: "stale" }, reasonCode: "drift_stale" });
+      continue;
+    }
+    const judgeInputs = evidence.hitMemories.map((hit) => ({
+      memoryIdA: preference.frontmatter.id,
+      memoryIdB: hit.frontmatter.id,
+      textA: preference.content,
+      textB: hit.content,
+      categoryA: preference.frontmatter.category,
+      categoryB: hit.frontmatter.category
+    }));
+    const judged = await judgeContradictionPairs(
+      judgeInputs,
+      deps.config,
+      deps.localLlm,
+      deps.fallbackLlm,
+      judgeCache
+    );
+    const orderedVerdicts = [];
+    for (const input of judgeInputs) {
+      for (const result of judged.results.values()) {
+        if (result.memoryIdA === input.memoryIdA && result.memoryIdB === input.memoryIdB) {
+          orderedVerdicts.push(result);
+          break;
+        }
+      }
+    }
+    const outcome = classifyFromVerdicts(orderedVerdicts);
+    finding.classification = outcome.classification;
+    finding.reason = outcome.reason;
+    if (outcome.skipped) finding.skipped = outcome.skipped;
+    report.findings.push(finding);
+    report.counts[outcome.classification] += 1;
+    if (outcome.classification === "corroborated") {
+      stamps.push({
+        memory: preference,
+        patch: { lastCorroborated: nowIso, driftState: void 0 },
+        reasonCode: "drift_corroborated"
+      });
+    } else if (outcome.classification === "stale") {
+      stamps.push({ memory: preference, patch: { driftState: "stale" }, reasonCode: "drift_stale" });
+    } else if (outcome.classification === "drifted" && outcome.driftedAgainst) {
+      const verdict = orderedVerdicts.find((v) => v.verdict === "contradicts");
+      driftedPairs.push({
+        preference,
+        evidenceId: outcome.driftedAgainst,
+        finding,
+        rationale: verdict?.rationale ?? outcome.reason,
+        confidence: verdict?.confidence ?? 0
+      });
+    }
+  }
+  if (mode === "shadow") {
+    report.elapsedMs = Date.now() - startTime;
+    return report;
+  }
+  let writes = 0;
+  for (const stamp of stamps) {
+    try {
+      await storage.writeMemoryFrontmatter(stamp.memory, { ...stamp.patch, updated: nowIso }, {
+        at: now,
+        actor: DRIFT_ACTOR,
+        reasonCode: stamp.reasonCode,
+        ruleVersion: DRIFT_RULE_VERSION
+      });
+      writes += 1;
+      report.appliedCount += 1;
+    } catch (err) {
+      log.warn(
+        `[preference-drift] stamp ${stamp.reasonCode} on ${stamp.memory.frontmatter.id} failed: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  if (driftedPairs.length > 0) {
+    const queueEntries = driftedPairs.map((d) => ({
+      memoryIds: [d.preference.frontmatter.id, d.evidenceId],
+      kind: "preference-drift",
+      // A drift finding IS a detected conflict, so the honest verdict is
+      // `contradicts`; `kind` is what distinguishes it from a pair the
+      // contradiction scan produced. Existing review surfaces render it
+      // unchanged.
+      verdict: "contradicts",
+      rationale: d.rationale,
+      confidence: d.confidence,
+      detectedAt: nowIso,
+      memoryContentHashes: {
+        [d.preference.frontmatter.id]: computeMemoryContentHash(
+          d.preference.content,
+          d.preference.frontmatter.category
+        )
+      },
+      namespace
+    }));
+    const written = writePairs(deps.memoryDir, queueEntries);
+    report.reviewItemsOpened = written.length;
+    report.appliedCount += written.length;
+    for (const entry of written) {
+      const match = driftedPairs.find((d) => d.preference.frontmatter.id === entry.memoryIds[0]);
+      if (match) match.finding.reviewPairId = entry.pairId;
+    }
+  }
+  if (writes > 0) {
+    bumpMemoryCorpusVersionForDir(storage.dir);
+    if (storage.dir !== deps.memoryDir) bumpMemoryCorpusVersionForDir(deps.memoryDir);
+  }
+  try {
+    await writeJsonFileAtomic(driftMarkerPath(deps.memoryDir), {
+      schemaVersion: 1,
+      lastRunAt: nowIso,
+      lastApplyAt: nowIso,
+      appliedCount: report.appliedCount
+    });
+  } catch (err) {
+    log.warn(
+      `[preference-drift] failed to persist run marker: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  report.elapsedMs = Date.now() - startTime;
+  return report;
+}
+async function resolvePreferenceDrift(storage, pair, verb, options = {}) {
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const nowIso = now.toISOString();
+  const preferenceId = pair.memoryIds[0];
+  const preference = await storage.getMemoryById(preferenceId);
+  if (!preference) {
+    return { affectedIds: [], message: `Preference ${preferenceId} not found; not resolving ${pair.pairId}` };
+  }
+  const touched = () => {
+    try {
+      options.onMemoryWritten?.(pair.namespace, storage.dir);
+    } catch (err) {
+      log.warn(
+        `[preference-drift] catalog write touch failed for ${pair.pairId}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  };
+  if (verb === "keep") {
+    await storage.writeMemoryFrontmatter(
+      preference,
+      { lastCorroborated: nowIso, driftState: void 0, updated: nowIso },
+      { at: now, actor: DRIFT_ACTOR, reasonCode: "drift_kept", ruleVersion: DRIFT_RULE_VERSION }
+    );
+    bumpMemoryCorpusVersionForDir(storage.dir);
+    touched();
+    return { affectedIds: [preferenceId], message: `Preference ${preferenceId} confirmed still current` };
+  }
+  if (verb === "archive") {
+    const archivedPath = await storage.archiveMemory(preference, {
+      at: now,
+      actor: DRIFT_ACTOR,
+      reasonCode: "drift_archived",
+      ruleVersion: DRIFT_RULE_VERSION,
+      relatedMemoryIds: [pair.memoryIds[1]]
+    });
+    if (archivedPath === null) {
+      return { affectedIds: [], message: `Preference ${preferenceId} could not be archived; not resolving` };
+    }
+    bumpMemoryCorpusVersionForDir(storage.dir);
+    touched();
+    return { affectedIds: [preferenceId], message: `Preference ${preferenceId} archived` };
+  }
+  const replacementText = options.mergedContent?.trim();
+  if (!replacementText) {
+    return {
+      affectedIds: [],
+      message: "supersede requires mergedContent carrying the updated preference; no memories changed"
+    };
+  }
+  const envelope = composeMemoryEnvelope(
+    {
+      content: replacementText,
+      category: "preference",
+      confidence: preference.frontmatter.confidence ?? 0.8,
+      tags: ["preference-drift", "supersede"],
+      entityRef: preference.frontmatter.entityRef
+    },
+    { source: DRIFT_ACTOR },
+    { salvage: true }
+  );
+  if (envelope.salvageNotes.length > 0) {
+    log.warn(`[preference-drift] supersede write salvaged invalid fields: ${envelope.salvageNotes.join("; ")}`);
+  }
+  const written = await storage.writeSealedMemory(envelope, {
+    actor: DRIFT_ACTOR,
+    lineage: [preferenceId],
+    // `update` is the operator for "newer version of the same claim" — the
+    // drift replacement restates one preference, it does not merge two.
+    derivedVia: "update"
+  });
+  if (written.tombstoneBlocked) {
+    return {
+      affectedIds: [],
+      message: `Replacement preference for ${pair.pairId} was tombstone-blocked (pending_review); not resolving \u2014 original kept active`
+    };
+  }
+  const superseded = await storage.supersedeMemory(
+    preferenceId,
+    written.id,
+    `preference drift resolved by supersede (${pair.pairId})`,
+    void 0,
+    { actor: DRIFT_ACTOR }
+  );
+  bumpMemoryCorpusVersionForDir(storage.dir);
+  touched();
+  if (!superseded) {
+    return {
+      affectedIds: [written.id],
+      message: `Replacement ${written.id} written but superseding ${preferenceId} failed; both remain \u2014 re-run resolution`
+    };
+  }
+  return {
+    affectedIds: [preferenceId, written.id],
+    message: `Preference ${preferenceId} superseded by ${written.id}`
+  };
+}
+
+// src/contradiction/resolution.ts
+var VALID_VERBS = [...CONTRADICTION_VERBS, ...PREFERENCE_DRIFT_VERBS];
+function isValidResolutionVerb(value) {
+  return VALID_VERBS.includes(value);
+}
+async function executeResolution(memoryDir, storage, pairId, verb, options = {}) {
+  if (typeof verb !== "string" || !isValidResolutionVerb(verb)) {
+    throw new Error(`Invalid contradiction resolution verb: ${String(verb)}`);
+  }
+  const pair = readPair(memoryDir, pairId);
+  if (!pair) {
+    return { pairId, verb, affectedIds: [], message: `Pair ${pairId} not found` };
+  }
+  if (pair.namespace && !options.storageForNamespace) {
+    throw new Error(
+      "contradiction resolution requires storageForNamespace for namespaced pairs so callers resolve the correct namespace storage"
+    );
+  }
+  const resolutionStorage = options.storageForNamespace ? await options.storageForNamespace(pair.namespace) : storage;
+  if (pair.resolution && pair.resolution !== "needs-more-context") {
+    return { pairId, verb, affectedIds: [], message: `Pair already resolved with verb "${pair.resolution}"` };
+  }
+  const isDriftItem = pair.kind === "preference-drift";
+  const verbMatchesKind = isDriftItem ? PREFERENCE_DRIFT_VERBS.includes(verb) : CONTRADICTION_VERBS.includes(verb);
+  if (!verbMatchesKind) {
+    const allowed = (isDriftItem ? PREFERENCE_DRIFT_VERBS : CONTRADICTION_VERBS).join(", ");
+    return {
+      pairId,
+      verb,
+      affectedIds: [],
+      message: `Verb "${verb}" is not valid for a ${isDriftItem ? "preference-drift" : "contradiction"} item. Valid: ${allowed}`
+    };
+  }
+  if (isDriftItem) {
+    const outcome = await resolvePreferenceDrift(
+      resolutionStorage,
+      pair,
+      verb,
+      {
+        mergedContent: options.mergedContent,
+        onMemoryWritten: options.onMergedMemoryWritten
+      }
+    );
+    if (outcome.affectedIds.length > 0) resolvePair(memoryDir, pairId, verb);
+    return { pairId, verb, affectedIds: outcome.affectedIds, message: outcome.message };
+  }
+  const [idA, idB] = pair.memoryIds;
+  const affectedIds = [];
+  let message = "";
+  let supersedeFailed = false;
+  let rollbackAfterResolveFailure = null;
+  let recordCatalogWriteTouch = null;
+  const buildCatalogTouch = () => {
+    if (!options.onMergedMemoryWritten) return null;
+    const onMergedMemoryWritten = options.onMergedMemoryWritten;
+    const namespace = pair.namespace;
+    const storageDir = resolutionStorage.dir;
+    return () => onMergedMemoryWritten(namespace, storageDir);
+  };
+  const catalogWriteTouch = buildCatalogTouch();
+  const recordCatalogWriteTouchSafely = (context, touch = catalogWriteTouch) => {
+    if (!touch) return;
+    try {
+      touch();
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] catalog write touch failed for pair=%s context=%s: %s",
+        pairId,
+        context,
+        err instanceof Error ? err.message : err
+      );
+    }
+  };
+  const touchCatalogIfRollbackLeftChange = async (context, snapshots, replacement) => {
+    if (!catalogWriteTouch) return;
+    if (await rollbackLeftDurableMutation(resolutionStorage, snapshots, replacement)) {
+      recordCatalogWriteTouchSafely(context);
+    }
+  };
+  switch (verb) {
+    case "keep-a": {
+      const keepTarget = await validateKeepTarget(resolutionStorage, pairId, idA);
+      if (!keepTarget.ok) {
+        supersedeFailed = true;
+        message = keepTarget.message;
+        break;
+      }
+      const sourceB = await loadSourceSnapshot(resolutionStorage, idB);
+      const ok = sourceB ? await supersedeSafe(resolutionStorage, idB, idA, "contradiction-resolution:keep-a") : false;
+      if (ok) {
+        affectedIds.push(idB);
+        rollbackAfterResolveFailure = async () => restoreMemorySnapshot(resolutionStorage, sourceB, "contradiction-resolution:keep-a-rollback");
+        recordCatalogWriteTouch = catalogWriteTouch;
+        message = `Kept ${idA}, superseded ${idB}`;
+      } else {
+        supersedeFailed = true;
+        const rolledBack = sourceB ? await restoreMemorySnapshot(resolutionStorage, sourceB, "contradiction-resolution:keep-a-rollback") : false;
+        if (sourceB && !rolledBack) {
+          await touchCatalogIfRollbackLeftChange("keep-a-rollback-incomplete", [sourceB]);
+        }
+        message = rolledBack ? `Supersede failed for ${idB}; restored ${idB} and did not resolve` : `Supersede failed for ${idB}; rollback incomplete for ${idB} and pair is not resolved`;
+      }
+      break;
+    }
+    case "keep-b": {
+      const keepTarget = await validateKeepTarget(resolutionStorage, pairId, idB);
+      if (!keepTarget.ok) {
+        supersedeFailed = true;
+        message = keepTarget.message;
+        break;
+      }
+      const sourceA = await loadSourceSnapshot(resolutionStorage, idA);
+      const ok = sourceA ? await supersedeSafe(resolutionStorage, idA, idB, "contradiction-resolution:keep-b") : false;
+      if (ok) {
+        affectedIds.push(idA);
+        rollbackAfterResolveFailure = async () => restoreMemorySnapshot(resolutionStorage, sourceA, "contradiction-resolution:keep-b-rollback");
+        recordCatalogWriteTouch = catalogWriteTouch;
+        message = `Kept ${idB}, superseded ${idA}`;
+      } else {
+        supersedeFailed = true;
+        const rolledBack = sourceA ? await restoreMemorySnapshot(resolutionStorage, sourceA, "contradiction-resolution:keep-b-rollback") : false;
+        if (sourceA && !rolledBack) {
+          await touchCatalogIfRollbackLeftChange("keep-b-rollback-incomplete", [sourceA]);
+        }
+        message = rolledBack ? `Supersede failed for ${idA}; restored ${idA} and did not resolve` : `Supersede failed for ${idA}; rollback incomplete for ${idA} and pair is not resolved`;
+      }
+      break;
+    }
+    case "merge": {
+      const replacement = await prepareMergeReplacement(resolutionStorage, pairId, idA, idB, options);
+      if (!replacement.ok) {
+        supersedeFailed = true;
+        message = replacement.message;
+        break;
+      }
+      const okA = await supersedeSafe(resolutionStorage, idA, replacement.mergedId, "contradiction-resolution:merge");
+      if (!okA) {
+        supersedeFailed = true;
+        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);
+        message = rolledBackA ? `Merge failed for ${idA}; restored ${idA} and did not resolve` : `Merge failed for ${idA}; rollback incomplete for ${idA} and pair is not resolved`;
+        if (rolledBackA) {
+          await cleanupCreatedReplacement(resolutionStorage, replacement);
+        } else {
+          await touchCatalogIfRollbackLeftChange("merge-first-rollback-incomplete", [replacement.sourceA], replacement);
+        }
+        break;
+      }
+      const okB = await supersedeSafe(resolutionStorage, idB, replacement.mergedId, "contradiction-resolution:merge");
+      if (!okB) {
+        supersedeFailed = true;
+        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);
+        const rolledBackB = await restoreMemorySnapshot(resolutionStorage, replacement.sourceB);
+        message = rolledBackA && rolledBackB ? `Merge failed for ${idB}; restored ${idA} and ${idB} and did not resolve` : `Merge failed for ${idB}; rollback incomplete for ${[
+          rolledBackA ? void 0 : idA,
+          rolledBackB ? void 0 : idB
+        ].filter(Boolean).join(", ")} and pair is not resolved`;
+        if (rolledBackA && rolledBackB) {
+          await cleanupCreatedReplacement(resolutionStorage, replacement);
+        } else {
+          await touchCatalogIfRollbackLeftChange(
+            "merge-second-rollback-incomplete",
+            [replacement.sourceA, replacement.sourceB],
+            replacement
+          );
+        }
+        break;
+      }
+      affectedIds.push(idA, idB);
+      rollbackAfterResolveFailure = async () => {
+        const rolledBackA = await restoreMemorySnapshot(resolutionStorage, replacement.sourceA);
+        const rolledBackB = await restoreMemorySnapshot(resolutionStorage, replacement.sourceB);
+        if (rolledBackA && rolledBackB) {
+          await cleanupCreatedReplacement(resolutionStorage, replacement);
+        }
+        return rolledBackA && rolledBackB;
+      };
+      recordCatalogWriteTouch = catalogWriteTouch;
+      message = `Both memories superseded by merged ${replacement.mergedId}`;
+      break;
+    }
+    case "both-valid": {
+      message = "Pair marked as both-valid; cooldown applied";
+      break;
+    }
+    case "needs-more-context": {
+      message = "Deferred; no action taken, short cooldown applied";
+      break;
+    }
+  }
+  if (!supersedeFailed) {
+    let resolved = false;
+    try {
+      resolved = resolvePair(memoryDir, pairId, verb) !== null;
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] failed to persist pair=%s verb=%s: %s",
+        pairId,
+        verb,
+        err instanceof Error ? err.message : err
+      );
+    }
+    if (!resolved) {
+      if (rollbackAfterResolveFailure) {
+        const rolledBack = await rollbackAfterResolveFailure();
+        affectedIds.length = 0;
+        message = rolledBack ? `Resolution persistence failed; rolled back memory changes and did not resolve ${pairId}` : "Resolution persistence failed; rollback incomplete and pair is not resolved";
+        if (!rolledBack && recordCatalogWriteTouch) {
+          recordCatalogWriteTouchSafely("resolve-persistence-rollback-incomplete", recordCatalogWriteTouch);
+        }
+      } else {
+        message = "Resolution persistence failed; pair is not resolved";
+      }
+    } else if (recordCatalogWriteTouch) {
+      recordCatalogWriteTouchSafely("resolved", recordCatalogWriteTouch);
+    }
+  }
+  log.info("[contradiction-resolution] pair=%s verb=%s affected=%d", pairId, verb, affectedIds.length);
+  return { pairId, verb, affectedIds, message };
+}
+async function prepareMergeReplacement(storage, pairId, idA, idB, options) {
+  const sourceA = await storage.getMemoryById(idA);
+  const sourceB = await storage.getMemoryById(idB);
+  if (!sourceA || !sourceB) {
+    return { ok: false, message: `Merge requires both source memories to exist; not resolving ${pairId}` };
+  }
+  const requestedMergedId = options.mergedMemoryId?.trim();
+  if (requestedMergedId) {
+    if (requestedMergedId === idA || requestedMergedId === idB) {
+      return { ok: false, message: "Merge replacement must be distinct from both source memories; not resolving" };
+    }
+    const replacement2 = await storage.getMemoryById(requestedMergedId);
+    if (!replacement2) {
+      return { ok: false, message: `Merged memory ${requestedMergedId} not found; not resolving` };
+    }
+    const replacementStatus = replacement2.frontmatter.status ?? "active";
+    if (replacementStatus !== "active") {
+      return {
+        ok: false,
+        message: `Merged memory ${requestedMergedId} is ${replacementStatus}; not resolving`
+      };
+    }
+    return { ok: true, mergedId: requestedMergedId, sourceA, sourceB, created: false };
+  }
+  const mergedContent = options.mergedContent;
+  if (typeof mergedContent !== "string" || mergedContent.trim().length === 0) {
+    return {
+      ok: false,
+      message: "Merge requires mergedMemoryId or mergedContent; no memories changed"
+    };
+  }
+  const category = options.mergedCategory ?? mergedMemoryCategory(sourceA, sourceB);
+  let mergedId;
+  try {
+    const mergeEnvelope = composeMemoryEnvelope(
+      {
+        content: mergedContent,
+        category,
+        confidence: Math.min(sourceA.frontmatter.confidence ?? 0.8, sourceB.frontmatter.confidence ?? 0.8),
+        tags: ["contradiction-resolution", "merge"]
+      },
+      { source: "contradiction-resolution" },
+      { salvage: true }
+    );
+    if (mergeEnvelope.salvageNotes.length > 0) {
+      log.warn(`contradiction-resolution write salvaged invalid fields: ${mergeEnvelope.salvageNotes.join("; ")}`);
+    }
+    const mergeResult = await storage.writeSealedMemory(mergeEnvelope, {
+      actor: "contradiction-resolution",
+      lineage: [idA, idB],
+      derivedVia: "merge"
+    });
+    mergedId = mergeResult.id;
+    if (mergeResult.tombstoneBlocked) {
+      await cleanupMemoryId(storage, mergedId);
+      return { ok: false, message: `Merged memory for ${pairId} was tombstone-blocked (pending_review); not resolving \u2014 sources kept active` };
+    }
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] merged memory creation failed for %s: %s",
+      pairId,
+      err instanceof Error ? err.message : err
+    );
+    return { ok: false, message: `Merged memory could not be created; not resolving ${pairId}` };
+  }
+  const replacement = await storage.getMemoryById(mergedId);
+  if (!replacement) {
+    await cleanupMemoryId(storage, mergedId);
+    return { ok: false, message: `Merged memory ${mergedId} could not be verified; not resolving` };
+  }
+  return { ok: true, mergedId, sourceA, sourceB, created: true };
+}
+function mergedMemoryCategory(sourceA, sourceB) {
+  return sourceA.frontmatter.category === sourceB.frontmatter.category ? sourceA.frontmatter.category : "fact";
+}
+async function validateKeepTarget(storage, pairId, keepId) {
+  const target = await loadSourceSnapshot(storage, keepId);
+  if (!target) {
+    return { ok: false, message: `Kept memory ${keepId} not found; not resolving ${pairId}` };
+  }
+  const status = target.frontmatter.status ?? "active";
+  if (status !== "active") {
+    return { ok: false, message: `Kept memory ${keepId} is ${status}; not resolving ${pairId}` };
+  }
+  return { ok: true };
+}
+async function loadSourceSnapshot(storage, memoryId) {
+  try {
+    return await storage.getMemoryById(memoryId);
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] source snapshot failed for %s: %s",
+      memoryId,
+      err instanceof Error ? err.message : err
+    );
+    return null;
+  }
+}
+async function restoreMemorySnapshot(storage, memory, reasonCode = "contradiction-resolution:merge-rollback") {
+  try {
+    const current = await storage.getMemoryById(memory.frontmatter.id);
+    if (!current) return false;
+    const restoredFrontmatter = {
+      ...memory.frontmatter,
+      status: memory.frontmatter.status,
+      supersededBy: memory.frontmatter.supersededBy,
+      supersededAt: memory.frontmatter.supersededAt
+    };
+    return await storage.writeMemoryFrontmatter(current, restoredFrontmatter, {
+      actor: "contradiction-resolution",
+      reasonCode
+    });
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] rollback failed for %s: %s",
+      memory.frontmatter.id,
+      err instanceof Error ? err.message : err
+    );
+    return false;
+  }
+}
+async function rollbackLeftDurableMutation(storage, snapshots, replacement) {
+  for (const snapshot of snapshots) {
+    try {
+      const current = await storage.getMemoryById(snapshot.frontmatter.id);
+      if (!current) return true;
+      if (supersessionStateChanged(current, snapshot)) return true;
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] rollback inspection failed for %s: %s",
+        snapshot.frontmatter.id,
+        err instanceof Error ? err.message : err
+      );
+      return true;
+    }
+  }
+  if (replacement?.created) {
+    try {
+      return await storage.getMemoryById(replacement.mergedId) !== null;
+    } catch (err) {
+      log.warn(
+        "[contradiction-resolution] rollback replacement inspection failed for %s: %s",
+        replacement.mergedId,
+        err instanceof Error ? err.message : err
+      );
+      return true;
+    }
+  }
+  return false;
+}
+function supersessionStateChanged(current, snapshot) {
+  return current.frontmatter.status !== snapshot.frontmatter.status || current.frontmatter.supersededBy !== snapshot.frontmatter.supersededBy || current.frontmatter.supersededAt !== snapshot.frontmatter.supersededAt;
+}
+async function cleanupCreatedReplacement(storage, replacement) {
+  if (!replacement.created) return;
+  await cleanupMemoryId(storage, replacement.mergedId);
+}
+async function cleanupMemoryId(storage, memoryId) {
+  try {
+    const memory = await storage.getMemoryById(memoryId);
+    const invalidated = await storage.invalidateMemory(memoryId);
+    if (invalidated && memory?.frontmatter.category === "fact") {
+      await storage.removeFactContentHashesForMemories([memory]);
+    }
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] cleanup failed for merged memory %s: %s",
+      memoryId,
+      err instanceof Error ? err.message : err
+    );
+  }
+}
+async function supersedeSafe(storage, oldId, newId, reason) {
+  try {
+    const result = await storage.supersedeMemory(oldId, newId, reason);
+    if (result === false) {
+      log.warn("[contradiction-resolution] supersede returned false for %s \u2192 %s", oldId, newId);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    log.warn(
+      "[contradiction-resolution] supersede failed %s \u2192 %s: %s",
+      oldId,
+      newId,
+      err instanceof Error ? err.message : err
+    );
+    return false;
+  }
+}
+
+export {
+  readPreferenceDriftMarker,
+  runPreferenceDriftScan,
+  resolvePreferenceDrift,
+  isValidResolutionVerb,
+  executeResolution
+};
+//# sourceMappingURL=chunk-I32NKXE2.js.map