Fix #291: [Model] PathConstrainedNetworkFlow

[GiggleLiu]

Summary

Add the implementation plan for PathConstrainedNetworkFlow and execute it in follow-up commits.

Fixes #291

[codecov]

Codecov Report

❌ Patch coverage is 99.61832% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 97.61%. Comparing base (fa3e24b) to head (2f0e6db).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/models/graph/path_constrained_network_flow.rs	99.33%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #738    +/-   ##
========================================
  Coverage   97.60%   97.61%            
========================================
  Files         427      429     +2     
  Lines       52822    53084   +262     
========================================
+ Hits        51557    51818   +261     
- Misses       1265     1266     +1     

☔ 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 PathConstrainedNetworkFlow model in src/models/graph/path_constrained_network_flow.rs, including validation for prescribed simple s-t paths, feasibility evaluation, canonical example data, and registry exports.
• Added model tests in src/unit_tests/models/graph/path_constrained_network_flow.rs covering construction, dimension bounds, feasibility, solver behavior, serialization, invalid paths, and the paper example.
• Extended pred create support in problemreductions-cli/src/cli.rs and problemreductions-cli/src/commands/create.rs with --paths and --requirement, examples, parsing, and CLI tests.
• Updated library/model re-exports in src/models/graph/mod.rs, src/models/mod.rs, and src/lib.rs.
• Added the paper entry and reference updates in docs/paper/reductions.typ and docs/paper/references.bib.

Deviations from Plan

• No open companion rule issue exists for PathConstrainedNetworkFlow, so this remains an orphan model PR. The warning comment was kept in the PR description per the add-model workflow.

Open Questions

• None.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: model PathConstrainedNetworkFlow

Structural Completeness

#	Check	Status
0	Blacklisted generated files	PASS - none of docs/src/reductions/reduction_graph.json, docs/src/reductions/problem_schemas.json, src/example_db/fixtures/examples.json, or docs/paper/data/examples.json are in the diff
1	Model file exists	PASS - src/models/graph/path_constrained_network_flow.rs
2	inventory::submit! present	PASS - src/models/graph/path_constrained_network_flow.rs
3	Serialize/Deserialize derives present	PASS - src/models/graph/path_constrained_network_flow.rs
4	Problem impl present	PASS - src/models/graph/path_constrained_network_flow.rs
5	SatisfactionProblem impl present	PASS - src/models/graph/path_constrained_network_flow.rs
6	#[cfg(test)] + #[path = ...] link present	PASS - src/models/graph/path_constrained_network_flow.rs
7	Test file exists	PASS - src/unit_tests/models/graph/path_constrained_network_flow.rs
8	Test file has at least 3 test functions	PASS - src/unit_tests/models/graph/path_constrained_network_flow.rs
9	Registered in graph/mod.rs	PASS - src/models/graph/mod.rs and src/models/graph/mod.rs
10	Re-exported in models/mod.rs	PASS - src/models/mod.rs
11	declare_variants! entry exists	PASS - src/models/graph/path_constrained_network_flow.rs
12	CLI resolve_alias entry	PASS - alias resolution is registry-driven; no model-specific branch was needed in problemreductions-cli/src/problem_name.rs
13	CLI create support	PASS - problemreductions-cli/src/commands/create.rs and problemreductions-cli/src/commands/create.rs
14	Canonical model example registered	PASS - src/models/graph/mod.rs and src/models/graph/path_constrained_network_flow.rs
15	Paper display-name entry	PASS - docs/paper/reductions.typ
16	Paper problem-def block	PASS - docs/paper/reductions.typ

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• evaluate() correctness: OK - it checks config length, per-path bottlenecks, per-arc loads, and the total-flow threshold in src/models/graph/path_constrained_network_flow.rs.
• dims() correctness: OK - it exposes one dimension per prescribed path, bounded by bottleneck+1 in src/models/graph/path_constrained_network_flow.rs.
• Path feasibility checks: OK - new() rejects non-simple, non-contiguous, or non-s-to-t prescribed paths in src/models/graph/path_constrained_network_flow.rs.
• Paper/example alignment: OK - the paper statement, canonical fixture, and unit tests all describe the same 8-vertex, 10-arc YES instance in docs/paper/reductions.typ and src/unit_tests/models/graph/path_constrained_network_flow.rs.
• Weight handling: OK - not applicable; this model has no weight dimension.

Summary

• 17/17 structural checks passed
• No FAIL or ISSUE items
• Linked issue context was not included in the packet, so compliance was checked against the model, tests, and paper text only

---

Additional Driver Findings

