@ohtaman/washi 0.6.0 → 0.7.0

package/docs/guide/variables.md

@@ -1,6 +1,6 @@
 # Variables & Domains
 
-Variables represent the mathematical decision variables in your optimization model.
+Variables represent the mathematical decision variables in your optimization or logical model.
 WaSHI provides domain-specific factory methods on the `Model` instance: `m.continuous()`, `m.integer()`, `m.binary()`, and `m.bool()`.
 
 ---
@@ -8,7 +8,7 @@ WaSHI provides domain-specific factory methods on the `Model` instance: `m.conti
 ## Decision Variable Types
 
 ### 1. Continuous Variables (`m.continuous`)
-Can take any real number value within `[lb, ub]`. Ideal for physical measurements, flow rates, budgets, and weights:
+Can take any real number value within `[lb, ub]`. Used for continuous quantities such as flow rates, weights, budgets, and portfolio allocations:
 
 ```typescript
 import { Model } from "@ohtaman/washi";
@@ -20,7 +20,7 @@ const fuel = m.continuous("fuel", { lb: 0, ub: 1000 });
 ```
 
 ### 2. Integer Variables (`m.integer`)
-Restricted to integers. Ideal for countable assets (machines, trucks, staff count):
+Restricted to integer values within `[lb, ub]`. Used for discrete counts such as machines, vehicles, or headcount:
 
 ```typescript
 // Single integer variable bounded in [0, 15]
@@ -28,48 +28,43 @@ const trucks = m.integer("trucks", { lb: 0, ub: 15 });
 ```
 
 ### 3. Binary Variables (`m.binary`)
-Restricted to $\{0, 1\}$ as mathematical 0-1 values. Ideal for MIP selection, yes/no decisions, and facility selections:
+Restricted to $\{0, 1\}$ as numeric values (`lb = 0`, `ub = 1`). Used for 0-1 MIP selection and yes/no decisions that appear in linear sums or objective costs:
 
 ```typescript
-// Single binary variable
+// Single binary variable (lb = 0, ub = 1 automatically)
 const openWarehouse = m.binary("open_warehouse");
-// lb is automatically 0, ub is automatically 1
 ```
 
 ### 4. Propositional Boolean Variables (`m.bool`)
-Pure boolean logic propositions for SMT / SAT modeling with Z3:
+Pure boolean propositions (`true` / `false`) for logical and SMT constraints:
 
 ```typescript
-// Single propositional boolean variable
-const isNight = m.bool("isNight");
-const alarmTriggered = m.bool("alarmTriggered");
+// Single propositional boolean variables
+const isAdmin = m.bool("isAdmin");
+const hasMfa = m.bool("hasMfa");
 
 // First-class boolean operators: and, or, not, implies, xor
-m.constraint(alarmTriggered.implies(isNight), "alarm_policy");
+m.constraint(isAdmin.implies(hasMfa), "admin_requires_mfa");
 ```
 
-### 💡 Modeling Semi-Continuous Decisions
-Semi-continuous variables take values in $\{0\} \cup [L, U]$ (either zero or between a positive lower and upper bound, useful for minimum production batches or operational thresholds).
+### Choosing Between `m.binary()` and `m.bool()`
 
-While not a primitive `VarType` in `Model`, semi-continuous behavior is cleanly modeled by combining a continuous variable with a binary indicator variable and linking constraints ($L \cdot b \le x \le U \cdot b$):
+| Feature | `m.binary()` (`Var`) | `m.bool()` (`BoolVar`) |
+| :--- | :--- | :--- |
+| **Solved `.value` type** | `number \| null` (`0` or `1`) | `boolean \| null` (`true` or `false`) |
+| **Linear arithmetic (`expr`, `sum`, `dot`, objective costs)** | ✅ Native (`` expr`30 * ${b}` ``) | ❌ Cannot be multiplied by numbers or summed directly |
+| **Indicator constraints (`m.indicator(b, ...)` )** | ✅ Supported as trigger variable | ❌ Use `` implies(flag, expr`...`) `` instead |
+| **Propositional logic (`and`, `or`, `not`, `implies`, `xor`)** | Via comparison (`` expr`${b} == 1` ``) | ✅ Native first-class methods (`.implies()`, `.and()`) |
+| **Solver execution** | Native 0-1 MIP on HiGHS/GLPK; bounded integer on Z3 | Native boolean proposition on Z3; auto-linearized to 0-1 MIP on HiGHS/GLPK |
 
-```typescript
-import { Model, expr } from "@ohtaman/washi";
-
-const m = new Model();
-const batch = m.continuous("batch", { lb: 0, ub: 100 });
-const isActive = m.binary("is_active");
-
-// If isActive === 0, batch is forced to 0; if 1, batch is within [10, 100]
-m.constraint(expr`${batch} >= 10 * ${isActive}`, "min_batch_run");
-m.constraint(expr`${batch} <= 100 * ${isActive}`, "max_batch_run");
-```
+> [!TIP]
+> Use **`m.binary()`** when a decision participates in arithmetic expressions—such as linear sums ($\sum x_i \ge 3$), objective cost terms ($c_i x_i$), or `m.indicator()`. Use **`m.bool()`** when expressing logical conditions with `implies()`, `and()`, and `or()` without numeric coefficients.
 
 ---
 
 ## Multi-Dimensional & Array Creation
 
-The domain factory methods (`continuous`, `integer`, `binary`, `bool`) support count, arrays of keys, and row/column keys to create 1D arrays, typed dictionaries, and 2D matrices in a single call.
+The domain factory methods (`continuous`, `integer`, `binary`, `bool`) accept a numeric count or an array of string keys to create 1D arrays, typed dictionaries, and 2D matrices in a single call.
 
 ### By Count
 Pass a number to create an array of variables:
@@ -80,15 +75,15 @@ const flags = m.bool(3);              // BoolVar[] (p_0, p_1, p_2)
 ```
 
 ### 1D Variable Dictionaries
