Define and track the repository-wide numeric-domain contract

[isPANN]

Purpose

This is the design and tracking issue for the repository-wide numeric-domain contract. It separates three concerns that the current catalog often mixes:

1. the mathematical domain of a quantity;
2. its Rust representation inside models and reductions;
3. the numeric representation accepted by an external solver.

This issue defines the contract and coordinates focused follow-up migrations. It is not a request for one PR to migrate the entire catalog, redesign ILP and QUBO, change reduction execution, update HiGHS, and enable every cast lint at once.

Motivation

A mathematical variant may change the accepted instance set or a reduction precondition, such as unit, integer, or real weights. Changing storage width from i32 to i64 does not create a new mathematical problem.

Likewise, an exact integer model must not silently lose ordering or feasibility information merely because a reduction target or numerical solver uses f64. For example, the exact integers 9_007_199_254_740_992 and 9_007_199_254_740_993 are distinct, but a conversion to f64 may collapse them.

Relevant precedents:

• OR-Tools CP-SAT uses signed 64-bit integers for integer domains and coefficients and validates overflow:
  https://github.com/google/or-tools/blob/stable/ortools/sat/cp_model.proto
• OR-Tools knapsack uses int64_t for profits, weights, capacities, and results:
  https://github.com/google/or-tools/blob/stable/ortools/algorithms/knapsack_solver.h
• SCIP knapsack uses SCIP_Longint for weights and capacity:
  https://scipopt.org/doc/html/cons__knapsack_8h.php
• HiGHS, Gurobi, and good_lp use double-precision solver interfaces; that is a backend property, not a reason to discard exact provenance inside the repository:
  https://ergo-code.github.io/HiGHS/dev/guide/numerics/
  https://docs.gurobi.com/projects/optimizer/en/current/concepts/numericguide/rounding.html
  https://docs.rs/crate/good_lp/latest
• JuMP/MathOptInterface separates model coefficient types from solver capabilities:
  https://jump.dev/JuMP.jl/stable/manual/models/
• Exact rational solving is a separate backend capability:
  https://soplex.zib.de/doc/html/EXACT.php

Settled contract

Domains and representations

Mathematical role	Repository representation	Contract
Index, collection length, configuration dimension	usize	Checked conversion at boundaries where another encoding is required
Unit weight	One	Represents the mathematical constant one
Ordinary bounded exact integer, including semantically nonnegative quantities	i64	All arithmetic remains in i64; construction or reduction rejects instances whose required values do not fit
Approximate real input	finite f64	All arithmetic remains in f64; NaN and both infinities are rejected
Problem-native arbitrary-precision integer	BigInt or BigUint	Used only when arbitrary precision is part of the problem definition, such as Factoring
SAT literal or another compact protocol encoding	the protocol-required type	The encoding range is validated explicitly

The existing catalog labels One / i64 / f64 are retained to minimize churn. Their meanings are unit, ordinary bounded exact integer, and approximate real respectively. The i32 weight/coefficient variant is replaced rather than retained as a compatibility alias.

Storage width, signedness, and solver storage alone do not justify a mathematical variant. A problem-native arbitrary-precision representation also does not create a storage variant when arbitrary precision is inherent in that problem's mathematical input domain.

Arithmetic and validation

• Arithmetic uses the representation of the declared mathematical domain. Ordinary exact integers use checked i64 addition, subtraction, multiplication, division, and related operations. Approximate reals use finite f64 operations.
• Do not widen ordinary i64 calculations to i128, BigInt, or another larger type to rescue an instance that does not fit the chosen domain.
• Constructors and reductions must validate that every required input and derived value is representable in the model's declared domain. If an ordinary exact result would exceed i64, construction or reduction returns an explicit overflow error.
• evaluate() operates only on already validated instances. It must not contain fallback widening, overflow recovery, saturation, wrapping, or silent approximation.
• A semantically nonnegative field uses i64 and rejects -1.
• BigInt or BigUint is used when the problem definition itself requires arbitrary-precision values, for example Factoring or a problem whose mathematical object is an explicitly large bit string interpreted as an integer. This is a model-specific domain decision, not a generic intermediate-arithmetic policy.
• A user-provided approximate value such as 0.1 remains the supplied finite f64; it is not rationalized or scaled into an integer.
• JSON, serde, CLI, MCP, evaluation, and reductions must enforce the same domain contract.

Exact integer to approximate real

Mathematically, integers embed into the reals. In the implementation, an i64 → f64 conversion may lose precision and is therefore explicit and fallible.

Two boundaries must be treated separately:

1. Reduction boundary: an exact-to-approximate model conversion is valid only when that concrete model can establish that feasibility, equality, objective values, and objective ordering required by the reduction are preserved. The check is model-specific; this issue does not mandate one global formula such as n_terms * max|coefficient| ≤ 2^53.
2. Solver boundary: when pred solve invokes a double-based backend such as HiGHS, the adapter checks every exact integer value it converts and returns an explicit precision-loss error before invoking the backend if faithful conversion is impossible.

