@remnic/core 9.3.687 → 9.3.689

package/src/connectors/paths.test.ts

@@ -0,0 +1,192 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  getConnectorsConfigRoot,
+  getLegacyConnectorsConfigRoot,
+  getActiveConnectorsConfigRoot,
+  getRegistryPath,
+  getConnectorsDir,
+  hasLegacyConnectorEntries,
+  REGISTRY_DIR_NAME,
+  LEGACY_REGISTRY_DIR_NAME,
+} from "./paths.js";
+
+/**
+ * Issue #1518 — the connector registry path moved from
+ * `~/.config/engram/.engram-connectors/` to `~/.config/remnic/.remnic-connectors/`,
+ * with a read-fallback so existing engram-era installs keep resolving until
+ * the user migrates. These tests lock in that contract.
+ */
+
+function withXdgHome<T>(body: (xdg: string) => T): T {
+  const xdg = fs.mkdtempSync(path.join(os.tmpdir(), "remnic-paths-test-"));
+  const prev = process.env.XDG_CONFIG_HOME;
+  process.env.XDG_CONFIG_HOME = xdg;
+  try {
+    return body(xdg);
+  } finally {
+    if (prev === undefined) delete process.env.XDG_CONFIG_HOME;
+    else process.env.XDG_CONFIG_HOME = prev;
+    fs.rmSync(xdg, { recursive: true, force: true });
+  }
+}
+
+test("getConnectorsConfigRoot: canonical root is remnic/, not engram/ (#1518)", () => {
+  withXdgHome((xdg) => {
+    const root = getConnectorsConfigRoot();
+    assert.equal(root, path.join(xdg, "remnic"));
+    assert.notEqual(root, path.join(xdg, "engram"));
+  });
+});
+
+test("getLegacyConnectorsConfigRoot: legacy root is still engram/ (read-fallback)", () => {
+  withXdgHome((xdg) => {
+    assert.equal(getLegacyConnectorsConfigRoot(), path.join(xdg, "engram"));
+  });
+});
+
+test("REGISTRY_DIR_NAME: canonical subdir is .remnic-connectors", () => {
+  assert.equal(REGISTRY_DIR_NAME, ".remnic-connectors");
+  assert.equal(LEGACY_REGISTRY_DIR_NAME, ".engram-connectors");
+});
+
+test("getConnectorsDir: fresh install writes to remnic/.remnic-connectors/connectors", () => {
+  withXdgHome((xdg) => {
+    // Neither remnic nor engram exists → canonical remnic wins.
+    const dir = getConnectorsDir();
+    assert.equal(
+      dir,
+      path.join(xdg, "remnic", ".remnic-connectors", "connectors"),
+      "fresh install must resolve to the canonical remnic path",
+    );
+  });
+});
+
+test("getRegistryPath: fresh install writes registry.json under remnic/.remnic-connectors", () => {
+  withXdgHome((xdg) => {
+    const reg = getRegistryPath();
+    assert.equal(
+      reg,
+      path.join(xdg, "remnic", ".remnic-connectors", "registry.json"),
+    );
+  });
+});
+
+test("read-fallback: when ONLY engram/ exists, active root resolves to engram (#1518 back-compat)", () => {
+  withXdgHome((xdg) => {
+    // Seed the legacy engram tree — no remnic dir.
+    fs.mkdirSync(path.join(xdg, "engram", ".engram-connectors", "connectors"), {
+      recursive: true,
+    });
+    assert.equal(getActiveConnectorsConfigRoot(), path.join(xdg, "engram"));
+    assert.equal(
+      getConnectorsDir(),
+      path.join(xdg, "engram", ".engram-connectors", "connectors"),
+    );
+    assert.equal(
+      getRegistryPath(),
+      path.join(xdg, "engram", ".engram-connectors", "registry.json"),
+    );
+  });
+});
+
+test("read-fallback: once remnic/ exists, it wins over engram (post-migration)", () => {
+  withXdgHome((xdg) => {
+    // Seed BOTH trees — the user has started migrating.
+    fs.mkdirSync(path.join(xdg, "engram", ".engram-connectors", "connectors"), {
+      recursive: true,
+    });
+    fs.mkdirSync(path.join(xdg, "remnic", ".remnic-connectors", "connectors"), {
+      recursive: true,
+    });
+    assert.equal(getActiveConnectorsConfigRoot(), path.join(xdg, "remnic"));
+    assert.equal(
+      getConnectorsDir(),
+      path.join(xdg, "remnic", ".remnic-connectors", "connectors"),
+    );
+  });
+});
+
+test("read-fallback: a bare config-root dir without its registry subdir does NOT trigger fallback (#1620 round 1)", () => {
+  withXdgHome((xdg) => {
+    // A stray engram/ dir (no .engram-connectors inside) is NOT evidence of a
+    // connector install. The probe targets the registry subdir, so this falls
+    // through to the canonical remnic root.
+    fs.mkdirSync(path.join(xdg, "engram"), { recursive: true });
+    assert.equal(
+      getActiveConnectorsConfigRoot(),
+      path.join(xdg, "remnic"),
+      "bare engram/ without .engram-connectors must not trigger the legacy fallback",
+    );
+  });
+});
+
+test("read-fallback: stray remnic/config.json must not hide legacy engram connector data (#1620 round 1 regression)", () => {
+  // The cursor-reported bug: the daemon creates ~/.config/remnic/config.json
+  // for its own setup, so the bare remnic/ config root exists on a machine
+  // that has NEVER installed a connector under remnic. The active root must
+  // still resolve to engram when connector data lives there, otherwise
+  // loadRegistry would read an empty remnic tree and legacy installs would
+  // look uninstalled.
+  withXdgHome((xdg) => {
+    // Daemon setup created remnic/config.json (no .remnic-connectors).
+    fs.mkdirSync(path.join(xdg, "remnic"), { recursive: true });
+    fs.writeFileSync(path.join(xdg, "remnic", "config.json"), "{}\n");
+    // Real connector data still lives under the legacy engram tree.
+    fs.mkdirSync(path.join(xdg, "engram", ".engram-connectors", "connectors"), {
+      recursive: true,
+    });
+    assert.equal(getActiveConnectorsConfigRoot(), path.join(xdg, "engram"));
+    assert.equal(
+      getConnectorsDir(),
+      path.join(xdg, "engram", ".engram-connectors", "connectors"),
+    );
+  });
+});
+
+test("hasLegacyConnectorEntries: fresh canonical install is NOT legacy evidence (#1620 review)", () => {
+  // The codex P2 concern: a fresh post-rename install writes its first
+  // connector under remnic/.remnic-connectors/. That must NOT flip
+  // resolveEmitLegacyTools, because the user never had engram.* aliases.
+  withXdgHome((xdg) => {
+    fs.mkdirSync(
+      path.join(xdg, "remnic", ".remnic-connectors", "connectors"),
+      { recursive: true },
+    );
+    fs.writeFileSync(
+      path.join(xdg, "remnic", ".remnic-connectors", "connectors", "claude-code.json"),
+      "{}\n",
+    );
+    assert.equal(
+      hasLegacyConnectorEntries(),
+      false,
+      "canonical remnic/ connector entries are not legacy evidence",
+    );
+  });
+});
+
+test("hasLegacyConnectorEntries: legacy engram entries ARE sticky-legacy evidence (#1550)", () => {
+  // An unmigrated install with connector data under engram/.engram-connectors
+  // must still report legacy evidence so its clients keep seeing engram_* aliases.
+  withXdgHome((xdg) => {
+    fs.mkdirSync(
+      path.join(xdg, "engram", ".engram-connectors", "connectors"),
+      { recursive: true },
+    );
+    fs.writeFileSync(
+      path.join(xdg, "engram", ".engram-connectors", "connectors", "claude-code.json"),
+      "{}\n",
+    );
+    assert.equal(hasLegacyConnectorEntries(), true);
+  });
+});
+
+test("hasLegacyConnectorEntries: missing legacy dir is not legacy evidence (fresh install)", () => {
+  withXdgHome(() => {
+    assert.equal(hasLegacyConnectorEntries(), false);
+  });
+});

package/src/connectors/paths.ts

@@ -4,46 +4,132 @@ import path from "node:path";
 import { readEnvVar, resolveHomeDir } from "../runtime/env.js";
 
 /**
- * Connector registry directory name. Kept under the legacy `engram` config
- * root for backward compatibility with existing installs; the rename to a
- * `remnic` path (with a legacy read-fallback) is tracked in #1518.
+ * Connector registry directory name. Kept under the canonical `remnic` config
+ * root for new installs; legacy installs that still live under `engram` are
+ * read-transparent via {@link getActiveConnectorsConfigRoot} (issue #1518).
  */
-export const REGISTRY_DIR_NAME = ".engram-connectors";
+export const REGISTRY_DIR_NAME = ".remnic-connectors";
 
 /**
- * Single source of truth for the connectors config root
- * (`$XDG_CONFIG_HOME/engram` or `~/.config/engram`). Issue #1527 flagged this
- * derivation as previously duplicated across call sites — add new callers
- * here, never re-derive the path inline.
+ * Legacy registry directory name from the engram era. Used only for the
+ * read-fallback so existing installs keep resolving until the user migrates.
+ */
+export const LEGACY_REGISTRY_DIR_NAME = ".engram-connectors";
+
+/**
+ * Config-root segment for the canonical (post-rename) layout. Issue #1518
+ * point 6: the path `~/.config/engram/...` is confusing when the product is
+ * called Remnic, so new writes land under `remnic/`.
+ */
+const CONFIG_ROOT_SEGMENT = "remnic";
+
+/**
+ * Config-root segment for the legacy engram-era layout. Read-fallback only.
+ */
+const LEGACY_CONFIG_ROOT_SEGMENT = "engram";
+
+/**
+ * Single source of truth for the canonical connectors config root
+ * (`$XDG_CONFIG_HOME/remnic` or `~/.config/remnic`). New writes ALWAYS go
+ * here. Issue #1527 flagged this derivation as previously duplicated across
+ * call sites — add new callers here, never re-derive the path inline.
  */
 export function getConnectorsConfigRoot(): string {
   const xdgConfigHome = readEnvVar("XDG_CONFIG_HOME");
   return xdgConfigHome
-    ? path.join(xdgConfigHome, "engram")
-    : path.join(resolveHomeDir(), ".config", "engram");
+    ? path.join(xdgConfigHome, CONFIG_ROOT_SEGMENT)
+    : path.join(resolveHomeDir(), ".config", CONFIG_ROOT_SEGMENT);
 }
 
