@ohtaman/washi 0.4.0 → 0.6.0

package/dist/types/modeler/solvers/z3/solver.d.ts

@@ -1,6 +1,7 @@
-import type { Solver, SolverCapabilities, SolverOptions, SolverResult, SolverCheckResult } from "../types.js";
-import { resetZ3LoaderCache, killZ3Threads, unlockAllZ3Semaphores, notifyZ3WorkerError } from "./loader.js";
-export { resetZ3LoaderCache, killZ3Threads, unlockAllZ3Semaphores, notifyZ3WorkerError };
+import type { CheckModelData, SolveModelData, Solver, SolverCapabilities, SolverOptions, SolverResult, SolverCheckResult } from "../types.js";
+import { type LpExportResult, type LpModelData } from "../../lp-writer.js";
+import { resetZ3LoaderCache, killZ3Threads, notifyZ3WorkerError } from "./loader.js";
+export { resetZ3LoaderCache, killZ3Threads, notifyZ3WorkerError };
 /**
  * Z3 SMT / SAT / MIP Solver Adapter
  *
@@ -9,6 +10,12 @@ export { resetZ3LoaderCache, killZ3Threads, unlockAllZ3Semaphores, notifyZ3Worke
  * - Feasibility checking via check()
  * - Unsatisfiable core extraction (unsatCore) for conflict diagnosis
  * - Mixed-Integer Programming (MIP) optimization via Z3 Optimize
+ *
+ * Solution metrics provided by Z3:
+ * - `status` and `terminationStatus`: `"Optimal" | "Infeasible" | "Error"`
+ * - `hasPrimalSolution`: `true` when Z3 returns `"sat"` (`status === "Optimal"`), `false` otherwise.
+ * - `objectiveValue`: Primal objective value when `hasPrimalSolution` is `true`, otherwise `null`.
+ * - `objectiveBound`, `relGap` (`mipGap`), `absGap`: Z3 Optimize is an SMT optimization engine and does not expose branch-and-bound MIP dual bounds or relative/absolute MIP gaps, so these fields are intentionally left `undefined` rather than returning invented defaults.
  */
 export declare class Z3Solver implements Solver {
     readonly name = "z3";
@@ -17,15 +24,18 @@ export declare class Z3Solver implements Solver {
      * Helper to build AST translations for a given Z3 Context
      */
     private createContextTranslator;
+    private addVariableBounds;
+    private runZ3CheckWithErrorGuard;
     /**
      * Check feasibility & propositional satisfaction without an objective function.
      * Tracks constraints to return an unsatCore if infeasible.
      */
-    check(modelData: any, options?: SolverOptions): Promise<SolverCheckResult>;
+    check(modelData: CheckModelData, options?: SolverOptions): Promise<SolverCheckResult>;
     /**
      * Solve optimization problem (MIP) or feasibility problem
      */
-    solve(modelData: any, _lpResult: any, options?: SolverOptions): Promise<SolverResult>;
+    solve(modelData: SolveModelData, options?: SolverOptions): Promise<SolverResult>;
+    solve(modelData: LpModelData, lpResult: LpExportResult, options?: SolverOptions): Promise<SolverResult>;
 }
 /**
  * Register Z3 solver into global solver registry

package/dist/types/modeler/solvers/z3/solver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"solver.d.ts","sourceRoot":"","sources":["../../../../../src/modeler/solvers/z3/solver.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,MAAM,EACN,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAU,kBAAkB,EAAE,aAAa,EAA0B,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAE5I,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,CAAC;AAEzF;;;;;;;;GAQG;AACH,qBAAa,QAAS,YAAW,MAAM;IACrC,QAAQ,CAAC,IAAI,QAAQ;IACrB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAKvC;IAEF;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAyM/B;;;OAGG;IACG,KAAK,CAAC,SAAS,EAAE,GAAG,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgGnF;IAED;;OAEG;IACG,KAAK,CACT,SAAS,EAAE,GAAG,EACd,SAAS,EAAE,GAAG,EACd,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA4HvB;CACF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}
+{"version":3,"file":"solver.d.ts","sourceRoot":"","sources":["../../../../../src/modeler/solvers/z3/solver.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,MAAM,EACN,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAU,kBAAkB,EAAE,aAAa,EAA0B,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAErH,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC;AAWlE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,QAAS,YAAW,MAAM;IACrC,QAAQ,CAAC,IAAI,QAAQ;IACrB,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAMvC;IAEF;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgO/B,OAAO,CAAC,iBAAiB;YAqBX,wBAAwB;IAgBtC;;;OAGG;IACG,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA2G9F;IAED;;OAEG;IACG,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACjF,KAAK,CACT,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;CAkR1B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}

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

@@ -1,14 +1,41 @@
+import type { Constraint } from "./constraint.js";
 /**
  * HiGHS & Model Types
  */
 export type VarType = "Continuous" | "Integer" | "Binary" | "continuous" | "integer" | "binary" | "cont" | "int" | "bin";
 export type OptimizationSense = "Minimize" | "Maximize" | "minimize" | "maximize";
 /**
- * Normalizes user-facing optimization sense to internal canonical form ("Maximize" | "Minimize")
+ * Normalizes user-facing optimization sense to internal canonical form ("Maximize" | "Minimize").
+ * Throws a descriptive error if an invalid sense string is provided at runtime.
  */
 export declare function normalizeSense(sense?: OptimizationSense): "Maximize" | "Minimize";
 export type ComparisonSense = "<=" | ">=" | "==";
 export type SolverStatus = "Optimal" | "Feasible" | "Infeasible" | "Unbounded" | "TimeLimit" | "IterationLimit" | "Error" | "NotSolved" | "Sat" | "Unsat" | "Unknown";
+export type TerminationStatus = "Optimal" | "Feasible" | "Infeasible" | "Unbounded" | "InfeasibleOrUnbounded" | "TimeLimit" | "IterationLimit" | "SolutionLimit" | "MemoryLimit" | "ObjectiveBound" | "ObjectiveTarget" | "Interrupted" | "Error" | "NotSolved" | "Sat" | "Unsat" | "Unknown";
+export interface SolveProgressEvent {
+    /** Elapsed solver time in seconds */
+    elapsedTime: number;
+    /** Alias for elapsedTime: elapsed solver time in seconds */
+    elapsedSeconds?: number;
+    /** Current solver phase when known */
+    phase?: "simplex" | "ipm" | "mip";
+    /** Best feasible incumbent objective value when available */
+    objectiveValue?: number;
+    /** Best proven dual / objective bound when available */
+    objectiveBound?: number;
+    /** Relative MIP optimality gap when available */
+    relGap?: number;
+    /** Alias for relGap: relative MIP optimality gap when available */
+    mipGap?: number;
+    /** Absolute MIP optimality gap |objectiveValue - objectiveBound| when available */
+    absGap?: number;
+    /** Explored MIP branch-and-bound node count when available */
+    nodes?: number;
+    /** Solver iteration count (simplex, IPM, or MIP LP iterations) when available */
+    iterations?: number;
+    /** Optional raw progress message from the solver */
+    message?: string;
+}
 export interface SolveOptions {
     timeLimit?: number;
     outputFlag?: boolean;
@@ -17,11 +44,37 @@ export interface SolveOptions {
     relGap?: number;
     absGap?: number;
     wasmUrl?: string;
+    /**
+     * AbortSignal to cancel a solve:
+     * - Pre-solve cancellation (`signal.aborted` before execution starts) is supported by all solvers.
+     * - Preemptive mid-solve cancellation is supported in browser HiGHS via Web Worker termination
+     *   (and cancels queued Worker requests before they are dispatched).
+     * - Main-thread (Node.js) HiGHS supports cooperative mid-solve cancellation when `abort()` is
+     *   triggered synchronously inside an `onProgress` callback at a solver interrupt checkpoint.
+     * - Single-threaded WASM solvers without interrupt hooks (GLPK, Z3) check `signal` before execution starts.
+     */
+    signal?: AbortSignal;
+    /** Callback invoked with real solver progress metrics when available */
+    onProgress?: (progress: SolveProgressEvent) => void;
+    /** Solve the continuous (LP) relaxation of the model by relaxing integer and binary variables */
+    relax?: boolean;
     [key: string]: any;
 }
 export interface SolverSolution {
     status: SolverStatus;
+    /** Exact termination reason independent of whether a feasible incumbent is available */
+    terminationStatus: TerminationStatus;
+    /** Whether a feasible primal solution / incumbent is available */
+    hasPrimalSolution: boolean;
     objectiveValue: number | null;
+    /** Best proven dual/objective bound when provided by the solver */
+    objectiveBound?: number;
+    /** Relative MIP optimality gap when provided by the solver */
+    relGap?: number;
+    /** Alias for relGap: relative MIP optimality gap when provided by the solver */
+    mipGap?: number;
+    /** Absolute MIP optimality gap |objectiveValue - objectiveBound| when provided by the solver */
+    absGap?: number;
     values: Record<string, number>;
     duals: Record<string, number>;
     reducedCosts: Record<string, number>;
@@ -29,4 +82,36 @@ export interface SolverSolution {
     runTime: number;
     raw?: any;
 }
+export interface CheckResult {
+    status: "Sat" | "Unsat" | "Unknown";
+    values: Record<string, number | boolean>;
+    unsatCore?: readonly string[];
+    /** Alias for unsatCore: subset of conflicting constraints causing infeasibility */
+    conflicts?: readonly string[];
+    runTime?: number;
+}
+/**
+ * Definition for dynamically adding a column (decision variable + constraint coefficients + objective cost).
+ * Core primitive for Column Generation and Dantzig-Wolfe decomposition.
+ */
+export interface ColumnDefinition {
+    name?: string;
+    type?: VarType;
+    lb?: number;
+    ub?: number;
+    /** Objective cost coefficient */
+    cost?: number;
+    /**
+     * Constraint coefficients for this column.
+     * Accepts:
+     * - Record<string, number> (keyed by constraint name)
+     * - Map<Constraint | string, number>
+     * - Array<[Constraint | string, number]>
+     * - Array<{ constraint: Constraint | string; coeff: number }>
+     */
+    coefficients?: Record<string, number> | Map<Constraint | string, number> | Array<[Constraint | string, number]> | Array<{
+        constraint: Constraint | string;
+        coeff: number;
+    }>;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modeler/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,OAAO,GACf,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,MAAM,GACN,KAAK,GACL,KAAK,CAAC;AAEV,MAAM,MAAM,iBAAiB,GACzB,UAAU,GACV,UAAU,GACV,UAAU,GACV,UAAU,CAAC;AAEf;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,CAAC,EAAE,iBAAiB,GAAG,UAAU,GAAG,UAAU,CAGjF;AAGD,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAEjD,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,UAAU,GACV,YAAY,GACZ,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,OAAO,GACP,WAAW,GACX,KAAK,GACL,OAAO,GACP,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;IACnC,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,CAAC;CACX"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/modeler/types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,56 @@
+import type { Model } from "./model.js";
+import { Var } from "./variable.js";
+import { BoolVar, type LogicElement } from "./boolean-expr.js";
+import { Constraint } from "./constraint.js";
+import { LinExpr } from "./expression.js";
+import { QuadExpr } from "./quad-expr.js";
+/**
+ * Recursively attaches ownerModel mutation tracking to any Constraint nodes embedded in a logical expression.
+ */
+export declare function attachLogicElementOwnership(elem: LogicElement, model: Model, undoActions?: (() => void)[]): void;
+/**
+ * Associates a variable instance with its owning model and rejects cross-model sharing.
+ */
+export declare function claimVarOwnership(v: Var, model: Model): void;
+/**
+ * Associates a constraint instance with its owning model and rejects reusing or cross-model sharing.
+ */
+export declare function claimConstraintOwnership(c: Constraint, model: Model): Model | undefined;
+/**
+ * Releases variable ownership when rolling back a failed batch operation.
+ */
+export declare function releaseVarOwnership(v: Var, model: Model): void;
+/**
+ * Releases constraint ownership when rolling back a failed batch operation.
+ */
+export declare function releaseConstraintOwnership(c: Constraint, model: Model, previousOwner?: Model): void;
+/**
+ * Numerical tolerance used when validating variable initial values against bounds and integrality.
+ */
+export declare const INITIAL_VALUE_TOLERANCE = 0.000001;
+/**
+ * Validates lower and upper bounds (and optional primal initialValue) of a single variable.
+ */
+export declare function validateVarBounds(v: Var): void;
+/**
+ * Validates and normalizes a variable's optional primal initialValue for solver consumption.
+ * Rounds near-integer values for Integer/Binary variables and clamps near-bound values for Continuous variables.
+ */
+export declare function normalizeVarInitialValue(v: Var): number | undefined;
+/**
+ * Validates objective expression constants, coefficients, and variable ownership.
+ */
+export declare function validateObjectiveExpr(expr: LinExpr | QuadExpr, modelName: string, isOwnedVar: (v: Var) => boolean): void;
+/**
+ * Validates a linear constraint's RHS, LHS constant, coefficients, and variable ownership.
+ */
+export declare function validateLinearConstraint(c: Constraint, modelName: string, isOwnedVar: (v: Var) => boolean, constrName?: string): void;
+/**
+ * Validates a logical constraint element recursively.
+ */
+export declare function validateLogicElement(elem: LogicElement, lcName: string, modelName: string, isOwnedVar: (v: Var) => boolean, isOwnedBoolVar: (bv: BoolVar) => boolean, ownerModel?: Model): void;
+/**
+ * Validates the structural and numerical integrity of an optimization model.
+ */
+export declare function validateModelIntegrity(model: Model): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/types/modeler/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/modeler/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AACpC,OAAO,EAAE,OAAO,EAAU,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAM1C;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,KAAK,EACZ,WAAW,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,EAAE,GAC3B,IAAI,CAuBN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAQ5D;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,SAAS,CAkBvF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAI9D;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,KAAK,EACZ,aAAa,CAAC,EAAE,KAAK,GACpB,IAAI,CAWN;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,WAAO,CAAC;AAE5C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,GAAG,IAAI,CAwD9C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAWnE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,OAAO,GAAG,QAAQ,EACxB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,GAC9B,IAAI,CAuDN;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,CAAC,EAAE,UAAU,EACb,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,EAC/B,UAAU,SAAS,GAClB,IAAI,CAuBN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,CAAC,CAAC,EAAE,GAAG,KAAK,OAAO,EAC/B,cAAc,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,EACxC,UAAU,CAAC,EAAE,KAAK,GACjB,IAAI,CA2CN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAiGzD"}

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

@@ -8,46 +8,80 @@ export interface VarOptions {
     type?: VarType;
     lb?: number;
     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/binary domains.
+     * Supported by HiGHS (`supportsWarmStart: true`); throws on solvers without warm-start support (GLPK, Z3).
+     */
+    initialValue?: number;
 }
 /**
- * Represents a decision variable in an optimization problem.
+ * Represents a numeric decision variable (`"Continuous"`, `"Integer"`, or `"Binary"`) in an optimization model.
+ * Typically created and registered via `m.continuous(...)`, `m.integer(...)`, or `m.binary(...)`.
+ *
+ * @example
+ * ```ts
+ * const m = new Model("VarExample");
+ * const x = m.continuous("x", { lb: 0, ub: 100 });
+ * const y = m.integer("y", { lb: 0, ub: 10, initialValue: 5 });
+ * m.objective(maximize(x.mul(2).add(y.mul(5))));
+ * m.constraint(x.add(y).le(50));
+ * ```
  */
 export declare class Var {
     readonly id: number;
-    readonly name: string;
-    type: "Continuous" | "Integer" | "Binary";
-    lb: number;
-    ub: number;
+    private _name;
+    readonly prefix: string;
+    hasExplicitName: boolean;
+    ownerModel: {
+        notifyMutation?: () => void;
+    } | null;
+    private _type;
+    private _lb;
+    private _ub;
+    private _initialValue;
     /** Optimal primal value after solve */
     value: number | null;
     /** Reduced cost from dual solution */
     reducedCost: number | null;
     constructor(options?: VarOptions);
+    get name(): string;
+    get type(): "Continuous" | "Integer" | "Binary";
+    set type(val: VarType);
+    get lb(): number;
+    set lb(val: number);
+    get ub(): number;
+    set ub(val: number);
+    /**
+     * Optional finite primal initial value (MIP start / warm-start hint), distinct from solved `Var.value`.
+     * Supported by HiGHS (`supportsWarmStart: true`); throws on solvers without warm-start support (GLPK, Z3).
+     */
+    get initialValue(): number | undefined;
+    set initialValue(val: number | undefined);
+    /** @internal Assigns a model-scoped name when registering an unnamed Var via Model.add() */
+    _assignModelName(name: string): void;
     /** Multiply variable by a scalar coefficient or another variable/expression */
     mul(coeff: number): LinExpr;
     mul(other: Var): QuadExpr;
     mul(other: LinExpr): QuadExpr;
     mul(other: QuadExpr): QuadExpr;
-    mul(other: number | Var | LinExpr | QuadExpr): LinExpr | QuadExpr;
+    mul(other: number | Var | LinExpr | QuadExpr | Constraint): LinExpr | QuadExpr;
     /** Add variable with another variable, linear/quadratic expression, or number */
     add(other: QuadExpr): QuadExpr;
     add(other: Var | LinExpr | number): LinExpr;
-    add(other: Var | LinExpr | QuadExpr | number): LinExpr | QuadExpr;
+    add(other: Var | LinExpr | QuadExpr | number | Constraint): LinExpr | QuadExpr;
     /** Subtract another variable, linear/quadratic expression, or number from this variable */
     sub(other: QuadExpr): QuadExpr;
     sub(other: Var | LinExpr | number): LinExpr;
-    sub(other: Var | LinExpr | QuadExpr | number): LinExpr | QuadExpr;
+    sub(other: Var | LinExpr | QuadExpr | number | Constraint): LinExpr | QuadExpr;
     /** Negate this variable: -x */
     neg(): LinExpr;
     /** Create a less-than-or-equal constraint: this <= rhs */
-    le(rhs: number | Var | LinExpr, name?: string): Constraint;
-    lessThanOrEqual(rhs: number | Var | LinExpr, name?: string): Constraint;
+    le(rhs: number | Var | LinExpr | QuadExpr | Constraint, name?: string): Constraint;
     /** Create a greater-than-or-equal constraint: this >= rhs */
-    ge(rhs: number | Var | LinExpr, name?: string): Constraint;
-    greaterThanOrEqual(rhs: number | Var | LinExpr, name?: string): Constraint;
+    ge(rhs: number | Var | LinExpr | QuadExpr | Constraint, name?: string): Constraint;
     /** Create an equality constraint: this == rhs */
-    eq(rhs: number | Var | LinExpr, name?: string): Constraint;
-    equalTo(rhs: number | Var | LinExpr, name?: string): Constraint;
+    eq(rhs: number | Var | LinExpr | QuadExpr | Constraint, name?: string): Constraint;
     toString(): string;
 }
 //# sourceMappingURL=variable.d.ts.map

package/dist/types/modeler/variable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"variable.d.ts","sourceRoot":"","sources":["../../../src/modeler/variable.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"variable.d.ts","sourceRoot":"","sources":["../../../src/modeler/variable.ts"],"names":[],"mappings":"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"}

package/docs/examples/diet-sensitivity.md

@@ -0,0 +1,90 @@
+# Diet Problem & Sensitivity Analysis (LP Duals & Slacks)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=diet_sensitivity">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts">Source Code</a></li></ul> |
+
+When solving a Linear Programming model, the optimal variable values (`var.value`) are only half the story. In practice, decision-makers need to know:
+
+1. **Bottlenecks (`constr.dual` — Shadow Price):** Which minimum requirements are actively driving up the total cost, and by how much per unit?
+2. **Surpluses (`constr.slack`):** Which constraints have room to spare?
+3. **Reduced Costs (`var.reducedCost`):** For items not selected in the optimal plan, how much cheaper would they need to become before entering the solution?
+
+## Problem Inputs
+
+We choose daily servings ($0 \le x_i \le 4$) among 6 food items to meet 4 daily nutritional minimums (`Calories >= 2000 kcal`, `Protein >= 105 g`, `Calcium >= 1000 mg`, `Iron >= 18 mg`) at minimum cost:
+
+| Food Item | Cost / Serving | Calories (kcal) | Protein (g) | Calcium (mg) | Iron (mg) | Max Servings |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
+| **Oats** | $0.60 | 150 | 5 | 20 | 1.8 | 4.0 |
+| **Chicken** | $2.40 | 220 | 32 | 15 | 1.2 | 4.0 |
+| **Eggs** | $0.80 | 140 | 12 | 50 | 1.7 | 4.0 |
+| **Milk** | $0.90 | 120 | 8 | 280 | 0.1 | 4.0 |
+| **Spinach** | $1.50 | 40 | 4 | 120 | 3.5 | 4.0 |
+| **Salmon** | $3.60 | 200 | 25 | 20 | 0.8 | 4.0 |
+
+## Implementation in WaSHI
+
+<CodeRunner preset="diet_sensitivity">
+
+```typescript
+import { Model, minimize, dot, expr } from "@ohtaman/washi";
+
+const foods = [
+  { name: "Oats",    cost: 0.60, calories: 150, protein: 5,  calcium: 20,  iron: 1.8 },
+  { name: "Chicken", cost: 2.40, calories: 220, protein: 32, calcium: 15,  iron: 1.2 },
+  { name: "Eggs",    cost: 0.80, calories: 140, protein: 12, calcium: 50,  iron: 1.7 },
+  { name: "Milk",    cost: 0.90, calories: 120, protein: 8,  calcium: 280, iron: 0.1 },
+  { name: "Spinach", cost: 1.50, calories: 40,  protein: 4,  calcium: 120, iron: 3.5 },
+  { name: "Salmon",  cost: 3.60, calories: 200, protein: 25, calcium: 20,  iron: 0.8 },
+];
+
+async function runDietSensitivity() {
+  const m = new Model("DietSensitivity");
+
+  // Continuous servings per day (0 to 4 servings max per food)
+  const srv = m.continuous(foods.map((f) => f.name), { lb: 0, ub: 4 });
+
+  const costs = Object.fromEntries(foods.map((f) => [f.name, f.cost]));
+  const cals  = Object.fromEntries(foods.map((f) => [f.name, f.calories]));
+  const prots = Object.fromEntries(foods.map((f) => [f.name, f.protein]));
+  const calcs = Object.fromEntries(foods.map((f) => [f.name, f.calcium]));
+  const irons = Object.fromEntries(foods.map((f) => [f.name, f.iron]));
+
+  // Objective: Minimize total daily cost via dot product
+  m.objective(minimize(dot(costs, srv)));
+
+  // Nutritional constraints defined declaratively with expr and constraint()
+  m.constraint(expr`${dot(cals, srv)} >= 2000`, "min_calories")
+   .constraint(expr`${dot(prots, srv)} >= 105`,  "min_protein")
+   .constraint(expr`${dot(calcs, srv)} >= 1000`, "min_calcium")
+   .constraint(expr`${dot(irons, srv)} >= 18`,   "min_iron");
+
+  const status = await m.solve();
+
+  console.log(`Status: ${status}, Minimum Daily Cost: $${m.objectiveValue?.toFixed(2)}`);
+  console.log("--- Food Servings & Reduced Costs ---");
+  for (const f of foods) {
+    const v = srv[f.name];
+    console.log(`  ${f.name.padEnd(8)}: value=${v.value?.toFixed(2)}, reducedCost=${v.reducedCost?.toFixed(4)}`);
+  }
+  console.log("--- Nutritional Constraints (Dual & Slack) ---");
+  for (const name of ["min_calories", "min_protein", "min_calcium", "min_iron"]) {
+    const c = m.getConstraintByName(name);
+    if (c) {
+      console.log(`  ${c.name.padEnd(13)}: dual=$${c.dual?.toFixed(4)}, slack=${Math.abs(c.slack ?? 0).toFixed(2)}`);
+    }
+  }
+}
+
+runDietSensitivity();
+```
+
+</CodeRunner>
+
+## Interpretation of Results
+
+- **Bottleneck constraints (`slack == 0`, `dual > 0`):** Calories (`2000 kcal`) and Iron (`18 mg`) are tight at their lower bounds. Increasing the daily Iron requirement by 1 mg increases the minimum daily diet cost by **$0.3241**.
+- **Constraints with surplus (`slack > 0`, `dual == 0`):** Protein (`+46.46 g` surplus) and Calcium (`+483.02 mg` surplus) are already exceeded with room to spare, so their shadow prices are `$0`.
+- **Reduced cost (`Salmon`):** Unselected `Salmon` (`0.00` servings) has a reduced cost of `+1.5125`, meaning its price per serving would need to drop by at least **$1.51** before it enters the optimal daily menu.
+

package/docs/examples/ecommerce-coupons.md

@@ -0,0 +1,106 @@
+# E-Commerce Cart & Coupon Optimizer (Indicator MIP)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Mixed-Integer Programming (MIP) | HiGHS (default) | `m.binary()`, `m.constraint()`, `m.indicator()`, `expr`, `minimize` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=cart_coupon">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts">Source Code</a></li></ul> |
+
+Modern e-commerce checkouts often feature complex promotional rules: minimum spend thresholds, category-specific discounts, stackable vs. mutually exclusive coupons, and maximum coupon limits per order. Running an optimizer directly in the browser (or an edge worker) lets the checkout UI automatically apply the best coupon combination—and even recommend a small "filler" item when crossing a spend threshold lowers the customer's net bill.
+
+This example demonstrates **`m.indicator(binVar, constraint, { activeValue, M? })`**, which automatically linearizes conditional *"if coupon is selected, minimum spend must hold"* constraints using Big-M reformulation for MIP solvers like HiGHS. When `M` is omitted, WaSHI automatically derives safe, tight Big-M values from finite variable bounds.
+
+<EcommerceCouponDemo />
+
+## Scenario & Promotion Rules
+
+A customer's shopping cart currently contains **$242** of merchandise (**$210** in Tech items and **$32** in Apparel):
+- **Optional Filler Add-on:** A **$10** Braided USB-C Cable (Tech) can be added to bring the cart total from `$242` to `$252`.
+- **Available Coupons** (maximum **2 coupons** total per checkout; at most **1 Exclusive** coupon):
+
+| Coupon Code | Discount | Condition | Stacking Rule |
+| :--- | :---: | :--- | :--- |
+| `WELCOME15` | **-$15** | Total cart spend $\ge \$100$ | **Stackable** |
+| `TECH30` | **-$30** | Tech category spend $\ge \$200$ | **Exclusive** (cannot combine with `MEGA45_250`) |
+| `MEGA45_250` | **-$45** | Total cart spend $\ge \$250$ | **Exclusive** (cannot combine with `TECH30`) |
+| `MEMBER10` | **-$10** | Total cart spend $\ge \$150$ | **Stackable** |
+
+Without adding the `$10` cable, the cart (`$242`) cannot use `MEGA45_250` and pays `$242 - $30 (TECH30) - $15 (WELCOME15) = $197`.  
+By adding the `$10` cable (`$252` gross), the customer unlocks `MEGA45_250` (`-$45`) + `WELCOME15` (`-$15`) for a net total of **$192**—saving an extra **$5** while getting an extra item!
+
+## Implementation in WaSHI
+
+<CodeRunner preset="cart_coupon">
+
+```typescript
+import { Model, sum, minimize, expr } from "@ohtaman/washi";
+
+async function optimizeCheckoutCart() {
+  const m = new Model("CartCouponOptimizer");
+
+  const baseCartSubtotal = 242;
+  const baseTechSubtotal = 210;
+
+  // Binary decision: add optional $10 USB-C cable to unlock $250 tier?
+  const addUsbCable = m.binary("addon_USB_Cable");
+  const usbCablePrice = 10;
+
+  const coupons = [
+    { id: "WELCOME15",  discount: 15, minCart: 100, minTech: 0,   stackable: true  },
+    { id: "TECH30",     discount: 30, minCart: 0,   minTech: 200, stackable: false },
+    { id: "MEGA45_250", discount: 45, minCart: 250, minTech: 0,   stackable: false },
+    { id: "MEMBER10",   discount: 10, minCart: 150, minTech: 0,   stackable: true  },
+  ];
+
+  // Binary decision variables for each coupon
+  const useCoupon = m.binary(coupons.map((c) => c.id));
+
+  const merchSpend = addUsbCable.mul(usbCablePrice).add(baseCartSubtotal);
+  const techSpend  = addUsbCable.mul(usbCablePrice).add(baseTechSubtotal);
+
+  // 1. Indicator constraints: If useCoupon[id] == 1, minimum spend threshold must hold
+  for (const cpn of coupons) {
+    if (cpn.minCart > 0) {
+      m.indicator(useCoupon[cpn.id], merchSpend.ge(cpn.minCart), {
+        activeValue: 1,
+        M: 500,
+        name: `min_spend_${cpn.id}`,
+      });
+    }
+    if (cpn.minTech > 0) {
+      m.indicator(useCoupon[cpn.id], techSpend.ge(cpn.minTech), {
+        activeValue: 1,
+        M: 500,
+        name: `min_tech_${cpn.id}`,
+      });
+    }
+  }
+
+  // 2. Mutual exclusion among non-stackable ("Exclusive") coupons
+  const exclusiveCoupons = coupons.filter((c) => !c.stackable);
+  m.constraint(
+    expr`${sum(exclusiveCoupons, (c) => useCoupon[c.id])} <= 1`,
+    "at_most_one_exclusive"
+  );
+
+  // 3. Max 2 coupons per order
+  m.constraint(
+    expr`${sum(coupons, (c) => useCoupon[c.id])} <= 2`,
+    "max_two_coupons"
+  );
+
+  // Objective: Minimize final net payable amount (merchSpend - totalDiscounts)
+  const totalDiscount = sum(coupons, (c) => useCoupon[c.id].mul(c.discount));
+  m.objective(minimize(merchSpend.sub(totalDiscount)));
+
+  const status = await m.solve();
+  console.log(`Status: ${status}, Optimal Net Payable: $${m.objectiveValue}`);
+  console.log(`Recommended Add-on (+$10 USB-C Cable): ${(addUsbCable.value ?? 0) > 0.5 ? "YES" : "NO"}`);
+  for (const cpn of coupons) {
+    const applied = (useCoupon[cpn.id].value ?? 0) > 0.5;
+    console.log(`  ${applied ? "✅ [APPLIED]" : "   [skipped]"} ${cpn.id.padEnd(11)} (-$${cpn.discount})`);
+  }
+}
+
+optimizeCheckoutCart();
+```
+
+</CodeRunner>

package/docs/examples/index.md

@@ -0,0 +1,57 @@
+# Examples & API Finder
+
+Explore runnable optimization and logic formulations built with WaSHI. Every example can be executed directly inside its documentation page, or edited in the [Playground](https://ohtaman.github.io/washi/demo/).
+
+## Examples
+
+| Example | Problem Class | Solver | Key WaSHI APIs | Description | Code Editor |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **[Production Planning](./production.md)** | LP / MIP | HiGHS | `m.integer()`, `m.constraint()`, `expr` | Basic variables, tagged template literal equations, and maximizing profit under resource limits. | [Playground](https://ohtaman.github.io/washi/demo/?preset=production) |
+| **[0-1 Knapsack](./knapsack.md)** | Binary MIP | HiGHS | `m.binary(keys)`, `sum()`, `m.constraint()` | 1D dictionary of `Binary` variables and linear aggregation over item arrays. | [Playground](https://ohtaman.github.io/washi/demo/?preset=knapsack) |
+| **[Transportation Network](./transportation.md)** | LP | HiGHS | `m.continuous(rows, cols)`, `dot()`, `m.constraint()` | 2D matrix indexing (`ship[factory][store]`) and row/column flow balance constraints. | [Playground](https://ohtaman.github.io/washi/demo/?preset=transportation) |
+| **[Diet & Sensitivity Analysis](./diet-sensitivity.md)** | LP | HiGHS | `constr.dual`, `constr.slack`, `var.reducedCost` | Reading shadow prices (bottlenecks), constraint surpluses, and reduced costs after solving. | [Playground](https://ohtaman.github.io/washi/demo/?preset=diet_sensitivity) |
+| **[Staff Shift Scheduling](./shift-scheduling.md)** | Binary MIP + Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `check()`, `unsatCore` | 5×7 weekly roster planner (coverage, senior duty, max shifts, day-off requests) and diagnosing conflicting vacation requests with Z3 `unsatCore`. | [Playground](https://ohtaman.github.io/washi/demo/?preset=shift_scheduling) |
+| **[E-Commerce Coupon Optimizer](./ecommerce-coupons.md)** | Indicator MIP | HiGHS | `m.indicator()`, `sum()`, `m.constraint()` | Checkout optimizer using `m.indicator()` for minimum spend thresholds, exclusive vs. stackable rules, and smart filler add-on suggestions. | [Playground](https://ohtaman.github.io/washi/demo/?preset=cart_coupon) |
+| **[Portfolio Optimization](./portfolio-qp.md)** | Convex QP | HiGHS | `m.continuous()`, `m.constraint()`, `dot()`, `QuadExpr` | Markowitz mean-variance risk minimization ($w^T \Sigma w$) using `QuadExpr` subject to return targets. | [Playground](https://ohtaman.github.io/washi/demo/?preset=portfolio_qp) |
+| **[SMT Security Policies](./smt-security.md)** | SMT Logic | Z3 | `m.bool()`, `m.constraint()`, `m.check()` | Propositional variables (`BoolVar`) and logical connectives (`implies`, `and`, `not`, `xor`) mixed with integer bounds. | [Playground](https://ohtaman.github.io/washi/demo/?preset=smt_sat_scheduling) |
+| **[Conflict Diagnosis (`unsatCore`)](./unsat-core.md)** | Unsat Core | Z3 | `m.constraint()`, `m.check()`, `m.unsatCore` | Extracting a conflicting constraint subset (`unsatCore`) when staffing and budget rules contradict each other. | [Playground](https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat) |
+| **[Vehicle Routing (CVRP)](./vehicle-routing.md)** | Combinatorial OR / Dantzig-Wolfe | HiGHS | `m.solveColumnGeneration()`, `pricing` | Dynamic route column generation from customer dual shadow prices to minimize total fleet vehicles. | [Decomposition Guide](../guide/decomposition.md) |
+| **[Traveling Salesperson (TSP)](./traveling-salesperson.md)** | Combinatorial OR / Benders | HiGHS | `m.solveBenders()`, `subproblem` | Subtour elimination on degree-assignment relaxation using dynamic Benders feasibility cuts. | [Decomposition Guide](../guide/decomposition.md) |
+
+## Find by WaSHI API (Reverse Index)
+
+Looking for a specific modeling method or solver capability? Jump straight to the example that demonstrates it:
+
+| Feature / API | Description | Example Page | Node.js Source |
+| :--- | :--- | :--- | :--- |
+| ``m.constraint(expr`...`)`` | Tagged template literal constraints | [Production Planning](./production.md) | [`01-production-planning.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) |
+| `m.binary(keys)` / `m.continuous(keys)` | 1D dictionary of indexed variables | [0-1 Knapsack](./knapsack.md) | [`02-knapsack-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts) |
+| `m.continuous(rows, cols)` / `m.binary(rows, cols)` | 2D matrix of indexed variables | [Transportation Network](./transportation.md), [Shift Scheduling](./shift-scheduling.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
+| `dot(matrix, vars2d)` / `dot(vector, vars)` | Fast vector/matrix dot product | [Transportation Network](./transportation.md), [Portfolio Optimization](./portfolio-qp.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
+| `constr.dual` & `constr.slack` | Shadow prices & constraint surpluses | [Diet & Sensitivity Analysis](./diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
+| `var.reducedCost` | Variable reduced costs in LP | [Diet & Sensitivity Analysis](./diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
+| `m.indicator()` | Big-M conditional constraints (`binVar => constr`) | [E-Commerce Coupon Optimizer](./ecommerce-coupons.md) | [`12-ecommerce-coupon-optimizer.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) |
+| `new QuadExpr()` | Convex quadratic objectives ($x^T Q x$) | [Portfolio Optimization](./portfolio-qp.md) | [`03-portfolio-qp.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) |
+| `m.bool()` & `.implies()` | Propositional logic & SMT rules | [SMT Security Policies](./smt-security.md) | [`04-smt-security-rules.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) |
+| `m.check()` & `m.unsatCore` | Feasibility check & conflict diagnosis | [Conflict Diagnosis](./unsat-core.md), [Shift Scheduling](./shift-scheduling.md) | [`05-unsat-core-diagnosis.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) |
+| `m.solveColumnGeneration()` | Dantzig-Wolfe Column Generation | [Vehicle Routing](./vehicle-routing.md) | [`13-vehicle-routing-column-generation.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts) |
+| `m.solveBenders()` | Benders Decomposition & cut separation | [Traveling Salesperson](./traveling-salesperson.md) | [`14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) |
+| `solver: "glpk"` | Solving LP/MIP with GLPK plugin | [GLPK Solver Guide](../solvers/glpk.md) | [`08-glpk-solver-plugin.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/08-glpk-solver-plugin.ts) |
+
+## Running Examples Locally in Node.js
+
+All standalone scripts are located in [`examples/node/`](https://github.com/ohtaman/washi/tree/main/examples/node):
+
+```bash
+npx tsx examples/node/01-production-planning.ts
+npx tsx examples/node/02-knapsack-problem.ts
+npx tsx examples/node/03-portfolio-qp.ts
+npx tsx examples/node/04-smt-security-rules.ts
+npx tsx examples/node/05-unsat-core-diagnosis.ts
+npx tsx examples/node/07-hybrid-smt-mip.ts
+npx tsx examples/node/08-glpk-solver-plugin.ts
+npx tsx examples/node/09-transportation-problem.ts
+npx tsx examples/node/10-diet-sensitivity.ts
+npx tsx examples/node/11-shift-scheduling.ts
+npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
+```