Track PTO-ISA build/run revision compatibility validation

[vegetabledoww]

Background

PR #1096 adds PTO-ISA build/run revision compatibility validation for simpler.

The current implementation records the actual PTO-ISA git HEAD used when pip install builds the a2a3 onboard runtime, then validates that revision when a2a3 onboard runtime binaries are looked up at test/runtime startup.

Current scope

• Build metadata is written to build/lib/pto_isa_build.json after runtime builds complete.
• The recorded build revision is the actual PTO-ISA checkout HEAD, read with git rev-parse HEAD.
• Runtime validation is scoped to a2a3 onboard runtime lookup only.
• a5, a2a3sim, and a5sim are intentionally outside this check because the current metadata represents the a2a3 onboard host runtime PTO-ISA dependency.
• Runtime non-git PTO_ISA_ROOT falls back to explicit/default pin when possible; latest/HEAD without a concrete checkout remains an error.
• Build-time non-git PTO_ISA_ROOT remains unsupported because metadata would be unverifiable.

Follow-up items to track

• Decide whether future support is needed for headers-only / packaged PTO-ISA directories.
• If needed, design an explicit resolved-version source, such as PTO_ISA_ROOT/.pto_isa_commit or a build-time resolved commit override.
• If additional platforms start embedding PTO-ISA headers into prebuilt runtime binaries, extend metadata from one global a2a3-onboard record to per-platform or per-runtime records.
• Keep docs aligned with the actual build/run resolution order for PTO_ISA_ROOT, --pto-isa-commit, SIMPLER_PTO_ISA_COMMIT, and DEFAULT_PTO_ISA_COMMIT.

Related PR: #1096

[ChaoZheng109]

Triage decisions on the follow-up items:

1. Headers-only / packaged PTO-ISA directories — not supporting for now.
Keep the current behavior: PTO_ISA_ROOT must be a full pto-isa git checkout. Build-time non-git PTO_ISA_ROOT stays unsupported (metadata would be unverifiable); runtime non-git keeps falling back to the explicit/default pin. We don't have a concrete consumer that needs the headers-only/packaged form yet, so we won't add support speculatively.

2. Explicit resolved-version source (.pto_isa_commit / build-time override) — deferred with #1.
This is only the mechanism to make #1 work, so it's moot until #1 is revisited. If a real headers-only consumer shows up, we design this then.

3. Per-platform / per-runtime metadata — defer until a second platform actually embeds PTO-ISA headers into its prebuilt runtime.
Today only the a2a3 onboard host runtime carries the PTO-ISA dependency, so one global record is correct. We extend to per-platform/per-runtime records only when a5 (or another runtime) starts embedding PTO-ISA headers into its prebuilt binaries — condition-triggered, not now.

4. Documentation — yes, we will do this.
The full build/run resolution order across PTO_ISA_ROOT, --pto-isa-commit, SIMPLER_PTO_ISA_COMMIT, and DEFAULT_PTO_ISA_COMMIT (plus the build-time vs run-time distinction) currently lives only in the simpler_setup/pto_isa.py docstring. docs/getting-started.md covers basic PTO_ISA_ROOT setup but not the precedence. We'll document the complete precedence in the user docs and keep it aligned as the resolution logic changes. This is independent of #1/#2/#3 and can be done now.

Net: #1/#2 parked (no current need), #3 condition-gated on a future platform, #4 actionable now.

[vegetabledoww]

Documentation follow-up item 4 is tracked in PR #1118: #1118