recallnest 1.4.1

package/src/conflict-engine.ts

@@ -0,0 +1,181 @@
+import { randomUUID } from "node:crypto";
+
+import { summarizeConflictAdvice } from "./conflict-advisor.js";
+import type { Embedder } from "./embedder.js";
+import {
+  extractBoundaryMetadata,
+  extractPromotedFrom,
+  normalizeCanonicalKey,
+  parseMetadataObject,
+} from "./memory-boundaries.js";
+import type { MemoryStore } from "./store.js";
+import {
+  type ConflictCandidateInput,
+  ConflictCandidateInputSchema,
+  type ConflictCandidateRecord,
+  ConflictCandidateRecordSchema,
+  type ConflictResolutionResult,
+  ConflictResolutionResultSchema,
+  type ResolveConflictInput,
+  ResolveConflictInputSchema,
+} from "./conflict-schema.js";
+import type { ConflictCandidateStore } from "./conflict-store.js";
+
+function normalizeFingerprintPart(value: string): string {
+  return normalizeCanonicalKey(value) || "na";
+}
+
+export function buildConflictFingerprint(params: {
+  canonicalKey: string;
+  existingMemoryId: string;
+  incomingText: string;
+  sourceMemoryId?: string;
+}): string {
+  return [
+    normalizeFingerprintPart(params.canonicalKey),
+    normalizeFingerprintPart(params.existingMemoryId),
+    normalizeFingerprintPart(params.sourceMemoryId || "no-source"),
+    normalizeFingerprintPart(params.incomingText),
+  ].join("--").slice(0, 240);
+}
+
+export function buildConflictCandidateRecord(rawInput: unknown): ConflictCandidateRecord {
+  const input = ConflictCandidateInputSchema.parse(rawInput);
+  return ConflictCandidateRecordSchema.parse({
+    ...input,
+    conflictId: randomUUID(),
+    status: "open",
+  });
+}
+
+export function reopenConflictCandidate(record: ConflictCandidateRecord): ConflictCandidateRecord {
+  const now = new Date().toISOString();
+  return ConflictCandidateRecordSchema.parse({
+    ...record,
+    status: "open",
+    reopenCount: (record.reopenCount || 0) + 1,
+    lastReopenedAt: now,
+    updatedAt: now,
+    resolvedAt: undefined,
+    resolutionNotes: undefined,
+  });
+}
+
+function buildMergedConflictMetadata(
+  record: ConflictCandidateRecord,
+  resolvedAt: string,
+  mergedText: string,
+): string {
+  const existingMetadata = parseMetadataObject(record.existing.metadata) ?? {};
+  const incomingMetadata = parseMetadataObject(record.incoming.metadata) ?? {};
+  const boundary = extractBoundaryMetadata(record.existing.metadata)
+    ?? extractBoundaryMetadata(record.incoming.metadata);
+  const promotedFrom = extractPromotedFrom(record.incoming.metadata)
+    ?? extractPromotedFrom(record.existing.metadata);
+  const source = typeof existingMetadata.source === "string"
+    ? existingMetadata.source
+    : typeof incomingMetadata.source === "string"
+      ? incomingMetadata.source
+      : record.incoming.source;
+
+  return JSON.stringify({
+    ...existingMetadata,
+    ...(source ? { source } : {}),
+    canonicalKey: record.canonicalKey,
+    ...(boundary ? { boundary } : {}),
+    ...(promotedFrom ? { promotedFrom } : {}),
+    mergedFrom: {
+      conflictId: record.conflictId,
+      resolvedAt,
+      existingMemoryId: record.existing.memoryId,
+      ...(record.incoming.sourceMemoryId ? { incomingSourceMemoryId: record.incoming.sourceMemoryId } : {}),
+      mergedText,
+    },
+  });
+}
+
+export interface ResolveConflictDeps {
+  store: Pick<MemoryStore, "getById" | "update">;
+  embedder: Pick<Embedder, "embedPassage">;
+  conflictStore: Pick<ConflictCandidateStore, "getById" | "replace">;
+}
+
+export async function resolveConflictCandidate(
+  deps: ResolveConflictDeps,
+  rawInput: unknown,
+): Promise<ConflictResolutionResult> {
+  const input = ResolveConflictInputSchema.parse(rawInput);
+  const record = await deps.conflictStore.getById(input.conflictId);
+
+  if (!record) {
+    throw new Error(`Conflict ${input.conflictId} not found`);
+  }
+  if (record.status !== "open") {
+    throw new Error(`Conflict ${input.conflictId} is already ${record.status}`);
+  }
+
+  const now = new Date().toISOString();
+  let updatedMemoryId: string | undefined;
+
+  if (input.resolution === "accept_incoming" || input.resolution === "merge") {
+    const existing = await deps.store.getById(record.existing.memoryId);
+    if (!existing) {
+      throw new Error(`Existing memory ${record.existing.memoryId} not found`);
+    }
+
+    let nextText = record.incoming.text;
+    let nextCategory = record.incoming.category;
+    let nextImportance = record.incoming.importance;
+    let nextMetadata = record.incoming.metadata;
+
+    if (input.resolution === "merge") {
+      if (record.existing.category !== record.incoming.category) {
+        throw new Error("Merge resolution only supports same-category durable conflicts");
+      }
+      const mergeSuggestion = summarizeConflictAdvice(record).mergeSuggestion;
+      const mergedText = input.mergedText || mergeSuggestion;
+      if (!mergedText) {
+        throw new Error("Merge resolution requires mergedText or an available merge suggestion");
+      }
+      nextText = mergedText;
+      nextCategory = record.existing.category;
+      nextImportance = Math.max(existing.importance, record.incoming.importance);
+      nextMetadata = buildMergedConflictMetadata(record, now, mergedText);
+    }
+
+    const vector = await deps.embedder.embedPassage(nextText);
+    const updated = await deps.store.update(existing.id, {
+      text: nextText,
+      vector,
+      importance: nextImportance,
+      category: nextCategory,
+      metadata: nextMetadata,
+      timestamp: Date.now(),
+    });
+    if (!updated) {
+      throw new Error(`Failed to update durable memory ${existing.id}`);
+    }
+    updatedMemoryId = updated.id;
+  }
+
+  const resolved = ConflictCandidateRecordSchema.parse({
+    ...record,
+    status: input.resolution === "accept_incoming"
+      ? "accepted-incoming"
+      : input.resolution === "merge"
+        ? "merged"
+        : "kept-existing",
+    updatedAt: now,
+    resolvedAt: now,
+    ...(input.notes ? { resolutionNotes: input.notes } : {}),
+  });
+  await deps.conflictStore.replace(resolved);
+
+  return ConflictResolutionResultSchema.parse({
+    conflictId: resolved.conflictId,
+    status: resolved.status,
+    updatedAt: resolved.updatedAt,
+    resolvedAt: resolved.resolvedAt,
+    ...(updatedMemoryId ? { updatedMemoryId } : {}),
+  });
+}

