Add: support dynamic Graph boundary scalars

[TaoZQY]

Summary

• Preserve Graph boundary scalar provenance and serialize current values as POD submission bindings.
• Refresh dynamic scalar slots during first materialization and affine replay while leaving static scalar slots unchanged.
• Keep construction config values in Graph cache identity and reject mutable boundary-derived values instead of replaying stale data.

Testing

• test_graph_cache: 8 passed
• C++ non-hardware test suite: 90 passed
• Graph Execution a2a3sim scenes: 3 passed, 1 deselected
• Full host_build_graph a2a3sim runtime sweep: 27 passed, 4 skipped
• Graph Execution a2a3 onboard via task-submit: 3 passed
• Manual Qwen3-14B three-layer Graph a2a3 onboard via task-submit: 1 passed
• Pre-commit checks for all changed files
  Close [Feature] hbg: Support dynamic boundary scalars in Graph Execution (Step 2) #1712

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a82462dc-3a21-4fbb-b001-1e7931fdff56

📥 Commits

Reviewing files that changed from the base of the PR and between 1f0f006 and eca540b.

📒 Files selected for processing (11)

• src/a2a3/runtime/host_build_graph/docs/GRAPH_EXECUTION.md
• src/a2a3/runtime/host_build_graph/host/runtime_maker.cpp
• src/a2a3/runtime/host_build_graph/orchestration/pto_orchestration_api.h
• src/a2a3/runtime/host_build_graph/runtime/graph_cache.h
• src/a2a3/runtime/host_build_graph/runtime/graph_execution.h
• src/a2a3/runtime/host_build_graph/runtime/orchestrator_core/pto_orchestrator.cpp
• src/a2a3/runtime/host_build_graph/runtime/pto_types.h
• src/a2a3/runtime/host_build_graph/runtime/scheduler/graph_execution.cpp
• tests/st/a2a3/host_build_graph/graph_execution/kernels/orchestration/graph_execution_orch.cpp
• tests/st/a2a3/host_build_graph/graph_execution/test_graph_execution.py
• tests/ut/cpp/a2a3/test_graph_cache.cpp

---

📝 Walkthrough

Walkthrough

Graph execution now supports dynamic boundary scalars. Scalar provenance is recorded in graph definitions, submitted separately, materialized with validation, and refreshed during affine replay. Cacheability, storage sizing, orchestration, documentation, and tests now cover scalar bindings.

Changes

Dynamic boundary scalar execution

Layer / File(s)	Summary
Scalar contracts and provenance src/a2a3/runtime/host_build_graph/runtime/graph_execution.h, src/a2a3/runtime/host_build_graph/runtime/pto_types.h, src/a2a3/runtime/host_build_graph/runtime/graph_cache.h, src/a2a3/runtime/host_build_graph/orchestration/pto_orchestration_api.h	Graph wire structures and execution storage now include scalar sources, boundary counts, scalar payloads, and scalar patches. Arg preserves scalar provenance and tracks invalidation.
Recording and submission serialization src/a2a3/runtime/host_build_graph/runtime/orchestrator_core/pto_orchestrator.cpp	Graph recording classifies static, boundary, and invalidated scalar sources. Graph definitions serialize scalar metadata, and submissions carry boundary scalar payloads with count validation.
Execution storage and scalar replay src/a2a3/runtime/host_build_graph/runtime/scheduler/graph_execution.cpp, src/a2a3/runtime/host_build_graph/host/runtime_maker.cpp	Execution storage accounts for scalar patches. Materialization resolves scalar sources and records boundary patches. Affine replay reapplies updated boundary values.
Documentation and validation src/a2a3/runtime/host_build_graph/docs/GRAPH_EXECUTION.md, tests/ut/cpp/a2a3/test_graph_cache.cpp, tests/st/a2a3/host_build_graph/graph_execution/*	Documentation and tests cover dynamic scalar forwarding, cacheability, provenance invalidation, storage layout, materialization, and replay.
Estimated code review effort: 4 (Complex)	~45 minutes

Possibly related issues

• [Feature] hbg: Support dynamic boundary scalars in Graph Execution (Step 2) #1712 — Directly covers dynamic boundary scalar support, provenance tracking, cacheability, patching, and replay.

Possibly related PRs

• hw-native-sys/simpler#1444 — Introduced the graph execution paths extended here.
• hw-native-sys/simpler#1731 — Shares the graph recording, submission, caching, replay, and documentation paths.
• hw-native-sys/simpler#1733 — Ports related graph execution infrastructure to A5.

Poem

A rabbit hops through scalar streams,
Patching graphs with changing dreams.
Static values stay in place,
Boundary values change their trace.
Replay thumps with careful cheer:
Fresh scalar bindings now appear.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 13.33% 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
Title check	✅ Passed	The title clearly and concisely identifies the main change: support for dynamic Graph boundary scalars.
Description check	✅ Passed	The description directly explains dynamic boundary scalar support, replay behavior, cache identity, rejection rules, and testing.
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.

---

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

[ChaoZheng109]

建议:放宽"边界 scalar 传了必须全部被绑定"这条约束

graph_build_definition(pto_orchestrator.cpp:621-627)会在任一边界 scalar 未被内部 task 绑定时判定整图不可缓存:

recording.boundary_scalar_used.size() != recording.boundary_args->scalar_count() ||
std::any_of(boundary_scalar_used.begin(), boundary_scalar_used.end(),
            [](bool used) { return !used; }) ||

失败后在 graph_end(:1704-1706)走:

debug_assert(false && "The recorded Graph contains a construct that Graph Execution does not support");
LOG_WARN("[GraphExecution] unsupported construct observed; definition was not cached");
return;

即 debug 构建直接 assert 中止,release 退回普通提交、永不缓存。

问题:这条"传了必须全用"缺乏既有惯例支撑,且与本特性内部不一致。

1. 普通 submit_task(L0) 只校验 has_error / active_mask / count,对"scalar 是否被 kernel 读到"无任何校验——kernel 独立编译,主机侧也无从判断。未使用的 arg 一律容忍。
2. L2 aicpu_orchestration_entry(const ChipTaskArgs&) 是纯用户函数,框架不强制入参被全部下发。
3. Graph 自己的边界 tensor 也容忍未使用:代码里只有 boundary_scalar_used(:316),没有 boundary_tensor_used;一个未被任何节点消费的边界 tensor 照样进签名、照常缓存。

于是出现同一特性内部的不对称:边界 tensor 传了不用没事,边界 scalar 传了不用就 assert。而技术上,一个未绑定的边界 scalar 与一个未消费的边界 tensor 等价——都只是 wire 镜像里的一份 dead data,不构成正确性风险。

建议放宽为:未被任何内部 task 绑定的边界 scalar 直接当静态数据处理 / 忽略,对齐边界 tensor 的行为,不再据此拒绝缓存,也移除 graph_end 中的 debug_assert(false) 中止。

这么做的收益:允许"为统一不同 variant 的边界签名而携带某些 variant 用不到的 scalar"这类合理写法;避免调用方在 debug 下因为多传一个暂未使用的 scalar 而被 assert 打断,却无法从当前文档(GRAPH_EXECUTION.md:329-341 的 debug-assert 清单里并未列出这一条)预知。

[TaoZQY]

@ChaoZheng109 Addressed the latest feedback:

• Unused boundary scalars are now allowed and create no internal scalar patches.
• Added a regression where an unused boundary scalar changes across cache hits.
• Documented the host-derived scalar provenance limitation and safe alternatives.