Fix #293: [Model] IntegralFlowBundles

[GiggleLiu]

Summary

Add the implementation plan for IntegralFlowBundles, including the model, direct ILP solver reduction, CLI/example-db work, and paper updates.

Fixes #293

[codecov]

Codecov Report

❌ Patch coverage is 98.71795% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.61%. Comparing base (40fc86c) to head (be24905).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/models/graph/integral_flow_bundles.rs	97.51%	4 Missing ⚠️
src/rules/integralflowbundles_ilp.rs	98.24%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #740      +/-   ##
==========================================
- Coverage   97.61%   97.61%   -0.01%     
==========================================
  Files         429      433       +4     
  Lines       53084    53474     +390     
==========================================
+ Hits        51818    52197     +379     
- Misses       1266     1277      +11     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GiggleLiu]

Implementation Summary

Changes

• Added the IntegralFlowBundles graph model with constructor validation, tight per-arc domains derived from bundle capacities, evaluation logic, canonical examples, and unit tests.
• Added the IntegralFlowBundles -> ILP<i32> reduction with bundle-capacity inequalities, flow-conservation equalities, sink-requirement constraints, rule tests, and example-db coverage.
• Wired pred create IntegralFlowBundles into the CLI, added CLI tests, and documented the new model and ILP reduction in docs/paper/reductions.typ with the supporting Sahni bibliography entry.

Deviations from Plan

• The new model was placed under src/models/graph/ after reviewing the existing directed-flow models, rather than treating it as a misc model.
• No other functional deviations.

Open Questions

• None.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: model+rule IntegralFlowBundles / integralflowbundles_ilp

Structural Completeness — Model

#	Check	Status
1	Model file exists	PASS
2	inventory::submit! present	PASS
3	Serialize / Deserialize derive on struct	PASS
4	Problem trait impl	PASS
5	SatisfactionProblem impl	PASS
6	#[cfg(test)] + #[path = ...] test link	PASS
7	Test file exists	PASS
8	Test file has >= 3 test functions	PASS — 7 tests
9	Registered in src/models/graph/mod.rs	PASS
10	Re-exported in src/models/mod.rs	PASS
11	declare_variants! entry exists	PASS
12	CLI problem-name resolution	PASS — problem_name.rs resolves canonical names and aliases from the registry; no model-specific hardcoded entry is required
13	CLI create support	PASS
14	Canonical model example registered	PASS — via canonical_model_example_specs() -> src/models/graph/mod.rs -> src/example_db/model_builders.rs
15	Paper display-name entry	PASS
16	Paper problem-def block	PASS

Structural Completeness — Rule

#	Check	Status
1	Rule file exists	PASS
2	#[reduction(...)] macro present	PASS
3	ReductionResult impl present	PASS
4	ReduceTo impl present	PASS
5	#[cfg(test)] + #[path = ...] test link	PASS
6	Test file exists	PASS
7	Closed-loop test present	PASS
8	Registered in src/rules/mod.rs	PASS
9	Canonical rule example registered	PASS — via canonical_rule_example_specs() -> src/rules/mod.rs -> src/example_db/rule_builders.rs
10	Example-db lookup tests exist	PASS
11	Paper reduction-rule entry	PASS

Blacklisted Files

#	Check	Status
1	Auto-generated files committed	PASS

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• Model dims() / evaluate(): OK — per-arc domains are derived from the minimum containing bundle capacity, and evaluate() enforces bundle sums, nonterminal conservation, and sink net inflow.
• Overhead expressions: OK — the reduction emits num_bundles bundle inequalities, num_vertices - 2 conservation equalities, and 1 sink requirement inequality, matching num_bundles + num_vertices - 1.
• Paper quality: OK — the problem definition and ILP proof sketch match the implementation.
• Rule correctness: ISSUE — the reduction is only correct while every feasible arc value fits ILP<i32>. The source model and CLI accept u64 capacities / requirements (src/models/graph/integral_flow_bundles.rs:40-57, src/models/graph/integral_flow_bundles.rs:81-115, problemreductions-cli/src/commands/create.rs:1387-1423, problemreductions-cli/src/commands/create.rs:4255-4294), but the reduction hardcodes ILP<i32> (src/rules/integralflowbundles_ilp.rs:14-20, src/rules/integralflowbundles_ilp.rs:37-83). The solver then bounds each ILP variable by V::DIMS_PER_VAR - 1, i.e. i32::MAX for ILP<i32> (src/solvers/ilp/solver.rs:67-75). Satisfiable large-capacity source instances therefore become unsatisfiable after reduction.

