Add manual-scope v0 to tensormap runtime

[uv-xiao]

Summary

• add a narrower manual_scope v0 model to tensormap_and_ringbuffer using the same submit APIs as AUTO mode
• introduce explicit same-scope dependencies through Arg.add_dep(task_id) instead of a new manual submit API family
• keep task publication at submit time; do not add delayed wiring, delayed linking, or a manual scope_end() replay barrier
• add manual-scope validation coverage, paged-attention manual-scope example variants, and the design note in docs/manual-scope-v0-design.md

Design Reference

The main design/reference document for this PR is:

• docs/manual-scope-v0-design.md

Constraints Of This Version

This PR intentionally stays narrow.

• PTO2_SCOPE() remains AUTO by default; PTO2_SCOPE(PTO2ScopeMode::MANUAL) enables manual scope
• submit APIs stay unchanged:
  • pto2_rt_submit_aic_task(...)
  • pto2_rt_submit_aiv_task(...)
  • pto2_rt_submit_task(...)
• explicit ordering is expressed only through Arg.add_dep(task_id)
• Arg.add_dep(...) is rejected outside manual scope
• nested manual scopes are rejected in v0
• no post-submit add_dependency(...)
• no delayed wiring / delayed linking / delayed publish path
• no manual-specific scope_end() dependency replay

Core Runtime Semantics

Inside manual scope, the runtime still publishes tasks immediately at submit time, like AUTO mode.

The additional v0 behavior is:

• read explicit deps from Arg
• validate that those deps belong to the current manual scope
• materialize them as ordinary fanins before publish
• classify tensor args by scope metadata to decide whether TensorMap lookup is still required

This keeps manual scope as a lightweight extension on top of normal PTO2 submit, not a separate graph-construction pipeline.

Where TensorMap Lookup Still Happens

Manual scope does not remove TensorMap entirely.

TensorMap lookup/insert still happens for:

• boundary tensors: external tensors, AUTO-scope tensors, outer-scope tensors, outer-manual-scope tensors
• modifier tensors: INOUT and OUTPUT_EXISTING

TensorMap lookup can be skipped only for producer-flow tensors that are:

• produced in the current manual scope, and
• already covered by explicit Arg.add_dep(...) ordering

That split is the key design point of v0.

Why alloc_tensors(...) Matters

alloc_tensors(...) stays output-only, but v0 treats allocation as a task and returns its task id together with the output tensors.

That matters because manual consumers can then depend on the allocation explicitly:

auto alloc = alloc_tensors(ci0, ci1);
Arg args;
args.add_dep(alloc.task_id());

This keeps the API light:

• no new alloc-specific manual API
• no delayed dependency wiring
• allocation still participates in manual ordering when needed

Important Limitation

V0 cannot express every same-scope chain using only Arg.add_dep(...).

The main gap is zero-output updater tasks.
They do not expose a returned task id handle, so repeated modifier chains like:

• update(i) -> update(i+1)

still need TensorMap publication / lookup on INOUT / OUTPUT_EXISTING tensors.

That is why this PR keeps TensorMap on the modifier path even inside manual scope.

Testing

Verified on this branch tip:

• ctest --test-dir tests/ut/cpp/build -R 'test_a2a3_pto2_manual_scope_(api|runtime)' --output-on-failure
• python -m pytest tests/st/a2a3/tensormap_and_ringbuffer/test_manual_scope_validation.py --platform a2a3sim --device 0 -q

The design note also records the broader validation / benchmark context used during development:

• docs/manual-scope-v0-design.md

[gemini-code-assist]

Code Review

This pull request introduces manual dependency tracking to the tensormap_and_ringbuffer runtime, allowing for a hybrid model where same-scope dependencies are explicitly defined while cross-scope relations continue to use TensorMap discovery. The implementation includes significant updates to the orchestrator and scheduler to handle deferred task publication and manual edge recording, as well as a repository-wide restructuring of examples and tests to follow a new {arch}/{runtime} directory convention. Review feedback correctly identified critical issues with bitmask widths and bitwise shifts that could lead to overflows when tracking more than 16 tensor arguments. Suggestions were also made to improve memory safety during buffer reallocation and to simplify logic using standard library functions.