Docs: state the launched invariant in simpler_finalize_run

[ChaoWao]

Fixes #1742.

What the issue asked for

launched in simpler_finalize_run was redefined from phase != NativeRunPhase::Prepared to state->active_execution != nullptr by #1694, and the invariant behind it was never written down — not in a comment, not in either #1694's or #1725's commit message. The new definition is correct; the problem is that a future regression on this path has nothing to git bisect back to, and the next reader has to re-derive it.

What the invariant actually is

I traced it rather than paraphrasing the issue. launch_execution populates active only when the transaction reached the device:

// src/a2a3/platform/onboard/host/device_runner.cpp
if (transaction.progress == LaunchProgress::NotStarted) {
    outcome.prepared = std::move(prepared);          // active stays null
} else {                                             // Partial or Complete
    outcome.active = std::make_unique<ActiveExecution>(std::move(prepared), transaction.progress);
}

So a null active_execution is exactly a run that never touched a stream — which is why it should take the -1 / set_gm_sm_ptr(nullptr) path rather than being treated as launched. The sim runner has the same rule (device_runner.cpp:494-496), so both copies get the same comment.

The change

A comment at the definition in both c_api_shared.cpp variants, stating the present-tense fact per comments.md — no reference to #1694 or to the edit that produced it, since that belongs in the commit message and not the code.

Comment only. No behavior change; the diff is 12 added lines, zero modified.

One thing I got wrong mid-way and corrected: my first draft said launched "decides all four uses below". Enumerating them found five (:876, :894, :898, :900, :938). The comment now states the invariant instead of counting call sites, which is both accurate and won't rot when a sixth appears.

Validation

Comment-only, so this is really just proving nothing else moved:

• 91/91 cpp UT (ctest -LE requires_hardware)
• 1277 passed / 13 skipped — full tests/ut/py
• a2a3 onboard sweep: 54 passed, plus 24 passed / 2 skipped in the resource phase
• git diff --stat is +12 / -0 across the two files — pure addition, no reformatting churn

[coderabbitai]

Warning

Review limit reached

@ChaoWao, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 24 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 78c7bb5d-96de-41e6-b879-b776d8e235db

📥 Commits

Reviewing files that changed from the base of the PR and between e03c84a and 6eef3a7.

📒 Files selected for processing (2)

• src/common/platform/onboard/host/c_api_shared.cpp
• src/common/platform/sim/host/c_api_shared.cpp

---

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