A blanket infallible as f64 cast is invalid at either boundary. Whether and how the reduction graph represents a fallible natural edge is a focused follow-up design problem, not part of the core representation migration.

Solver tolerances remain solver semantics; they are not mathematical reduction semantics.

Scope of this tracking issue

This issue owns:

• the normative numeric-domain table and rules in docs/src/design.md;
• the settled meanings of One, i64, and f64;
• the distinction between ordinary bounded exact integers and problem-native arbitrary-precision integers;
• the distinction between mathematical variants, internal representation, reductions, and solver conversion;
• the migration workstreams and their dependency order;
• consistency of the final repository-wide result.

This issue does not ask one implementation PR to touch every affected subsystem.

Follow-up workstreams

Each workstream should be implemented and verified independently. Large catalog migrations should be split further by model category when necessary.

• Exact weight migration: replace i32 exact weight variants with i64; update WeightElement, registrations, schemas, examples, tests, and documentation.
• ILP numeric domains: define and implement ILP variable and coefficient domains, preserving exact integer coefficients internally.
• QUBO and algebraic domains: separate exact integer coefficients from approximate real coefficients and update applicable reductions.
• Fallible exact-to-real reductions: define model-specific preservation checks and the error channel/graph representation for conversions that may fail.
• HiGHS solver boundary: perform faithful i64 → f64 conversion checks in the pred solve adapter and fail before backend invocation.
• Catalog field migration: migrate ordinary exact costs, capacities, times, bounds, and other nonnegative quantities from ad hoc primitive types to i64, split by category; retain problem-native arbitrary-precision domains where mathematically required.
• Enforcement: add focused numeric_contract tests, remove remaining unsafe casts, and enable the applicable Clippy cast lints once violations have been migrated.

Repository-wide acceptance criteria

The tracking issue is complete when the contract is documented and the follow-up migrations establish that:

• numeric variants describe mathematical domains rather than storage-width alternatives;
• One, i64, and finite f64 have consistent meanings across public construction paths;
• ordinary exact arithmetic remains checked i64 arithmetic, and oversized instances fail during construction or reduction;
• problem-native arbitrary-precision models retain BigInt or BigUint only where their mathematical definition requires it;
• exact-to-approximate conversions are explicit, checked, and fail with a precision error when their boundary condition is not met;
• no compatibility alias retains the superseded i32 exact-weight/coefficient variant;
• focused known-answer tests cover adjacent integers around 2^53, finite f64 validation, nonnegative-field validation, construction/reduction overflow, and solver-boundary rejection;
• the normal formatting, lint, and test checks pass.

Out of scope

• Implementing the entire migration in one PR.
• Introducing generic wider-intermediate arithmetic for ordinary i64 models.
• Accepting oversized ordinary instances by silently promoting them to i128, BigInt, or BigUint.
• Guessing an exact decimal or rational intention from an already parsed f64.
• Implementing an exact rational solver backend.
• Treating numerical solver tolerances as reduction semantics.
• Keeping duplicate numeric variants for backward compatibility.
• Requiring one universal precision certificate for every exact-to-approximate model conversion.

[isPANN]

Settled direction

We want variants to name mathematical domains, not storage width. i32 vs i64 is not a variant. We will still keep the existing catalog names One / i64 / f64 rather than renaming them to unit / integer / real. That avoids a repo-wide rename in CLI, JSON, paper, and examples. The names mean:

• One: unit weights
• i64: exact integer weights / coefficients (the single exact-integer representation)
• f64: approximate real weights / coefficients (finite f64 only)

i32 as a weight or coefficient variant goes away. It is replaced by i64, not kept as a compatibility alias.

Design decisions (to record in docs/src/design.md first)

1. Domains and one Rust type each

   • Index / length / dims: usize
   • Exact integer, including mathematically nonnegative quantities: i64 plus constructor checks
   • Approximate real input: finite f64 (reject NaN and infinities)
   • SAT literals and other protocol encodings: keep the encoding’s required type (i32 literals today)
   • Wider intermediates: i128 / BigInt, then a checked conversion back into i64

2. Nonnegative quantities use signed i64. Do not pick u64 just because a definition says “nonnegative”. -1 is a constructor error.

3. A numeric variant exists only if the instance set or a reduction precondition changes. Width, signedness, and solver storage are not variants.

4. Overflow is “this library cannot represent the instance”, not infeasibility. Prove representability at construction / reduction time; do not scatter width handling through evaluate() or the mathematical steps of a reduction. Encoding overflow such as 2^n is a reduction precondition and must fail explicitly.

5. i64 → f64 is fallible. Out of range is an error, not a silent cast. For a variant cast or reduction into an f64 model, check the linear forms that evaluate can compute, not only each coefficient: a sufficient certificate is n_terms * max|coeff| ≤ 2^53. Instances that fail remain valid i64 instances; they simply do not embed.

6. Do not rationalize user f64 values. A supplied 0.1 stays 0.1.

