fix(foundations): reserve can fail even with +16 flag set

[novusnota]

Closes #2002. Also, adjusts the wording on the /foundations/messages/internal#bounce page a little.

Summary by CodeRabbit

Documentation

• Refined reserve action documentation clarifying error handling and bounce phase behavior with improved descriptions of transaction failure processing.
• Updated bounce eligibility conditions for compute and action phase failures with enhanced precision and accuracy.
• Expanded documentation examples demonstrating bounce behavior across different message and reservation modes.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
mintlify-ton-docs	🟢 Ready	View Preview	Mar 24, 2026, 4:26 PM

[github-actions]

Thanks for the clear update to foundations/actions/reserve.mdx: I have one inline suggestion to align the bounce-phase description with the actual behavior, so please apply the inline suggestion.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation clarifications for reserve action failure behavior and bounce eligibility conditions. Changes include refining algorithm descriptions, updating notation to literal values, and expanding examples with explicit flag references for error handling scenarios.

Changes

Cohort / File(s)	Summary
Reserve Action Documentation foundations/actions/reserve.mdx	Refined algorithm description for ReserveBounceIfActionFail mode to clarify that failed reserve actions enter the bounce phase. Updated original_balance documentation to use literal 0 instead of $0$ notation. Clarified error handling for flag +16 to explicitly equate it with ReserveBounceIfActionFail.
Internal Messages Documentation foundations/messages/internal.mdx	Updated bounce eligibility conditions to specify contract errors (not message errors) during compute phase failures when state is not committed. Refined action phase failure case to reference +16 flag enablement. Expanded examples with SendBounceIfActionFail for messages and ReserveBounceIfActionFail for reservations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Bounce and Reserve, now clearer they be,
With +16 flags and 0 without fee,
The docs hop along with precision so bright,
Action phases gleam, error modes set right! 🎉

🚥 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 directly describes the main issue being fixed: clarifying that reserve actions can fail even with the +16 flag set, which is the core problem addressed in the linked issue #2002.
Linked Issues check	✅ Passed	The PR successfully addresses the requirement from issue #2002 by updating documentation to clarify that reserve actions fail (not skip) when the +16 flag is set, with error codes handled like other actions.
Out of Scope Changes check	✅ Passed	All changes are scoped to documentation updates in reserve.mdx and internal.mdx files directly addressing the reserve failure behavior clarification and bounce eligibility conditions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ 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 2002-reserve-fix

---

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]

🧹 Nitpick comments (1)

foundations/actions/reserve.mdx (1)

41-42: Minor wording inconsistency with line 88.

Line 42 uses "the bounce phase is initiated" while line 88 uses "the transaction enters the bounce phase." Consider using consistent phrasing across both locations for clarity.

📝 Suggested wording for consistency

 1. Check that `mode` has flag `ReserveBounceIfActionFail`:
-   - if so, then in case of any failure during reservation, the [bounce phase](/foundations/phases#bounce-phase) is initiated.
+   - if so, then in case of any failure during reservation, the transaction enters the [bounce phase](/foundations/phases#bounce-phase).

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@foundations/actions/reserve.mdx` around lines 41 - 42, Replace the wording at
the first occurrence ("the bounce phase is initiated") to match the phrasing
used on line 88 ("the transaction enters the bounce phase") for consistency;
update the sentence describing the behavior when `mode` has the
`ReserveBounceIfActionFail` flag so it reads that the transaction enters the
bounce phase on any reservation failure, keeping the same terminology
`ReserveBounceIfActionFail` and "bounce phase" to locate the sentence in
reserve.mdx.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@foundations/actions/reserve.mdx`:
- Around line 41-42: Replace the wording at the first occurrence ("the bounce
phase is initiated") to match the phrasing used on line 88 ("the transaction
enters the bounce phase") for consistency; update the sentence describing the
behavior when `mode` has the `ReserveBounceIfActionFail` flag so it reads that
the transaction enters the bounce phase on any reservation failure, keeping the
same terminology `ReserveBounceIfActionFail` and "bounce phase" to locate the
sentence in reserve.mdx.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 01884086-b696-45d5-b436-ce2226b3fac7

📥 Commits

Reviewing files that changed from the base of the PR and between cd5eb42 and 8947a8a.

📒 Files selected for processing (2)

• foundations/actions/reserve.mdx
• foundations/messages/internal.mdx