Fix: adapt host build graph swimlane clock alignment

[indigo1973]

Fix: adapt host build graph swimlane clock alignment

Support host_build_graph swimlane captures containing Host records, including
level-4 captures and level-3 captures with Host phase recording enabled.
Align Host Orchestrator and device records on a bounded timeline, and store
the mapping in the source JSON for converters and IDE readers.

• Read versioned Scheduler streams, include all device producers in the
  containment extent, and join AICPU streams to logged scheduler phases.
  Name AICore Scheduler lanes by worker ID to match Worker View.
• Emit invocation-correlated AICPU-launch markers at TIMING and use them
  to constrain device placement within the Host runner window.
• Export host_clock_alignment..log beside each eligible capture during
  native finalize, covering direct L2 calls and persistent ChipWorker runs.
  Read the cumulative log tail from the invocation's starting offset,
  filter by PID and invocation, flush the process logger, and publish the
  capture-local timing log atomically before run completion.
• Keep the live Host logger bound to its first configured directory. Support
  flushing through runtime DSOs borrowing the process logger, and flush
  ChipWorker logs before task completion when chip-swimlane is enabled.
• Match capture invocations using dispatch identities, Host PIDs, and
  Host-record bounds, including zero synchronous dispatch IDs.
• Store alignment status, device/Host anchors, and allowed Host bounds in
  metadata.clock_alignment while preserving raw timestamps and formatting.
  Reuse valid mappings and recalculate when explicit Host logs are supplied.
• Apply alignment during single-file conversion and directory merging.
  Warn on missing or ambiguous inputs and retain unaligned diagnostic views.
  Support full-log inputs for general multi-rank containment.
• Bind ST log drains to a pytest session directory so temporary capture
  cleanup and per-test retention policies cannot remove the active log sink.
  Use the native monotonic clock for ST log filtering.
• Document the source schema, profiling behavior, and log lifecycle. Keep
  internal join residuals in cycles and serialize them in nanoseconds.

Validation:

• Focused Python alignment, converter, Worker, SceneTest, and trace API UT.
• C++ logger tests, including cross-DSO flushing, and applicable pre-commit.
• A5 level-4 and level-3 Host-enabled direct L2 and persistent ChipWorker ST;
  level-3 Device-only captures produce no compact timing log.
• Consecutive captures with dependency generation and temporary-directory
  cleanup: complete markers, distinct invocations, and bounded conversion.

Co-authored-by: majin0824 majin15@huawei.com

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: f95960e4-05d7-46c4-8d94-f3a2c705aade

📥 Commits

Reviewing files that changed from the base of the PR and between 8414356 and 9ccb5e7.

📒 Files selected for processing (10)

• docs/dfx/chip-swimlane-profiling.md
• simpler_setup/scene_test.py
• simpler_setup/tools/README.md
• simpler_setup/tools/containment.py
• simpler_setup/tools/swimlane_converter.py
• src/a2a3/runtime/host_build_graph/docs/profiling_levels.md
• src/a5/runtime/host_build_graph/docs/profiling_levels.md
• tests/ut/py/test_clock_alignment.py
• tests/ut/py/test_containment.py
• tests/ut/py/test_swimlane_converter.py

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds persisted Host/device clock alignment for eligible single-file captures. It adds scheduler-stream containment, alignment metadata and fallback behavior, updated profiling documentation, diagnostic logging, and tests for legacy, HBG, device-only, and invalid-input cases.

Changes

Host/device clock alignment

Layer / File(s)	Summary
Alignment behavior and profiling contracts docs/dfx/chip-swimlane-profiling.md, simpler_setup/tools/README.md, src/a2a3/runtime/host_build_graph/docs/profiling_levels.md, src/a5/runtime/host_build_graph/docs/profiling_levels.md	The documentation describes Host/device alignment, persisted mappings, Host-log handling, and Host lane availability at profiling levels 3 and 4.
Scheduler stream containment simpler_setup/tools/containment.py, tests/ut/py/test_containment.py	Containment reads versioned scheduler_records streams with legacy fallback. Only AICPU records bound the sched join window, while other producers extend the capture extent.
Single-capture alignment flow simpler_setup/tools/swimlane_converter.py, simpler_setup/scene_test.py, simpler_setup/tools/README.md	The converter validates, persists, reuses, and applies clock mappings. It reports alignment metadata, preserves raw timestamps, and logs non-empty successful subprocess stderr at warning level.
Alignment and conversion validation tests/ut/py/test_clock_alignment.py, tests/ut/py/test_swimlane_converter.py	Tests cover mapping reuse and invalidation, fallback behavior, legacy inputs, diagnostic output, device-only conversion, HBG sources, scheduler streams, and explicit rank mappings.

Priority: ⬇️ Low

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant Capture as Single-file capture
  participant Converter as swimlane_converter
  participant Logs as Host logs
  participant Metadata as metadata.clock_alignment
  Capture->>Converter: Prepare or reuse alignment
  Converter->>Logs: Match Host records when no valid saved mapping exists
  Logs-->>Converter: Host anchors and timing bounds
  Converter->>Metadata: Persist validated mapping atomically
  Converter-->>Capture: Decode with aligned or fallback timestamps

Loading

Merge Risk: ⚪ Minimal · up to 9ccb5

The alignment, containment, fallback, and persistence paths have corresponding validation coverage, with no actionable merge-blocking issue identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 6 files. (4 skipped: …	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 directly identifies the main change: adapting host build graph swimlane clock alignment. It is concise and specific.
Description check	✅ Passed	The description clearly explains the Host/device timeline alignment, persisted mappings, scheduler stream handling, fallback behavior, documentation, and validation. It is directly related to the chan…

Full details: Docstring Coverage

Explanation

Docstring coverage is 31.11% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 45 functions across 6 files. (4 skipped: 4 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

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

_{A rabbit checks the clocks at dawn
Host and device lines align
Scheduler streams mark the path
Saved bounds remain in time
Logs may guide the mapping
And tests guard every sign}

_{Comment @coderabbitai help to get the list of available commands.}