@ohtaman/washi 0.5.0 → 0.6.0

package/docs/guide/decomposition.md

@@ -0,0 +1,399 @@
+# Advanced Decomposition Methods & Best Practices
+
+Mixed-Integer Programming (MIP) formulations can become slow when symmetry or coupling constraints cause branch-and-bound trees to grow large.
+WaSHI provides decomposition orchestrators (`master.solveColumnGeneration` and `master.solveBenders`) along with lower-level modeling primitives for dual inspection and dynamic model modification.
+
+---
+
+## Why Decomposition? (When Monolithic MIP Stalls)
+
+There are two common problem structures where monolithic MIP formulations struggle:
+
+| Problem Structure | Monolithic MIP Bottleneck | Technique | WaSHI API |
+| :--- | :--- | :--- | :--- |
+| **Symmetry & Loose Continuous Bounds**<br>*(Cutting Stock, Vehicle Routing/VRP, Crew Rostering)* | Symmetric permutations and a weak continuous relaxation enlarge the branch-and-bound tree. | **Column Generation**<br>*(Dantzig-Wolfe Decomposition)* | [`master.solveColumnGeneration()`](#column-generation-solvecolumngeneration) |
+| **Complicating Decisions & Multi-Stage Structure**<br>*(Traveling Salesperson/TSP, Facility Location with Routing, Two-Stage Stochastic Planning)* | Coupling master decisions with large scenario or operational subproblems increases the matrix size. | **Benders Decomposition** | [`master.solveBenders()`](#benders-decomposition-solvebenders) |
+
+---
+
+## Foundational Primitives
+
+WaSHI provides fine-grained modeling primitives to inspect dual information and dynamically modify models:
+
+### 1. Constraint Duals (`dual`)
+Access the dual values (marginal impact on the objective per unit change in RHS) after an LP solve:
+
+```typescript
+m.constraint(expr`${x} + ${y} <= 10`, "capacity");
+await m.solve();
+
+const c = m.getConstraintByName("capacity")!;
+console.log(c.dual); // Dual value / shadow price
+console.log(m.solution?.duals.capacity);
+```
+
+### 2. Continuous LP Relaxation (`model.relax()`)
+Decomposition algorithms require solving the continuous LP relaxation to extract dual values. `model.relax()` temporarily relaxes all `Integer` and `Binary` variables to continuous variables within their bounds:
+
+```typescript
+// Solves LP relaxation and populates shadow prices in m.solution.duals
+const status = await m.relax();
+console.log("Theoretical dual bound:", m.objectiveValue);
+```
+
+### 3. Dynamic Column Injection (`model.addColumn()`)
+Inject a new decision variable along with its objective coefficient and constraint contributions in a single call:
+
+```typescript
+const col = m.addColumn({
+  name: "pattern_1",
+  type: "Integer", // or "Continuous"
+  lb: 0,
+  cost: 1, // objective coefficient
+  coefficients: {
+    demand_itemA: 2,
+    demand_itemB: 1,
+  },
+});
+```
+
+### 4. Dynamic Constraint Modification (`addTerm` / `setTerm`)
+Update the coefficients of individual variables in an existing constraint:
+
+```typescript
+const c = m.getConstraintByName("budget")!;
+c.addTerm(newVar, 5); // Increments newVar's coefficient by 5
+c.setTerm(newVar, 0); // Setting to 0 cleanly removes the term
+```
+
+---
+
+## Column Generation (`solveColumnGeneration`)
+
+Column Generation starts with a **Restricted Master Problem (RMP)** with a small subset of columns. In each iteration:
+1. It solves the RMP's LP relaxation via `master.relax()`.
+2. Evaluates a pricing subproblem using constraint shadow prices.
+3. Finds candidate columns with negative reduced costs ($\bar{c} = \text{cost} - \sum \pi_i a_i < 0$) and dynamically injects them into the master problem.
+4. Repeats until no improving columns exist.
+5. Finally solves the full master model as a Mixed-Integer Program (`finalizeAsMIP`, default: `true`) to obtain optimal integer solutions.
+
+### Column Generation with the `pricing` Callback
+
+Provide a `pricing` callback that receives constraint shadow prices (duals), solves the subproblem (using a WaSHI model or any custom algorithm), and returns new column proposals. WaSHI automatically evaluates reduced costs and injects improving columns:
+
+```typescript
+import { Model, expr, minimize, maximize } from "@ohtaman/washi";
+
+const rollWidth = 100;
+const items = [
+  { id: "A", width: 45, demand: 10 },
+  { id: "B", width: 36, demand: 14 },
+  { id: "C", width: 16, demand: 20 },
+];
+
+// 1. Define Restricted Master Problem (RMP) with naive initial single-cut patterns
+const master = new Model("CuttingStockMaster");
+
+const pA = master.integer("init_A", { lb: 0 }); // 2 of A per roll (45*2 = 90 <= 100)
+const pB = master.integer("init_B", { lb: 0 }); // 2 of B per roll (36*2 = 72 <= 100)
+const pC = master.integer("init_C", { lb: 0 }); // 6 of C per roll (16*6 = 96 <= 100)
+
+master.objective(minimize(expr`${pA} + ${pB} + ${pC}`));
+master.constraint(expr`2 * ${pA} >= 10`, "demand_A");
+master.constraint(expr`2 * ${pB} >= 14`, "demand_B");
+master.constraint(expr`6 * ${pC} >= 20`, "demand_C");
+const [demandA, demandB, demandC] = master.constraints;
+
+// 2. Solve with master.solveColumnGeneration()
+const result = await master.solveColumnGeneration({
+  finalizeAsMIP: true,
+  pricing: async () => {
+    // Pricing subproblem: Bounded Knapsack
+    const sub = new Model("KnapsackPricing");
+    const a_A = sub.integer("a_A", { lb: 0, ub: 2 });
+    const a_B = sub.integer("a_B", { lb: 0, ub: 2 });
+    const a_C = sub.integer("a_C", { lb: 0, ub: 6 });
+
+    // Maximize shadow price collection
+    const dualA = demandA.dual ?? 0;
+    const dualB = demandB.dual ?? 0;
+    const dualC = demandC.dual ?? 0;
+    sub.objective(maximize(expr`${dualA} * ${a_A} + ${dualB} * ${a_B} + ${dualC} * ${a_C}`));
+    sub.constraint(expr`45 * ${a_A} + 36 * ${a_B} + 16 * ${a_C} <= ${rollWidth}`);
+
+    await sub.solve();
+
+    // Return the generated cutting pattern
+    return {
+      cost: 1,
+      type: "Integer",
+      coefficients: {
+        demand_A: Math.round(a_A.value ?? 0),
+        demand_B: Math.round(a_B.value ?? 0),
+        demand_C: Math.round(a_C.value ?? 0),
+      },
+    };
+  },
+});
+
+console.log("Optimal rolls needed:", result.objectiveValue); // 14
+console.log("Iterations executed:", result.iterations);
+console.log("Dynamic columns added:", result.columnsAdded);
+```
+
+### Custom Pricing Algorithms (Graph / Dynamic Programming)
+
+Because `pricing` is a standard callback returning column definitions, you can solve the subproblem using any algorithm (e.g. Dijkstra, Bellman-Ford, or custom heuristics):
+
+```typescript
+const result = await master.solveColumnGeneration({
+  pricing: async ({ getDual }) => {
+    // Solve subproblem with specialized custom graph algorithm
+    const route = solveSpecializedShortestPath(getDual);
+    if (!route) return null;
+
+    return {
+      cost: route.distance,
+      type: "Integer",
+      coefficients: route.visitedCustomers,
+    };
+  },
+});
+```
+
+---
+
+## Benders Decomposition (`solveBenders`)
+
+Benders Decomposition partitions the problem into:
+- **Master Problem**: Contains complicating variables (e.g., 0-1 facility opening decisions $y$) and an auxiliary variable $\theta \ge 0$ representing estimated subproblem costs.
+- **Subproblem**: Solves operational decisions given fixed master values $y^*$, feeding back **Optimality Cuts** to the master.
+
+### Recommended: Automated Cut Generation with `sub.link()`
+
+Return the subproblem `Model` from your callback and register linking constraints with `sub.link(...)`. WaSHI automatically manages $\theta$, evaluates master candidate values, extracts duals, and injects Benders optimality cuts:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+// 1. Master problem: Facility location decisions
+const master = new Model("FacilityMaster");
+const y1 = master.binary("open_F1");
+const y2 = master.binary("open_F2");
+
+// Objective: Fixed facility costs (theta is managed automatically)
+master.objective(minimize(expr`100 * ${y1} + 120 * ${y2}`));
+// Minimal aggregate capacity requirement
+master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "capacity_check");
+
+// 2. Solve automatically with master.solveBenders()
+const result = await master.solveBenders({
+  gapTolerance: 1e-4,
+  subproblem: () => {
+    // Operational dispatch subproblem
+    const sub = new Model("TransportSubproblem");
+    const x11 = sub.continuous("x_11", { lb: 0 });
+    const x12 = sub.continuous("x_12", { lb: 0 });
+    const x13 = sub.continuous("x_13", { lb: 0 });
+    const x21 = sub.continuous("x_21", { lb: 0 });
+    const x22 = sub.continuous("x_22", { lb: 0 });
+    const x23 = sub.continuous("x_23", { lb: 0 });
+
+    sub.objective(
+      minimize(
+        expr`3 * ${x11} + 4 * ${x12} + 2 * ${x13} + 4 * ${x21} + 2 * ${x22} + 3 * ${x23}`
+      )
+    );
+
+    // Customer demand constraints
+    sub.constraint(expr`${x11} + ${x21} >= 20`, "demand_C1");
+    sub.constraint(expr`${x12} + ${x22} >= 25`, "demand_C2");
+    sub.constraint(expr`${x13} + ${x23} >= 30`, "demand_C3");
+
+    // Link subproblem flows with master decisions y1, y2 via linking constraints
+    sub.link(expr`${x11} + ${x12} + ${x13} <= 50 * ${y1}`);
+    sub.link(expr`${x21} + ${x22} + ${x23} <= 60 * ${y2}`);
+
+    return sub; // Returning the model automatically generates cuts and manages theta
+  },
+});
+
+console.log("Optimal total cost:", result.objectiveValue); // 390
+console.log("Iterations:", result.iterations);
+console.log("Cuts added:", result.cutsAdded);
+console.log("Facility decisions:", {
+  F1: result.values.open_F1,
+  F2: result.values.open_F2,
+});
+```
+
+### Low-Level Control: Custom `BendersCut` Callback
+
+You can also construct Benders cuts manually by returning `BendersCut` objects:
+
+```typescript
+const result = await master.solveBenders({
+  gapTolerance: 1e-4,
+  subproblem: async () => {
+    const open1 = y1.value ?? 0;
+    const open2 = y2.value ?? 0;
+    const estTheta = theta.value ?? 0;
+
+    const sub = new Model("TransportSubproblem");
+    // ...
+    await sub.solve();
+
+    const actualCost = sub.objectiveValue!;
+    if (estTheta < actualCost - 1e-4) {
+      return {
+        kind: "optimality",
+        constraint: expr`${theta} - 50 * ${sub.solution!.duals.cap1} * ${y1} - 60 * ${sub.solution!.duals.cap2} * ${y2} >= ${rhs}`,
+        subproblemObjective: 100 * open1 + 120 * open2 + actualCost,
+      };
+    }
+    return null; // Converged
+  },
+});
+```
+
+---
+
+## Application Examples
+
+Two common applications of decomposition methods:
+
+### 1. Vehicle Routing Problem (CVRP) $\times$ Column Generation
+*(Full executable source: [`examples/node/13-vehicle-routing-column-generation.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts))*
+
+* **Problem Structure**: Enumerating every feasible customer tour upfront produces a large number of variables.
+* **Column Generation Formulation**:
+  * **Master Problem**: Set covering model that selects the minimum number of vehicle routes such that each customer is served.
+  * **Pricing Subproblem**: Knapsack model that dynamically generates a capacity-feasible route (column) with negative reduced cost based on customer dual shadow prices.
+
+```typescript
+import { Model, expr, minimize, LinExpr, type Var } from "@ohtaman/washi";
+
+const vehicleCapacity = 8;
+const customers = [
+  { id: "C1", demand: 4 },
+  { id: "C2", demand: 3 },
+  { id: "C3", demand: 5 },
+  { id: "C4", demand: 2 },
+  { id: "C5", demand: 4 },
+];
+
+// 1. Master Problem: Customer coverage
+const master = new Model("CVRP_Master");
+const initialRoutes: Var[] = [];
+for (const cust of customers) {
+  initialRoutes.push(master.integer(`init_${cust.id}`, { lb: 0, ub: 1 }));
+}
+master.objective(minimize(initialRoutes.reduce((acc, r) => acc.add(r), new LinExpr())));
+
+for (let i = 0; i < customers.length; i++) {
+  master.constraint(expr`${initialRoutes[i]} >= 1`, `visit_${customers[i].id}`);
+}
+const visitConstrs = master.constraints;
+
+// 2. Solve via Column Generation
+const result = await master.solveColumnGeneration({
+  finalizeAsMIP: true,
+  pricing: async () => {
+    const sub = new Model("RoutePricing");
+    const a: Record<string, Var> = {};
+    const obj = new LinExpr();
+
+    for (let i = 0; i < customers.length; i++) {
+      const cust = customers[i];
+      a[cust.id] = sub.binary(`v_${cust.id}`);
+      obj.addTerm(a[cust.id], visitConstrs[i].dual ?? 0);
+    }
+
+    sub.objective(maximize(obj));
+
+    // Capacity limit: sum(demand_i * a_i) <= vehicleCapacity
+    const load = customers.reduce((acc, c) => acc.add(a[c.id].mul(c.demand)), new LinExpr());
+    sub.constraint(expr`${load} <= ${vehicleCapacity}`);
+
+    await sub.solve();
+
+    const coefficients: Record<string, number> = {};
+    for (const cust of customers) {
+      coefficients[`visit_${cust.id}`] = Math.round(a[cust.id].value ?? 0);
+    }
+
+    return {
+      cost: 1,
+      type: "Integer",
+      coefficients,
+    };
+  },
+});
+
+console.log("Optimal fleet size:", result.objectiveValue); // 3 vehicles
+```
+
+### 2. Traveling Salesperson Problem (TSP) $\times$ Benders Decomposition (Lazy Subtour Elimination)
+*(Full executable source: [`examples/node/14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts))*
+
+* **Problem Structure**: Preventing isolated sub-loops (subtours) requires Subtour Elimination Constraints (SECs), which grow as $O(2^n)$ constraints for $n$ cities.
+* **Benders Decomposition Formulation**:
+  * **Master Problem**: Solves the relaxed assignment problem (each city has 1 incoming and 1 outgoing edge).
+  * **Subproblem**: Evaluates the candidate tour graph for disconnected components. If isolated subtours exist, it lazily injects a Benders feasibility cut ($\sum_{i,j \in S} x_{ij} \le |S| - 1$) cutting off that cycle.
+
+```typescript
+import { Model, expr, minimize, LinExpr, type Var } from "@ohtaman/washi";
+
+const n = cities.length;
+const master = new Model("TSP_Master");
+const x: Record<string, Var> = {};
+const objExpr = new LinExpr();
+
+for (let i = 0; i < n; i++) {
+  for (let j = 0; j < n; j++) {
+    if (i !== j) {
+      const v = master.binary(`x_${i}_${j}`);
+      x[`${i}_${j}`] = v;
+      objExpr.addTerm(v, dist(i, j));
+    }
+  }
+}
+master.objective(minimize(objExpr));
+
+// Degree constraints
+for (let i = 0; i < n; i++) {
+  const outE = new LinExpr();
+  const inE = new LinExpr();
+  for (let j = 0; j < n; j++) {
+    if (i !== j) {
+      outE.addTerm(x[`${i}_${j}`], 1);
+      inE.addTerm(x[`${j}_${i}`], 1);
+    }
+  }
+  master.constraint(expr`${outE} == 1`, `out_${i}`);
+  master.constraint(expr`${inE} == 1`, `in_${i}`);
+}
+
+// Solve with Benders lazy subtour elimination
+const result = await master.solveBenders({
+  subproblem: () => {
+    const cycles = findCycles(n, (i, j) => (x[`${i}_${j}`].value ?? 0) > 0.5);
+    if (cycles.length === 1 && cycles[0].length === n) {
+      return null; // Single tour covers all cities
+    }
+
+    // Subtour detected: inject Benders feasibility cut for smallest cycle
+    const S = cycles.reduce((min, c) => (c.length < min.length ? c : min), cycles[0]);
+    const secExpr = new LinExpr();
+    for (const i of S) {
+      for (const j of S) {
+        if (i !== j) secExpr.addTerm(x[`${i}_${j}`], 1);
+      }
+    }
+    return {
+      kind: "feasibility",
+      constraint: expr`${secExpr} <= ${S.length - 1}`,
+    };
+  },
+});
+```

package/docs/guide/unsat-core.md

@@ -42,16 +42,23 @@ Notice that `routine_operating_cost` is **not** in the core, because only `minim
 > - **Use `m.check({ solver: "z3" })` for Unsat Core extraction**: `m.solve()` runs optimization (`Z3.Optimize`), whereas `m.check()` runs tracked satisfiability checking (`Z3.Solver.assertAndTrack`) and populates `result.conflicts` / `m.conflicts` (and alias `m.unsatCore`).
 > - **Name your constraints**: Variable bounds (`lb`, `ub`) act as background domain declarations. To include a bound or business rule in the reported `unsatCore` list, register it as a named constraint via `m.constraint(expr`...`, "rule_name")`.
 
-### Workflow: Optimize with HiGHS, Diagnose with Z3
+### Workflow: Infeasibility Diagnosis with HiGHS or Z3
 
-Because WaSHI models are solver-independent, you can solve your optimization model with **HiGHS** first and automatically fall back to **Z3** `m.check()` if HiGHS reports `"Infeasible"`:
+Because WaSHI models are solver-independent, you can diagnose infeasibilities using either solver:
+1. **Built-in HiGHS & GLPK (default)**: `await m.check()` uses a single-solve elastic slack formulation ($\min \sum s_i$) to identify which constraints required relaxation (`diag.conflicts`), requiring no extra dependencies.
+2. **Z3 SMT Solver**: `await m.check({ solver: "z3" })` uses SMT tracking to extract an exact unsatisfiable core (`diag.unsatCore` / `diag.conflicts`).
 
 ```typescript
 const status = await m.solve(); // Fast MIP solve with default HiGHS
 
 if (status === "Infeasible") {
-  const diag = await m.check({ solver: "z3" });
+  // Option 1: Built-in single-solve elastic diagnosis with HiGHS
+  const diag = await m.check();
   console.error("Model is infeasible due to conflicting rules:", diag.conflicts);
+
+  // Option 2: Exact SMT unsat core diagnosis with Z3 (requires import "@ohtaman/washi/solvers/z3")
+  // const z3Diag = await m.check({ solver: "z3" });
+  // console.error("Z3 Unsat Core:", z3Diag.unsatCore);
 }
 ```
 

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
 >   ```
@@ -132,9 +135,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 されます。
 

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 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).
+
+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.
 - **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 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).
+
+### 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.
+- **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`).
 
 ---
 

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 |
 
 ---

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
 >   ```
@@ -132,9 +135,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。