Skip to content

build: centralize warm-build fast-path contract#196

Merged
zackees merged 2 commits intomainfrom
codex/issue-157-active
Apr 24, 2026
Merged

build: centralize warm-build fast-path contract#196
zackees merged 2 commits intomainfrom
codex/issue-157-active

Conversation

@zackees
Copy link
Copy Markdown
Member

@zackees zackees commented Apr 24, 2026

Summary

  • introduce a shared FastPathContract that owns warm-build fingerprint path, watched roots, and required artifacts
  • move fast-path reuse and persistence into shared helpers instead of open-coding them in each orchestrator
  • migrate AVR, ESP32, Teensy, RP2040, SAM, NRF52, and Renesas orchestrators onto the shared contract

Testing

  • cargo test -p fbuild-build fast_path -- --nocapture
  • cargo test -p fbuild-build orchestrator -- --nocapture

Closes #157.

Summary by CodeRabbit

  • Refactor
    • Consolidated build caching abstractions across microcontroller platforms (AVR, ESP32, NRF52, Renesas, RP2040, SAM, Teensy) to improve code consistency and maintainability. Build behavior and performance remain unchanged.

@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 24, 2026

Warning

Rate limit exceeded

@zackees has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 46 minutes and 1 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 46 minutes and 1 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: aa294b29-598b-4e4b-a3ae-953aa26d81cb

📥 Commits

Reviewing files that changed from the base of the PR and between c916995 and 26e218c.

📒 Files selected for processing (9)
  • crates/fbuild-build/src/avr/orchestrator.rs
  • crates/fbuild-build/src/build_fingerprint/fast_path.rs
  • crates/fbuild-build/src/build_fingerprint/mod.rs
  • crates/fbuild-build/src/esp32/orchestrator.rs
  • crates/fbuild-build/src/nrf52/orchestrator.rs
  • crates/fbuild-build/src/renesas/orchestrator.rs
  • crates/fbuild-build/src/rp2040/orchestrator.rs
  • crates/fbuild-build/src/sam/orchestrator.rs
  • crates/fbuild-build/src/teensy/orchestrator.rs
📝 Walkthrough

Walkthrough

This PR centralizes fast-path warm-build cache management across seven orchestrators (AVR, ESP32, NRF52, Renesas, RP2040, SAM, Teensy) by introducing a shared FastPathContract abstraction. Each orchestrator now declares required output artifacts and watches through the contract, uses typed FastPathCheckInputs and FastPathPersistInputs for cache operations, and delegates fingerprint persistence logic to a unified persist_fast_path_success helper, replacing ad-hoc orchestrator-specific implementations.

Changes

Cohort / File(s) Summary
Core Fast-Path API
crates/fbuild-build/src/build_fingerprint/fast_path.rs
Introduces FastPathContract to encapsulate fingerprint path, watch roots, and required output artifacts. Refactors fast_path_check to accept contract plus slimmer FastPathCheckInputs, and adds persist_fast_path_success helper with FastPathPersistInputs to handle fingerprint hashing, JSON writing, and zccache success marking.
Module Exports
crates/fbuild-build/src/build_fingerprint/mod.rs
Expands public re-exports to include persist_fast_path_success, FastPathCheckInputs, FastPathContract, and FastPathPersistInputs alongside existing fast-path types.
Documentation
crates/fbuild-build/src/build_fingerprint/README.md
Updates description of fast-path mechanism from orchestrator-extracted function to contract-based warm-build cache model; lists all supported platforms.
Orchestrator Refactoring
crates/fbuild-build/src/{avr,esp32,nrf52,renesas,rp2040,sam,teensy}/orchestrator.rs
Each orchestrator replaces ad-hoc watch collection and manual fingerprint persistence with FastPathContract-based workflow: derives expected artifacts, constructs contract, calls fast_path_check(&fast_path, &FastPathCheckInputs) for reuse decisions, and calls persist_fast_path_success(&fast_path, &FastPathPersistInputs) on successful builds. Tests updated to validate contract watches behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

Poem

🐰 A faster path contracts its way through the forest—
No more scattered watches, no more duplication!
One contract to bind them, from AVR to Renesas,
A unified cache that hops with efficiency.

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'build: centralize warm-build fast-path contract' accurately summarizes the main refactoring: introducing a shared FastPathContract abstraction and migrating all orchestrators to use it.
Linked Issues check ✅ Passed All requirements from issue #157 are met: a shared FastPathContract is introduced [fast_path.rs], all seven orchestrators are migrated to use it [avr, esp32, teensy, rp2040, sam, nrf52, renesas], and fingerprint lifecycle is centralized in persist_fast_path_success.
Out of Scope Changes check ✅ Passed All changes are directly scoped to centralizing the fast-path contract: new abstraction in fast_path.rs, orchestrator migrations, and documentation updates align with issue #157 objectives.
Docstring Coverage ✅ Passed Docstring coverage is 92.73% which is sufficient. The required threshold is 80.00%.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/issue-157-active

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

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (1)
crates/fbuild-build/src/renesas/orchestrator.rs (1)

62-71: Optional: the expected_fast_path_artifacts helper and its test are duplicated across orchestrators.

expected_fast_path_artifacts differs only in the firmware filename (firmware.bin here, firmware.hex in Teensy, etc.), and test_expected_fast_path_artifacts_follow_compile_db_location (lines 402-418) appears to be identical between orchestrators. Given the PR's objective to centralize the fast-path contract, this helper could move into build_fingerprint::fast_path (e.g. taking the firmware filename(s) as a parameter) to eliminate the per-platform copies and the redundant unit test.

