docs: Ghidra decompiler unreliable for this ROM (~85% of sampled functions flagged); SLEIGH instruction coverage incomplete

docs/ghidra-tms34010-calla-bug.md

@@ -598,3 +598,62 @@ The `.cspec/.pspec/.ldefs/.slaspec` were re-copied by the installer with unchang
 The `tms34010.sinc` fix was swept into HEAD by the concurrently-running worker's broad
 `git add -A` commit `5000b8bc07a8` before this task committed; HEAD therefore already contains
 lines 73/185 as shown in §1. This task's own commit adds only §1–§8 of this document.
+
+---
+
+# FURTHER FINDING: the decompiler is not trustworthy for this ROM either
+
+Found 2026-10-16, after the `CALLA`/`ADDI` fix above, while investigating why a worker
+reported "Ghidra failed to decompile the DUART test code".
+
+## Symptom
+
+`decomp_function` does **not** error — it returns C, but with a warning embedded, e.g.:
+
+```c
+/* WARNING: Control flow encountered bad instruction data */
+
+void FUN_rom_07fbbf96(uint param_1, undefined4 param_2, undefined4 param_3)
+{
+  ...
+```
+
+## Measurement
+
+Twelve functions sampled across the ROM, decompiled via the MCP:
+
+```
+sampled: 12    warned ("bad instruction data" or other WARNING): 10    clean: 2    hard errors: 0
+```
+
+So roughly **85% of sampled functions** produce output that carries a warning that the
+decompiler could not follow the real instruction stream. The returned C is therefore
+**unreliable**, even though it looks plausible.
+
+## Cause
+
+This is a **different and deeper defect than the `CALLA` mask**: it is not an address
+computation error but **missing/incomplete instruction definitions in the SLEIGH module**
+(`tools/ghidra-tms34010/tms34010.sinc`). Where an instruction has no p-code, the decompiler
+cannot model its effect and reports "bad instruction data" on that path.
+
+## Consequence — the working rule for this project
+
+| Ghidra layer | verdict |
+|---|---|
+| **disassembly** (`listing_disassemble_range`, `search_instructions`) | **trustworthy** — validated at 31,691/31,691 affected sites after the fix |
+| **xrefs / call graph / function recovery** | **trustworthy** — 25 → 1,588 functions |
+| **decompiler / p-code** (`decomp_function`) | **NOT trustworthy** — ~85% of sampled functions flagged |
+
+Use Ghidra for structure and disassembly; use `tools/smart34010/dis34` when reading
+instruction semantics. Do not build conclusions on decompiled C for this ROM until the
+SLEIGH instruction coverage is completed.
+
+## To fix later
+
+Extend the SLEIGH module's instruction definitions so every opcode used by this firmware has
+p-code. That is a substantially larger job than the one-line mask fix — it needs the full
+TMS34010 instruction set audited against `tms34010.sinc`, with each missing instruction
+added and the `.sla` rebuilt and re-validated the same way (see the FIX + VALIDATION section
+above for the validation method: cross-check against `smart34010` and check for
+over-correction on the instructions that were already correct).