Widthdom · Widthdom · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md
@@ -33,6 +33,7 @@ Development contracts:
 |---|---|
 | Formatting and warnings | CI enforces repository formatting with `.editorconfig` and treats compiler warnings as errors through `Directory.Build.props`, so local changes should pass the format check before opening a PR. Existing trim-analysis warnings are explicitly listed in `WarningsNotAsErrors` until they are fixed without blocking ordinary compiler-warning enforcement, and ILLink keeps reporting trim warnings without failing trimmed publish smoke tests. |
 | CLI help | `cdidx --help` stays brief, `cdidx --help-all` prints the full command/flag/example reference, `cdidx --help-flags` prints only shared flag tables, and `cdidx <command> --help` prints one command's usage line. Keep new commands visible in the brief summary only when they are a primary user workflow; every command must remain present in the full help and command-specific usage table. |
+| `index --dry-run` mutation estimates | Dry-run remains strictly non-mutating: it does not create or lock the database and does not alter sources or index artifacts. It uses read-only stat/checksum data together with the production cap-issue, symbol-filter, extractor-version, graph-contract, forced extractor/config refresh, hotspot-marker trust, and C# workspace reuse gates to project unchanged skips; projects updates, content-policy skips, deletes, purges, and symbol/reference cap hits; and performs the normal chunk/symbol/reference/content-diagnostic extraction for at most 100 planned update files. `estimated_table_mutations` counts projected delete-and-insert row operations, not final table cardinality. Its nullable values must stay synchronized with `estimated_table_mutation_details`: `source` identifies filesystem planning or parse-only plus index-snapshot input, `confidence` is `exact`, `estimate`, or `unknown`, and stable `unknown_reasons` cover candidate truncation, parse-estimate truncation/failure, C# workspace expansion, unreadable index snapshots, and partial-index table absence. A numeric zero is reserved for measured no work and remains qualified by its confidence. Parse-only estimates intentionally omit post-extraction hook mutations and cross-file C# workspace augmentation, so child-table values remain estimates; when a changed C# source proves that production must expand the refresh across otherwise reusable C# files, those child-table metrics become explicitly unknown instead of retaining incomplete parse totals. |
 | `cdidx validate` | This is the user-facing integrity scan for indexed content issues such as replacement characters, BOMs, NUL bytes, mixed line endings, UTF-16 BOMs, and likely non-UTF8 content. Keep its CLI usage, README entry, and help summary in sync when adding validation issue kinds or filters. |
 | `cdidx doctor` | This is the copy-pasteable environment summary for support requests. Keep it redacted by default: secret-like `CDIDX_*` values must not be printed, and new diagnostic fields should be stable enough for issue triage. Full environment inventory filters (`--env-domain`, `--env-category`, and `--env-sensitivity`) use case-insensitive exact values and compose with AND; filtered JSON summaries describe the returned inventory rather than the global catalog. `--max-json-bytes` is valid only with `--json --env-inventory=full`, counts the serialized UTF-8 document plus its newline, and returns a structured usage error rather than an oversized successful document. The `github` block reports `proxy_default_credentials` as `enabled` / `disabled` and the bounded `max_request_timeout_s`; never print proxy credential material or raw secret values. `license --json` returns the versioned `license`, `commercial_use`, `trademark`, and controlling `documents` contract. |
 | Exception diagnostics | User-facing CLI, JSON, MCP, file-issue, and local diagnostic output must not echo raw `ex.Message` directly. Route exception prose through `CommandErrorWriter.FormatSanitizedExceptionMessage`, `DiagnosticSanitizer.ForMessage`, or an existing bounded `DiagnosticRedactor` helper, and use stable error codes/categories when the message is not needed for recovery. Intentional broad catches should match the `risky-code/broad-exception-catch` taxonomy and normalize to bounded diagnostics, private best-effort suppression, or a documented fallback. |
