build: centralize warm-build fast-path contract

[zackees]

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]

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

• perf(build): extend watch-set fingerprint fast-path to AVR orchestrator #136: Introduced the original fast-path infrastructure that this PR refactors and extends with the new FastPathContract abstraction across all orchestrators.
• Add RP2040 warm-build fast path #159: Added RP2040 fast-path support with watch collection and persistence logic that this PR consolidates into the shared contract-based API.

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

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

[zackees]

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