@oomkapwn/enquire-mcp 3.8.0-rc.4 → 3.8.0-rc.5

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 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.8.0-rc.5] — 2026-05-21
+
+> **TL;DR:** Fifth v3.8.0 release candidate. Adds **K-3 readOnlyHint structural invariant** — pins the tool-registry's `READ_ONLY` ↔ read-handler / `WRITE` ↔ write-handler mapping so the annotations can't drift away from the wired handlers. Catches the class of bug an MCP client's `readOnlyHint`-driven confirmation gate would silently swallow. Ships under `@rc` dist-tag.
+
+**Minor — fifth v3.8.0 release candidate.**
+
+### K-3 — readOnlyHint structural invariant
+
+**Background.** MCP tool annotations advertise to the client and the agent orchestrator what each tool can do. Specifically:
+- `readOnlyHint: true` → MCP clients that gate destructive operations behind user confirmation will SKIP that gate for this tool.
+- `destructiveHint: true` → MCP clients show a "destructive" badge and may ask for explicit confirmation per call.
+
+If a tool annotated `readOnlyHint: true` is silently wired to a write handler (e.g. `createNote`, `appendToNote`, `renameNote`, `replaceInNotes`, `archiveNote`, `chatThreadAppend`, `frontmatterSet`), the client won't confirm, and the agent can mutate the vault without the user knowing.
+
+`src/tool-registry.ts` already follows the convention (two shorthand annotation objects — `READ_ONLY` + `WRITE` — at lines 57, 138, 1028 — plus 7 known write-handler names). But there was no automated check that the convention is maintained. K-3 pins it.
+
+### What's enforced
+
+1. **Every `READ_ONLY`-annotated tool's handler block does NOT reference any function in `KNOWN_WRITE_HANDLERS`.**
+2. **Every `WRITE`-annotated tool's handler block references at least one function from `KNOWN_WRITE_HANDLERS`.**
+3. **Every tool in `tool-registry.ts` has an explicit `READ_ONLY` or `WRITE` annotation** (no UNKNOWN).
+
+`KNOWN_WRITE_HANDLERS` is a set of 7 names: `createNote`, `appendToNote`, `renameNote`, `replaceInNotes`, `archiveNote`, `chatThreadAppend`, `frontmatterSet`. If a future PR adds a new write operation, it MUST register its handler name in this set, OR the K-3 invariant test will reject it as UNKNOWN/violation.
+
+### Implementation
+
+- **`tests/k3-readonly-hint-invariant.test.ts`** — 3 production tests + 3 negative-control fixture tests = 6 new tests.
+- **`scanRegistry(source)`** — exposed as a pure function so fixture-based negative controls can exercise the scanner directly (per CLAUDE.md anti-pattern "Invariant test without negative-control — Rule since v3.6.4").
+- **Block boundary fix** — the scanner bounds each `registerTool(...)` block by the NEXT `registerTool(` call (or end of file), not a fixed line window. Caught during initial test: a fixed 60-line window allowed the last READ_ONLY tool's window to extend into `registerWriteTools()` and grab the first WRITE tool's `createNote(` call. The block-bounding fix was found via the test failing on initial run — exactly the kind of class-of-bug discovery the invariant is designed for.
+
+### Fixture coverage (negative-control)
+
+3 fixture files under `tests/fixtures/k3-invariant/`:
+- **`good.fixture.ts`** — positive control: canonical READ_ONLY + WRITE patterns, both correctly wired.
+- **`bad-readonly-with-write.fixture.ts`** — READ_ONLY tool wired to `createNote` (the exact bug shape K-3 catches).
+- **`bad-write-no-handler.fixture.ts`** — WRITE tool wired to `readNote` (inverse drift).
+
+Each fixture is parseable by `scanRegistry` independently, so the negative-control sibling tests prove the scanner classifies each case correctly without requiring production code violations.
+
+### Stats
+
+- **838 tests** (+6 from K-3). Was 832 in v3.8.0-rc.4.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All required CI gates pass locally.
+
+### v3.8.0 remaining backlog (next RCs)
+
+- **R-10** — HNSW + privacy under-return fix (over-fetch margin tuning).
+- **T-1..T-5** — test coverage gaps (`contextPack`, `get_communities` handler E2E, `hyde_search` E2E, `serve-http` cli.test E2E).
+- **4/5 reranker E2E in CI** with model-cache strategy.
+- **OCR'd PDF watcher embed-sync** (deferred from rc.3).
+- **HNSW in-memory update** alongside watcher upserts (architectural).
+- **watcher.ts catch-branch coverage via vi.mock or DI** — lift floor back to ≥71%.
+- **External audit on rc.N** before promotion to stable.
+
 ## [3.8.0-rc.4] — 2026-05-21
 
 > **TL;DR:** Fourth v3.8.0 release candidate. Closes the rc.3 architectural deferral: extracts `embedSingleNote` (rc.2) + `embedSinglePdf` (rc.3) from `src/server.ts` into a dedicated `src/embed-pipeline.ts` module. The motivation was the `tests/no-internal-imports.test.ts` Class A invariant — server.ts is in `RESTRICTED_MODULES`, so the helpers couldn't be unit-tested directly. Now they can: 10 new direct unit tests in `tests/embed-pipeline.test.ts` cover happy paths, null returns, embedder error propagation, frontmatter title resolution, late-chunk-context honoring, and the data-integrity guard against mismatched vector counts. Ships under `@rc` dist-tag.

