Normalize maintenance database error handling

DEVELOPER_GUIDE.md

@@ -875,6 +875,7 @@ Current stable codes and triggers:
 | Writable open pragmas | `DbContext` opens writable indexes in WAL mode, applies connection performance pragmas through `DbPragmaPolicy`, sets `PRAGMA auto_vacuum=INCREMENTAL` before schema creation for new empty databases, sets `PRAGMA application_id=0x43444958` (`CDIX`), sets `PRAGMA synchronous=NORMAL`, and pins `PRAGMA wal_autocheckpoint=1000`. |
 | Open intent | Every `DbContext` caller declares `QueryOnly`, `WriteIndex`, `Migration`, or `Repair`. `QueryOnly` uses unpooled connections and skips persistent pragmas, migrations, metadata writes, and repair work. WAL databases are read from private temporary snapshots: checkpointed databases copy the main file and open that copy through an immutable read-only URI, while non-empty WAL databases copy the stable main/WAL pair so committed WAL content remains visible. Before and after copying, database-header and WAL-generation fingerprints must match; otherwise the bounded copy retries and ultimately refuses the open instead of returning stale data or modifying source `-wal` / `-shm`. Attached cross-database snapshots are cleaned up only after the attaching connection closes. Missing source/WAL files may retry as generation churn, while persistent copy I/O failures report `query_only_snapshot_copy_failed` with temporary-storage remediation. Long-lived MCP and LSP sessions refresh a detached snapshot when its source generation changes. `RepairIncompleteBatchReadiness` is guarded by `Repair` intent. |
 | Application id | The application id lets file-type detection tools distinguish cdidx databases from generic SQLite databases. |
+| Maintenance error contract | `vacuum`, `backfill-fold`, `optimize` / `index --optimize`, and `db integrity` route failures through `MaintenanceDatabaseErrorClassifier` version `1` and one JSON/human writer. SQLite primary codes `5`/`6`, `8`, `11`, and `26` classify locked/busy, not-writable, corrupt, and not-a-database failures without inspecting exception wording. The shared response carries a stable error code/category, conditional recovery hint, redacted path metadata, and optional primary/extended SQLite codes. Absolute paths are redacted by default; `--show-paths` is the explicit diagnostic opt-in. |
 | Durable WAL file set | When WAL is active, the durable SQLite index is the `.db` file plus sibling `.db-wal` and `.db-shm` files. Backups, diagnostics bundles, and manual copies must include all three files when the siblings exist, or use SQLite's `.backup` command/API from a live connection. Copying only `codeindex.db` can produce a stale snapshot because committed pages may still live in `codeindex.db-wal`. |
 | `synchronous=NORMAL` | Under WAL, `NORMAL` avoids per-commit fsync pressure during 500-row indexing batches while preserving database consistency after crashes. |
 | Checkpointing | `DbWriter` runs `PRAGMA wal_checkpoint(PASSIVE)` after each outer transaction commit, and SQLite may also checkpoint automatically after the configured 1000-page threshold. Both checkpoint paths are opportunistic: active readers are not blocked, and an uncheckpointed WAL is expected state rather than corruption. |
@@ -4124,6 +4125,7 @@ apply 時は `PRAGMA optimize` を実行します。
 | writable open pragma | `DbContext` は writable な index を WAL mode で開き、connection performance pragma を `DbPragmaPolicy` 経由で適用し、新規の空 DB では schema 作成前に `PRAGMA auto_vacuum=INCREMENTAL` を設定し、`PRAGMA application_id=0x43444958` (`CDIX`)、`PRAGMA synchronous=NORMAL`、`PRAGMA wal_autocheckpoint=1000` を固定します。 |
 | open intent | すべての `DbContext` caller は `QueryOnly`、`WriteIndex`、`Migration`、`Repair` のいずれかを宣言します。`QueryOnly` は unpooled connection を使い、永続的な pragma、migration、metadata write、repair を skip します。WAL database は private temporary snapshot から読みます。checkpoint 済み database は main file を copy してその copy を immutable read-only URI で開き、non-empty WAL database は安定した main/WAL pair を copy して committed WAL content を維持します。copy 前後の database header / WAL generation fingerprint が一致しなければ bounded copy を retry し、最終的には stale data を返したり source `-wal` / `-shm` を変更したりせず open を拒否します。cross-database で attach した snapshot は、attach 元 connection を閉じた後に cleanup します。source/WAL file の消失は generation churn として retry できますが、永続的な copy I/O failure は temporary storage の remediation を含む `query_only_snapshot_copy_failed` を返します。長時間動作する MCP / LSP session は source generation が変わると detached snapshot を refresh します。`RepairIncompleteBatchReadiness` は `Repair` intent の場合に限り実行できます。 |
 | application id | application id は file-type detection tool が cdidx database と generic SQLite database を区別するための印です。 |
