@ohtaman/washi 0.5.0 → 0.6.0

package/llms-full.txt

@@ -3,7 +3,10 @@
 > **Scope Note**: This document is the **consumer modeling quick-reference** for AI coding agents and developers building optimization or satisfiability models with `@ohtaman/washi`.
 > - **Portable Agent Skill (`SKILL.md`)**: For an actionable end-to-end modeling, `toLpString()` inspection, `validateSolution()` verification, and Z3 `unsatCore` conflict-diagnosis workflow skill (compatible with Claude Code, Antigravity, Cursor, Codex, and other `SKILL.md`-aware agents), use [`skills/washi/SKILL.md`](https://github.com/ohtaman/washi/blob/main/skills/washi/SKILL.md) (also shipped in the npm package at `node_modules/@ohtaman/washi/skills/washi/SKILL.md`):
 >   ```bash
->   # Link or copy the packaged skill into your project's agent skills directory
+>   # Install directly via the skills CLI (skills.sh / vercel-labs/skills)
+>   npx skills add ohtaman/washi
+>
+>   # Or link/copy the packaged skill into your project's agent skills directory
 >   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" });
   - Returns `SolverStatus` (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`, `"Sat"`, or `"Unsat"`). Built-in optimization solvers return the optimization statuses (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`), where a time-, iteration-, or solution-limited run (or an interrupted solve) that found a valid primal incumbent returns `"Feasible"`; `"Sat"` and `"Unsat"` are included in `SolverStatus` for satisfiability/custom solver adapters (such as `MockSolver`).
   - Read values via `x.value`, `expr`...`.value`, `m.getValues(x)`, `m.getValues(container)`, `m.objectiveValue`, `constr.dual`, `constr.slack`, and `x.reducedCost`.
   - Call `m.validateSolution()` after solving to independently verify variable finiteness, variable bounds (`lb`/`ub`), integer/binary/boolean domains, linear constraint residuals, and logical constraints (`SolutionValidationReport`: `{ valid, complete, maxViolation, violations, ... }`). Note that `validateSolution()` checks primal feasibility of variables and constraints; it does not recompute or compare `m.objectiveValue`.
-- **Satisfiability & Unsat Core (`await m.check(options?)`)**:
-  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` and `unsatCore` are optional and populated only when an unsat-core-capable solver (such as Z3) returns `"Unsat"`.
-  - For models containing only linear arithmetic constraints, `m.check()` works with any solver (including the default HiGHS and GLPK) by falling back to a feasibility `solve()`. Logical constraints (`BoolVar`, `and`, `or`, `implies`, etc.) and unsatisfiable-core extraction (`result.conflicts` / `result.unsatCore`) require an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `conflicts` / `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
+- **Satisfiability & Conflict Diagnosis (`await m.check(options?)`)**:
+  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` is populated when the model is proven `"Unsat"`.
+  - For models containing linear arithmetic constraints or logical constraints (`BoolVar`, `and`, `or`, `implies`, `xor`), `m.check()` works with any solver (including the default HiGHS and GLPK via single-solve elastic slack relaxation, automatically linearizing logical constraints into 0-1 MIP formulation) and diagnoses conflicting constraints as `conflicts` (leaving `unsatCore: undefined` for semantic rigor).
+  - Exact SMT unsatisfiable-core extraction (`result.unsatCore` and `result.conflicts`) is provided when using an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
 - **No concurrent mutation during async solve/check**:
   - Mutating variables, constraints, or the objective while `await m.solve()` or `await m.check()` is pending invalidates the in-flight execution and rejects the stale promise.
 
@@ -1254,7 +1258,7 @@ m.constraint(and(or(isAdmin, hasMfa), not(xor(isAdmin, hasMfa))), "policy");
 | :--- | :--- | :--- |
 | **Trigger variable** | Numeric `Binary` variable (`m.binary()`) | `BoolVar` (`m.bool()`), `BoolOp`, or `Constraint` |
 | **Consequent** | Linear `Constraint` (`<=`, `>=`, `==`) | `BoolVar`, `BoolOp`, or linear `Constraint` |
-| **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **Z3 SMT solver** (`capabilities.supportsSMT: true`) |
+| **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **All solvers** (HiGHS and GLPK via automatic 0-1 MIP linearization, Z3 natively) |
 | **Best For** | Operations research & MIP optimization with an objective (`m.solve()`) | Rule engines, policy verification, and SMT feasibility (`m.check()`) |
 
 ---
@@ -1495,16 +1499,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);
 }
 ```
 
@@ -1601,6 +1612,408 @@ console.log(x.value, y.value); // 10, 20
 
 ---
 
+# 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}`,
+    };
+  },
+});
+```
+
+---
+
 # Solvers Overview
 
 WaSHI is designed around a pluggable, decoupled solver architecture. You formulate mathematical models using a unified algebraic API, then solve them with the engine best suited for your problem class.
@@ -1611,9 +2024,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 |
 
 ---
@@ -1648,17 +2061,39 @@ const m3 = new Model({ solver: "glpk" });
 
 # 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`).
 
 ---
 
