solverpilot 0.1__py3-none-any.whl

solverpilot/conic/ir.py

@@ -0,0 +1,299 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+import hashlib
+import json
+from types import MappingProxyType
+from typing import Any, Mapping
+
+import numpy as np
+from scipy import sparse
+
+from solverpilot.problem import ConvexityStatus, ObjectiveSense, QuadraticProblem, VariableDomain
+from solverpilot.problem.linear import _readonly_csr, _readonly_f64, _require_bound_directions, _require_finite
+from solverpilot.problem.quadratic import _canonicalize_hessian, _check_convexity
+from solverpilot.problem.hashing import _hash_parts, hash_sparse_matrix
+
+
+class ConeKind(str, Enum):
+    SECOND_ORDER = "second_order"
+    ROTATED_SECOND_ORDER = "rotated_second_order"
+    POSITIVE_SEMIDEFINITE = "positive_semidefinite"
+
+
+def _readonly_shape(value: tuple[int, ...]) -> tuple[int, ...]:
+    out = tuple(int(x) for x in value)
+    if not out or any(x <= 0 for x in out):
+        raise ValueError("cone output_shape must contain positive dimensions")
+    return out
+
+
+def _hash_array(arr: np.ndarray) -> str:
+    a = np.ascontiguousarray(np.asarray(arr, dtype=np.float64))
+    h = hashlib.sha256()
+    h.update(str(a.shape).encode())
+    h.update(a.tobytes())
+    return h.hexdigest()
+
+
+def _json_float(value: float) -> float | str:
+    v = float(value)
+    if np.isposinf(v): return "+inf"
+    if np.isneginf(v): return "-inf"
+    if np.isnan(v): raise ValueError("NaN cannot be serialized")
+    return v
+
+
+def _csr_dict(matrix: sparse.csr_matrix) -> dict[str, Any]:
+    m = sparse.csr_matrix(matrix)
+    return {
+        "shape": [int(m.shape[0]), int(m.shape[1])],
+        "indptr": [int(x) for x in m.indptr],
+        "indices": [int(x) for x in m.indices],
+        "data": [float(x) for x in m.data],
+    }
+
+
+@dataclass(frozen=True, slots=True)
+class ConeAffineBlock:
+    """Affine cone membership block ``F x + g in K``.
+
+    For vector cones, ``output_shape`` is ``(dim,)``. For PSD cones it is
+    ``(n, n)`` and the flattened affine map is row-major. The block itself is
+    solver-independent; backend-specific vectorization/scaling is performed by
+    the adapter.
+    """
+
+    kind: ConeKind
+    F: sparse.csr_matrix
+    g: np.ndarray
+    output_shape: tuple[int, ...]
+    source_id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+    structural_hash: str = field(init=False)
+    data_hash: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        kind = ConeKind(self.kind)
+        F = _readonly_csr(self.F)
+        g = _readonly_f64(self.g, name="cone offset")
+        _require_finite(g, name="cone offset")
+        shape = _readonly_shape(self.output_shape)
+        expected = int(np.prod(shape, dtype=np.int64))
+        if F.shape[0] != expected:
+            raise ValueError(f"cone F has {F.shape[0]} rows but output_shape requires {expected}")
+        if g.shape != (expected,):
+            raise ValueError(f"cone g must have shape ({expected},), got {g.shape}")
+        if kind is ConeKind.SECOND_ORDER:
+            if len(shape) != 1 or shape[0] < 2:
+                raise ValueError("second-order cone requires vector dimension >= 2")
+        elif kind is ConeKind.ROTATED_SECOND_ORDER:
+            if len(shape) != 1 or shape[0] < 3:
+                raise ValueError("rotated second-order cone requires vector dimension >= 3")
+        elif kind is ConeKind.POSITIVE_SEMIDEFINITE:
+            if len(shape) != 2 or shape[0] != shape[1]:
+                raise ValueError("PSD cone requires a square matrix output_shape")
+        else:  # pragma: no cover - Enum guards this
+            raise ValueError(kind)
+        object.__setattr__(self, "kind", kind)
+        object.__setattr__(self, "F", F)
+        object.__setattr__(self, "g", g)
+        object.__setattr__(self, "output_shape", shape)
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+        structural = _hash_parts([
+            kind.value.encode(),
+            json.dumps(shape).encode(),
+            hash_sparse_matrix(F.astype(bool)).encode(),
+        ])
+        data = _hash_parts([
+            structural.encode(),
+            hash_sparse_matrix(F).encode(),
+            _hash_array(g).encode(),
+        ])
+        object.__setattr__(self, "structural_hash", structural)
+        object.__setattr__(self, "data_hash", data)
+
+    def to_canonical_dict(self) -> dict[str, Any]:
+        return {
+            "kind": self.kind.value,
+            "F": _csr_dict(self.F),
+            "g": [float(x) for x in self.g],
+            "output_shape": list(self.output_shape),
+            "source_id": self.source_id,
+            "metadata": dict(self.metadata),
+            "structural_hash": self.structural_hash,
+            "data_hash": self.data_hash,
+        }
+
+    @property
+    def n_variables(self) -> int:
+        return int(self.F.shape[1])
+
+    @property
+    def dimension(self) -> int:
+        return int(self.F.shape[0])
+
+    def value(self, x: np.ndarray) -> np.ndarray:
+        vec = np.asarray(self.F @ np.asarray(x, dtype=np.float64).reshape(-1), dtype=np.float64).reshape(-1) + self.g
+        return vec.reshape(self.output_shape)
+
+
+@dataclass(frozen=True, slots=True)
+class ConicProblem:
+    """Convex quadratic objective + linear rows + affine cone memberships."""
+
+    P: sparse.csr_matrix
+    q: np.ndarray
+    A: sparse.csr_matrix
+    variable_lower: np.ndarray
+    variable_upper: np.ndarray
+    constraint_lower: np.ndarray
+    constraint_upper: np.ndarray
+    cones: tuple[ConeAffineBlock, ...]
+    objective_sense: ObjectiveSense = ObjectiveSense.MINIMIZE
+    objective_offset: float = 0.0
+    name: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict, compare=False, repr=False)
+    convexity_status: ConvexityStatus = ConvexityStatus.UNKNOWN
+    structural_hash: str = field(init=False)
+    data_hash: str = field(init=False)
+
+    def __post_init__(self) -> None:
+        P_raw = _readonly_csr(self.P)
+        q = _readonly_f64(self.q, name="q")
+        A = _readonly_csr(self.A)
+        vl = _readonly_f64(self.variable_lower, name="variable_lower")
+        vu = _readonly_f64(self.variable_upper, name="variable_upper")
+        cl = _readonly_f64(self.constraint_lower, name="constraint_lower")
+        cu = _readonly_f64(self.constraint_upper, name="constraint_upper")
+        sense = ObjectiveSense(self.objective_sense)
+        if sense is not ObjectiveSense.MINIMIZE:
+            raise ValueError("P6 ConicProblem supports convex minimization only")
+        m, n = A.shape
+        if P_raw.shape != (n, n):
+            raise ValueError(f"P must have shape ({n}, {n})")
+        P = _canonicalize_hessian(P_raw)
+        if q.shape != (n,) or vl.shape != (n,) or vu.shape != (n,):
+            raise ValueError("q/variable bounds must match n_variables")
+        _require_finite(q, name="q")
+        if cl.shape != (m,) or cu.shape != (m,):
+            raise ValueError("linear constraint bounds must match A rows")
+        if np.any(vl > vu) or np.any(cl > cu):
+            raise ValueError("inconsistent bounds")
+        _require_bound_directions(vl, vu, label="variable")
+        _require_bound_directions(cl, cu, label="constraint")
+        if not np.isfinite(float(self.objective_offset)):
+            raise ValueError("objective_offset must be finite")
+        cones = tuple(self.cones)
+        if not cones:
+            raise ValueError("ConicProblem requires at least one cone block")
+        for block in cones:
+            if block.n_variables != n:
+                raise ValueError("cone block variable dimension mismatch")
+        status = ConvexityStatus(self.convexity_status)
+        if status is ConvexityStatus.UNKNOWN:
+            status = _check_convexity(P)
+        elif status is ConvexityStatus.CONFIRMED and _check_convexity(P) is not ConvexityStatus.CONFIRMED:
+            raise ValueError("conic quadratic objective is not independently confirmed convex")
+        if status is ConvexityStatus.REJECTED:
+            raise ValueError("conic quadratic objective is not convex")
+        object.__setattr__(self, "P", P)
+        object.__setattr__(self, "q", q)
+        object.__setattr__(self, "A", A)
+        object.__setattr__(self, "variable_lower", vl)
+        object.__setattr__(self, "variable_upper", vu)
+        object.__setattr__(self, "constraint_lower", cl)
+        object.__setattr__(self, "constraint_upper", cu)
+        object.__setattr__(self, "cones", cones)
+        object.__setattr__(self, "objective_sense", sense)
+        object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
+        object.__setattr__(self, "convexity_status", status)
+        structural = _hash_parts([
+            b"solverpilot-conic-ir-v1",
+            hash_sparse_matrix(P.astype(bool)).encode(),
+            hash_sparse_matrix(A.astype(bool)).encode(),
+            *(c.structural_hash.encode() for c in cones),
+        ])
+        data = _hash_parts([
+            structural.encode(),
+            hash_sparse_matrix(P).encode(),
+            _hash_array(q).encode(),
+            hash_sparse_matrix(A).encode(),
+            _hash_array(vl).encode(), _hash_array(vu).encode(),
+            _hash_array(cl).encode(), _hash_array(cu).encode(),
+            *(c.data_hash.encode() for c in cones),
+            sense.value.encode(), float(self.objective_offset).hex().encode(),
+        ])
+        object.__setattr__(self, "structural_hash", structural)
+        object.__setattr__(self, "data_hash", data)
+
+    def to_canonical_dict(self) -> dict[str, Any]:
+        return {
+            "schema": "solverpilot.conic-ir.v1",
+            "P": _csr_dict(self.P),
+            "q": [float(x) for x in self.q],
+            "A": _csr_dict(self.A),
+            "variable_lower": [_json_float(x) for x in self.variable_lower],
+            "variable_upper": [_json_float(x) for x in self.variable_upper],
+            "constraint_lower": [_json_float(x) for x in self.constraint_lower],
+            "constraint_upper": [_json_float(x) for x in self.constraint_upper],
+            "cones": [c.to_canonical_dict() for c in self.cones],
+            "objective_sense": self.objective_sense.value,
+            "objective_offset": float(self.objective_offset),
+            "name": self.name,
+            "metadata": dict(self.metadata),
+            "convexity_status": self.convexity_status.value,
+            "structural_hash": self.structural_hash,
+            "data_hash": self.data_hash,
+        }
+
+    @property
+    def n_variables(self) -> int:
+        return int(self.A.shape[1])
+
+    @property
+    def n_linear_constraints(self) -> int:
+        return int(self.A.shape[0])
+
+    @property
+    def n_cone_constraints(self) -> int:
+        return len(self.cones)
+
+    def objective_value(self, x: np.ndarray) -> float:
+        x = np.asarray(x, dtype=np.float64).reshape(-1)
+        return float(0.5 * x @ (self.P @ x) + self.q @ x + self.objective_offset)
+
+    @classmethod
+    def from_data(
+        cls,
+        *,
+        P: sparse.spmatrix | np.ndarray,
+        q: np.ndarray,
+        A: sparse.spmatrix | np.ndarray,
+        variable_lower: np.ndarray,
+        variable_upper: np.ndarray,
+        constraint_lower: np.ndarray,
+        constraint_upper: np.ndarray,
+        cones: tuple[ConeAffineBlock, ...] | list[ConeAffineBlock],
+        objective_offset: float = 0.0,
+        name: str | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        verify_convexity: bool = True,
+    ) -> "ConicProblem":
+        P_csr = sparse.csr_matrix(P, dtype=np.float64)
+        status = _check_convexity(P_csr) if verify_convexity else ConvexityStatus.UNKNOWN
+        return cls(
+            P=P_csr,
+            q=np.asarray(q, dtype=np.float64),
+            A=sparse.csr_matrix(A, dtype=np.float64),
+            variable_lower=np.asarray(variable_lower, dtype=np.float64),
+            variable_upper=np.asarray(variable_upper, dtype=np.float64),
+            constraint_lower=np.asarray(constraint_lower, dtype=np.float64),
+            constraint_upper=np.asarray(constraint_upper, dtype=np.float64),
+            cones=tuple(cones),
+            objective_offset=float(objective_offset),
+            name=name,
+            metadata={} if metadata is None else metadata,
+            convexity_status=status,
+        )

