Add structured export/import archive validation

DEVELOPER_GUIDE.md

@@ -46,7 +46,7 @@ Development contracts:
 |---|---|---|
 | Read-only database queries | `cdidx status --db /artifacts/codeindex.db --read-only --json`; `cdidx search AuthService --db /artifacts/codeindex.db --immutable` | Query commands accept `--read-only` (alias `--immutable`) to open an existing CodeIndex database through SQLite's immutable read-only URI mode. Use this for CI artifacts, mounted caches, and sandboxes where creating or updating `codeindex.db-wal` / `codeindex.db-shm` sidecars is not allowed. |
 | Mutating commands | `index`, `backfill-fold`, `optimize`, `vacuum` | These require writable storage and reject read-only database opens. |
-| Reusable index artifact | `cdidx export codeindex.cdidx.zip`; `cdidx import codeindex.cdidx.zip --db <path>` | Run export after indexing and upload the archive. Consumers import before query commands. Use `--prune-paths` when the archive comes from another checkout and the restored DB should advertise the current workspace root. The archive contains `manifest.json` plus `codeindex.db`; import validates manifest format, manifest `user_version`, `database_sha256`, and the embedded SQLite file as a CodeIndex database before replacing the destination DB. Import rejects archive `codeindex.db` entries whose compressed or uncompressed metadata exceeds 8 GiB, and the extraction stream is also capped at 8 GiB. |
+| Reusable index artifact | `cdidx export codeindex.cdidx.zip`; `cdidx import codeindex.cdidx.zip --db <path>`; `cdidx import codeindex.cdidx.zip --dry-run --json` | Run export after indexing and upload the archive. Consumers import before query commands, or use `--dry-run` / `--check` to validate the archive without replacing the destination DB. Use `--prune-paths` when the archive comes from another checkout and the restored DB should advertise the current workspace root. The archive contains `manifest.json` plus `codeindex.db`; the manifest carries bounded summary/readiness metadata including row counts, readiness bits, writer/indexed-head metadata, schema contract stamps, and unknown-extension summary when available. Import validates manifest format, manifest `user_version`, `database_sha256`, present summary counts, and the embedded SQLite file as a CodeIndex database before replacing the destination DB. Import rejects archive `codeindex.db` entries whose compressed or uncompressed metadata exceeds 8 GiB, and the extraction stream is also capped at 8 GiB. |
 | Maintenance checkpoint | `cdidx db checkpoint <name>`; `cdidx db restore <name>` | Checkpoint snapshots `codeindex.db` plus existing WAL/SHM sidecars before risky maintenance. Restore rolls back and keeps pre-restore files under `<db>.restore-backup-<timestamp>/`. Checkpoints live next to the DB under `<db>.checkpoints/<name>/`. `backfill-fold` creates an automatic checkpoint before it mutates rows unless `--no-checkpoint` is passed. |
 | Binary compatibility | [COMPATIBILITY.md](COMPATIBILITY.md) | Database compatibility across `cdidx` binary upgrades and downgrades is documented there. Keep that policy updated whenever readiness bits, `codeindex_meta` contract stamps, or rebuild requirements change. |
 | Fold backfill preview and recovery | `backfill-fold --dry-run`; MCP `backfill_fold` with `dry_run: true` or `force: true` | Dry-run previews folded-key rows without mutating the DB or stamping FoldReady. MCP accepts the same preview and can force rewriting all folded keys when an operator needs to recover from suspicious fold metadata or row state even though the stored version/fingerprint appears current. Non-dry-run row rewrites are resumable after interruption: completed row updates remain durable, and final FoldReady metadata is stamped only after verification succeeds. MCP responses include `progress.rows_done`, `progress.rows_total`, and `progress.fraction` so clients can report and retry long backfills. |
@@ -2154,7 +2154,7 @@ net9 CI lane に合わせる場合は `FRAMEWORK=net9.0 make test` を使いま
 |---|---|---|
 | read-only database query | `cdidx status --db /artifacts/codeindex.db --read-only --json`; `cdidx search AuthService --db /artifacts/codeindex.db --immutable` | query コマンドは `--read-only`（alias: `--immutable`）を受け付け、既存の CodeIndex database を SQLite の immutable read-only URI mode で開けます。CI artifact、mounted cache、`codeindex.db-wal` / `codeindex.db-shm` sidecar を作成・更新できない sandbox で使います。 |
 | 変更系コマンド | `index`、`backfill-fold`、`optimize`、`vacuum` | 書き込み可能な storage を必要とし、read-only database open を拒否します。 |
-| 再利用可能な index artifact | `cdidx export codeindex.cdidx.zip`; `cdidx import codeindex.cdidx.zip --db <path>` | CI job では index 後に export して archive を upload します。利用側は query コマンドの前に import できます。別 checkout 由来の archive を現在の workspace root として扱いたい場合は `--prune-paths` を使います。archive は `manifest.json` と `codeindex.db` を含み、import は manifest format、manifest `user_version`、`database_sha256`、embedded SQLite file が CodeIndex database であることを検証してから destination DB を置き換えます。archive の `codeindex.db` entry は compressed / uncompressed metadata と extraction stream の双方で 8 GiB を上限に拒否されます。 |
+| 再利用可能な index artifact | `cdidx export codeindex.cdidx.zip`; `cdidx import codeindex.cdidx.zip --db <path>`; `cdidx import codeindex.cdidx.zip --dry-run --json` | CI job では index 後に export して archive を upload します。利用側は query コマンドの前に import でき、`--dry-run` / `--check` で destination DB を置き換えず archive を検証できます。別 checkout 由来の archive を現在の workspace root として扱いたい場合は `--prune-paths` を使います。archive は `manifest.json` と `codeindex.db` を含み、manifest は row count、readiness bit、writer / indexed-head metadata、schema contract stamp、利用可能な unknown-extension summary などの bounded summary/readiness metadata を持ちます。import は manifest format、manifest `user_version`、`database_sha256`、存在する summary count、embedded SQLite file が CodeIndex database であることを検証してから destination DB を置き換えます。archive の `codeindex.db` entry は compressed / uncompressed metadata と extraction stream の双方で 8 GiB を上限に拒否されます。 |
 | maintenance checkpoint | `cdidx db checkpoint <name>`; `cdidx db restore <name>` | 危険な maintenance の前に `codeindex.db` と既存 WAL/SHM sidecar の filesystem snapshot を作成し、restore で戻します。checkpoint は DB の隣の `<db>.checkpoints/<name>/` に置かれ、restore は pre-restore file を `<db>.restore-backup-<timestamp>/` に保持します。`backfill-fold` は `--no-checkpoint` を渡さない限り、row mutation 前に automatic checkpoint を作ります。 |
 | binary compatibility | [COMPATIBILITY.md](COMPATIBILITY.md) | `cdidx` binary の upgrade / downgrade をまたぐ database compatibility を記載します。readiness bit、`codeindex_meta` contract stamp、rebuild requirement を変える場合は、この policy も更新してください。 |
 | Fold backfill の preview / recovery | `backfill-fold --dry-run`; MCP `backfill_fold` の `dry_run: true` または `force: true` | dry-run は DB を変更せず FoldReady stamp も書かずに、rewrite 対象の folded-key row をプレビューします。MCP も同じ preview を受け付け、stored version / fingerprint が current に見える場合でも suspicious な fold metadata や row state を復旧するため `force: true` を受け付けます。non-dry-run rewrite は中断後に resume でき、完了済み row update は durable に残り、最終 FoldReady metadata は verification 成功後にだけ stamp されます。MCP response は `progress.rows_done`、`progress.rows_total`、`progress.fraction` を含みます。 |

changelog.d/unreleased/3548.fixed.md

