recallnest 2.3.0 → 2.6.0

package/src/__tests__/ui-server-security.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  enforceLocalHttpRequestPolicy,
+  LOCAL_HTTP_HOSTNAME,
+  LOCAL_JSON_BODY_LIMIT_BYTES,
+} from "../http-request-policy.js";
+
+function uiRequest({
+  method = "GET",
+  host = "127.0.0.1:4317",
+  headers = {},
+  body,
+}: {
+  method?: string;
+  host?: string;
+  headers?: Record<string, string>;
+  body?: string;
+} = {}): Request {
+  return new Request("http://127.0.0.1:4317/api/search", {
+    method,
+    headers: { host, ...headers },
+    body,
+  });
+}
+
+describe("RecallNest UI local HTTP policy", () => {
+  test("binds the UI to the IPv4 loopback interface", () => {
+    expect(LOCAL_HTTP_HOSTNAME).toBe("127.0.0.1");
+  });
+
+  test("allows same-origin browser requests", async () => {
+    const result = await enforceLocalHttpRequestPolicy(uiRequest({
+      method: "POST",
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        origin: "http://127.0.0.1:4317",
+        "sec-fetch-site": "same-origin",
+      },
+      body: JSON.stringify({ query: "local" }),
+    }));
+
+    expect(result).toEqual({ allowed: true });
+  });
+
+  test("rejects a non-local Host header", async () => {
+    const result = await enforceLocalHttpRequestPolicy(uiRequest({
+      host: "attacker.example",
+    }));
+
+    expect(result).toEqual({ allowed: false, status: 403, message: "Host is not allowed." });
+  });
+
+  test("rejects cross-origin and cross-site browser requests", async () => {
+    const wrongOrigin = await enforceLocalHttpRequestPolicy(uiRequest({
+      headers: { origin: "https://attacker.example" },
+    }));
+    const crossSite = await enforceLocalHttpRequestPolicy(uiRequest({
+      headers: { "sec-fetch-site": "cross-site" },
+    }));
+
+    expect(wrongOrigin).toEqual({ allowed: false, status: 403, message: "Origin is not allowed." });
+    expect(crossSite).toEqual({ allowed: false, status: 403, message: "Cross-site requests are not allowed." });
+  });
+
+  test("rejects non-JSON POST bodies", async () => {
+    const result = await enforceLocalHttpRequestPolicy(uiRequest({
+      method: "POST",
+      headers: { "content-type": "text/plain" },
+      body: JSON.stringify({ query: "local" }),
+    }));
+
+    expect(result).toEqual({
+      allowed: false,
+      status: 415,
+      message: "Content-Type must be application/json.",
+    });
+  });
+
+  test("rejects streamed JSON bodies over the limit", async () => {
+    const result = await enforceLocalHttpRequestPolicy(uiRequest({
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ query: "x".repeat(LOCAL_JSON_BODY_LIMIT_BYTES) }),
+    }));
+
+    expect(result).toEqual({
+      allowed: false,
+      status: 413,
+      message: `Request body exceeds ${LOCAL_JSON_BODY_LIMIT_BYTES} bytes.`,
+    });
+  });
+});

package/src/__tests__/usage-tracker.test.ts

