@modusensus/dsh-mneme 0.4.6 → 0.5.0

package/src/service.js

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE } from "./mirror.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
+import { createBM25Index } from "./search/bm25.js";
+import { adaptiveThreshold } from "./search/adaptive.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
@@ -307,6 +309,66 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   // Weighted blend factor for hybrid search; exposed so callers can tune it.
   const DEFAULT_HYBRID_WEIGHTS = { vector: 0.6, keyword: 0.4 };
 
+  // Cosine over two plain arrays (shared by the search-time semantic dedup).
+  function cosineVec(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length || !a.length) return 0;
+    let dot = 0, na = 0, nb = 0;
+    for (let i = 0; i < a.length; i++) {
+      dot += a[i] * b[i];
+      na += a[i] * a[i];
+      nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0) return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+  }
+
+  /**
+   * BM25 third recall path (v0.5.0 1.1). Scores the query tokens against the
+   * live non-archived rows and returns the top `limit` hits with scores
+   * normalized to [0,1]. Failures degrade to [] — BM25 is a recall booster,
+   * never a correctness gate.
+   */
+  function bm25Recall(q, limit) {
+    if (config?.bm25SearchEnabled === false) return [];
+    try {
+      const docs = store.list({ limit: 500, includeForgotten: false }).filter((m) => !m.archived);
+      if (!docs.length) return [];
+      return createBM25Index(docs).search(q, { limit });
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Search-time semantic dedup (v0.5.0 2.3): greedy pass dropping candidates
+   * whose embedding similarity to an already-kept row exceeds the threshold.
+   * Rows without a stored embedding are always kept (no signal = no drop).
+   */
+  function semanticDeduplicate(candidates) {
+    // Opt-in aggressive mode (default off): collapsing near-duplicates can
+    // drop legitimately distinct rows on small embedding models, so it ships
+    // behind searchSemanticDedup=true.
+    if (config?.searchSemanticDedup !== true || candidates.length < 2) return candidates;
+    const threshold = config?.searchSemanticDedupThreshold ?? 0.95;
+    try {
+      const vecs = store.getEmbeddings(candidates.map((c) => c.id));
+      if (vecs.size < 2) return candidates;
+      const kept = [];
+      for (const c of candidates) {
+        const v = vecs.get(c.id);
+        if (!v) { kept.push(c); continue; }
+        const dup = kept.some((k) => {
+          const kv = vecs.get(k.id);
+          return kv && cosineVec(v, kv) > threshold;
+        });
+        if (!dup) kept.push(c);
+      }
+      return kept;
+    } catch {
+      return candidates;
+    }
+  }
+
   /**
    * Give a keyword-hit row a relevance score in [0,1]: title hits score
    * higher than content hits, then scaled by importance (1-5). This lets
@@ -371,14 +433,39 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           : embedder.embed.bind(embedder);
         const qv = await embedSingle(q);
         if (qv?.length) {
-          const hits = vectorIndex
-            ? vectorIndex.search(qv, { limit: lim * 2, threshold: threshold ?? 0 })
-            : store.searchVector(qv, { limit: lim * 2, threshold: threshold ?? 0 });
-          vector = hits.map((m) => ({ ...m, vector: true, source: "vector" }));
+          // Adaptive threshold (v0.5.0 1.2): the fetch runs at the loosest
+          // branch floor so the head-gap rule can still re-admit the tail;
+          // the final cutoff is computed against the fetched score
+          // distribution. Explicit `threshold` wins; disabled → legacy 0.
+          const adaptive = config?.adaptiveThresholdEnabled !== false;
+          const fetchThreshold = adaptive && threshold === undefined
+            ? Math.min(0.5, adaptiveThreshold(q))
+            : (threshold ?? 0);
+          const search = vectorIndex
+            ? vectorIndex.search(qv, { limit: lim * 2, threshold: fetchThreshold })
+            : store.searchVector(qv, { limit: lim * 2, threshold: fetchThreshold });
+          const finalThreshold = adaptive && threshold === undefined
+            ? adaptiveThreshold(q, search)
+            : (threshold ?? 0);
+          vector = search
+            .filter((m) => (m.score ?? 1) >= finalThreshold)
+            .map((m) => ({ ...m, vector: true, source: "vector" }));
         }
       } catch { /* vector unavailable: keep keyword results */ }
     }
 
