Fix #290: [Model] IntegralFlowWithMultipliers

[GiggleLiu]

Summary

• add an implementation plan for IntegralFlowWithMultipliers
• stage the work as Rust/CLI/example-db first, then the paper entry

Fixes #290

[codecov]

Codecov Report

❌ Patch coverage is 98.43750% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.58%. Comparing base (ca7b5b6) to head (a1ffbd5).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/models/graph/integral_flow_with_multipliers.rs	97.36%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #736      +/-   ##
==========================================
- Coverage   97.58%   97.58%   -0.01%     
==========================================
  Files         417      419       +2     
  Lines       51699    51955     +256     
==========================================
+ Hits        50453    50699     +246     
- Misses       1246     1256      +10     

☔ 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 IntegralFlowWithMultipliers model in src/models/graph/integral_flow_with_multipliers.rs and wired it into the public registry via src/models/graph/mod.rs, src/models/mod.rs, and src/lib.rs.
• Added CLI creation support in problemreductions-cli/src/cli.rs and problemreductions-cli/src/commands/create.rs, plus CLI coverage in problemreductions-cli/tests/cli_tests.rs.
• Added model coverage in src/unit_tests/models/graph/integral_flow_with_multipliers.rs, including the canonical paper example and extra validation cases.
• Added the paper entry and bibliography references in docs/paper/reductions.typ and docs/paper/references.bib.

Deviations from Plan

• No structural deviations. After the main implementation landed, I added two extra CLI rejection tests and strengthened the paper-example assertions to lock the canonical 2 + 4 + 6 = 12 witness.

Open Questions

• None. The implementation follows the issue discussion choice that multipliers has one entry per vertex and ignores the source/sink entries.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: model IntegralFlowWithMultipliers

Structural Completeness

#	Check	Status
1	Model file exists	PASS — src/models/graph/integral_flow_with_multipliers.rs added
2	inventory::submit! present	PASS — schema and size-field entries registered
3	Serialize / Deserialize derive	PASS — struct derives both
4	Problem trait impl	PASS — implemented in model file
5	SatisfactionProblem impl	PASS — decision problem marker added
6	Test link from model file	PASS — #[path = "../../unit_tests/models/graph/integral_flow_with_multipliers.rs"] present
7	Test file exists	PASS — dedicated unit-test file added
8	Test file has >= 3 tests	PASS — 11 tests present
9	Registered in graph/mod.rs	PASS — module, re-export, and example aggregation added
10	Re-exported in models/mod.rs	PASS — public re-export added
11	declare_variants! entry exists	PASS — default satisfaction variant declared
12	CLI alias resolution path exists	PASS — canonical name resolves through registry-backed resolve_alias, no manual table entry required
13	CLI create support	PASS — create branch and CLI flags added
14	Canonical model example registered	PASS — model contributes canonical_model_example_specs() and graph aggregator includes it
15	Paper display-name entry	PASS — display name added to docs/paper/reductions.typ
16	Paper problem-def block	PASS — paper entry added

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• evaluate() correctness: OK — arc capacities, multiplier-scaled conservation, and sink net-flow threshold match the model definition in src/models/graph/integral_flow_with_multipliers.rs.
• dims() correctness: OK — one bounded integer variable per arc with domain 0..=capacity.
• Size getter consistency: OK — num_vertices, num_arcs, max_capacity, and requirement match the declared size fields and complexity string.
• Solver integration / documented command path: ISSUE — the model has no registered path to ILP (pred path IntegralFlowWithMultipliers ILP fails), so the paper’s advertised command pred solve integral-flow-with-multipliers.json does not work as written (docs/paper/reductions.typ:5194-5196). Reproduced on the PR head: plain pred solve errors with No reduction path from IntegralFlowWithMultipliers to ILP ... Try --solver brute-force.

Issue Compliance (if linked issue found)

#	Check	Status
1	Problem name matches issue	OK
2	Mathematical definition matches	OK
3	Problem type (opt/sat) matches	OK — satisfaction problem
4	Type parameters match	OK — none required
5	Configuration space matches	OK — one variable per arc with c(a)+1 domain
6	Feasibility check matches	OK
7	Objective function matches	OK — boolean feasibility
8	Complexity matches	OK — (max_capacity + 1)^num_arcs

Summary

• 16/16 structural checks passed
• 8/8 issue compliance checks passed
• ISSUE: the shipped paper command sequence claims a default pred solve path that does not exist for this model (docs/paper/reductions.typ:5194-5196)

---

Quality Check

Quality Review

Design Principles

• DRY: OK — the new model/CLI/test code follows existing per-problem patterns without introducing avoidable shared-state duplication.
• KISS: OK — feasibility is implemented as direct inflow/outflow accounting, and CLI validation stays local to the create branch.
• HC/LC: OK — model logic, CLI parsing, paper text, and tests remain separated along existing module boundaries.

HCI (if CLI/MCP changed)