7. ILP

   • Two orthogonal variant dimensions: variable (bool | i64) and coefficient (i64 | f64).
   • Default: ILP { variable: bool, coefficient: i64 }.
   • Integer-coefficient ILP is the mathematical restriction “all constraint coefficients, right-hand sides, and objective coefficients are integers”. It is the default hub. A coefficient: f64 variant is also required, for sources whose weights are already approximate reals (QUBO<f64>, real-weighted graph problems, etc.).
   • Constraint, objective, and RHS coefficients share one coefficient domain per instance.
   • coefficient: i64 is a subtype of coefficient: f64 with the fallible embedding above. It is not an automatic lossless cast.
   • evaluate for coefficient: i64 uses exact integer arithmetic. evaluate for coefficient: f64 uses finite f64 and an explicit equality tolerance. Do not share one comparison rule.
   • HiGHS / good_lp conversion to double happens only in the solver adapter, with the same lossless check. That conversion is not a reduction-graph edge.

8. QUBO and other algebraic models follow the same split: exact integer coefficients stay i64 in-repo; f64 is the approximate variant, not the default dump for combinatorial reductions.

9. JSON / CLI / MCP / serde use the same types as the Rust constructors. No narrower intermediate type on the way in.

Step-by-step plan

Do this as a sequence of PRs. Each step should leave main buildable. No compatibility aliases for i32 weight/coefficient variants.

Step 0 — Write the contract

Update docs/src/design.md with the table above. Replace “element i32, total i64” with “exact integer is i64 for both elements and totals”. Record the ILP variable × coefficient lattice, the fallible i64 → f64 certificate, and the solver-adapter boundary.

Add the numeric_contract test module with the known-answer cases from this issue, even if some cases fail until later steps. That keeps the target observable.

Step 1 — Core numeric types

• Change WeightElement so exact weights are i64 with Sum = i64 (to_sum is identity). Keep One (Sum = i64) and f64 (Sum = f64).
• Rename the weight variant value "i32" → "i64" everywhere it is registered (VariantParam, declare_variants!, schemas, examples, paper loaders, CLI docs). Hierarchy remains One → i64 → f64, but the i64 → f64 cast is fallible under the 2^53 linear-form certificate.
• Add a small exact arithmetic helper (add / mul / sum → Result<i64, NumericOverflow>) and a lossless i64 → f64 conversion helper. Use these at constructors and reductions; not inside evaluate after a representability certificate has passed.
• Keep SAT literals as i32.

No ILP coefficient change in this step beyond what is forced by the weight-type rename.

Step 2 — ILP / QUBO hubs

• Parameterize ILP by variable domain and coefficient domain. Default coefficients are i64.
• Register coefficient: i64 (default) and coefficient: f64. Reuse current bool / integer variable names, with the integer variable domain stored as i64 rather than i32.
• Integer-coefficient evaluate becomes exact. Real-coefficient evaluate keeps finite f64 semantics.
• Move every as f64 in combinatorial *_ilp.rs rules onto the integer-coefficient hub. Only sources that are already f64 target coefficient: f64.
• QUBO: integer-coefficient variant for exact reductions; keep QUBO<f64> as the approximate variant. QUBO<f64> → ILP goes to coefficient: f64.

Step 3 — Catalog storage cleanup

Mechanically migrate remaining model fields that are exact integers onto i64:

• replace ad hoc u64 nonnegative fields with i64 + sign checks
• replace leftover i32 costs / bounds / capacities
• constructors reject -1 on nonnegative fields and reject NaN / infinities on f64 fields
• construction-time representability certificates so evaluate does not need overflow branches

Do this per category (graph, set, scheduling, algebraic) if a single PR is too large.

Step 4 — Solver adapter

HiGHS / good_lp is the only place that converts exact i64 coefficients to f64. Lossless or explicit error, before the backend is invoked. Known-answer case 1 and case 5 from this issue must pass here.

Step 5 — Enforcement

• Make cargo test --all-features numeric_contract pass, including the negative controls in this issue.
• Turn on the Clippy cast lints listed in this issue after the remaining as conversions are gone or rewritten as proven-safe from / try_from.
• make fmt-check, make clippy, make test.

Out of scope for this sequence

• Renaming One / i64 / f64 to unit / integer / real
• Exact rational coefficients or an exact rational solver
• Treating solver tolerances as reduction semantics
• Keeping i32 as a second exact-integer variant

[isPANN]

Operational rule

One representation per domain, then error instead of converting.

Models, reductions, evaluate, serde, CLI, and MCP must not cast between i32 / i64 / u64 / f64 / usize to “make the types line up”. If a value is not already valid in the destination domain, fail with an explicit range/overflow/precision error.

The only allowed numeric conversions are:

• usize for indices and collection sizes, via try_from at the boundary where a count becomes an index
• SAT / protocol encodings that already require a compact signed type
• the solver adapter’s lossless i64 → f64 check, which is not a reduction

In particular: do not widen i32 to i64, do not store nonnegative exact integers as u64 and later convert to signed, and do not write as f64 in a reduction because ILP or HiGHS happens to use doubles. If the instance does not fit the chosen domain, it is a construction or reduction error.