@@ -3388,6 +3389,7 @@ net9 CI lane に合わせる場合は `FRAMEWORK=net9.0 make test` を使いま
 |---|---|
 | formatting と warning | CI は `.editorconfig` による repository formatting を強制し、`Directory.Build.props` により compiler warning を error として扱います。ローカル変更は PR 前に formatting check を通してください。既存の trim 解析警告は、通常の警告エラー化を止めずに修正を進められるよう `WarningsNotAsErrors` に明示列挙されています。ILLink は trimmed publish の smoke test を失敗させずに trim warning を報告し続けます。 |
 | CLI help | `cdidx --help` は短い概要、`cdidx --help-all` は全コマンド・flag・例の一覧、`cdidx --help-flags` は共有 flag table のみ、`cdidx <command> --help` は 1 コマンドの usage line を出します。新しいコマンドは主要な user workflow である場合だけ簡易概要に載せ、full help とコマンド固有の usage table には必ず載せてください。 |
+| `index --dry-run` の mutation 推定 | dry-run は厳密に非変更のままにし、database の作成・lock や source / index artifact の変更を行いません。read-only な stat / checksum と production の cap issue、symbol filter、extractor version、graph contract、extractor / config の強制 refresh、hotspot marker の trust、C# workspace の再利用条件を組み合わせて未変更 skip を判定し、update、内容に対する policy skip、delete、purge、symbol / reference 上限到達を予測し、update 予定 file のうち最大100件に通常の chunk / symbol / reference / content diagnostic 抽出を適用します。`estimated_table_mutations` は最終 table row 数ではなく、delete と insert の予測 row operation 数です。nullable な値は `estimated_table_mutation_details` と常に同期させます。`source` は filesystem plan または parse-only と index snapshot の入力元、`confidence` は `exact` / `estimate` / `unknown`、安定した `unknown_reasons` は candidate の切り詰め、parse 推定の切り詰め・失敗、C# workspace の展開、index snapshot の読み取り不能、partial index の table 不足を表します。数値のゼロは、処理がないと計測できた場合だけに使い、その信頼度も併記します。parse-only 推定では extraction 後の hook mutation と C# の cross-file workspace augmentation を意図的に省くため、child table の値は estimate のままです。変更された C# source によって production が本来再利用可能な C# file にも refresh を展開すると判明した場合は、不完全な parse 合計を残さず、それらの child-table metric を明示的な unknown にします。 |
 | `cdidx validate` | replacement character、BOM、NUL byte、混在改行、UTF-16 BOM、非 UTF-8 らしい内容など、indexed content の問題を user-facing に検査する integrity scan です。validation issue の種別や filter を追加する場合は、CLI usage、README entry、help summary を同期してください。 |
 | `cdidx doctor` | support request 向けにコピーしやすい environment summary です。既定では redacted に保ち、secret 風の `CDIDX_*` 値は出力しないでください。新しい diagnostic field は issue triage に使える程度に安定したものだけにします。full environment inventory の filter（`--env-domain`、`--env-category`、`--env-sensitivity`）は大文字小文字を区別しない完全一致で AND 合成し、filtered JSON summary は global catalog ではなく返却 inventory を表します。`--max-json-bytes` は `--json --env-inventory=full` とだけ組み合わせ、serialize した UTF-8 文書と改行を数え、上限を超える成功文書の代わりに structured usage error を返します。`github` block は `proxy_default_credentials` を `enabled` / `disabled` として出力し、bounded な `max_request_timeout_s` も出します。proxy credential material や raw secret value は出力しないでください。`license --json` は version 付きの `license`、`commercial_use`、`trademark`、controlling `documents` contract を返します。 |
 | 例外診断 | user-facing な CLI / JSON / MCP / file issue / local diagnostic output では raw `ex.Message` を直接 echo しないでください。例外の prose は `CommandErrorWriter.FormatSanitizedExceptionMessage`、`DiagnosticSanitizer.ForMessage`、または既存の bounded な `DiagnosticRedactor` helper を通し、回復に message が不要な場合は安定した error code/category を使ってください。意図的に残す broad catch は `risky-code/broad-exception-catch` taxonomy に沿い、bounded diagnostic、private な best-effort suppression、または documented fallback に正規化してください。 |