@@ -0,0 +1,287 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  getUsageMetadata,
+  computeUsageStatus,
+  buildUsagePatch,
+  recordMemoryUsage,
+  recordReconstructionUsage,
+  deriveUsageStatus,
+  USAGE_COLD_INJECTION_THRESHOLD,
+  type UsageMetadata,
+  type UsageStorePort,
+} from "../usage-tracker.js";
+import type { MemoryEntry } from "../store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const ID = "11111111-1111-1111-1111-111111111111";
+
+function makeEntry(id: string, meta: Record<string, unknown> = {}): MemoryEntry {
+  return {
+    id,
+    text: "t",
+    vector: [1, 0, 0],
+    category: "events",
+    scope: "project:test",
+    importance: 0.7,
+    timestamp: 1000,
+    metadata: JSON.stringify(meta),
+  };
+}
+
+function createMockStore(entries: MemoryEntry[]): {
+  store: UsageStorePort;
+  data: Map<string, MemoryEntry>;
+  updates: Array<{ id: string; metadata: string }>;
+} {
+  const data = new Map(entries.map(e => [e.id, { ...e }]));
+  const updates: Array<{ id: string; metadata: string }> = [];
+  // 模拟 store.patchMetadata 的真实语义:读最新 metadata → patchFn → 写回。
+  const store: UsageStorePort = {
+    async patchMetadata(id, patchFn, _scopeFilter) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      let meta: Record<string, unknown>;
+      try {
+        const parsed: unknown = JSON.parse(entry.metadata || "{}");
+        meta = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+          ? (parsed as Record<string, unknown>)
+          : {};
+      } catch {
+        meta = {};
+      }
+      const patched = patchFn(meta, entry);
+      entry.metadata = JSON.stringify(patched);
+      updates.push({ id, metadata: entry.metadata });
+      return entry;
+    },
+  };
+  return { store, data, updates };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("usage-tracker", () => {
+  describe("getUsageMetadata", () => {
+    it("returns useCount 0 for entry without usage", () => {
+      expect(getUsageMetadata(makeEntry(ID)).useCount).toBe(0);
+    });
+
+    it("returns 0 for malformed metadata", () => {
+      const e: MemoryEntry = { ...makeEntry(ID), metadata: "not-json" };
+      expect(getUsageMetadata(e).useCount).toBe(0);
+    });
+
+    it("reads stored usage fields", () => {
+      const e = makeEntry(ID, { usage: { useCount: 3, firstUsedAt: 1, lastUsedAt: 5, usageStatus: "warm" } });
+      const u = getUsageMetadata(e);
+      expect(u.useCount).toBe(3);
+      expect(u.lastUsedAt).toBe(5);
+      expect(u.usageStatus).toBe("warm");
+    });
+
+    it("ignores invalid usageStatus value", () => {
+      const e = makeEntry(ID, { usage: { useCount: 1, usageStatus: "bogus" } });
+      expect(getUsageMetadata(e).usageStatus).toBeUndefined();
+    });
+
+    it("malformed metadata='null' does not crash", () => {
+      const e: MemoryEntry = { ...makeEntry(ID), metadata: "null" };
+      expect(getUsageMetadata(e).useCount).toBe(0);
+      expect(() => buildUsagePatch(e, 100)).not.toThrow();
+    });
+
+    it("malformed array metadata does not crash", () => {
+      const e: MemoryEntry = { ...makeEntry(ID), metadata: "[1,2,3]" };
+      expect(getUsageMetadata(e).useCount).toBe(0);
+      expect(deriveUsageStatus(e)).toBe("unused");
+    });
+  });
+
+  describe("computeUsageStatus (复刻 Orb decay_tick)", () => {
+    it("unused: no injections, no uses", () => {
+      expect(computeUsageStatus(0, 0)).toBe("unused");
+    });
+
+    it("unused: just below cold threshold, zero uses", () => {
+      expect(computeUsageStatus(USAGE_COLD_INJECTION_THRESHOLD - 1, 0)).toBe("unused");
+    });
+
+    it("cold: AT injection threshold with zero uses (核心边界 inj=6 & use=0)", () => {
+      expect(computeUsageStatus(USAGE_COLD_INJECTION_THRESHOLD, 0)).toBe("cold");
+    });
+
+    it("cold: well above threshold, zero uses", () => {
+      expect(computeUsageStatus(20, 0)).toBe("cold");
+    });
+
+    it("warm: used but ratio below hot (1/10=0.1)", () => {
+      expect(computeUsageStatus(10, 1)).toBe("warm");
+    });
+
+    it("hot: use/injection ratio meets HOT_RATIO (3/10=0.3)", () => {
+      expect(computeUsageStatus(10, 3)).toBe("hot");
+    });
+
+    it("warm: used with zero injections (no div-by-zero → hot)", () => {
+      expect(computeUsageStatus(0, 2)).toBe("warm");
+    });
+  });
+
+  describe("buildUsagePatch", () => {
+    it("returns null for null entry", () => {
+      expect(buildUsagePatch(null, 100)).toBeNull();
+    });
+
+    it("first use: 0 -> 1, sets first/lastUsedAt", () => {
+      const patch = buildUsagePatch(makeEntry(ID), 100);
+      expect(patch).not.toBeNull();
+      const usage = patch!.metadata.usage as UsageMetadata;
+      expect(usage.useCount).toBe(1);
+      expect(usage.firstUsedAt).toBe(100);
+      expect(usage.lastUsedAt).toBe(100);
+      expect(patch!.update.oldUseCount).toBe(0);
+      expect(patch!.update.newUseCount).toBe(1);
+    });
+
+    it("accumulates useCount, preserves firstUsedAt, updates lastUsedAt", () => {
+      const e = makeEntry(ID, { usage: { useCount: 2, firstUsedAt: 50 } });
+      const patch = buildUsagePatch(e, 200);
+      const usage = patch!.metadata.usage as UsageMetadata;
+      expect(usage.useCount).toBe(3);
+      expect(usage.firstUsedAt).toBe(50);
+      expect(usage.lastUsedAt).toBe(200);
+    });
+
+    it("双计数互不污染：不动 accessCount / confidence / evolution / tier", () => {
+      const e = makeEntry(ID, {
+        accessCount: 9,
+        confidence: 0.9,
+        evolution: { accessCount: 4 },
+        tier: "core",
+      });
+      const m = buildUsagePatch(e, 100)!.metadata;
+      expect(m.accessCount).toBe(9);
+      expect(m.confidence).toBe(0.9);
+      expect((m.evolution as { accessCount: number }).accessCount).toBe(4);
+      expect(m.tier).toBe("core");
+    });
+
+    it("不写 usageStatus（status 留 deriveUsageStatus 离线算，避免假 cold）", () => {
+      const e = makeEntry(ID, { accessCount: 8 });
+      const patch = buildUsagePatch(e, 100);
+      const usage = patch!.metadata.usage as UsageMetadata;
+      expect(usage.usageStatus).toBeUndefined();
+      expect("status" in patch!.update).toBe(false);
+    });
+
+    it("does not emit any ranking multiplier / score field (影子定位)", () => {
+      const patch = buildUsagePatch(makeEntry(ID), 100);
+      const update = patch!.update as Record<string, unknown>;
+      expect(update.scoreMultiplier).toBeUndefined();
+      expect(update.weight).toBeUndefined();
+    });
+  });
+
+  describe("deriveUsageStatus (离线按需，cold 可达)", () => {
+    it("cold: accessCount>=6 且从未被引用（无 usage 字段）", () => {
+      expect(deriveUsageStatus(makeEntry(ID, { accessCount: 8 }))).toBe("cold");
+    });
+    it("cold: accessCount=6 边界 + useCount 0", () => {
+      expect(deriveUsageStatus(makeEntry(ID, { accessCount: 6, usage: { useCount: 0 } }))).toBe("cold");
+    });
+    it("unused: 低 injection 从未被引用", () => {
+      expect(deriveUsageStatus(makeEntry(ID, { accessCount: 2 }))).toBe("unused");
+    });
+    it("warm: 被引用但比例低", () => {
+      expect(deriveUsageStatus(makeEntry(ID, { accessCount: 10, usage: { useCount: 1 } }))).toBe("warm");
+    });
+    it("hot: use/injection 达标", () => {
+      expect(deriveUsageStatus(makeEntry(ID, { accessCount: 10, usage: { useCount: 3 } }))).toBe("hot");
+    });
+  });
+
+  describe("recordMemoryUsage", () => {
+    it("returns null and skips update when entry not found", async () => {
+      const { store, updates } = createMockStore([]);
+      const res = await recordMemoryUsage(store, "missing", 100);
+      expect(res).toBeNull();
+      expect(updates.length).toBe(0);
+    });
+
+    it("writes full metadata back with usage, preserving other fields", async () => {
+      const e = makeEntry(ID, { accessCount: 3, confidence: 0.8 });
+      const { store, updates, data } = createMockStore([e]);
+      const res = await recordMemoryUsage(store, ID, 100);
+      expect(res!.newUseCount).toBe(1);
+      expect(updates.length).toBe(1);
+      const written = JSON.parse(updates[0].metadata) as Record<string, unknown>;
+      expect((written.usage as UsageMetadata).useCount).toBe(1);
+      expect(written.accessCount).toBe(3);
+      expect(written.confidence).toBe(0.8);
+      const persisted = JSON.parse(data.get(ID)!.metadata ?? "{}") as Record<string, unknown>;
+      expect((persisted.usage as UsageMetadata).useCount).toBe(1);
+    });
+
+    it("second call accumulates useCount to 2", async () => {
+      const { store } = createMockStore([makeEntry(ID)]);
+      await recordMemoryUsage(store, ID, 100);
+      const res2 = await recordMemoryUsage(store, ID, 200);
+      expect(res2!.newUseCount).toBe(2);
+    });
+
+    it("passes scope through to store.patchMetadata when provided", async () => {
+      const captured: Array<string[] | undefined> = [];
+      const base = createMockStore([makeEntry(ID)]);
+      const store: UsageStorePort = {
+        async patchMetadata(id, patchFn, scopeFilter) {
+          captured.push(scopeFilter);
+          return base.store.patchMetadata(id, patchFn, scopeFilter);
+        },
+      };
+      await recordMemoryUsage(store, ID, 100, "project:test");
+      expect(captured[0]).toEqual(["project:test"]);
+    });
+  });
+
+  describe("recordReconstructionUsage (批量影子)", () => {
+    it("no-op on empty array", async () => {
+      const { store, updates } = createMockStore([]);
+      await recordReconstructionUsage(store, [], 100);
+      expect(updates.length).toBe(0);
+    });
+
+    it("records useCount=1 for each distinct cited id", async () => {
+      const { store, data } = createMockStore([makeEntry("mem-a"), makeEntry("mem-b")]);
+      await recordReconstructionUsage(store, ["mem-a", "mem-b"], 100);
+      const a = JSON.parse(data.get("mem-a")!.metadata ?? "{}") as Record<string, unknown>;
+      const b = JSON.parse(data.get("mem-b")!.metadata ?? "{}") as Record<string, unknown>;
+      expect((a.usage as UsageMetadata).useCount).toBe(1);
+      expect((b.usage as UsageMetadata).useCount).toBe(1);
+    });
+
+    it("dedupes repeated ids within one call (writes once)", async () => {
+      const { store, updates } = createMockStore([makeEntry(ID)]);
+      await recordReconstructionUsage(store, [ID, ID, ID], 100);
+      expect(updates.length).toBe(1);
+    });
+
+    it("one failing id does not block others (allSettled, no throw)", async () => {
+      const base = createMockStore([makeEntry(ID)]);
+      const store: UsageStorePort = {
+        async patchMetadata(id, patchFn, scopeFilter) {
+          if (id === "bad") throw new Error("boom");
+          return base.store.patchMetadata(id, patchFn, scopeFilter);
+        },
+      };
+      await recordReconstructionUsage(store, ["bad", ID], 100);
+      const good = JSON.parse(base.data.get(ID)!.metadata ?? "{}") as Record<string, unknown>;
+      expect((good.usage as UsageMetadata).useCount).toBe(1);
+    });
+  });
+});