solverpilot/conic/validation.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import numpy as np
+
+from solverpilot.validate.core import _max_violation, _scaled_feasibility
+
+from .ir import ConeKind, ConicProblem
+
+
+@dataclass(frozen=True, slots=True)
+class ConeCheck:
+    source_id: str | None
+    kind: ConeKind
+    valid: bool
+    violation: float
+    detail: str
+
+
+@dataclass(frozen=True, slots=True)
+class ConicValidationReport:
+    valid: bool
+    max_variable_violation: float
+    max_linear_violation: float
+    max_cone_violation: float
+    cone_checks: tuple[ConeCheck, ...]
+    objective: float | None
+
+
+def _scaled_tol(atol: float, rtol: float, magnitude: float) -> float:
+    return float(atol + rtol * max(1.0, abs(float(magnitude))))
+
+
+def _componentwise_feasibility(
+    values: np.ndarray,
+    lower: np.ndarray,
+    upper: np.ndarray,
+    *,
+    atol: float,
+    rtol: float,
+    extra_scale: np.ndarray | None = None,
+) -> tuple[float, bool]:
+    _, ok = _scaled_feasibility(values, lower, upper, atol=atol, rtol=rtol, extra_scale=extra_scale)
+    return _max_violation(values, lower, upper), ok
+
+
+def _psd_check(M: np.ndarray, *, atol: float, rtol: float) -> tuple[bool, float, float, float]:
+    """Check symmetry and PSD after local congruence scaling.
+
+    The congruence transform preserves inertia, while removing the dangerous
+    dependence on an unrelated huge matrix entry that a single global norm creates.
+    """
+    if M.size == 0:
+        return True, 0.0, 0.0, 0.0
+    abs_m = np.abs(M)
+    sym_allowed = float(atol) + float(rtol) * np.maximum(1.0, np.maximum(abs_m, abs_m.T))
+    asym_matrix = np.abs(M - M.T)
+    asym = float(np.max(asym_matrix))
+    symmetry_ok = bool(np.all(asym_matrix <= sym_allowed))
+    sym = 0.5 * M + 0.5 * M.T
+    eigmin = float(np.linalg.eigvalsh(sym)[0])
+
+    row_scale = np.maximum(1.0, np.max(np.abs(sym), axis=1))
+    inv_sqrt = 1.0 / np.sqrt(row_scale)
+    scaled = inv_sqrt[:, None] * sym * inv_sqrt[None, :]
+    scaled_eigmin = float(np.linalg.eigvalsh(scaled)[0])
+    scaled_norm = float(np.linalg.norm(scaled, ord=np.inf))
+    psd_tol = float(atol) + float(rtol) * max(1.0, scaled_norm)
+    return bool(symmetry_ok and scaled_eigmin >= -psd_tol), asym, eigmin, scaled_eigmin
+
+
+def _cone_check(kind: ConeKind, value: np.ndarray, *, atol: float, rtol: float, source_id: str | None) -> ConeCheck:
+    if not np.isfinite(value).all():
+        return ConeCheck(source_id, kind, False, float("inf"), "non-finite cone activity")
+    if kind is ConeKind.SECOND_ORDER:
+        y = np.asarray(value, dtype=float).reshape(-1)
+        t = float(y[0]); norm = math.hypot(*y[1:])
+        viol = max(0.0, norm - t)
+        tol = _scaled_tol(atol, rtol, max(abs(t), norm))
+        return ConeCheck(source_id, kind, math.isfinite(norm) and math.isfinite(tol) and viol <= tol, viol, f"norm={norm:.17g}, t={t:.17g}, tol={tol:.3g}")
+    if kind is ConeKind.ROTATED_SECOND_ORDER:
+        y = np.asarray(value, dtype=float).reshape(-1)
+        u = float(y[0]); v = float(y[1])
+        scale = max(1.0, float(np.max(np.abs(y))))
+        z = y / scale
+        norm2 = float(np.dot(z[2:], z[2:]))
+        product = 2.0 * float(z[0]) * float(z[1])
+        gap = norm2 - product
+        # Compare the squared inequality in normalized coordinates, avoiding
+        # inf - inf. Nonnegativity uses separate, unsquared tolerances.
+        tol = (atol / scale) / scale + rtol * max((1.0 / scale) / scale, norm2, abs(product))
+        nonnegative = u >= -_scaled_tol(atol, rtol, u) and v >= -_scaled_tol(atol, rtol, v)
+        viol = max(0.0, -u, -v, (max(0.0, gap) * scale) * scale)
+        return ConeCheck(source_id, kind, nonnegative and gap <= tol, viol, f"u={u:.17g}, v={v:.17g}, normalized_gap={gap:.17g}, tol={tol:.3g}")
+    if kind is ConeKind.POSITIVE_SEMIDEFINITE:
+        M = np.asarray(value, dtype=float)
+        ok, asym, eigmin, scaled_eigmin = _psd_check(M, atol=atol, rtol=rtol)
+        viol = max(asym, max(0.0, -eigmin))
+        return ConeCheck(
+            source_id,
+            kind,
+            ok,
+            viol,
+            f"asym={asym:.3g}, eigmin={eigmin:.17g}, scaled_eigmin={scaled_eigmin:.17g}",
+        )
+    raise AssertionError(kind)
+
+
+def validate_conic_solution(
+    problem: ConicProblem,
+    x: np.ndarray | None,
+    *,
+    atol: float = 1e-7,
+    rtol: float = 1e-7,
+) -> ConicValidationReport:
+    for name, raw in (("atol", atol), ("rtol", rtol)):
+        if isinstance(raw, bool) or type(raw) not in (int, float) or not np.isfinite(float(raw)) or float(raw) < 0:
+            raise ValueError(f"{name} must be finite and non-negative")
+    atol = float(atol)
+    rtol = float(rtol)
+    if x is None:
+        return ConicValidationReport(False, float("inf"), float("inf"), float("inf"), (), None)
+    x = np.asarray(x, dtype=np.float64).reshape(-1)
+    if x.shape != (problem.n_variables,) or not np.all(np.isfinite(x)):
+        return ConicValidationReport(False, float("inf"), float("inf"), float("inf"), (), None)
+
+    var_viol, vars_ok = _componentwise_feasibility(
+        x,
+        problem.variable_lower,
+        problem.variable_upper,
+        atol=atol,
+        rtol=rtol,
+    )
+    ax = np.asarray(problem.A @ x, dtype=float).reshape(-1)
+    row_scale = np.asarray(np.abs(problem.A) @ np.abs(x), dtype=np.float64).reshape(-1)
+    lin_viol, linear_ok = _componentwise_feasibility(
+        ax,
+        problem.constraint_lower,
+        problem.constraint_upper,
+        atol=atol,
+        rtol=rtol,
+        extra_scale=row_scale,
+    )
+    checks = tuple(_cone_check(c.kind, c.value(x), atol=atol, rtol=rtol, source_id=c.source_id) for c in problem.cones)
+    cone_viol = max((c.violation for c in checks), default=0.0)
+    objective = problem.objective_value(x)
+    valid = bool(vars_ok and linear_ok and all(c.valid for c in checks) and np.isfinite(objective))
+    return ConicValidationReport(valid, var_viol, lin_viol, cone_viol, checks, objective)