package/README.md

@@ -11,7 +11,7 @@
 [![CI](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@oomkapwn/enquire-mcp.svg?label=npm&color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)
 [![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-832%20passing-brightgreen.svg)](#trust)
+[![tests](https://img.shields.io/badge/tests-838%20passing-brightgreen.svg)](#trust)
 [![stable](https://img.shields.io/badge/v3.7.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)
 [![MCP](https://img.shields.io/badge/MCP-1.29-8A2BE2.svg)](https://modelcontextprotocol.io/)
@@ -36,7 +36,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 · 832 unit tests · 50+ languages · v3.7.x stable · semver-bound · MIT · SLSA-3 signed.**
+**44 tools · 19 MCP prompts · 838 unit tests · 50+ languages · v3.7.x stable · semver-bound · MIT · SLSA-3 signed.**
 
 ---
 
@@ -112,7 +112,7 @@ Auto-generated **[API reference at oomkapwn.github.io/enquire-mcp](https://oomka
 | **GraphRAG-light** (wikilink community detection via Louvain modularity) | ✅ **only here** | ❌ | ❌ |
 | **Standalone `.base` query execution** (works without Obsidian running) | ✅ **only here** | ❌ | ❌ delegates to Obsidian |
 | **HyDE retrieval** (Gao et al 2023) + sub-question decomposition | ✅ **only here** | ❌ | ❌ |
-| **832 unit tests · 8 required + 4 advisory CI gates per PR** | ✅ | n/a | rare |
+| **838 unit tests · 8 required + 4 advisory CI gates per PR** | ✅ | n/a | rare |
 | **SLSA-3 build provenance** | ✅ | n/a | ❌ |
 | **Semver-bound public surface** ([STABILITY.md](./STABILITY.md)) | ✅ | n/a | ❌ |
 | Standalone (no Obsidian plugin needed) | ✅ | ❌ requires Obsidian | varies |
@@ -222,7 +222,7 @@ Channel: `npm install @oomkapwn/enquire-mcp` → latest stable. Full changelog:
 ```bash
 git clone https://github.com/oomkapwn/enquire-mcp.git
 cd enquire-mcp && npm install
-npm test       # full suite (832 tests, ~5s)
+npm test       # full suite (838 tests, ~5s)
 npm run lint   # zero warnings
 npm run build  # tsc → dist/
 ```

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.8.0-rc.4";
+export declare const VERSION = "3.8.0-rc.5";
 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.8.0-rc.4";
+export const VERSION = "3.8.0-rc.5";
 // 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

@@ -43,7 +43,7 @@ The four axes the external audit (#3, 2026-05) called out as decisive — **REST
 | 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               |
-| Test count (public)                           | **832**             | (varies)         | (varies)         | (varies)         | (varies)         |
+| Test count (public)                           | **838**             | (varies)         | (varies)         | (varies)         | (varies)         |
 | Tool count                                    | 44                  | ~25              | ~8               | ~10              | 3–5              |
 | MCP prompt count                              | 19                  | 0                | 0                | 0                | 0                |
 | License                                       | MIT                 | Apache-2.0       | MIT              | MIT              | (varies)         |

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oomkapwn/enquire-mcp",
-  "version": "3.8.0-rc.4",
-  "description": "The most advanced Obsidian MCP — long-term memory for AI agents. Hybrid retrieval (BM25 + TF-IDF + multilingual ML embeddings, RRF-fused) with BGE cross-encoder reranking, HNSW + int8 quantization, late-chunking, HyDE + sub-question decomposition, agentic RAG, PDFs (with OCR), standalone Bases (.base query execution — no Obsidian needed), GraphRAG-light (Louvain wikilink community detection), wikilinks, backlinks, Dataview, frontmatter, canvas. Open-source long-term memory / second brain for Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, OpenClaw, and any MCP client. 44 tools, 19 MCP prompts, BGE cross-encoder reranker verified end-to-end (+4 aliases in catalog, transformers.js bump pending), 832 tests, SLSA-3, semver-bound, MIT.",
+  "version": "3.8.0-rc.5",
+  "description": "The most advanced Obsidian MCP — long-term memory for AI agents. Hybrid retrieval (BM25 + TF-IDF + multilingual ML embeddings, RRF-fused) with BGE cross-encoder reranking, HNSW + int8 quantization, late-chunking, HyDE + sub-question decomposition, agentic RAG, PDFs (with OCR), standalone Bases (.base query execution — no Obsidian needed), GraphRAG-light (Louvain wikilink community detection), wikilinks, backlinks, Dataview, frontmatter, canvas. Open-source long-term memory / second brain for Claude Code, Claude Desktop, Cursor, ChatGPT custom GPT, Codex, OpenClaw, and any MCP client. 44 tools, 19 MCP prompts, BGE cross-encoder reranker verified end-to-end (+4 aliases in catalog, transformers.js bump pending), 838 tests, SLSA-3, semver-bound, MIT.",
   "type": "module",
   "bin": {
     "enquire-mcp": "dist/index.js"