@ohtaman/washi 0.4.0 → 0.5.0

package/dist/types/modeler/model.d.ts

@@ -1,131 +1,330 @@
-import { type OptimizationSense, type SolverStatus, type SolveOptions, type SolverSolution } from "./types.js";
+import { type OptimizationSense, type SolverStatus, type TerminationStatus, type SolveOptions, type SolverSolution, type CheckResult } from "./types.js";
+import { type ObjectiveSpec } from "./objective.js";
 import { Var } from "./variable.js";
 import { LinExpr } from "./expression.js";
 import { QuadExpr } from "./quad-expr.js";
 import { Constraint } from "./constraint.js";
 import { BoolVar, BoolExpr } from "./boolean-expr.js";
 import { type Solver } from "./solvers/index.js";
+import { type SolutionValidationOptions, type SolutionValidationReport } from "./solution-validator.js";
+/**
+ * Valid items that can be added as a constraint to a model.
+ * Raw mathematical expressions (LinExpr, QuadExpr) without comparisons are strictly prohibited.
+ */
+export type ConstraintItem = Constraint | BoolExpr | string;
 export interface ModelOptions {
+    /** Optional model name (default: `"OptimizationModel"`). */
     name?: string;
+    /** Default optimization direction (`"Minimize"` or `"Maximize"`, default: `"Minimize"`). */
     sense?: OptimizationSense;
+    /** Solver instance or registered solver name (`"highs"`, `"glpk"`, `"z3"`, or custom solver). */
     solver?: Solver | string;
 }
 export interface BoundsOptions {
+    /** Explicit name for a scalar variable, or fallback prefix for indexed variable containers. */
     name?: string;
+    /** Name prefix when creating unnamed scalar variables or indexed variable containers (default: `"x"`). */
     prefix?: string;
+    /** Lower bound (default: `0`; `-Infinity` allowed for free lower bound; `+Infinity` and `NaN` rejected). */
     lb?: number;
+    /** Upper bound (default: `Infinity`; `-Infinity` and `NaN` rejected; must satisfy `lb <= ub`). */
     ub?: number;
+    /**
+     * Optional finite primal initial value (MIP start / warm-start hint), distinct from solved `Var.value`.
+     * Validated within tolerance `1e-6` against `[lb, ub]` and integer domain.
+     * Supported by HiGHS (`supportsWarmStart: true`); throws on solvers without warm-start support (GLPK, Z3).
+     */
+    initialValue?: number;
+    [Symbol.iterator]?: never;
 }
