[DecisionNerd]

Implements #545: serial disposition for max_flow.

Closes #545

  

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Note

Add serial disposition for paths(by="max_flow") to the M4 entry baseline

• Adds a run_paths_max_flow workload to the M4 entry harness that runs GraphForge::paths with PathAlgorithm::MaxFlow, asserts determinism across two runs, and records fingerprint evidence.
• Documents in execution-resource-policy.md that max-flow uses serial Edmonds–Karp augmentations across all thread configurations due to residual graph mutation and fingerprint stability concerns.
• Registers "paths-max-flow" in the CI matrix script and contract JSON with disposition: serial_edmonds_karp_augmenting_paths and short_ci: true.

^{Macroscope summarized 1679ecc.}

Summary by CodeRabbit

• New Features

  • Added a deterministic maximum-flow workload for validating directed, capacity-weighted paths from Alice to Dave.
  • Included evidence metadata and repeatability checks for consistent results.

• Bug Fixes

  • Updated the GraphForge paths contract to use the Edmonds–Karp maximum-flow algorithm.

• Tests

  • Added the workload to short continuous-integration and manual coverage matrices.
  • Added checks for expected workload ordering, registration, and deterministic execution.
  • Documented that maximum-flow views remain serial for stable results.

[coderabbitai]

Walkthrough

The PR adds a deterministic paths-max-flow baseline workload, records Max-Flow evidence, documents serial Edmonds-Karp execution, and updates M4 workload matrices and contract validation.

Changes

Max-flow workload

Layer / File(s)	Summary
Workload execution and evidence crates/graphforge-api/tests/m4_entry_baseline.rs, crates/graphforge-exec/src/algorithm_paths_max_flow.rs	The baseline runs the directed Alice-to-Dave Max-Flow query twice, verifies deterministic results, records a fingerprint, and describes serial residual-graph execution.
M4 matrix and contract registration crates/graphforge-api/tests/m4_entry_baseline.rs, scripts/ci/m4-entry-matrix.py, tests/contracts/m4-entry-matrix.json	The short CI matrix, expected workload list, required workload IDs, and contract entry now include paths-max-flow.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related issues

• perf(exec): polish scale/performance for paths(by="max_flow_edges") #546 — Concerns the same paths-max-flow workload and its serial execution and deterministic evidence requirements.
• perf(exec): polish scale/performance for paths(by="min_cut") #549 — Covers a related serial max-flow workload classification in the M4 matrix.

Possibly related PRs

• CurateLabs/graphforge#485 — Introduced the M4 baseline harness and contract extended by this PR.
• CurateLabs/graphforge#660 — Adds and documents another serial GraphForge::paths workload in the M4 matrix.
• CurateLabs/graphforge#645 — Documents serial execution for a graph algorithm with shared mutable state.

Suggested labels: ci-cd

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description states the main change and linked issue, but it omits most required template sections, including type, testing, checklist, and performance details.	Complete the template with the change type, testing and coverage, commands run, checklist items, performance impact, breaking-change status, and reviewer notes.
Linked Issues check	❓ Inconclusive	The summary confirms serial documentation and deterministic evidence, but it does not verify cancellation, limits, CSR/Arrow gates, full performance evidence, or exact-head CI.	Provide reviewable evidence for cancellation and limits, CSR/Arrow compliance, workload metrics, and exact-head CI; review the excluded execution-resource policy documentation separately.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	All reviewed changes support issue #545 by documenting serial max-flow behavior and updating workload tests, CI validation, and contract expectations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly and concisely identifies the serial treatment of max-flow execution, which is the main change in the pull request.

✨ 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 cursor/545-serial-max-flow-disposition-c6a4

---

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

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/graphforge-api/tests/m4_entry_baseline.rs`:
- Around line 421-422: Remove the obsolete paths-gomory-hu-tree workload
consistently: in crates/graphforge-api/tests/m4_entry_baseline.rs at lines
421-422, keep run_paths_max_flow as the only workload in collect_workloads_for;
at lines 1092-1093, apply the same replacement in collect_short_matrix; at lines
1200-1201, replace the Gomory-Hu ID in its original position and do not append a
Max-Flow ID; in scripts/ci/m4-entry-matrix.py at lines 28-29, remove
paths-gomory-hu-tree from REQUIRED_WORKLOAD_IDS so the workload matrix matches
the contract.
- Around line 583-594: Repair the malformed insertion around
run_paths_gomory_hu_tree and run_paths_max_flow: retain a single person_uuid
helper, restore each function as a complete independent implementation, and
ensure both return their workload collections with WorkloadEvidence initializers
valid. Match each function’s workload count and ordering to the expected IDs,
then run the required Rust validation gates.

🪄 Autofix

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: c11ceb0b-f1b1-49e8-b4d0-25a12d543ac4

📥 Commits

Reviewing files that changed from the base of the PR and between 40a66ae and 9a9f9df.

⛔ Files ignored due to path filters (1)

• docs/development/execution-resource-policy.md is excluded by !**/*.md, !**/docs/**

📒 Files selected for processing (4)

• crates/graphforge-api/tests/m4_entry_baseline.rs
• crates/graphforge-exec/src/algorithm_paths_max_flow.rs
• scripts/ci/m4-entry-matrix.py
• tests/contracts/m4-entry-matrix.json