Actuator library: runtime swap, direct-control session, actuator option on VDSimPlant - #23

Summary

Actuator library (work order 32): runtime actuator swap, direct-control session, backlash and user-defined stage, cascade gains and sensor lag, the actuator= option on VDSimPlant, generic actuator presets, and the actuator guide in the docs navigation.

The retired direct-control-level branch is not merged. Its two options are pinned by equivalence tests in this PR instead:

• B1: steering dead time through actuator={"steer":{"dead_time_s":...}} delays the command by the exact number of substeps.
• B2: direct-control generation at L3 and L4 through the main level argument.
• 31 touch point: ClosedLoopEval mode A vs B with zero latency is bit-identical when VDSimPlant carries actuator=.

How this branch was built

This branch starts from origin/main b820364 and carries the final tree of the local working branch as six logical commits.

• Source tree: 7e538ed (local branch, never pushed). git diff 7e538ed HEAD is empty, so the local results below were measured on the same tree.
• Source history (local only): cfc977a, 58e32bb, 37dea96, b06f9bc, 179cdfc, dce96e3, merge 81fe78a, 46f68d8, 2b40c43, 7e538ed.
• Vehicle-specific measured presets are kept in private storage and are not in the public tree or in this branch's history.

History checks on the new head:

git merge-base --is-ancestor b06f9bc HEAD   -> false
git merge-base --is-ancestor 179cdfc HEAD   -> false
git log -p origin/main..HEAD | grep -ci <vehicle preset name>         -> 0
git log --name-only origin/main..HEAD | grep -c 'parts/actuator/<vehicle preset>'  -> 0

git diff --check origin/main HEAD flags trailing whitespace only in core/include/vdsim/vec_session.hpp and core/src/vec_session.cpp. Both files are CRLF on main already (every line), and the added lines keep the file's CRLF ending, so this is not a line-ending rewrite.

Local verification (tree 7e538ed = this head)

Host ailab-12, cores 0-9,12-23, cmake/ctest 3.31.10.

Fresh build of this branch's worktree (head a2358a8): ctest --preset validation rc 0, 532 / 532 passed.

Validation currency

The registered surface changed (new script tests in cosim/CMakeLists.txt), so the count was fixed by three CI attempts on one head.

closedloop_wallclock_timing appears 0 times in the CI logs (timing label excluded by the validation preset).

Windows wheel (manual wheels.yml dispatch, run 38349552030 on 8f5a8dd): sdist, wheels windows-latest, wheels ubuntu-latest, verify all success; publish skipped.

Known issues

• The C++ direct-control session maps an unknown level string to L2 without an error. Not changed in this PR; tracked as a follow-up.

B3 (information)

On main, L3 vs L4 direct-control state difference for the same scenario is zero. A first non-zero reading came from the probe script building the two sessions differently, not from the code.

🤖 Generated with Claude Code