package/src/conflict-escalation.ts

@@ -0,0 +1,138 @@
+import type { ConflictSuggestedResolution, ConflictAdviceConfidence } from "./conflict-advisor.js";
+import { summarizeConflictAdvice } from "./conflict-advisor.js";
+import { type ConflictAttention, summarizeConflictLifecycle } from "./conflict-lifecycle.js";
+import {
+  type ConflictCandidateRecord,
+  ConflictCandidateRecordSchema,
+  type ConflictEscalationResultItem,
+  ConflictEscalationResultItemSchema,
+  type EscalateConflictsInput,
+  EscalateConflictsInputSchema,
+  type EscalateConflictsResult,
+  EscalateConflictsResultSchema,
+} from "./conflict-schema.js";
+import type { ConflictCandidateStore } from "./conflict-store.js";
+
+export type EscalationAttention = Extract<ConflictAttention, "stale" | "escalated">;
+
+export interface EscalateConflictsDeps {
+  conflictStore: Pick<ConflictCandidateStore, "listRecent" | "replace">;
+}
+
+function toEscalationAttention(attention: ConflictAttention): EscalationAttention | null {
+  return attention === "stale" || attention === "escalated" ? attention : null;
+}
+
+export function buildConflictEscalationItem(
+  record: ConflictCandidateRecord,
+  now = new Date(),
+): ConflictEscalationResultItem | null {
+  const lifecycle = summarizeConflictLifecycle(record, now);
+  const attention = toEscalationAttention(lifecycle.attention);
+  if (!attention) return null;
+
+  const advice = summarizeConflictAdvice(record);
+  const alreadyEscalated = record.lastEscalationAttention === attention;
+  return ConflictEscalationResultItemSchema.parse({
+    conflictId: record.conflictId,
+    canonicalKey: record.canonicalKey,
+    attention,
+    openAgeDays: lifecycle.openAgeDays,
+    reopenCount: lifecycle.reopenCount,
+    escalationCount: Math.max(0, record.escalationCount || 0),
+    suggestedResolution: advice.suggestedResolution,
+    confidence: advice.confidence,
+    action: alreadyEscalated ? "already-escalated" : "pending",
+    clusterKey: advice.clusterKey,
+  });
+}
+
+export function markConflictEscalated(
+  record: ConflictCandidateRecord,
+  params: {
+    attention: EscalationAttention;
+    notes?: string;
+    now?: Date;
+  },
+): ConflictCandidateRecord {
+  const nowIso = (params.now || new Date()).toISOString();
+  const note = params.notes?.trim();
+
+  return ConflictCandidateRecordSchema.parse({
+    ...record,
+    escalationCount: Math.max(0, record.escalationCount || 0) + 1,
+    lastEscalatedAt: nowIso,
+    lastEscalationAttention: params.attention,
+    updatedAt: nowIso,
+    ...(note ? { resolutionNotes: note } : {}),
+  });
+}
+
+function sortEscalationItems(items: ConflictEscalationResultItem[]): ConflictEscalationResultItem[] {
+  return [...items].sort((a, b) => {
+    const attentionRankA = a.attention === "escalated" ? 2 : 1;
+    const attentionRankB = b.attention === "escalated" ? 2 : 1;
+    if (attentionRankB !== attentionRankA) return attentionRankB - attentionRankA;
+    if (b.openAgeDays !== a.openAgeDays) return b.openAgeDays - a.openAgeDays;
+    if (b.reopenCount !== a.reopenCount) return b.reopenCount - a.reopenCount;
+    return a.conflictId.localeCompare(b.conflictId);
+  });
+}
+
+export async function escalateConflicts(
+  deps: EscalateConflictsDeps,
+  rawInput: unknown,
+  { now: nowOverride }: { now?: Date } = {},
+): Promise<EscalateConflictsResult> {
+  const input = EscalateConflictsInputSchema.parse(rawInput);
+  const now = nowOverride ?? new Date();
+  const records = await deps.conflictStore.listRecent({
+    status: "open",
+    canonicalKey: input.canonicalKey,
+    limit: input.limit,
+  });
+
+  const eligibleItems = sortEscalationItems(
+    records
+      .map((record) => buildConflictEscalationItem(record, now))
+      .filter((item): item is ConflictEscalationResultItem => Boolean(item))
+      .filter((item) => !input.attention || item.attention === input.attention)
+      .slice(0, input.top),
+  );
+
+  const items: ConflictEscalationResultItem[] = [];
+  let escalated = 0;
+
+  for (const item of eligibleItems) {
+    const record = records.find((candidate) => candidate.conflictId === item.conflictId);
+    if (!record) continue;
+
+    if (!input.apply || item.action === "already-escalated") {
+      items.push(item);
+      continue;
+    }
+
+    const updated = markConflictEscalated(record, {
+      attention: item.attention,
+      notes: input.notes,
+      now,
+    });
+    await deps.conflictStore.replace(updated);
+    escalated += 1;
+    items.push(ConflictEscalationResultItemSchema.parse({
+      ...item,
+      escalationCount: updated.escalationCount,
+      action: "escalated",
+    }));
+  }
+
+  return EscalateConflictsResultSchema.parse({
+    apply: input.apply,
+    scanned: records.length,
+    eligible: eligibleItems.length,
+    escalated,
+    skipped: eligibleItems.filter((item) => item.action === "already-escalated").length,
+    items,
+  });
+}
+