Not blocking; pointed out because it's adjacent to the centralization work in this PR.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@crates/fbuild-build/src/renesas/orchestrator.rs` around lines 62 - 71, The
helper expected_fast_path_artifacts and its duplicate test should be
centralized: move the logic into build_fingerprint::fast_path as a function that
accepts the firmware filename(s) (e.g., "firmware.bin"/"firmware.hex") plus
build_dir and project_dir, and return the same tuple (elf, firmware, compile_db)
using CompileDatabase::expected_output_path; then update the
orchestrator-specific expected_fast_path_artifacts references to call the new
build_fingerprint::fast_path with the appropriate filename(s) and remove the
duplicated unit test
test_expected_fast_path_artifacts_follow_compile_db_location from
per-orchestrator modules, keeping a single shared test alongside the new helper.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@crates/fbuild-build/src/build_fingerprint/fast_path.rs`:
- Around line 136-149: add_default_watches currently skips adding the "dep_libs"
root when fast_path_watch returns None, causing missing-root state to be lost;
update add_watch_root (or fast_path_watch) so it always records a watch entry
even when the directory is absent: call fast_path_watch(cache_name,
&self.build_dir, root) and if it returns None, push a placeholder watch that
encodes "missing root" (e.g. Watch::missing_root or similar) into self.watches
instead of skipping; this preserves the root in add_default_watches for
"project" and "dep_libs" and lets the hash/check layer represent the absent-root
state.

In `@crates/fbuild-build/src/esp32/orchestrator.rs`:
- Around line 1256-1264: The call to
crate::build_fingerprint::persist_fast_path_success with FastPathPersistInputs
(using metadata_hash, link_result.size_info, params.watch_set_cache,
compiler_cache) must only run after the entire build (link/convert and any final
artifact writes) has completed successfully; move or gate this call so it
executes only on the successful build path (i.e., after the final link/convert
result is confirmed OK and no errors were returned), rather than unconditionally
where it currently runs.
- Around line 262-275: The fast-path contract currently built by
FastPathContract::for_project_outputs is missing the ESP32 side-output
boot_app0.bin, so add the corresponding fast_app0 (or similarly named artifact
token you already use elsewhere) into the list passed to
FastPathContract::for_project_outputs alongside fast_elf, fast_bin, fast_boot,
fast_parts, and fast_compile_db; ensure the symbol you add matches the variable
used when the cold path copies boot_app0.bin (so the contract and the copy refer
to the same artifact name) so warm fast-path hits will require/own boot_app0.bin
as well.

---

Nitpick comments:
In `@crates/fbuild-build/src/renesas/orchestrator.rs`:
- Around line 62-71: The helper expected_fast_path_artifacts and its duplicate
test should be centralized: move the logic into build_fingerprint::fast_path as
a function that accepts the firmware filename(s) (e.g.,
"firmware.bin"/"firmware.hex") plus build_dir and project_dir, and return the
same tuple (elf, firmware, compile_db) using
CompileDatabase::expected_output_path; then update the orchestrator-specific
expected_fast_path_artifacts references to call the new
build_fingerprint::fast_path with the appropriate filename(s) and remove the
duplicated unit test
test_expected_fast_path_artifacts_follow_compile_db_location from
per-orchestrator modules, keeping a single shared test alongside the new helper.
🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 5b0167f6-d234-43ca-b981-7870374083d3

📥 Commits

Reviewing files that changed from the base of the PR and between dab5a0c and c916995.

📒 Files selected for processing (10)
  • crates/fbuild-build/src/avr/orchestrator.rs
  • crates/fbuild-build/src/build_fingerprint/README.md
  • crates/fbuild-build/src/build_fingerprint/fast_path.rs
  • crates/fbuild-build/src/build_fingerprint/mod.rs
  • crates/fbuild-build/src/esp32/orchestrator.rs
  • crates/fbuild-build/src/nrf52/orchestrator.rs
  • crates/fbuild-build/src/renesas/orchestrator.rs
  • crates/fbuild-build/src/rp2040/orchestrator.rs
  • crates/fbuild-build/src/sam/orchestrator.rs
  • crates/fbuild-build/src/teensy/orchestrator.rs

Comment thread crates/fbuild-build/src/build_fingerprint/fast_path.rs Outdated
Comment thread crates/fbuild-build/src/esp32/orchestrator.rs
Comment thread crates/fbuild-build/src/esp32/orchestrator.rs Outdated
@zackees
Copy link
Copy Markdown
Member Author

zackees commented Apr 24, 2026

Addressed the review points in 26e218c.

Changes:

  • preserve missing-root fast-path watches in the shared contract so dep_libs absence is fingerprinted until the directory appears
  • centralize the repeated expected-artifact path helper into build_fingerprint::expected_fast_path_artifacts and remove the duplicated per-orchestrator compile-db-location tests
  • update ESP32 fast-path artifacts to include boot_app0.bin
  • only persist the ESP32 fast-path fingerprint once the final required artifact set actually exists after the boot-artifact phase

Validation:

  • cargo test -p fbuild-build fast_path -- --nocapture
  • cargo test -p fbuild-build orchestrator -- --nocapture

@zackees zackees merged commit 3cc09b8 into main Apr 24, 2026
76 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

build: centralize fast-path cache artifacts in a shared orchestrator contract

1 participant