Add Graph Execution to host_build_graph

[TaoZQY]

Summary

• add Graph Execution to the a2a3 host_build_graph runtime;
• record a repeated C/V/MIX/Dummy task DAG once, including topological order,
  fanin/fanout, roots, argument sources, and static scalars;
• submit one GRAPH task from the host Orchestrator on a cache hit, then let
  the device Scheduler materialize and execute the saved topology;
• carry dynamic tensors and scalars through the existing L2TaskArgs API,
  without public GraphBindings, Patch, or GraphArgs types;
• upload only the compact definition plus current args, and reuse bounded host
  submission and graph-affine AICPU execution pools;
• expose Host Orchestrator, Graph Execution, and graph_prepare DFX lanes;
• add simulation coverage, converter unit tests, API documentation, and a
  Qwen3-14B-style upstream integration example.

Execution flow

1. First structurally compatible invocation: execute the Graph function through
   ordinary task submits and save the complete DAG definition.
2. Later invocation: the host submits one outer GRAPH descriptor containing a
   compact definition and the current L2TaskArgs values.
3. The Scheduler acquires an AICPU-local execution block, prepares four nodes
   per scheduling slice, activates the saved roots, and releases saved fanout
   edges as nodes complete.
4. The outer Graph task completes only after all internal nodes retire, so its
   downstream dependencies retain normal task semantics.

Upstream API: Qwen decoder layer

void qwen_decoder_layer(const L2TaskArgs &args) {
    const Tensor &hidden = args.tensor(0).ref();
    const Tensor &weight = args.tensor(1).ref();
    const Tensor &output = args.tensor(2).ref();

    L0TaskArgs task_args;
    task_args.add_input(hidden, weight);
    task_args.add_output(output);
    task_args.add_scalar(args.scalar(0));  // dynamic layer_id
    task_args.add_scalar(args.scalar(1));  // dynamic token_position
    task_args.add_scalar(uint32_t{16});    // static Graph-definition value
    rt_submit_aic_task(FUNC_MATMUL, task_args);
}

void submit_qwen_decoder_layer(const L2TaskArgs &args) {
    rt_submit_graph(&qwen_decoder_layer, args);
}

The caller packages hidden state, weights, output, layer_id, and
token_position into L2TaskArgs; the wrapper does not repeat them in its
signature. The function pointer is the Graph ID for structurally identical
layers. Tensor addresses and scalar values may change; tensor shape, dtype,
stride, size, direction, and task topology must remain compatible. See
GRAPH_EXECUTION.md
for the complete three-layer Qwen-style example and current limitations.

Scope

• exactly one commit on top of upstream/main;
• Graph Execution behavior is confined to a2a3 host_build_graph;
• shared platform/converter changes carry the new DFX records;
• tensormap_and_ringbuffer changes are API-plumbing compatibility and two
  predicate-field build fixes, not Graph Execution enablement.

Testing

• all pre-commit hooks on changed files;
• python simpler_setup/build_runtimes.py --platforms a2a3sim a5sim;
• Graph Execution on a2a3sim: 1 passed;
• swimlane converter unit tests: 24 passed;
• full a2a3 host_build_graph simulation: 12 passed, 1 deselected;
• Qwen3-14B three-layer Graph Execution onboard run;
• generated Perfetto trace contains cache-miss task_submit, cache-hit
  graph_submit, Scheduler graph_prepare, and Graph Execution lanes.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds host-side graph capture and replay for host_build_graph, including cache-key generation, graph execution storage, device upload, graph-aware scheduling, scalar provenance, documentation, and an end-to-end record/replay test.

Changes

Graph Execution Runtime

Layer / File(s)	Summary
Graph contracts and submission API src/a2a3/runtime/host_build_graph/runtime/pto_graph_cache.h, src/a2a3/runtime/host_build_graph/runtime/pto_types.h, src/a2a3/runtime/host_build_graph/orchestration/pto_orchestration_api.h, src/a2a3/runtime/host_build_graph/runtime/pto_runtime2*.h, src/a2a3/runtime/host_build_graph/runtime/pto_orchestrator.h	Adds cache keys, cacheability checks, scalar provenance, graph task metadata, runtime graph callbacks, and rt_submit_graph wrappers.
Graph capture and replay construction src/a2a3/runtime/host_build_graph/runtime/orchestrator_core/pto_orchestrator.cpp	Records task topology and tensor/scalar sources, builds cached definitions, submits replay executions, and materializes graph nodes.
Execution storage and device upload src/a2a3/runtime/host_build_graph/runtime/pto_graph_execution.*, src/a2a3/runtime/host_build_graph/host/runtime_maker.cpp	Adds pooled execution images, lifecycle state transitions, pointer relocation, pending graph uploads, and device buffer ownership.
Graph scheduling and completion src/a2a3/runtime/host_build_graph/runtime/scheduler/*, src/a2a3/runtime/host_build_graph/runtime/shared/pto_runtime2_init.cpp	Adds graph queues, sliced preparation and activation, graph-node fanout handling, and stream-aware completion accounting.
Graph execution test and documentation src/a2a3/runtime/host_build_graph/docs/GRAPH_EXECUTION.md, tests/st/a2a3/host_build_graph/graph_execution/*	Documents graph capture/replay semantics and adds an end-to-end orchestration test with dynamic and fixed scalars.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related PRs

• hw-native-sys/simpler#1379: Shares host graph runtime operations and scheduler publication paths.
• hw-native-sys/simpler#1415: Overlaps the scheduler task-state and synchronization paths.
• hw-native-sys/simpler#1435: Overlaps scheduler completion and dispatch accounting.

Poem

A bunny hops through cached graphs,
With tensor trails and scalar tags.
Roots wake up, then nodes race,
Uploading dreams to device space.
The DAG remembers every way—
And replays hops another day.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.47% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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 is concise and accurately summarizes the main change: adding Graph Execution to host_build_graph.
Description check	✅ Passed	The description is clearly aligned with the changeset and explains the Graph Execution workflow, scope, and testing.

---

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