Test: mirror a2a3 scope-guard regression to a5 and fix stale TMR docs

[yanghaoran29]

Summary

Closes the two P4/P5 residuals flagged in #1582's 2026-08-09 re-audit (after #1718 landed).

R1 — a5 lacked the scope-guard regression test that a2a3 gained in #1718

a5's PTO2_SCOPE_GUARD(...) has been variadic (and its MANUAL path live — rt_scope_begin reads pending_scope_mode and forwards it to begin_scope(mode)) since the #1100 import, but ut-a5 would not catch a regression in MANUAL forwarding. Mirrored ScopeGuardForwardsModeUntilLexicalScopeExit to tests/ut/cpp/a5/test_a5_fatal.cpp:

• FakeRuntime gains pending_scope_mode (immediately after ops, the prefix the inline wrappers pun through) and last_scope_mode.
• fake_scope_begin records the forwarded mode.
• The test asserts AUTO then MANUAL forwarding across lexical scope exit.

Both test files also extend the single offsetof(FakeRuntime, ops) == 0 guard to a second one pinning pending_scope_mode at sizeof(PTO2RuntimeOps *), since the reinterpret_cast now depends on the two-field {ops, pending_scope_mode} prefix, not one.

R2 — a2a3 RUNTIME_LOGIC.md retained-buffer wording was stale

a2a3 described the retained temp buffer as a single runner-owned instance, but the shared host-runtime callback get_retained_temp_buffer(runner_ctx, pipeline_slot, ...) is per-slot and a5's matching paragraph already says so. Aligned a2a3 to a5's wording ("each slot's buffer lives on the runner").

Bonus — stale accessor location in both trees' MULTI_RING.md

PTO2TaskId's direct accessors live in src/common/task_interface/pto_task_id.h, not pto_runtime2_types.h. Fixed in both a2a3 and a5.

Test plan

• cmake -S tests/ut/cpp -B build_ut -G Ninja then cmake --build build_ut --target test_a2a3_fatal test_a5_fatal — both compile clean.
• ./build_ut/test_a2a3_fatal — 4/4 passed (incl. A2A3Fatal.ScopeGuardForwardsModeUntilLexicalScopeExit).
• ./build_ut/test_a5_fatal — 4/4 passed (incl. new A5Fatal.ScopeGuardForwardsModeUntilLexicalScopeExit).
• CI ut-a2a3 / ut-a5 green.

Refs #1582.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

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: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 21bc7d03-a257-419b-a076-44631631159d

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

📝 Walkthrough

Walkthrough

The pull request adds scope-mode tracking and layout assertions to A2A3 and A5 runtime tests. It adds coverage for default and manual PTO2_SCOPE_GUARD behavior. It also corrects runtime documentation for accessor paths and retained buffer ownership.

Changes

Runtime scope behavior and documentation

Layer / File(s)	Summary
Scope guard validation tests/ut/cpp/a2a3/test_a2a3_fatal.cpp, tests/ut/cpp/a5/test_a5_fatal.cpp	Fake runtimes record scope modes and validate runtime prefix layout. Tests cover default and manual PTO2_SCOPE_GUARD forwarding and lexical scope exits.
Runtime documentation updates src/a2a3/runtime/tensormap_and_ringbuffer/docs/MULTI_RING.md, src/a2a3/runtime/tensormap_and_ringbuffer/docs/RUNTIME_LOGIC.md, src/a5/runtime/tensormap_and_ringbuffer/docs/MULTI_RING.md	Documentation points PTO2TaskId accessors to the current header and describes retained buffers per pipeline slot.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• hw-native-sys/simpler#1718: Adds related scope-mode forwarding tests and runtime layout assertions.

Poem

A rabbit checks the scope with care,
AUTO and MANUAL modes pass through the air.
Guards begin and guards then end,
Layout checks stand as a friend.
Correct docs now guide the way.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the added a5 scope-guard regression test and the stale TMR documentation fixes.
Description check	✅ Passed	The description directly explains the test changes, documentation updates, validation results, and pending CI status.

---

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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/ut/cpp/a2a3/test_a2a3_fatal.cpp`:
- Line 53: Update the static layout assertions near FakeRuntime in
tests/ut/cpp/a2a3/test_a2a3_fatal.cpp:53-53 and
tests/ut/cpp/a5/test_a5_fatal.cpp:47-47 to compare
FakeRuntime::pending_scope_mode’s offset directly with
PTO2Runtime::pending_scope_mode, preserving the production runtime layout
contract used by PTO2ScopeGuard.

In `@tests/ut/cpp/a5/test_a5_fatal.cpp`:
- Around line 183-206: Update the setup in
ScopeGuardForwardsModeUntilLexicalScopeExit to initialize
runtime.pending_scope_mode to PTO2ScopeMode::MANUAL before the first
PTO2_SCOPE_GUARD(); retain the existing assertion that the default guard
forwards PTO2ScopeMode::AUTO.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: ea5b98df-86e6-4624-a406-59b782871a97

📥 Commits

Reviewing files that changed from the base of the PR and between 69be6b7 and 17948bd.

📒 Files selected for processing (5)

• src/a2a3/runtime/tensormap_and_ringbuffer/docs/MULTI_RING.md
• src/a2a3/runtime/tensormap_and_ringbuffer/docs/RUNTIME_LOGIC.md
• src/a5/runtime/tensormap_and_ringbuffer/docs/MULTI_RING.md
• tests/ut/cpp/a2a3/test_a2a3_fatal.cpp
• tests/ut/cpp/a5/test_a5_fatal.cpp