docs(cdb): A6.P1 — README for the cdb probe + runner

Documents prerequisites (PDB match, cdb install, retail+ACE running), per-scenario invocation, the 9-scenario tag table, and the parallel acdream capture command. Includes the CLAUDE.md cdb watchouts inline so probe operators don't have to chase them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 18:44:42 +02:00 · 2026-05-21 18:44:42 +02:00 · df315a9654
commit df315a9654
parent 1c640ebefa
1 changed files with 99 additions and 0 deletions
--- a/tools/cdb/README-a6-probe.md
+++ b/tools/cdb/README-a6-probe.md
@ -0,0 +1,99 @@
+# A6.P1 cdb probe — usage
+
+Phase A6.P1 cdb probe spike (2026-05-21). Captures retail's per-tick BSP
+collision response state for paired comparison against acdream.
+
+## Files
+
+- `a6-probe.cdb` — the 7-breakpoint cdb script (see comments inside).
+- `a6-probe-runner.ps1` — PowerShell wrapper that attaches cdb to live retail.
+
+## Prerequisites
+
+1. **Retail binary matches our PDB.** Verify with:
+   ```powershell
+   py tools\pdb-extract\check_exe_pdb.py "C:\Turbine\Asheron's Call\acclient.exe"
+   ```
+   Expected: `=== MATCH: this exe pairs with our acclient.pdb ===`
+
+2. **cdb installed.** Microsoft Store WinDbg installs cdb at
+   `C:\Program Files (x86)\Windows Kits\10\Debuggers\x86\cdb.exe`. 32-bit
+   required for acclient.exe.
+
+3. **Retail running and in-world.** Launch retail, log into your character,
+   navigate to the scenario start point.
+
+4. **ACE running locally on 127.0.0.1:9000.**
+
+## Usage
+
+For each of the 9 A6.P1 scenarios:
+
+```powershell
+# 1. Position retail character at scenario start (e.g., outside Holtburg inn).
+# 2. Launch the probe with a scenario tag:
+.\tools\cdb\a6-probe-runner.ps1 -ScenarioTag "scen1_inn_doorway"
+
+# 3. cdb attaches; "a6-probe armed: BPs 1-7 set" appears in console.
+# 4. In the retail client window, perform the scripted walk for this scenario.
+# 5. cdb auto-detaches at 50K total hits (cleanly via qd; retail keeps running).
+# 6. Log filed at docs\research\2026-05-21-a6-captures\scen1_inn_doorway\retail.log
+```
+
+## The 9 scenarios
+
+Per the A6 design spec, in capture order:
+
+| # | Tag | Walk script |
+|---|---|---|
+| 1 | `scen1_inn_doorway` | Walk forward through door, stop just inside |
+| 2 | `scen2_inn_stairs` | Walk up 4 steps, stop on landing |
+| 3 | `scen3_inn_2nd_floor` | Walk forward 3 m, sidestep 1 m, walk back |
+| 4 | `scen4_cottage_cellar` | Walk to cellar opening, descend 2 steps |
+| 5 | `scen5_sewer_entry` | Walk into portal, then walk 2 m forward inside |
+| 6 | `scen6_sewer_first_stair` | Walk down full stair flight |
+| 7 | `scen7_sewer_inter_room` | Walk through portal, stop 1 m past |
+| 8 | `scen8_sewer_chamber` | Walk in, traverse center, walk out other side |
+| 9 | `scen9_sewer_corridor` | Walk full length end-to-end |
+
+## Pairing with acdream
+
+For each scenario, run acdream IN PARALLEL with the same scripted walk:
+
+```powershell
+$env:ACDREAM_DAT_DIR          = "$env:USERPROFILE\Documents\Asheron's Call"
+$env:ACDREAM_LIVE             = "1"
+$env:ACDREAM_TEST_HOST        = "127.0.0.1"
+$env:ACDREAM_TEST_PORT        = "9000"
+$env:ACDREAM_TEST_USER        = "testaccount"
+$env:ACDREAM_TEST_PASS        = "testpassword"
+$env:ACDREAM_DEVTOOLS         = "1"
+$env:ACDREAM_PROBE_PUSH_BACK  = "1"
+$env:ACDREAM_PROBE_INDOOR_BSP = "1"
+$env:ACDREAM_PROBE_CELL       = "1"
+$env:ACDREAM_PROBE_CELL_CACHE = "1"
+$env:ACDREAM_PROBE_CONTACT_PLANE = "1"
+
+dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
+    Tee-Object -FilePath "docs\research\2026-05-21-a6-captures\scen1_inn_doorway\acdream.log"
+```
+
+The `[push-back]`, `[push-back-disp]`, `[push-back-cell]` lines in
+`acdream.log` pair with the `[BP1]..[BP7]` lines in `retail.log` via
+scenario tag.
+
+## Known watchouts
+
+Per [`CLAUDE.md`](../../CLAUDE.md#known-watchouts):
+
+- **High BP hit rates cause retail lag.** 50K threshold is the calibrated
+  ceiling that keeps retail responsive without triggering ACE timeout.
+- **`qd` (quit detached) is forbidden in BP actions** per CLAUDE.md cdb
+  watchout. The a6-probe.cdb script puts `qd` ONLY in the threshold
+  branch, NOT directly in a BP action's primary command list. Verify this
+  is preserved if editing.
+- **Killing cdb kills retail.** `qd` detaches cleanly; `Stop-Process` does
+  not. If you must interrupt mid-capture, press Ctrl-Break in the cdb
+  console.
+- **acclient.exe is 32-bit + uses thiscall.** `this` is in `ecx`. Struct
+  field offsets in the script come from `docs/research/named-retail/acclient.h`.