package/src/conflict-lifecycle.ts

@@ -0,0 +1,67 @@
+import type { ConflictCandidateRecord } from "./conflict-schema.js";
+
+export const CONFLICT_ATTENTION_LEVELS = [
+  "fresh",
+  "aging",
+  "stale",
+  "escalated",
+  "resolved",
+] as const;
+
+export type ConflictAttention = (typeof CONFLICT_ATTENTION_LEVELS)[number];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export interface ConflictLifecycleSummary {
+  attention: ConflictAttention;
+  openAgeDays: number;
+  reopenCount: number;
+  isOpen: boolean;
+  needsAttention: boolean;
+}
+
+export function parseConflictAttention(value?: string | null): ConflictAttention | undefined {
+  if (!value) return undefined;
+  return CONFLICT_ATTENTION_LEVELS.includes(value as ConflictAttention)
+    ? value as ConflictAttention
+    : undefined;
+}
+
+export function summarizeConflictLifecycle(
+  record: ConflictCandidateRecord,
+  now = new Date(),
+): ConflictLifecycleSummary {
+  const isOpen = record.status === "open";
+  const reopenCount = Math.max(0, record.reopenCount || 0);
+  if (!isOpen) {
+    return {
+      attention: "resolved",
+      openAgeDays: 0,
+      reopenCount,
+      isOpen: false,
+      needsAttention: false,
+    };
+  }
+
+  const openedAtRaw = record.lastReopenedAt || record.createdAt;
+  const openedAtMs = Date.parse(openedAtRaw);
+  const ageMs = Number.isFinite(openedAtMs) ? Math.max(0, now.getTime() - openedAtMs) : 0;
+  const openAgeDays = Math.floor(ageMs / DAY_MS);
+
+  let attention: ConflictAttention = "fresh";
+  if (openAgeDays >= 7 || reopenCount >= 3) {
+    attention = "escalated";
+  } else if (openAgeDays >= 3 || reopenCount >= 2) {
+    attention = "stale";
+  } else if (openAgeDays >= 1 || reopenCount >= 1) {
+    attention = "aging";
+  }
+
+  return {
+    attention,
+    openAgeDays,
+    reopenCount,
+    isOpen: true,
+    needsAttention: attention === "stale" || attention === "escalated",
+  };
+}

