Fix: extend PTO-ISA version guard to a5 async workspace overlays

[yanghaoran29]

Summary

• Generalize the PTO-ISA pin/metadata/staleness/ccache guard from a2a3-onboard-only to "host embeds pto-isa headers", via a new platform_embeds_pto_isa predicate: a2a3 onboard always; a5 onboard only when an async workspace overlay is ON — SDMA (SIMPLER_ENABLE_PTO_SDMA_WORKSPACE) or URMA (SIMPLER_ENABLE_PTO_URMA_WORKSPACE, added in feat(a5): add URMA deferred completion backend for tensormap_and_ringbuffer #1392).
• Resolve the managed pin in build_runtimes / _init_a5 when embedding, write a5 provenance metadata, and bake SIMPLER_PTO_ISA_BUILD_COMMIT into the a5 host ccache key whenever an overlay populates it.
• Extend test_runtime_builder coverage for a5 SDMA/URMA overlay ON (validate / metadata / stamp / cmake define / pin) and OFF (no-op); OFF cases now also clear the URMA env var.
• Docs: refresh the docs/a5-sdma-overlay.md "Gating points" table for the guard sites that activate when the overlay is ON, and note the a5 case in getting-started.md / developer-guide.md.

Rebased onto latest main; composes with the URMA overlay (#1392) so both a5 async overlays get the same stale-binary guard.

Fixes #1351

[coderabbitai]

📝 Walkthrough

Walkthrough

PTO-ISA handling now follows whether a platform embeds PTO-ISA headers. The change extends pin resolution, metadata validation, cache stamping, and host compile definitions to a5 onboard builds when the SDMA workspace overlay is enabled, while leaving overlay-disabled a5 builds unchanged.

Changes

PTO-ISA embedding lifecycle

Layer / File(s)	Summary
Embedding predicate and runtime validation simpler_setup/runtime_builder.py	Adds platform_embeds_pto_isa() for a2a3 onboard and overlay-enabled a5 onboard platforms, and uses it for runtime metadata validation.
Build pin and host compilation wiring simpler_setup/build_runtimes.py, simpler_setup/runtime_compiler.py, src/a5/platform/onboard/host/CMakeLists.txt	Extends managed PTO-ISA root resolution and metadata-key collection to embedding platforms, conditionally initializes a5’s pinned root, and passes the PTO-ISA commit to host_runtime.
Behavior coverage and diagnostics tests/ut/py/test_runtime_builder.py, simpler_setup/pto_isa.py	Adds overlay-specific validation, metadata, cache-stamp, and pin-resolution tests, and updates PTO-ISA checkout error wording.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• hw-native-sys/simpler 1315 — Describes the a5 PTO-ISA guard gap addressed by this change.

Possibly related PRs

• hw-native-sys/simpler#1096 — Introduced the PTO-ISA runtime compatibility validation pipeline expanded here.
• hw-native-sys/simpler#1179 — Added the a5 SDMA overlay that causes host runtimes to embed PTO-ISA headers.

Poem

A rabbit hops where pinned headers grow,
A5’s bright overlay now knows the flow.
Cache stamps bloom with commits in line,
Old runtimes face a guarded sign.
“Build true,” twirls the rabbit, “and keep it fine!”

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes match #1351: a5 overlay builds use pinned PTO-ISA, write metadata, validate staleness, update cache stamps, and add the CMake define.
Out of Scope Changes check	✅ Passed	The modified files stay within the PTO-ISA guard and a5 overlay scope, with no obvious unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly states the main change: extending the PTO-ISA guard to a5 async workspace overlays.
Description check	✅ Passed	The description is on-topic and summarizes the PTO-ISA guard expansion plus related tests and docs.

---

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

[gemini-code-assist]

Code Review

This pull request refactors the build setup to support embedding PTO-ISA headers for the a5 platform when the SDMA overlay is enabled (SIMPLER_ENABLE_PTO_SDMA_WORKSPACE is ON), mirroring the existing behavior for a2a3. It introduces a helper function platform_embeds_pto_isa to dynamically determine if a platform embeds these headers, updates the cache invalidation logic, sets up the environment variable PTO_ISA_ROOT for a5 when opted in, and updates the CMake configuration for a5 to bake the PTO-ISA commit into the compiler cache key. Comprehensive unit tests are also added to verify these changes. There are no review comments, so I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[ChaoZheng109]

Doc consistency: update docs/a5-sdma-overlay.md "Gating points" table

The code changes look correct and the test coverage is solid (a5 overlay ON/OFF both exercised). One thing to fix before merge — the doc most directly tied to this change is now stale.

This PR extends the PTO-ISA pin / metadata / staleness / ccache guard to the a5 SDMA overlay, but the "Gating points" table in docs/a5-sdma-overlay.md (the canonical map of what the overlay gates) no longer matches the code:

• The simpler_setup/runtime_compiler.py row still reads _init_a5 "PTO_ISA_ROOT ensure + _sdma_workspace_enabled()". Under this PR _init_a5 now resolves the pinned managed checkout (ensure_pto_isa_root) — same contract as a2a3 — not just an ensure of a user-provided var.
• There is no row for the guard machinery this PR newly activates under the overlay:
  • platform_embeds_pto_isa predicate in simpler_setup/runtime_builder.py (now the single driver of every guard site)
  • pin/metadata write + load-time staleness validation for a5 onboard binaries
  • the new SIMPLER_PTO_ISA_BUILD_COMMIT cache-string / compile-define block in src/a5/platform/onboard/host/CMakeLists.txt

Please update the table in the same commit (per .claude/rules/doc-consistency.md §1/§4) so the overlay doc reflects the protections that now apply when the overlay is ON.

---

Optional, non-blocking: docs/getting-started.md:58 and docs/developer-guide.md:188 both describe the metadata/ccache guard as "a2a3 onboard" only. A parenthetical "(and a5 onboard when the SDMA overlay is enabled)" would make them accurate, but they self-correct once a5 unifies to a2a3, so feel free to defer.

Also non-blocking (transitional only): _requires_pto_isa_metadata_validation() recomputes _sdma_workspace_enabled() at load time, so a5 load-time staleness validation is skipped if the loading process doesn't set the env var. This is strictly better than the pre-PR state (no a5 validation at all) and disappears entirely once a5 forces the workspace ON like a2a3 — no action needed here.

[yanghaoran29]

Thanks — all addressed in the pushed update:

• docs/a5-sdma-overlay.md "Gating points" — rewrote the table: fixed the runtime_compiler.py row (_init_a5 now resolves the pinned managed checkout via ensure_pto_isa_root, same contract as _init_a2a3), and added rows for platform_embeds_pto_isa, the pin/metadata/staleness validation it drives, and the SIMPLER_PTO_ISA_BUILD_COMMIT cache-key block.
• Optional parentheticals — added "(and a5 onboard when the SDMA overlay is enabled)" to docs/getting-started.md and docs/developer-guide.md.

While rebasing onto latest main I also composed with the URMA overlay (#1392): platform_embeds_pto_isa now keys on SDMA or URMA, so both a5 async overlays get the same guard (previously URMA would have hit the identical stale-binary gap). Table and UT updated to match.