Fix/FTS5 preflight coverage, store protection, and a discoverable telemetry opt-out

[Yashasvi2229]

What

Finishes the four-part report in #110. PR #168 fixed the first part — mex graph now names the problem when Node's bundled SQLite lacks FTS5 — and this picks up what it scoped out, plus a gap that fix left behind.

• FTS5 preflight now covers every consumer. fix(graph): fail with an actionable message when Node's SQLite lacks FTS5 #168 guarded only the writable graph open. Readers query nodes_fts / source_chunks_fts, and the wiki index has the same dependency via wiki_fts, so mex check, graph scope/query/get, impact and every mex wiki command could still hit SQLite's raw no such module: fts5. The probe moved from graph/db/database.ts to graph/db/sqlite.ts — it describes the SQLite build, not the code graph, and the wiki architecture rule lets the wiki reach that module but not database.ts. database.ts re-exports it, so existing callers are unchanged.
• .mex/.gitignore is written by store writers, not only by setup. mex graph rebuild/refresh/repair and mex wiki rebuild-index now ensure it exists before creating anything.
• mex telemetry disable / enable, writing the same ~/.mex/config.json key as mex config set telemetry on|off. The env opt-outs are named in telemetry --help and in status.
• COMPATIBILITY.md documents the FTS5 requirement, which the preflight's error message already pointed at.

engines stays >=22.5 — see Why.

Why

Closes #110.

Each remaining item was a way for a correct tool to look broken:

• Coverage. A store built on one Node and read on another fails on read, not on build. Switching versions with a version manager is enough — no copying between machines required. mex wiki rebuild-index run on its own reproduced the original confusing failure verbatim.
• Untracked databases. Setup writes the ignore rules at step 2, long before it builds anything, but a store writer invoked on its own never passed through setup. The reporter ran mex graph in a checkout that had never run setup, and their next git add -A would have committed a broken database plus its WAL and SHM files.
• The opt-out. Turning telemetry off was always one command, but the only switch lived under mex config. The reporter typed mex telemetry disable, got unknown command, read telemetry --help, found two commands that only show things, and then guessed at env var names that didn't exist. They said they audited TELEMETRY.md against src/telemetry/index.ts line by line before running anything, because their work touches medical data — that is exactly the user for whom "where is the off switch" must be a ten-second answer.
• The dangling pointer. fix(graph): fail with an actionable message when Node's SQLite lacks FTS5 #168's message told users to "see COMPATIBILITY.md for which versions are known to work". That document said nothing about FTS5; it repeated the same >=22.5 range that had just failed them.

On not narrowing engines: FTS5 is a compile-time option that Node neither documents nor guarantees, so availability is a property of the build, not the version number — official installers, distro packages and self-compiled Node can differ at the same version. Setting a floor from one field report would lock out working 22.x/23.x installs while still admitting a broken build above the floor. COMPATIBILITY.md instead carries a one-line command to test the Node you actually run, and the two known data points as reports rather than a supported-range claim. More data points would justify a floor; one does not.

Type of change

• Bug fix
• New feature
• Refactor
• Docs
• CI/Tooling

How to test

FTS5 preflight (behaviour is unchanged on any Node that has FTS5, which is the common case):

1. node --no-warnings -e "new (require('node:sqlite').DatabaseSync)(':memory:').exec('CREATE VIRTUAL TABLE t USING fts5(x)')" && echo "FTS5 ok" — the check now documented in COMPATIBILITY.md.
2. npx vitest run src/graph/__tests__/database-fts5.test.ts src/wiki/index/__tests__/fts5.test.ts — the probe's failure paths are driven through an injected opener, so they are reachable without an FTS5-less Node. Covers the write path, both graph read paths, and a real, intact wiki index that this engine cannot read.

Store protection, in a scratch repo with no .mex/:

3. git init, add one .ts file, then run mex graph.
4. git add -A && git status — .mex/.gitignore and your source are staged; graph.db and its sidecars are not. On main, all three databases stage.
5. npx vitest run test/store-ignore-protection.test.ts

Telemetry:

6. mex telemetry --help — lists disable, DO_NOT_TRACK=1 and MEX_TELEMETRY=0.
7. mex telemetry disable, then mex telemetry status — the reason is named and explained. DO_NOT_TRACK=1 mex telemetry enable reports that the env var still outranks what was just written.
8. npx vitest run test/telemetry-optout-cli.test.ts

Checklist

• Tests pass (npm test)
• No breaking changes (or documented below)
• Tested locally with a real project

On "tests pass": measured as branch-vs-main, not as a green board. The full suite was run on this branch and again in a worktree at main, and the failure sets diffed by name: 69 failures here, 71 on main, with one test failing only here and two only on main. All three pass in isolation — that is parallelism flake, not a regression. The ~70 baseline failures are pre-existing on this Windows machine (the documented findConfig trap: TEMP sits under a home directory that is itself a git repo, so tests asserting branch: null see branch: "main"). npm test also does not run the evaluator tests. CI is the arbiter.

Not breaking, and why each near-miss isn't:

• assertFts5Available moved from graph/db/database.ts to graph/db/sqlite.ts and is re-exported from its old home, so any existing import keeps working. It gained an optional injected-opener parameter; the default is the previous behaviour.
• WIKI_INDEX_FTS5_UNAVAILABLE is a new wiki diagnostic code — additive, and registered with the coverage test's emitter. The frozen WikiContractReadError vocabulary is untouched: the read session reuses INDEX_UNAVAILABLE, which already means "this index cannot be read right now".
• Graph reads on an FTS5-less Node now fail at open with a clear message instead of at the first query with a raw SQLite error. Both are failures; only one is legible.

Tested locally with a real project: two private repositories (111 and 64 indexed source files), with the store redirected to a temp path so neither repository's own .mex/ was opened or written. Both produced node counts identical to their existing live stores (1337 and 1163), and read-only and immutable opens both succeeded with FTS queries returning hits. For the wiki, one real scaffold was copied to scratch (markdown only): rebuild-index indexed 31 entities from 19 files, and wiki query — the FTS5 read path guarded here — returned correct results. Temporary stores deleted after measuring.

Code-graph changes

This touches graph infrastructure (db/sqlite.ts, db/database.ts, maintenance.ts) but adds no extractor, resolver, grammar or schema change, so the extractor-specific items below are marked N/A rather than ticked.

• This PR targets main
• A linked issue agrees on the bounded extractor/resolver scope — graph: 'no such module: fts5' on Node 23.10.0 (inside documented engines range) #110
• The change follows the frozen LanguageExtractor or FrameworkResolver interface — N/A, no extractor or resolver added
• A focused fixture and assertions for the expected node/edge shape are included — N/A, no extraction behaviour changed; node and edge output is byte-identical, verified against two real corpora
• Any new grammar WASM, extension mapping, extractor, or resolver is registered — N/A, none added
• No graph identity, reconciliation, schema, or drift-semantics changes are included