solverpilot/cp/__init__.py

@@ -0,0 +1,7 @@
+from .ir import *
+from .model import CPModel, CPIntVar, CPBoolVar, CPIntervalVar, CPLinearExpr
+from .validate import CPValidationReport, validate_cp_solution
+from .reference import CPSolveResult, ReferenceCPBackend
+from .ortools_backend import ORToolsCPSATBackend, VERIFIED_ORTOOLS_VERSION
+from .conformance import CPConformanceCheck, CPConformanceReport, reference_cp_conformance, ortools_cp_sat_conformance
+__all__=[n for n in globals() if n.startswith('CP') or n in {'ReferenceCPBackend','ORToolsCPSATBackend','VERIFIED_ORTOOLS_VERSION','validate_cp_solution','reference_cp_conformance','ortools_cp_sat_conformance'}]

solverpilot/cp/conformance.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from .model import CPModel
+from .reference import ReferenceCPBackend
+from .ortools_backend import ORToolsCPSATBackend, VERIFIED_ORTOOLS_VERSION
+
+@dataclass(frozen=True, slots=True)
+class CPConformanceCheck:
+    name:str; passed:bool; detail:str
+@dataclass(frozen=True, slots=True)
+class CPConformanceReport:
+    backend:str; available:bool; passed:bool; checks:tuple[CPConformanceCheck,...]; verified_version:str|None=None
+
+def reference_cp_conformance():
+    checks=[]
+    # Latin/permutation core.
+    m=CPModel(); xs=[m.int_var(1,3,f'x{i}') for i in range(3)]; m.add_all_different(xs); m.add(xs[0]==1); m.minimize(xs[2])
+    r=m.solve(ReferenceCPBackend()); checks.append(CPConformanceCheck('all-different-linear',r.optimality_proven and r.validation.valid and r.objective==2,str(r.assignment)))
+    # Element/table/exactly-one.
+    m=CPModel(); i=m.int_var(0,2,'i'); t=m.int_var(4,9,'t'); bs=[m.bool_var(f'b{k}') for k in range(3)]; m.add_element(i,[4,7,9],t); m.add_allowed_assignments([i,t],[(0,4),(2,9)]); m.add_exactly_one(bs); m.add(i==2); r=m.solve(); checks.append(CPConformanceCheck('element-table-exactly-one',r.validation.valid and r.assignment[t.var_id]==9,str(r.assignment)))
+    # Scheduling core.
+    m=CPModel(); s1=m.int_var(0,3,'s1'); s2=m.int_var(0,3,'s2'); a=m.interval_var(s1,2,'a'); b=m.interval_var(s2,2,'b'); m.add_no_overlap([a,b]); m.minimize(s1+s2); r=m.solve(); checks.append(CPConformanceCheck('interval-no-overlap',r.optimality_proven and r.validation.valid and r.objective==2,str(r.assignment)))
+    return CPConformanceReport('reference-cp-enumeration',True,all(c.passed for c in checks),tuple(checks),'p9-reference-v1')
+
+def ortools_cp_sat_conformance():
+    b=ORToolsCPSATBackend();
+    if not b.is_available():
+        return CPConformanceReport(b.name,False,False,(CPConformanceCheck('availability',False,f'OR-Tools {VERIFIED_ORTOOLS_VERSION} unavailable in release runtime'),),VERIFIED_ORTOOLS_VERSION)
+    # Same representative model against adapter.
+    m=CPModel(); x=[m.int_var(1,3,f'x{i}') for i in range(3)]; m.add_all_different(x); m.add(x[0]==1); m.minimize(x[2]); r=m.solve(b)
+    ok=r.optimality_proven and r.validation.valid and r.objective==2
+    return CPConformanceReport(b.name,True,ok,(CPConformanceCheck('solve-and-independent-validation',ok,str(r.assignment)),),VERIFIED_ORTOOLS_VERSION)

