Fix #411: [Model] CapacityAssignment

[GiggleLiu]

Summary

Add the implementation plan for CapacityAssignment, a new satisfaction problem from Garey & Johnson issue #411.

Fixes #411

[GiggleLiu]

Implementation Summary

Changes

• Added the new CapacityAssignment satisfaction model in src/models/misc/capacity_assignment.rs, including schema metadata, invariant checks, brute-force dimensions, canonical example registration, and crate exports.
• Added model regression coverage in src/unit_tests/models/misc/capacity_assignment.rs, including the paper example, brute-force solution-count checks, serialization, and constructor guard tests.
• Added pred create CapacityAssignment support in problemreductions-cli/src/cli.rs and problemreductions-cli/src/commands/create.rs with dedicated --cost-matrix, --delay-matrix, --cost-budget, and --delay-budget flags plus CLI validation tests.
• Added the paper entry and citation updates in docs/paper/reductions.typ and docs/paper/references.bib.

Deviations from Plan

• No material deviations. The only implementation detail worth calling out is that I kept problem-name lookup canonical-only (no new short alias) because the registry already resolves canonical names case-insensitively.

Open Questions

• None.

[GiggleLiu]

Agentic Review Report

Structural Check

Structural Review: model CapacityAssignment

Structural Completeness

#	Check	Status
1	Model file exists	PASS — src/models/misc/capacity_assignment.rs
2	inventory::submit! present	PASS — src/models/misc/capacity_assignment.rs
3	Serialize / Deserialize derive on struct	PASS — src/models/misc/capacity_assignment.rs
4	Problem trait impl	PASS — src/models/misc/capacity_assignment.rs
5	SatisfactionProblem impl	PASS — src/models/misc/capacity_assignment.rs
6	#[cfg(test)] + #[path = ...] test link	PASS — src/models/misc/capacity_assignment.rs
7	Test file exists	PASS — src/unit_tests/models/misc/capacity_assignment.rs
8	Test file has >= 3 tests	PASS — 8 tests in src/unit_tests/models/misc/capacity_assignment.rs
9	Registered in misc/mod.rs	PASS — src/models/misc/mod.rs
10	Re-exported in models/mod.rs	PASS — src/models/mod.rs
11	declare_variants! entry exists	PASS — src/models/misc/capacity_assignment.rs
12	CLI resolve-alias support	PASS — canonical-name resolution is registry-backed via problem_name.rs; no hard-coded alias entry is required
13	CLI create support	PASS — problemreductions-cli/src/commands/create.rs
14	Canonical model example registered	PASS — canonical_model_example_specs() is wired through src/models/misc/mod.rs into the example DB
15	Paper display-name entry	PASS — docs/paper/reductions.typ
16	Paper problem-def block	PASS — docs/paper/reductions.typ
17	Deterministic whitelist	FAIL — review packet flagged files outside the current model-PR whitelist: problemreductions-cli/src/cli.rs, problemreductions-cli/src/commands/create.rs, src/lib.rs, src/models/misc/mod.rs, src/models/mod.rs. These look like integration files required by the current architecture, so this appears to be whitelist/tooling drift rather than a correctness defect in the PR.
18	Blacklisted autogenerated files absent	PASS — none of the banned generated files are in the diff

Build Status

• make test: PASS
• make clippy: PASS

Semantic Review

• evaluate() correctness: OK — src/models/misc/capacity_assignment.rs correctly rejects wrong-length / out-of-range configs and checks both budget inequalities.
• dims() correctness: OK — src/models/misc/capacity_assignment.rs returns one num_capacities dimension per link.
• Size getter consistency: OK — the complexity string num_capacities ^ num_links matches the inherent getters used by the model.
• Weight handling: OK — not applicable for this model.