@@ -2010,7 +2445,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
@@ -2434,6 +2869,8 @@ Explore runnable optimization and logic formulations built with WaSHI. Every exa
 | **[Portfolio Optimization](docs/examples/portfolio-qp.md)** | Convex QP | HiGHS | `m.continuous()`, `m.constraint()`, `dot()`, `QuadExpr` | Markowitz mean-variance risk minimization ($w^T \Sigma w$) using `QuadExpr` subject to return targets. | [Playground](https://ohtaman.github.io/washi/demo/?preset=portfolio_qp) |
 | **[SMT Security Policies](docs/examples/smt-security.md)** | SMT Logic | Z3 | `m.bool()`, `m.constraint()`, `m.check()` | Propositional variables (`BoolVar`) and logical connectives (`implies`, `and`, `not`, `xor`) mixed with integer bounds. | [Playground](https://ohtaman.github.io/washi/demo/?preset=smt_sat_scheduling) |
 | **[Conflict Diagnosis (`unsatCore`)](docs/examples/unsat-core.md)** | Unsat Core | Z3 | `m.constraint()`, `m.check()`, `m.unsatCore` | Extracting a conflicting constraint subset (`unsatCore`) when staffing and budget rules contradict each other. | [Playground](https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat) |
+| **[Vehicle Routing (CVRP)](docs/examples/vehicle-routing.md)** | Combinatorial OR / Dantzig-Wolfe | HiGHS | `m.solveColumnGeneration()`, `pricing` | Dynamic route column generation from customer dual shadow prices to minimize total fleet vehicles. | [Decomposition Guide](docs/guide/decomposition.md) |
+| **[Traveling Salesperson (TSP)](docs/examples/traveling-salesperson.md)** | Combinatorial OR / Benders | HiGHS | `m.solveBenders()`, `subproblem` | Subtour elimination on degree-assignment relaxation using dynamic Benders feasibility cuts. | [Decomposition Guide](docs/guide/decomposition.md) |
 
 ## Find by WaSHI API (Reverse Index)
 
@@ -2451,6 +2888,8 @@ Looking for a specific modeling method or solver capability? Jump straight to th
 | `new QuadExpr()` | Convex quadratic objectives ($x^T Q x$) | [Portfolio Optimization](docs/examples/portfolio-qp.md) | [`03-portfolio-qp.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) |
 | `m.bool()` & `.implies()` | Propositional logic & SMT rules | [SMT Security Policies](docs/examples/smt-security.md) | [`04-smt-security-rules.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) |
 | `m.check()` & `m.unsatCore` | Feasibility check & conflict diagnosis | [Conflict Diagnosis](docs/examples/unsat-core.md), [Shift Scheduling](docs/examples/shift-scheduling.md) | [`05-unsat-core-diagnosis.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) |
+| `m.solveColumnGeneration()` | Dantzig-Wolfe Column Generation | [Vehicle Routing](docs/examples/vehicle-routing.md) | [`13-vehicle-routing-column-generation.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts) |
+| `m.solveBenders()` | Benders Decomposition & cut separation | [Traveling Salesperson](docs/examples/traveling-salesperson.md) | [`14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) |
 | `solver: "glpk"` | Solving LP/MIP with GLPK plugin | [GLPK Solver Guide](docs/solvers/glpk.md) | [`08-glpk-solver-plugin.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/08-glpk-solver-plugin.ts) |
 
 ## Running Examples Locally in Node.js
@@ -3247,3 +3686,380 @@ async function diagnoseConflicts() {
 
 diagnoseConflicts();
 ```
+
+---
+
+# Capacitated Vehicle Routing Problem (CVRP, 50 Customers via Column Generation)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Combinatorial OR / Dantzig-Wolfe | HiGHS (default) | `m.solveColumnGeneration()`, `pricing`, `sum()`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts">Source Code</a></li><li><a href="../guide/decomposition.md">Decomposition Guide</a></li></ul> |
+
+The **Capacitated Vehicle Routing Problem (CVRP)** determines the minimum number of delivery vehicles needed to visit a set of customers, subject to vehicle cargo capacity, maximum customer stops per shift, and route duration limits.
+
+In a monolithic MIP formulation, enumerating all possible customer combinations and visit sequences leads to $O(2^n)$ binary variables. With **Column Generation (Dantzig-Wolfe Decomposition)**, routes are generated on demand:
+1. **Restricted Master Problem (RMP)**: Solves a set partitioning problem that selects a subset of candidate routes so that every customer is visited once.
+2. **Pricing Subproblem**: Uses the dual values (shadow prices) from the master LP relaxation to construct improving routes with negative reduced cost ($\bar{c} = 1 - \sum \pi_i < 0$) via cheapest insertion and 2-opt local search.
+
+## Problem Inputs
+
+We consider a distribution network with a central depot at $(0, 0)$ and **50 customer locations**:
+
+- **Vehicle Cargo Capacity**: At most **10 units** per vehicle.
+- **Maximum Stops**: At most **4 customers** per route.
+- **Maximum Shift Duration**: At most **200 minutes** (transit time + service time) per route.
+- **Transit & Service Times**: Euclidean distances between nodes (1 unit = 1 minute) plus **10 minutes** of unloading service time per customer.
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, expr, minimize, sum } from "@ohtaman/washi";
+
+// --- Extracted Routing Helpers ---
+
+// 2-opt local search to eliminate crossing paths in a tour
+function optimize2Opt(tour, dist) {
+  let best = [...tour];
+  let improved = true;
+
+  while (improved) {
+    improved = false;
+    for (let i = 1; i < best.length - 2; i++) {
+      for (let j = i + 1; j < best.length - 1; j++) {
+        const dCurrent = dist(best[i - 1], best[i]) + dist(best[j], best[j + 1]);
+        const dSwap = dist(best[i - 1], best[j]) + dist(best[i], best[j + 1]);
+        if (dSwap < dCurrent) {
+          best = [...best.slice(0, i), ...best.slice(i, j + 1).reverse(), ...best.slice(j + 1)];
+          improved = true;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// Inserts a customer into the tour at the position that minimizes detour distance
+function insertCheapest(tour, id, dist) {
+  let bestPos = 1;
+  let minCost = Infinity;
+
+  for (let p = 1; p < tour.length; p++) {
+    const cost = dist(tour[p - 1], id) + dist(id, tour[p]) - dist(tour[p - 1], tour[p]);
+    if (cost < minCost) {
+      minCost = cost;
+      bestPos = p;
+    }
+  }
+  return [...tour.slice(0, bestPos), id, ...tour.slice(bestPos)];
+}
+
+// Calculates transit time and total duration (transit + service) for a tour
+function calcRouteTime(tour, dist, serviceTimes) {
+  let travelTime = 0;
+  for (let i = 0; i < tour.length - 1; i++) {
+    travelTime += dist(tour[i], tour[i + 1]);
+  }
+  const serviceTime = tour.slice(1, -1).reduce((acc, id) => acc + (serviceTimes[id] ?? 0), 0);
+  return { travelTime, totalTime: travelTime + serviceTime };
+}
+
+// Pricing subproblem: Finds an improving route with negative reduced cost (1 - dualSum < 0)
+function findImprovingRoute(candidates, config) {
+  let bestRoute = null;
+  let minReducedCost = -1e-4;
+
+  for (const seed of candidates.slice(0, 15)) {
+    let tour = ["Depot", seed.id, "Depot"];
+    let load = seed.demand;
+    let dualSum = seed.dual;
+
+    for (const next of candidates) {
+      if (tour.includes(next.id)) continue;
+      if (load + next.demand > config.vehicleCapacity) continue;
+      if (tour.length - 2 >= config.maxStops) continue;
+
+      const candidateTour = optimize2Opt(insertCheapest(tour, next.id, config.dist), config.dist);
+      const { totalTime } = calcRouteTime(candidateTour, config.dist, config.serviceTimes);
+
+      if (totalTime <= config.maxRouteTime) {
+        tour = candidateTour;
+        load += next.demand;
+        dualSum += next.dual;
+      }
+    }
+
+    const reducedCost = 1 - dualSum;
+    if (reducedCost < minReducedCost) {
+      minReducedCost = reducedCost;
+      bestRoute = tour;
+    }
+  }
+  return bestRoute;
+}
+
+// --- Main CVRP via Column Generation ---
+
+async function runCVRP() {
+  const vehicleCapacity = 10;
+  const maxStops = 4;
+  const maxRouteTime = 200; // minutes
+
+  // Central depot and 50 customer locations
+  const depot = { id: "Depot", x: 0, y: 0 };
+  const customers = Array.from({ length: 50 }, (_, i) => {
+    const angle = i * 2.4;
+    const radius = 15 + (i % 5) * 8;
+    return {
+      id: `C${i + 1}`,
+      x: Math.round(Math.cos(angle) * radius),
+      y: Math.round(Math.sin(angle) * radius),
+      demand: 1 + (i % 4),
+      serviceTime: 10,
+    };
+  });
+
+  const nodes = Object.fromEntries([depot, ...customers].map((n) => [n.id, n]));
+  const dist = (a, b) =>
+    Math.round(Math.hypot(nodes[a].x - nodes[b].x, nodes[a].y - nodes[b].y));
+  const serviceTimes = Object.fromEntries(customers.map((c) => [c.id, c.serviceTime]));
+
+  const routeConfig = { dist, serviceTimes, vehicleCapacity, maxStops, maxRouteTime };
+
+  // 1. Build Restricted Master Problem (RMP)
+  const master = new Model("CVRP_FleetMaster");
+
+  // Initial naive routes: 1 dedicated vehicle per customer
+  const initialRoutes = customers.map((c) => master.binary(`route_init_${c.id}`));
+  master.objective(minimize(sum(initialRoutes)));
+
+  // Each customer must be visited by exactly 1 vehicle
+  for (let i = 0; i < customers.length; i++) {
+    master.constraint(expr`${initialRoutes[i]} == 1`, `visit_${customers[i].id}`);
+  }
+  const visitConstrs = master.constraints;
+
+  console.log(`Initial state: 50 naive single-customer routes (50 vehicles).`);
+  console.log("Solving via Column Generation with dual-directed heuristic pricing...");
+
+  // 2. Solve via Column Generation
+  const result = await master.solveColumnGeneration({
+    finalizeAsMIP: true,
+    pricing: async () => {
+      // 1. Sort customers by shadow price (dual profit) descending
+      const candidates = customers
+        .map((c, i) => ({ id: c.id, demand: c.demand, dual: visitConstrs[i].dual ?? 0 }))
+        .filter((c) => c.dual > 0)
+        .sort((a, b) => b.dual - a.dual);
+
+      // 2. Solve pricing subproblem: find route with negative reduced cost (dualSum > 1)
+      const bestRoute = findImprovingRoute(candidates, routeConfig);
+      if (!bestRoute) return null; // No improving column found
+
+      // 3. Propose new column to Restricted Master Problem
+      const { travelTime, totalTime } = calcRouteTime(bestRoute, dist, serviceTimes);
+      const coefficients = {};
+      for (const id of bestRoute.slice(1, -1)) {
+        coefficients[`visit_${id}`] = 1;
+      }
+
+      return {
+        cost: 1,
+        type: "Binary",
+        coefficients,
+        meta: { tour: bestRoute, travelTime, totalTime },
+      };
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Fleet Size: ${Math.round(result.objectiveValue ?? 0)} vehicles (heuristic column generation)`);
+  console.log(`Total Columns Generated: ${result.columnsAdded}`);
+
+  console.log("\nSample routes selected in fleet:");
+  const activeRoutes = result.generatedColumns.filter((c) => (c.variable.value ?? 0) > 0.5);
+  for (const r of activeRoutes.slice(0, 5)) {
+    const meta = r.proposal.meta;
+    console.log(`  ${meta?.tour.join(" -> ")} (Transit: ${meta?.travelTime}m, Total: ${meta?.totalTime}m)`);
+  }
+}
+
+runCVRP();
+```
+
+## Notes
+
+- **Master Problem and Pricing Separation**: The master problem solves the LP relaxation and final set-partitioning MIP, while the `pricing` callback searches for negative-reduced-cost routes using cheapest insertion and 2-opt local search.
+- **Dual Value Access**: Dual values from the master LP relaxation are read from `visitConstrs[i].dual` to prioritize customers with higher shadow prices during route construction.
+- **Route Metadata**: Each proposed column attaches `{ tour, travelTime, totalTime }` under `meta`, allowing the ordered stop sequence to be inspected from `result.generatedColumns` after the solve completes.
+
+---
+
+# Traveling Salesperson Problem (TSP via Benders Decomposition)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Combinatorial OR / Benders | HiGHS (default) | `m.solveBenders()`, `subproblem`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts">Source Code</a></li><li><a href="../guide/decomposition.md">Decomposition Guide</a></li></ul> |
+
+The **Traveling Salesperson Problem (TSP)** seeks the shortest closed tour that visits every city in a given set once and returns to the starting city.
+
+In the **Dantzig-Fulkerson-Johnson (DFJ)** formulation, preventing disconnected cycles (**subtours**) requires subtour elimination constraints for every non-empty proper subset of cities $S \subset V$:
+
+$$\sum_{i \in S, j \notin S} x_{ij} \ge 1 \quad \forall S \subset V, \; 2 \le |S| \le |V| - 1$$
+
+Because there are $2^n - 2$ subsets, enumerating all subtour constraints upfront is impractical as $n$ grows. With **Benders Decomposition (Lazy Constraint Separation)**, constraints are added only when violated:
+1. **Master Problem**: Solves the degree-assignment relaxation (each city has 1 incoming and 1 outgoing edge).
+2. **Separation Subproblem**: Inspects the candidate solution graph. If disconnected cycles exist, it adds a **Benders Feasibility Cut** eliminating the smallest cycle and resolves until a single connected tour is obtained.
+
+## Problem Inputs
+
+We consider **5 cities** on a 2D Euclidean coordinate grid:
+
+| City | Coordinates $(x, y)$ |
+| :--- | :---: |
+| **City A (0)** | $(0, 0)$ |
+| **City B (1)** | $(1, 0)$ |
+| **City C (2)** | $(1, 2)$ |
+| **City D (3)** | $(0, 2)$ |
+| **City E (4)** | $(0.5, 3)$ |
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, expr, minimize, LinExpr } from "@ohtaman/washi";
+
+async function runTSP() {
+  const cities = [
+    { name: "A", x: 0, y: 0 },
+    { name: "B", x: 1, y: 0 },
+    { name: "C", x: 1, y: 2 },
+    { name: "D", x: 0, y: 2 },
+    { name: "E", x: 0.5, y: 3 },
+  ];
+  const n = cities.length;
+
+  function dist(i, j) {
+    const dx = cities[i].x - cities[j].x;
+    const dy = cities[i].y - cities[j].y;
+    return Math.hypot(dx, dy);
+  }
+
+  // 1. Master Problem: Degree assignment relaxation
+  const master = new Model("TSP_BendersMaster");
+  const x = {};
+
+  for (let i = 0; i < n; i++) {
+    x[i] = {};
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        x[i][j] = master.binary(`x_${i}_${j}`);
+      }
+    }
+  }
+
+  // Objective: Minimize total tour distance
+  let totalDistance = new LinExpr();
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        totalDistance = totalDistance.add(x[i][j].mul(dist(i, j)));
+      }
+    }
+  }
+  master.objective(minimize(totalDistance));
+
+  // Each city must have 1 outgoing and 1 incoming edge
+  for (let i = 0; i < n; i++) {
+    let outExpr = new LinExpr();
+    let inExpr = new LinExpr();
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        outExpr = outExpr.add(x[i][j]);
+        inExpr = inExpr.add(x[j][i]);
+      }
+    }
+    master.constraint(expr`${outExpr} == 1`, `out_${i}`);
+    master.constraint(expr`${inExpr} == 1`, `in_${i}`);
+  }
+
+  console.log("Solving TSP with Benders lazy subtour elimination...");
+
+  // 2. Solve via Benders Decomposition
+  let cutCounter = 0;
+  const result = await master.solveBenders({
+    subproblem: () => {
+      // Find active directed edges in the master solution
+      const succ = {};
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i !== j && Math.round(x[i][j].value ?? 0) === 1) {
+            succ[i] = j;
+          }
+        }
+      }
+
+      // Trace connected cycles
+      const visited = new Set();
+      const cycles = [];
+      for (let i = 0; i < n; i++) {
+        if (!visited.has(i)) {
+          const cycle = [];
+          let curr = i;
+          while (!visited.has(curr)) {
+            visited.add(curr);
+            cycle.push(curr);
+            curr = succ[curr];
+          }
+          cycles.push(cycle);
+        }
+      }
+
+      // If more than 1 cycle, subtours exist: inject Benders feasibility cut
+      if (cycles.length > 1) {
+        const smallestCycle = cycles.reduce((min, c) => (c.length < min.length ? c : min));
+        const S = new Set(smallestCycle);
+        cutCounter++;
+        console.log(`Subtour detected: [${smallestCycle.map(k => cities[k].name).join(" -> ")}]. Adding Benders cut #${cutCounter}.`);
+
+        let cutLhs = new LinExpr();
+        for (const i of S) {
+          for (let j = 0; j < n; j++) {
+            if (!S.has(j)) {
+              cutLhs = cutLhs.add(x[i][j]);
+            }
+          }
+        }
+
+        return {
+          kind: "feasibility",
+          constraint: expr`${cutLhs} >= 1`,
+          name: `subtour_cut_${cutCounter}`,
+        };
+      }
+
+      return null; // Single connected tour found
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Optimal Tour Distance: ${result.objectiveValue?.toFixed(3)}`);
+  console.log(`Total Benders Cuts Added: ${result.cutsAdded}`);
+  console.log(`Iterations: ${result.iterations}`);
+
+  console.log("\nOptimal tour edges:");
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      if (i !== j && (result.values[`x_${i}_${j}`] ?? 0) > 0.5) {
+        console.log(`  ${cities[i].name} -> ${cities[j].name} (distance: ${dist(i, j).toFixed(3)})`);
+      }
+    }
+  }
+}
+
+runTSP();
+```
+
+## Notes
+
+- **Lazy Subtour Elimination**: The master problem starts with only the $2n$ degree constraints, and subtour elimination cuts are added on demand when disconnected cycles appear in the master solution.
+- **Separation Callback**: The `subproblem` callback reads candidate edge values via `x[i][j].value`, traces connected components in $O(n)$, and returns `{ kind: "feasibility", constraint: ... }` when multiple cycles are present.
+- **Termination Condition**: Returning `null` from `subproblem` indicates that no violated subtour constraints remain.