fix: harden maximum-flow allocations (#2123)

[DecisionNerd]

Description

Harden the shared maximum-flow solution against allocation and size-overflow failures while preserving exact Edmonds-Karp behavior and the scalar/per-edge result contract.

Type of Change

• 🐛 Bug fix
• ♻️ Refactoring with no algorithm-semantic change
• ✅ Tests

Related Issues

Closes #2123

Changes Made

• replace input-sized allocations with checked fallible reservations
• validate canonical UUID-sorted projection before constructing residual state
• use checked adjacency degree/product arithmetic and structured atomic errors
• preserve scalar maximum flow and signed per-edge assignments from one shared solution

Testing

• Unit and regression tests updated
• Existing max-flow and min-cut behavior passes
• Required CI passes

CARGO_TARGET_DIR=/tmp/graphforge-target-2123 cargo test -p gf-exec --lib algorithm_paths_max_flow::tests
CARGO_TARGET_DIR=/tmp/graphforge-target-2123 cargo test -p gf-exec --lib algorithm_paths_min_cut::tests
CARGO_TARGET_DIR=/tmp/graphforge-target-2123 cargo check -p gf-exec
CARGO_TARGET_DIR=/tmp/graphforge-target-2123 cargo clippy -p gf-exec -- -D warnings
cargo fmt --all -- --check
git diff --check
cargo clean --target-dir /tmp/graphforge-target-2123

Checklist

• One focused executor file and one logical hardening change
• Root-cause allocation/overflow handling; no skips or suppression
• Self-reviewed and independently reviewed
• No public API, Arrow schema, algorithm semantics, or knowledge boundary changed
• Relevant local gates and required CI pass
• Contributing guidelines followed

Reviewer Notes

Focus on preserved residual-capacity/order semantics and error atomicity across every fallible reservation.

Summary by CodeRabbit

• Bug Fixes

  • Improved maximum-flow calculations with more deterministic results.
  • Added clearer handling for invalid capacities, endpoints, duplicate identifiers, and impossible graph sizes.
  • Improved resilience when memory or arithmetic limits are exceeded.

• Tests

  • Expanded coverage for graph size limits, reservation failures, and overflow scenarios.

[github-actions]

🏷️ Auto-labeled based on changed files:

• executor
• core

Labels are automatically applied based on which files were modified. You can add or remove labels as needed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 145fe335-7570-408b-a7c1-dafdd19493e1

📥 Commits

Reviewing files that changed from the base of the PR and between 54bfcd4 and d689c8c.

📒 Files selected for processing (1)

• crates/gf-exec/src/algorithm_paths_max_flow.rs

---

Walkthrough

The maximum-flow implementation now separates validation, residual graph construction, and Edmonds-Karp augmentation. It uses deterministic sorted lookups, checked sizing, fallible allocations, structured allocation errors, and expanded overflow and reservation tests.

Changes

Maximum-flow allocation hardening

Layer / File(s)	Summary
Flow validation and orchestration crates/gf-exec/src/algorithm_paths_max_flow.rs	maximum_flow now coordinates validated flow data, residual graph construction, augmentation, total flow calculation, and per-edge net flows using deterministic sorted UUID lookups.
Fallible residual graph and BFS crates/gf-exec/src/algorithm_paths_max_flow.rs	Residual adjacency construction, arc insertion, BFS state, and augmenting-path reconstruction use checked arithmetic and allocation-aware operations.
Structured allocation error coverage crates/gf-exec/src/algorithm_paths_max_flow.rs	Tests cover impossible node and edge reservations and adjacency-product overflow mappings.

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

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the max-flow allocation hardening work.
Description check	✅ Passed	The description matches the template well and includes the change summary, issue link, testing, checklist, and reviewer notes.
Linked Issues check	✅ Passed	The changes align with #2123 by hardening max-flow allocations, preserving semantics, and adding overflow/reservation regressions.
Out of Scope Changes check	✅ Passed	The PR stays scoped to algorithm_paths_max_flow.rs plus focused tests, with no clear unrelated code or API changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/2123-max-flow-allocations

---

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

[github-actions]

🏷️ Auto-labeled based on changed files:

• executor
• core

Labels are automatically applied based on which files were modified. You can add or remove labels as needed.

[github-actions]

🏷️ Auto-labeled based on changed files:

• executor
• core

Labels are automatically applied based on which files were modified. You can add or remove labels as needed.

[DecisionNerd]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[DecisionNerd]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[DecisionNerd]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.