@ohtaman/washi 0.4.0 → 0.5.0

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

@@ -1,18 +1,66 @@
-import type { SolverStatus } from "../types.js";
-import type { LpModelData, LpExportResult } from "../lp-writer.js";
+import type { OptimizationSense, SolverStatus, TerminationStatus, SolveProgressEvent } from "../types.js";
+import type { Var } from "../variable.js";
+import type { LinExpr } from "../expression.js";
+import type { QuadExpr } from "../quad-expr.js";
+import type { Constraint } from "../constraint.js";
+import type { BoolVar, LogicElement } from "../boolean-expr.js";
+/**
+ * Named logical constraint entry in a model snapshot.
+ */
+export interface LogicalConstraintItem {
+    name: string;
+    expr: LogicElement;
+}
+/**
+ * Typed model snapshot passed to `Solver.check()` (objective-free satisfiability / feasibility).
+ *
+ * Each entity in `variables`, `boolVars`, and `constraints` carries its own model-unique
+ * `.name` (and numeric `.id`), while `logicalConstraints` entries carry their `.name` and
+ * AST `.expr`. Adapters should key returned `values`, `duals`, `reducedCosts`, `slacks`,
+ * and `unsatCore` by these canonical model names (`v.name`, `bv.name`, `c.name`, `lc.name`),
+ * keeping any backend-specific identifier sanitization internal to the adapter.
+ */
+export interface CheckModelData {
+    name?: string;
+    variables: Var[];
+    boolVars?: BoolVar[];
+    constraints: Constraint[];
+    logicalConstraints?: LogicalConstraintItem[];
+}
+/**
+ * Typed model snapshot passed to `Solver.solve()` (optimization with an objective).
+ */
+export interface SolveModelData extends CheckModelData {
+    sense: OptimizationSense;
+    objective: LinExpr | QuadExpr;
+}
 /**
  * Normalized solution result returned by any solver adapter
  */
 export interface SolverResult {
     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;
-    /** Variable primal values (keyed by variable name or ID) */
+    /** 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;
+    /** Variable primal values (keyed by canonical variable name) */
     values: Record<string, number>;
-    /** Variable reduced costs (optional) */
+    /** Boolean variable assignments (optional, keyed by canonical BoolVar name) */
+    boolValues?: Record<string, boolean>;
+    /** Variable reduced costs (optional, keyed by canonical variable name) */
     reducedCosts?: Record<string, number>;
-    /** Constraint dual values (optional) */
+    /** Constraint dual values (optional, keyed by canonical constraint name) */
     duals?: Record<string, number>;
-    /** Constraint slacks (optional) */
+    /** Constraint slacks (optional, keyed by canonical constraint name) */
     slacks?: Record<string, number>;
     /** Solution time in seconds */
     runTime?: number;
@@ -30,12 +78,20 @@ export interface SolverOptions {
     presolve?: "on" | "off" | "choose";
     /** Relative MIP gap tolerance (e.g. 0.01 for 1%) */
     mipGap?: number;
+    /** Relative MIP gap tolerance alias */
+    relGap?: number;
+    /** Absolute MIP gap tolerance */
+    absGap?: number;
     /** Number of parallel threads */
     threads?: number;
     /** Enable verbose solver logging */
     verbose?: boolean;
     /** Use Web Worker for non-blocking browser execution */
     useWorker?: boolean;
+    /** AbortSignal to cancel an in-flight solve */
+    signal?: AbortSignal;
+    /** Callback invoked with real solver progress metrics when available */
+    onProgress?: (progress: SolveProgressEvent) => void;
     /** Additional solver-specific options */
     [key: string]: any;
 }
@@ -53,18 +109,22 @@ export interface SolverCapabilities {
     supportsSMT?: boolean;
     /** Supports extracting an unsatisfiable core (conflicting constraint subset; minimality is not guaranteed) */
     supportsUnsatCore?: boolean;
+    /** Supports primal initial values (MIP starts / warm-start hints) */
+    supportsWarmStart?: boolean;
 }
 export interface SolverCheckResult {
     status: "Sat" | "Unsat" | "Unknown";
     values: Record<string, number | boolean>;
-    unsatCore?: string[];
+    unsatCore?: readonly string[];
+    /** Alias for unsatCore: subset of conflicting constraints causing infeasibility */
+    conflicts?: readonly string[];
     runTime?: number;
     logs?: string[];
     raw?: any;
 }
 /**
  * Universal Solver interface.
- * Any optimization engine (HiGHS WASM, GLPK, Gurobi Remote, CBC, SCIP, custom JS)
+ * Any optimization engine (HiGHS WASM, GLPK, Z3, Gurobi Remote, CBC, SCIP, custom JS)
  * implements this interface to be used interchangeably with Model.
  */
 export interface Solver {
@@ -77,10 +137,10 @@ export interface Solver {
     /**
      * Solve the given mathematical programming model data
      */
-    solve(modelData: LpModelData, lpResult: LpExportResult, options?: SolverOptions): Promise<SolverResult>;
+    solve(modelData: SolveModelData, options?: SolverOptions): Promise<SolverResult>;
     /**
-     * Check satisfiability of the model and logical constraints (optional)
+     * Check satisfiability of the model and logical constraints without an objective (optional)
      */
-    check?(modelData: any, options?: SolverOptions): Promise<SolverCheckResult>;
+    check?(modelData: CheckModelData, options?: SolverOptions): Promise<SolverCheckResult>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/modeler/solvers/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,YAAY,CAAC;IACrB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+BAA+B;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,IAAI,GAAG,KAAK,GAAG,QAAQ,CAAC;IACnC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yCAAyC;IACzC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oEAAoE;IACpE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,8GAA8G;IAC9G,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,GAAG,OAAO,GAAG,SAAS,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACzC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mCAAmC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAC3C;;OAEG;IACH,KAAK,CACH,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC,CAAC;IACzB;;OAEG;IACH,KAAK,CAAC,CACJ,SAAS,EAAE,GAAG,EACd,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC/B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/modeler/solvers/types.ts"],"names":[],"mappings":"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"}

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

@@ -1,7 +1,6 @@
 type Z3Instance = any;
-export declare function unlockAllZ3Semaphores(error?: Error): void;
-export declare function registerZ3ErrorHandler(handler: (err: Error) => void): () => void;
-export declare function notifyZ3WorkerError(err: any): void;
+export declare function registerZ3ErrorHandler(handler: (err: Error) => void, instance?: Z3Instance): () => void;
+export declare function notifyZ3WorkerError(err: unknown): void;
 /**
  * Configure explicit URLs for Z3 assets (z3-built.js and z3-built.wasm).
  */

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

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../src/modeler/solvers/z3/loader.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,GAAG,GAAG,CAAC;AAyBtB,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,IAAI,CAazD;AA+BD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI,CAGhF;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAyBlD;AAkED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAI1F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CA4BnD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBjJ;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAuFpE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAqG5H;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BnE"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../../src/modeler/solvers/z3/loader.ts"],"names":[],"mappings":"AAEA,KAAK,UAAU,GAAG,GAAG,CAAC;AAkEtB,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,IAAI,CASvG;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEtD;AAkED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAI1F;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC;AAED;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CA4BnD;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCjF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAO,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiBjJ;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAuFpE;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAO,GAAG,OAAO,CAAC,UAAU,CAAC,CAwG5H;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,UAAU,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBnE"}

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

@@ -4,11 +4,37 @@
 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 +43,35 @@ 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;
     [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 +79,12 @@ 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;
+}
 //# 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.
+