docs(runtime): give the retention witness its section, and take back the comment that outlived its method

[PhysShell]

Closes #334 — the remainder carved out when PR #280 was closed as superseded. Independent of #333: different branch, no shared files, mergeable in any order.

Dominators.cs is not restored, per the issue.

Что и зачем

0753a45 приземлил свидетеля «minus the dominator tree» — решение осознанное и записанное в csproj. Но три вещи остались висеть: <summary> про доминаторы пережил свой метод и стал документацией к Dispose(); RetentionPath оказался единственным из четырёх runtime-инструментов без секции в README, хотя таблица его возможность обещает; и указатель «See the README» вёл в пустоту. Здесь всё три закрыты, кода не возвращено.

1. A doc comment outlived its method

The extraction removed the method and kept its <summary>, which C# then binds to the next member regardless of the blank line:

/// <summary>
/// The dominator tree of the whole live graph, with retained sizes. …
/// </summary>

public void Dispose()

So the file advertised, on Dispose(), precisely the capability the extraction had removed. Deleted.

2. RetentionPath had no README section

It was the only one of the four runtime tools without one, while README.md:27 kept advertising "Heap analysis (retained, duplicates, retention paths) — ClrMD" in the stack table:

tool	section before	after
LeakHarness	✅ §4.1	✅
DuplicateDetector	✅ cat. 11	✅
PropertyChangedStorm	✅ cat. 6	✅
RetentionPath	none	✅

The new section covers what the two verbs answer and why the order matters — census first, because ClrHeap.EnumerateObjects() returns uncollected garbage too and a big heap is not evidence of a leak; then roots, with the field names that turn "this object is alive" into "this field is holding it".

Deliberately weighted toward the parts that constrain trust rather than advertise:

• percentages are shares of the resolved sample, never of the population;
• the verdict is computed over every instance, so no display budget (--sample, --max-hops) can move the diagnosis or the exit code;
• a [stack] root is liveness, not retention;
• the type matcher refuses System.Func<…GTDGoody…> because it once confidently reported a 2-hop path to the wrong object;
• attaching suspends the target — on a multi-GB heap, take a dump.

Plus the exit-code table and why exit 2 is a tier of its own, cross-linked to docs/runtime-witness-operations.md.

Layout and Status were missing the tool too; both now name it, and Status records the dominator tree under Deferred instead of leaving it unmentioned.

3. The dangling pointer

Heap.cs:34 said "See the README" about the dominator tree and the README had nothing to see. It now points at a section that exists, states plainly that dominance is not implemented here, and sends anyone wanting the reasoning to #334, where the extracted implementation's argument is recorded.

Одна поправка к самому #334

Issue поместил dangling pointer в Program.cs. Он в Heap.cs:34. Program.cs тоже упоминает dominator tree, но как ремарку без перекрёстной ссылки, поэтому править там нечего. Записываю, потому что issue писал я, и ошибка в нём — моя.

Тип изменения

• docs — документация
• fix — исправление бага (осиротевший XML-комментарий документировал не тот член)

Как проверено

• dotnet build audit/runtime/RetentionPath -c Release → 0 warnings, 0 errors
• RetentionPath selftest → 16/16
• python audit/runtime/ingest.py --selftest → 26/26
• python tests/run_tests.py → exit 0, wpf 28/28
• проверил программно, что у всех четырёх runtime-инструментов теперь есть секция в README, и что Dominators.cs не вернулся

Связанные issue

Closes #334. Refs #280 (closed as superseded), #309, 0753a45.

Чеклист

• изменение покрыто существующими селфтестами (правка документационная; удаление комментария проверено сборкой)
• README/docs обновлены — в этом и состоит изменение
• коммит в conventional-commit стиле

---

Generated by Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ec014840-d2cb-48f6-a462-4443a5db277f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}