-export interface IndicatorOptions {
-    activeValue?: 0 | 1;
-    M?: number;
+export interface BinaryOptions {
+    /** Explicit name for a scalar variable, or fallback prefix for indexed variable containers. */
     name?: string;
+    /** Name prefix when creating unnamed scalar variables or indexed variable containers (default: `"x"`). */
+    prefix?: string;
+    /**
+     * Optional finite primal initial value (`0` or `1` within tolerance `1e-6`), distinct from solved `Var.value`.
+     * Supported by HiGHS (`supportsWarmStart: true`); throws on solvers without warm-start support (GLPK, Z3).
+     */
+    initialValue?: number;
+    [Symbol.iterator]?: never;
 }
+type VarNameOptions = {
+    prefix?: string;
+    name?: string;
+    [Symbol.iterator]?: never;
+};
+import { type IndicatorOptions } from "./big-m.js";
+export type { IndicatorOptions };
 /**
- * High-level mathematical programming model for LP, MIP, QP, and SMT,
- * running directly with WebAssembly solvers (HiGHS, Z3, GLPK) in browser and Node.js.
+ * Named propositional or SMT constraint registered on a `Model`.
  */
 export interface LogicalConstraint {
     name: string;
     expr: BoolExpr | Constraint;
 }
+declare const UniqueStringTag: unique symbol;
+declare global {
+    interface String {
+        readonly [UniqueStringTag]: false;
+    }
+}
+export type KeyCollection<K extends string | number> = ReadonlyArray<K> | (Iterable<K> & object & {
+    readonly [UniqueStringTag]?: true;
+});
+/**
+ * High-level mathematical programming and SMT model for LP, MIP, convex QP, and SAT/SMT,
+ * running with WebAssembly solvers (HiGHS, GLPK, Z3) in Node.js and browsers.
+ *
+ * **Solver capability notes**:
+ * - `"highs"` (default, built-in): Supports LP, MIP, convex QP objectives (`supportsQP: true`),
+ *   and `initialValue` warm starts (`supportsWarmStart: true`). Also supports `m.check()` on purely
+ *   linear models via a zero-objective feasibility fallback. Throws if `BoolVar`/logical constraints are present.
+ * - `"glpk"` (`import "@ohtaman/washi/solvers/glpk"`): Supports LP and MIP, and `m.check()` on purely
+ *   linear models via LP feasibility fallback. Throws on quadratic objectives, `BoolVar`/logical constraints,
+ *   or `initialValue` warm starts.
+ * - `"z3"` (`import "@ohtaman/washi/solvers/z3"`): Supports SMT satisfiability (`m.check()`), optimization (`m.solve()`),
+ *   `BoolVar`/logical constraints (`and`, `or`, `not`, `implies`, `xor`), and unsatisfiable-core extraction
+ *   (`conflicts` / `unsatCore`). Throws on quadratic objectives or `initialValue` warm starts.
+ *
+ * @example
+ * ```ts
+ * import { Model, expr, sum, dot, maximize } from "@ohtaman/washi";
+ *
+ * const m = new Model("ProductionPlan");
+ * const qty = m.integer(["desk", "chair"] as const, { lb: 0, ub: 100 });
+ * const setup = m.binary("setup", { initialValue: 1 });
+ *
+ * m.objective(maximize(expr`${dot({ desk: 30, chair: 50 }, qty)} - 20 * ${setup}`));
+ * m.constraint(expr`${dot({ desk: 1, chair: 2 }, qty)} <= 40`, "wood_cap");
+ * m.constraint(expr`${sum(Object.values(qty))} <= 30 * ${setup}`, "require_setup");
+ *
+ * const status = await m.solve();
+ * const report = m.validateSolution();
+ * const solvedQty = m.getValues(qty);
+ * ```
+ */
 export declare class Model {
     name: string;
-    sense: OptimizationSense;
-    objective: LinExpr | QuadExpr;
+    private _sense;
+    private _objectiveExpr;
     variables: Var[];
     constraints: Constraint[];
     boolVars: BoolVar[];
     logicalConstraints: LogicalConstraint[];
-    unsatCore: string[];
+    unsatCore: readonly string[] | undefined;
     values: Map<string, number | boolean>;
     private varMapByName;
+    private varPrefixCounters;
     private boolVarMapByName;
     private boolVarPrefixCounters;
     private constrMapByName;
+    private constrPrefixCounters;
+    private logicalConstrMapByName;
+    private logicalConstrCounter;
     status: SolverStatus;
+    terminationStatus: TerminationStatus;
+    hasPrimalSolution: boolean;
     objectiveValue: number | null;
+    objectiveBound: number | undefined;
+    relGap: number | undefined;
+    mipGap: number | undefined;
+    absGap: number | undefined;
     runTime: number;
     solution: SolverSolution | null;
     solver: Solver | null;
+    private hasSolutionState;
+    private modelRevision;
+    private activeOperationId;
+    private batchDepth;
+    private batchMutated;
+    private batchUndoActions;
     constructor(nameOrOptions?: string | ModelOptions, maybeOptions?: ModelOptions);
-    get vars(): Var[];
-    get constrs(): Constraint[];
+    get sense(): OptimizationSense;
+    set sense(value: OptimizationSense);
+    get objectiveExpr(): LinExpr | QuadExpr;
+    set objectiveExpr(value: LinExpr | QuadExpr | Constraint);
+    /**
+     * User-friendly alias for unsatCore.
+     * Returns a subset of conflicting constraint names causing infeasibility,
+     * or undefined if not diagnosed, not applicable, or satisfiable.
+     */
+    get conflicts(): readonly string[] | undefined;
     get numVars(): number;
     get numConstrs(): number;
+    /**
+     * Clears stored solution and diagnostic fields on the model and its entities.
+     */
+    private clearSolutionFields;
+    /**
+     * Records a model mutation, invalidating any stored solution state and in-flight solver executions.
+     */
+    private recordModelMutation;
+    /**
+     * @internal Notifies the model that an owned entity (e.g., Var bounds/type or Constraint RHS/sense) was mutated.
+     */
+    notifyMutation(): void;
+    /**
+     * Reset prior solution and diagnostic state to avoid stale data leakage across runs,
+     * and invalidate any in-flight solve() or check() execution.
+     */
+    resetSolutionState(): void;
+    /**
+     * Executes a multi-item model mutation atomically so failed batch edits neither leave
+     * partial entities registered nor invalidate prior solved / in-flight state.
+     */
+    private runTransactionalBatch;
     /**
      * Internal generator for domain-specific variables
      */
     private createDomainVars;
     /**
-     * Create 0-1 binary variable(s) (x in {0, 1}).
-     * Supports:
-     * - m.binary("x") -> Var
-     * - m.binary(5) -> Var[]
-     * - m.binary(["a", "b"]) -> Record<string, Var>
-     * - m.binary(rows, cols) -> Record<string, Record<string, Var>>
-     */
-    binary(name: string): Var;
-    binary(count: number, options?: {
-        prefix?: string;
-        name?: string;
-    }): Var[];
-    binary<K extends string | number>(keys: K[] | Iterable<K>, options?: {
-        prefix?: string;
-        name?: string;
-    }): Record<K, Var>;
-    binary<R extends string | number, C extends string | number>(dim1: R[] | number, dim2: C[] | number, options?: {
-        prefix?: string;
-        name?: string;
-    }): Record<R, Record<C, Var>>;
-    /**
-     * Create integer variable(s) (y in Z).
-     * Supports:
-     * - m.integer("y", { lb: 0, ub: 10 }) -> Var
-     * - m.integer(5, { lb: 0 }) -> Var[]
-     * - m.integer(["a", "b"], { lb: 0, ub: 5 }) -> Record<string, Var>
-     * - m.integer(rows, cols, options) -> Record<string, Record<string, Var>>
-     */
-    integer(name: string, options?: BoundsOptions): Var;
+     * Create 0-1 binary decision variable(s) ($x \in \{0, 1\}$).
+     *
+     * **Scalar & indexed container overloads**:
+     * - `m.binary("x", options?)` or `m.binary(options?)` -> `Var`
+     * - `m.binary(count, options?)` -> `Var[]`
+     * - `m.binary(keys, options?)` -> `Record<K, Var>`
+     * - `m.binary(rowsCount, colsCount, options?)` -> `Var[][]`
+     * - `m.binary(rowsCount, colKeys, options?)` -> `Array<Record<C, Var>>`
+     * - `m.binary(rowKeys, colsCount, options?)` -> `Record<R, Var[]>`
+     * - `m.binary(rowKeys, colKeys, options?)` -> `Record<R, Record<C, Var>>`
+     *
+     * **Warm-start (`initialValue`) semantics**:
+     * - `options.initialValue` supplies an optional finite primal hint (`0` or `1` within tolerance `1e-6`),
+     *   kept distinct from solved `v.value`.
+     * - Supported by HiGHS (`supportsWarmStart: true`); throws on GLPK and Z3.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("BinaryVars");
+     * const b = m.binary("b", { initialValue: 1 }); // Var
+     * const vec = m.binary(4, { prefix: "u" }); // Var[]
+     * const grid = m.binary(2, 3, { prefix: "g" }); // Var[][]
+     * const byShift = m.binary(["day", "night"] as const); // Record<"day" | "night", Var>
+     * ```
+     */
+    binary(name?: string, options?: BinaryOptions): Var;
+    binary(options: BinaryOptions): Var;
+    binary(count: number, options?: BinaryOptions): Var[];
+    binary<K extends string | number>(keys: KeyCollection<K>, options?: BinaryOptions): Record<K, Var>;
+    binary(rows: number, cols: number, options?: BinaryOptions): Var[][];
+    binary<C extends string | number>(rows: number, cols: KeyCollection<C>, options?: BinaryOptions): Array<Record<C, Var>>;
+    binary<R extends string | number>(rows: KeyCollection<R>, cols: number, options?: BinaryOptions): Record<R, Var[]>;
+    binary<R extends string | number, C extends string | number>(rows: KeyCollection<R>, cols: KeyCollection<C>, options?: BinaryOptions): Record<R, Record<C, Var>>;
+    /**
+     * Create integer decision variable(s) ($y \in \mathbb{Z}$, default bounds `lb: 0`, `ub: Infinity`).
+     *
+     * **Scalar & indexed container overloads**:
+     * - `m.integer("y", options?)` or `m.integer(options)` -> `Var`
+     * - `m.integer(count, options?)` -> `Var[]`
+     * - `m.integer(keys, options?)` -> `Record<K, Var>`
+     * - `m.integer(rowsCount, colsCount, options?)` -> `Var[][]`
+     * - `m.integer(rowsCount, colKeys, options?)` -> `Array<Record<C, Var>>`
+     * - `m.integer(rowKeys, colsCount, options?)` -> `Record<R, Var[]>`
+     * - `m.integer(rowKeys, colKeys, options?)` -> `Record<R, Record<C, Var>>`
+     *
+     * **Warm-start (`initialValue`) semantics**:
+     * - `options.initialValue` supplies an optional finite integer primal hint within tolerance `1e-6` of `[lb, ub]`,
+     *   kept distinct from solved `v.value`.
+     * - Supported by HiGHS (`supportsWarmStart: true`); throws on GLPK and Z3.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("IntegerVars");
+     * const n = m.integer("n", { lb: 0, ub: 10, initialValue: 4 }); // Var
+     * const counts = m.integer(3, { lb: 0, prefix: "k" }); // Var[]
+     * const matrix = m.integer(2, 2, { lb: 0, prefix: "m" }); // Var[][]
+     * const byItem = m.integer(["desk", "chair"] as const, { lb: 0, ub: 50 }); // Record<"desk" | "chair", Var>
+     * ```
+     */
+    integer(name?: string, options?: BoundsOptions): Var;
+    integer(options: BoundsOptions): Var;
     integer(count: number, options?: BoundsOptions): Var[];
-    integer<K extends string | number>(keys: K[] | Iterable<K>, options?: BoundsOptions): Record<K, Var>;
-    integer<R extends string | number, C extends string | number>(dim1: R[] | number, dim2: C[] | number, options?: BoundsOptions): Record<R, Record<C, Var>>;
+    integer<K extends string | number>(keys: KeyCollection<K>, options?: BoundsOptions): Record<K, Var>;
+    integer(rows: number, cols: number, options?: BoundsOptions): Var[][];
+    integer<C extends string | number>(rows: number, cols: KeyCollection<C>, options?: BoundsOptions): Array<Record<C, Var>>;
+    integer<R extends string | number>(rows: KeyCollection<R>, cols: number, options?: BoundsOptions): Record<R, Var[]>;
+    integer<R extends string | number, C extends string | number>(rows: KeyCollection<R>, cols: KeyCollection<C>, options?: BoundsOptions): Record<R, Record<C, Var>>;
     /**
-     * Create continuous (real) variable(s) (z in R).
-     * Supports:
-     * - m.continuous("z", { lb: 0 }) -> Var
-     * - m.continuous(5, { lb: 0 }) -> Var[]
-     * - m.continuous(["a", "b"], { lb: 0 }) -> Record<string, Var>
-     * - m.continuous(rows, cols, options) -> Record<string, Record<string, Var>>
+     * Create continuous (real) decision variable(s) ($z \in \mathbb{R}$, default bounds `lb: 0`, `ub: Infinity`).
+     *
+     * **Scalar & indexed container overloads**:
+     * - `m.continuous("z", options?)` or `m.continuous(options)` -> `Var`
+     * - `m.continuous(count, options?)` -> `Var[]`
+     * - `m.continuous(keys, options?)` -> `Record<K, Var>`
+     * - `m.continuous(rowsCount, colsCount, options?)` -> `Var[][]`
+     * - `m.continuous(rowsCount, colKeys, options?)` -> `Array<Record<C, Var>>`
+     * - `m.continuous(rowKeys, colsCount, options?)` -> `Record<R, Var[]>`
+     * - `m.continuous(rowKeys, colKeys, options?)` -> `Record<R, Record<C, Var>>`
+     *
+     * **Warm-start (`initialValue`) semantics**:
+     * - `options.initialValue` supplies an optional finite primal hint within tolerance `1e-6` of `[lb, ub]`,
+     *   kept distinct from solved `v.value`.
+     * - Supported by HiGHS (`supportsWarmStart: true`); throws on GLPK and Z3.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("ContinuousVars");
+     * const x = m.continuous("x", { lb: 0, ub: 100, initialValue: 25 }); // Var
+     * const vec = m.continuous(4, { lb: 0, prefix: "v" }); // Var[]
+     * const flow = m.continuous(2, 3, { lb: 0, prefix: "f" }); // Var[][]
+     * const alloc = m.continuous(["A", "B"] as const, { lb: 0 }); // Record<"A" | "B", Var>
+     * ```
      */
-    continuous(name: string, options?: BoundsOptions): Var;
+    continuous(name?: string, options?: BoundsOptions): Var;
+    continuous(options: BoundsOptions): Var;
     continuous(count: number, options?: BoundsOptions): Var[];
-    continuous<K extends string | number>(keys: K[] | Iterable<K>, options?: BoundsOptions): Record<K, Var>;
-    continuous<R extends string | number, C extends string | number>(dim1: R[] | number, dim2: C[] | number, options?: BoundsOptions): Record<R, Record<C, Var>>;
-    /**
-     * Create Boolean (propositional logic) variable(s) for SMT / SAT modeling.
-     * Supports:
-     * - m.bool("isNight") -> BoolVar
-     * - m.bool() -> BoolVar
-     * - m.bool(5) -> BoolVar[]
-     * - m.bool(["flagA", "flagB"]) -> Record<string, BoolVar>
-     * - m.bool(rows, cols) -> Record<string, Record<string, BoolVar>>
-     */
-    bool(name?: string): BoolVar;
-    bool(count: number, options?: {
-        prefix?: string;
-        name?: string;
-    }): BoolVar[];
-    bool<K extends string | number>(keys: K[] | Iterable<K>, options?: {
-        prefix?: string;
-        name?: string;
-    }): Record<K, BoolVar>;
-    bool<R extends string | number, C extends string | number>(dim1: R[] | number, dim2: C[] | number, options?: {
-        prefix?: string;
-        name?: string;
-    }): Record<R, Record<C, BoolVar>>;
+    continuous<K extends string | number>(keys: KeyCollection<K>, options?: BoundsOptions): Record<K, Var>;
+    continuous(rows: number, cols: number, options?: BoundsOptions): Var[][];
+    continuous<C extends string | number>(rows: number, cols: KeyCollection<C>, options?: BoundsOptions): Array<Record<C, Var>>;
+    continuous<R extends string | number>(rows: KeyCollection<R>, cols: number, options?: BoundsOptions): Record<R, Var[]>;
+    continuous<R extends string | number, C extends string | number>(rows: KeyCollection<R>, cols: KeyCollection<C>, options?: BoundsOptions): Record<R, Record<C, Var>>;
+    /**
+     * Create propositional Boolean variable(s) (`BoolVar`: `true` / `false`) for SMT / SAT logical modeling.
+     *
+     * **Scalar & indexed container overloads**:
+     * - `m.bool("flag", options?)` or `m.bool(options?)` -> `BoolVar`
+     * - `m.bool(count, options?)` -> `BoolVar[]`
+     * - `m.bool(keys, options?)` -> `Record<K, BoolVar>`
+     * - `m.bool(rowsCount, colsCount, options?)` -> `BoolVar[][]`
+     * - `m.bool(rowsCount, colKeys, options?)` -> `Array<Record<C, BoolVar>>`
+     * - `m.bool(rowKeys, colsCount, options?)` -> `Record<R, BoolVar[]>`
+     * - `m.bool(rowKeys, colKeys, options?)` -> `Record<R, Record<C, BoolVar>>`
+     *
+     * **Solver capability note**:
+     * - Logical constraints over `BoolVar` (`and`, `or`, `not`, `implies`, `xor`) require an SMT-capable solver
+     *   such as Z3 (`new Model("...", { solver: "z3" })` after `import "@ohtaman/washi/solvers/z3"`).
+     * - LP/MIP solvers (HiGHS, GLPK) throw if logical constraints are present. For 0-1 arithmetic variables
+     *   in LP/MIP (or Big-M `m.indicator()`), use `m.binary()` instead.
+     *
+     * @example
+     * ```ts
+     * import "@ohtaman/washi/solvers/z3";
+     *
+     * const m = new Model("BoolVars", { solver: "z3" });
+     * const vip = m.bool("vip"); // BoolVar
+     * const flags = m.bool(3, { prefix: "f" }); // BoolVar[]
+     * const grid = m.bool(2, 2, { prefix: "g" }); // BoolVar[][]
+     * const byRole = m.bool(["admin", "guest"] as const); // Record<"admin" | "guest", BoolVar>
+     * m.constraint(implies(vip, flags[0]), "vip_flag");
+     * ```
+     */
+    bool(name?: string, options?: VarNameOptions): BoolVar;
+    bool(options: VarNameOptions): BoolVar;
+    bool(count: number, options?: VarNameOptions): BoolVar[];
+    bool<K extends string | number>(keys: KeyCollection<K>, options?: VarNameOptions): Record<K, BoolVar>;
+    bool(rows: number, cols: number, options?: VarNameOptions): BoolVar[][];
+    bool<C extends string | number>(rows: number, cols: KeyCollection<C>, options?: VarNameOptions): Array<Record<C, BoolVar>>;
+    bool<R extends string | number>(rows: KeyCollection<R>, cols: number, options?: VarNameOptions): Record<R, BoolVar[]>;
+    bool<R extends string | number, C extends string | number>(rows: KeyCollection<R>, cols: KeyCollection<C>, options?: VarNameOptions): Record<R, Record<C, BoolVar>>;
     private hasVarName;
+    private getNextVarName;
     private getNextBoolVarName;
+    private hasConstraintName;
+    private hasBoolVarName;
+    private getNextConstrName;
+    private getNextLogicalConstrName;
     private createBoolVar;
     /**
      * Internal variable creator
@@ -144,39 +343,86 @@ export declare class Model {
      */
     getConstraintByName(name: string): Constraint | undefined;
     /**
-     * Set the objective function
+     * Find a logical constraint by its name
      */
-    setObjective(expr: LinExpr | QuadExpr | Var | number | string | Constraint, sense?: OptimizationSense): void;
+    getLogicalConstraintByName(name: string): LogicalConstraint | undefined;
     /**
-     * Set objective to maximize
+     * Get the current objective expression, or set the objective function and direction (`maximize(...)` / `minimize(...)`).
+     * Calling `objective(spec)` replaces any previously defined objective and returns `this` for chaining.
+     *
+     * **Formulation & solver capability notes**:
+     * - Supports linear (`LinExpr`, `Var`, `number`, formula string) and quadratic (`QuadExpr`: `^2`, `${x} * ${y}`) expressions.
+     * - Quadratic terms are supported in **objectives only** (requires a QP-capable solver such as HiGHS; throws on GLPK and Z3).
+     * - Passing a comparison `Constraint` (`<=`, `>=`, `==`) throws an Error.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("ObjectiveExample");
+     * const chairs = m.integer("chairs", { lb: 0 });
+     * const tables = m.integer("tables", { lb: 0 });
+     *
+     * m.objective(maximize(expr`30 * ${chairs} + 50 * ${tables}`));
+     * const currentExpr = m.objective();
+     * ```
      */
-    maximize(expr: LinExpr | QuadExpr | Var | number | string | Constraint): void;
+    objective(): LinExpr | QuadExpr;
+    objective(spec: ObjectiveSpec): this;
     /**
-     * Set objective to minimize
+     * Internal objective setter.
      */
-    minimize(expr: LinExpr | QuadExpr | Var | number | string | Constraint): void;
+    private applyObjective;
     /**
-     * Constrain the model with linear, boolean, or string formula constraints (primary default API).
-     * Supports single constraint, array of constraints, and fluent chaining:
-     * - m.constrain(expr`${desks} + 2 * ${chairs} <= 40`, "wood")
-     * - m.constrain(items.map(i => expr`${x[i]} <= 10`))
-     * - m.constrain(c1).constrain(c2)
+     * Register linear comparison constraint(s) (`<=`, `>=`, `==`), SMT logical constraint(s) (`BoolVar`, `BoolExpr`),
+     * or constraint formula string(s) on the model. Chainable: returns `this`.
+     *
+     * **Formulation & solver capability notes**:
+     * - Rejects raw arithmetic expressions (`LinExpr`, `QuadExpr`) without a comparison operator and quadratic constraints.
+     * - Logical constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`) require an SMT-capable solver (`{ solver: "z3" }`);
+     *   LP/MIP solvers (HiGHS, GLPK) throw if logical constraints are present.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("ConstraintExample");
+     * const desks = m.integer("desks", { lb: 0 });
+     * const chairs = m.integer("chairs", { lb: 0 });
+     * const x = m.continuous(3, { lb: 0, prefix: "x" });
+     *
+     * m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood");
+     * m.constraint(x.map((v) => expr`${v} <= 10`));
+     * m.constraint(desks.ge(2)).constraint(chairs.ge(4));
+     * ```
      */
-    constrain(constraint: Constraint | LinExpr | QuadExpr | BoolExpr | string, name?: string): this;
-    constrain(constraints: (Constraint | LinExpr | QuadExpr | BoolExpr | string)[]): this;
+    constraint(constraint: ConstraintItem | LinExpr | QuadExpr, name?: string): this;
+    constraint(constraints: ReadonlyArray<ConstraintItem | LinExpr | QuadExpr>): this;
     /**
-     * Extract primal solution values directly into plain primitives:
-     * - m.getValues(x) -> number | null
-     * - m.getValues(p) -> boolean | null
-     * - m.getValues([x, y]) -> (number | null)[]
-     * - m.getValues([p, q]) -> (boolean | null)[]
-     * - m.getValues(record) -> Record<string, number | boolean | null>
-     * - m.getValues(matrix) -> Record<string, Record<string, number | boolean | null>>
+     * Extract primal solution values directly into plain primitives, preserving container shapes:
+     * - `m.getValues(x)` -> `number | null`
+     * - `m.getValues(p)` -> `boolean | null`
+     * - `m.getValues([x, y])` -> `(number | null)[]`
+     * - `m.getValues([[x11, x12], [x21, x22]])` -> `(number | null)[][]`
+     * - `m.getValues(record)` -> `Record<K, number | boolean | null>`
+     * - `m.getValues(matrix)` -> `Record<R, Record<C, number | boolean | null>>`
+     *
+     * @example
+     * ```ts
+     * const m = new Model("GetValuesExample");
+     * const qty = m.integer(["desk", "chair"] as const, { lb: 0, ub: 10 });
+     * m.objective(maximize(expr`30 * ${qty.desk} + 50 * ${qty.chair}`));
+     * m.constraint(expr`${qty.desk} + ${qty.chair} <= 10`);
+     * await m.solve();
+     * const values = m.getValues(qty); // Record<"desk" | "chair", number | null>
+     * ```
      */
     getValues(item: Var): number | null;
     getValues(item: BoolVar): boolean | null;
-    getValues(items: Var[]): (number | null)[];
-    getValues(items: BoolVar[]): (boolean | null)[];
+    getValues(items: ReadonlyArray<Var>): (number | null)[];
+    getValues(items: ReadonlyArray<BoolVar>): (boolean | null)[];
+    getValues(items: ReadonlyArray<ReadonlyArray<Var>>): (number | null)[][];
+    getValues(items: ReadonlyArray<ReadonlyArray<BoolVar>>): (boolean | null)[][];
+    getValues<C extends string | number>(items: ReadonlyArray<Record<C, Var>>): Array<Record<C, number | null>>;
+    getValues<C extends string | number>(items: ReadonlyArray<Record<C, BoolVar>>): Array<Record<C, boolean | null>>;
+    getValues<R extends string | number>(items: Record<R, ReadonlyArray<Var>>): Record<R, (number | null)[]>;
+    getValues<R extends string | number>(items: Record<R, ReadonlyArray<BoolVar>>): Record<R, (boolean | null)[]>;
     getValues<K extends string | number>(items: Record<K, Var>): Record<K, number | null>;
     getValues<K extends string | number>(items: Record<K, BoolVar>): Record<K, boolean | null>;
     getValues<R extends string | number, C extends string | number>(items: Record<R, Record<C, Var>>): Record<R, Record<C, number | null>>;
@@ -186,54 +432,155 @@ export declare class Model {
      */
     private addConstraint;
     /**
-     * Universal classical fluent adder for constraints, variables, or batches.
-     * Enables:
-     * - m.add(x.mul(2).add(y).le(10))
-     * - m.add(c`${x} + ${y} <= 10`)
-     * - m.add("x + y <= 10")
-     * - m.add([c1, c2, c3])
-     * - m.add(new Var(...))
-     * - m.add(c1).add(c2) (fluent chaining)
-     */
-    add(constraint: Constraint, name?: string): this;
-    add(expr: BoolExpr, name?: string): this;
-    add(strConstraint: string, name?: string): this;
-    add(variable: Var): this;
-    add(items: (Constraint | BoolExpr | string | Var)[]): this;
-    /**
-     * Add an indicator constraint via Big-M auto-linearization:
-     * "If binVar == activeValue, then constraint holds"
+     * Add an indicator constraint via floating-point Big-M auto-linearization:
+     * `"If binVar === activeValue, then constraint holds"` (`activeValue` defaults to `1`).
      *
-     * Automatically handles <=, >=, and == constraints.
-     * Enables solving conditional logic in MIP solvers (HiGHS, GLPK) without requiring SMT.
+     * **Formulation & solver capability notes**:
+     * - Automatically linearizes `<=`, `>=`, and `==` constraints for LP/MIP solvers (HiGHS, GLPK)
+     *   under standard floating-point feasibility tolerances (`==` generates `_le` and `_ge` rows).
+     * - Variables appearing in `constraint` must have finite bounds (`lb`/`ub`) to derive a safe tight Big-M
+     *   automatically, unless an explicit `{ M }` override is supplied in `options`.
+     * - Because Big-M rows are floating-point linear relaxations, they do not guarantee exact rational
+     *   equivalence in SMT solvers (Z3); use `implies(...)` with `m.bool(...)` when exact SMT diagnosis is required.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("IndicatorExample");
+     * const b = m.binary("b");
+     * const x = m.continuous("x", { lb: 0, ub: 100 });
+     * // Enforces x <= 50 when b === 1 (relaxed to x <= 100 when b === 0)
+     * m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
+     * ```
      */
     indicator(binVar: Var, constraint: Constraint | LinExpr | QuadExpr, options?: IndicatorOptions): Constraint[];
     /**
-     * Export model to CPLEX LP format string
+     * Validate model integrity (`validateIntegrity()`) and serialize the model's linear/quadratic objective,
+     * linear constraints, and numeric variable bounds/domains (`Continuous`, `Integer`, `Binary`) to a
+     * standard CPLEX LP format string with collision-free sanitized identifiers.
+     *
+     * **Note**: Propositional `BoolVar`s and SMT `logicalConstraints` are not part of the CPLEX LP format.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("LpExportExample");
+     * const x = m.integer("x", { lb: 0, ub: 10 });
+     * m.objective(maximize(expr`5 * ${x}`));
+     * m.constraint(expr`${x} <= 8`, "cap");
+     * const lpText = m.toLpString();
+     * ```
      */
     toLpString(): string;
     /**
-     * Solve the optimization model using the configured solver (defaults to HiGHS WASM)
-     * or a solver passed dynamically (e.g., await model.optimize(new HiGHS()))
+     * Validates model integrity: variable bounds, ownership, numeric sanity, and unique constraint names.
+     * Throws an Error with actionable explanation if any validation rule is violated.
      */
-    optimize(solverOrOptions?: Solver | string | SolveOptions, options?: SolveOptions): Promise<SolverStatus>;
+    validateIntegrity(): void;
+    private ensureExecutionValid;
+    private wrapSolveOptions;
+    private hasPrimalFromResult;
     /**
-     * Convenience alias for optimize():
-     * await model.solve()
-     * await model.solve(new HiGHS())
-     * await model.solve(new GLPK())
-     * await model.solve(new RemoteSolver({ url: "..." }))
+     * Resolves the target solver and execution options without mutating caller-owned objects,
+     * stripping the routing `solver` field from the returned `SolverOptions`.
+     */
+    private resolveSolverAndOptions;
+    /**
+     * Solve the optimization model using the configured solver (defaults to HiGHS WASM)
+     * or a solver passed dynamically (e.g., `await m.solve("glpk")` or `await m.solve({ timeLimit: 10 })`).
+     *
+     * **Return status (`SolverStatus`)**:
+     * - Built-in optimization solvers return `"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`,
+     *   `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, or `"NotSolved"` (`"Sat"` / `"Unsat"`
+     *   are included in `SolverStatus` for custom/satisfiability adapters).
+     * - When a time-, iteration-, or solution-limited run (or an interrupted solve) has found a valid
+     *   primal incumbent, `solve()` returns `"Feasible"` (`m.hasPrimalSolution === true`, with the exact
+     *   stopping reason in `m.terminationStatus`).
+     * - After solving, read primal/dual values via `x.value`, `m.getValues(...)`, `m.objectiveValue`,
+     *   `constr.dual`, `constr.slack`, and `x.reducedCost`, and verify primal feasibility with `m.validateSolution()`.
+     *
+     * **Solver capability preconditions**:
+     * - Quadratic objectives (`QuadExpr`) require `supportsQP` (supported by HiGHS; throws on GLPK and Z3).
+     * - Logical constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`) require `supportsSMT`
+     *   (supported by Z3; throws on HiGHS and GLPK).
+     * - Primal `initialValue` warm starts require `supportsWarmStart` (supported by HiGHS; throws on GLPK and Z3).
+     * - Mutating the model or starting a newer `solve()` / `check()` while in flight discards the stale
+     *   result and rejects the pending promise.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("SolveExample");
+     * const x = m.integer("x", { lb: 0, ub: 50, initialValue: 10 });
+     * const y = m.integer("y", { lb: 0, ub: 50 });
+     * m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+     * m.constraint(expr`${x} + 2 * ${y} <= 40`, "resource_limit");
+     *
+     * const status = await m.solve();
+     * const report = m.validateSolution();
+     * const obj = m.objectiveValue;
+     * ```
      */
     solve(solverOrOptions?: Solver | string | SolveOptions, options?: SolveOptions): Promise<SolverStatus>;
     /**
-     * Check satisfiability of the model without requiring an objective function.
-     * Can be used to verify feasibility or diagnose infeasibilities / unsat core.
+     * Check satisfiability / feasibility of the model without requiring an objective function.
+     *
+     * Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values, conflicts?, unsatCore?, runTime? }`).
+     *
+     * **LP feasibility fallback vs. Z3 requirement**:
+     * - **Linear models (`m.check()` fallback)**: For models containing only linear arithmetic constraints,
+     *   `m.check()` works with any solver (including the default HiGHS and GLPK) by falling back to a
+     *   zero-objective feasibility `solve()` without mutating `m.objectiveExpr` or `m.sense`.
+     * - **Logical constraints & `unsatCore` (requires Z3)**: Models containing `BoolVar` or logical
+     *   constraints (`and`, `or`, `not`, `implies`, `xor`) require an SMT-capable solver (`{ solver: "z3" }`
+     *   after `import "@ohtaman/washi/solvers/z3"`). Unsatisfiable-core extraction (`result.conflicts` /
+     *   `result.unsatCore` and `m.conflicts` / `m.unsatCore`) is populated only when an unsat-core-capable
+     *   solver such as Z3 returns `"Unsat"`, reporting a subset of registered constraint names that conflicts
+     *   together with the model's fixed variable bounds/domains.
+     * - Mutating the model or starting a newer `solve()` / `check()` while in flight discards the stale
+     *   result and rejects the pending promise.
+     *
+     * @example
+     * ```ts
+     * import "@ohtaman/washi/solvers/z3";
+     *
+     * // 1. Linear feasibility check (works with default HiGHS via LP fallback)
+     * const mLin = new Model("LinearCheck");
+     * const x = mLin.continuous("x", { lb: 0, ub: 10 });
+     * mLin.constraint(expr`${x} >= 4`, "min_x");
+     * const linRes = await mLin.check(); // { status: "Sat", values: { x: ... } }
+     *
+     * // 2. SMT satisfiability & unsatCore diagnosis (requires Z3)
+     * const mSmt = new Model("PolicyCheck", { solver: "z3" });
+     * const vip = mSmt.bool("vip");
+     * const discount = mSmt.integer("discount", { lb: 0, ub: 50 });
+     * mSmt.constraint(vip, "is_vip");
+     * mSmt.constraint(implies(vip, expr`${discount} >= 20`), "vip_min");
+     * mSmt.constraint(expr`${discount} <= 10`, "cap");
+     * const smtRes = await mSmt.check(); // { status: "Unsat", conflicts: [...], unsatCore: [...] }
+     * ```
+     */
+    check(solverOrOptions?: Solver | string | SolveOptions, options?: SolveOptions): Promise<CheckResult>;
+    /**
+     * Independently evaluate and verify variable finiteness, variable bounds (`lb`/`ub`),
+     * integer/binary/boolean domains, linear constraint residuals, and logical (SMT/propositional)
+     * constraints against the model's current solved values (or an explicit `options.values` map).
+     *
+     * Returns a `SolutionValidationReport` (`{ valid, complete, maxViolation, violations, violationsByName, uncheckedConstraints, missingVariables, summary }`).
+     *
+     * **Verification notes**:
+     * - Runs purely in JavaScript/TypeScript without requiring any WASM solver runtime.
+     * - Verifies primal feasibility of variables and constraints; does not recompute or compare `m.objectiveValue`.
+     *
+     * @example
+     * ```ts
+     * const m = new Model("ValidateExample");
+     * const x = m.integer("x", { lb: 0, ub: 10 });
+     * m.objective(maximize(expr`3 * ${x}`));
+     * m.constraint(expr`${x} <= 7`, "cap");
+     *
+     * await m.solve();
+     * const report = m.validateSolution();
+     * const isFeasible = report.valid && report.maxViolation <= 1e-6;
+     * ```
      */
-    check(solverOrOptions?: Solver | string | SolveOptions, options?: SolveOptions): Promise<{
-        status: "Sat" | "Unsat" | "Unknown";
-        values: Record<string, number | boolean>;
-        unsatCore?: string[];
-        runTime?: number;
-    }>;
+    validateSolution(options?: SolutionValidationOptions): SolutionValidationReport;
 }
 //# sourceMappingURL=model.d.ts.map