userspace/cuda: complete the analysis pass

* Name recovery: name_candidates.py proposes the hand-written API-layer
  implementation for each exported wrapper by grouping version variants and
  intersecting their callees; 180 high-confidence proposals recorded in
  annotations/name-candidates.tsv, 29 of them body-verified and promoted to
  names.tsv with evidence in subsystems.tsv.
* Engine records: identified the 0x14-byte per-engine descriptor, mapped its
  fields (kind, engine type, instance, class id, CE caps) and the existence
  callback, and documented how the missing async copy engine (COPY14) leaves
  the secondary record zeroed and blocks context creation (docs/05 section
  3.7, public-safe).
* Targeted type recovery: AnalyzeFunctions.java runs the parameter-ID
  analyzer over a curated list of 80 functions; 16 improved materially and
  the typed decompilations are kept under the version run tree.
* Cross-version: cudatool.py fdematch measures how names transfer between
  patch versions (570.144 -> 570.211.01: exports 100%, verified internals
  ~70%, generated wrappers must be re-resolved by relocation, never by
  address arithmetic); documented in the upgrade playbook.
* Corpus tooling: diff_corpus.py (version-to-version corpus diff) and
  subsystem_digest.py (per-subsystem call trees).
* Deprecate the old per-version helpers whose address handling and analysis
  timeout produced wrong results.

Generated corpora and typed outputs remain untracked under the version run
tree.

1 files changed, 30 insertions, 1 deletions

diff --git a/userspace/cuda/docs/07-version-upgrade-playbook.md b/userspace/cuda/docs/07-version-upgrade-playbook.md
index 337f5eb..23569bd 100644
--- a/userspace/cuda/docs/07-version-upgrade-playbook.md
+++ b/userspace/cuda/docs/07-version-upgrade-playbook.md
@@ -49,6 +49,33 @@ with `PrintProgramInfo.java` before citing addresses.
 
 ## 3. Transfer names and knowledge
 
+Measure the transfer first, before copying anything:
+
+```
+tools/cudatool.py fdematch <previous>/run/libcuda.so.<old> <libcuda.so.<new>> \
+    --names <previous>/annotations/names.tsv
+```
+
+`fdematch` matches function ranges from both `.eh_frame_hdr` tables using the
+common exports as local address anchors (same FDE size within a small window
+of `old_addr + nearest-export delta`), and breaks the previous name map down
+by its `source` column. Measured for **570.144 → 570.211.01**
+(`570.144/run/analysis/fdematch-570.144-570.211.txt`, gitignored):
+
+| Map part | Transferable | How |
+|---|---|---|
+| 659 exports | **100%**, exact | same name, same size, address = old + local delta |
+| verified internals | 5/7 (71%) | anchored same-size window |
+| wrapper-callee internals | 21/29 (72%) | anchored same-size window |
+| generated `wrapper_*` | **1.1%** | **do not transfer by address** |
+| all A functions | 85.5% matched (58.3% unique) | anchored same-size window |
+
+The wrapper result is the important one: the generated wrapper region is
+re-laid-out between patch versions, so wrapper addresses must be re-resolved
+on the new binary with `tools/cudatool.py wrappers` (and then
+`annotate_corpus.py` re-run), never by adding a delta to the old map. Export
+and hand-written internal names do carry over.
+
 ```
 cp <previous>/annotations/names.tsv <new>/annotations/names.tsv
 # translate addresses: the map is file-vaddr keyed, so for unchanged
@@ -61,7 +88,9 @@ analyzeHeadless <proj> cuda-full -process <program> -noanalysis \
 
 Also transfer the *subsystem index* (`annotations/subsystems.tsv`: address,
 our name, subsystem, evidence) and re-validate the entries that the delta
-marked as moved.
+marked as moved. For corpus-level measurement (added/removed/resized
+functions, not just name transfer) use `tools/diff_corpus.py` on the old and
+new `decompiled_index.tsv` once the new version has been decompiled.
 
 ## 4. Validate against the guest