• pred show PathConstrainedNetworkFlow currently prints no Size fields section, even though issue #291 defines num_vertices, num_arcs, num_paths, max_capacity, and requirement as size fields. The model registers a ProblemSchemaEntry in src/models/graph/path_constrained_network_flow.rs:15 but no ProblemSizeFieldEntry, and pred show only renders size fields when graph.size_field_names(name) is non-empty (problemreductions-cli/src/commands/graph.rs:245, src/registry/schema.rs:55). Reproduced with cargo run -q -p problemreductions-cli --bin pred -- show PathConstrainedNetworkFlow.

---

Quality Check

Quality Review

Design Principles

• DRY: OK
• KISS: ISSUE - problemreductions-cli/src/commands/create.rs defers structural path validation to PathConstrainedNetworkFlow::new, so malformed in-bounds paths still reach a panic instead of being rejected once at the CLI boundary.
• HC/LC: ISSUE - pred create is coupled to constructor assertions for user-facing validation, which makes invalid --paths input crash the process instead of returning a recoverable error.

HCI (if CLI/MCP changed)

• Error messages: ISSUE - invalid but in-bounds paths panic inside src/models/graph/path_constrained_network_flow.rs rather than returning an actionable CLI error with usage context.
• Discoverability: OK
• Consistency: ISSUE - this create branch is the only one here that leaves structural input validation to a panic-prone model constructor.
• Least surprise: ISSUE - a malformed --paths value should not terminate pred create.
• Feedback: ISSUE - the command does not report which path shape is invalid before constructing the model.

Test Quality

• Naive test detection: ISSUE - src/unit_tests/models/graph/path_constrained_network_flow.rs:103 only checks an out-of-bounds arc index; it does not cover the in-bounds malformed-path case that currently panics.

Issues

Important (Should Fix)

• problemreductions-cli/src/commands/create.rs:3073 and src/models/graph/path_constrained_network_flow.rs:99 - pred create PathConstrainedNetworkFlow can still panic on any in-bounds but non-contiguous or non-terminal path. parse_prescribed_paths only checks arc bounds, then the constructor asserts on path shape. Example: --paths "1" on a graph where arc 1 exists but does not leave source aborts the CLI instead of returning a normal error.

Minor (Nice to Have)

• src/unit_tests/models/graph/path_constrained_network_flow.rs:103 - the new negative-path test only exercises an out-of-bounds arc index, so the panic path for malformed in-bounds paths remains untested.

Summary

• Important - pred create PathConstrainedNetworkFlow panics on malformed in-bounds paths instead of reporting a recoverable error.
• Minor - the unit tests do not cover the malformed in-bounds path case that triggers that panic.

---

Agentic Feature Tests

Feature Test Report: PathConstrainedNetworkFlow

Project type: Rust library + CLI
Profile: ephemeral
Use Case: downstream CLI user discovers the new model, inspects it, creates an example instance, and solves it from the documented CLI surface.
Expected Outcome: discoverable via pred list, details display correctly via pred show, example creation works, solving works, and the output is not confusing.
Verdict: pass
Critical Issues: 0

Summary

Feature	Discoverable	Setup	Works	Expected Outcome Met	Doc Quality
PathConstrainedNetworkFlow	yes	yes	yes	yes	good

Per-Feature Details

PathConstrainedNetworkFlow

• Role: downstream CLI user
• What I tried: pred list, pred show PathConstrainedNetworkFlow, pred create --example PathConstrainedNetworkFlow -o .tmp-pcnf-example.json, pred solve .tmp-pcnf-example.json --solver brute-force, plus a custom-flag instance using --arcs, --capacities, --source, --sink, --paths, and --requirement.
• Discoverability: good. The model appears in pred list as PathConstrainedNetworkFlow * O((max_capacity + 1)^num_paths), and pred show renders the correct description, field list, and complexity. pred create PathConstrainedNetworkFlow also prints model-specific help with the exact flags and an example.
• Setup: clean. cargo build -p problemreductions-cli --bin pred completed successfully.
• Functionality: worked end-to-end. The documented example created a valid JSON instance, and pred solve returned evaluation: true with a satisfying assignment. The custom-flag instance also solved successfully.
• Expected vs Actual: matched. The solver returned a valid satisfying assignment, though not necessarily the paper’s canonical witness, which is fine.
• Blocked steps: none.
• Friction points: the no-argument pred create PathConstrainedNetworkFlow path exits with code 2 while printing help. The help text itself is clear, but wrapper scripts may treat that exit status as an error.
• Doc suggestions: add a short README CLI example for PathConstrainedNetworkFlow, or link to the model-specific create help, so the new model is visible without opening the paper.

Issues Found

• None confirmed in the current worktree.

---

Generated by review-pipeline