recallnest 1.4.1

package/src/__tests__/conflict-advisor.test.ts

@@ -0,0 +1,206 @@
+import { describe, expect, it } from "bun:test";
+
+import { buildConflictCandidateRecord } from "../conflict-engine.js";
+import { buildConflictAuditSummary, clusterConflicts, summarizeConflictAdvice } from "../conflict-advisor.js";
+
+/** Returns an ISO timestamp N days before now (defaults to 4 days = firmly "stale"). */
+function daysAgo(n: number): string {
+  return new Date(Date.now() - n * 24 * 60 * 60 * 1000).toISOString();
+}
+
+function createConflictRecord(overrides: Record<string, unknown> = {}) {
+  const defaultTs = daysAgo(4); // 4 days ago → "stale" (3-6 days range)
+  return {
+    ...buildConflictCandidateRecord({
+      canonicalKey: "user-reply-style",
+      category: "preferences",
+      fingerprint: "user-reply-style--durable-1--source-1--new-text",
+      reason: "promotion_conflicts_with_existing_durable",
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise, direct, technical replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers concise direct technical replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+      createdAt: defaultTs,
+      updatedAt: defaultTs,
+    }),
+    ...overrides,
+  };
+}
+
+describe("summarizeConflictAdvice", () => {
+  it("suggests keep_existing for text-equivalent conflicts", () => {
+    const advice = summarizeConflictAdvice(createConflictRecord() as any);
+
+    expect(advice.suggestedResolution).toBe("keep_existing");
+    expect(advice.confidence).toBe("high");
+    expect(advice.similarity).toBe(1);
+  });
+
+  it("suggests keep_existing for cross-category canonical key conflicts", () => {
+    const advice = summarizeConflictAdvice(createConflictRecord({
+      reason: "canonical_key_conflicts_with_existing_durable",
+      category: "events",
+      incoming: {
+        text: "Reply-style observation imported as an event.",
+        category: "events",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-2",
+        sourceCategory: "events",
+      },
+    }) as any);
+
+    expect(advice.suggestedResolution).toBe("keep_existing");
+    expect(["medium", "high"]).toContain(advice.confidence);
+    expect(advice.reasons.some((reason) => reason.includes("canonical key"))).toBe(true);
+  });
+
+  it("suggests accept_incoming when the incoming text is a tighter rewrite of the same memory", () => {
+    const advice = summarizeConflictAdvice(createConflictRecord({
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise grounded technical replies and avoids sales language in the final copy.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers concise grounded technical replies and avoids sales language.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+    }) as any);
+
+    expect(advice.suggestedResolution).toBe("accept_incoming");
+    expect(advice.confidence).toBe("medium");
+    expect(advice.similarity).toBeGreaterThanOrEqual(0.72);
+    expect(advice.mergeSuggestion).toBeUndefined();
+  });
+
+  it("offers a merged wording suggestion for same-category manual_review conflicts", () => {
+    const advice = summarizeConflictAdvice(createConflictRecord({
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise grounded technical replies; avoid sales language.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers concise grounded technical replies; keep the tone colloquial.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+    }) as any);
+
+    expect(advice.suggestedResolution).toBe("manual_review");
+    expect(advice.mergeSuggestion).toContain("User prefers concise grounded technical replies");
+    expect(advice.mergeSuggestion).toContain("avoid sales language");
+    expect(advice.mergeSuggestion).toContain("keep the tone colloquial");
+    expect(advice.reasons.some((reason) => reason.includes("merged durable wording"))).toBe(true);
+  });
+});
+
+describe("clusterConflicts", () => {
+  it("groups conflicts by canonical key, reason, and category", () => {
+    const clusters = clusterConflicts([
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+        createdAt: daysAgo(4),
+        updatedAt: daysAgo(4),
+      }) as any,
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000002",
+        createdAt: daysAgo(4),
+        updatedAt: daysAgo(3),
+      }) as any,
+      createConflictRecord({
+        canonicalKey: "project-entity-owner",
+        conflictId: "00000000-0000-0000-0000-000000000003",
+        fingerprint: "project-entity-owner--durable-1--source-1--new-text",
+      }) as any,
+    ]);
+
+    expect(clusters).toHaveLength(2);
+    expect(clusters[0]?.canonicalKey).toBe("user-reply-style");
+    expect(clusters[0]?.totalCount).toBe(2);
+    expect(clusters[0]?.latestConflictId).toBe("00000000-0000-0000-0000-000000000002");
+    expect(clusters[0]?.attention).toBe("stale");
+  });
+});
+
+describe("buildConflictAuditSummary", () => {
+  it("highlights escalated or stale open clusters first", () => {
+    const summary = buildConflictAuditSummary([
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+        createdAt: daysAgo(14),
+        updatedAt: daysAgo(14),
+      }) as any,
+      createConflictRecord({
+        canonicalKey: "project-entity-owner",
+        conflictId: "00000000-0000-0000-0000-000000000002",
+        fingerprint: "project-entity-owner--durable-1--source-1--new-text",
+        createdAt: daysAgo(1),
+        updatedAt: daysAgo(1),
+      }) as any,
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000003",
+        status: "kept-existing",
+        resolvedAt: daysAgo(0),
+        updatedAt: daysAgo(0),
+      }) as any,
+    ], 3);
+
+    expect(summary.totalConflicts).toBe(3);
+    expect(summary.openConflicts).toBe(2);
+    expect(summary.attentionCounts.resolved).toBe(1);
+    expect(summary.priorityClusters[0]?.attention).toBe("escalated");
+    expect(summary.suggestedActions.some((action) => action.includes("escalated"))).toBe(true);
+  });
+
+  it("returns a no-open-conflicts message when nothing is pending", () => {
+    const summary = buildConflictAuditSummary([
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+        status: "kept-existing",
+        resolvedAt: "2026-03-16T00:00:00.000Z",
+      }) as any,
+    ], 3);
+
+    expect(summary.openConflicts).toBe(0);
+    expect(summary.priorityClusters).toHaveLength(0);
+    expect(summary.suggestedActions).toEqual(["No open conflicts need review."]);
+  });
+});

