@oomkapwn/enquire-mcp 3.9.0-rc.6 → 3.9.0-rc.7

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.9.0-rc.7] — 2026-05-25
+
+> **TL;DR:** **Tier 0 integrity batch from a full project audit** (deep code audit of all 31 src/ modules + docs/workflows/config audit + competitive survey of the Obsidian-MCP / AI-memory / RAG-MCP landscapes). Fixes the two brand-critical overclaims the audit surfaced — **#15 SLSA-3** (badge linked to the slsa.dev **L3** spec + 8+ surfaces claimed "SLSA-3", but `release.yml` only runs `npm publish --provenance` = SLSA Build **L2**) and corrects pervasive version/RC drift + an undersold reranker number. Adds a public **ROADMAP.md**, gitignores the stray `false/` npm-cache tree, adds `CITATION.cff` version field, and documents a new overclaim anti-pattern (the "claimed-guarantee vs code-guard" class behind #15 + #16). **Docs/config-only; 926 tests unchanged. The OCR-offline-enforcement overclaim (#16, "implement" decision) ships in rc.8; the watcher live-update race (H1) in rc.9.**
+
+**Patch — audit-driven integrity (Tier 0).**
+
+### The audit
+
+Three parallel passes:
+1. **Deep code audit** (all `src/*.ts` + `src/tools/*.ts`, whole files): **zero CRITICAL**. The codebase is well-hardened (constant-time bearer compare, ReDoS-safe glob/like walkers, fail-closed `.base` predicates, transactional SQLite). Residual: 1 HIGH (watcher race, H1), 1 HIGH (OCR offline overclaim, #16), 5 MEDIUM, 5 LOW.
+2. **Docs/workflows/config audit**: SLSA-3 overclaim (#15), version drift, OIA self-count drift (docs say "6 checks", code has 8), reranker undersell, `false/` junk dir, no ROADMAP, missing OSS-health files.
+3. **Competitive survey**: enquire is technically ahead of every Obsidian-MCP peer (CRUD-only or REST-plugin-dependent); near-parity with local-RAG MCPs (knowledge-rag); behind AI-memory frameworks (mem0/cognee/Letta/Zep) only on **published LoCoMo numbers**, **entity knowledge graph**, and **discoverability** (8★). Letta's "filesystem memory scores 74% LoCoMo" validates our vault-as-memory thesis.
+
+### Fixed in this rc.7 (Tier 0)
+
+- **#15 SLSA-3 → SLSA L2 (overclaim instance #15).** Real mechanism is `npm publish --provenance` + GitHub OIDC = a Sigstore-signed provenance attestation = **SLSA Build Level 2** (hosted builder + non-forgeable-by-author provenance). Level 3 needs an isolated builder via `slsa-framework/slsa-github-generator`. Corrected every surface: README badge (now links to the L2 spec) + hero line + comparison table + releases row, package.json description + keyword (`slsa-3` → `build-provenance`), llms.txt (×2), docs/COMPARISON.md (×2). Earning real L3 is now a tracked **ROADMAP Tier 4** item, not a claim.
+- **Version/RC drift.** README "Pre-release: currently v3.9.0-rc.3" → rc.6; QUICKSTART version example → rc.6; benchmarks.md "still valid as of rc.3" → rc.6; AGENTS.md "OIA — 6 checks" → 8 (×2); CLAUDE.md OIA-walk description "6 cheap walks" → 8 + the rc.4 "(current)" marker corrected.
+- **Reranker undersold → measured numbers.** README (3 sites) + llms.txt: "+5-10 NDCG@10 typical" → **+15.5 NDCG@10 / +24.7 MRR measured** (the figure already in COMPARISON.md + benchmarks.md). The repo was undercutting its own measured, reproducible result by ~50%.
+- **`false/` npm-cache junk → `.gitignore`.** A stray `--cache false` / `npm_config_cache=false` mis-parse created an untracked `_cacache`/`_logs` tree at repo root; one `git add .` would have committed it.
+- **CITATION.cff** gains `version` (tracks the @latest stable line, deliberately not in version-consistency) + `date-released`.
+- **New `ROADMAP.md`** — public, tiered (Tier 0 integrity → Tier 1 correctness → Tier 2 LoCoMo benchmarks → Tier 3 GraphRAG-full / conversational write-back → Tier 4 discoverability + real SLSA-L3). Linked from README.
+- **New anti-pattern documented (CLAUDE.md):** "Never claim an ENFORCED guarantee the code doesn't actually enforce" — the class behind overclaim #15 (SLSA) + #16 (OCR offline). The invariant apparatus checks numeric/doc drift but had no defense for "we promise enforcement X; does a code path enforce X?". Candidate structural defense (deferred): an OIA enforcement-verb grep.
+
+### Deferred to the next RCs (tracked in ROADMAP.md)
+
+- **rc.8 — #16 OCR offline enforcement (HIGH, "implement" decision).** SECURITY.md claims "zero outbound network calls in serve mode" and `ocr.ts` TSDoc claims a pre-flight "throws if language not installed" check, but `extractPdfWithOcr` only warns then `createWorker` silently CDN-fetches; `install-ocr-lang` is referenced in 4 files but never existed. Implement: pre-flight cache check + `langPath` wiring + real `install-ocr-lang` subcommand + env-gated integration test.
+- **rc.9 — H1 watcher per-file serialization (HIGH).** Fire-and-forget `handle()` lets concurrent saves to one file interleave `applyDiff` + the shared `rowsByLabel` mutation → in-memory HNSW drift. Add a per-relPath promise queue + concurrent-event test. Plus M1 (HNSW `saveTo` live count), L2 (unlink kind).
+
+### Files changed
+
+- `README.md` — SLSA badge/hero/table/releases; reranker numbers (×3); RC currency; ROADMAP link.
+- `package.json` — description SLSA wording + `slsa-3`→`build-provenance` keyword.
+- `llms.txt` — SLSA (×2) + reranker number.
+- `docs/COMPARISON.md` — SLSA row + provenance paragraph.
+- `docs/QUICKSTART.md`, `docs/benchmarks.md` — RC currency.
+- `AGENTS.md`, `CLAUDE.md` — OIA check count (6→8); CLAUDE status rc.7 entry + new anti-pattern.
+- `CITATION.cff` — version + date-released.
+- `.gitignore` — `false/`.
+- `ROADMAP.md` — new file.
+- version bump 3.9.0-rc.6 → 3.9.0-rc.7 (7 surfaces).
+
+---
+
 ## [3.9.0-rc.6] — 2026-05-25
 
 > **TL;DR:** **HNSW disk persistence on live update.** When the watcher applies HNSW live updates (`applyDiff`) during a serve session, the in-memory index diverges from the persisted `.hnsw.bin` sidecar. This rc re-persists the live-updated index at watcher **close time** so the next serve loads the up-to-date sidecar (~50ms) instead of rebuilding from embed-db (~25s on 50K chunks). Correctness was always guaranteed by the signature guard (a stale sidecar is ignored → safe rebuild); this is purely a restart-speed optimization. Chose close-time flush over a debounced during-serve timer: same restart benefit, no timer-lifecycle complexity, no mid-serve disk I/O. **+3 tests (2 POSITIVE + 1 NEGATIVE control); 926 unit tests total. No API breaks (additive).**

package/README.md

@@ -15,7 +15,7 @@
 [![downloads](https://img.shields.io/npm/dm/@oomkapwn/enquire-mcp.svg?color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)
 [![tests](https://img.shields.io/badge/tests-926%20passing-brightgreen.svg)](#trust)
 [![stable](https://img.shields.io/badge/v3.8.x-stable-brightgreen.svg)](./STABILITY.md)
-[![SLSA-3](https://img.shields.io/badge/SLSA-3-blue.svg)](https://slsa.dev/spec/v1.0/levels#build-l3)
+[![build provenance](https://img.shields.io/badge/build_provenance-SLSA_L2-blue.svg)](https://slsa.dev/spec/v1.0/levels#build-l2)
 [![MCP](https://img.shields.io/badge/MCP-1.29-8A2BE2.svg)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
 
@@ -38,7 +38,7 @@ Your Obsidian vault becomes **persistent, queryable long-term memory** for any M
 > 2. **Best-in-class retrieval.** Hybrid BM25 + multilingual embeddings + BGE cross-encoder reranker fused via RRF, scaled with HNSW + int8 quantization. The same IR stack a search startup would build — open-sourced, in one binary.
 > 3. **Zero cloud calls during serve.** Models cached locally (one-time download from HuggingFace). Your vault content never leaves your machine. Air-gap-safe by default.
 
-**44 tools · 19 MCP prompts · 926 unit tests · 50+ languages · v3.8.x stable · semver-bound · MIT · SLSA-3 signed.**
+**44 tools · 19 MCP prompts · 926 unit tests · 50+ languages · v3.8.x stable · semver-bound · MIT · npm build provenance (SLSA L2).**
 
 ---
 
@@ -159,7 +159,7 @@ Auto-generated **[API reference at oomkapwn.github.io/enquire-mcp](https://oomka
 | Capability | enquire-mcp | Smart Connections | Other Obsidian-MCPs |
 |---|:---:|:---:|:---:|
 | Hybrid retrieval (BM25 + TF-IDF + ML embeddings, RRF-fused) | ✅ | ❌ | ❌ |
-| **Cross-encoder reranking** (BGE, +5-10 NDCG@10) | ✅ | ❌ | ❌ |
+| **Cross-encoder reranking** (BGE, +15.5 NDCG@10 measured) | ✅ | ❌ | ❌ |
 | **HNSW vector index** (sub-10ms top-K, persisted) | ✅ | ❌ | ❌ |
 | **int8 vector quantization** (~4× smaller embed-db) | ✅ | ❌ | ❌ |
 | **Late-chunking** context-windowed embeddings | ✅ | ❌ | ❌ |
@@ -177,7 +177,7 @@ Auto-generated **[API reference at oomkapwn.github.io/enquire-mcp](https://oomka
 | **Standalone `.base` query execution** (works without Obsidian running) | ✅ **only here** | ❌ | ❌ delegates to Obsidian |
 | **HyDE retrieval** (Gao et al 2023) + sub-question decomposition | ✅ **only here** | ❌ | ❌ |
 | **926 unit tests · 9 required + 4 advisory CI gates per PR** | ✅ | n/a | rare |
-| **SLSA-3 build provenance** | ✅ | n/a | ❌ |
+| **Signed build provenance** (npm + Sigstore, SLSA Build L2) | ✅ | n/a | ❌ |
 | **Semver-bound public surface** ([STABILITY.md](./STABILITY.md)) | ✅ | n/a | ❌ |
 | Standalone (no Obsidian plugin needed) | ✅ | ❌ requires Obsidian | varies |
 | License | MIT, free | proprietary, paid | varies |
@@ -204,14 +204,14 @@ graph LR
     RR --> R[Ranked hits<br/>per_signal observability]
 ```
 
-`obsidian_search` auto-detects available signals and gracefully degrades. Wikilink graph-boost reranks top-K via 1-step personalised PageRank. Optional cross-encoder reranking re-scores top-N for +5-10 NDCG@10. Every hit returns `per_signal: { bm25, tfidf, embeddings }` so you see WHY it ranked.
+`obsidian_search` auto-detects available signals and gracefully degrades. Wikilink graph-boost reranks top-K via 1-step personalised PageRank. Optional cross-encoder reranking re-scores top-N for +15.5 NDCG@10 measured. Every hit returns `per_signal: { bm25, tfidf, embeddings }` so you see WHY it ranked.
 
 | Tier | Setup | What you get |
 |---|---|---|
 | **1** | `serve --vault <path>` | TF-IDF cosine (zero setup, instant) |
 | **2** | + `--persistent-index` | + BM25 / FTS5 (sub-100ms top-10) |
 | **3** | + `setup` (downloads model + builds embed-db) | + multilingual ML embeddings |
-| **4** | + `--enable-reranker` | + BGE cross-encoder (+5-10 NDCG@10) |
+| **4** | + `--enable-reranker` | + BGE cross-encoder (+15.5 NDCG@10 measured) |
 | **5** | + `--use-hnsw` | + sub-10ms top-K at million-chunk scale |
 | **6** | + `--include-pdfs` | + PDFs blended into all of the above |
 | **7** | `serve-http --bearer-token …` | + remote MCP (Claude.ai web, ChatGPT, Cursor HTTP, mobile) |
@@ -248,7 +248,7 @@ Plus 3 MCP resources (`obsidian://vault/info`, `obsidian://note/{path}`, `obsidi
 | **Cache + index files** | chmod 0600, parent dir 0700 |
 | **CI** | **9 required** branch-protection gates: (1) `lint`, (2) `test` on Node 22, (3) `test` on Node 24, (4) `smoke`, (5) `audit`, (6) `coverage`, (7) `version-consistency`, (8) `docs`, (9) `oia`. **4 advisory**: `test-macos` via `.github/workflows/ci.yml`; CodeQL ×2 + Analyze actions via [GitHub default-setup](https://docs.github.com/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning) (not workflow files). Release workflow re-verifies all 9 required passed on tagged SHA before npm publish. _v3.7.10 — `docs` (TypeDoc generation gate) added to required set. v3.7.13 — `engines.node` floor bumped to `>=22.13.0` to match the CI matrix. v3.8.0-rc.6 — `oia` (Outside-In Audit) promoted from advisory._ |
 | **Coverage** | Lines ≥86% · statements ≥82% · functions ≥75% · branches ≥74% (gated) |
-| **Releases** | npm + GitHub release per tag · semver · **SLSA-3** build provenance |
+| **Releases** | npm + GitHub release per tag · semver · **signed build provenance** (npm + Sigstore, SLSA Build L2; L3 generator on the roadmap) |
 | **Stability** | v3.0+ semver-bound — every CLI flag, tool name, MCP resource, prompt, exported symbol is contract |
 
 Full posture: **[SECURITY.md](./SECURITY.md)** · Stability surface: **[STABILITY.md](./STABILITY.md)** · Vulns: `oomkapwn@gmail.com`.
@@ -277,7 +277,7 @@ Full posture: **[SECURITY.md](./SECURITY.md)** · Stability surface: **[STABILIT
 
 `v2.0` hybrid retrieval (BM25+TF-IDF+embeddings via RRF) · `v2.6` remote MCP · `v2.7-2.8` PDFs blended · `v2.9` BGE reranker · `v2.10` OCR · `v2.11` doctor + setup · `v2.12` eval harness · `v2.13` HNSW · `v2.14` stateful sessions · `v2.15` late-chunking · `v2.16` HNSW persistence · `v2.17` int8 quantization · `v3.8.0` stable · `v3.8.7` HTTP transport hardening · **`v3.9.0` (on `@rc`)**: OCR'd PDF watcher embed-sync, HNSW in-memory live update on file changes, R-10 adaptive HNSW refill (closes the >66% excluded under-return).
 
-Channel: `npm install @oomkapwn/enquire-mcp` → latest stable (`@latest` = v3.8.x). Pre-release: `npm install @oomkapwn/enquire-mcp@rc` (currently v3.9.0-rc.3). Full changelog: **[CHANGELOG.md](./CHANGELOG.md)**.
+Channel: `npm install @oomkapwn/enquire-mcp` → latest stable (`@latest` = v3.8.x). Pre-release: `npm install @oomkapwn/enquire-mcp@rc` (currently v3.9.0-rc.6). Full changelog: **[CHANGELOG.md](./CHANGELOG.md)** · Forward plan: **[ROADMAP.md](./ROADMAP.md)**.
 
 ---
 

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * + `McpServer({version})`) and `src/tool-registry.ts` (used in the
  * `vault-info` resource payload).
  */
-export declare const VERSION = "3.9.0-rc.6";
+export declare const VERSION = "3.9.0-rc.7";
 export { main } from "./cli.js";
 export { buildEmbedText, buildMcpServer, formatReadyBanner, prepareServerDeps, type ServeOptions, type ServerDeps, startServer } from "./server.js";
 export { parsePositiveInt, parseQuantizationMode } from "./tool-registry.js";

package/dist/index.js

@@ -40,7 +40,7 @@ import { main } from "./cli.js";
  * + `McpServer({version})`) and `src/tool-registry.ts` (used in the
  * `vault-info` resource payload).
  */
-export const VERSION = "3.9.0-rc.6";
+export const VERSION = "3.9.0-rc.7";
 // Re-exports — preserve the v3.5.x public surface so http-transport.ts and
 // tests don't need to know about the new module layout. The set below
 // exactly matches the v3.5.x `export` declarations: `main`,

package/docs/COMPARISON.md

@@ -42,7 +42,7 @@ The four axes the external audit (#3, 2026-05) called out as decisive — **REST
 | Invoke Obsidian palette commands / hotkeys    | **No**              | **Yes**          | Limited          | No               | No               |
 | Read open editor state, active note, etc.     | **No**              | **Yes**          | Limited          | No               | No               |
 | Zero outbound network calls in serve mode     | **Yes** (default)   | Local-only (REST)| Local-only (REST)| Yes              | Yes              |
-| SLSA-3 build provenance on releases           | **Yes**             | No               | No               | No               | No               |
+| Signed build provenance on releases (SLSA L2) | **Yes**             | No               | No               | No               | No               |
 | Test count (public)                           | **926**             | (varies)         | (varies)         | (varies)         | (varies)         |
 | Tool count                                    | 44                  | ~25              | ~8               | ~10              | 3–5              |
 | MCP prompt count                              | 19                  | 0                | 0                | 0                | 0                |
@@ -193,7 +193,7 @@ The alternatives expose tools but not curated agent-facing prompts. If your clie
 
 ### 6. Supply-chain hygiene matters
 
-enquire-mcp publishes **SLSA-3 build provenance** with every release — npm artifacts are signed and verifiable against the GitHub Actions build. If your org's MCP install path requires verifying that the binary you got from npm was built from the commit it claims, that's available out of the box.
+enquire-mcp publishes **signed build provenance** with every release — npm artifacts carry a Sigstore-signed provenance attestation (via `npm publish --provenance` + GitHub OIDC), verifiable with `npm audit signatures` against the GitHub Actions build. This is **SLSA Build Level 2** (hosted builder + signed, non-forgeable-by-author provenance). Isolated-builder **Level 3** (via the `slsa-github-generator` reusable workflow) is on the roadmap. If your org's MCP install path requires verifying that the binary you got from npm was built from the commit it claims, that's available out of the box.
 
 None of the four alternatives currently ships SLSA provenance. For some users this is a hard "no" on installing anything else; for most it's a "nice to have".
 

package/docs/QUICKSTART.md

@@ -29,7 +29,7 @@ Verify the install:
 enquire-mcp --version
 ```
 
-Expected output: the current version string (e.g. `3.9.0-rc.3` on `@rc` or `3.8.8` on `@latest`).
+Expected output: the current version string (e.g. `3.9.0-rc.6` on `@rc` or `3.8.8` on `@latest`).
 
 ## Step 2 — Smoke test (30 seconds)
 

package/docs/benchmarks.md

@@ -1,6 +1,6 @@
 # Benchmarks — enquire-mcp retrieval quality
 
-**Last updated:** 2026-05-15 (latency numbers re-measured under v3.7.10 against `bench/benchmarks.json`; methodology table updated v3.7.13 M11 to drop the duplicate latency column; ratio claim recomputed v3.7.18 B-3 against current TL;DR figures). Quality metrics (MRR / NDCG@10 / Recall@10) are deterministic and stable across the v3.7.x → v3.9.0-rc cascade (still valid as of v3.9.0-rc.3 — retrieval pipeline unchanged; v3.8.x→v3.9.0 work was correctness/hardening + watcher live-update, not algorithmic). · **Generated by:** `npm run bench:retrieval`
+**Last updated:** 2026-05-15 (latency numbers re-measured under v3.7.10 against `bench/benchmarks.json`; methodology table updated v3.7.13 M11 to drop the duplicate latency column; ratio claim recomputed v3.7.18 B-3 against current TL;DR figures). Quality metrics (MRR / NDCG@10 / Recall@10) are deterministic and stable across the v3.7.x → v3.9.0-rc cascade (still valid as of v3.9.0-rc.6 — retrieval pipeline unchanged; v3.8.x→v3.9.0 work was correctness/hardening + watcher live-update, not algorithmic). · **Generated by:** `npm run bench:retrieval`
 
 This page reports retrieval-quality numbers for every layer of the enquire-mcp
 hybrid stack against a deterministic synthetic vault. **Every metric below is

package/package.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oomkapwn/enquire-mcp",
-  "version": "3.9.0-rc.6",
+  "version": "3.9.0-rc.7",
   "mcpName": "io.github.oomkapwn/enquire-mcp",
-  "description": "MCP server giving AI agents (Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, OpenClaw) persistent long-term memory backed by your local Obsidian markdown vault. Hybrid retrieval (BM25 + ML embeddings + BGE reranker, RRF-fused), HNSW + int8 quantization, agentic RAG (HyDE + sub-question decomposition), GraphRAG-light (Louvain), standalone Obsidian Bases, PDFs + Tesseract OCR. Vendor-neutral memory layer for any MCP-compatible agent. 44 tools, 19 MCP prompts, 926 tests, SLSA-3, semver-bound, MIT, zero cloud calls during serve.",
+  "description": "MCP server giving AI agents (Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, OpenClaw) persistent long-term memory backed by your local Obsidian markdown vault. Hybrid retrieval (BM25 + ML embeddings + BGE reranker, RRF-fused), HNSW + int8 quantization, agentic RAG (HyDE + sub-question decomposition), GraphRAG-light (Louvain), standalone Obsidian Bases, PDFs + Tesseract OCR. Vendor-neutral memory layer for any MCP-compatible agent. 44 tools, 19 MCP prompts, 926 tests, signed npm build provenance (SLSA L2), semver-bound, MIT, zero cloud calls during serve.",
   "type": "module",
   "bin": {
     "enquire-mcp": "dist/index.js"
@@ -160,7 +160,7 @@
     "tesseract",
     "streamable-http",
     "remote-mcp",
-    "slsa-3"
+    "build-provenance"
   ],
   "author": "Alex (@OomkaBear)",
   "license": "MIT",