+    // BM25 third path (v0.5.0 1.1): IDF-weighted token overlap recalls rows
+    // whose query terms are scattered — the gap LIKE substring matching
+    // cannot close. Scores are already normalized to [0,1].
+    const bm25 = bm25Recall(q, lim).map((m) => ({ ...m, source: "bm25" }));
+    // Loose blend weight: BM25 confirms and backfills, never dominates the
+    // semantic signal. Same-memory overlap boosts, unseen ids backfill.
+    const wb = 0.3;
+    // Path bookkeeping for the boost rule below: which ids each semantic
+    // recall path surfaced.
+    const vectorIds = new Set(vector.map((m) => m.id));
+    const keywordIds = new Set(keyword.map((m) => m.id));
+
     // Hybrid blending weights from config when provided.
     const wv = config?.hybridSearchVectorWeight ?? DEFAULT_HYBRID_WEIGHTS.vector;
     const wk = config?.hybridSearchKeywordWeight ?? DEFAULT_HYBRID_WEIGHTS.keyword;
@@ -387,9 +474,10 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     if (mode === "keyword") {
       merged = keyword;
     } else if (mode === "vector" || mode === "hybrid") {
-      // semantic-first: vector recalls lead, keyword fills remaining slots.
-      // Weighted blend when both sides scored the same memory; otherwise
-      // vector order leads (it is the semantic signal), keyword backfills.
+      // semantic-first: vector recalls lead, keyword + BM25 fill remaining
+      // slots. Weighted blend when sides scored the same memory; otherwise
+      // vector order leads (it is the semantic signal), lexical paths
+      // backfill.
       const byId = new Map();
       for (const m of vector) {
         const rec = byId.get(m.id);
@@ -404,6 +492,19 @@ export function createService({ store, mirror, config, onWrite, logger }) {
           byId.set(m.id, m);
         }
       }
+      for (const m of bm25) {
+        const rec = byId.get(m.id);
+        if (rec) {
+          // Boost rule: a row the LIKE keyword path already hit carries the
+          // query as a substring, so BM25 tokens are trivially present —
+          // boosting it double-counts lexical evidence. Only vector-recalled
+          // rows (lexical hit is genuinely new information) get the boost.
+          if (keywordIds.has(m.id)) continue;
+          byId.set(m.id, { ...rec, score: (rec.score ?? 0) + wb * (m.score ?? 0) });
+        } else {
+          byId.set(m.id, { ...m, score: wb * (m.score ?? 0) });
+        }
+      }
       const ranked = [...byId.values()].sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
       merged = ranked.slice(0, lim);
       if (merged.length < lim && !merged.length) {
@@ -411,15 +512,26 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         merged = keyword.slice(0, lim);
       }
     } else {
-      // auto: keyword leads, vector fills remaining slots (legacy behavior)
+      // auto: keyword leads, vector + BM25 fill remaining slots (legacy
+      // behavior, extended with the third path)
       merged = keyword.slice(0, lim);
       const seen = new Set(merged.map((m) => m.id));
       for (const m of vector) {
         if (merged.length >= lim) break;
         if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
       }
+      for (const m of bm25) {
+        if (merged.length >= lim) break;
+        if (!seen.has(m.id)) { seen.add(m.id); merged.push(m); }
+      }
     }
 
+    // Search-time semantic dedup (v0.5.0 2.3): near-duplicate rows are
+    // dropped before the reranker sees them, so topK slots carry distinct
+    // information instead of the same memory twice. Keyword mode is exempt —
+    // it is the documented text-only path and must not be altered by
+    // embedding state.
+    merged = mode === "keyword" ? merged : semanticDeduplicate(merged);
     merged = merged.slice(0, lim);
     let result = useRerank && reranker && merged.length
       ? await rerankCandidates(q, merged, lim)
@@ -806,6 +918,20 @@ export function createService({ store, mirror, config, onWrite, logger }) {
         candidates = merged;
       }
     }
+    // Topic-ranked selection (v0.5.0 2.2): when the current query's vector is
+    // available the whole candidate list is re-ordered by similarity to that
+    // vector, so the injected slots go to memories on the current topic
+    // rather than to the rule-based order. Rows the index did not return
+    // keep their relative order after the scored ones.
+    if (config?.selectiveInjectEnabled !== false && Array.isArray(queryVector) && queryVector.length && vectorIndex) {
+      try {
+        const hits = vectorIndex.search(queryVector, { limit: 200, threshold: 0 });
+        const sim = new Map(hits.map((m) => [m.id, m.score ?? 0]));
+        if (sim.size) {
+          candidates = [...candidates].sort((a, b) => (sim.get(b.id) ?? -1) - (sim.get(a.id) ?? -1));
+        }
+      } catch { /* topic re-rank unavailable: keep rule-based order */ }
+    }
     const selected = candidates.slice(0, maxItems);
     touchRecalled(selected);
     return selected;