package/src/__tests__/conflict-escalation.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "bun:test";
+
+import { buildConflictCandidateRecord } from "../conflict-engine.js";
+import { buildConflictEscalationItem, escalateConflicts } from "../conflict-escalation.js";
+
+function createConflictRecord(overrides: Record<string, unknown> = {}) {
+  return {
+    ...buildConflictCandidateRecord({
+      canonicalKey: "user-reply-style",
+      category: "preferences",
+      fingerprint: "user-reply-style--durable-1--source-1--new-text",
+      reason: "promotion_conflicts_with_existing_durable",
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise, direct, technical replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers colloquial, grounded technical replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+      createdAt: "2026-03-01T00:00:00.000Z",
+      updatedAt: "2026-03-01T00:00:00.000Z",
+    }),
+    ...overrides,
+  };
+}
+
+describe("buildConflictEscalationItem", () => {
+  it("only returns an escalation item for stale or escalated open conflicts", () => {
+    const staleItem = buildConflictEscalationItem(
+      createConflictRecord() as any,
+      new Date("2026-03-16T00:00:00.000Z"),
+    );
+    const freshItem = buildConflictEscalationItem(
+      createConflictRecord({
+        createdAt: "2026-03-16T00:00:00.000Z",
+        updatedAt: "2026-03-16T00:00:00.000Z",
+      }) as any,
+      new Date("2026-03-16T12:00:00.000Z"),
+    );
+
+    expect(staleItem?.attention).toBe("escalated");
+    expect(freshItem).toBeNull();
+  });
+});
+
+describe("escalateConflicts", () => {
+  it("previews eligible stale conflicts without mutating them", async () => {
+    const records = [
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+      }),
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000002",
+        createdAt: "2026-03-16T00:00:00.000Z",
+        updatedAt: "2026-03-16T00:00:00.000Z",
+      }),
+    ];
+    const replaced: any[] = [];
+
+    const result = await escalateConflicts({
+      conflictStore: {
+        async listRecent() {
+          return records as any;
+        },
+        async replace(record: any) {
+          replaced.push(record);
+          return record;
+        },
+      } as any,
+    }, {
+      attention: "escalated",
+      limit: 100,
+      top: 10,
+      apply: false,
+    }, { now: new Date("2026-03-17T00:00:00.000Z") });
+
+    expect(result.apply).toBe(false);
+    expect(result.eligible).toBe(1);
+    expect(result.escalated).toBe(0);
+    expect(result.items[0]?.action).toBe("pending");
+    expect(replaced).toHaveLength(0);
+  });
+
+  it("applies escalation metadata exactly once per attention bucket", async () => {
+    const records = [
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+      }),
+    ];
+    const replaced: any[] = [];
+
+    const result = await escalateConflicts({
+      conflictStore: {
+        async listRecent() {
+          return records as any;
+        },
+        async replace(record: any) {
+          replaced.push(record);
+          return record;
+        },
+      } as any,
+    }, {
+      attention: "escalated",
+      limit: 100,
+      top: 10,
+      apply: true,
+      notes: "auto escalation test",
+    });
+
+    expect(result.escalated).toBe(1);
+    expect(result.items[0]?.action).toBe("escalated");
+    expect(replaced).toHaveLength(1);
+    expect(replaced[0]?.escalationCount).toBe(1);
+    expect(replaced[0]?.lastEscalationAttention).toBe("escalated");
+
+    const second = await escalateConflicts({
+      conflictStore: {
+        async listRecent() {
+          return replaced as any;
+        },
+        async replace(record: any) {
+          replaced[0] = record;
+          return record;
+        },
+      } as any,
+    }, {
+      attention: "escalated",
+      limit: 100,
+      top: 10,
+      apply: true,
+    });
+
+    expect(second.escalated).toBe(0);
+    expect(second.skipped).toBe(1);
+    expect(second.items[0]?.action).toBe("already-escalated");
+  });
+});

