Fix: align hbg docs/comments with the polling runtime model

[ChaoZheng109]

Summary

host_build_graph's dependency model was migrated from the wiring/refcount model (fanout_refcount + scope refcount + CONSUMED-via-refcount) to the polling model (completion_flags + per-ring completed_watermark), and the runtime is whole-graph-resident (the orchestrator runs to completion on the host; last_task_alive is never advanced at runtime). Several docs and load-bearing comments still described the removed model. Documentation/comment-only — no behavior change. All replacement facts were verified against the current source, not taken from the issue text.

Three facets from #1646, all confined to src/a2a3/runtime/host_build_graph/:

1. Removed refcount mechanism presented as current — retarget the seven present-tense references from fanout_refcount/fanout_count to the real consumer-retirement signal: per-ring completed_watermark >= producer's last_consumer_local_id (SCALAR_DATA_ACCESS.md §3.2/§4/§5, RUNTIME_LOGIC.md state machine, pto_orchestration_api.h, pto_runtime2_types.h, pto_runtime2.cpp). Correct the prepare_task zeroed-fields comment to the fields reset_for_reuse() actually clears (wake_list_head / next_in_wake_list / any_subtask_deferred / completed_subtasks / next_block_idx). The correct historical/contrast notes are left intact.
2. SCALAR_DATA_ACCESS.md §1 claimed a capability hbg lacks — scope it: the orchestrator finishes on the host before any device task runs, so a producer's task_state can never reach COMPLETED during orchestration; get/set_tensor_data are safe only on producer-less tensors (external / initial-value), and reading a produced result mid-graph is a tensormap_and_ringbuffer capability that times out here.
3. RUNTIME_LOGIC.md §4.5 sizing guidance + default — rewrite the deadlock section to the current model: whole-graph residency means the window must hold the whole graph's task count (not the largest scope), and a too-small window trips the 500 ms wall-clock backstop (report_deadlock); replace the stale Flow Control Deadlock FATAL/BLOCKED sample text the code no longer emits, and fix the task_window default (65536 → 16384, matching #define PTO2_TASK_WINDOW_SIZE 16384). This aligns §4.5 with the already-correct §8.4.

Scope

Per agreement on the issue, facet 3 fixes the sizing guidance and reconciles §4.5's stale root-cause/FATAL text (one coherent unit). §4.1–§4.4's broader last_task_alive reclaim narrative (L209–259) is intentionally left for a follow-up, as is the residue outside host_build_graph (tensormap_and_ringbuffer, top-level docs/, a5) that #1646 did not sweep.

Testing

Documentation and comment-only; no compiled behavior changes.

• All pre-commit hooks pass (check-headers, clang-format, clang-tidy, cpplint, markdownlint)
• Residue probe confirms the seven fixed refs are gone and the historical notes remain
• Edited docs cross-checked against §8.4 for internal consistency

Fixes #1646

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 627bb188-22bb-4913-8ed9-b9f014f130b6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The PR updates host-build-graph documentation and runtime comments. It documents whole-graph task residency, task-window sizing, restricted scalar access, and completed-watermark consumer tracking. No executable behavior or public declarations change.

Changes

Host Build Graph Documentation

Layer / File(s)	Summary
Graph residency and sizing guidance src/a2a3/runtime/host_build_graph/docs/RUNTIME_LOGIC.md	Documents whole-graph task residency, deadlock diagnostics, task-window sizing, and the default TensorMap capacity example.
Scalar access and completion tracking src/a2a3/runtime/host_build_graph/docs/SCALAR_DATA_ACCESS.md, src/a2a3/runtime/host_build_graph/orchestration/pto_orchestration_api.h, src/a2a3/runtime/host_build_graph/runtime/...	Documents task-free scalar access, InCore-result boundaries, completed-watermark waits, and updated task-state comments.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related issues

• hw-native-sys/simpler issue 1646: It directly covers replacing obsolete fanout_refcount semantics and correcting host-build-graph sizing and scalar-access guidance.

Possibly related PRs

• hw-native-sys/simpler#1444: Updates related task-consumption and completion documentation in the same runtime areas.
• hw-native-sys/simpler#1536: Implements or refactors the completed_watermark completion tracking described here.
• hw-native-sys/simpler#1618: Updates related completion-watermark and task-retirement semantics in overlapping files.

Poem

A rabbit reads the watermark bright,
No fanout ghosts remain in sight.
Tasks stay resident, windows guide,
Scalar waits know when to hide.
Clearer graphs now bound the night.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: aligning host_build_graph documentation and comments with the polling runtime model.
Description check	✅ Passed	The description directly explains the documentation and comment updates, their scope, runtime model, and validation performed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/a2a3/runtime/host_build_graph/docs/RUNTIME_LOGIC.md`:
- Around line 263-290: Update
src/a2a3/runtime/host_build_graph/docs/RUNTIME_LOGIC.md lines 263-290 to reflect
that allocation blocks on the 16th task with task_window=16 and cannot reach the
208-task example while last_alive remains 0; preserve the no-reclaim sizing
guidance. Update src/a2a3/runtime/host_build_graph/docs/RUNTIME_LOGIC.md line
352 to size TensorMap capacity using total_tasks × avg_outputs_per_task, and
remove the claim that smaller windows trigger frequent cleanup.

In `@src/a2a3/runtime/host_build_graph/docs/SCALAR_DATA_ACCESS.md`:
- Around line 5-10: Update Section 5’s scalar-access example to comply with the
host_build_graph restriction: remove the producing add_output tensor and
orchestration-side completion wait, or rewrite the example using a producer-less
external or initial-value tensor without submitting a producing task. If
retaining the producer-based example, move it to the tensormap_and_ringbuffer
documentation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 66fd0777-70a1-4232-bd0c-6de18876df44

📥 Commits

Reviewing files that changed from the base of the PR and between c975b61 and aba08a4.

📒 Files selected for processing (6)

• src/a2a3/runtime/host_build_graph/docs/RUNTIME_LOGIC.md
• src/a2a3/runtime/host_build_graph/docs/SCALAR_DATA_ACCESS.md
• src/a2a3/runtime/host_build_graph/orchestration/pto_orchestration_api.h
• src/a2a3/runtime/host_build_graph/runtime/orchestrator_core/pto_orchestrator.cpp
• src/a2a3/runtime/host_build_graph/runtime/orchestrator_core/pto_runtime2.cpp
• src/a2a3/runtime/host_build_graph/runtime/pto_runtime2_types.h