-/** Path of the connector registry manifest file. */
+/**
+ * Legacy config root from the engram era (`$XDG_CONFIG_HOME/engram` or
+ * `~/.config/engram`). Exposed for tests and the migration path only —
+ * production code should call {@link getActiveConnectorsConfigRoot} so the
+ * read-fallback is applied uniformly.
+ */
+export function getLegacyConnectorsConfigRoot(): string {
+  const xdgConfigHome = readEnvVar("XDG_CONFIG_HOME");
+  return xdgConfigHome
+    ? path.join(xdgConfigHome, LEGACY_CONFIG_ROOT_SEGMENT)
+    : path.join(resolveHomeDir(), ".config", LEGACY_CONFIG_ROOT_SEGMENT);
+}
+
+/**
+ * Read-time fallback: pick the config root that actually holds (or will hold)
+ * the connector registry.
+ *
+ *   1. Canonical `remnic/` root when its `.remnic-connectors` registry dir
+ *      already exists (post-migration, or a fresh install that has already
+ *      written its first connector).
+ *   2. Legacy `engram/` root when ONLY its `.engram-connectors` registry dir
+ *      exists — an existing install we keep reading in place until the user
+ *      runs `remnic migrate`.
+ *   3. Canonical `remnic/` root otherwise (fresh install with no registry on
+ *      disk yet) so the first write lands at the new path.
+ *
+ * The probe looks for the REGISTRY SUBDIR (`.remnic-connectors` /
+ * `.engram-connectors`), not the bare config root. The config root
+ * `~/.config/remnic/` is created by unrelated daemon setup (e.g. the daemon's
+ * own `config.json`), so probing the bare root would falsely resolve to
+ * remnic and hide connector data that still lives under
+ * `~/.config/engram/.engram-connectors/` (cursor review round 1, #1620).
+ *
+ * This is a READ-time fallback. Writes go to whichever root this returns, so
+ * a legacy install keeps its data colocated for the active session; a fresh
+ * install writes straight to `remnic/`.
+ */
+export function getActiveConnectorsConfigRoot(): string {
+  const canonical = getConnectorsConfigRoot();
+  if (fs.existsSync(path.join(canonical, REGISTRY_DIR_NAME))) return canonical;
+  const legacy = getLegacyConnectorsConfigRoot();
+  if (fs.existsSync(path.join(legacy, LEGACY_REGISTRY_DIR_NAME))) return legacy;
+  return canonical;
+}
+
+/**
+ * Path of the connector registry manifest file. The registry subdir name
+ * (`.remnic-connectors` vs the legacy `.engram-connectors`) is chosen from the
+ * active root so a pre-rename install reads its existing files without a
+ * rename-side migration step (#1518).
+ */
 export function getRegistryPath(): string {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "registry.json");
