@ghilteras/opencode-agent-memory 1.2.0 → 2.0.1

package/README.md

@@ -6,7 +6,7 @@
 >
 > Originally created by Joshua David Thomas and licensed under the MIT license. Attribution preserved below; see License section.
 
-A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local semantic search.
+A journal-only memory plugin for [OpenCode](https://opencode.ai): an append-only, tagged journal with local lexical search.
 
 ## Experimental
 
@@ -17,7 +17,7 @@ Think of it as a searchable sidecar to `AGENTS.md`. OpenCode supports [rules](ht
 ## Features
 
 - **Append-only journal** - Entries survive across sessions and context compaction
-- **Local semantic search** - Find entries by meaning, not just keywords
+- **Local lexical search** - Find candidate entries by matching query words in titles and bodies
 - **Metadata on every entry** - Project, model, provider, agent, session, timestamp, tags
 - **Guidance in tool descriptions** - Journal usage guidance lives in the descriptions of the journal tools, so an agent sees it only when it is allowed to call them
 - **No data leaves the machine** - Embeddings run locally
@@ -32,7 +32,7 @@ Add to your OpenCode config (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugins": ["@ghilteras/opencode-agent-memory@1.1.0"]
+  "plugins": ["@ghilteras/opencode-agent-memory@2.0.1"]
 }
 ```
 
@@ -63,7 +63,7 @@ The agent gets 3 tools:
 | Tool | Description |
 |------|-------------|
 | `journal_write` | Write a new append-only entry (title, body, optional tags) |
-| `journal_search` | Search entries semantically, filter by project or tags, with pagination |
+| `journal_search` | Find lexical candidates by matching query words in titles and bodies; filter by project or tags, with pagination |
 | `journal_read` | Read a specific journal entry by ID |
 
 ### Entry format
@@ -74,7 +74,7 @@ Entries are markdown files with YAML frontmatter in `~/.config/opencode/journal/
 ---
 title: "Reasoning-pruner wiring"
 created: 2026-09-21T18:16:11.300Z
-project: /home/angelo/homelab-config
+project: /path/to/project
 model: deepseek-v4.1-flash
 provider: opencode-go
 agent: executor
@@ -85,9 +85,9 @@ tags: [plugin, wiring]
 Body text...
 ```
 
-### Semantic search
+### Text search
 
-Search uses local embeddings ([paraphrase-multilingual-MiniLM-L12-v2](https://huggingface.co/Xenova/paraphrase-multilingual-MiniLM-L12-v2), 384d, multilingual EN/IT) - no data leaves your machine. An `.embedding` sidecar is written next to each entry in a versioned format (`{ v: 2, model, dimension, vector }`). The search gate is a **dimension** check: an entry whose recorded `dimension` differs from the plugin's expected dimension is not cosine-compared - it falls back to text matching instead of failing the search. Legacy bare-array embeddings from v0.3.x remain readable.
+Text search runs one MiniSearch BM25+ pass over title and body. Query terms are OR-matched, with native score order and a deterministic tie-break by creation time and ID. This is keyword matching, not a claim of semantic relevance: results are candidates for the agent to inspect. Matching works across languages by matching literal words, not by meaning. When a query has no tokenizable terms (for example, `!!!`), search falls back to case-insensitive exact-substring matching over title and body. The retained index is reused while the ordered candidate-entry ID list is unchanged, avoiding repeated index construction. Embedding sidecars are still written in the versioned `{ v: 2, model, dimension, vector }` format for compatibility, but search does not read them.
 
 ### Suggested tags
 
@@ -113,7 +113,7 @@ By default the transformers.js model cache lives in the default location (`~/.ca
 
 ```json
 {
-  "cacheDir": "/home/angelo/.cache/opencode/memory-model",
+  "cacheDir": "~/.cache/opencode/memory-model",
   "journal": {
     "enabled": true
   }
@@ -129,6 +129,12 @@ Two behaviour changes:
 - **The journal tools are registered by default.** Previously you had to opt in through `agent-memory.json`; now an absent config means the tools are on, and you turn them off with `"enabled": false`.
 - **Storage is unchanged.** Existing entries under `~/.config/opencode/journal/` and their `.embedding` sidecars stay readable; nothing is migrated or rewritten.
 
+## Upgrading to lexical candidate search
+
+- Text search now ranks entries with lexical OR matching: a candidate may match any query term in its title or body.
+- Results are candidates, not relevance claims. `Found N` reports the candidate count before pagination and will usually be large.
+- A punctuation-only query falls back to case-insensitive substring matching over title and body.
+
 ## Upgrading from 0.4.x
 
 Memory blocks and their tools (`memory_list`, `memory_set`, `memory_replace`) are **removed**. Blocks are no longer read, written, or injected into the system prompt; the plugin ships only the journal.
@@ -140,7 +146,7 @@ Existing `~/.config/opencode/memory/` and `.opencode/memory/` directories are **
 - **Requires OpenCode v2.** This release uses the OpenCode v2 plugin API and does not run on v1.
 - **Restart after config changes.** Plugin config changes require a full OpenCode restart to take effect; editing the config file alone is not sufficient.
 - **Journal is on by default.** Turn it off with `"enabled": false`; an explicit disable is silent, while a config that exists but is unreadable, malformed, or schema-invalid logs a warning and registers no tools (fail-closed).
-- **Local embeddings, no data leaves the machine.** Semantic search uses a locally cached transformers.js model; no external API calls are made for search or embedding.
+- **Embedding sidecars remain compatible.** They are written locally for the existing format contract, diagnostics, and future consumers; text search is lexical and does not read embeddings.
 - **Known limitation (since 0.5.1): guidance-in-descriptions depends on an unverified premise.** 0.5.1 moved journal guidance from the injected system-prompt note into the three journal tool descriptions, so only agents allowed to call those tools should see it. That relies on opencode omitting a permission-denied tool from the definitions sent to the model. This is **unverified**: a `tool.definition` probe on the isolated instance fires before permission filtering, so it cannot confirm what the model actually receives. If the premise does not hold, an agent denied `journal_*` may still read the description text; `deny` still blocks execution, so there is no capability escalation and no data disclosure — the blast radius is the three tools' description strings.
 
 ## Inspiration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghilteras/opencode-agent-memory",
-  "version": "1.2.0",
+  "version": "2.0.1",
   "description": "Journal-only memory plugin for OpenCode: tagged, searchable, append-only journal with semantic search.",
   "author": "Angelo Pantano <ghilteras@protonmail.com>",
   "license": "MIT",
@@ -13,9 +13,7 @@
   },
   "main": "src/plugin.ts",
   "type": "module",
-  "files": [
-    "src"
-  ],
+  "files": ["src", "!src/**/*.test.ts", "!src/test-suite.test.ts"],
   "scripts": {
     "test": "bun run test:core && bun run test:plugin",
     "test:core": "bun test src/test-suite.test.ts src/doctor.test.ts src/embeddings.test.ts src/tools.test.ts src/journal.test.ts",
@@ -27,6 +25,7 @@
     "@huggingface/transformers": "^3.8.1",
     "@opencode/plugin": "^2.0.18",
     "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
     "zod": "^4.1.13"
   },
   "overrides": {

package/src/journal.ts

@@ -3,9 +3,10 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 import * as yaml from "js-yaml";
+import MiniSearch from "minisearch";
 import { z } from "zod";
 
-import { cosineSimilarity, EMBEDDING_DIMENSION, embeddingModelName, generateEmbedding } from "./embeddings";
+import { EMBEDDING_DIMENSION, embeddingModelName, generateEmbedding } from "./embeddings";
 import { atomicWriteFile, buildFrontmatterDocument, splitFrontmatter } from "./frontmatter";
 
 const TagSchema = z.looseObject({
@@ -139,11 +140,20 @@ function embeddingPath(entryPath: string): string {
   return entryPath.replace(/\.md$/, ".embedding");
 }
 
-function titleMatches(queryText: string, title: string): boolean {
-  const q = queryText.trim().toLowerCase();
-  if (!q) return false;
-  const t = title.trim().toLowerCase();
-  return t.includes(q) || q.includes(t);
+function hasLexicalTerms(text: string): boolean {
+  return /[\p{L}\p{N}]+/u.test(text);
+}
+
+function substringMatches(
+  entries: CachedEntry[],
+  query: string,
+): { entry: JournalEntry; score: number }[] {
+  const needle = query.toLowerCase();
+  return entries.flatMap(({ entry }) =>
+    `${entry.title}\n${entry.body}`.toLowerCase().includes(needle)
+      ? [{ entry, score: 0 }]
+      : [],
+  );
 }
 
 async function readEntryFile(filePath: string): Promise<JournalEntry> {
@@ -178,55 +188,12 @@ async function readEntryFile(filePath: string): Promise<JournalEntry> {
   };
 }
 
-type ParsedEmbedding =
-  | { vector: number[]; model: string; dimension: number }
-  | undefined;
-
 type CachedEntry = {
   entryMtimeMs: number;
   entrySize: number;
-  embMtimeMs: number;
-  embSize: number;
   entry: JournalEntry;
-  embedding: ParsedEmbedding;
 };
 
-async function loadEmbedding(entryPath: string): Promise<ParsedEmbedding> {
-  const ePath = embeddingPath(entryPath);
-  try {
-    const raw = await fs.readFile(ePath, "utf-8");
-    const parsed = JSON.parse(raw);
-    if (Array.isArray(parsed)) {
-      // Legacy v1 (bare array from all-MiniLM-L6-v2)
-      return {
-        vector: parsed as number[],
-        model: "unknown-legacy",
-        dimension: parsed.length,
-      };
-    }
-    if (parsed && typeof parsed === "object" && parsed.v === 2) {
-      const vector = Array.isArray(parsed.vector)
-        ? parsed.vector
-        : undefined;
-      if (
-        vector &&
-        vector.length === (parsed.dimension as number) &&
-        vector.length > 0
-      ) {
-        return {
-          vector,
-          model: parsed.model as string,
-          dimension: parsed.dimension as number,
-        };
-      }
-      return undefined;
-    }
-    return undefined;
-  } catch {
-    return undefined;
-  }
-}
-
 const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
 
 function validateId(id: string): string {
@@ -270,6 +237,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
   // different (including nested or ephemeral) journal directories never
   // interfere and no foreign keys can accumulate.
   const entryCache = new Map<string, CachedEntry>();
+  let lexicalIndexSnapshot: { ids: string[]; index: MiniSearch } | undefined;
 
   return {
     async write(entry) {
@@ -294,7 +262,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
       const content = buildFrontmatterDocument(frontmatter, entry.body);
       await atomicWriteFile(filePath, content);
 
-      // Generate and save embedding for semantic search
+      // Keep the sidecar for compatibility with doctor, the format contract, and future consumers; search does not read it.
       const searchableText = `${entry.title}\n${entry.body}`;
       try {
         const embedding = await generateEmbedding(searchableText, cacheDir);
@@ -345,8 +313,6 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
       const limit = Math.min(Math.max(query.limit ?? 20, 1), 50);
       const offset = Math.max(query.offset ?? 0, 0);
 
-      let entries: { entry: JournalEntry; score: number }[] = [];
-
       // Read all entry files
       let files: string[];
       try {
@@ -368,48 +334,28 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         if (!alive.has(key)) entryCache.delete(key);
       }
 
-      // If a text query is provided, try semantic search first
-      let queryEmbedding: number[] | undefined;
-      if (query.text) {
-        try {
-          queryEmbedding = await generateEmbedding(query.text, cacheDir);
-        } catch {
-          // Fall back to text search if embedding fails
-        }
-      }
-
       // Collect all tags across every entry (before filtering)
       const tagSet = new Set<string>();
+      let entryCacheChanged = false;
 
       const indexed = await Promise.all(files.map(async (file) => {
         const filePath = path.join(journalDir, file);
         try {
-          const ePath = embeddingPath(filePath);
-          const [entryStat, embStat] = await Promise.all([
-            fs.stat(filePath),
-            fs.stat(ePath).catch(() => ({ mtimeMs: -1, size: -1 } as const)),
-          ]);
+          const entryStat = await fs.stat(filePath);
           const cached = entryCache.get(filePath);
           if (
             cached &&
             cached.entryMtimeMs === entryStat.mtimeMs &&
-            cached.entrySize === entryStat.size &&
-            cached.embMtimeMs === embStat.mtimeMs &&
-            cached.embSize === embStat.size
+            cached.entrySize === entryStat.size
           ) {
             return cached;
           }
-          const [entry, embedding] = await Promise.all([
-            readEntryFile(filePath),
-            loadEmbedding(filePath),
-          ]);
+          const entry = await readEntryFile(filePath);
+          entryCacheChanged = true;
           const value: CachedEntry = {
             entryMtimeMs: entryStat.mtimeMs,
             entrySize: entryStat.size,
-            embMtimeMs: embStat.mtimeMs,
-            embSize: embStat.size,
             entry,
-            embedding,
           };
           entryCache.set(filePath, value);
           return value;
@@ -418,6 +364,7 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
         }
       }));
 
+      const filtered: CachedEntry[] = [];
       for (const cached of indexed) {
         if (!cached) continue;
         const { entry } = cached;
@@ -439,65 +386,62 @@ export function createJournalStore(configDir?: string, cacheDir?: string): Journ
           if (!allTagsMatch) continue;
         }
 
-        // Score the entry
-        let score = 0;
-
-        if (query.text) {
-          if (queryEmbedding) {
-            // Semantic search
-            const storedEmbedding = cached.embedding;
-            if (storedEmbedding) {
-              // Hard gate: dimension must match, or the embedding is stale
-              // (different model) and cannot be compared with cosine.
-              // A mismatched/stale embedding degrades gracefully to text match.
-              if (storedEmbedding.dimension !== EMBEDDING_DIMENSION) {
-                const haystack =
-                  `${entry.title}\n${entry.body}`.toLowerCase();
-                score = haystack.includes(query.text.toLowerCase()) ? 0.5 : 0;
-              } else {
-                score = cosineSimilarity(
-                  queryEmbedding,
-                  storedEmbedding.vector,
-                );
-              }
-            } else {
-              // No embedding stored; fall back to text match
-              const haystack =
-                `${entry.title}\n${entry.body}`.toLowerCase();
-              score = haystack.includes(query.text.toLowerCase()) ? 0.5 : 0;
-            }
-          } else {
-            // Text search fallback
-            const haystack = `${entry.title}\n${entry.body}`.toLowerCase();
-            score = haystack.includes(query.text.toLowerCase()) ? 1 : 0;
-          }
-
-          // Title-anchor floor: a query that matches the entry title (either
-          // direction, case-insensitive) must not be diluted below the top
-          // ranks by long-body mean pooling (see 20260905-171239-533).
-          if (titleMatches(query.text, entry.title)) {
-            score = Math.max(score, 0.75);
-          }
+        filtered.push(cached);
+      }
 
-          if (score <= 0) continue;
+      let ranked: { entry: JournalEntry; score: number }[];
+      if (!query.text) {
+        ranked = filtered.map(({ entry }) => ({
+          entry,
+          score: entry.created.getTime(),
+        }));
+        ranked.sort((a, b) => b.score - a.score || (a.entry.id < b.entry.id ? 1 : a.entry.id > b.entry.id ? -1 : 0));
+      } else {
+        const ids = filtered.map(({ entry }) => entry.id);
+        const sameEntries = !entryCacheChanged && lexicalIndexSnapshot !== undefined &&
+          lexicalIndexSnapshot.ids.length === ids.length &&
+          ids.every((id, index) => lexicalIndexSnapshot!.ids[index] === id);
+        let lexicalIndex: MiniSearch;
+        if (sameEntries) {
+          lexicalIndex = lexicalIndexSnapshot!.index;
         } else {
-          // No text query - chronological order (score by recency)
-          score = entry.created.getTime();
+          const builtIndex = new MiniSearch({
+            fields: ["title", "body"],
+            storeFields: ["id"],
+          });
+          builtIndex.addAll(filtered.map(({ entry }) => ({
+            id: entry.id,
+            title: entry.title,
+            body: entry.body,
+          })));
+          lexicalIndexSnapshot = { ids, index: builtIndex };
+          lexicalIndex = builtIndex;
         }
-
-        entries.push({ entry, score });
+        const byId = new Map(filtered.map(({ entry }) => [entry.id, entry]));
+        const lexical = lexicalIndex.search(query.text, { combineWith: "OR" });
+        if (hasLexicalTerms(query.text)) {
+          ranked = lexical.flatMap((match) => {
+            const entry = byId.get(String(match.id));
+            return entry ? [{ entry, score: match.score }] : [];
+          });
+        } else {
+          ranked = substringMatches(filtered, query.text);
+        }
+        ranked.sort((a, b) =>
+          b.score - a.score ||
+          b.entry.created.getTime() - a.entry.created.getTime() ||
+          (a.entry.id < b.entry.id ? 1 : a.entry.id > b.entry.id ? -1 : 0),
+        );
       }
 
-      const total = entries.length;
-
-      // Sort by score descending
-      entries.sort((a, b) => b.score - a.score);
+      // Count lexical candidates after metadata filtering, before paging.
+      const total = ranked.length;
 
       // Apply offset + limit
-      entries = entries.slice(offset, offset + limit);
+      ranked = ranked.slice(offset, offset + limit);
 
       return {
-        entries: entries.map((e) => e.entry),
+        entries: ranked.map((e) => e.entry),
         total,
         allTags: Array.from(tagSet).sort(),
       };

package/src/tools.ts

@@ -76,11 +76,11 @@ export function JournalRead(store: JournalStore): ToolDefinition {
 export function JournalSearch(store: JournalStore): ToolDefinition {
   return {
     name: "journal_search",
-    description: "Search journal entries using semantic similarity. Returns matching entries sorted by relevance. All filters are optional and combined with AND logic. Use with no arguments to list recent entries. Use offset to paginate. Before starting complex tasks, search the journal for relevant past context. The journal is global across all projects but each entry records which project it was written from.",
+    description: "Find candidate journal entries by lexical OR matching query words in titles and bodies. Candidates are not relevance claims. All filters are optional and combined with AND logic. Use with no arguments to list recent entries. Use offset to paginate. Before starting complex tasks, search the journal for relevant past context. The journal is global across all projects but each entry records which project it was written from.",
     input: {
       type: "object",
       properties: {
-        text: { type: "string", description: "Semantic search text" },
+        text: { type: "string", description: "Query words for lexical candidate matching in titles and bodies" },
         project: { type: "string", description: "Filter by project directory" },
         tags: { type: "string", description: "Comma-separated tags; all must match" },
         limit: { type: "integer", minimum: 1, description: "Maximum entries to return" },
@@ -99,7 +99,7 @@ export function JournalSearch(store: JournalStore): ToolDefinition {
       const tagsLine = formatTagsInUse(result.allTags);
       if (!result.entries.length) return { content: `No journal entries found.${tagsLine}` };
       const offset = (input.offset as number | undefined) ?? 0;
-      const header = `Found ${result.total} entries (showing ${offset + 1}–${offset + result.entries.length}):`;
+      const header = `Found ${result.total} candidate entries (showing ${offset + 1}–${offset + result.entries.length}):`;
       const lines = result.entries.map((entry) => `${entry.id}\n  ${entry.title}${entry.tags.length ? ` [${entry.tags.join(", ")}]` : ""}\n  ${entry.created.toISOString()}`);
       return { content: `${header}${tagsLine}\n\n${lines.join("\n\n")}` };
     },

package/src/doctor.test.ts

@@ -1,183 +0,0 @@
-import { afterEach, expect, test } from "bun:test";
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { diagnoseJournal } from "./doctor";
-
-const roots: string[] = [];
-async function fixture() {
-  const root = await fs.mkdtemp(path.join(os.tmpdir(), "journal-doctor-"));
-  roots.push(root);
-  await fs.mkdir(path.join(root, "journal"));
-  return path.join(root, "journal");
-}
-async function entry(dir: string, name: string, yamlText?: string, sidecar?: string) {
-  await fs.writeFile(path.join(dir, `${name}.md`), yamlText === undefined ? "plain text" : `---\n${yamlText}\n---\nbody\n`);
-  if (sidecar !== undefined) await fs.writeFile(path.join(dir, `${name}.embedding`), sidecar);
-}
-afterEach(async () => { await Promise.all(roots.splice(0).map((root) => fs.rm(root, { recursive: true, force: true }))); });
-
-test("classifies frontmatter, created values, sidecars and multiple findings deterministically", async () => {
-  const dir = await fixture();
-  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
-  await entry(dir, "00-valid", valid, JSON.stringify({ v: 2, model: "wrong-model", dimension: 2, vector: [0.1, 0.2] }));
-  await entry(dir, "01-missing-title", "created: \"2025-01-01\"");
-  await entry(dir, "02-empty-title", 'title: ""');
-  await entry(dir, "03-wrong-title", "title: 42");
-  await entry(dir, "04-missing-created", "title: Present", "[1,2]");
-  await entry(dir, "05-date-only", "title: Present\ndate: \"2025-01-01\"");
-  await entry(dir, "06-invalid-created", 'title: Present\ncreated: "not a date"');
-  await entry(dir, "07-wrong-created", "title: Present\ncreated: 42");
-  await entry(dir, "08-yaml-timestamp", "title: Present\ncreated: 2025-01-01T00:00:00Z");
-  await entry(dir, "09-bad-yaml", "title: [broken");
-  await entry(dir, "10-no-frontmatter");
-  await entry(dir, "11-malformed-json", valid, "{");
-  await entry(dir, "12-vector-type", valid, '{"v":2,"model":"m","dimension":1,"vector":["x"]}');
-  await entry(dir, "13-empty-vector", valid, '{"v":2,"model":"m","dimension":0,"vector":[]}');
-  await entry(dir, "14-vector-dimension", valid, '{"v":2,"model":"m","dimension":3,"vector":[1,2]}');
-  await entry(dir, "15-legacy", valid, "[1,2]");
-  await entry(dir, "16-legacy-invalid", valid, '[1,"x"]');
-  await entry(dir, "17-missing-sidecar", valid);
-
-  const inventory = async () => Promise.all((await fs.readdir(dir)).sort().map(async (f) => [f, await fs.readFile(path.join(dir, f)), (await fs.stat(path.join(dir, f))).mtimeMs] as const));
-  const before = await inventory();
-  const report = await diagnoseJournal(path.dirname(dir));
-  expect(await diagnoseJournal(path.dirname(dir))).toEqual(report);
-  expect(report.counts.files).toBe(18);
-  const codes = (name: string) => report.findings.filter((f) => f.path.startsWith(name)).map((f) => f.code);
-  expect(codes("01-missing-title")).toContain("frontmatter_title_invalid");
-  expect(codes("02-empty-title")).toContain("frontmatter_title_invalid");
-  expect(codes("03-wrong-title")).toContain("frontmatter_title_invalid");
-  expect(codes("04-missing-created")).toContain("created_missing");
-  expect(codes("05-date-only")).toContain("created_missing");
-  expect(codes("06-invalid-created")).toContain("created_invalid");
-  expect(codes("07-wrong-created")).toContain("frontmatter_created_invalid");
-  expect(codes("08-yaml-timestamp")).toContain("frontmatter_created_invalid");
-  expect(codes("09-bad-yaml")).toContain("yaml_malformed");
-  expect(codes("10-no-frontmatter")).toContain("frontmatter_missing_or_malformed");
-  expect(codes("11-malformed-json")).toContain("embedding_json_malformed");
-  for (const name of ["12-vector-type", "13-empty-vector", "14-vector-dimension", "16-legacy-invalid"]) expect(codes(name)).toContain("embedding_invalid");
-  expect(codes("00-valid")).toContain("embedding_incompatible");
-  expect(codes("15-legacy")).toContain("embedding_model_unknown");
-  expect(codes("17-missing-sidecar")).toContain("embedding_missing");
-  expect(codes("04-missing-created")).toEqual(expect.arrayContaining(["created_missing", "embedding_model_unknown"]));
-  expect(report.findings).toEqual([...report.findings].sort((a, b) => a.path.localeCompare(b.path) || a.code.localeCompare(b.code) || a.severity.localeCompare(b.severity)));
-  expect(report.findings.some((f) => /broken|Good|Present|not a date/.test(JSON.stringify(f)))).toBe(false);
-  expect(await inventory()).toEqual(before);
-});
-
-test("empty, missing, and injected unreadable roots/files have explicit incomplete semantics", async () => {
-  const missing = await diagnoseJournal("/path/that/does/not/exist");
-  expect(missing.complete).toBe(false);
-  expect(missing.findings[0]?.code).toBe("root_unreadable");
-  const dir = await fixture();
-  expect((await diagnoseJournal(path.dirname(dir))).complete).toBe(true);
-  await entry(dir, "a", "title: A"); await entry(dir, "b", "title: B");
-  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
-    if (String(p).endsWith("a.md")) throw new Error("injected");
-    return fs.readFile(p, ...(args as [any]));
-  } } as unknown as typeof fs;
-  const report = await diagnoseJournal(path.dirname(dir), failingRead);
-  expect(report.complete).toBe(false);
-  expect(report.findings.some((f) => f.path === "a.md" && f.code === "file_unreadable")).toBe(true);
-  expect(report.findings.some((f) => f.path === "b.md" && f.code === "created_missing")).toBe(true);
-});
-
-test("CLI emits exact bytes and exit codes for clean, warning, error, incomplete and bad invocation", async () => {
-  const dir = await fixture();
-  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
-  const invoke = (...args: string[]) => Bun.spawnSync([process.execPath, "run", cli, ...args], { stdout: "pipe", stderr: "pipe" });
-  const assertCli = (result: ReturnType<typeof invoke>, stdout: string, stderr: string, exitCode: number) =>
-    expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout, stderr, exitCode });
-  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":0,"errors":0,"warnings":0},"findings":[]}\n', "", 0);
-
-  await entry(dir, "warning", 'title: Warn\ncreated: "2025-01-01"');
-  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":1,"errors":0,"warnings":1},"findings":[{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 0);
-
-  await entry(dir, "invalid", "title: 12");
-  assertCli(invoke(path.dirname(dir)), '{"complete":true,"counts":{"files":2,"errors":1,"warnings":2},"findings":[{"path":"invalid.embedding","code":"embedding_missing","severity":"warning"},{"path":"invalid.md","code":"frontmatter_title_invalid","severity":"error"},{"path":"warning.embedding","code":"embedding_missing","severity":"warning"}]}\n', "", 1);
-
-  assertCli(invoke("/path/that/does/not/exist"), '{"complete":false,"counts":{"files":0,"errors":1,"warnings":0},"findings":[{"path":".","code":"root_unreadable","severity":"error"}]}\n', "", 2);
-  assertCli(invoke(path.dirname(dir), "extra"), "", "usage: bun run journal:doctor [config-dir]\n", 2);
-});
-
-test("inventories orphan and associated sidecars independently and emits stable full report", async () => {
-  const dir = await fixture();
-  const valid = 'title: Good\ncreated: "2025-01-01T00:00:00Z"';
-  await entry(dir, "A", valid);
-  await entry(dir, "a", valid, "{");
-  await fs.writeFile(path.join(dir, "_.embedding"), "{");
-  const expected = { complete: true, counts: { files: 2, errors: 2, warnings: 2 }, findings: [
-    { path: "A.embedding", code: "embedding_missing", severity: "warning" },
-    { path: "_.embedding", code: "embedding_json_malformed", severity: "error" },
-    { path: "_.embedding", code: "embedding_orphan", severity: "warning" },
-    { path: "a.embedding", code: "embedding_json_malformed", severity: "error" },
-  ] };
-  const report = await diagnoseJournal(path.dirname(dir));
-  expect(JSON.stringify(report)).toBe(JSON.stringify(expected));
-  const cli = path.resolve(import.meta.dir, "journal-doctor.ts");
-  const result = Bun.spawnSync([process.execPath, "run", cli, path.dirname(dir)], { stdout: "pipe", stderr: "pipe" });
-  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: `${JSON.stringify(expected)}\n`, stderr: "", exitCode: 1 });
-});
-
-test("sidecar validation survives markdown read failure; listed sidecar disappearance is incomplete", async () => {
-  const dir = await fixture();
-  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "{");
-  const failingRead = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
-    if (String(p).endsWith("a.md")) throw Object.assign(new Error("denied"), { code: "EACCES" });
-    return fs.readFile(p, ...(args as [any]));
-  } } as unknown as typeof fs;
-  const failed = await diagnoseJournal(path.dirname(dir), failingRead);
-  expect(failed.complete).toBe(false);
-  expect(failed.findings.map((f) => f.code)).toEqual(expect.arrayContaining(["file_unreadable", "embedding_json_malformed"]));
-
-  let removed = false;
-  const disappearing = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
-    if (String(p).endsWith("a.embedding") && !removed) { removed = true; throw Object.assign(new Error("gone"), { code: "ENOENT" }); }
-    return fs.readFile(p, ...(args as [any]));
-  } } as unknown as typeof fs;
-  const gone = await diagnoseJournal(path.dirname(dir), disappearing);
-  expect(gone.complete).toBe(false);
-  expect(gone.findings.some((f) => f.path === "a.embedding" && f.code === "embedding_unreadable")).toBe(true);
-});
-
-test("diagnosis never initializes model pipeline or fetches, while warmup activates trap in child", async () => {
-  const dir = await fixture();
-  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"');
-  const childCode = `
-    import { mock } from "bun:test";
-    let pipelines = 0, fetches = 0;
-    const originalFetch = globalThis.fetch;
-    globalThis.fetch = async (...args) => { fetches++; throw new Error("FETCH_SENTINEL"); };
-    mock.module("@huggingface/transformers", () => ({ pipeline: async () => { pipelines++; throw new Error("PIPELINE_SENTINEL"); } }));
-    const { diagnoseJournal } = await import(${JSON.stringify(path.resolve(import.meta.dir, "doctor.ts"))});
-    const { warmupEmbedder } = await import(${JSON.stringify(path.resolve(import.meta.dir, "embeddings.ts"))});
-    await diagnoseJournal(${JSON.stringify(path.dirname(dir))});
-    if (pipelines !== 0 || fetches !== 0) throw new Error("diagnosis activated model/fetch trap");
-    try { await warmupEmbedder(); throw new Error("pipeline sentinel was not caught"); } catch (error) { if (!String(error).includes("PIPELINE_SENTINEL")) throw error; }
-    if (pipelines !== 1 || fetches !== 0) throw new Error("pipeline trap count mismatch");
-    globalThis.fetch = originalFetch;
-    console.log(JSON.stringify({ pipelines, fetches }));
-  `;
-  const result = Bun.spawnSync([process.execPath, "-e", childCode], { stdout: "pipe", stderr: "pipe" });
-  expect({ stdout: result.stdout.toString(), stderr: result.stderr.toString(), exitCode: result.exitCode }).toEqual({ stdout: '{"pipelines":1,"fetches":0}\n', stderr: "", exitCode: 0 });
-});
-
-test("only flat regular inventory files are read and each sidecar is read once", async () => {
-  const dir = await fixture();
-  await entry(dir, "a", 'title: Good\ncreated: "2025-01-01T00:00:00Z"', "[1]");
-  await fs.mkdir(path.join(dir, "nested"));
-  await fs.writeFile(path.join(dir, "nested", "hidden.md"), "bad");
-  await fs.writeFile(path.join(dir, "nested", "hidden.embedding"), "{");
-  await fs.writeFile(path.join(dir, "ignored.txt"), "bad");
-  await fs.symlink(path.join(dir, "a.md"), path.join(dir, "linked.md"));
-  const reads = new Map<string, number>();
-  const counting = { ...fs, readFile: async (p: Parameters<typeof fs.readFile>[0], ...args: any[]) => {
-    const name = path.basename(String(p)); reads.set(name, (reads.get(name) ?? 0) + 1);
-    return fs.readFile(p, ...(args as [any]));
-  } } as unknown as typeof fs;
-  const report = await diagnoseJournal(path.dirname(dir), counting);
-  expect(report.counts.files).toBe(1);
-  expect([...reads.entries()].sort()).toEqual([["a.embedding", 1], ["a.md", 1]]);
-  expect(report.findings.map((f) => f.path)).toEqual(["a.embedding", "a.embedding"]);
-});