diff --git a/README.md b/README.md
@@ -227,6 +227,25 @@ stderr. Human mode keeps the corresponding `Error`, `Hint`, and `Usage` lines.
 See the [Developer Guide](DEVELOPER_GUIDE.md#cli-recoverable-error-format) for
 the stable code/category mapping.
 
+## Index Dry-Run Mutation Estimates
+
+`cdidx index <project> --dry-run --json` reports update, unchanged-skip,
+content-policy-skip, delete, purge, symbol-cap, and reference-cap projections
+without creating a database, acquiring the index lock, or changing source or
+index artifacts. The first 100 planned update files receive parse-only
+estimates for `chunks`, `symbols`, `symbol_references`, `reference_lines`, and
+`file_issues`. The nullable
+`estimated_table_mutations` values are paired with
+`estimated_table_mutation_details`, whose `source`, `confidence`, and
+`unknown_reasons` distinguish an estimated or exact zero from unavailable
+work. Candidate-path truncation, the parse-estimate cap, parse failures,
+cross-file C# refresh expansion, an unreadable index snapshot, and missing
+tables in a partial index therefore produce `null` plus a stable reason instead
+of a misleading zero. Reuse projections also honor production extractor/config
+refreshes and hotspot-marker trust. See the
+[Developer Guide](DEVELOPER_GUIDE.md#build--test) for the implementation
+contract and limitations.
+
 ## Status JSON Contract
 
 `cdidx status --json` exposes trust, freshness, compatibility, and remediation
@@ -681,6 +700,23 @@ prose を stderr に混ぜず、envelope を stdout に出力します。human m
 category 対応は
 [開発者ガイド](DEVELOPER_GUIDE.md#cli-の回復可能エラー形式) を参照してください。
 
+## index dry-run の mutation 推定
+
+`cdidx index <project> --dry-run --json` は database を作成せず、index lock を
+取得せず、source / index artifact を変更せずに、update、未変更 skip、内容に
+対する policy skip、delete、purge、symbol 上限到達、reference 上限到達の予測を
+返します。update 予定 file の先頭100件について `chunks`、`symbols`、
+`symbol_references`、`reference_lines`、`file_issues` を parse-only で推定します。
+nullable な
+`estimated_table_mutations` の各値には `estimated_table_mutation_details` が対応し、
+`source`、`confidence`、`unknown_reasons` により、推定値または正確なゼロと
+計測不能を区別します。そのため candidate path の切り詰め、parse 推定の上限、
+parse failure、C# の cross-file refresh 展開、index snapshot の読み取り不能、
+partial index の table 不足は、誤解を招くゼロではなく安定した理由付きの `null`
+になります。再利用予測には production の extractor / config refresh と hotspot
+marker の trust も反映します。実装上の契約と制限は
+[開発者ガイド](DEVELOPER_GUIDE.md#ビルドテスト) を参照してください。
+
 ## Status JSON 契約
 
 `cdidx status --json` は script、MCP client、release check 向けに trust、

diff --git a/changelog.d/unreleased/4893.changed.md b/changelog.d/unreleased/4893.changed.md
@@ -0,0 +1,20 @@
+---
+category: changed
+issues:
+  - 4893
+affected:
+  - src/CodeIndex/Cli/IndexCommandRunner.DryRun.cs
+  - src/CodeIndex/Cli/IndexCommandRunner.cs
+  - src/CodeIndex/Cli/JsonOutputContracts.cs
+  - tests/CodeIndex.Tests/IndexCommandRunnerDryRunTests.cs
+  - README.md
+  - DEVELOPER_GUIDE.md
+---
+
+## English
+
+- **Index dry-run now reports useful mutation estimates and explicit unknowns (#4893)** — New and changed files receive bounded parse-only chunk, symbol, reference, reference-line, and issue estimates; unchanged, deleted, policy-skipped, symbol-capped, and reference-capped files expose their projected outcomes; production extractor/config, hotspot-marker, and C# workspace invalidations are reflected in reuse projections; and truncation, parse failures, unreadable snapshots, or partial index schemas return nullable metrics with source, confidence, and stable unknown reasons instead of misleading zeros, while preserving dry-run's non-mutation guarantee.
+
+## 日本語
+
+- **index dry-run が有用な mutation 推定と明示的な unknown を返すようになりました (#4893)** — 新規・変更 file には上限付きの parse-only による chunk、symbol、reference、reference-line、issue 推定を返し、未変更、削除、policy skip、symbol 上限、reference 上限の予測結果も公開します。production の extractor / config、hotspot marker、C# workspace による無効化も再利用予測へ反映し、切り詰め、parse failure、snapshot の読み取り不能、partial index schema の場合は誤解を招くゼロではなく、入力元、信頼度、安定した unknown reason を持つ nullable metric を返して、dry-run の非変更保証を維持します。