solverpilot/cp/cp-ir-v1.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema":"https://json-schema.org/draft/2020-12/schema",
+  "$id":"solverpilot.cp-ir.v1",
+  "type":"object",
+  "required":["schema_version","variables","intervals","constraints","objective_sense"],
+  "properties":{
+    "schema_version":{"const":"solverpilot.cp-ir.v1"},
+    "variables":{"type":"array"},
+    "intervals":{"type":"array"},
+    "constraints":{"type":"array"},
+    "objective_sense":{"enum":["minimize","maximize"]}
+  }
+}

solverpilot/cp/ir.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import Enum
+from types import MappingProxyType
+from typing import Any, Mapping
+import hashlib, json
+
+class CPObjectiveSense(str, Enum):
+    MINIMIZE='minimize'
+    MAXIMIZE='maximize'
+
+@dataclass(frozen=True, slots=True)
+class CPIntVarIR:
+    var_id:int
+    name:str
+    domain:tuple[int,...]
+    kind:str='int'
+    derived_from:tuple[int,int] | None=None  # (start_var_id, fixed_size)
+    def __post_init__(self):
+        if not self.domain: raise ValueError('CP variable domain cannot be empty')
+        vals=tuple(sorted(set(int(v) for v in self.domain)))
+        object.__setattr__(self,'domain',vals)
+        if self.kind not in {'int','bool'}: raise ValueError('invalid CP variable kind')
+        if self.kind=='bool' and not set(vals).issubset({0,1}): raise ValueError('bool domain must be subset of {0,1}')
+
+@dataclass(frozen=True, slots=True)
+class CPLinearExprIR:
+    terms:tuple[tuple[int,int],...]=()
+    constant:int=0
+    def __post_init__(self):
+        merged={}
+        for vid,c in self.terms:
+            merged[int(vid)]=merged.get(int(vid),0)+int(c)
+        object.__setattr__(self,'terms',tuple(sorted((v,c) for v,c in merged.items() if c)))
+        object.__setattr__(self,'constant',int(self.constant))
+
+@dataclass(frozen=True, slots=True)
+class CPIntervalIR:
+    interval_id:int
+    name:str
+    start_var:int
+    size:int
+    end_var:int
+    def __post_init__(self):
+        if self.size < 0: raise ValueError('interval size must be nonnegative')
+
+@dataclass(frozen=True, slots=True)
+class CPLinearConstraintIR:
+    expr:CPLinearExprIR; lower:int|None=None; upper:int|None=None; kind:str='linear'
+@dataclass(frozen=True, slots=True)
+class CPAllDifferentIR:
+    var_ids:tuple[int,...]; kind:str='all_different'
+@dataclass(frozen=True, slots=True)
+class CPExactlyOneIR:
+    literal_ids:tuple[int,...]; kind:str='exactly_one'
+@dataclass(frozen=True, slots=True)
+class CPTableIR:
+    var_ids:tuple[int,...]; allowed_tuples:tuple[tuple[int,...],...]; kind:str='table'
+@dataclass(frozen=True, slots=True)
+class CPElementIR:
+    index_var:int; values:tuple[int,...]; target_var:int; kind:str='element'
+@dataclass(frozen=True, slots=True)
+class CPCircuitIR:
+    arcs:tuple[tuple[int,int,int],...]; kind:str='circuit' # tail, head, bool var
+@dataclass(frozen=True, slots=True)
+class CPNoOverlapIR:
+    interval_ids:tuple[int,...]; kind:str='no_overlap'
+@dataclass(frozen=True, slots=True)
+class CPCumulativeIR:
+    interval_ids:tuple[int,...]; demands:tuple[int,...]; capacity:int; kind:str='cumulative'
+
+CPConstraintIR = CPLinearConstraintIR|CPAllDifferentIR|CPExactlyOneIR|CPTableIR|CPElementIR|CPCircuitIR|CPNoOverlapIR|CPCumulativeIR
+
+@dataclass(frozen=True, slots=True)
+class CPProblem:
+    variables:tuple[CPIntVarIR,...]
+    intervals:tuple[CPIntervalIR,...]
+    constraints:tuple[CPConstraintIR,...]
+    objective:CPLinearExprIR|None=None
+    objective_sense:CPObjectiveSense=CPObjectiveSense.MINIMIZE
+    name:str|None=None
+    metadata:Mapping[str,Any]=field(default_factory=dict)
+    schema_version:str='solverpilot.cp-ir.v1'
+    def __post_init__(self):
+        ids=[v.var_id for v in self.variables]
+        if len(ids)!=len(set(ids)): raise ValueError('duplicate CP variable id')
+        iids=[i.interval_id for i in self.intervals]
+        if len(iids)!=len(set(iids)): raise ValueError('duplicate interval id')
+        var_map={v.var_id:v for v in self.variables}
+        interval_map={i.interval_id:i for i in self.intervals}
+
+        def require_var(vid:int, where:str):
+            if int(vid) not in var_map:
+                raise ValueError(f'{where} references unknown CP variable id {vid}')
+
+        def require_bool(vid:int, where:str):
+            require_var(vid,where)
+            v=var_map[int(vid)]
+            if v.kind!='bool' or not set(v.domain).issubset({0,1}):
+                raise ValueError(f'{where} requires Boolean literal variable id {vid}')
+
+        def require_expr(expr:CPLinearExprIR, where:str):
+            for vid,_ in expr.terms: require_var(vid,where)
+
+        for v in self.variables:
+            if v.derived_from is not None:
+                require_var(v.derived_from[0],f'variable {v.var_id} derived_from')
+        for i in self.intervals:
+            require_var(i.start_var,f'interval {i.interval_id} start_var')
+            require_var(i.end_var,f'interval {i.interval_id} end_var')
+        if self.objective is not None: require_expr(self.objective,'objective')
+
+        for c in self.constraints:
+            where=f'{c.kind} constraint'
+            if isinstance(c,CPLinearConstraintIR):
+                require_expr(c.expr,where)
+            elif isinstance(c,CPAllDifferentIR):
+                for vid in c.var_ids: require_var(vid,where)
+            elif isinstance(c,CPExactlyOneIR):
+                if not c.literal_ids: raise ValueError('exactly_one requires at least one literal')
+                for vid in c.literal_ids: require_bool(vid,where)
+            elif isinstance(c,CPTableIR):
+                for vid in c.var_ids: require_var(vid,where)
+                if any(len(t)!=len(c.var_ids) for t in c.allowed_tuples):
+                    raise ValueError('table tuple arity mismatch')
+            elif isinstance(c,CPElementIR):
+                require_var(c.index_var,where); require_var(c.target_var,where)
+                if not c.values: raise ValueError('element values cannot be empty')
+            elif isinstance(c,CPCircuitIR):
+                for _,_,vid in c.arcs: require_bool(vid,where)
+            elif isinstance(c,CPNoOverlapIR):
+                for iid in c.interval_ids:
+                    if iid not in interval_map: raise ValueError(f'{where} references unknown interval id {iid}')
+            elif isinstance(c,CPCumulativeIR):
+                if len(c.interval_ids)!=len(c.demands): raise ValueError('cumulative demands must align with interval_ids')
+                if c.capacity < 0 or any(int(d)<0 for d in c.demands):
+                    raise ValueError('cumulative demands/capacity must be nonnegative')
+                for iid in c.interval_ids:
+                    if iid not in interval_map: raise ValueError(f'{where} references unknown interval id {iid}')
+        object.__setattr__(self,'metadata',MappingProxyType(dict(self.metadata)))
+    @property
+    def variable_map(self): return {v.var_id:v for v in self.variables}
+    @property
+    def interval_map(self): return {i.interval_id:i for i in self.intervals}
+    @property
+    def base_variables(self): return tuple(v for v in self.variables if v.derived_from is None)
+    def canonical_dict(self):
+        def expr(e): return {'terms':[list(x) for x in e.terms],'constant':e.constant}
+        cs=[]
+        for c in self.constraints:
+            d={'kind':c.kind}
+            if isinstance(c,CPLinearConstraintIR): d.update(expr=expr(c.expr),lower=c.lower,upper=c.upper)
+            elif isinstance(c,CPAllDifferentIR): d['var_ids']=list(c.var_ids)
+            elif isinstance(c,CPExactlyOneIR): d['literal_ids']=list(c.literal_ids)
+            elif isinstance(c,CPTableIR): d.update(var_ids=list(c.var_ids),allowed_tuples=[list(t) for t in c.allowed_tuples])
+            elif isinstance(c,CPElementIR): d.update(index_var=c.index_var,values=list(c.values),target_var=c.target_var)
+            elif isinstance(c,CPCircuitIR): d['arcs']=[list(a) for a in c.arcs]
+            elif isinstance(c,CPNoOverlapIR): d['interval_ids']=list(c.interval_ids)
+            elif isinstance(c,CPCumulativeIR): d.update(interval_ids=list(c.interval_ids),demands=list(c.demands),capacity=c.capacity)
+            cs.append(d)
+        return {'schema_version':self.schema_version,'name':self.name,'variables':[{'id':v.var_id,'name':v.name,'domain':list(v.domain),'kind':v.kind,'derived_from':None if v.derived_from is None else list(v.derived_from)} for v in self.variables],'intervals':[{'id':i.interval_id,'name':i.name,'start_var':i.start_var,'size':i.size,'end_var':i.end_var} for i in self.intervals],'constraints':cs,'objective':None if self.objective is None else expr(self.objective),'objective_sense':self.objective_sense.value,'metadata':dict(self.metadata)}
+    @property
+    def structural_hash(self):
+        d=self.canonical_dict();
+        for v in d['variables']: v['domain']=['<domain>']
+        d['metadata']={}
+        return hashlib.sha256(json.dumps(d,sort_keys=True,separators=(',',':')).encode()).hexdigest()
+    @property
+    def data_hash(self):
+        return hashlib.sha256(json.dumps(self.canonical_dict(),sort_keys=True,separators=(',',':')).encode()).hexdigest()