@@ -0,0 +1,17 @@
+---
+category: fixed
+issues:
+  - 3548
+affected:
+  - src/CodeIndex/Cli/ExportImportCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/ExportImportCommandRunnerTests.cs
+---
+
+## English
+
+- **Export/import JSON errors now include stable validation phases (#3548)** — `cdidx export --json` and `cdidx import --json` now return structured error payloads with `phase` and `error_code` fields for expected parse, manifest, archive, checksum, SQLite validation, prune, replacement, and archive-write failures.
+
+## 日本語
+
+- **export/import の JSON エラーに安定した検証 phase が含まれるようになりました (#3548)** — `cdidx export --json` と `cdidx import --json` は、想定される parse、manifest、archive、checksum、SQLite 検証、prune、置換、archive 書き込み失敗について `phase` と `error_code` を含む構造化エラー payload を返します。

changelog.d/unreleased/3549.changed.md

@@ -0,0 +1,17 @@
+---
+category: changed
+issues:
+  - 3549
+affected:
+  - src/CodeIndex/Cli/ExportImportCommandRunner.cs
+  - tests/CodeIndex.Tests/ProgramCliTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Export manifests now include index readiness and summary metadata (#3549)** — `cdidx export` writes bounded file/chunk/symbol/reference counts, readiness flags, writer and indexed-head metadata, schema contract stamps, and unknown-extension summary when available, and `cdidx import` validates present summary counts before replacing the destination DB.
+
+## 日本語
+
+- **export manifest に index readiness と summary metadata が含まれるようになりました (#3549)** — `cdidx export` は bounded な file / chunk / symbol / reference count、readiness flag、writer と indexed-head metadata、schema contract stamp、利用可能な unknown-extension summary を書き込み、`cdidx import` は destination DB を置き換える前に存在する summary count を検証します。

changelog.d/unreleased/3550.added.md

@@ -0,0 +1,19 @@
+---
+category: added
+issues:
+  - 3550
+affected:
+  - src/CodeIndex/Cli/ExportImportCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - src/CodeIndex/Cli/ConsoleUi.cs
+  - tests/CodeIndex.Tests/ProgramCliTests.cs
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Import can now dry-run archive validation (#3550)** — `cdidx import <archive> --dry-run` and `--check` validate the archive through the same manifest, size, checksum, SQLite, compatibility, and optional prune-path phases without replacing the destination DB; JSON output reports each phase and whether replacement would be allowed.
+
+## 日本語
+
+- **import で archive validation を dry-run できるようになりました (#3550)** — `cdidx import <archive> --dry-run` と `--check` は、destination DB を置き換えずに同じ manifest、size、checksum、SQLite、compatibility、任意の prune-path phase で archive を検証し、JSON output では各 phase と置換可能かどうかを報告します。

src/CodeIndex/Cli/ConsoleUi.cs

@@ -116,7 +116,7 @@ private static readonly (string Command, string Usage)[] CommandUsageLines =
         ("suggestions", "cdidx suggestions <list|show|export> [id] [--db <path>] [--json] [--status <all|submitted|unsubmitted>] [--language <lang>] [--category <category>] [--since <datetime>] [--agent <name>] [--limit <n>] [--offset <n>] [--format <json|markdown|issue-drafts>] [--open-issues <path>]"),
         ("export", "cdidx export <archive> [--db <path>] [--json]"),
         ("export", "cdidx export ctags [--output <path>] [--db <path>]"),
-        ("import", "cdidx import <archive> [--db <path>] [--prune-paths] [--json]"),
+        ("import", "cdidx import <archive> [--db <path>] [--prune-paths] [--dry-run|--check] [--json]"),
         ("languages", "cdidx languages [--db <path>] [--json] [--indexed-only] [--capability <graph|symbols|references>]"),
         ("batch", "cdidx batch [--db <path>]  # reads JSON string arrays from stdin, one query command per line; max 1,048,576 chars/line and 256 arguments"),
         ("mcp", "cdidx mcp [--db <path>] [--transport stdio|http] [--http-listen <host:port>] [--audit-log <path>] [--audit-log-include-values] [--audit-log-max-bytes <n>] [--suggestion-dedup-threshold <0..1>]"),
@@ -1091,6 +1091,7 @@ private static void PrintExamples()
         Console.WriteLine("  cdidx export ctags --output tags              Export editor tags for Vim, Emacs, and Sublime");
         Console.WriteLine("  cdidx export codeindex.cdidx.zip              Export a portable CodeIndex archive");
         Console.WriteLine("  cdidx import codeindex.cdidx.zip              Import a portable CodeIndex archive");
+        Console.WriteLine("  cdidx import codeindex.cdidx.zip --dry-run    Validate an archive without replacing the DB");
         Console.WriteLine("  cdidx search \"authenticate\"                    Full-text search");
         Console.WriteLine("  cdidx search \"auth*\"                          Prefix shorthand in literal-safe mode");
         Console.WriteLine("  cdidx search --query --path --path README.md   Search for a literal option token");