@@ -1352,6 +1478,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     findEntityByName: (n) => store.findEntityByName(n),
     findEntityById: (id) => store.findEntityById(id),
     getAttrsByMemory: (id) => store.getAttrsByMemory(id),
+    getCurrentAttrs: (id) => store.getCurrentAttrs(id),
     migrateAttrsToMemory: (fromId, toId, now) => store.migrateAttrsToMemory(fromId, toId, now)
   };
 }

package/src/store.js

@@ -548,51 +548,39 @@ export function createStore(path) {
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec(SCHEMA);
 
-  // Schema migrations for legacy databases (idempotent).
-  const columns = db.prepare("PRAGMA table_info(memories)").all().map((c) => c.name);
-  if (!columns.includes("archived")) {
-    db.exec("ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
-  }
-  if (!columns.includes("embedding")) {
-    db.exec("ALTER TABLE memories ADD COLUMN embedding TEXT");
-  }
-  if (!columns.includes("last_accessed_at")) {
-    db.exec("ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
-  }
-  if (!columns.includes("_full_content")) {
-    db.exec("ALTER TABLE memories ADD COLUMN _full_content TEXT");
-  }
-  if (!columns.includes("epistemic_status")) {
-    db.exec("ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
-  }
-  if (!columns.includes("content_history")) {
-    db.exec("ALTER TABLE memories ADD COLUMN content_history TEXT");
-  }
-  if (!columns.includes("quality_score")) {
-    db.exec("ALTER TABLE memories ADD COLUMN quality_score REAL");
-  }
+  // Schema migrations for legacy databases (idempotent). Each ADD COLUMN is
+  // also race-safe: two concurrently-opening processes can both pass the
+  // PRAGMA table_info check before either ALTERs, so the ALTER itself is
+  // guarded against the "duplicate column name" error SQLite raises when the
+  // other process won the race (SQLite has no ADD COLUMN IF NOT EXISTS).
+  const addColumn = (table, column, ddl) => {
+    const cols = db.prepare(`PRAGMA table_info(${table})`).all().map((c) => c.name);
+    if (!cols.includes(column)) {
+      try {
+        db.exec(ddl);
+      } catch (e) {
+        if (!/duplicate column name/i.test(String(e?.message ?? e))) throw e;
+      }
+    }
+  };
+
+  addColumn("memories", "archived", "ALTER TABLE memories ADD COLUMN archived INTEGER NOT NULL DEFAULT 0");
+  addColumn("memories", "embedding", "ALTER TABLE memories ADD COLUMN embedding TEXT");
+  addColumn("memories", "last_accessed_at", "ALTER TABLE memories ADD COLUMN last_accessed_at TEXT");
+  addColumn("memories", "_full_content", "ALTER TABLE memories ADD COLUMN _full_content TEXT");
+  addColumn("memories", "epistemic_status", "ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
+  addColumn("memories", "content_history", "ALTER TABLE memories ADD COLUMN content_history TEXT");
+  addColumn("memories", "quality_score", "ALTER TABLE memories ADD COLUMN quality_score REAL");
 
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
-  const dreamCols = db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
-  if (!dreamCols.includes("policy_epoch")) {
-    db.exec("ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
-  }
-  if (!dreamCols.includes("run_type")) {
-    db.exec("ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
-  }
+  addColumn("dream_runs", "policy_epoch", "ALTER TABLE dream_runs ADD COLUMN policy_epoch INTEGER NOT NULL DEFAULT 0");
+  addColumn("dream_runs", "run_type", "ALTER TABLE dream_runs ADD COLUMN run_type TEXT NOT NULL DEFAULT 'auto'");
 
   // Legacy mirror_state without v0.3.6 generation columns → add each missing
   // column idempotently (old DBs open cleanly, no data loss).
-  const mirrorCols = db.prepare("PRAGMA table_info(mirror_state)").all().map((c) => c.name);
-  if (!mirrorCols.includes("generation")) {
-    db.exec("ALTER TABLE mirror_state ADD COLUMN generation INTEGER NOT NULL DEFAULT 0");
-  }
-  if (!mirrorCols.includes("applied_generation")) {
-    db.exec("ALTER TABLE mirror_state ADD COLUMN applied_generation INTEGER NOT NULL DEFAULT 0");
-  }
-  if (!mirrorCols.includes("type_status")) {
-    db.exec("ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
-  }
+  addColumn("mirror_state", "generation", "ALTER TABLE mirror_state ADD COLUMN generation INTEGER NOT NULL DEFAULT 0");
+  addColumn("mirror_state", "applied_generation", "ALTER TABLE mirror_state ADD COLUMN applied_generation INTEGER NOT NULL DEFAULT 0");
+  addColumn("mirror_state", "type_status", "ALTER TABLE mirror_state ADD COLUMN type_status TEXT");
 
   // Audit peer F: a legacy DB may hold a non-integer generation/applied_generation
   // (pre-v0.3.9 the JS gate truncated with Math.trunc and SQLite's CHECK only
@@ -923,6 +911,29 @@ export function createStore(path) {
     db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(json, id);
   }
 
+  /** Batch fetch stored embeddings by id (v0.5.0 search-time semantic dedup).
+   *  Returns a Map(id → number[]); rows without a parseable embedding are
+   *  simply absent from the map. */
+  function getEmbeddings(ids) {
+    const out = new Map();
+    const list = (Array.isArray(ids) ? ids : []).filter(Boolean);
+    for (let i = 0; i < list.length; i += 100) {
+      const chunk = list.slice(i, i + 100);
+      const rows = db.prepare(
+        `SELECT id, embedding FROM memories
+         WHERE embedding IS NOT NULL AND embedding != ''
+           AND id IN (${chunk.map(() => "?").join(",")})`
+      ).all(...chunk);
+      for (const row of rows) {
+        try {
+          const vec = JSON.parse(row.embedding);
+          if (Array.isArray(vec) && vec.length) out.set(row.id, vec);
+        } catch { /* corrupt row: skip */ }
+      }
+    }
+    return out;
+  }
+
   function embeddedCount() {
     return db.prepare(
       "SELECT count(*) AS c FROM memories WHERE embedding IS NOT NULL AND embedding != ''"
@@ -1864,6 +1875,7 @@ export function createStore(path) {
     all,
     search,
     setEmbedding,
+    getEmbeddings,
     embeddedCount,
     needsEmbedding,
     searchVector,

package/test/benchmark.test.js

@@ -0,0 +1,35 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { runBenchmark, TEST_CASES } from "../scripts/benchmark-recall.js";
+
+// The benchmark harness must stay a working evaluation: it runs the real
+// searchMemories pipeline over the seeded store and the fused configuration
+// must not fall behind the legacy one (that is the whole point of the third
+// recall path).
+test("benchmark harness runs both configurations", async () => {
+  const report = await runBenchmark({ topK: 5 });
+  assert.equal(report.runs.length, 2);
+  assert.equal(report.runs[0].config, "legacy");
+  assert.equal(report.runs[1].config, "fused");
+  for (const run of report.runs) {
+    assert.equal(run.rows.length, TEST_CASES.length);
+    assert.ok(run.recallAtK >= 0 && run.recallAtK <= 1);
+  }
+});
+
+test("fused configuration never trails legacy on Recall@5", async () => {
+  const report = await runBenchmark({ topK: 5 });
+  const [legacy, fused] = report.runs;
+  assert.ok(
+    fused.recallAtK >= legacy.recallAtK,
+    `fused (${fused.recallAtK}) must be >= legacy (${legacy.recallAtK})`
+  );
+});
+
+test("test cases cover the scattered-term BM25 territory", () => {
+  assert.ok(TEST_CASES.length >= 10);
+  assert.ok(TEST_CASES.some((tc) => tc.expected.length >= 2), "multi-target cases present");
+  for (const tc of TEST_CASES) {
+    assert.ok(tc.query && tc.expected.length > 0);
+  }
+});

package/test/client.test.js

@@ -25,20 +25,210 @@ test("client bundle is lib-only with no src counterpart", () => {
   assert.equal(existsSync(join(root, "lib/client.js")), true, "lib/client.js must exist");
 });
 
-// Both panels render in two modes: a portal modal (styles.panel, full chrome)
-// and an embedded settings-section variant. The embedded variant must drop the
-// modal-only chrome (background, radius, padding, shadow) — the settings host
-// already provides its own surface, so reusing the modal panel style makes the
-// section render as a floating card with an inset box and shadow inside the
-// settings page.
-test("embedded variant drops the modal panel chrome", () => {
-  const branches = clientSource.match(/embedded \? \{[^}]+\}/g);
-  assert.ok(branches, "panels must branch on the embedded flag");
-  assert.equal(branches.length, 2, "both MemoryPanel and SettingsPanel must branch");
-  for (const branch of branches) {
-    assert.equal(branch.includes("styles.panel"), false, "embedded branch must not reuse the modal panel style");
-    for (const chrome of ["boxShadow", "background", "borderRadius", "padding"]) {
-      assert.equal(branch.includes(chrome), false, `embedded branch must not carry ${chrome}`);
-    }
+// The memory entry lives at the sidebar foot, not in the settings modal: the
+// migration must register into `sidebar.footer.action` (the list slot the
+// sidebar shell renders beside Settings) and must not keep a `settings.section`
+// registration, or the entry would appear twice under different hosts.
+test("memory entry registers into the sidebar foot slot", () => {
+  assert.ok(
+    clientSource.includes('ctx.slots.inject("sidebar.footer.action"'),
+    "client must inject into sidebar.footer.action"
+  );
+  assert.equal(
+    clientSource.includes('"settings.section"'),
+    false,
+    "the old settings.section registration must be gone"
+  );
+});
+
+// The drawer era is over as the PRIMARY surface: the sidebar entry must
+// activate the main-area memory library tab first. The one sanctioned
+// exception is the hero screen — the host hides the whole tab ring while a
+// session is blank, so activation legitimately fails there and the same
+// click falls back to a full-viewport overlay (same MemoryExplorer, not the
+// old 420px side drawer). A dialog role stays banned either way.
+test("tab-first activation with hero-screen overlay fallback", () => {
+  assert.equal(
+    clientSource.includes("role: \"dialog\""),
+    false,
+    "no dialog surface should remain"
+  );
+  assert.ok(
+    clientSource.includes("activateExplorerTab(t(\"memory.view.label\"))"),
+    "the sidebar trigger must activate the memory library tab by its label"
+  );
+  assert.ok(
+    clientSource.includes("activateExplorerTab(t(\"memory.view.label\")).then((ok) => { if (!ok) setOpen(true); })"),
+    "a failed tab activation must open the fallback overlay"
+  );
+  assert.ok(
+    /if \(!tab\) \{ resolve\(false\); return; \}/.test(clientSource),
+    "activation must resolve false when the tab ring is absent (hero screen)"
+  );
+  assert.ok(
+    /aria-selected.*true/.test(clientSource),
+    "activation is only confirmed once the host marks the tab selected"
+  );
+});
+
+// The fallback overlay reuses the full MemoryExplorer (three columns, graph,
+// settings) at viewport size — not the old side drawer — and closes on Esc
+// or the close button.
+test("hero fallback overlay is a full-viewport MemoryExplorer with a close affordance", () => {
+  assert.ok(
+    clientSource.includes('.mneme-overlay{position:fixed;inset:0'),
+    "the overlay must cover the full viewport"
+  );
+  assert.ok(
+    clientSource.includes('h(MemoryExplorer, { t })'),
+    "the overlay renders the same MemoryExplorer component as the tab"
+  );
+  assert.ok(
+    clientSource.includes('e.key === "Escape"'),
+    "Esc must close the overlay"
+  );
+  assert.ok(
+    clientSource.includes('"memory.overlay.close"'),
+    "the overlay ships a localized close label in both dictionaries"
+  );
+});
+
+// The sidebar hands each footer action only its column state: a wide row
+// (icon + label) when expanded, a bare rail icon when collapsed.
+test("trigger renders a wide row or a rail icon from the wide flag", () => {
+  assert.ok(
+    /wide \? "mneme-trigger" : "mneme-trigger mneme-rail"/.test(clientSource),
+    "trigger must branch on the wide flag"
+  );
+  assert.ok(
+    /wide && h\("span", \{ className: "mneme-trigger-label" \}/.test(clientSource),
+    "the label span must render only when wide"
+  );
+});
+
+// The full-width memory browser lives in the conversation view ring beside
+// Chat / Trajectory, so the client must inject into `conversation.view` with
+// a stable entry id (the active view is persisted by that id).
+test("explorer registers into the conversation view ring", () => {
+  assert.ok(
+    clientSource.includes('ctx.slots.inject("conversation.view"'),
+    "client must inject into conversation.view"
+  );
+  assert.ok(
+    clientSource.includes('id: "dsh-mneme-memory"'),
+    "the view entry needs a stable, unique id"
+  );
+  assert.ok(
+    clientSource.includes('"memory.view.label"'),
+    "the tab label must come from the memory.view.label dictionary key"
+  );
+});
+
+// The graph toggle must not read as "share": the primitives share icon is
+// banned and a custom node-graph glyph takes its place.
+test("graph toggle uses a node-graph glyph, not the share icon", () => {
+  assert.equal(
+    clientSource.includes("IconShareOutline16"),
+    false,
+    "IconShareOutline16 reads as share and must not appear"
+  );
+  assert.ok(
+    clientSource.includes("GraphNodesIcon"),
+    "the custom node-graph icon must back the graph toggle"
+  );
+});
+
+// Every memory feature lives in the main-area library now: the explorer
+// hosts three sub-views (browse / graph / settings) switched by tabs whose
+// labels come from dedicated dictionary keys.
+test("explorer hosts browse, graph and settings sub-views", () => {
+  for (const key of ["tabMemory", "tabGraph", "tabSettings"]) {
+    assert.ok(
+      clientSource.includes(`"memory.explorer.${key}"`),
+      `sub-view labels must come from memory.explorer.${key}`
+    );
   }
+  assert.ok(
+    clientSource.includes('h(GraphPanel, { t, focusEntity: graphFocus, onJumpMemory: jumpToMemory })'),
+    "the graph panel must be embedded as a sub-view"
+  );
+  assert.ok(
+    clientSource.includes('h(SettingsContent, { t })'),
+    "the settings forms must be embedded as a sub-view"
+  );
+});
+
+// The graph panel jumps back into the browser: related-memory rows and the
+// edge source button must land on the browse tab with the target selected.
+test("graph jump lands on the selected memory in the browser", () => {
+  assert.ok(
+    /onClick: \(\) => onJumpMemory && onJumpMemory\(m\)/.test(clientSource),
+    "related-memory rows must jump via onJumpMemory(m)"
+  );
+  assert.ok(
+    clientSource.includes("onJumpMemory({ id: selected.edge.memory_id })"),
+    "the edge source button must jump to the origin memory by id"
+  );
+  assert.ok(
+    /const jumpToMemory = \(target\) => \{/.test(clientSource),
+    "jumpToMemory must reset filters and select the target"
+  );
+});
+
+// "entity:" in the browser search is the graph entry grammar: it must offer
+// a jump chip instead of filtering the list.
+test("entity: search grammar offers a graph jump", () => {
+  assert.ok(
+    clientSource.includes('query.trim().startsWith("entity:")'),
+    "the entity: prefix must be recognized"
+  );
+  assert.ok(
+    /onClick: \(\) => openGraphFor\(entityQuery\)/.test(clientSource),
+    "the jump chip must switch to the graph sub-view"
+  );
+});
+
+// The explorer is a three-pane layout: types with counts, a month→day time
+// tree, and a detail pane rendering the untruncated content.
+test("explorer lays out types, timeline, and full-text detail", () => {
+  assert.ok(
+    clientSource.includes('className: "mneme-xmain"'),
+    "the three-column grid must be present"
+  );
+  assert.ok(
+    clientSource.includes('className: "mneme-xdcontent"'),
+    "the detail pane must render the full content"
+  );
+  assert.ok(
+    /toLocaleDateString\(undefined, \{ year: "numeric", month: "long" \}\)/.test(clientSource),
+    "month groups must format via the host locale, not hardcoded strings"
+  );
+});
+
+// The library page must read as a first-party view: the chrome resolves to
+// the host's design tokens (layer-1 canvas, brand-blue active states) and
+// the boxed-panel / pill-chip patterns of the drawer era must stay gone.
+test("explorer chrome aligns with the host design system", () => {
+  assert.ok(
+    clientSource.includes("background:var(--dsw-alias-bg-layer-1)"),
+    "the page canvas must sit on the host bg-layer-1 token"
+  );
+  assert.ok(
+    /\.mneme-vtab\.mneme-active::after/.test(clientSource),
+    "active sub-tabs use the host underline treatment"
+  );
+  assert.ok(
+    clientSource.includes(".mneme-vtab.mneme-active{color:var(--dsw-alias-state-business-primary)}"),
+    "active sub-tab text must turn the host brand blue"
+  );
+  assert.equal(
+    /\.mneme-xmain\{[^}]*border:1px/.test(clientSource),
+    false,
+    "the three-column layout must not wrap itself in a boxed panel"
+  );
+  assert.equal(
+    clientSource.includes("border-radius:999px"),
+    false,
+    "pill chips belong to the drawer era and must stay gone"
+  );
 });