package/src/__tests__/version-manager.test.ts

@@ -0,0 +1,213 @@
+/**
+ * Tests for Tier 3.3: Version Coexistence + Competition
+ *
+ * Validates:
+ * 1. computeVersionRank formula
+ * 2. createVersionGroup tags both entries with same group
+ * 3. deduplicateByVersionGroup keeps top-ranked per group
+ * 4. Entries without version_group pass through unchanged
+ * 5. Multiple version groups are handled independently
+ * 6. Existing version_group is reused (not duplicated)
+ */
+import { describe, expect, it } from "bun:test";
+import {
+  computeVersionRank,
+  deduplicateByVersionGroup,
+  createVersionGroup,
+} from "../version-manager.js";
+import type { MemoryEntry } from "../store.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEntry(
+  id: string,
+  overrides: {
+    confidence?: number;
+    accessCount?: number;
+    version_group?: string;
+    version_rank?: number;
+  } = {},
+): MemoryEntry {
+  const meta: Record<string, unknown> = {
+    confidence: overrides.confidence ?? 0.7,
+    accessCount: overrides.accessCount ?? 0,
+  };
+  if (overrides.version_group) meta.version_group = overrides.version_group;
+  if (overrides.version_rank !== undefined) meta.version_rank = overrides.version_rank;
+
+  return {
+    id,
+    text: `memory-${id}`,
+    vector: [1, 0, 0],
+    category: "events",
+    scope: "project:test",
+    importance: 0.7,
+    timestamp: Date.now(),
+    metadata: JSON.stringify(meta),
+  };
+}
+
+function createMockStore(entries: MemoryEntry[]) {
+  const data = new Map(entries.map(e => [e.id, { ...e }]));
+  const updates: Array<{ id: string; metadata: string }> = [];
+
+  return {
+    data,
+    updates,
+    async getById(id: string) {
+      return data.get(id) ?? null;
+    },
+    async update(id: string, upd: { metadata?: string }, _scope?: string[]) {
+      const entry = data.get(id);
+      if (!entry) return null;
+      if (upd.metadata) {
+        entry.metadata = upd.metadata;
+        updates.push({ id, metadata: upd.metadata });
+      }
+      return entry;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// computeVersionRank
+// ---------------------------------------------------------------------------
+
+describe("computeVersionRank", () => {
+  it("computes rank from importance, confidence, and accessCount", () => {
+    const entry = makeEntry("a", { confidence: 1.0, accessCount: 10 });
+    const rank = computeVersionRank(entry);
+    // quality = 0.5*0.7 + 0.5*1.0 = 0.85 (importance=0.7 from makeEntry)
+    // rank = 0.85 * (1 + ln(11)) ≈ 0.85 * 3.398 = 2.888
+    expect(rank).toBeGreaterThan(2.8);
+    expect(rank).toBeLessThan(3.0);
+  });
+
+  it("returns baseline for default confidence and zero access", () => {
+    const entry = makeEntry("b", { confidence: 0.7, accessCount: 0 });
+    const rank = computeVersionRank(entry);
+    // quality = 0.5*0.7 + 0.5*0.7 = 0.7
+    // rank = 0.7 * (1 + 0) = 0.7
+    expect(rank).toBeCloseTo(0.7, 5);
+  });
+
+  it("higher confidence wins over lower with same access", () => {
+    const high = computeVersionRank(makeEntry("h", { confidence: 1.0, accessCount: 5 }));
+    const low = computeVersionRank(makeEntry("l", { confidence: 0.3, accessCount: 5 }));
+    expect(high).toBeGreaterThan(low);
+  });
+
+  it("higher access wins over lower with same confidence", () => {
+    const frequent = computeVersionRank(makeEntry("f", { confidence: 0.7, accessCount: 20 }));
+    const rare = computeVersionRank(makeEntry("r", { confidence: 0.7, accessCount: 1 }));
+    expect(frequent).toBeGreaterThan(rare);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createVersionGroup
+// ---------------------------------------------------------------------------
+
+describe("createVersionGroup", () => {
+  it("tags both entries with the same version_group", async () => {
+    const canonical = makeEntry("canon", { confidence: 1.0, accessCount: 5 });
+    const member = makeEntry("member", { confidence: 0.5, accessCount: 1 });
+    const store = createMockStore([canonical, member]);
+
+    const groupId = await createVersionGroup(store as any, canonical, member, "project:test");
+
+    expect(groupId).toBeTruthy();
+    expect(store.updates.length).toBe(2);
+
+    const canonMeta = JSON.parse(store.data.get("canon")!.metadata);
+    const memberMeta = JSON.parse(store.data.get("member")!.metadata);
+
+    expect(canonMeta.version_group).toBe(groupId);
+    expect(memberMeta.version_group).toBe(groupId);
+    expect(canonMeta.version_rank).toBeGreaterThan(memberMeta.version_rank);
+  });
+
+  it("reuses existing version_group from canonical", async () => {
+    const canonical = makeEntry("canon", {
+      confidence: 1.0,
+      accessCount: 5,
+      version_group: "vg-existing",
+      version_rank: 3.0,
+    });
+    const member = makeEntry("new", { confidence: 0.5, accessCount: 0 });
+    const store = createMockStore([canonical, member]);
+
+    const groupId = await createVersionGroup(store as any, canonical, member, "project:test");
+
+    expect(groupId).toBe("vg-existing");
+    const memberMeta = JSON.parse(store.data.get("new")!.metadata);
+    expect(memberMeta.version_group).toBe("vg-existing");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deduplicateByVersionGroup
+// ---------------------------------------------------------------------------
+
+describe("deduplicateByVersionGroup", () => {
+  it("keeps only the top-ranked entry per version group", () => {
+    const results = [
+      { entry: makeEntry("a", { version_group: "vg1", version_rank: 3.0 }), score: 0.9, sources: {} },
+      { entry: makeEntry("b", { version_group: "vg1", version_rank: 1.0 }), score: 0.85, sources: {} },
+      { entry: makeEntry("c"), score: 0.8, sources: {} },
+    ];
+
+    const deduped = deduplicateByVersionGroup(results);
+
+    expect(deduped.length).toBe(2);
+    expect(deduped.map(r => r.entry.id)).toContain("a");
+    expect(deduped.map(r => r.entry.id)).toContain("c");
+    expect(deduped.map(r => r.entry.id)).not.toContain("b");
+  });
+
+  it("passes through entries without version_group", () => {
+    const results = [
+      { entry: makeEntry("x"), score: 0.9, sources: {} },
+      { entry: makeEntry("y"), score: 0.8, sources: {} },
+    ];
+
+    const deduped = deduplicateByVersionGroup(results);
+
+    expect(deduped.length).toBe(2);
+  });
+
+  it("handles multiple independent version groups", () => {
+    const results = [
+      { entry: makeEntry("a1", { version_group: "vg1", version_rank: 3.0 }), score: 0.95, sources: {} },
+      { entry: makeEntry("a2", { version_group: "vg1", version_rank: 1.0 }), score: 0.90, sources: {} },
+      { entry: makeEntry("b1", { version_group: "vg2", version_rank: 2.0 }), score: 0.85, sources: {} },
+      { entry: makeEntry("b2", { version_group: "vg2", version_rank: 4.0 }), score: 0.80, sources: {} },
+      { entry: makeEntry("solo"), score: 0.75, sources: {} },
+    ];
+
+    const deduped = deduplicateByVersionGroup(results);
+
+    expect(deduped.length).toBe(3);
+    const ids = deduped.map(r => r.entry.id);
+    expect(ids).toContain("a1"); // vg1 winner (rank 3.0)
+    expect(ids).toContain("b2"); // vg2 winner (rank 4.0)
+    expect(ids).toContain("solo");
+  });
+
+  it("handles empty array", () => {
+    expect(deduplicateByVersionGroup([])).toEqual([]);
+  });
+
+  it("handles single entry in a version group", () => {
+    const results = [
+      { entry: makeEntry("only", { version_group: "vg1", version_rank: 2.0 }), score: 0.9, sources: {} },
+    ];
+
+    const deduped = deduplicateByVersionGroup(results);
+
+    expect(deduped.length).toBe(1);
+    expect(deduped[0].entry.id).toBe("only");
+  });
+});