fix(repair): anchor the FTS5 classifier, attribute integrity verdicts (#2240)

maybe_autoheal_fts5_index rebuilds a corrupt FTS5 index in place when
PRAGMA quick_check's errors look like they came from that index alone. On
develop it has six exits, two of them take that decision silently, and no
verdict anywhere says which SQLite produced it -- or whether one was
produced at all.

Anchor both known phrasings to the start of the quick_check row.
sqlite_integrity_errors reports a failed probe as `PRAGMA quick_check
failed: <error>`, and an unanchored match reads such a row as an isolated
FTS5 fault whenever the wrapped text carries one of the phrasings,
authorizing a write on a database whose state was never established. That
is not a cosmetic misread: on develop, handing such a row to
maybe_autoheal_fts5_index takes the mine lock and changes chroma.sqlite3
on disk. Producing a matching wrapped row needs a table named after a
phrasing, which a chroma palace never has, so this is hardening rather
than a reachable fix. Across 3,200 deliberately damaged databases per
build on 3.45.1, 3.47.1 and 3.51.2, 2,975 dirty on each, the anchored
pattern refused no row the old one accepted and accepted none it refused;
FTS5 faults arrived as whole rows, and the `*** in database <db> ***`
header appeared on b-tree rows only.

Explain a declined heal instead of returning silently, on both quiet
exits and in --dry-run, and name the SQLite that decided. The message
reports what the classifier concluded rather than guessing a cause, since
quick_check may have failed to run at all, reported damage outside the
index, or reported an FTS5 fault in an unrecognized wording. The
--dry-run copy is marked as a preview: without the marker it was
byte-for-byte the run it was predicting, which is the one thing a preview
must not be. The shared text no longer opens with a blank line either,
because the post-mine path passes logger.warning as progress, where a
leading newline renders as a bare WARNING header above an empty line.

Carry sqlite3.sqlite_version wherever a quick_check result is stated: the
abort banner, both --dry-run branches, the heal's outcome line, the
post-recovery check, all three shapes of the MCP integrity payload, the
tool-refusal payload, the integrity log line and MineValidationError's
message. A clean result from a build that cannot detect a given FTS5
fault reads exactly like one from a build that can. The exception message
matters because two callers render it rather than the banner: the MCP
mine tool and the daemon's job runner.

Stop the MCP integrity payload reporting a verdict nobody produced. Above
MEMPALACE_STARTUP_INTEGRITY_MAX_MB, 512 MB by default, the startup probe
does not run, yet the payload answered checked: true, ok: true. It now
returns the not-applicable shape #1931 introduced for the same reason,
carrying the skip as its reason. This matters here specifically: the
palace in #2240 is about four times that limit, so on that install no
quick_check runs at all. The reason is recorded before the rest of the
state, so a reader taking the payload without the refresh lock cannot
catch a half-updated skip and read it as clean. That reason also states
sizes precisely enough to show the comparison it reports: rounded to whole
megabytes, a 1.4 MB database against a 1 MB limit read as "is 1 MB, over
the 1 MB limit". /statusz no longer collapses a missing verdict into a
failure either: false there now means a check came back dirty, which also
stops a non-chroma backend from reporting itself unhealthy.

Report the post-mine validator at warning rather than info. Nothing
configures logging on the mempalace mine path, so its info records were
dropped before reaching a handler there; the MCP server, which configures
logging at info on import, was already showing them.

`fts5: checksum mismatch`, which SQLite 3.51.2 emits, stays unmatched on
purpose. It says the index and the content table disagree without naming
the damaged side, and a rebuild reads from content: edited bytes inside
%_content produce it while the index still holds the original token, and
single-byte damage to an index leaf produces it too, in 75 of the 115
flips that registered at all in a 120-trial run. A rebuild then leaves
quick_check clean whichever side was damaged, on all three builds. A
comment and a test record the counterexample so the pattern is not
widened again.

The subject of #2240 -- one SQLite calling a file clean while another
calls it malformed -- is not addressed here, and the issue stays open.
That asymmetry did not reproduce: 3.45.1, 3.47.1 and 3.51.2 all called the
same 2,975 shapes dirty, differing only in wording, and quick_check agreed
with FTS5's own integrity-check 24 times out of 24 on each build.

Reported by @darkrhodes7, whose suggestion to log the SQLite version
alongside integrity verdicts is implemented here.

Author: mvalentsev

CHANGELOG.md

@@ -8,6 +8,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+### Improvements
+
+- **`repair` says when it declines an in-place FTS5 heal, and names the SQLite that decided.** Declining was a silent `return` on two paths, so the operator saw the ABORT banner with no sign that a rebuild had been considered; `--dry-run` withheld the same explanation. All of them now print it, and the `--dry-run` copy is marked as a preview so it cannot be read as the run it is predicting. `sqlite3.sqlite_version` accompanies every verdict these paths state — the abort banner, both `--dry-run` branches, the heal's outcome line, the post-recovery check, all three shapes of the MCP integrity payload, the tool-refusal payload, the integrity log line and `MineValidationError`'s message — because a clean result from a build that cannot detect a given FTS5 fault reads exactly like one from a build that can. The post-mine validator reports at `warning` rather than `info`, the level that survives on the `mempalace mine` path, which configures no logging. (#2240)
+- **A skipped startup integrity probe is no longer reported as a clean verdict.** Above `MEMPALACE_STARTUP_INTEGRITY_MAX_MB` no `quick_check` runs, yet the MCP payload answered `checked: true, ok: true`. It now returns the not-applicable shape with the skip as its `reason`, and that reason states sizes precisely enough to show the comparison it reports — a 1.4 MB database against a 1 MB limit used to read as "is 1 MB, over the 1 MB limit". Write tools gate on recorded errors rather than on `ok`, so nothing is newly refused, and `/statusz` no longer collapses a missing verdict into a failure — `ok` is false only when a check came back dirty, which also stops a non-chroma backend from reporting itself unhealthy (#1931). (#2240)
+- **The FTS5 classifier is anchored to the start of the `quick_check` row.** `sqlite_integrity_errors` reports a failed probe as `PRAGMA quick_check failed: <error>`, and an unanchored match read such a row as an isolated FTS5 fault — authorizing a rebuild on a database whose state was never established. `fts5: checksum mismatch`, which SQLite 3.51.2 emits, stays unmatched deliberately: it does not name which side is damaged, and a rebuild reads from the content table. (#2240)
+
 ---
 
 ## [3.8.0] — 2026-08-20

mempalace/mcp_server.py

@@ -352,6 +352,9 @@ def _parse_args():
 _sqlite_integrity_checked = False
 _sqlite_integrity_errors: list[str] = []
 _sqlite_integrity_check_error = ""
+# Set when the startup probe was deliberately not run, so the payload can say a
+# verdict is absent rather than report a clean one nobody produced (#2240).
+_sqlite_integrity_skipped_reason = ""
 # Serializes quick_check runs between the async startup preflight thread and
 # lazy consumers on the protocol thread (double-checked in
 # _ensure_sqlite_integrity_status) so the O(database size) probe never runs
@@ -834,6 +837,31 @@ def _startup_integrity_size_limit_bytes() -> int:
     return int(mb * 1024 * 1024)
 
 
+def _rendered_mb(*byte_counts: float) -> tuple[str, ...]:
+    """Render byte counts as MB strings that stay distinguishable from each other.
+
+    Whole megabytes turned a 1.4 MB database against a 1 MB limit into "is 1 MB,
+    over the 1 MB limit", and a sub-megabyte limit into "0 MB, over the 0 MB
+    limit" — a sentence that reads as a contradiction and hides the very
+    comparison it is reporting. The limit is read from the environment as a
+    float, so neither end is guaranteed to be a round number. Widening the
+    precision until the rendered values differ keeps the common case ("1954 MB,
+    over the 512 MB limit") free of noise digits.
+    """
+    values = [count / (1024 * 1024) for count in byte_counts]
+    for digits in range(4):
+        rendered = tuple(f"{value:.{digits}f}" for value in values)
+        # Distinct is not enough on its own: 0.6 MB over a 0.5 MB limit renders
+        # as "1" over "0" at zero digits, which is distinct and wrong in both
+        # numbers. A value that survives rounding to nothing has been rounded
+        # past the point of describing itself.
+        if len(set(rendered)) == len(rendered) and not any(
+            float(text) == 0 and value > 0 for text, value in zip(rendered, values)
+        ):
+            return rendered
+    return tuple(f"{value:.3f}" for value in values)
+
+
 def _refresh_sqlite_integrity_status() -> None:
     """Refresh the MCP startup SQLite/FTS5 integrity gate.
 
@@ -852,11 +880,25 @@ def _refresh_sqlite_integrity_status_locked() -> None:
     global _sqlite_integrity_checked
     global _sqlite_integrity_errors
     global _sqlite_integrity_check_error
-
+    global _sqlite_integrity_skipped_reason
+
+    # Deliberately not cleared up front. _sqlite_integrity_payload reads these
+    # globals without the lock, and _ensure_sqlite_integrity_status short-
+    # circuits on _sqlite_integrity_checked, which a previous skip already set
+    # to True. Clearing here and re-populating after os.path.getsize would open
+    # a window in which a reader sees checked=True, errors=[] and no reason —
+    # the clean verdict nobody produced that this whole path exists to prevent.
+    # Each exit below sets it instead, and the order within an exit is chosen
+    # so every window falls on the safe side. Entering the skip records the
+    # reason before the other three, so a reader cannot catch an empty error
+    # list that nothing explains. Leaving it clears the reason only once the
+    # fresh errors are in place, so the reader catching that half sees a stale
+    # "no verdict" rather than a clean one it was never entitled to.
     if not _config.palace_path or not _is_chroma_backend():
         _sqlite_integrity_checked = True
         _sqlite_integrity_errors = []
         _sqlite_integrity_check_error = ""
+        _sqlite_integrity_skipped_reason = ""
         return
 
     max_bytes = _startup_integrity_size_limit_bytes()
@@ -867,19 +909,29 @@ def _refresh_sqlite_integrity_status_locked() -> None:
         except OSError:
             db_bytes = 0
         if db_bytes > max_bytes:
-            _sqlite_integrity_checked = True
-            _sqlite_integrity_errors = []
-            _sqlite_integrity_check_error = ""
+            # Reason first: it is the field that distinguishes this state from a
+            # clean verdict, so a lock-free reader must never catch the other
+            # three updated while it still says nothing was skipped.
+            db_mb, limit_mb = _rendered_mb(db_bytes, max_bytes)
+            _sqlite_integrity_skipped_reason = (
+                f"startup integrity check skipped: {sqlite_path} is "
+                f"{db_mb} MB, over the {limit_mb} MB limit "
+                f"({_STARTUP_INTEGRITY_MAX_MB_ENV}); no quick_check has run "
+                "against this palace. Run `mempalace repair` for a full check."
+            )
             logger.warning(
-                "SQLite startup integrity check skipped: %s is %.0f MB "
-                "(> %.0f MB limit); PRAGMA quick_check would block MCP "
+                "SQLite startup integrity check skipped: %s is %s MB "
+                "(> %s MB limit); PRAGMA quick_check would block MCP "
                 "startup. Run `mempalace repair` for a full check, or set "
                 "%s (MB; 0 disables the limit).",
                 sqlite_path,
-                db_bytes / (1024 * 1024),
-                max_bytes / (1024 * 1024),
+                db_mb,
+                limit_mb,
                 _STARTUP_INTEGRITY_MAX_MB_ENV,
             )
+            _sqlite_integrity_checked = True
+            _sqlite_integrity_errors = []
+            _sqlite_integrity_check_error = ""
             return
 
     try:
@@ -895,12 +947,16 @@ def _refresh_sqlite_integrity_status_locked() -> None:
         _sqlite_integrity_errors = [str(error) for error in errors if str(error)]
         _sqlite_integrity_check_error = ""
 
+    # A probe ran, so whatever an earlier skip recorded no longer describes
+    # this palace.
+    _sqlite_integrity_skipped_reason = ""
     _sqlite_integrity_checked = True
 
     if _sqlite_integrity_errors:
         logger.error(
-            "SQLite integrity check failed for palace=%s: %s",
+            "SQLite integrity check failed for palace=%s (SQLite %s): %s",
             _config.palace_path,
+            sqlite3.sqlite_version,
             "; ".join(_sqlite_integrity_errors[:3]),
         )
 
@@ -928,6 +984,24 @@ def _sqlite_integrity_payload() -> dict:
     # backend lookup (which may itself fail); only the clean case is
     # reclassified as not-applicable.
     if not _sqlite_integrity_errors:
+        # Same rule, second way to have no verdict: the startup probe is
+        # skipped above a size limit, and the palace in #2240 is roughly four
+        # times the default. Reporting checked/ok true there says a build
+        # examined the database and found it clean when none ever opened it.
+        if _sqlite_integrity_skipped_reason:
+            return {
+                "checked": False,
+                "ok": None,
+                "sqlite_version": sqlite3.sqlite_version,
+                "palace": _config.palace_path or "",
+                "sqlite_path": os.path.join(_config.palace_path, "chroma.sqlite3")
+                if _config.palace_path
+                else "",
+                "error_count": 0,
+                "errors": [],
+                "reason": _sqlite_integrity_skipped_reason,
+            }
+
         try:
             backend_name = _selected_backend_name()
         except Exception:
@@ -937,6 +1011,9 @@ def _sqlite_integrity_payload() -> dict:
             return {
                 "checked": False,
                 "ok": None,
+                # A property of this process, not of the backend, and every
+                # payload shape is deliberately kept parallel on it.
+                "sqlite_version": sqlite3.sqlite_version,
                 "palace": _config.palace_path or "",
                 "sqlite_path": "",
                 "error_count": 0,
@@ -950,6 +1027,10 @@ def _sqlite_integrity_payload() -> dict:
     payload = {
         "checked": _sqlite_integrity_checked,
         "ok": not _sqlite_integrity_errors,
+        # Which SQLite produced this verdict. An "ok" from a build that cannot
+        # detect a given FTS5 fault is not the same claim as an "ok" from one
+        # that can, and the two are otherwise indistinguishable here (#2240).
+        "sqlite_version": sqlite3.sqlite_version,
         "palace": _config.palace_path,
         "sqlite_path": os.path.join(_config.palace_path, "chroma.sqlite3")
         if _config.palace_path
@@ -995,6 +1076,9 @@ def _mcp_sqlite_integrity_refusal(req_id, tool_name: str):
                 ),
                 "errors": _sqlite_integrity_errors[:10],
                 "error_count": len(_sqlite_integrity_errors),
+                # This is the payload an operator is most likely to paste into
+                # a report, so it carries the build behind the verdict too.
+                "sqlite_version": sqlite3.sqlite_version,
                 "hint": (
                     "Stop all MemPalace MCP clients/writers, back up the palace, "
                     "repair the SQLite/FTS5 corruption offline, then run "
@@ -7089,7 +7173,12 @@ def _http_status_payload(httpd) -> dict:
         os.path.abspath(os.path.expanduser(_config.palace_path)) if _config.palace_path else ""
     )
     return {
-        "ok": bool(integrity.get("ok")),
+        # `ok` is None when no integrity verdict exists — a non-chroma backend
+        # (#1931) or a palace above the startup-probe size limit. That is an
+        # absence, not a failure, and collapsing it with bool() reported every
+        # such server as unhealthy. Only a verdict that actually came back
+        # dirty belongs here (#2240).
+        "ok": integrity.get("ok") is not False,
         "server": {
             "name": "mempalace",
             "version": __version__,

mempalace/palace.py

@@ -9,6 +9,7 @@
 import logging
 import os
 import re
+import sqlite3
 import sys
 import threading
 import time
@@ -1107,7 +1108,16 @@ def __init__(self, palace_path: str, errors: list[str]) -> None:
             raise ValueError("MineValidationError requires at least one error string")
         if not palace_path:
             raise ValueError("MineValidationError requires a non-empty palace_path")
-        super().__init__(f"FTS5/SQLite quick_check failed: {len(errors)} issue(s)")
+        # Name the SQLite that produced the verdict. #2240 points at this
+        # post-mine check by name: a build that cannot detect a given FTS5
+        # fault reports the same "clean" as one that can. The CLI handler
+        # renders the abort banner, which carries the version; the MCP `mine`
+        # tool and the daemon's job runner render this message instead, so it
+        # belongs in the message.
+        super().__init__(
+            f"FTS5/SQLite quick_check failed: {len(errors)} issue(s) "
+            f"(SQLite {sqlite3.sqlite_version})"
+        )
         self.palace_path = palace_path
         # Freeze the forensic snapshot so handlers cannot mutate it.
         self.errors: tuple[str, ...] = tuple(errors)
@@ -1144,11 +1154,19 @@ def _validate_palace_fts5_after_mine(palace_path: str) -> None:
 
     errors = sqlite_integrity_errors(palace_path)
     if errors:
-        # progress=logger.info, not the default print: this runs inside the
-        # MCP server process too (mcp_server.tool_mine -> miner.mine), where
-        # stdout is the JSON-RPC transport -- a stray print() here would
-        # corrupt the protocol stream and crash the connection.
-        errors = maybe_autoheal_fts5_index(palace_path, errors, progress=logger.info)
+        # Not the default print: this runs inside the MCP server process too
+        # (mcp_server.tool_mine -> miner.mine), where stdout is the JSON-RPC
+        # transport -- a stray print() here would corrupt the protocol stream
+        # and crash the connection.
+        #
+        # warning, not info: this module logs through the `mempalace_mcp`
+        # logger, which sets no level of its own, and nothing configures logging
+        # on the `mempalace mine` path -- so root keeps its default and info
+        # records are dropped. Every message this call can emit describes a palace whose
+        # quick_check already failed -- a rebuild being attempted, refused, or
+        # completed against the operator's data -- so warning is both the level
+        # that survives and the level that fits.
+        errors = maybe_autoheal_fts5_index(palace_path, errors, progress=logger.warning)
     if errors:
         raise MineValidationError(palace_path, errors)