-Pass an array of keys to get a typed dictionary `Record<string, Var>` or `Record<string, BoolVar>`:
+Pass an array of keys to get a typed dictionary `Record<K, Var>` or `Record<K, BoolVar>`:
 
 ```typescript
-const items = ["laptop", "phone", "tablet"];
+const items = ["laptop", "phone", "tablet"] as const;
 
 // Record<"laptop" | "phone" | "tablet", Var>
 const selected = m.binary(items);
 
-const perms = m.bool(["read", "write", "execute"]);
+const perms = m.bool(["read", "write", "execute"] as const);
 // perms.read, perms.write, perms.execute
 ```
 
@@ -122,16 +117,16 @@ const schedule = m.binary(factories, 7, { prefix: "open_day" });
 
 | Option | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `lb` | `number` | `0` | Lower bound. Defaults to 0 (non-negative). |
+| `lb` | `number` | `0` | Lower bound. Defaults to `0` (non-negative). |
 | `ub` | `number` | `Infinity` (or `1` for binary) | Upper bound. |
 | `type` | `"Continuous"` \| `"Integer"` \| `"Binary"` | Inferred from method | Underlying variable domain category. |
-| `initialValue` | `number` | `undefined` | Optional primal solution hint (MIP start), kept distinct from solved `variable.value`. |
+| `initialValue` | `number` | `undefined` | Optional primal solution hint (MIP warm start), kept distinct from solved `variable.value`. |
 
 ---
 
 ## Primal Initial Values (Warm-Start Hints)
 
-When rebuilding a model across iterations with stable variable names, you can supply optional primal initial values (`initialValue`) on a subset or all numeric variables (`m.continuous`, `m.integer`, `m.binary`, or `v.initialValue = ...`):
+When rebuilding a model across iterations, you can supply optional primal initial values (`initialValue`) on a subset or all numeric variables (`m.continuous`, `m.integer`, `m.binary`, or `v.initialValue = ...`):
 
 ```typescript
 const prevValues: Record<string, number | null> = { trucks: 8, open_warehouse: 1 };
@@ -148,15 +143,15 @@ const openWarehouse2 = m2.binary("open_warehouse", {
 const extraCapacity = m2.continuous("extra_capacity", { lb: 0 }); // Partial start: no initialValue needed
 ```
 