package/src/__tests__/conflict-lifecycle.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+
+import { summarizeConflictLifecycle } from "../conflict-lifecycle.js";
+import { buildConflictCandidateRecord } from "../conflict-engine.js";
+
+function createConflictRecord(overrides: Record<string, unknown> = {}) {
+  return {
+    ...buildConflictCandidateRecord({
+      canonicalKey: "user-reply-style",
+      category: "preferences",
+      fingerprint: "user-reply-style--durable-1--source-1--new-text",
+      reason: "promotion_conflicts_with_existing_durable",
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise, direct replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers colloquial writing that stays grounded and non-salesy.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+      createdAt: "2026-03-10T00:00:00.000Z",
+      updatedAt: "2026-03-10T00:00:00.000Z",
+    }),
+    ...overrides,
+  };
+}
+
+describe("summarizeConflictLifecycle", () => {
+  it("marks newly opened conflicts as fresh", () => {
+    const record = createConflictRecord();
+    const summary = summarizeConflictLifecycle(record as any, new Date("2026-03-10T12:00:00.000Z"));
+
+    expect(summary.attention).toBe("fresh");
+    expect(summary.openAgeDays).toBe(0);
+    expect(summary.reopenCount).toBe(0);
+    expect(summary.needsAttention).toBe(false);
+  });
+
+  it("marks older or reopened conflicts as aging/stale/escalated", () => {
+    const aging = summarizeConflictLifecycle(
+      createConflictRecord({ createdAt: "2026-03-08T00:00:00.000Z" }) as any,
+      new Date("2026-03-10T00:00:00.000Z"),
+    );
+    const stale = summarizeConflictLifecycle(
+      createConflictRecord({ createdAt: "2026-03-05T00:00:00.000Z" }) as any,
+      new Date("2026-03-10T00:00:00.000Z"),
+    );
+    const escalated = summarizeConflictLifecycle(
+      createConflictRecord({ status: "open", reopenCount: 3 }) as any,
+      new Date("2026-03-10T12:00:00.000Z"),
+    );
+
+    expect(aging.attention).toBe("aging");
+    expect(stale.attention).toBe("stale");
+    expect(stale.needsAttention).toBe(true);
+    expect(escalated.attention).toBe("escalated");
+    expect(escalated.needsAttention).toBe(true);
+  });
+
+  it("marks resolved conflicts as resolved", () => {
+    const record = createConflictRecord({
+      status: "kept-existing",
+      resolvedAt: "2026-03-10T02:00:00.000Z",
+      reopenCount: 1,
+    });
+    const summary = summarizeConflictLifecycle(record as any, new Date("2026-03-10T12:00:00.000Z"));
+
+    expect(summary.attention).toBe("resolved");
+    expect(summary.isOpen).toBe(false);
+    expect(summary.reopenCount).toBe(1);
+  });
+});