• Error messages: OK — missing flags and invalid inputs include concrete usage strings, and the solve failure suggests --solver brute-force.
• Discoverability: ISSUE — the new paper/example command sequence advertises plain pred solve integral-flow-with-multipliers.json, but a docs-following user hits a solver-path error instead of a solution (docs/paper/reductions.typ:5193-5196).
• Consistency: OK — --arcs, --capacities, --source, --sink, --multipliers, and --requirement fit the existing create-CLI conventions.
• Least surprise: ISSUE — pred create --example IntegralFlowWithMultipliers succeeds, but the immediately-following default pred solve path fails because no ILP/reduction route exists for the new model.
• Feedback: OK — the CLI points users to the working fallback (--solver brute-force).

Test Quality

• Naive test detection: ISSUE
  • The new CLI tests cover create validation and inspect, but they do not exercise the documented example solve path or lock in the intended solver UX for the new model (problemreductions-cli/tests/cli_tests.rs:659-806).
  • The model tests verify the library BruteForce solver and the paper witness, but they do not cover the CLI default solve path that downstream users invoke (src/unit_tests/models/graph/integral_flow_with_multipliers.rs:102-148).

Issues

Critical (Must Fix)

None.

Important (Should Fix)

• Update the paper/example command sequence to use pred solve integral-flow-with-multipliers.json --solver brute-force, or add an actual reduction/solver path so the advertised plain pred solve command works (docs/paper/reductions.typ:5193-5196).
• Add an end-to-end CLI regression test for the example solve flow so the documented user path is enforced in CI (problemreductions-cli/tests/cli_tests.rs:659-806).

Minor (Nice to Have)

None.

Summary

• ISSUE: the documented canonical solve flow is broken for this model because default pred solve cannot route the instance to an available solver.
• ISSUE: the new tests do not cover the documented solve path, so the docs/UX regression was not caught.

---

Agentic Feature Tests

Feature Test Report: problem-reductions

Date: 2026-03-22
Project type: Rust library + CLI
Features tested: IntegralFlowWithMultipliers
Profile: ephemeral
Use Case: A downstream CLI user wants to discover the new model from the catalog/docs, inspect its schema, create the canonical example instance, and solve it successfully.
Expected Outcome: The model appears in pred list, pred show IntegralFlowWithMultipliers renders correctly, pred create --example IntegralFlowWithMultipliers creates a valid example, and solving that example through the documented CLI flow succeeds.
Verdict: fail
Critical Issues: 1

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
IntegralFlowWithMultipliers	yes	yes	partial	no	misleading solve command

Per-Feature Details

IntegralFlowWithMultipliers

• Role: CLI user validating a newly added model.
• Use Case: Discover the model, inspect it, create the canonical example, and solve it.
• What they tried: pred list, pred show IntegralFlowWithMultipliers, pred create --example IntegralFlowWithMultipliers, pred solve <example>, pred solve <example> --solver brute-force, and pred evaluate <example> --config ....
• Discoverability: Good. The model appears in pred list, and pred show displays the schema and size fields correctly.
• Setup: Good. No special setup beyond building the CLI in the review worktree.
• Functionality: pred create --example succeeds and writes a valid example JSON. pred evaluate succeeds on the paper witness. Plain pred solve <example> fails with No reduction path from IntegralFlowWithMultipliers to ILP ... Try --solver brute-force. Re-running with --solver brute-force succeeds.
• Expected vs Actual Outcome: Expected the documented default pred solve flow to solve the example. Actual result: the default solve path fails; only explicit brute-force works.
• Blocked steps: None.
• Friction points: The paper command block implies a default solver path that the implementation does not provide.
• Doc suggestions: Change the command to pred solve integral-flow-with-multipliers.json --solver brute-force or add a registered reduction path that makes plain pred solve work.

Expected vs Actual Outcome

• IntegralFlowWithMultipliers: partially achieved. Catalog discovery, inspection, example creation, and explicit brute-force solving all work. The documented default solve command does not.

Issues Found

• Confirmed: the documented pred solve integral-flow-with-multipliers.json flow fails on the canonical example because there is no reduction path from IntegralFlowWithMultipliers to ILP in the shipped graph.

Suggestions

• Update the paper/example command sequence to match the working CLI invocation.
• Add a CLI regression test that exercises the example solve path for the new model.

---

Generated by review-pipeline

[GiggleLiu]

Agentic Review Addendum

One confirmed issue was omitted from the earlier combined report:

• The linked issue and paper define capacities c(a) and requirement R over Z^+, but the implementation and CLI currently accept zero values. IntegralFlowWithMultipliers::new() stores capacity == 0 and requirement == 0 without rejecting them (src/models/graph/integral_flow_with_multipliers.rs:85, src/models/graph/integral_flow_with_multipliers.rs:95), and the CLI create path accepts both --capacities 0 and --requirement 0 (problemreductions-cli/src/commands/create.rs:1112, problemreductions-cli/src/commands/create.rs:1174).

Reproduced on the PR head:

cargo run -q -p problemreductions-cli --bin pred -- create IntegralFlowWithMultipliers --arcs "0>1" --capacities 0 --source 0 --sink 1 --multipliers 1,1 --requirement 1
cargo run -q -p problemreductions-cli --bin pred -- create IntegralFlowWithMultipliers --arcs "0>1" --capacities 1 --source 0 --sink 1 --multipliers 1,1 --requirement 0

Both commands succeeded and emitted JSON instances.

This is an issue-compliance mismatch relative to the current model definition. Either reject zero capacities / zero requirement in both constructor and CLI validation, or relax the paper / issue specification consistently.