From 578078633b9744597666cd75272fe5b15fcfb047 Mon Sep 17 00:00:00 2001 From: Xiwei Pan Date: Fri, 7 Aug 2026 02:14:43 +0800 Subject: [PATCH 1/5] Establish numeric types and arithmetic standard --- .claude/CLAUDE.md | 10 ++ .claude/skills/add-model/SKILL.md | 2 + .claude/skills/add-rule/SKILL.md | 9 ++ .claude/skills/review-structural/SKILL.md | 4 + .github/ISSUE_TEMPLATE/problem.md | 12 ++ .github/ISSUE_TEMPLATE/rule.md | 12 ++ docs/src/design.md | 90 +++++++++++++ problemreductions-cli/src/commands/create.rs | 8 +- .../src/commands/create/schema_support.rs | 2 +- src/models/formula/ksat.rs | 69 +++++++--- .../formula/maximum_2_satisfiability.rs | 37 +++-- src/models/formula/mod.rs | 1 + src/models/formula/nae_satisfiability.rs | 3 +- .../formula/one_in_three_satisfiability.rs | 46 ++++--- src/models/formula/planar_3_satisfiability.rs | 46 ++++--- src/models/formula/qbf.rs | 45 +++++-- src/models/formula/sat.rs | 127 +++++++++++++++++- src/models/graph/mixed_chinese_postman.rs | 18 +-- src/rules/circuit_sat.rs | 23 ++-- ...overby3sets_boundeddiameterspanningtree.rs | 7 +- ...oniancircuit_biconnectivityaugmentation.rs | 3 +- ...ncircuit_strongconnectivityaugmentation.rs | 3 +- src/rules/ksatisfiability_acyclicpartition.rs | 16 +-- ...tisfiability_decisionminimumvertexcover.rs | 8 +- ...satisfiability_oneinthreesatisfiability.rs | 53 +++++--- src/rules/ksatisfiability_timetabledesign.rs | 46 ++++--- ...nimumvertexcover_comparativecontainment.rs | 3 +- src/rules/sat_ksat.rs | 37 +++-- .../satisfiability_maximum2satisfiability.rs | 46 ++++--- src/rules/satisfiability_naesatisfiability.rs | 11 +- src/solvers/decision_search.rs | 22 +-- src/types.rs | 17 +-- .../formula/one_in_three_satisfiability.rs | 2 +- .../models/formula/planar_3_satisfiability.rs | 2 +- src/unit_tests/models/formula/qbf.rs | 4 +- src/unit_tests/models/formula/sat.rs | 29 +++- src/unit_tests/models/graph/max_cut.rs | 2 +- src/unit_tests/models/graph/maximal_is.rs | 2 +- .../models/graph/maximum_independent_set.rs | 2 +- .../models/graph/maximum_matching.rs | 2 +- .../models/graph/minimum_dominating_set.rs | 2 +- .../models/graph/minimum_vertex_cover.rs | 2 +- src/unit_tests/models/graph/spin_glass.rs | 2 +- .../models/set/maximum_set_packing.rs | 2 +- .../models/set/minimum_set_covering.rs | 2 +- ...imumdominatingset_minimumsummulticenter.rs | 5 +- ...nminimumdominatingset_minmaxmulticenter.rs | 2 +- ...onminimumvertexcover_hamiltoniancircuit.rs | 2 +- ...overby3sets_boundeddiameterspanningtree.rs | 2 +- .../rules/hamiltoniancircuit_ruralpostman.rs | 2 +- .../rules/maxcut_minimummatrixcover.rs | 2 +- .../rules/maximum2satisfiability_maxcut.rs | 2 +- ...nimumvertexcover_comparativecontainment.rs | 2 +- src/unit_tests/rules/sat_ksat.rs | 4 +- tests/main.rs | 2 + tests/suites/numeric_boundaries.rs | 104 ++++++++++++++ 56 files changed, 770 insertions(+), 250 deletions(-) create mode 100644 tests/suites/numeric_boundaries.rs diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 502e837f5..c15470b14 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -214,6 +214,16 @@ Reduction graph nodes use variant key-value pairs from `Problem::variant()`: ## Conventions +### Numeric Contract + +Follow the [numeric types and arithmetic standard](../docs/src/design.md#numeric-types-and-arithmetic) +for every model and reduction. Before implementation, identify each numeric +input and domain, each computed total and result type, the largest supported +value, every range/sign-changing conversion, overflow behavior, and whether +arithmetic is exact or approximate. Use `TryFrom` at range boundaries and +checked arithmetic for derived values that may overflow. Rust construction, +serde, CLI, and MCP must enforce the same range. + ### File Naming - Reduction files: `src/rules/_.rs` (e.g., `maximumindependentset_qubo.rs`) - Model files: `src/models//.rs` — category is by input structure: `graph/` (graph input), `formula/` (boolean formula/circuit), `set/` (universe + subsets), `algebraic/` (matrix/linear system/lattice), `misc/` (other) diff --git a/.claude/skills/add-model/SKILL.md b/.claude/skills/add-model/SKILL.md index 54f4c2292..903be1de1 100644 --- a/.claude/skills/add-model/SKILL.md +++ b/.claude/skills/add-model/SKILL.md @@ -27,6 +27,7 @@ Before any implementation, collect all required information. If called from `iss | 10 | **Solving strategy** | How it can be solved | "BruteForce works; ILP reduction available" | | 11 | **Category** | Which sub-module under `src/models/` | `graph`, `formula`, `set`, `algebraic`, `misc` | | 12 | **Expected outcome from the issue** | Concrete outcome for the issue's example instance | Objective: one optimal solution + optimal value. Witness: one valid/satisfying solution + why it is valid. Aggregate-only: the final aggregate value and how it is derived | +| 13 | **Numeric contract** | Every numeric input/domain, computed total type, maximum supported value, checked conversion, overflow behavior, and exact/approximate choice | `weight: i32`, `total: i64`, exact, constructor rejects out-of-range input | If any item is missing, ask the user to provide it. Do NOT proceed until the checklist is complete. @@ -75,6 +76,7 @@ Read these first to understand the patterns: ## Pre-review Checklist Before implementing, make sure the plan explicitly covers these items that structural review checks later: +- Numeric choices follow `docs/src/design.md#numeric-types-and-arithmetic`; serde/CLI construction uses the same validation as `new`/`try_new`, and boundary tests cover the declared maximum without requiring impractical allocation - `ProblemSchemaEntry` metadata is complete for the current schema shape (`display_name`, `aliases`, `dimensions`, and constructor-facing `fields`) - `Problem::Value` uses the correct aggregate wrapper and witness support is intentional - `declare_variants!` is present with exactly one `default` variant when multiple concrete variants exist diff --git a/.claude/skills/add-rule/SKILL.md b/.claude/skills/add-rule/SKILL.md index 5e9b01ea6..9264a508a 100644 --- a/.claude/skills/add-rule/SKILL.md +++ b/.claude/skills/add-rule/SKILL.md @@ -33,6 +33,7 @@ Before any implementation, collect all required information. If called from `iss | 7 | **Concrete example** | A small worked-out instance (tutorial style, clear intuition) | "Triangle graph: VC={0,1} -> IS={2}" | | 8 | **Solving strategy** | How to solve the target problem | "BruteForce, or existing ILP reduction" | | 9 | **Reference** | Paper, textbook, or URL for the reduction | URL or citation | +| 10 | **Numeric contract** | Source/target numeric fields, totals, size arithmetic, coefficients, bounds, auxiliary IDs, maximum values, checked conversions, overflow behavior, and exact/approximate choice | `usize` source count to checked `i32` SAT IDs | If any item is missing, ask the user to provide it. Put a high standard on item 7 (concrete example): it must be in tutorial style with clear intuition and easy to understand. Do NOT proceed until the checklist is complete. @@ -56,6 +57,14 @@ grep "type Value = " src/models/*/.rs src/models/*/.rs If incompatible, STOP and comment on the issue explaining the type mismatch and options. Do NOT proceed. +## Numeric Safety Gate + +Read `docs/src/design.md#numeric-types-and-arithmetic`. Reject an incomplete +plan when numeric domains, total types, maxima, or conversions are unspecified. +Do not use `as` for range/sign changes. Check target-size arithmetic and +auxiliary identifiers before constructing the target, verify serde/CLI uses the +same ranges, and add focused tests at the declared boundary. + ## Reference Implementations Read these first to understand the patterns: diff --git a/.claude/skills/review-structural/SKILL.md b/.claude/skills/review-structural/SKILL.md index cdf144284..d32c6b3fb 100644 --- a/.claude/skills/review-structural/SKILL.md +++ b/.claude/skills/review-structural/SKILL.md @@ -66,6 +66,7 @@ Only run if review type includes "model". Given: problem name `P`, category `C`, | 14 | Canonical model example registered | `Grep("{P}", "src/example_db/model_builders.rs")` | | 15 | Paper `display-name` entry | `Grep('"{P}"', "docs/paper/reductions.typ")` | | 16 | Paper `problem-def` block | `Grep('problem-def.*"{P}"', "docs/paper/reductions.typ")` | +| 17 | Numeric contract | Compare issue fields, schema types, Rust fields, aggregate/total type, constructor and serde validation, conversions, overflow behavior, and boundary tests against `docs/src/design.md#numeric-types-and-arithmetic` | ### Rule Checklist @@ -85,6 +86,7 @@ Only run if review type includes "rule". Given: source `S`, target `T`, rule fil | 10 | Example-db lookup tests exist | `Grep("find_rule_example|build_rule_db", "src/unit_tests/example_db.rs")` | | 11 | Paper `reduction-rule` entry | `Grep('reduction-rule.*"{S}".*"{T}"', "docs/paper/reductions.typ")` | | 12 | Extraction contract | Direct decoders call `validate_target_solution()`, enforce rule-specific structure, and test malformed cases; the helper does not establish feasibility or optimality. Composed extractors may delegate. | +| 13 | Numeric contract | Compare source/target types, size arithmetic, coefficients, bounds, auxiliary IDs, conversions, overflow behavior, and boundary tests against `docs/src/design.md#numeric-types-and-arithmetic` | ## Step 2b: Blacklisted File Check @@ -111,12 +113,14 @@ Report pass/fail. If tests fail, identify which tests. **Do NOT fix anything** 2. **`dims()` correctness** — Does it return the actual configuration space? (e.g., `vec![2; n]` for binary) 3. **Size getter consistency** — Do inherent getter methods (e.g., `num_vertices()`, `num_edges()`) match names used in overhead expressions? 4. **Weight handling** — Are weights managed via inherent methods, not traits? +5. **Numeric safety** — Are element and total types distinct where required, do serde and constructors enforce the same range, and are overflow and non-finite values rejected explicitly? ### For Rules: 1. **`extract_solution` correctness** — Does it implement the mathematical inverse? Is every branch either a defined mathematical case or an `ExtractionError`, with no defaulting, truncation, clamping, panic, or recovery? 2. **Overhead accuracy** — Does `overhead = { field = "expr" }` reflect the actual size relationship? 3. **Example quality** — Is it tutorial-style? Does the JSON export include both source and target data? 4. **Paper quality** — Is the reduction-rule statement precise? Is the proof sketch sound? +5. **Numeric safety** — Are target sizes and auxiliary IDs checked before construction, with no unchecked narrowing or exact-to-`f64` shortcut? ## Step 5: Issue Compliance Review diff --git a/.github/ISSUE_TEMPLATE/problem.md b/.github/ISSUE_TEMPLATE/problem.md index 412397888..e5214d071 100644 --- a/.github/ISSUE_TEMPLATE/problem.md +++ b/.github/ISSUE_TEMPLATE/problem.md @@ -50,6 +50,18 @@ Connect fields to the symbols defined above. | | | | | | | | +## Numeric Contract + + + +| Quantity | Meaning and domain | Input type | Computed/total type | Maximum supported value | Checked conversions | +|----------|--------------------|------------|---------------------|-------------------------|---------------------| +| | | | | | | + +- **Overflow behavior:** +- **Arithmetic:** + ## Complexity - **Best known exact algorithm:** diff --git a/.github/ISSUE_TEMPLATE/rule.md b/.github/ISSUE_TEMPLATE/rule.md index 230db8452..ca49e2dd2 100644 --- a/.github/ISSUE_TEMPLATE/rule.md +++ b/.github/ISSUE_TEMPLATE/rule.md @@ -45,6 +45,18 @@ Use the symbols defined in the Reduction Algorithm above. --> | | | | | | +## Numeric Contract + + + +| Quantity | Meaning and domain | Source type | Target/computed type | Maximum supported value | Checked conversions | +|----------|--------------------|-------------|----------------------|-------------------------|---------------------| +| | | | | | | + +- **Overflow behavior:** +- **Arithmetic:** + ## Validation Method | | | | | | | -## Numeric Contract - - - -| Quantity | Meaning and domain | Input type | Computed/total type | Maximum supported value | Checked conversions | -|----------|--------------------|------------|---------------------|-------------------------|---------------------| -| | | | | | | - -- **Overflow behavior:** -- **Arithmetic:** - ## Complexity - **Best known exact algorithm:** diff --git a/.github/ISSUE_TEMPLATE/rule.md b/.github/ISSUE_TEMPLATE/rule.md index ca49e2dd2..230db8452 100644 --- a/.github/ISSUE_TEMPLATE/rule.md +++ b/.github/ISSUE_TEMPLATE/rule.md @@ -45,18 +45,6 @@ Use the symbols defined in the Reduction Algorithm above. --> | | | | | | -## Numeric Contract - - - -| Quantity | Meaning and domain | Source type | Target/computed type | Maximum supported value | Checked conversions | -|----------|--------------------|-------------|----------------------|-------------------------|---------------------| -| | | | | | | - -- **Overflow behavior:** -- **Arithmetic:** - ## Validation Method