scry_db_health
Check SQLite database health for corruption vs write-lock contention. Returns status (ok/corrupt/locked), integrity check result, doc count, and error info to guide auto-restore decisions.
Instructions
Probe the scry project database and report health.
Designed for substrate code (e.g. reflection's wake.py auto-restore
loop) that needs to distinguish actual corruption from transient WAL
write-lock contention. The same scry-mcp connection primitives are
used as for every other tool — long busy_timeout, WAL journal mode,
retry semantics — so a healthy-but-busy DB will not be reported as
corrupt.
Returns JSON with these fields:
status "ok" | "corrupt" | "locked"
integrity result of PRAGMA integrity_check (string), or null
when the probe could not run (e.g. status=locked)
doc_count integer row count of scry__doc, or null when the
table does not exist yet (fresh / unmigrated DB)
doc_count_error populated when doc_count is null and the count
query failed for a known-benign reason (table
missing); null otherwise
db_path absolute path to the project.db file probed
error string explanation when status != "ok"; null otherwise
Status semantics for substrate decisions:
status="ok" DB is healthy. Do not quarantine.
status="locked" DB is healthy but contended. Do NOT quarantine;
retry the probe on the next wake. Substrate code
that conflates this with corruption causes the
Group-C cascade described in the May 2026
diagnostic.
status="corrupt" DB failed PRAGMA integrity_check or could not
be opened as a SQLite database at all. Safe to
initiate auto-restore.
A status="ok" with doc_count=null and doc_count_error="no such
table: scry__doc" is a fresh-and-unmigrated DB. Substrate should
run migrations (or call scry_surface) rather than quarantine.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |