@ohtaman/washi 0.5.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

@@ -3,7 +3,10 @@
 > **スコープに関する注記**: このドキュメントは、`@ohtaman/washi` を用いて数理最適化モデルや充足可能性（SAT/SMT）モデルを構築する AI コーディングエージェントおよび開発者向けの**利用者向けモデリング・クイックリファレンス**です。
 > - **ポータブル Agent Skill (`SKILL.md`)**: モデリング・`toLpString()` による式検査・`validateSolution()` による解検証・Z3 `unsatCore` による矛盾診断までを一貫して実行するワークフロースキル（Claude Code, Antigravity, Cursor, Codex 等に対応）として、[`skills/washi/SKILL.md`](https://github.com/ohtaman/washi/blob/main/skills/washi/SKILL.md)（npm パッケージ内の `node_modules/@ohtaman/washi/skills/washi/SKILL.md` にも同梱）を利用できます：
 >   ```bash
->   # パッケージ同梱のスキルをプロジェクトのエージェントスキルディレクトリへ配置
+>   # skills CLI (skills.sh / vercel-labs/skills) 経由で導入
+>   npx skills add ohtaman/washi
+>
+>   # またはパッケージ同梱のスキルをプロジェクトのエージェントスキルディレクトリへ配置
 >   mkdir -p .agents/skills/washi
 >   cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
 >   ```
@@ -54,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`（ドキュメント応答）
@@ -63,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` を確認します。
 
 ---
@@ -79,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 / 論理制約用）
@@ -100,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?)`
@@ -119,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" });
@@ -132,9 +136,10 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
   - `SolverStatus`（`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`, `"Sat"`, または `"Unsat"`）を返します。組み込みの最適化ソルバーは最適化ステータス（`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`）を返し、時間・反復・解数制限や中断で停止した際に有効な実行可能解（Incumbent）が見つかっている場合は `"Feasible"` を返します。`"Sat"` と `"Unsat"` は充足可能性ソルバーやカスタムソルバーアダプター（`MockSolver` など）向けに `SolverStatus` に含まれています。
   - 解の値は `x.value`, `expr`...`.value`, `m.getValues(x)`, `m.getValues(container)`, `m.objectiveValue`, `constr.dual`, `constr.slack`, `x.reducedCost` から読み取ります。
   - 求解後に `m.validateSolution()` を呼び出すことで、変数の有限性、境界条件（`lb`/`ub`）、整数・バイナリ・真偽値領域、線形制約の残差、および論理制約を独立して検証できます（`SolutionValidationReport`: `{ valid, complete, maxViolation, violations, ... }`）。なお、`validateSolution()` は変数および制約条件の主実行可能性を検査するものであり、`m.objectiveValue` の再計算や比較は行いません。
-- **充足可能性判定と Unsat Core (`await m.check(options?)`)**:
-  - `CheckResult`（`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`）を返します。`conflicts` と `unsatCore` は省略可能であり、Unsat Core 抽出に対応したソルバー（Z3 など）が `"Unsat"` を返したときにのみ設定されます。
-  - 線形算術制約のみを含むモデルでは、`m.check()` は実行可能性の `solve()` にフォールバックすることで、デフォルトの HiGHS や GLPK を含む任意のソルバーで動作します。論理制約（`BoolVar`, `and`, `or`, `implies` 等）および Unsat Core 抽出（`result.conflicts` / `result.unsatCore`）には SMT 対応ソルバー（`{ solver: "z3" }`）が必要です。Z3 は登録された制約を追跡しつつ、変数の上下限（`lb`/`ub`）およびバイナリ領域 `{0, 1}` を直接アサートするため、`conflicts` / `unsatCore` は*モデルの固定された変数境界・領域と合わせたときに*矛盾する登録済み制約名の部分集合を返します（最小性は保証されません）。
+- **充足可能性判定と矛盾診断 (`await m.check(options?)`)**:
+  - `CheckResult`（`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`）を返します。`conflicts` はモデルが `"Unsat"` と証明されたときに設定されます。
+  - 線形算術制約または論理制約（`BoolVar`, `and`, `or`, `implies`, `xor`）を含むモデルでは、`m.check()` はデフォルトの HiGHS や GLPK を含む任意のソルバーで動作します（単一 solve の弾性スラック緩和を用い、論理制約は 0-1 MIP へ自動線形化）。矛盾時は緩和が必要な制約名を `conflicts` として診断します（意味論の厳密さのため `unsatCore: undefined`）。
+  - 厳密な SMT Unsat Core 抽出（`result.unsatCore` および `result.conflicts`）は SMT 対応ソルバー（`{ solver: "z3" }`）使用時に提供されます。Z3 は登録された制約を追跡しつつ、変数の上下限（`lb`/`ub`）およびバイナリ領域 `{0, 1}` を直接アサートするため、`unsatCore` は*モデルの固定された変数境界・領域と合わせたときに*矛盾する登録済み制約名の部分集合を返します（最小性は保証されません）。
 - **非同期 `solve` / `check` 実行中のモデル変更禁止**:
   - `await m.solve()` または `await m.check()` の完了待機中に変数・制約・目的関数を変更すると、進行中の実行は無効化され、古い Promise は reject されます。
 
@@ -157,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();
@@ -264,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/custom-solver.md

@@ -119,7 +119,7 @@ export interface SolveModelData extends CheckModelData {
 
 Custom solvers declare their supported features using `capabilities`. Before dispatching `solve()` or `check()`, `Model` validates:
 - `supportsQP === false` when the objective contains quadratic terms (`QuadExpr`),
-- `supportsSMT !== true` when the model contains logical constraints (`m.logicalConstraints`), and
+- when the model contains logical constraints (`m.logicalConstraints`) and the solver does not support SMT (`supportsSMT !== true`), `Model` automatically linearizes them into equivalent 0-1 MIP binary variables and linear constraints via `linearizeModelForMip`, and
 - `supportsWarmStart !== true` when any variable has a primal `initialValue` set.
 
 ```typescript

package/docs/solvers/highs.md

@@ -1,16 +1,38 @@
 # HiGHS Solver Engine
 
-**HiGHS** is high-performance mathematical optimization software developed at the University of Edinburgh. 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.
 
 ---
 
 ## Key Features in WaSHI
 
-- **Built-in & Zero-Config**: Bundled directly with `@ohtaman/washi`. No separate peer dependency or compilation required.
+- **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**: Emscripten-compiled 32-bit WASM runs at near-native speed.
+- **Fast WASM Execution**: Runs the directly compiled 32-bit WebAssembly binary at near-native speed.
+
+---
+
+## Architecture & WebAssembly Runtime
+
+WaSHI compiles official HiGHS C++ source directly to WebAssembly (`highs.wasm`) with `-fwasm-exceptions` and single-threaded universal portability (`-DHIGHS_NO_DEFAULT_THREADS=ON`). By interfacing directly with HiGHS's native C API (`highs_c_api.h`), WaSHI achieves zero-copy solution extraction via typed array views on WebAssembly linear memory, rapid upstream release tracking, and a self-contained zero-dependency distribution.
+
+### Callbacks & Solver Interactivity
+
+- **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 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 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`).
 
 ---
 
@@ -38,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:
@@ -49,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
@@ -69,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)}%`
+  );
+}
 ```
 
 ---
@@ -91,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

@@ -8,9 +8,9 @@ WaSHI is designed around a pluggable, decoupled solver architecture. You formula
 
 | Solver | Engine License | Problem Classes | Best For | Status in WaSHI |
 | :--- | :--- | :--- | :--- | :--- |
-| **HiGHS** | **MIT** | **LP, MIP, Convex QP** | Industrial-scale optimization, operations research, finance | **Built-in default** (zero configuration) |
-| **Z3** | **MIT** | **SMT, SAT, Logic, MIP** | Propositional logic, conflict diagnosis (`unsatCore`), rule engines | Optional plugin (`@ohtaman/washi/solvers/z3`) |
-| **GLPK** | **GPL-3.0** | **LP, MIP** | Academic benchmarks, legacy GLPK compatibility | Optional plugin (`@ohtaman/washi/solvers/glpk`) |
+| **[HiGHS](https://github.com/ERGO-Code/HiGHS)** | **MIT** | **LP, MIP, Convex QP** | Industrial-scale optimization, operations research, finance | **Built-in default** (zero configuration) |
+| **[Z3](https://github.com/Z3Prover/z3)** (via [`z3-solver`](https://www.npmjs.com/package/z3-solver)) | **MIT** | **SMT, SAT, Logic, MIP** | Propositional logic, conflict diagnosis (`unsatCore`), rule engines | Optional plugin (`@ohtaman/washi/solvers/z3`) |
+| **[GLPK](https://www.gnu.org/software/glpk/)** (via [`glpk.js`](https://www.npmjs.com/package/glpk.js)) | **GPL-3.0** | **LP, MIP** | Academic benchmarks, legacy GLPK compatibility | Optional plugin (`@ohtaman/washi/solvers/glpk`) |
 | **Mock** | **MIT** | *Any* | Ultra-fast unit testing in CI without loading WebAssembly | Built-in |
 
 ---
@@ -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

@@ -3,7 +3,10 @@
 > **范围说明**：本文档是面向使用 `@ohtaman/washi` 构建数理优化或可满足性（SAT/SMT）模型的 AI 编程助手与开发者的**使用端建模快速参考**。
 > - **可移植 Agent Skill (`SKILL.md`)**：如需涵盖端到端建模、`toLpString()` 导出检查、`validateSolution()` 解验证以及 Z3 `unsatCore` 冲突诊断的完整工作流技能（兼容 Claude Code、Antigravity、Cursor、Codex 等支持 `SKILL.md` 的代理），请使用 [`skills/washi/SKILL.md`](https://github.com/ohtaman/washi/blob/main/skills/washi/SKILL.md)（同时随 npm 包分发于 `node_modules/@ohtaman/washi/skills/washi/SKILL.md`）：
 >   ```bash
->   # 将随包附带的技能复制到项目的代理技能目录中
+>   # 通过 skills CLI (skills.sh / vercel-labs/skills) 直接安装
+>   npx skills add ohtaman/washi
+>
+>   # 或将随包附带的技能复制到项目的代理技能目录中
 >   mkdir -p .agents/skills/washi
 >   cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
 >   ```
@@ -54,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`（主文档响应）
@@ -63,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`。
 
 ---
@@ -79,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 / 逻辑约束）
@@ -100,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?)`
@@ -119,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" });
@@ -132,9 +136,10 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
   - 返回 `SolverStatus`（`"Optimal"`、`"Feasible"`、`"Infeasible"`、`"Unbounded"`、`"TimeLimit"`、`"IterationLimit"`、`"Error"`、`"Unknown"`、`"NotSolved"`、`"Sat"` 或 `"Unsat"`）。内置优化求解器返回优化状态（`"Optimal"`、`"Feasible"`、`"Infeasible"`、`"Unbounded"`、`"TimeLimit"`、`"IterationLimit"`、`"Error"`、`"Unknown"`、`"NotSolved"`），其中因时间、迭代或解数量上限（或中断）停止但已找到合法可行解（Incumbent）的运行会返回 `"Feasible"`；`"Sat"` 与 `"Unsat"` 包含在 `SolverStatus` 中以供可满足性/自定义求解器适配器（如 `MockSolver`）使用。
   - 通过 `x.value`、`expr`...`.value`、`m.getValues(x)`、`m.getValues(container)`、`m.objectiveValue`、`constr.dual`、`constr.slack` 和 `x.reducedCost` 读取结果。
   - 求解后调用 `m.validateSolution()` 可独立校验变量有限性、变量上下界（`lb`/`ub`）、整数/二元/布尔域、线性约束残差以及逻辑约束（`SolutionValidationReport`：`{ valid, complete, maxViolation, violations, ... }`）。注意：`validateSolution()` 校验变量与约束的原问题可行性，不会重新计算或比对 `m.objectiveValue`。
-- **可满足性检查与 Unsat Core (`await m.check(options?)`)**:
-  - 返回 `CheckResult`（`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`），其中 `conflicts` 和 `unsatCore` 为可选字段，仅在支持不可行核提取的求解器（如 Z3）返回 `"Unsat"` 时填充。
-  - 对于仅包含线性算术约束的模型，`m.check()` 会回退为可行性 `solve()`，因此可用于任何求解器（包括默认的 HiGHS 和 GLPK）。逻辑约束（`BoolVar`、`and`、`or`、`implies` 等）以及不可行核提取（`result.conflicts` / `result.unsatCore`）需要支持 SMT 的求解器（`{ solver: "z3" }`）。由于 Z3 在跟踪已注册约束的同时直接断言变量边界（`lb`/`ub`）和二元 `{0, 1}` 域，`conflicts` / `unsatCore` 报告的是*结合模型固定变量边界/域时*发生冲突的已注册约束名称子集（不保证最小性）。
+- **可满足性检查与冲突诊断 (`await m.check(options?)`)**:
+  - 返回 `CheckResult`（`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`），其中在模型证明为 `"Unsat"` 时填充 `conflicts`。
+  - 对于包含线性算术约束或逻辑约束（`BoolVar`、`and`、`or`、`implies`、`xor`）的模型，`m.check()` 均可在任意求解器（包括默认的 HiGHS 与 GLPK，通过单次求解弹性松弛模型，并将逻辑约束自动线性化为 0-1 MIP）上运行，并在不可行时将需要松弛的冲突约束诊断为 `conflicts`（为保证语义严谨，`unsatCore: undefined`）。
+  - 精确的 SMT 不满足核提取（`result.unsatCore` 与 `result.conflicts`）在选用 SMT 求解器（`{ solver: "z3" }`）时提供。由于 Z3 在跟踪已注册约束的同时直接断言变量边界（`lb`/`ub`）和二元 `{0, 1}` 域，`unsatCore` 报告的是*结合模型固定变量边界/域时*发生冲突的已注册约束名称子集（不保证最小性）。
 - **异步 `solve` / `check` 期间禁止并发修改模型**:
   - 在 `await m.solve()` 或 `await m.check()` 挂起期间修改变量、约束或目标函数会使当前执行失效，并使过期的 Promise 被 reject。
 
@@ -157,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();
@@ -264,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"`。