Issue Compliance (linked issue #411)

#	Check	Status
1	Problem name matches issue	OK
2	Mathematical definition matches	OK
3	Problem type (sat) matches	OK
4	Type parameters match	OK — none required
5	Configuration space matches	OK — one capacity choice per link
6	Feasibility check matches	OK — both cost and delay budgets enforced
7	Objective function matches	OK — satisfaction / feasibility only
8	Complexity matches	OK — registry complexity string and paper text align with the issue

Summary

• 17/18 structural checks passed
• 8/8 issue-compliance checks passed
• Deterministic whitelist flagged integration files outside the current model-PR whitelist; this looks like policy/tooling drift, not a mathematical or implementation defect in the PR.

---

Quality Check

Quality Review

Design Principles

• DRY: OK — constructor invariants and CLI validation intentionally overlap so CLI users get actionable Result errors instead of invariant panics.
• KISS: OK — the model and CLI parsing logic stay direct and readable.
• HC/LC: OK — model semantics live in src/models/misc/capacity_assignment.rs, while CLI parsing stays in problemreductions-cli/src/commands/create.rs.

HCI (CLI changed)

• Error messages: OK — reproduced CapacityAssignment requires --cost-budget error includes the missing flag and a full usage example.
• Discoverability: ISSUE — problemreductions-cli/src/cli.rs:358 still describes --capacities only as “Edge capacities for multicommodity flow problems”, which is misleading for CapacityAssignment users. Reproduced via target/debug/pred create --help.
• Consistency: OK — the dedicated CapacityAssignment usage string, examples, and validation messages are internally consistent.
• Least surprise: OK — pred list, pred show, pred create, pred solve, and pred evaluate all behaved as expected.
• Feedback: OK — pred create reports the output path; pred solve and pred evaluate emit structured JSON.

Test Quality

• Naive test detection: OK
  • Model tests cover valid/invalid configs, satisfying-assignment counts, serialization, and constructor guards in src/unit_tests/models/misc/capacity_assignment.rs.
  • CLI tests cover successful serialization plus validation failures for monotone rows and matrix-width mismatch in problemreductions-cli/src/commands/create.rs.

Issues

Critical (Must Fix)

None.

Important (Should Fix)

None.

Minor (Nice to Have)

• Update the --capacities help text at problemreductions-cli/src/cli.rs:358 so it describes both flow-capacity inputs and CapacityAssignment capacity levels.

Summary

• Minor HCI issue: the generic --capacities help text is stale for the new CapacityAssignment workflow.

---

Agentic Feature Tests

Feature Under Test

• Model: CapacityAssignment

Commands Exercised

• pred list
• pred show CapacityAssignment
• pred create --example CapacityAssignment -o <file>
• pred solve <file> --solver brute-force
• pred evaluate <file> --config 1,1,1
• pred create CapacityAssignment --capacities 1,2,3 --cost-matrix "1,3,6;2,4,7;1,2,5" --delay-matrix "8,4,1;7,3,1;6,3,1" --cost-budget 10 --delay-budget 12 -o <file>

Results

• pred list: PASS — CapacityAssignment appears in the catalog with O(num_capacities^num_links).
• pred show CapacityAssignment: PASS — description, complexity, and schema fields render correctly.
• pred create --example CapacityAssignment: PASS — canonical example JSON was created successfully.
• pred solve <example> --solver brute-force: PASS — solver returned a satisfying configuration ([0, 1, 2]).
• pred evaluate <example> --config 1,1,1: PASS — returned true for the canonical balanced assignment.
• Manual pred create CapacityAssignment ...: PASS — produced JSON identical to the canonical example (diff -u empty).

Findings

• confirmed / minor — pred create --help still describes --capacities as flow-only, which is misleading for CapacityAssignment users. Source: problemreductions-cli/src/cli.rs:358.
• not reproducible in current worktree — none.

Discoverability / Setup / Functionality

• Discoverability: partial — the feature is easy to find via pred list / pred show, but the generic help text for --capacities is stale.
• Setup: yes — building and running the CLI in the review worktree succeeded.
• Functionality: yes — all required commands worked.
• Expected vs Actual: matched.
• Blocked steps: none.
• Friction points: stale --capacities help text.
• Doc suggestions: make the --capacities flag description generic enough to cover both multicommodity-flow capacities and CapacityAssignment capacity levels.

---

Generated by review-pipeline

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.62%. Comparing base (94063e7) to head (925374a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff            @@
##             main     #747    +/-   ##
========================================
  Coverage   97.61%   97.62%            
========================================
  Files         441      443     +2     
  Lines       54455    54620   +165     
========================================
+ Hits        53158    53323   +165     
  Misses       1297     1297            

☔ 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.