package/src/conflict-output.ts

@@ -0,0 +1,218 @@
+import type { ConflictCandidateRecord, ConflictResolutionResult } from "./conflict-schema.js";
+import type { ConflictAuditSummary, ConflictClusterSummary } from "./conflict-advisor.js";
+import { summarizeConflictAdvice } from "./conflict-advisor.js";
+import { summarizeConflictLifecycle } from "./conflict-lifecycle.js";
+import type { EscalateConflictsResult } from "./conflict-schema.js";
+
+export interface ConflictAuditRenderOptions {
+  generatedAt: string;
+  limit: number;
+  top: number;
+  status?: string;
+  canonicalKey?: string;
+}
+
+function shortAdviceLabel(record: ConflictCandidateRecord): string {
+  const advice = summarizeConflictAdvice(record);
+  const action = advice.suggestedResolution === "keep_existing"
+    ? "keep"
+    : advice.suggestedResolution === "accept_incoming"
+      ? "accept"
+      : "review";
+  const confidence = advice.confidence === "high"
+    ? "h"
+    : advice.confidence === "medium"
+      ? "m"
+      : "l";
+  return `${action}[${confidence}]`;
+}
+
+export function formatConflictList(records: ConflictCandidateRecord[]): string {
+  if (records.length === 0) return "No conflicts found.";
+
+  const lines = [
+    "ID       Status             Attention   Advice     Category     Canonical key                   Updated      Existing -> Incoming",
+    "-------- ------------------ ----------  ---------  ------------ ------------------------------ ----------  ------------------------------",
+  ];
+
+  for (const record of records) {
+    const lifecycle = summarizeConflictLifecycle(record);
+    lines.push(
+      `${record.conflictId.slice(0, 8).padEnd(8)} ${record.status.padEnd(18)} ${lifecycle.attention.padEnd(10)} ${shortAdviceLabel(record).padEnd(9)} ${record.category.padEnd(12)} ${record.canonicalKey.slice(0, 30).padEnd(30)} ${record.updatedAt.slice(0, 10)}  ${record.existing.memoryId.slice(0, 8)} -> ${record.incoming.sourceMemoryId?.slice(0, 8) || "manual"}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function formatConflictClusters(clusters: ConflictClusterSummary[]): string {
+  if (clusters.length === 0) return "No conflict clusters found.";
+
+  const lines = [
+    "Cluster                          Attention   Open/All  Advice     Category     Canonical key                   Latest      Latest ID",
+    "------------------------------  ----------  --------  ---------  ------------ ------------------------------ ----------  --------",
+  ];
+
+  for (const cluster of clusters) {
+    const action = cluster.suggestedResolution === "keep_existing"
+      ? "keep"
+      : cluster.suggestedResolution === "accept_incoming"
+        ? "accept"
+        : "review";
+    const confidence = cluster.confidence === "high"
+      ? "h"
+      : cluster.confidence === "medium"
+        ? "m"
+        : "l";
+    lines.push(
+      `${cluster.clusterKey.slice(0, 30).padEnd(30)}  ${cluster.attention.padEnd(10)}  ${`${cluster.openCount}/${cluster.totalCount}`.padEnd(8)}  ${`${action}[${confidence}]`.padEnd(9)} ${cluster.category.padEnd(12)} ${cluster.canonicalKey.slice(0, 30).padEnd(30)} ${cluster.latestUpdatedAt.slice(0, 10)}  ${cluster.latestConflictId.slice(0, 8)}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function formatConflictAudit(summary: ConflictAuditSummary): string {
+  const lines = [
+    "Conflict audit",
+    `Open conflicts : ${summary.openConflicts}/${summary.totalConflicts}`,
+    `Open clusters  : ${summary.openClusters}/${summary.totalClusters}`,
+    `Attention      : fresh=${summary.attentionCounts.fresh}, aging=${summary.attentionCounts.aging}, stale=${summary.attentionCounts.stale}, escalated=${summary.attentionCounts.escalated}, resolved=${summary.attentionCounts.resolved}`,
+    "",
+    "Suggested actions:",
+    ...summary.suggestedActions.map((action) => `- ${action}`),
+  ];
+
+  lines.push("");
+  lines.push("Priority clusters:");
+  if (summary.priorityClusters.length === 0) {
+    lines.push("- None");
+  } else {
+    lines.push(formatConflictClusters(summary.priorityClusters));
+  }
+
+  return lines.join("\n");
+}
+
+export function formatConflictAuditMarkdown(
+  summary: ConflictAuditSummary,
+  options: ConflictAuditRenderOptions,
+): string {
+  const lines = [
+    "# Conflict Audit",
+    "",
+    `- Generated: ${options.generatedAt}`,
+    `- Filters: status=${options.status || "all"}, canonicalKey=${options.canonicalKey || "all"}, limit=${options.limit}, top=${options.top}`,
+    `- Open conflicts: ${summary.openConflicts}/${summary.totalConflicts}`,
+    `- Open clusters: ${summary.openClusters}/${summary.totalClusters}`,
+    `- Attention: fresh=${summary.attentionCounts.fresh}, aging=${summary.attentionCounts.aging}, stale=${summary.attentionCounts.stale}, escalated=${summary.attentionCounts.escalated}, resolved=${summary.attentionCounts.resolved}`,
+    "",
+    "## Suggested Actions",
+    "",
+    ...summary.suggestedActions.map((action) => `- ${action}`),
+    "",
+    "## Priority Clusters",
+    "",
+  ];
+
+  if (summary.priorityClusters.length === 0) {
+    lines.push("- None");
+    return lines.join("\n");
+  }
+
+  summary.priorityClusters.forEach((cluster, index) => {
+    lines.push(`### ${index + 1}. ${cluster.clusterLabel}`);
+    lines.push("");
+    lines.push(`- Cluster key: ${cluster.clusterKey}`);
+    lines.push(`- Attention: ${cluster.attention}`);
+    lines.push(`- Open/All: ${cluster.openCount}/${cluster.totalCount}`);
+    lines.push(`- Advice: ${cluster.suggestedResolution} (${cluster.confidence})`);
+    lines.push(`- Canonical key: ${cluster.canonicalKey}`);
+    lines.push(`- Category: ${cluster.category}`);
+    lines.push(`- Latest conflict: ${cluster.latestConflictId}`);
+    lines.push(`- Updated: ${cluster.latestUpdatedAt}`);
+    lines.push("");
+  });
+
+  return lines.join("\n");
+}
+
+export function formatConflictRecord(record: ConflictCandidateRecord): string {
+  const lifecycle = summarizeConflictLifecycle(record);
+  const advice = summarizeConflictAdvice(record);
+  const lines = [
+    `Conflict ${record.conflictId.slice(0, 8)}`,
+    `Status: ${record.status}`,
+    `Attention: ${lifecycle.attention}`,
+    `Open age days: ${lifecycle.openAgeDays}`,
+    `Reopen count: ${lifecycle.reopenCount}`,
+    `Escalation count: ${record.escalationCount || 0}`,
+    `Suggested resolution: ${advice.suggestedResolution} (${advice.confidence})`,
+    `Similarity: ${advice.similarity}`,
+    `Cluster key: ${advice.clusterKey}`,
+    `Reason: ${record.reason}`,
+    `Canonical key: ${record.canonicalKey}`,
+    `Incoming category: ${record.category}`,
+    `Existing category: ${record.existing.category}`,
+    `Created: ${record.createdAt}`,
+    `Updated: ${record.updatedAt}`,
+    ...(record.lastReopenedAt ? [`Last reopened: ${record.lastReopenedAt}`] : []),
+    ...(record.lastEscalatedAt ? [`Last escalated: ${record.lastEscalatedAt} (${record.lastEscalationAttention})`] : []),
+    "",
+    `Existing durable (${record.existing.memoryId.slice(0, 8)}): ${record.existing.text}`,
+    `Incoming candidate (${record.incoming.sourceMemoryId?.slice(0, 8) || record.incoming.source}): ${record.incoming.text}`,
+  ];
+
+  if (record.resolutionNotes) {
+    lines.push(`Notes: ${record.resolutionNotes}`);
+  }
+  if (advice.mergeSuggestion) {
+    lines.push(`Merge suggestion: ${advice.mergeSuggestion}`);
+  }
+  if (advice.reasons.length > 0) {
+    lines.push("");
+    lines.push("Advice reasons:");
+    for (const reason of advice.reasons) {
+      lines.push(`- ${reason}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function formatConflictEscalation(result: EscalateConflictsResult): string {
+  const lines = [
+    result.apply ? "Conflict escalation applied" : "Conflict escalation preview",
+    `Scanned   : ${result.scanned}`,
+    `Eligible  : ${result.eligible}`,
+    `Escalated : ${result.escalated}`,
+    `Skipped   : ${result.skipped}`,
+  ];
+
+  if (result.items.length === 0) {
+    lines.push("");
+    lines.push("No stale or escalated conflicts matched.");
+    return lines.join("\n");
+  }
+
+  lines.push("");
+  lines.push("Items:");
+  for (const item of result.items) {
+    lines.push(
+      `${item.conflictId.slice(0, 8)}  ${item.attention.padEnd(10)} ${item.action.padEnd(17)} ${item.suggestedResolution.padEnd(15)} ${item.canonicalKey}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+export function formatConflictResolution(result: ConflictResolutionResult): string {
+  const lines = [
+    `Conflict ${result.conflictId.slice(0, 8)} resolved`,
+    `Status: ${result.status}`,
+    `Updated: ${result.updatedAt}`,
+  ];
+  if (result.updatedMemoryId) {
+    lines.push(`Updated memory: ${result.updatedMemoryId.slice(0, 8)}`);
+  }
+  return lines.join("\n");
+}