+| maintenance error contract | `vacuum`、`backfill-fold`、`optimize` / `index --optimize`、`db integrity` の失敗は `MaintenanceDatabaseErrorClassifier` version `1` と単一の JSON / human writer を通ります。SQLite primary code `5` / `6`、`8`、`11`、`26` から locked / busy、not-writable、corrupt、not-a-database を分類し、例外 message は判定に使いません。共有 response は stable error code / category、条件別 recovery hint、redaction 済み path metadata、任意の primary / extended SQLite code を返します。absolute path は既定で redaction し、`--show-paths` を明示的な diagnostic opt-in とします。 |
 | durable WAL file set | WAL が有効な場合、永続化された SQLite index は `.db` file と sibling の `.db-wal` / `.db-shm` file の組です。backup、diagnostics bundle、手動 copy では sibling が存在する場合に 3 file すべてを含めるか、live connection から SQLite の `.backup` command/API を使う必要があります。`codeindex.db` だけを copy すると、committed page がまだ `codeindex.db-wal` に残っているため stale snapshot になる可能性があります。 |
 | `synchronous=NORMAL` | WAL では `NORMAL` により 500 row 単位の indexing batch ごとの fsync 負荷を避けつつ、crash 後の database consistency を保ちます。 |
 | checkpoint | `DbWriter` は outer transaction commit 後に `PRAGMA wal_checkpoint(PASSIVE)` を実行し、SQLite も設定済みの 1000 page threshold を超えると自動 checkpoint する場合があります。どちらの checkpoint path も opportunistic で、active reader は block されず、未 checkpoint の WAL は corruption ではなく期待される状態です。 |

TESTING_GUIDE.md

@@ -350,6 +350,8 @@ Use `docs/test-doc-maintenance-plan.md` before moving oversized suites or adding
 - `IndexCommandRunnerTests.RunOptimizeFts_DryRunPreviewsWithoutWritingThenOptimizeMutates_Issue4577`, `RunOptimizeFts_LockHeld_ReportsDbLocked`, and `RunOptimizeFts_ReadOnlyUri_ReturnsDbNotWritable`
   share seeded databases to verify that optimize dry-run reports sizes, readiness, lock state, recommendations, and planned work while preserving the source bytes and creating no lock artifacts; the same fixtures retain the writable optimize and lock/read-only URI mutation guards.
   `ConsoleUiTests.PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags` keeps the optimize dry-run flag visible in full CLI usage.
+- Issue #4856 maintenance-error coverage spans `CommandErrorWriterTests`, `QueryCommandRunnerTests`, `IndexCommandRunnerTests`, and `DbCommandRunnerTests`.
+  Keep the SQLite primary-code matrix (`5`, `6`, `8`, `11`, `26`), caller-spelled relative paths, whole-value Unix/Windows/file-URI redaction, missing and invalid-header files, directory/inaccessible preflight classification, integrity corruption rows, lock-holder metadata, the `index --optimize` human preamble, valid JSON, and category-specific recovery hints aligned with classifier version `1`.
 - `IndexCommandRunnerTests.Run_DryRunWithRebuildAndMemoryTrace_SkipsConfirmationAndPreservesWorkspace_Issue4580`
   runs a rebuild preview as redirected input without `--yes`, verifies live memory phases and samples, and byte-compares the complete project file set before and after so source, DB, WAL, SHM, and other workspace artifacts cannot be changed silently.
 - `IndexCommandRunnerTests.Run_MemoryTrace_ReportsFullScanAndUpdatePhaseBoundaries`
@@ -1258,6 +1260,8 @@ dotnet test --filter "FullyQualifiedName~GitHelperTests"
 - `IndexCommandRunnerTests.RunOptimizeFts_DryRunPreviewsWithoutWritingThenOptimizeMutates_Issue4577`、`RunOptimizeFts_LockHeld_ReportsDbLocked`、`RunOptimizeFts_ReadOnlyUri_ReturnsDbNotWritable`
   seed 済み database を共有し、optimize dry-run が size、readiness、lock state、推奨、planned work を報告しつつ source byte を保持し、lock artifact を作成しないことを検証する。同じ fixture で、書き込み版 optimize と lock/read-only URI の mutation guard も維持する。
   `ConsoleUiTests.PrintUsage_WithoutBanner_HidesAsciiArtAndEasterEggFlags` は、full CLI usage に optimize dry-run flag が表示され続けることを固定します。
+- Issue #4856 の maintenance-error coverage は `CommandErrorWriterTests`、`QueryCommandRunnerTests`、`IndexCommandRunnerTests`、`DbCommandRunnerTests` にまたがります。
+  SQLite primary-code matrix (`5`、`6`、`8`、`11`、`26`)、呼び出し側表記を維持する relative path、Unix / Windows / file URI の値全体 redaction、missing / invalid-header file、directory / inaccessible preflight classification、integrity corruption row、lock-holder metadata、`index --optimize` の human preamble、有効な JSON、category 別 recovery hint を classifier version `1` と同期させてください。
 - `IndexCommandRunnerTests.Run_DryRunWithRebuildAndMemoryTrace_SkipsConfirmationAndPreservesWorkspace_Issue4580`
   redirect input で `--yes` なしの rebuild preview を実行し、live memory phase/sample を検証します。実行前後の project file set 全体を byte 比較し、source、DB、WAL、SHM、その他 workspace artifact が暗黙に変更されないことも固定します。
 - `IndexCommandRunnerTests.Run_MemoryTrace_ReportsFullScanAndUpdatePhaseBoundaries`