-- **Hint vs. Hard Constraint**: `initialValue` is strictly an optional solver hint (passed to HiGHS via `setSolution`). It does **not** fix the variable, add a constraint, or guarantee either solver acceptance or a runtime speedup. It remains separate from `variable.value` (which is `null` until solved and populated with the solver's primal solution).
-- **Validation & Tolerance (`1e-6`)**: Supplied values must be finite numbers within `[lb - 1e-6, ub + 1e-6]` (and within `1e-6` of an integer inside bounds for `"Integer"` and `"Binary"` variables). Partial starts are not required to satisfy every model constraint.
+- **Hint vs. Hard Constraint**: `initialValue` is an optional solver hint (passed to HiGHS via `setSolution`). It does **not** fix the variable or add a constraint, and `variable.value` remains `null` until solved. *(To penalize deviations from a previous plan, see [Formulation Patterns & Tips](./formulation-tips.md#minimal-perturbation-rescheduling-vs-warm-starting).)*
+- **Validation & Tolerance (`1e-6`)**: Supplied values must be finite numbers within `[lb - 1e-6, ub + 1e-6]` (and within `1e-6` of an integer for `"Integer"` and `"Binary"` variables). Partial starts are accepted without needing to satisfy every model constraint, though supplying a complete constraint-feasible assignment gives MIP solvers an immediate incumbent bound.
 - **Solver Support**: Supported by **HiGHS** (`capabilities.supportsWarmStart === true`). Solvers without warm-start support (**GLPK**, **Z3**, or custom adapters without `supportsWarmStart: true`) reject `solve()` and `check()` with a descriptive error rather than silently ignoring `initialValue`.
 
 ---
 
 ## Accessing Solution Values & Reduced Costs
 
-After calling `await m.solve()` or `await m.check()`, assigned variable values (optimal or incumbent primal values from `solve()`, or a satisfying assignment from `check()`) are accessible via `variable.value` (returns `number | null` for `Var`, or `boolean | null` for `BoolVar`) or the bulk accessor `m.getValues()`:
+After calling `await m.solve()` or `await m.check()`, assigned variable values are accessible via `variable.value` (returns `number | null` for `Var`, or `boolean | null` for `BoolVar`) or the bulk accessor `m.getValues()`:
 
 ```typescript
 await m.solve();
@@ -164,7 +159,7 @@ await m.solve();
 // Single variable primal value
 console.log(`trucks: ${trucks.value}`);
 
-// Reduced cost (LP sensitivity analysis — how much an objective coefficient must improve before a variable at its bound enters the basis)
+// Reduced cost (LP sensitivity analysis)
 console.log(`fuel reduced cost: ${fuel.reducedCost}`);
 
 // Bulk extraction for 1D or 2D collections (works for both Var and BoolVar collections)
@@ -179,10 +174,10 @@ const flowValues = m.getValues(ship);
 
 ## Looking Up Variables by Name
 
-You can retrieve registered decision variables by name or inspect the total variable count on the model:
+You can retrieve registered decision variables by name or inspect the total numeric variable count on the model:
 
 ```typescript
 const v = m.getVarByName("trucks");           // Var | undefined
-const b = m.getBoolVarByName("isNight");      // BoolVar | undefined
+const b = m.getBoolVarByName("isAdmin");      // BoolVar | undefined
 console.log("Total numeric variables:", m.numVars);
 ```

package/docs/ja/getting-started/ai-agents.md

@@ -57,7 +57,7 @@ import "@ohtaman/washi/solvers/glpk";
 1. **デフォルトでパッケージ同梱 WASM を使用（暗黙の CDN フォールバックなし）**:
    - Node.js および最新のバンドラーでは、WebAssembly アセットはモジュールからの相対パスで自動的に解決されます。
    - ブラウザ環境へデプロイする際は、`dist/browser/` ディレクトリ一式（JS、Worker、`.wasm` ファイル）をまとめて配置してください。ローカルの WASM URL が欠落している場合や HTML の SPA フォールバックが返された場合、初期化は試行した URL を明示して即座に失敗し、**外部パブリック CDN へ勝手に切り替わることは決してありません**。
-   - ブラウザランタイムで `highs.wasm` をカスタム URL から読み込む場合は、`setHighsWasmUrl("https://.../highs.wasm")` を呼び出すか、`await m.solve({ wasmUrl: "https://.../highs.wasm" })` を渡します（Node.js では常にローカルの `highs` パッケージランタイムを読み込むため無視されます）。
+   - ブラウザランタイムで `highs.wasm` をカスタム URL から読み込む場合は、`setHighsWasmUrl("https://.../highs.wasm")` を呼び出すか、`await m.solve({ wasmUrl: "https://.../highs.wasm" })` を渡します（Node.js では常にパッケージ同梱のローカル `highs.wasm` ランタイムを読み込むため無視されます）。
 2. **ブラウザでの Z3 実行にはセキュアコンテキスト・Cross-Origin Isolation・CORS が必要**:
    - Z3 WebAssembly は `SharedArrayBuffer` によるマルチスレッドを使用します。Z3 を実行するブラウザページは、セキュアコンテキスト（`window.isSecureContext === true`、すなわち HTTPS または `localhost`）かつ Cross-Origin Isolated（`window.crossOriginIsolated === true`）である必要があり、以下の HTTP ヘッダーを配信する必要があります：
      - `Cross-Origin-Opener-Policy: same-origin`（ドキュメント応答）
@@ -66,7 +66,7 @@ import "@ohtaman/washi/solvers/glpk";
    - `@ohtaman/washi` のインポートによって Service Worker が自動注入されることはありません。ブラウザでセキュアコンテキストや Cross-Origin Isolation が欠けている場合、Z3 は原因を示すエラーで即座に reject します。
 3. **Web Worker とキャンセル制御 (`AbortSignal`)**:
    - 求解開始前のキャンセル（実行開始時点で `signal.aborted`）は、すべてのソルバーでサポートされています。
-   - `Worker` が利用可能なブラウザ環境では、HiGHS はデフォルトで専用 Web Worker 内で実行されます（`useWorker: true`）。`m.solve({ signal })` に `{ signal }` を渡すと、実行中の Worker 求解をプリエンプティブに強制終了（または待機中の Worker リクエストをキャンセル）できます。
+   - 実効オリジンが不透明でない（`window.origin !== "null"`）かつ `Worker` が利用可能なブラウザ環境では、HiGHS はデフォルトで専用 Web Worker 内で実行されます（`useWorker: true`）。実効オリジンが不透明な環境（`window.origin === "null"`、`file:` URL や `allow-same-origin` なしの `sandbox="allow-scripts"` `<iframe>` 埋め込み等）ではデフォルトでメインスレッド実行（`useWorker: false`）になります。`m.solve({ signal })` に `{ signal }` を渡すと、実行中の Worker 求解をプリエンプティブに強制終了（または待機中の Worker リクエストをキャンセル）できます。
    - メインスレッド実行の HiGHS（`useWorker: false` または Node.js）では、ソルバーの割り込みチェックポイントで呼ばれる `onProgress` コールバック内で同期的に `abort()` をトリガーした場合に協調的な途中中断が機能します。外部からの非同期 abort は、同期実行中の WASM スレッドがチェックポイントまたは完了に達するまで割り込むことはできません。割り込みフックを持たないシングルスレッド WASM ソルバー（GLPK、Z3）は実行開始前に `signal` を確認します。
 
 ---
@@ -82,6 +82,7 @@ const m = new Model("ExampleModel");
 
 // スカラー変数
 const x = m.continuous("x", { lb: 0, ub: 100 });
+const y = m.continuous("y", { lb: 0, ub: 100 });
 const n = m.integer("n", { lb: 0, ub: 10 });
 const b = m.binary("b");
 const flag = m.bool("flag"); // 命題論理変数（Z3 / 論理制約用）
@@ -103,12 +104,12 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 ### ステップ 2: 数式の構築 (`expr`, `sum`, `dot`)
 
 - **統一 `expr` テンプレートタグ**:
-  - 1次式（`LinExpr`）: `` expr`30 * ${x} + 50 * ${n} - 10` ``
-  - 2次式（`QuadExpr`）: `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` ``（凸 QP 目的関数向けに変数同士の積や二乗をサポート）。
-  - 線形制約（`Constraint`）: `` expr`${x} + 2 * ${n} <= 40` ``（`<=`, `>=`, `==`, `=` をサポート）。
-- **集計ヘルパー**:
-  - `sum(iterable, mapper?)` は `Var` / `LinExpr` / `number` の `Iterable`（例：`Var[]`, `grid.flat()`, `Object.values(record)`）の総和を計算します。
-  - `dot(a, b)` は対応する 1次元配列、2次元配列（`number[][]` / `Var[][]`）、プレーンな辞書（`Record<string, ...>`）、または配列と辞書の混合コンテナの内積を、引数の順序を問わず計算します。
+  - 1次式（`LinExpr`）: `` expr`30 * ${x} + 50 * ${n} - 10` ``, `` expr`dot(${profit}, ${byItem}) - 20 * ${b}` ``, `` expr`sum((${price} - ${cost}) * ${byItem})` ``
+  - 2次式（`QuadExpr`）: `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``, `` expr`sum((${vec} - ${target})^2)` ``（連続変数 `m.continuous` のみで構成される凸 QP モデルの目的関数としてサポート。標準搭載の HiGHS は整数・バイナリ・論理変数を含む MIQP には非対応です）。
+  - 線形制約（`Constraint`）: `` expr`${x} + 2 * ${n} <= 40` ``, `` expr`sum(${byItem}) <= 100` ``（`<=`, `>=`, `==`, `=` をサポート）。
+- **集計ヘルパーと要素ごとの四則演算**:
+  - `sum(containerOrItems, mapper?)`（`` expr`sum(...)` `` の内部またはスタンドアロン `sum(...)` で利用可能）は、1次元・2次元の `Array`, `Iterable`, またはプレーンな `Record`（`Object.values(record)` 不要）の総和を計算します。`` expr`sum(...)` `` 内ではコンテナの要素ごとの四則演算・二乗（`+`, `-`, `*`, `/`, `^2`）も記述可能です。
+  - `dot(a, b)`（`` expr`dot(${a}, ${b})` `` の内部またはスタンドアロン `dot(a, b)` で利用可能）は、対応する 1次元配列、2次元配列（`number[][]` / `Var[][]`、フロベニウス内積 $\sum_{i,j} A_{i,j} B_{i,j}$）、プレーンな辞書（`Record<string, ...>`）、または配列と辞書の混合コンテナの内積を、引数の順序を問わず計算します。
 - **メソッドチェーン（Fluent API）**:
   - 算術演算（`LinExpr` と `QuadExpr` で利用可能。`Var` は `.add()`, `.sub()`, `.mul()`, `.neg()` をサポート）: `.add(other)`, `.sub(other)`, `.mul(other)`, `.div(scalar)`, `.neg()`
   - 比較演算（`Var` と `LinExpr`）: `.le(rhs, name?)`, `.ge(rhs, name?)`, `.eq(rhs, name?)`
@@ -122,8 +123,8 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 // maximize() または minimize() を用いて目的関数を設定
 m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
 
-// モデルに制約条件を登録
-m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+// モデルに制約条件を登録（登録された Constraint / BoolExpr またはその配列を返す）
+const limit = m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
 
 // 条件付き（Indicator）制約 (MIP Big-M 変換: b === 1 => x <= 50)
 m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
@@ -161,10 +162,13 @@ export async function runMipExample() {
   const qty = m.integer(products, { lb: 0, ub: 100 });
   const setup = m.binary("setup");
 
-  m.objective(maximize(expr`${dot(profit, qty)} - 20 * ${setup}`));
-  m.constraint(expr`${dot(woodPerUnit, qty)} <= 40`, "wood_cap");
-  m.constraint(expr`${dot(laborPerUnit, qty)} <= 50`, "labor_cap");
-  m.constraint(expr`${sum(Object.values(qty))} <= 30 * ${setup}`, "require_setup");
+  m.objective(maximize(expr`dot(${profit}, ${qty}) - 20 * ${setup}`));
+  m.constraint(expr`dot(${woodPerUnit}, ${qty}) <= 40`, "wood_cap");
+  m.constraint(expr`dot(${laborPerUnit}, ${qty}) <= 50`, "labor_cap");
+  m.indicator(setup, expr`sum(${qty}) <= 0`, {
+    activeValue: 0,
+    name: "require_setup",
+  });
 
   const status = await m.solve();
   const report = m.validateSolution();
@@ -268,3 +272,9 @@ export function verifyNegativePatterns() {
   return { m, x, y, maximize };
 }
 ```
+
+### 実務モデリングのベストプラクティス
+
+- **等式制約（`==`）よりも不等式制約（`>=` / `<=`）を優先する**: 需要充足やリソース上限など、コストが正である限り不等式で自然に等号成立する条件には `>=` / `<=` を使い、`==` は流量保存則や重みの合計（$\sum w_i = 1$）など物理的・定義的な恒等式に限定してください。
+- **`m.indicator(...)` 内の変数には有限の `lb` / `ub` を設定し `M` を省略する**: 変数に現実的な上下限を設定して `M` オプションを省略することで、`1e6` のような過大なデフォルト値ではなく、変数境界から最もタイトな Big-M が自動導出されます。
+- **絶対条件以外のビジネス目標はソフト制約（スラック変数）にする**: 希望休や目標在庫などの「可能な限り守りたい条件」には非負スラック変数（`lb: 0`）を導入して目的関数でペナルティを課し、データ変動時にモデル全体が `Infeasible` で停止するのを防いでください。

package/docs/solvers/highs.md

@@ -1,6 +1,6 @@
 # HiGHS Solver Engine
 
-**HiGHS** is high-performance mathematical optimization software developed at the University of Edinburgh ([ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS)). It is widely recognized as the state-of-the-art open-source solver for Linear Programming (LP), Mixed-Integer Programming (MIP), and Convex Quadratic Programming (QP).
+**HiGHS** is high-performance mathematical optimization software initiated at the University of Edinburgh ([highs.dev](https://highs.dev/) · [ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS)). It is widely recognized as the state-of-the-art open-source solver for Linear Programming (LP), Mixed-Integer Programming (MIP), and Convex Quadratic Programming (QP).
 
 In `@ohtaman/washi`, HiGHS runs entirely in WebAssembly compiled directly from official upstream source ([ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS)) using its native C API (`highs_c_api.h`), providing zero-config execution across Node.js, Web Workers, and browsers without third-party wrapper dependencies.
 
@@ -10,7 +10,7 @@ In `@ohtaman/washi`, HiGHS runs entirely in WebAssembly compiled directly from o
 
 - **Built-in & Zero-Config**: Bundled directly with `@ohtaman/washi` with zero external runtime dependencies. No separate peer dependency or C++ compiler required.
 - **Permissive MIT License**: 100% commercially friendly.
-- **Web Worker Multithreading**: Automatically offloads intensive solving to background Web Workers in browser environments to avoid freezing the UI thread.
+- **Background Web Worker Execution**: Automatically offloads solving to a dedicated Web Worker in browser environments to avoid freezing the UI thread.
 - **Warm-Start Support (`initialValue`)**: Supports passing variable primal initial value hints (`initialValue`) to HiGHS `setSolution` for warm starting.
 - **Fast WASM Execution**: Runs the directly compiled 32-bit WebAssembly binary at near-native speed.
 
@@ -24,14 +24,14 @@ WaSHI compiles official HiGHS C++ source directly to WebAssembly (`highs.wasm`)
 
 - **Progress Monitoring & Cancellation (Supported)**:
   Through HiGHS's internal logging and interrupt hooks, WaSHI provides real-time progress callbacks (`onProgress`) and cooperative mid-solve cancellation via standard `AbortSignal`.
-- **Dynamic Cuts / Lazy Constraints (Not Supported in WASM Wrapper)**:
-  The upstream WebAssembly wrapper intentionally excludes low-level native callback type 8 (`MIP lazy constraints`) due to WASM-to-JS boundary and synchronous memory safety constraints. For problems requiring subtour elimination or Benders decomposition, use an **iterative cutting-plane loop** (solve $\to$ detect violation $\to$ `model.constraint(...)` $\to$ re-solve).
+- **Dynamic Cuts / Lazy Constraints (Not Exposed in WASM Driver)**:
+  WaSHI's HiGHS WebAssembly C API driver currently binds logging, progress, interrupt, and incumbent callbacks and does not expose in-tree lazy constraint or user cut callbacks across the WASM-to-JS boundary. For problems requiring dynamic subtour elimination or Benders decomposition, use [`await m.solveBenders({ subproblem })`](../guide/decomposition.md#benders-decomposition-solvebenders) (or a manual outer cutting-plane loop: solve $\to$ detect violation $\to$ `model.constraint(...)` $\to$ re-solve), which iteratively separates cuts and converges to the same exact optimal solution.
 
 ### WebAssembly Asset Lifecycle & On-Demand Builds
 
 HiGHS's WebAssembly binary (`public/highs.wasm`) and runtime driver (`runtime.js`) are managed via `highs.config.json` with cryptographic SHA-256 verification:
 - **Zero-Friction Verification**: Build and distribution pipelines run `node scripts/ensure-highs-wasm.mjs`, verifying local assets in milliseconds before bundling.
-- **On-Demand Release Download**: When assets are missing or updated, `ensure-highs-wasm.mjs` automatically downloads verified binaries from official GitHub Release assets.
+- **On-Demand Release Download**: When assets are missing or updated, `ensure-highs-wasm.mjs` automatically downloads verified binaries from WaSHI's GitHub Release assets.
 - **Compiling from Source**: When updating HiGHS or modifying compiler flags, run `npm run build:highs-wasm` with the Emscripten SDK (`emcc`), CMake, and Ninja installed, and upload the rebuilt assets to the `highs-<version>` GitHub Release tag (`gh release upload highs-v1.15.1 public/highs.wasm src/modeler/solvers/highs/runtime.js --clobber`) so on-demand downloads match `highs.config.json` (or run `.github/workflows/build-wasm.yml` and commit the `highs-wasm-assets` artifact including `highs.config.json`).
 
 ---
@@ -60,7 +60,7 @@ const count = model.integer("count", { lb: 0, ub: 50 });
 ```
 
 ### 3. Convex Quadratic Programming (QP)
-Solves quadratic objective functions subject to linear constraints:
+Solves continuous models with convex quadratic objective functions subject to linear constraints:
 
 ```typescript
 // Minimize risk/variance uniformly using expr:
@@ -71,6 +71,9 @@ model.objective(minimize(expr`0.5 * ${x}^2 + 0.5 * ${y}^2`));
 // model.objective(minimize(quadObj));
 ```
 
+> [!NOTE]
+> **Continuous Convex QP Only**: HiGHS solves Convex QP models where **all** model variables are continuous (`m.continuous`), with a positive semi-definite quadratic matrix $\mathbf{Q}$ when minimizing (or negative semi-definite when maximizing). Mixed-Integer Quadratic Programming (**MIQP**—any model combining a quadratic objective with `Integer`, `Binary`, or `BoolVar` variables) and quadratic constraints (**QCP**) are not supported; to model products of binary decisions in MILP, see [Formulation Patterns & Tips](../guide/formulation-tips.md).
+
 ---
 
 ## Solver Options
@@ -91,6 +94,14 @@ await model.solve({
     console.log(`Elapsed: ${ev.elapsedTime.toFixed(1)}s, Best: ${ev.objectiveValue}`);
   },
 });
+
+// Always check hasPrimalSolution when timeLimit or AbortSignal is used:
+if (model.hasPrimalSolution) {
+  console.log(
+    `Usable solution (${model.status}, termination: ${model.terminationStatus}):`,
+    `obj = ${model.objectiveValue}, gap = ${((model.relGap ?? 0) * 100).toFixed(2)}%`
+  );
+}
 ```
 
 ---
@@ -113,3 +124,13 @@ const syncModel = new Model({
 });
 ```
 
+---
+
+## References & Upstream Links
+
+- **Official Website**: [https://highs.dev/](https://highs.dev/)
+- **Official Documentation**: [https://ergo-code.github.io/HiGHS/](https://ergo-code.github.io/HiGHS/)
+- **Source Repository**: [ERGO-Code/HiGHS](https://github.com/ERGO-Code/HiGHS) (MIT License)
+- **Academic Citation**: If you cite HiGHS in academic or technical publications, please reference the foundational paper requested by the HiGHS authors:
+  > Q. Huangfu and J. A. J. Hall, *"Parallelizing the dual revised simplex method"*, Mathematical Programming Computation, 10 (1), 119–142, 2018. DOI: [10.1007/s12532-017-0130-5](https://doi.org/10.1007/s12532-017-0130-5)
+

package/docs/solvers/index.md

@@ -36,7 +36,7 @@ const m3 = new Model({ solver: "glpk" });
 
 ## Solver Guides
 
-- [HiGHS Guide](./highs.md): Web Worker multithreading, MIP tolerances, and QP solving.
+- [HiGHS Guide](./highs.md): Background Web Worker execution, MIP tolerances, and Convex QP solving.
 - [Z3 Guide](./z3.md): SMT assertions, logic modeling, and Unsat Core analysis.
 - [GLPK Guide](./glpk.md): GLPK adapter, GPL-3.0 licensing considerations, and browser usage.
 - [Custom Solvers](./custom-solver.md): Step-by-step developer tutorial for integrating proprietary or cloud REST solvers.

package/docs/solvers/z3.md

@@ -23,6 +23,9 @@ npm install z3-solver
 3. **Exact Mathematical Guarantees**:
    Z3 can perform exact rational arithmetic without floating-point inaccuracies.
 
+> [!TIP]
+> **Z3 (`m.check()`) vs. HiGHS (`m.solve()`)**: Z3 excels at satisfiability checking (`m.check()`), formal policy verification, general inequality implications (`` implies(expr`${x} <= 50`, y) ``), and scale-invariant `unsatCore` extraction. For numerical LP, MIP, or Convex QP optimization with objective functions over tens or hundreds of variables, use the built-in **HiGHS** solver (`m.solve()`), whose simplex relaxations and branch-and-bound cutting planes are orders of magnitude faster than `Z3.Optimize`. Or combine both in a hybrid pipeline: verify/diagnose rules with Z3 `m.check()`, then optimize costs with HiGHS `m.solve()`.
+
 ---
 
 ## Basic Usage

package/docs/zh/getting-started/ai-agents.md

@@ -57,7 +57,7 @@ import "@ohtaman/washi/solvers/glpk";
 1. **默认使用随包内置的 WASM（无隐式 CDN 回退）**:
    - 在 Node.js 和现代构建工具中，WebAssembly 资源会自动相对于模块路径解析。
    - 在浏览器部署中，请将完整的 `dist/browser/` 目录（包含 JS、Worker 和 `.wasm` 文件）一起部署。如果本地 WASM URL 缺失或返回了 HTML SPA 回退页面，初始化会立即失败并报告所尝试的 URL——**绝不会**静默切换到公共 CDN。
-   - 在浏览器运行时中，若需从自定义位置加载 `highs.wasm`，请调用 `setHighsWasmUrl("https://.../highs.wasm")` 或传入 `await m.solve({ wasmUrl: "https://.../highs.wasm" })`（在 Node.js 中会被忽略，Node.js 始终加载本地安装的 `highs` 包运行时）。
+   - 在浏览器运行时中，若需从自定义位置加载 `highs.wasm`，请调用 `setHighsWasmUrl("https://.../highs.wasm")` 或传入 `await m.solve({ wasmUrl: "https://.../highs.wasm" })`（在 Node.js 中会被忽略，Node.js 始终加载随包内置的本地 `highs.wasm` 运行时）。
 2. **浏览器中运行 Z3 需要安全上下文、跨源隔离（Cross-Origin Isolation）与 CORS**:
    - Z3 WebAssembly 依赖 `SharedArrayBuffer` 多线程。运行 Z3 的浏览器页面必须处于安全上下文（`window.isSecureContext === true`，即 HTTPS 或 `localhost`）且开启跨源隔离（`window.crossOriginIsolated === true`），服务端需配置以下响应头：
      - `Cross-Origin-Opener-Policy: same-origin`（主文档响应）
@@ -66,7 +66,7 @@ import "@ohtaman/washi/solvers/glpk";
    - 导入 `@ohtaman/washi` 绝不会自动注入 Service Worker。当浏览器缺少安全上下文或跨源隔离时，Z3 会立即以明确说明原因的错误 reject。
 3. **Web Worker 与取消控制 (`AbortSignal`)**:
    - 求解前取消（执行开始前 `signal.aborted` 已为真）在所有求解器中均受支持。
-   - 在支持 `Worker` 的浏览器环境中，HiGHS 默认在专用 Web Worker 中运行（`useWorker: true`）。向 `m.solve({ signal })` 传入 `{ signal }` 可以抢占式终止正在运行的 Worker 求解（或取消排队中的 Worker 请求）。
+   - 在有效源非不透明（`window.origin !== "null"`）且支持 `Worker` 的浏览器环境中，HiGHS 默认在专用 Web Worker 中运行（`useWorker: true`）；在有效源为不透明源（`window.origin === "null"`，如 `file:` URL 或未开启 `allow-same-origin` 的 `sandbox="allow-scripts"` `<iframe>` 嵌入）下则默认在主线程运行（`useWorker: false`）。向 `m.solve({ signal })` 传入 `{ signal }` 可以抢占式终止正在运行的 Worker 求解（或取消排队中的 Worker 请求）。
    - 在主线程运行 HiGHS 时（`useWorker: false` 或在 Node.js 中），支持在求解器中断检查点触发的 `onProgress` 回调内同步调用 `abort()` 实现协作式中途取消；来自外部的任意异步取消在同步 WASM 线程到达检查点或执行完成前无法抢占阻塞线程。无中断钩子的单线程 WASM 求解器（GLPK、Z3）会在执行开始前检查 `signal`。
 
 ---
@@ -82,6 +82,7 @@ const m = new Model("ExampleModel");
 
 // 标量变量
 const x = m.continuous("x", { lb: 0, ub: 100 });
+const y = m.continuous("y", { lb: 0, ub: 100 });
 const n = m.integer("n", { lb: 0, ub: 10 });
 const b = m.binary("b");
 const flag = m.bool("flag"); // 命题布尔变量（用于 Z3 / 逻辑约束）
@@ -103,12 +104,12 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 ### 步骤 2：构建表达式 (`expr`, `sum`, `dot`)
 
 - **统一 `expr` 模板标签**:
-  - 线性表达式（`LinExpr`）: `` expr`30 * ${x} + 50 * ${n} - 10` ``
-  - 二次表达式（`QuadExpr`）: `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` ``（支持凸 QP 目标函数中的变量相乘与平方项）。
-  - 线性约束（`Constraint`）: `` expr`${x} + 2 * ${n} <= 40` ``（支持 `<=`、`>=`、`==` 和 `=`）。
-- **聚合函数**:
-  - `sum(iterable, mapper?)` 对 `Var` / `LinExpr` / `number` 的 `Iterable`（例如 `Var[]`、`grid.flat()` 或 `Object.values(record)`）求和。
-  - `dot(a, b)` 计算匹配的一维数组、二维数组（`number[][]` / `Var[][]`）、普通字典（`Record<string, ...>`）或混合 Array/Record 容器的内积，操作数顺序不限。
+  - 线性表达式（`LinExpr`）: `` expr`30 * ${x} + 50 * ${n} - 10` ``、`` expr`dot(${profit}, ${byItem}) - 20 * ${b}` ``、`` expr`sum((${price} - ${cost}) * ${byItem})` ``
+  - 二次表达式（`QuadExpr`）: `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``、`` expr`sum((${vec} - ${target})^2)` ``（支持仅含连续变量 `m.continuous` 的凸 QP 目标函数；内置 HiGHS 不支持包含整数、二元或布尔变量的混合整数二次规划 MIQP）。
+  - 线性约束（`Constraint`）: `` expr`${x} + 2 * ${n} <= 40` ``、`` expr`sum(${byItem}) <= 100` ``（支持 `<=`、`>=`、`==` 和 `=`）。
+- **聚合函数与逐元素算术运算**:
+  - `sum(containerOrItems, mapper?)`（可在 `` expr`sum(...)` `` 内部或独立函数 `sum(...)` 中使用）对一维/二维 `Array`、`Iterable` 或普通字典 `Record`（无需 `Object.values(record)`）求和。在 `` expr`sum(...)` `` 内部还支持容器逐元素四则运算与平方（`+`、`-`、`*`、`/`、`^2`）。
+  - `dot(a, b)`（可在 `` expr`dot(${a}, ${b})` `` 内部或独立函数 `dot(a, b)` 中使用）计算匹配的一维数组、二维数组（`number[][]` / `Var[][]`，计算 Frobenius 内积 $\sum_{i,j} A_{i,j} B_{i,j}$）、普通字典（`Record<string, ...>`）或混合 Array/Record 容器的内积，操作数顺序不限。
 - **链式方法**:
   - 算术运算（在 `LinExpr` 和 `QuadExpr` 上支持；`Var` 支持 `.add()`、`.sub()`、`.mul()`、`.neg()`）: `.add(other)`、`.sub(other)`、`.mul(other)`、`.div(scalar)`、`.neg()`
   - 比较运算（在 `Var` 和 `LinExpr` 上支持）: `.le(rhs, name?)`、`.ge(rhs, name?)`、`.eq(rhs, name?)`
@@ -122,8 +123,8 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 // 使用 maximize() 或 minimize() 设置目标函数
 m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
 
-// 将约束注册到模型
-m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+// 将约束注册到模型（返回已注册的 Constraint / BoolExpr 或其数组）
+const limit = m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
 
 // 指示约束 (MIP Big-M 转化: b === 1 => x <= 50)
 m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
@@ -161,10 +162,13 @@ export async function runMipExample() {
   const qty = m.integer(products, { lb: 0, ub: 100 });
   const setup = m.binary("setup");
 
-  m.objective(maximize(expr`${dot(profit, qty)} - 20 * ${setup}`));
-  m.constraint(expr`${dot(woodPerUnit, qty)} <= 40`, "wood_cap");
-  m.constraint(expr`${dot(laborPerUnit, qty)} <= 50`, "labor_cap");
-  m.constraint(expr`${sum(Object.values(qty))} <= 30 * ${setup}`, "require_setup");
+  m.objective(maximize(expr`dot(${profit}, ${qty}) - 20 * ${setup}`));
+  m.constraint(expr`dot(${woodPerUnit}, ${qty}) <= 40`, "wood_cap");
+  m.constraint(expr`dot(${laborPerUnit}, ${qty}) <= 50`, "labor_cap");
+  m.indicator(setup, expr`sum(${qty}) <= 0`, {
+    activeValue: 0,
+    name: "require_setup",
+  });
 
   const status = await m.solve();
   const report = m.validateSolution();
@@ -268,3 +272,9 @@ export function verifyNegativePatterns() {
   return { m, x, y, maximize };
 }
 ```
+
+### 实战运筹建模守则
+
+- **优先使用不等式（`>=` / `<=`）而非严格等式（`==`）**：当目标成本为正时，需求覆盖与资源上限应优先采用 `>=` / `<=`；仅将 `==` 用于流量守恒或投资权重归一化（$\sum w_i = 1$）等严格恒等关系。
+- **为 `m.indicator(...)` 涉及的变量提供有限 `lb` 与 `ub` 并省略 `M`**：设置合理的有限变量边界并省略 `M`，可让 WaSHI 自动推导最紧凑的 Big-M，避免退化为松散的 `1e6` 默认值。
+- **将非刚性业务规则建模为软约束（弹性松弛变量）**：对排班偏好、安全库存等非绝对硬性规则，引入非负松弛变量（`lb: 0`）并在目标函数中施加分级惩罚，避免真实业务数据微小波动导致整个模型返回 `"Infeasible"`。