+  const root = getActiveConnectorsConfigRoot();
+  const dirName = root === getConnectorsConfigRoot() ? REGISTRY_DIR_NAME : LEGACY_REGISTRY_DIR_NAME;
+  return path.join(root, dirName, "registry.json");
 }
 
-/** Directory holding one `<connector-id>.json` per installed connector. */
+/**
+ * Directory holding one `<connector-id>.json` per installed connector. The
+ * registry subdir name follows the active root (see {@link getRegistryPath}).
+ */
 export function getConnectorsDir(): string {
-  return path.join(getConnectorsConfigRoot(), REGISTRY_DIR_NAME, "connectors");
+  const root = getActiveConnectorsConfigRoot();
+  const dirName = root === getConnectorsConfigRoot() ? REGISTRY_DIR_NAME : LEGACY_REGISTRY_DIR_NAME;
+  return path.join(root, dirName, "connectors");
 }
 
 /**
  * Sticky-legacy evidence for `emitLegacyTools` (issue #1550): any persisted
- * connector entry under the legacy engram connectors dir means an existing
- * install whose clients may still address engram_* aliases. Missing or
- * unreadable dir means fresh install — no evidence, no aliases.
+ * connector entry under the LEGACY engram registry means an existing install
+ * whose clients may still address engram_* aliases. Missing or unreadable
+ * legacy dir means fresh install — no evidence, no aliases.
+ *
+ * Probes ONLY the legacy engram registry (`$XDG_CONFIG_HOME/engram/.engram-connectors`),
+ * never the active/canonical root. A fresh post-rename install that just
+ * wrote its first connector under `remnic/.remnic-connectors/` is NOT legacy
+ * evidence — counting it would flip `resolveEmitLegacyTools` to true and
+ * advertise deprecated `engram.*` aliases to users who never had them
+ * (#1620 review, codex P2). An unmigrated install still reports its entries
+ * here because its data lives under the engram tree.
  */
 export function hasLegacyConnectorEntries(): boolean {
   try {
-    return fs
-      .readdirSync(getConnectorsDir())
-      .some((name) => name.endsWith(".json"));
+    const legacyDir = path.join(
+      getLegacyConnectorsConfigRoot(),
+      LEGACY_REGISTRY_DIR_NAME,
+      "connectors",
+    );
+    return fs.readdirSync(legacyDir).some((name) => name.endsWith(".json"));
   } catch {
     return false;
   }

package/src/memory-extension/claude-code-publisher.ts

@@ -17,6 +17,7 @@ export class ClaudeCodeMemoryExtensionPublisher implements MemoryExtensionPublis
   readonly hostId = "claude-code";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: true,
     instructionsMd: false,
     skillsFolder: false,
     citationFormat: false,

package/src/memory-extension/codex-publisher.ts

@@ -53,6 +53,7 @@ export class CodexMemoryExtensionPublisher implements MemoryExtensionPublisher {
   readonly hostId = "codex";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: false,
     instructionsMd: true,
     skillsFolder: false,
     citationFormat: true,

package/src/memory-extension/hermes-publisher.ts

@@ -17,6 +17,7 @@ export class HermesMemoryExtensionPublisher implements MemoryExtensionPublisher
   readonly hostId = "hermes";
 
   static readonly capabilities: PublisherCapabilities = {
+    isStub: true,
     instructionsMd: false,
     skillsFolder: false,
     citationFormat: false,

package/src/memory-extension/types.ts

@@ -73,8 +73,19 @@ export interface PublishResult {
  * Declarative capability flags that describe what a given publisher
  * can produce. Useful for feature-gating UI or doctor output without
  * instantiating the publisher.
+ *
+ * `isStub` is the explicit declaration required by #1518: when true, the
+ * docs-code parity gate (`scripts/check-docs-parity.mjs`) refuses any
+ * automation claim ("installs the plugin", "configures mcp",
+ * "automatically …") in the publisher's mapped install docs, because a stub
+ * publisher writes nothing to disk. A publisher that implements any real
+ * artefact writes MUST set this false. The inferred "all flags false ⇒ stub"
+ * detection in the parity script remains as a backstop, but the explicit
+ * flag is now the source of truth.
  */
 export interface PublisherCapabilities {
+  /** Whether the publisher is an intentional no-op stub (writes nothing). */
+  readonly isStub: boolean;
   /** Whether the publisher writes an instructions.md file. */
   readonly instructionsMd: boolean;
   /** Whether the publisher populates a skills folder. */

package/src/recall-pipeline-stages.test.ts

@@ -0,0 +1,269 @@
+// Issue #1539 PR2 — unit tests for the recall pipeline spine module.
+//
+// These tests verify `unifiedDedupeAndRank` produces the correct results for
+// each declared divergence dimension, WITHOUT changing any existing pipeline.
+// PRs 3–6 will migrate each pipeline to call this function; at that point the
+// characterization snapshots (tests/recall-pipeline-unified.test.ts) verify
+// end-to-end byte-for-byte parity.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import type { EvidencePackItem } from "./evidence-pack.js";
+import {
+  unifiedDedupeAndRank,
+  type RankedEvidenceItem,
+} from "./recall-pipeline-stages.js";
+
+const NO_INTENTS: never[] = [];
+const constantScorer = (_item: EvidencePackItem): number => 10;
+
+function item(
+  turnIndex: number,
+  content: string,
+  overrides: Partial<EvidencePackItem> = {},
+): EvidencePackItem {
+  return {
+    id: `s1:${turnIndex}`,
+    sessionId: "s1",
+    turnIndex,
+    role: "user",
+    content,
+    ...overrides,
+  };
+}
+
+test("unifiedDedupeAndRank: dedup collapses identical ids", () => {
+  const items = [
+    item(3, "Content A"),
+    item(3, "Content A"), // same id → deduped
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+  });
+  assert.equal(result.length, 1);
+  assert.equal(result[0]?.turnIndex, 3);
+});
+
+test("unifiedDedupeAndRank: dedup collapses identical normalized content under different ids", () => {
+  const items = [
+    item(10, "My monthly expenses are $2,400."),
+    item(11, "MY   MONTHLY   EXPENSES ARE $2,400."), // same normalized content
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+  });
+  assert.equal(result.length, 1, "expected content dedup to collapse the two items");
+  assert.equal(result[0]?.turnIndex, 10, "first-seen wins");
+});
+
+test("unifiedDedupeAndRank: DESC sort (default) orders turnIndex descending on score ties", () => {
+  const items = [
+    item(2, "Oldest"),
+    item(5, "Middle"),
+    item(9, "Newest"),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer, // all tied → turnIndex DESC
+  });
+  const turns = result.map((r) => r.turnIndex);
+  assert.deepEqual(turns, [9, 5, 2]);
+});
+
+test("unifiedDedupeAndRank: ASC sort orders turnIndex ascending on score ties", () => {
+  const items = [
+    item(30, "Latest"),
+    item(10, "Earliest"),
+    item(20, "Middle"),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+    turnIndexSortDirection: "asc",
+  });
+  const turns = result.map((r) => r.turnIndex);
+  assert.deepEqual(turns, [10, 20, 30]);
+});
+
+test("unifiedDedupeAndRank: rank primary key is always DESC regardless of turnIndex direction", () => {
+  const items = [
+    item(1, "Low rank", { score: 0 }),
+    item(2, "High rank", { score: 0 }),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: (i) => (i.turnIndex === 2 ? 100 : 1),
+    turnIndexSortDirection: "asc",
+  });
+  // rank DESC wins over turnIndex ASC: turn 2 (rank 100) comes first despite ASC.
+  assert.equal(result[0]?.turnIndex, 2);
+  assert.equal(result[1]?.turnIndex, 1);
+});
+
+test("unifiedDedupeAndRank: rankThreshold drops items below the declared threshold", () => {
+  const items = [
+    item(1, "Weak", { score: 0 }),
+    item(2, "Strong", { score: 0 }),
+    item(3, "Medium", { score: 0 }),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: (i) => {
+      if (i.turnIndex === 1) return 3;
+      if (i.turnIndex === 2) return 10;
+      return 6;
+    },
+    rankThreshold: 6,
+  });
+  const turns = result.map((r) => r.turnIndex).sort((a, b) => (a ?? 0) - (b ?? 0));
+  assert.deepEqual(turns, [2, 3], "turn 1 (rank 3) is below threshold 6 and dropped");
+});
+
+test("unifiedDedupeAndRank: transformContent is applied to output but NOT to scorer input", () => {
+  const items = [item(5, "original content")];
+  let scorerSawTransformed = false;
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: (i) => {
+      if (i.content.includes("APPENDED CUE")) scorerSawTransformed = true;
+      return 5;
+    },
+    transformContent: (content) => `${content}\nAPPENDED CUE`,
+  });
+  assert.equal(scorerSawTransformed, false, "scorer must see ORIGINAL content");
+  assert.ok(result[0]?.content.includes("APPENDED CUE"), "output must have transformed content");
+});
+
+test("unifiedDedupeAndRank: undefined turnIndex sorts to the bottom of DESC (-1 sentinel)", () => {
+  const items = [
+    item(5, "Has turn"),
+    { id: "s1:x", sessionId: "s1", role: "user", content: "No turn" }, // no turnIndex
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+    // default DESC
+  });
+  assert.equal(result[1]?.id, "s1:x", "undefined-turnIndex item sorts last in DESC");
+});
+
+test("unifiedDedupeAndRank: undefined turnIndex sorts to the bottom of ASC (MAX sentinel)", () => {
+  const items = [
+    item(5, "Has turn"),
+    { id: "s1:x", sessionId: "s1", role: "user", content: "No turn" },
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+    turnIndexSortDirection: "asc",
+  });
+  assert.equal(result[1]?.id, "s1:x", "undefined-turnIndex item sorts last in ASC");
+});
+
+test("unifiedDedupeAndRank: DESC tertiary tiebreaker is score DESC", () => {
+  // Same rank (all tied via constantScorer) AND same turnIndex → score breaks the tie.
+  const items = [
+    item(5, "Low score", { score: 10 }),
+    item(5, "High score", { score: 90 }), // same turn, deduped by content? No — different content
+  ];
+  // Wait — both have turn 5 so same id "s1:5" → second is deduped. Use different sessions.
+  const itemsDistinct: EvidencePackItem[] = [
+    { id: "s1:5", sessionId: "s1", turnIndex: 5, role: "user", content: "A", score: 10 },
+    { id: "s2:5", sessionId: "s2", turnIndex: 5, role: "user", content: "B", score: 90 },
+  ];
+  const result = unifiedDedupeAndRank(itemsDistinct, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer, // rank tied → turnIndex tied → score DESC
+  });
+  assert.equal(result[0]?.id, "s2:5", "higher score (90) ranks first on DESC tertiary");
+  assert.equal(result[1]?.id, "s1:5");
+});
+
+test("unifiedDedupeAndRank: ASC tertiary tiebreaker is content.localeCompare", () => {
+  const items: EvidencePackItem[] = [
+    { id: "s2:5", sessionId: "s2", turnIndex: 5, role: "user", content: "Banana" },
+    { id: "s1:5", sessionId: "s1", turnIndex: 5, role: "user", content: "Apple" },
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer, // rank tied → turnIndex tied → content localeCompare
+    turnIndexSortDirection: "asc",
+  });
+  assert.equal(result[0]?.content, "Apple", "localeCompare ASC: Apple < Banana");
+  assert.equal(result[1]?.content, "Banana");
+});
+
+test("unifiedDedupeAndRank: RankedEvidenceItem carries the computed rank", () => {
+  const items = [item(1, "content")];
+  const result: RankedEvidenceItem[] = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: () => 42,
+  });
+  assert.equal(result[0]?.rank, 42);
+});
+
+test("unifiedDedupeAndRank: fallback id uses sessionId:turnIndex when id is absent", () => {
+  const items: EvidencePackItem[] = [
+    { sessionId: "s1", turnIndex: 7, role: "user", content: "No explicit id" },
+    { sessionId: "s1", turnIndex: 7, role: "user", content: "Same fallback id → deduped" },
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+  });
+  assert.equal(result.length, 1, "fallback id dedup must collapse the two items");
+});
+
+test("unifiedDedupeAndRank: dedupByContent false keeps distinct ids with identical content (event-order shape)", () => {
+  // Event-order's rankAndSelectEventOrderItems deduplicates by turn id only and
+  // keeps distinct turns even when two turns share the same cue-appended body.
+  // The spine must express that as a declared config field so PR 6's migration
+  // does not silently drop valid turns (cursor bugbot a4299851).
+  const items: EvidencePackItem[] = [
+    item(1, "What time is it?", { id: "s1:1" }),
+    item(5, "What time is it?", { id: "s1:5" }),
+  ];
+  const result = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+    dedupByContent: false,
+  });
+  assert.equal(result.length, 2, "distinct ids with identical content must both survive when dedupByContent is false");
+});
+
+test("unifiedDedupeAndRank: dedupByContent true (default) still collapses identical content under different ids", () => {
+  const items: EvidencePackItem[] = [
+    item(1, "Duplicate body", { id: "s1:1" }),
+    item(2, "Duplicate body", { id: "s1:2" }),
+  ];
+  const resultDefault = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+  });
+  assert.equal(resultDefault.length, 1, "default dedupByContent collapses identical content");
+  const resultExplicit = unifiedDedupeAndRank(items, {
+    query: "q",
+    intents: NO_INTENTS,
+    scoreEvidence: constantScorer,
+    dedupByContent: true,
+  });
+  assert.equal(resultExplicit.length, 1, "explicit dedupByContent: true collapses identical content");
+});