package/src/__tests__/conflict-output.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "bun:test";
+
+import { buildConflictAuditSummary } from "../conflict-advisor.js";
+import { buildConflictCandidateRecord } from "../conflict-engine.js";
+import { formatConflictAuditMarkdown } from "../conflict-output.js";
+
+function createConflictRecord(overrides: Record<string, unknown> = {}) {
+  return {
+    ...buildConflictCandidateRecord({
+      canonicalKey: "user-reply-style",
+      category: "preferences",
+      fingerprint: "user-reply-style--durable-1--source-1--new-text",
+      reason: "promotion_conflicts_with_existing_durable",
+      existing: {
+        memoryId: "durable-1",
+        text: "User prefers concise, direct replies.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.84,
+        metadata: "{\"source\":\"agent\"}",
+        canonicalKey: "user-reply-style",
+      },
+      incoming: {
+        text: "User prefers colloquial writing that stays grounded and non-salesy.",
+        category: "preferences",
+        scope: "memory:agent",
+        importance: 0.78,
+        metadata: "{\"source\":\"agent\"}",
+        source: "agent",
+        sourceMemoryId: "source-1",
+        sourceCategory: "events",
+      },
+      createdAt: "2026-03-10T00:00:00.000Z",
+      updatedAt: "2026-03-10T00:00:00.000Z",
+    }),
+    ...overrides,
+  };
+}
+
+describe("formatConflictAuditMarkdown", () => {
+  it("renders audit counts, filters, and priority clusters", () => {
+    const summary = buildConflictAuditSummary([
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+        createdAt: "2026-03-01T00:00:00.000Z",
+        updatedAt: "2026-03-01T00:00:00.000Z",
+      }) as any,
+    ], 3);
+
+    const markdown = formatConflictAuditMarkdown(summary, {
+      generatedAt: "2026-03-16T16:00:00.000Z",
+      limit: 100,
+      top: 3,
+      status: "open",
+      canonicalKey: "user-reply-style",
+    });
+
+    expect(markdown).toContain("# Conflict Audit");
+    expect(markdown).toContain("Generated: 2026-03-16T16:00:00.000Z");
+    expect(markdown).toContain("Filters: status=open, canonicalKey=user-reply-style, limit=100, top=3");
+    expect(markdown).toContain("## Suggested Actions");
+    expect(markdown).toContain("## Priority Clusters");
+    expect(markdown).toContain("Cluster key:");
+    expect(markdown).toContain("Advice:");
+  });
+
+  it("renders an empty priority-cluster section when nothing is open", () => {
+    const summary = buildConflictAuditSummary([
+      createConflictRecord({
+        conflictId: "00000000-0000-0000-0000-000000000001",
+        status: "kept-existing",
+        resolvedAt: "2026-03-16T00:00:00.000Z",
+      }) as any,
+    ], 3);
+
+    const markdown = formatConflictAuditMarkdown(summary, {
+      generatedAt: "2026-03-16T16:00:00.000Z",
+      limit: 50,
+      top: 5,
+    });
+
+    expect(markdown).toContain("## Priority Clusters");
+    expect(markdown).toContain("- None");
+  });
+});