Issue Compliance (linked issue #293)

#	Check	Status
1	Problem name matches issue	OK
2	Mathematical definition matches	OK
3	Problem type (satisfaction) matches	OK
4	Type parameters / variants match	OK
5	Configuration space matches issue	OK
6	Feasibility check matches issue	OK
7	Objective / metric matches issue	OK
8	Complexity registration matches issue	OK — unit-capacity complexity string is 2^num_arcs

Summary

• 28/28 structural checks passed.
• 8/8 issue-compliance checks passed.
• ISSUE: the IntegralFlowBundles -> ILP<i32> reduction is not correct for legal u64-capacity instances above i32::MAX.

---

Quality Check

Quality Review

Design Principles

• DRY: OK — the implementation is compact; the only duplication is small test-fixture setup.
• KISS: OK — constructor validation, arc_upper_bounds(), and the direct ILP mapping are straightforward.
• HC/LC: OK — model logic, CLI parsing, example-db wiring, tests, and paper updates are separated cleanly.

HCI

• Error messages: OK — missing required flags report the exact flag plus the full usage string; manually reproduced with missing --bundles.
• Discoverability: OK — pred list, pred list --rules, and pred show IntegralFlowBundles all expose the new model and rule.
• Consistency: OK — new flags and help text follow the existing pred create conventions.
• Least surprise: ISSUE — pred solve can reject a satisfiable instance when bundle capacities / requirements exceed i32::MAX, because the only advertised solver path silently narrows the domain to ILP<i32>.
• Feedback: OK — create / reduce print output paths, and solve --json reports the solver and reduction target.

Test Quality

• Naive test detection: ISSUE — the new tests only exercise small unit-capacity examples (src/unit_tests/models/graph/integral_flow_bundles.rs:6-25, src/unit_tests/rules/integralflowbundles_ilp.rs:7-26) and miss the i32::MAX boundary that breaks the solver path.

Issues

Critical (Must Fix)

• src/rules/integralflowbundles_ilp.rs:14-20, src/rules/integralflowbundles_ilp.rs:37-83, and src/solvers/ilp/solver.rs:67-75: the reduction targets ILP<i32>, so every arc variable is solver-bounded by i32::MAX. Legal IntegralFlowBundles instances can use larger u64 capacities / requirements (src/models/graph/integral_flow_bundles.rs:40-57, src/models/graph/integral_flow_bundles.rs:81-115; problemreductions-cli/src/commands/create.rs:1387-1423, problemreductions-cli/src/commands/create.rs:4255-4294). Reproduced in this PR worktree with a one-arc instance: pred evaluate returns true for config [2147483648], but pred solve reports no ILP solution.

Important (Should Fix)

• src/unit_tests/rules/integralflowbundles_ilp.rs:7-113: no regression test exercises the solver / reduction at or above the i32 boundary, which is why the incorrect target variant landed unnoticed.

Minor (Nice to Have)

• None.

Summary

• Critical correctness issue: large-capacity bundled-flow instances are satisfiable in the source model but unsatisfiable after the PR's only solver reduction path.
• Test gap: no adversarial capacity-boundary case covers the ILP domain mismatch.

---

Agentic Feature Tests

Feature Test Report: problem-reductions

Date: 2026-03-22
Project type: Rust library + CLI
Features tested: IntegralFlowBundles, IntegralFlowBundles -> ILP<i32>
Profile: ephemeral
Use Case: Verify that a downstream user can discover, create, inspect, reduce, and solve the new bundled-flow model from the CLI.
Expected Outcome: The new model appears in the catalog, example creation works, normal examples solve through ILP, and invalid inputs fail with actionable errors.
Verdict: fail
Critical Issues: 1

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
IntegralFlowBundles model + CLI	yes	yes	yes	yes	good
IntegralFlowBundles -> ILP<i32> solver path	yes	yes	partial	no	good

Per-Feature Details

IntegralFlowBundles model + CLI

• Role: downstream CLI user validating a new model and its built-in example.
• Use Case: discover the model, inspect its schema, create the canonical example, and solve it.
• What they tried: cargo run -q -p problemreductions-cli --bin pred --features highs -- list; list --rules; show IntegralFlowBundles; create --example IntegralFlowBundles; solve <example> --json; reduce <example> --to ILP/i32; solve <bundle> --json.
• Discoverability: good. list showed IntegralFlowBundles; list --rules showed IntegralFlowBundles -> ILP/i32; show exposed fields and the outgoing reduction.
• Setup: worked using the workspace binary.
• Functionality: the canonical example solved successfully, and the reduced ILP bundle also solved successfully.
• Expected vs Actual Outcome: matched for the normal example flow.
• Blocked steps: none.
• Friction points: none in the normal example path.
• Doc suggestions: none required for the normal path.

High-capacity solver boundary

• Role: downstream CLI user trying a legal larger-capacity instance.
• Use Case: solve a one-arc bundled-flow instance with requirement equal to the bundle capacity.
• What they tried: create IntegralFlowBundles with --arcs '0>1' --bundles '0' --bundle-capacities 2147483648 --source 0 --sink 1 --requirement 2147483648 --num-vertices 2; evaluate it with --config 2147483648; then run solve.
• Discoverability: the CLI accepts the instance without warning.
• Setup: worked.
• Functionality: broken. evaluate returned true, but solve failed with No reduction path from IntegralFlowBundles to ILP or ILP solver found no solution. Try --solver brute-force.
• Expected vs Actual Outcome: expected the solver path to preserve the source instance's legal value range; actual behavior incorrectly rejects a satisfiable instance.
• Blocked steps: none.
• Friction points: the error message hides the real cause, which is the ILP<i32> variable bound.
• Doc suggestions: document the supported numeric domain if the model must remain ILP<i32>-only, or better, fix the reduction / solver mismatch.

Expected vs Actual Outcome

• Canonical example: achieved.
• High-capacity legal instance: not achieved; the solver path is unsound above i32::MAX.

Issues Found

• Confirmed critical: satisfiable IntegralFlowBundles instances with arc values above i32::MAX cannot be solved through the new IntegralFlowBundles -> ILP<i32> reduction, even though the source model and CLI accept them.

Suggestions

• Either restrict IntegralFlowBundles construction / CLI parsing to the numeric range that ILP<i32> can faithfully represent, or add a target variant / solver path that preserves full u64-scale arc values.
• Add a regression test that creates a one-arc instance with capacity and requirement i32::MAX + 1 and asserts the expected behavior.

---

Generated by review-pipeline