@ohtaman/washi 0.5.0 → 0.7.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
 >   ```
@@ -54,7 +57,7 @@ import "@ohtaman/washi/solvers/glpk";
 1. **Bundled WASM by default (no implicit CDN fallback)**:
    - In Node.js and modern bundlers, WebAssembly assets resolve relative to the module automatically.
    - In browser deployments, deploy the full `dist/browser/` directory (JS, Worker, and `.wasm` files) together. If a local WASM URL is missing or returns an HTML SPA fallback, initialization fails immediately and reports the attempted URL—it **never** silently switches to a public CDN.
-   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads the local Node `highs` package runtime).
+   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads WaSHI's bundled local `highs.wasm` runtime).
 2. **Z3 requires a Secure Context, Cross-Origin Isolation, and CORS in browsers**:
    - Z3 WebAssembly uses `SharedArrayBuffer` multithreading. Browser pages running Z3 must run in a secure context (`window.isSecureContext === true`, i.e., HTTPS or `localhost`) and be cross-origin isolated (`window.crossOriginIsolated === true`) by serving:
      - `Cross-Origin-Opener-Policy: same-origin` (on the document)
@@ -63,7 +66,7 @@ import "@ohtaman/washi/solvers/glpk";
    - Importing `@ohtaman/washi` never auto-injects a Service Worker. When a secure context or cross-origin isolation is absent in a browser, Z3 rejects immediately with a descriptive error.
 3. **Web Workers & Cancellation (`AbortSignal`)**:
    - Pre-solve cancellation (`signal.aborted` before execution starts) is supported across all solvers.
-   - In browsers where `Worker` is available, HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
+   - In browsers where `Worker` is available on a non-opaque effective origin (`window.origin !== "null"`), HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). On opaque effective origins (`window.origin === "null"`, such as `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), HiGHS defaults to main-thread execution (`useWorker: false`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
    - On main-thread HiGHS (`useWorker: false` or in Node.js), cooperative mid-solve cancellation is supported when `abort()` is triggered synchronously inside an `onProgress` callback at a solver interrupt checkpoint; arbitrary asynchronous aborts from outside cannot preempt a blocked synchronous WASM thread until a callback checkpoint or completion. Single-threaded WASM solvers without interrupt hooks (GLPK, Z3) check `signal` before execution starts.
 
 ---
@@ -79,6 +82,7 @@ const m = new Model("ExampleModel");
 
 // Scalar variables
 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"); // Propositional boolean (for Z3 / logical constraints)
@@ -100,12 +104,12 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 ### Step 2: Build Expressions (`expr`, `sum`, `dot`)
 
 - **Unified `expr` template tag**:
-  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``
-  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` `` (variable-by-variable products and squares are supported for convex QP objectives).
-  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` `` (supports `<=`, `>=`, `==`, and `=`).
-- **Aggregations**:
-  - `sum(iterable, mapper?)` sums an `Iterable` of `Var` / `LinExpr` / `number` (e.g., `Var[]`, `grid.flat()`, or `Object.values(record)`).
-  - `dot(a, b)` computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
+  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``, `` expr`dot(${profit}, ${byItem}) - 20 * ${b}` ``, `` expr`sum((${price} - ${cost}) * ${byItem})` ``
+  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``, `` expr`sum((${vec} - ${target})^2)` `` (supported for convex QP objectives on purely continuous models using `m.continuous`; built-in HiGHS does not support MIQP models containing integer, binary, or boolean variables).
+  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` ``, `` expr`sum(${byItem}) <= 100` `` (supports `<=`, `>=`, `==`, and `=`).
+- **Aggregations & Element-Wise Container Arithmetic**:
+  - `sum(containerOrItems, mapper?)` (usable inside `` expr`sum(...)` `` or standalone `sum(...)`) sums a 1D/2D `Array`, `Iterable`, or plain `Record` of `Var` / `LinExpr` / `number` (without needing `Object.values(record)`), or maps over items/counts via `sum(items, (item, i) => ...)`. Inside `` expr`sum(...)` ``, element-wise container arithmetic (`+`, `-`, `*`, `/`, `^2`) is also supported.
+  - `dot(a, b)` (usable inside `` expr`dot(${a}, ${b})` `` or standalone `dot(a, b)`) computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`, computing the Frobenius inner product $\sum_{i,j} A_{i,j} B_{i,j}$), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
 - **Fluent methods**:
   - Arithmetic (on `LinExpr` and `QuadExpr`; `Var` supports `.add()`, `.sub()`, `.mul()`, `.neg()`): `.add(other)`, `.sub(other)`, `.mul(other)`, `.div(scalar)`, `.neg()`
   - Comparisons (on `Var` and `LinExpr`): `.le(rhs, name?)`, `.ge(rhs, name?)`, `.eq(rhs, name?)`
@@ -119,8 +123,8 @@ Constructing an `expr` or `.le()` object does **not** attach it to the model unt
 // Set objective using maximize() or minimize()
 m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
 
-// Register constraints on the model
-m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+// Register constraints on the model (returns the registered Constraint / BoolExpr or array)
+const limit = m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
 
 // Indicator constraint (MIP Big-M reformulation: 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" });
   - 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.
 
@@ -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();
@@ -265,24 +273,46 @@ export function verifyNegativePatterns() {
 }
 ```
 
+### Practical OR Modeling Guardrails
+
+- **Prefer inequalities (`>=` / `<=`) over exact equalities (`==`)** for demand coverage and resource limits when objective costs are positive; reserve `==` for physical conservation laws (e.g., flow balance, portfolio weights summing to `1`).
+- **Always provide finite `lb` and `ub` bounds** on variables referenced inside `m.indicator(...)` and omit `M` so WaSHI automatically derives the tightest valid Big-M instead of falling back to `1e6`.
+- **Use soft constraints (elastic slack variables)** for non-rigid business targets (e.g., preferred staffing, safety stock, day-off requests) by adding a non-negative slack variable (`lb: 0`) with a tiered objective penalty, reserving hard constraints for physical or legal invariants.
+
 ---
 
 # Introduction & Installation
 
-Welcome to **WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface).
+**WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) brings the algebraic modeling style of Python's **PuLP** to the TypeScript and JavaScript ecosystem. Write expressions naturally with tagged templates (`expr`) and solve mathematical optimization problems directly in **Node.js and the browser** using WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**).
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model("production");
 
-WaSHI brings the algebraic modeling style of Python's **PuLP** and Julia's **JuMP** to the TypeScript and JavaScript ecosystem. You can formulate mathematical optimization problems using algebraic expressions and solve them locally using WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**)—without a separate Python service or native C/C++ build steps.
+// 1. Define decision variables with realistic finite bounds (lb / ub)
+const desks = m.integer("desks", { lb: 0, ub: 100 });
+const chairs = m.integer("chairs", { lb: 0, ub: 100 });
 
-### Why TypeScript & WebAssembly?
+// 2. Set the objective function and constraints
+m.objective(maximize(expr`30 * ${desks} + 50 * ${chairs}`));
+m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_capacity");
+m.constraint(expr`2 * ${desks} + ${chairs} <= 50`, "labor_capacity");
 
-- **Removing the deployment bottleneck**: In traditional optimization workflows (e.g., Python with PuLP or Pyomo), turning a model into an interactive application requires provisioning a backend service and managing native C/C++ solver binaries. As AI-assisted development accelerates UI and application prototyping, backend infrastructure often becomes the primary bottleneck to shipping. Running both the modeler and WebAssembly solvers on standard Web technologies allows an optimization tool to be deployed as static assets (e.g., on GitHub Pages or Cloudflare Pages, serving the generated JS, Worker, and WASM files; with COOP/COEP headers when using Z3)—and makes it straightforward to pair mathematical optimization with in-browser LLMs (e.g., WebGPU / WebLLM) entirely on the client.
-- **Algebraic syntax without operator overloading (`expr`)**: Because JavaScript lacks operator overloading, libraries usually trade off between verbose method chaining (`x.mul(30).add(y.mul(50))`) and untyped strings (`"30 * x + 50 * y"`). WaSHI uses tagged template literals (`` expr`30 * ${x} + 50 * ${y} <= 40` ``) similar to parameterized SQL queries—parsing infix operators while binding `${x}` directly as typed TypeScript object references for static type checking, IDE symbol renaming, and multi-dimensional indexing (`${flow[i][j]}`).
+// 3. Solve (built-in HiGHS WebAssembly) and validate the solution
+const status = await m.solve();
+if (m.hasPrimalSolution) {
+  const report = m.validateSolution();
+  console.log(status, report.valid); // "Optimal", true
+  console.log(`Profit: ${m.objectiveValue} (desks=${desks.value}, chairs=${chairs.value})`); // 1100 (desks=20, chairs=10)
+}
+```
 
 ---
 
 ## 📦 Installation
 
-Install WaSHI using your preferred package manager:
+The default **HiGHS** solver (LP / MIP / Convex QP) is bundled and works out of the box:
 
 ```bash [npm]
 npm install @ohtaman/washi
@@ -300,96 +330,54 @@ yarn add @ohtaman/washi
 bun add @ohtaman/washi
 ```
 
-### Optional Solver Dependencies
-
-WaSHI ships with **HiGHS** built-in with zero configuration. If you need SMT logic / Unsat Core diagnosis via **Z3**, or compatibility with **GLPK**, install their respective peer dependencies:
+Install optional peer dependencies only if you need **Z3** (SMT logic & Unsat Core diagnosis) or **GLPK**:
 
 ```bash
-# For SMT logic and Unsat Core conflict diagnosis
-npm install z3-solver
-
-# For GLPK solver (GPL-3.0)
-npm install glpk.js
+npm install z3-solver   # For SMT logic and Unsat Core conflict diagnosis
+npm install glpk.js     # For GLPK solver (GPL-3.0)
 ```
 
 ---
 
-## 🚀 Quickstart Walkthrough
-
-Here is a step-by-step example of solving a production allocation problem.
-
-### 1. Import the Core Classes
-
-```typescript
-import { Model, expr, maximize } from "@ohtaman/washi";
-```
-
-### 2. Instantiate a Model
-
-```typescript
-const model = new Model("WoodworkingProfit");
-```
-
-### 3. Add Decision Variables
-
-Variables represent the unknowns you want to determine. Factory methods (`m.continuous`, `m.integer`, `m.binary`) clearly define their domain:
+## 💡 Why TypeScript & WebAssembly?
 
-```typescript
-const x = model.integer("x", { lb: 0 });
-const y = model.integer("y", { lb: 0 });
-```
-
-### 4. Set the Objective Function
-
-Use the `expr` tagged template literal along with `maximize(...)` or `minimize(...)` to define the goal:
-
-```typescript
-// Maximize 30*x + 50*y
-model.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
-```
+- **Zero native setup across Node.js and the browser**: No platform-specific C/C++ builds or separate Python runtimes to manage. A single `npm install` runs the same modeling code across **Node.js APIs, CLIs, and scripts** as well as in the **browser**.
+- **Lightweight embedding with standard Web APIs & UIs**: Go beyond local analysis scripts by shipping **interactive Web tools, mini-games, or Chrome extensions** that anyone can open via a URL with zero backend hosting cost. You can wire mathematical optimization directly into drag-and-drop UIs or **standard browser capabilities**—such as screen/camera capture and speech recognition (Web Speech API)—with no network round-trips or external data transfer.
+- **End-to-end type safety from app data to model**: Prevent common indexing and dictionary-key mistakes with TypeScript's type system. Typed variable dictionaries (`Record<K, Var>`) and variable-reference interpolation (`` expr`30 * ${qty.desk} <= 40` ``) connect directly to your application schemas, preserving compile-time variable/key checks, IDE autocompletion, and symbol renaming.
+- **Strong synergy with AI development & LLM workflows**: Keeping your application and optimization model in a **single TypeScript codebase** lets you validate everything in one test runner—without crossing a Python service boundary—and deploy easily as static assets or a single service. That tight test-and-deploy loop fits AI-assisted coding naturally, while at runtime you can pair flexible LLM extraction with exact solver feasibility and conflict diagnosis (`unsatCore`) in the same runtime.
 
-### 5. Add Constraints
-
-Use `model.constraint()` with the `expr` tagged template to formulate equality and inequality constraints:
-
-```typescript
-model.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_capacity");
-model.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_capacity");
-```
-
-### 6. Solve and Extract Results
+---
 
-Solve the model asynchronously via WebAssembly (HiGHS by default):
+## 🔍 Core Workflow Essentials
 
-```typescript
-const status = await model.solve();
+Three practical habits cover the essentials shown in the snippet above:
 
-console.log("Status:", status); // "Optimal"
-console.log("Optimal Objective Value:", model.objectiveValue); // 1100
-console.log(`Solution: x = ${x.value}, y = ${y.value}`); // x = 20, y = 10
-```
+1. **Set realistic finite bounds (`lb`, `ub`)**: When defining variables with `m.continuous`, `m.integer`, or `m.binary`, finite bounds strengthen MIP presolve and enable automatic tight Big-M derivation for logical constraints.
+2. **Formulate objectives and constraints with `expr`**: Use `` m.objective(maximize(expr`...`)) `` and `` m.constraint(expr`... <= ...`, "name") ``. Naming constraints lets you pinpoint conflicting rules immediately if a model becomes infeasible.
+3. **Check `hasPrimalSolution` and call `validateSolution()`**: After `await m.solve()`, check `m.hasPrimalSolution` before reading `.value` on variables, and call `m.validateSolution()` to independently verify that bounds, integrality, and constraints hold within tolerance.
 
 ---
 
 ## 🧭 Next Steps
 
-- Give AI coding agents a concise API & deployment reference with the [AI Coding Agent Quick-Reference Guide](docs/getting-started/ai-agents.md).
-- Learn how to run WaSHI across different environments in [Runtime Environments](docs/getting-started/runtimes.md).
-- Understand how to formulate complex expressions in the [Modeling Guide](docs/guide/expressions.md).
-- Explore built-in and pluggable solvers in the [Solvers Matrix](docs/solvers/index.md).
-- Browse 9 runnable optimization and SMT recipes in [Examples & API Finder](docs/examples/index.md).
+- **[Modeling Guide](docs/guide/variables.md)**: Array/dictionary variables, aggregations (`sum`, `dot`), logical constraints, and Unsat Core diagnosis
+- **[Examples & API Finder](docs/examples/index.md)**: 11 runnable optimization and SMT recipes—from shift scheduling and portfolio QP to vehicle routing
+- **[Solvers Overview](docs/solvers/index.md)**: Compare built-in HiGHS with optional Z3 and GLPK adapters
+- **[Runtime Environments](docs/getting-started/runtimes.md)**: Setup details for Node.js, Vite / Next.js bundlers, CDNs, and static hosting
 
 ---
 
 # Runtime Environments & Deployment
 
-WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, vanilla browser `<script>` tags, and air-gapped intranets—without native C/C++ compilation.
+WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, static hosting, and vanilla browser `<script>` tags—without native C/C++ compilation.
 
 ---
 
-## 🟢 Node.js
+## 🟢 Node.js, Bun & Deno
 
-WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package.
+### Node.js
+
+WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package:
 
 ```typescript
 import { Model, expr, maximize } from "@ohtaman/washi";
@@ -402,8 +390,10 @@ m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
 m.constraint(expr`${x} + ${y} <= 15`, "capacity");
 
 await m.solve();
-console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
-console.log(`x = ${x.value}, y = ${y.value}`);
+if (m.hasPrimalSolution) {
+  console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
+  console.log(`x = ${x.value}, y = ${y.value}`);
+}
 ```
 
 Run directly with `tsx` or `node`:
@@ -412,11 +402,33 @@ Run directly with `tsx` or `node`:
 npx tsx app.ts
 ```
 
+### Bun & Deno
+
+```bash
+# Bun
+bun add @ohtaman/washi
+bun run app.ts
+```
+
+In Deno (v1.30+ with `npm:` specifiers):
+
+```typescript
+import { Model, maximize } from "npm:@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0, ub: 10 });
+m.objective(maximize(x));
+await m.solve();
+if (m.hasPrimalSolution) {
+  console.log("x =", x.value);
+}
+```
+
 ---
 
-## 🌐 Bundlers (Vite, Webpack, Rollup, Next.js)
+## 🌐 Bundlers & Static Hosting (Vite, Next.js, Webpack, Rollup)
 
-### Modern Bundlers (Vite / Rollup / Webpack)
+### Modern Bundlers & Static Deployment
 
 When importing `@ohtaman/washi` in a browser bundler, the `browser` export condition resolves automatically:
 
@@ -428,14 +440,16 @@ export async function runOptimization() {
   const x = m.continuous("x", { lb: 0, ub: 100 });
   m.objective(maximize(x));
   await m.solve();
-  return x.value;
+  return m.hasPrimalSolution ? x.value : null;
 }
 ```
 
+Because both the modeler and solver run on WebAssembly, the static output of `vite build` (or your bundler's production build) can be deployed directly to **GitHub Pages, Cloudflare Pages, Vercel, or Netlify** with no backend server required. (The default HiGHS and GLPK solvers require no special HTTP headers; if you use Z3 in the browser, see [Cross-Origin Isolation](docs/getting-started/cross-origin.md).)
+
 #### Background Web Worker Execution (Default)
-In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so long-running LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
+In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
 
-If your environment prohibits Web Workers or you explicitly want synchronous main-thread execution, pass `useWorker: false`:
+If your environment prohibits Web Workers or you explicitly want main-thread execution, pass `useWorker: false`:
 
 ```typescript
 await m.solve({ useWorker: false });
@@ -474,7 +488,9 @@ export default function OptimizerComponent() {
     const x = m.continuous("x", { lb: 0, ub: 50 });
     m.objective(maximize(x));
     await m.solve();
-    setVal(x.value);
+    if (m.hasPrimalSolution) {
+      setVal(x.value);
+    }
   };
 
   return (
@@ -490,36 +506,36 @@ export default function OptimizerComponent() {
 
 ## 📦 Browser ESM (`<script type="module">`)
 
-You can import the pre-bundled browser ESM modules directly from a local static server (or from an npm CDN once a compatible release is published) without a build step:
+Without a bundler, you can import the pre-built browser ESM module directly from your own static server or an npm CDN:
 
 ```html
 <script type="module">
-  // Serve from your local static server / dist:
-  import { Model, expr, maximize } from "./dist/browser/washi.js";
-  // Or from an npm CDN once a compatible release is published:
-  // import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.js";
+  // From an npm CDN (or "./dist/browser/washi.js" when self-hosted):
+  import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.js";
   // Optional solver plugins:
-  // import "./dist/browser/solvers/glpk.js";
-  // import "./dist/browser/solvers/z3.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.js";
 
   const m = new Model("BrowserESM");
-  const x = m.integer("x", { lb: 0 });
-  const y = m.integer("y", { lb: 0 });
+  const x = m.integer("x", { lb: 0, ub: 100 });
+  const y = m.integer("y", { lb: 0, ub: 100 });
 
   m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
   m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
   m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor");
 
   await m.solve();
-  console.log("Optimal Objective:", m.objectiveValue);
+  if (m.hasPrimalSolution) {
+    console.log("Optimal Objective:", m.objectiveValue);
+  }
 </script>
 ```
 
 ---
 
-## 🟨 Classic `<script>` Tags (IIFE / Standalone Build / CDN)
+## 🟨 Classic `<script>` Tags (IIFE / Standalone HTML / CDN)
 
-For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
+For single-file HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
 
 ```html
 <!DOCTYPE html>
@@ -532,13 +548,11 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
     <h1>WaSHI Browser Optimization</h1>
     <pre id="output">Solving...</pre>
 
-    <!-- Core WaSHI + HiGHS (MIT) from local static build / assets -->
-    <script src="./dist/browser/washi.min.js"></script>
-    <!-- Or via CDN once a compatible release is published: -->
-    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js"></script> -->
+    <!-- Core WaSHI + HiGHS (MIT) via CDN (or "./dist/browser/washi.min.js" when self-hosted) -->
+    <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.min.js"></script>
     <!-- Optional plugins (auto-register on window.Washi): -->
-    <!-- <script src="./dist/browser/solvers/glpk.min.js"></script> -->
-    <!-- <script src="./dist/browser/solvers/z3.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.min.js"></script> -->
 
     <script>
       (async () => {
@@ -553,10 +567,12 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 
         await m.solve();
 
-        document.getElementById("output").textContent =
-          `Status: ${m.status}\n` +
-          `Objective: ${m.objectiveValue}\n` +
-          `x = ${x.value}, y = ${y.value}`;
+        if (m.hasPrimalSolution) {
+          document.getElementById("output").textContent =
+            `Status: ${m.status}\n` +
+            `Objective: ${m.objectiveValue}\n` +
+            `x = ${x.value}, y = ${y.value}`;
+        }
       })();
     </script>
   </body>
@@ -564,7 +580,7 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 ```
 
 > [!NOTE]
-> When loading `washi.min.js` from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction due to the same-origin policy. WaSHI automatically bridges cross-origin workers via a lightweight `Blob` wrapper using `importScripts()`, so Web Worker execution works out of the box from CDNs.
+> When loading from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction under the same-origin policy. On standard web origins (`https://` / `http://`), WaSHI automatically bridges cross-origin workers via a lightweight ES module `Blob` bootstrap (`import "https://..."`). On opaque effective origins (`window.origin === "null"`, such as local `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), WaSHI automatically runs HiGHS on the main thread when `useWorker` is omitted.
 
 ---
 
@@ -578,83 +594,81 @@ WaSHI never phones home or falls back to public CDNs. To self-host in an air-gap
    - Optional Z3: `solvers/z3.js` / `solvers/z3.min.js`, `solvers/z3-built.js`, `solvers/z3-built.wasm`
 2. **Content Security Policy (CSP) Headers**:
    - Allow WebAssembly compilation (`'wasm-unsafe-eval'` in `script-src`).
-   - If using the default Web Worker or cross-origin Blob worker fallback, allow `worker-src 'self' blob:;`.
+   - If using the default Web Worker or cross-origin Blob worker bootstrap, allow `worker-src 'self' blob:;`.
    - If `blob:` workers are prohibited by policy, either serve `highs-worker.js` from `'self'` or run on the main thread with `await m.solve({ useWorker: false })`.
 3. **Cross-Origin Isolation (Z3 Only)**:
    - HiGHS and GLPK run in standard browser contexts without special headers.
-   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). See the [Cross-Origin Isolation Guide](docs/getting-started/cross-origin.md) for setup details.
-
----
-
-## ⚡ Bun & Deno
-
-### Bun
-
-```bash
-bun add @ohtaman/washi
-bun run app.ts
-```
-
-### Deno
-
-In Deno (v1.30+ with `npm:` specifiers):
-
-```typescript
-import { Model, maximize } from "npm:@ohtaman/washi";
-
-const m = new Model();
-const x = m.continuous("x", { lb: 0, ub: 10 });
-m.objective(maximize(x));
-await m.solve();
-console.log("x =", x.value);
-```
+   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (`credentialless` works in Chromium/Firefox, whereas Safari requires `require-corp`). See the [Cross-Origin Isolation Guide](docs/getting-started/cross-origin.md) for setup details.
 
 ---
 
 # Cross-Origin Isolation (Z3 & Browsers)
 
-When running the **Z3** solver engine inside a web browser, special HTTP headers are required due to browser security models.
+When running the **Z3** solver inside a web browser, Cross-Origin Isolation HTTP headers are required so the browser enables `SharedArrayBuffer`.
+
+> [!TIP]
+> **Not needed for HiGHS, GLPK, or Node.js**: The built-in **HiGHS** solver and **GLPK** plugin run in standard browser contexts without Cross-Origin Isolation or `SharedArrayBuffer`. Running Z3 in **Node.js** also requires no HTTP headers. You only need this page when using `@ohtaman/washi/solvers/z3` in the browser.
 
 ---
 
 ## Why is Cross-Origin Isolation Required?
 
-The Z3 WebAssembly engine utilizes multithreading backed by `SharedArrayBuffer` and Web Workers.
-
-In modern browsers (Chrome, Firefox, Safari, Edge), `SharedArrayBuffer` is disabled by default to mitigate Spectre-style timing side-channel attacks. To re-enable it, the hosting page must be **Cross-Origin Isolated**.
+Z3's WebAssembly build uses multithreading (pthreads) backed by `SharedArrayBuffer` and Web Workers. Modern browsers (Chrome, Firefox, Safari, Edge) disable `SharedArrayBuffer` by default to mitigate Spectre-style side-channel attacks unless the top-level document opts into **Cross-Origin Isolation** (`window.crossOriginIsolated === true`).
 
 ---
 
 ## Required HTTP Response Headers
 
-To establish cross-origin isolation, your web server must serve the top-level HTML document with the following HTTP headers:
+Serve the top-level HTML document with:
 
 ```http
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-In addition, any cross-origin assets (e.g. scripts or WASM files loaded from external domains) must send:
+If your page loads cross-origin subresources (such as scripts, images, or WASM files from another domain), those responses must also include `Cross-Origin-Resource-Policy: cross-origin` (or CORS headers).
 
-```http
-Cross-Origin-Resource-Policy: cross-origin
-```
+> [!NOTE]
+> Chromium and Firefox also support `Cross-Origin-Embedder-Policy: credentialless`, which relaxes subresource CORP requirements, **but Safari (WebKit) does not support `credentialless`**. Use `require-corp` if you support Safari / iOS.
 
 ---
 
-## Solutions by Hosting Environment
+## Setup by Environment
 
-### 1. Custom Node.js / Express Server
+### 1. Vite (`vite.config.ts`)
 
-```javascript
-app.use((req, res, next) => {
-  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
-  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
-  next();
+Configure both the local dev server (`vite`) and production preview server (`vite preview`):
+
+```typescript
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  server: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
+  preview: {
+    headers: {
+      "Cross-Origin-Opener-Policy": "same-origin",
+      "Cross-Origin-Embedder-Policy": "require-corp",
+    },
+  },
 });
 ```
 
-### 2. Next.js (`next.config.js`)
+### 2. Cloudflare Pages / Netlify (`public/_headers`)
+
+Place a `_headers` file in `public/` so it is copied to the root of your build output:
+
+```text
+/*
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
+```
+
+### 3. Next.js (`next.config.js`)
 
 ```javascript
 /** @type {import('next').NextConfig} */
@@ -675,35 +689,40 @@ const nextConfig = {
 module.exports = nextConfig;
 ```
 
-### 3. Static Hosting without Header Control (e.g., GitHub Pages)
+### 4. Custom Node.js / Express Server
+
+```javascript
+app.use((req, res, next) => {
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+  next();
+});
+```
 
-Platforms like GitHub Pages or preview environments do not allow customizing response headers directly.
+### 5. Static Hosting without Header Control (e.g., GitHub Pages)
 
-For these environments, you can use **`coi-serviceworker`** (a lightweight Service Worker that injects isolation headers on the client side):
+Platforms like GitHub Pages do not allow customizing HTTP response headers directly. You can use **`coi-serviceworker`** to inject the isolation headers via a client-side Service Worker:
 
-1. Place `coi-serviceworker.js` in your website root.
-2. In your HTML `<head>`, include:
+1. Place `coi-serviceworker.js` at your site root.
+2. Load it in your HTML `<head>`:
 
 ```html
 <script src="/coi-serviceworker.js"></script>
 ```
 
-When a user visits for the first time, the service worker registers and reloads the page once to establish `window.crossOriginIsolated === true`.
+On the first visit, the Service Worker registers and reloads the page once to establish `window.crossOriginIsolated === true`.
 
 ---
 
-## Graceful Degradation in WaSHI
+## Runtime Check in WaSHI
 
-WaSHI's Z3 solver adapter automatically inspects the environment at runtime. If Z3 is invoked in a browser lacking cross-origin isolation, it immediately rejects with a clear, informative error message explaining that COOP/COEP headers or a service worker are required, rather than hanging silently.
-
-> [!TIP]
-> The default **HiGHS** solver engine does not require cross-origin isolation or `SharedArrayBuffer`. It works out of the box in standard browser contexts.
+WaSHI's Z3 adapter checks `crossOriginIsolated` before initializing Z3 in the browser. If Cross-Origin Isolation is missing, `solve()` / `check()` immediately rejects with an actionable error explaining that COOP/COEP headers or a Service Worker are required, rather than hanging silently.
 
 ---
 
 # 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()`.
 
 ---
@@ -711,7 +730,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";
@@ -723,7 +742,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]
@@ -731,48 +750,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$):
-
-```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");
+| 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 |
 
-// 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:
@@ -783,15 +797,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
 ```
 
@@ -825,16 +839,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 };
@@ -851,15 +865,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](docs/guide/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();
@@ -867,7 +881,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)
@@ -882,11 +896,11 @@ 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);
 ```
 
@@ -896,7 +910,7 @@ console.log("Total numeric variables:", m.numVars);
 
 Mathematical expressions are linear or quadratic combinations of decision variables and numeric coefficients.
 
-In JavaScript and TypeScript—which do not support operator overloading—WaSHI provides the **unified tagged template literal (`expr`)**, **`sum()`**, and matrix/vector **`dot()`** to construct algebraic expressions without losing static type safety.
+In JavaScript and TypeScript—which do not support operator overloading—WaSHI provides the **unified tagged template literal (`expr`)**, **`sum()`**, and matrix/vector **`dot()`** to construct algebraic expressions with full static type safety.
 
 | Approach | Example | Infix readability | Type safety & IDE rename | Indexed variables (`flow[i][j]`) |
 | :--- | :--- | :--- | :--- | :--- |
@@ -906,9 +920,9 @@ In JavaScript and TypeScript—which do not support operator overloading—WaSHI
 
 ---
 
-## ✍️ Tagged Template Literal (`expr`)
+## Tagged Template Literal (`expr`)
 
-Similar to parameterized `sql` tagged templates, `expr` receives the static operator text (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) separately from the interpolated `${...}` values (`Var`, `LinExpr`, `QuadExpr`, or finite `number`). Variables are bound by object reference rather than resolved by string name, avoiding naming collisions and preserving TypeScript type checking and IDE refactoring.
+Similar to parameterized `sql` tagged templates, `expr` receives static operator text (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) separately from interpolated `${...}` values (`Var`, `LinExpr`, `QuadExpr`, or finite `number`). Variables are bound by object reference rather than resolved by string name, avoiding naming collisions and preserving TypeScript type checking and IDE refactoring.
 
 Use `expr` for both arithmetic expressions (`LinExpr | QuadExpr`) and relational constraints (`Constraint`):
 
@@ -931,44 +945,55 @@ const balanceConstraint = expr`${x} + 2 * ${y} <= 40`;
 
 ### Supported Syntax in `expr`
 - **Addition & Subtraction**: `${x} + ${y} - 5`
-- **Scalar Multiplication**: `4 * ${x}`, `${x} * 4`
+- **Scalar Multiplication & Division**: `4 * ${x}`, `${x} / 2`
 - **Variable Multiplication (Quadratic terms)**: `${x} * ${y}`, `2 * ${x} * ${x}`
 - **Powers & Exponentiation**: `${x}^2`, `${x}**2`
-- **Unary Negation**: `-${x} + 10`
+- **Unary Plus & Negation**: `-${x} + 10`, `+${x}`
 - **Parentheses**: `2 * (${x} + ${y})`
-- **Nested Expressions**: `expr` seamlessly interpolates variables, numbers, `sum()` results, and nested expressions.
+- **Aggregations (`sum` & `dot`)**: `sum(${xVec}) <= 100`, `dot(${costs}, ${xVec})`, `sum(${rows}, ${(r) => grid[r][col]})`
+- **Element-Wise Container Arithmetic**: `sum((${price} - ${cost}) * ${qty})`, `sum((${xVec} - ${target})^2)`, `dot(${price} - ${cost}, ${qty})`
+- **Nested Expressions**: `expr` interpolates variables, numbers, `Array` / `Record` containers (inside `sum` or `dot`), and nested `LinExpr` / `QuadExpr` objects.
 
 > [!NOTE]
 > For relational comparisons (`<=`, `>=`, `==`), `expr` (e.g., ``expr`${x} + 2 * ${y} <= 40` ``) returns a first-class `Constraint`.
-> For arithmetic expressions without comparison operators, `expr` uniformly handles linear and quadratic expressions (up to degree 2): if quadratic terms are present, `expr` returns a `QuadExpr`; otherwise, it returns a `LinExpr`. Polynomial terms of degree $> 2$ (e.g. ``${x} * ${y} * ${z}``, ``${x}^3``) and non-linear constraints (e.g. ``${x} * ${y} <= 10``) are rejected because standard MILP/LP/QP formulations only support linear constraints and quadratic objectives.
+> For arithmetic expressions without comparison operators, `expr` uniformly handles linear and quadratic expressions (up to degree 2): if quadratic terms are present, `expr` returns a `QuadExpr`; otherwise, it returns a `LinExpr`. Interpolated `Array` or `Record` containers must be reduced to a scalar via `sum(...)` or `dot(..., ...)`. Polynomial terms of degree $> 2$ (e.g., ``${x} * ${y} * ${z}``, ``${x}^3``) and non-linear constraints (e.g., ``${x} * ${y} <= 10``) throw an error because LP/MIP/QP formulations require linear constraints and at most quadratic objectives.
 
 ---
 
-## ⚡ High-Performance Summation (`sum`)
+## High-Performance Summation (`sum`)
 
-For iterating over large collections of variables or indices:
+Sum 1D or 2D `Array`, `Iterable`, or `Record` containers directly inside `` expr`sum(...)` `` or via the standalone `sum()` helper:
 
 ```typescript
-import { sum } from "@ohtaman/washi";
+import { expr, sum } from "@ohtaman/washi";
 
-const items = ["A", "B", "C"];
+const items = ["A", "B", "C"] as const;
 const weights = { A: 10, B: 20, C: 30 };
 const x = m.binary(items);
 
-// 1. Transform elements with a mapping callback:
+// 1. Direct Record or Array summation inside expr (no Object.values() needed):
+m.constraint(expr`sum(${x}) <= 2`, "max_selected");
+
+// 2. Element-wise arithmetic inside expr`sum(...)`:
+const weightedExpr = expr`sum(${weights} * ${x})`;
+
+// 3. Transform elements with a mapping callback (standalone or inside expr):
 const totalWeight = sum(items, (item) => x[item].mul(weights[item]));
 
-// 2. Direct array summation:
-const count = sum(Object.values(x));
+// 4. Standalone 1D/2D Record or Array summation:
+const count = sum(x);
 ```
 
-`sum()` runs in $O(N)$ linear time without AST overhead.
+`sum()` runs in $O(N)$ linear time without AST parsing overhead.
+
+> [!TIP]
+> **Avoid $O(N^2)$ `expr` Re-Assignment Inside Loops**: Because `LinExpr` and `expr` results are immutable, accumulating terms one by one via ``total = expr`${total} + ${x[i]}` `` inside a loop copies all previously accumulated terms on every iteration ($O(N^2)$ time and memory). Pass arrays or records to `sum(x)` or `dot(coeffs, x)` for $O(N)$ construction.
 
 ---
 
-## 🎯 Dot Product (`dot`)
+## Dot Product (`dot`)
 
-The `dot(a, b)` helper computes linear combinations of numeric coefficients (`number`) and variables or linear expressions (`Var | LinExpr`) in either operand order (`dot(coeffs, vars)` or `dot(vars, coeffs)`).
+The `dot(a, b)` helper (usable both inside `` expr`dot(${a}, ${b})` `` and as a standalone function `dot(a, b)`) computes linear combinations of numeric coefficients (`number`) and variables or linear expressions (`Var | LinExpr`) in either operand order (`dot(coeffs, vars)` or `dot(vars, coeffs)`).
 
 Supported 1D and 2D container shapes:
 - **1D Arrays**: `number[]` $\times$ `(Var | LinExpr)[]`
@@ -981,41 +1006,74 @@ Mismatched array lengths, missing dictionary keys, or non-finite/non-linear leav
 
 ### 1D Vector Dot Product
 ```typescript
-import { dot } from "@ohtaman/washi";
+import { expr, dot } from "@ohtaman/washi";
 
 const profits = { desk: 30, chair: 50 };
-const vars = m.integer(["desk", "chair"]);
+const vars = m.integer(["desk", "chair"] as const);
 
-// Computes 30 * vars.desk + 50 * vars.chair
-const totalProfit = dot(profits, vars);
+// Computes 30 * vars.desk + 50 * vars.chair inside expr (or via standalone dot(profits, vars))
+const totalProfit = expr`dot(${profits}, ${vars})`;
 ```
 
-### 2D Matrix Dot Product
+### 2D Matrix Inner Product (Frobenius Inner Product)
 Works directly with 2D arrays (`m.continuous(rows, cols)`), nested dictionaries (`m.continuous(rowKeys, colKeys)`), or mixed 2D containers:
 
 ```typescript
-const factories = ["Tokyo", "Osaka"];
-const stores = ["StoreA", "StoreB"];
+const factories = ["Tokyo", "Osaka"] as const;
+const stores = ["StoreA", "StoreB"] as const;
 
 const costs = {
   Tokyo: { StoreA: 4, StoreB: 7 },
   Osaka: { StoreA: 8, StoreB: 3 },
 };
 
-const ship = m.continuous(factories, stores);
+const ship = m.continuous(factories, stores, { lb: 0 });
+
+// Total shipping cost across all routes (equivalent to expr`sum(${costs} * ${ship})`):
+const totalShippingCost = expr`dot(${costs}, ${ship})`;
+```
+
+> [!NOTE]
+> **2D `dot(A, B)` is the Frobenius Inner Product**: For 2D matrices or nested records, `dot(A, B)` computes the scalar **Frobenius inner product** $\langle A, B \rangle_F = \sum_{i,j} A_{i,j} B_{i,j}$ (the sum of element-wise products across all rows and columns, equivalent to `` expr`sum(${A} * ${B})` ``), **not** the matrix-matrix product $(AB)_{i,k} = \sum_j A_{i,j} B_{j,k}$.
+
+---
+
+## Composing Aggregations in `expr`
+
+### Separating Operators and Data
 
-// Total shipping cost in one line:
-m.objective(minimize(dot(costs, ship)));
+Write mathematical operators, `sum(...)`, `dot(..., ...)`, and comparison symbols (`<=`, `>=`, `==`) in the template string, and pass variables, scalars, and containers (`Array` / `Record`) via `${...}`:
+
+```typescript
+// Nested template calls and Object.values() (verbose)
+const totalProfit1 = expr`${dot(profits, vars)}`;
+const cap1 = expr`${sum(Object.values(vars))} <= 100`;
+
+// Direct sum() and dot() inside expr (recommended)
+const totalProfit2 = expr`dot(${profits}, ${vars})`;
+const cap2 = expr`sum(${vars}) <= 100`;
 ```
 
+### Common `expr` Aggregation Syntax
+
+| Operation | Mathematical Formula | WaSHI Expression |
+| :--- | :--- | :--- |
+| **Total sum** (1D/2D `Array` or `Record`) | $\sum_i x_i \le C$ | `` m.constraint(expr`sum(${x}) <= ${C}`) `` |
+| **Inner product** (1D vector or 2D Frobenius) | $\sum_i c_i x_i \le B$ | `` m.constraint(expr`dot(${c}, ${x}) <= ${B}`) `` |
+| **Element-wise difference & product** | $\sum_i (p_i - c_i) \cdot x_i$ | `` expr`sum((${price} - ${cost}) * ${x})` `` |
+| **Sum of squared deviations (QP)** | $\sum_i (x_i - t_i)^2$ | `` expr`sum((${x} - ${target})^2)` `` |
+| **Element-wise constraints** ($\forall i \in I$) | $a_i x_i \le b_i \quad (\forall i)$ | `` m.constraint(items.map((i) => expr`${a[i]} * ${x[i]} <= ${b[i]}`)) `` |
+| **2D row sums** (for each row $f$) | $\sum_s X_{f,s} \le S_f \quad (\forall f)$ | `` m.constraint(factories.map((f) => expr`sum(${ship[f]}) <= ${supply[f]}`)) `` |
+| **2D column sums** (for each column $s$) | $\sum_f X_{f,s} \ge D_s \quad (\forall s)$ | `` m.constraint(stores.map((s) => expr`sum(${factories}, ${(f) => ship[f][s]}) >= ${demand[s]}`)) `` |
+
 ---
 
-## 🧮 Quadratic Expressions (`QuadExpr` & `expr`)
+## Quadratic Expressions (`QuadExpr` & `expr`)
 
-WaSHI natively supports Convex Quadratic Programming (QP) with the HiGHS solver. Quadratic objectives can be written uniformly using the `expr` template literal, or algebraically using `QuadExpr` and `.mul()`:
+WaSHI supports Convex Quadratic Programming (QP) objectives via the HiGHS solver. Quadratic expressions can be written using the `expr` template literal or constructed programmatically with `QuadExpr` and `.mul()`.
 
 ### 1. Using `expr` (Recommended)
-You can write quadratic formulas naturally with `*`, `^2`, or `**2`:
+Write quadratic terms with `*`, `^2`, or `**2`:
 
 ```typescript
 import { Model, expr, minimize } from "@ohtaman/washi";
@@ -1032,7 +1090,7 @@ m.constraint(expr`${x} + ${y} >= 4`);
 ```
 
 ### 2. Method Chaining with `.mul()` or `QuadExpr`
-Alternatively, you can construct quadratic expressions programmatically:
+You can also construct quadratic expressions programmatically:
 
 ```typescript
 import { Model, QuadExpr, minimize } from "@ohtaman/washi";
@@ -1041,12 +1099,11 @@ const m = new Model();
 const x = m.continuous("x", { lb: 0 });
 const y = m.continuous("y", { lb: 0 });
 
-// 1. Construct quadratic terms with .mul()
-// Represents x * y + 2 * x^2
+// 1. Construct quadratic terms with .mul() (x * y + 2 * x^2)
 const quad = x.mul(y).add(x.mul(x).mul(2));
 
-// 2. Build portfolio risk objective: w^T * Sigma * w
-const assets = ["Tech", "Bonds"];
+// 2. Build portfolio variance objective: w^T * Sigma * w
+const assets = ["Tech", "Bonds"] as const;
 const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 let risk = new QuadExpr();
@@ -1057,13 +1114,22 @@ risk = risk.add(w.Bonds.mul(w.Bonds).mul(0.01));
 m.objective(minimize(risk));
 ```
 
+> [!NOTE]
+> **Convexity Requirement ($\mathbf{Q} \succeq 0$)**: QP solvers (including HiGHS) require the quadratic objective matrix $\mathbf{Q}$ to be **positive semi-definite (PSD)** when minimizing (or negative semi-definite when maximizing). Sum-of-squares terms ($\sum_i (x_i - t_i)^2$) and covariance matrices ($\mathbf{w}^\top \boldsymbol{\Sigma} \mathbf{w}$) are guaranteed PSD, whereas indefinite products over continuous variables (such as minimizing $x \cdot y$) are non-convex and rejected by the solver. *(To linearize the product of two binary variables $x_A \cdot x_B$ in MILP, see [Formulation Patterns & Tips](docs/guide/formulation-tips.md#product-of-two-binary-variables).)*
+
 ---
 
-## 📊 Evaluating Expressions After Solving (`.value`)
+## Evaluating Expressions After Solving (`.value`)
 
-Both `LinExpr` and `QuadExpr` expose a `.value` getter (`number | null`). Once a model has been solved and all referenced variables have finite primal values, you can evaluate any sub-expression—such as total department cost, portfolio return, or resource utilization—directly without manual arithmetic:
+Both `LinExpr` and `QuadExpr` expose a `.value` getter (`number | null`). Once a model has been solved and all referenced variables have finite primal values, you can evaluate any sub-expression directly:
 
 ```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.integer("x", { lb: 0 });
+const y = m.integer("y", { lb: 0 });
+
 const revenue = expr`30 * ${x} + 50 * ${y}`;
 const laborUsed = expr`2 * ${x} + ${y}`;
 
@@ -1081,7 +1147,7 @@ If the model has not been solved (or any variable in the expression has `value =
 
 ---
 
-## 🔗 Fluent Arithmetic & Relational Methods
+## Fluent Arithmetic & Relational Methods
 
 In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent methods for programmatic expression building:
 
@@ -1101,17 +1167,17 @@ In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent
 # Constraints (`m.constraint` & `m.indicator`)
 
 Constraints restrict the feasible solution space of your mathematical or logical model.
-In WaSHI, both linear arithmetic constraints and propositional SMT formulas are registered using **`m.constraint()`**:
+In WaSHI, both linear arithmetic constraints and propositional logic formulas are registered using **`m.constraint()`**:
 
 ```typescript
-m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_limit");
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
 ```
 
 ---
 
-## ✍️ Algebraic Linear Constraints (`expr`)
+## Algebraic Linear Constraints (`expr`)
 
-The `expr` tagged template literal syntax allows writing equations and inequalities with natural mathematical notation:
+The `expr` tagged template literal allows writing equations and inequalities with standard mathematical notation:
 
 ```typescript
 import { Model, expr } from "@ohtaman/washi";
@@ -1130,13 +1196,15 @@ m.constraint(expr`3 * ${x} + ${y} >= 20`, "min_demand");
 m.constraint(expr`${x} + ${y} == 30`, "exact_quota");
 ```
 
+`m.constraint()` returns the registered `Constraint` (or `BoolExpr` for logical formulas), or an array when passed a batch array.
+
 ### Supported Comparison Operators
 - `<=`: Upper bound constraint
 - `>=`: Lower bound constraint
 - `==` or `=`: Exact equality constraint
 
 ### Batch Registration
-You can pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
+Pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
 
 ```typescript
 m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
@@ -1144,50 +1212,51 @@ m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
 
 ---
 
-## 🏷️ Naming Constraints
+## Naming Constraints
 
-Every constraint can be given a unique, descriptive name as the second argument of `m.constraint(c, name)`:
+Pass a unique, descriptive name as the second argument of `m.constraint(c, name)`:
 
 ```typescript
 m.constraint(expr`${x} + ${y} <= 100`, "budget_cap");
 ```
 
 ### Why Name Constraints?
-1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the exact generated formulation.
-2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, Z3 `m.check()` returns the exact constraint names forming the conflicting subset.
+1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the generated formulation.
+2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, `m.check()` returns the conflicting constraint names (via built-in HiGHS elastic relaxation or Z3 `unsatCore`).
 3. **Direct Lookup (`m.getConstraintByName()`)**: Retrieve a constraint by name after solving to inspect its `dual` or `slack` value.
 
 ---
 
-## 🔁 Adding Constraints over Iterables & Sums
+## Aggregated Constraints (`sum` & `dot`)
 
-Use `sum()` or `dot()` inside `expr` to express linear aggregations cleanly:
+Use `sum(...)` and `dot(..., ...)` directly inside `expr` to express linear aggregations over arrays and dictionaries cleanly:
 
 ```typescript
-import { Model, sum, expr } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const items = ["A", "B", "C"];
+const m = new Model();
+const items = ["A", "B", "C"] as const;
 const weights = { A: 5, B: 10, C: 15 };
 const selected = m.binary(items);
 
+// Select at most 2 items
+m.constraint(expr`sum(${selected}) <= 2`, "max_items");
+
 // Total weight cannot exceed capacity 25
-m.constraint(
-  expr`${sum(items, (i) => selected[i].mul(weights[i]))} <= 25`,
-  "capacity_limit"
-);
+m.constraint(expr`dot(${weights}, ${selected}) <= 25`, "capacity_limit");
 ```
 
 ---
 
-## 🎯 Conditional / Indicator Constraints (`m.indicator`)
+## Conditional / Indicator Constraints (`m.indicator`)
 
-When a linear constraint should only take effect when a binary decision variable is active (`1` or `0`), use `m.indicator()`:
+When a linear constraint should only take effect when a binary decision variable (`m.binary()`) equals `1` (or `0`), use `m.indicator()`:
 
 ```typescript
 const useDiscount = m.binary("use_discount");
 const cartTotal = m.continuous("cart_total", { lb: 0, ub: 10_000 });
 
-// If useDiscount == 1, then cartTotal >= 100
+// If useDiscount == 1, enforce cartTotal >= 100
 // WaSHI automatically derives a safe, tight Big-M from the variable bounds
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
   activeValue: 1,
@@ -1197,16 +1266,16 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 
 ### Safe Automatic Big-M Derivation & Bounds
 
-When `options.M` is omitted, WaSHI automatically derives a safe, minimal Big-M value from the finite variable bounds:
+When `options.M` is omitted, WaSHI automatically derives a minimal valid Big-M value from finite variable bounds (`lb` and `ub`):
 - For `<=` constraints, variables with positive coefficients require finite upper bounds (`ub`), and negative coefficients require finite lower bounds (`lb`).
 - For `>=` constraints, variables with positive coefficients require finite lower bounds (`lb`), and negative coefficients require finite upper bounds (`ub`).
-- For `==` constraints, safe bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
+- For `==` constraints, bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
 
-If any referenced variable lacks the required finite bounds, `m.indicator()` throws an actionable error prompting for finite bounds or an explicit `options.M`.
+If any referenced variable lacks the required finite bound, `m.indicator()` throws an error prompting for finite bounds or an explicit `options.M`.
 
-### Explicit Override & Numerical Stability
+### Explicit `M` Override
 
-You can override the derived Big-M by providing `{ M: number }`:
+You can override the derived Big-M by passing `{ M: number }`:
 
 ```typescript
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
@@ -1216,15 +1285,13 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 ```
 
 > [!TIP]
-> **Numerical Stability vs. Correctness**:
-> An $M$ value that is too small can inadvertently cut off valid solutions. Conversely, an excessively large $M$ (e.g., $10^9$) causes poor matrix conditioning and numerical instability in MIP solvers.
-> By setting explicit, realistic variable bounds (`lb` and `ub`), WaSHI derives the tightest possible safe Big-M automatically.
+> **Prefer Finite Variable Bounds Over Arbitrary Large `M`**: An $M$ value that is too small can cut off valid feasible solutions, whereas an excessively large $M$ (e.g., $10^9$) degrades numerical conditioning in MIP solvers. Setting realistic `lb` and `ub` bounds on variables lets WaSHI compute the tightest safe Big-M automatically.
 
 ---
 
-## 🧠 Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
+## Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
 
-When solving with the **Z3** SMT engine (`@ohtaman/washi/solvers/z3`), you can combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`) using first-class logical operators:
+WaSHI provides first-class logical operators to combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`). Logical formulas are solved natively by the **Z3** SMT adapter (`@ohtaman/washi/solvers/z3`) and automatically linearized to 0-1 MIP constraints on **HiGHS** and **GLPK**:
 
 ```typescript
 import { Model, expr, and, or, not, implies, xor } from "@ohtaman/washi";
@@ -1233,14 +1300,14 @@ import "@ohtaman/washi/solvers/z3";
 const m = new Model({ solver: "z3" });
 const isAdmin = m.bool("isAdmin");
 const hasMfa = m.bool("hasMfa");
-const Clearance = m.integer("clearance", { lb: 0, ub: 5 });
+const clearance = m.integer("clearance", { lb: 0, ub: 5 });
 
 // Method syntax on BoolVar / BoolOp:
 m.constraint(isAdmin.implies(hasMfa), "admin_requires_mfa");
 
 // Mixing boolean propositions with linear arithmetic comparisons:
 m.constraint(
-  implies(isAdmin, expr`${Clearance} >= 4`),
+  implies(isAdmin, expr`${clearance} >= 4`),
   "admin_clearance_level"
 );
 
@@ -1254,27 +1321,32 @@ 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`) |
-| **Best For** | Operations research & MIP optimization with an objective (`m.solve()`) | Rule engines, policy verification, and SMT feasibility (`m.check()`) |
+| **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) |
+| **Primary Use Case** | MIP optimization models with arithmetic binary variables (`m.solve()`) | Logical rule systems and SMT feasibility (`m.check()`) |
+
+> [!NOTE]
+> **General Inequality Antecedents in `implies()`**: On **Z3** (`solver: "z3"`), the antecedent `a` in `implies(a, b)` can be any linear inequality—for example, ``implies(expr`${clearance} >= 4`, hasMfa)`` using `clearance` and `hasMfa` above. On MIP solvers (**HiGHS** / **GLPK**), conditional constraints should use a `BoolVar` (`m.bool()`) antecedent or `m.indicator(binVar, constraint)` with a `Binary` trigger variable.
 
 ---
 
-## 📐 Dual Values, Shadow Prices & Lookups
+## Dual Values, Shadow Prices & Lookups
 
-For continuous Linear Programming (LP) problems, query the economic shadow price (`dual`) and surplus (`slack`) on each constraint:
+For continuous Linear Programming (LP) problems, query the shadow price (`dual`) and surplus (`slack`) on each constraint (returned by `m.constraint()` or looked up via `m.getConstraintByName()`):
 
 ```typescript
-m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
+const woodConstraint = m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
 
 await m.solve();
 
-const woodConstraint = m.getConstraintByName("wood");
-console.log("Shadow price (dual):", woodConstraint?.dual);
-console.log("Slack surplus:", woodConstraint?.slack);
+console.log("Shadow price (dual):", woodConstraint.dual);
+console.log("Slack surplus:", woodConstraint.slack);
 console.log("Total linear constraints:", m.numConstrs);
 ```
 
-For logical constraints registered with a name, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+For named logical constraints, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+
+> [!TIP]
+> For modeling techniques such as **soft constraints with slack variables** and **symmetry breaking**, see [Formulation Patterns & Optimization Tips](docs/guide/formulation-tips.md#_3-constraint-design-numerical-conditioning).
 
 ---
 
@@ -1305,9 +1377,12 @@ m.constraint(expr`2 * ${x} + 3 * ${y} <= 100`, "resource_limit");
 
 Calling `m.objective()` with no arguments returns the current objective expression (`LinExpr | QuadExpr`). If you omit setting an objective, the model defaults to minimizing `0`.
 
+> [!TIP]
+> For objective formulation patterns—such as **Min-Max / Max-Min load balancing**, **weighted-sum vs. lexicographic multi-objective optimization**, and **MIP stopping tolerances (`relGap` / `absGap`)**—see [Formulation Patterns & Optimization Tips](docs/guide/formulation-tips.md#_4-multi-objective-mip-stopping-design).
+
 ---
 
-## 🚀 Solving the Model (`m.solve()` vs. `m.check()`)
+## Solving the Model (`m.solve()` vs. `m.check()`)
 
 WaSHI provides two asynchronous execution entrypoints:
 
@@ -1343,7 +1418,7 @@ You can also pass a solver name directly as the first argument: `await m.solve("
 
 ---
 
-## ⏱️ Real-Time Progress (`onProgress`) & Cancellation (`AbortSignal`)
+## Real-Time Progress (`onProgress`) & Cancellation (`AbortSignal`)
 
 For long-running MIP optimizations in interactive UIs, you can stream live branch-and-bound progress (`SolveProgressEvent`) and allow users to cancel the solve cleanly with `AbortController`:
 
@@ -1389,7 +1464,7 @@ console.log("Has incumbent:", m.hasPrimalSolution); // true if an incumbent was
 
 ---
 
-## 📊 Reading Results, Bounds & Solver Status
+## Reading Results, Bounds & Solver Status
 
 After solving, query the status, optimal values, and MIP optimality bounds on the `Model`:
 
@@ -1437,7 +1512,7 @@ If an integer-feasible incumbent was found before hitting `timeLimit` or `signal
 
 ---
 
-## 🔄 Model Mutations & Execution Validity
+## Model Mutations & Execution Validity
 
 A `Model` instance keeps its solution state synchronized across mutations made through `Model` methods and `Model` / `Var` / `Constraint` property setters:
 
@@ -1457,13 +1532,13 @@ When building real-world optimization and configuration systems, two verificatio
 1. **Why is my model infeasible?** Which specific business rules contradict each other?
 2. **Does the solver's solution genuinely satisfy every constraint?** How do I verify tolerances, integrality, and formulations?
 
-WaSHI provides built-in tools for both: **Unsat Core conflict diagnosis** via Z3 (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
+WaSHI provides built-in tools for both: **conflict diagnosis** via built-in HiGHS elastic relaxation or Z3 Unsat Core (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
 
 ---
 
-## 🔍 Conflict Diagnosis (`unsatCore` / `conflicts`)
+## Conflict Diagnosis (`unsatCore` / `conflicts`)
 
-When a model is **Infeasible**, traditional MIP solvers simply report that no solution exists without indicating *which* constraints are contradictory.
+When an optimization run (`m.solve()`) returns **`"Infeasible"`**, the status alone tells you that no solution satisfies every constraint—not *which* rules conflict with each other.
 By calling **`await m.check({ solver: "z3" })`**, WaSHI uses Z3's `assertAndTrack` mechanism to compute an **Unsatisfiable Core (`unsatCore`)**—a conflicting subset of named constraints that cannot be satisfied simultaneously:
 
 ```typescript
@@ -1495,109 +1570,613 @@ 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" });
-  console.error("Model is infeasible due to conflicting rules:", diag.conflicts);
-}
+if (status === "Infeasible") {
+  // 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);
+}
+```
+
+### Comparing Z3 `unsatCore` vs. HiGHS Elastic Slack `conflicts`
+
+| Property | Z3 (`m.check({ solver: "z3" })`) | HiGHS / GLPK (`m.check()`) |
+| :--- | :--- | :--- |
+| **Algorithm** | SMT assumption tracking (`assertAndTrack`) | Single-solve $L_1$ elastic slack relaxation ($\min \sum s_i$) |
+| **Populated Fields** | Both `result.unsatCore` and `result.conflicts` | `result.conflicts` (`unsatCore` is `undefined`) |
+| **Semantic Meaning** | A **contradictory subset** of rules that cannot all hold together | A **minimum-violation repair set** of constraints whose relaxation restores feasibility |
+| **Unit-Scaling Sensitivity** | **Scale-invariant** (pure logical/algebraic contradiction) | **Scale-sensitive** (minimizing unweighted $\sum s_i$ prefers relaxing a headcount constraint by `2` units over a budget constraint by `10,000` dollars) |
+
+> [!TIP]
+> When diagnosing models that mix constraints of vastly different magnitudes (e.g., headcount $\le 8$ alongside budget $\le 50{,}000$), use **`m.check({ solver: "z3" })`** if you want the complete scale-invariant set of mutually contradictory rules, or normalize constraint scales when relying on unweighted $L_1$ slack relaxation.
+
+---
+
+## Independent Solution Validation (`m.validateSolution()`)
+
+After solving a model (or supplying a custom candidate map via `values`), you can independently verify that all variable bounds, integer/binary domains, linear constraints, and logical SMT formulas hold against the original model definitions:
+
+```typescript
+const status = await m.solve();
+
+if (m.hasPrimalSolution) {
+  const report = m.validateSolution({
+    feasibilityTolerance: 1e-6,     // Max allowed violation for bounds and linear constraints
+    integralityTolerance: 1e-6,     // Max distance from nearest integer for Integer/Binary vars
+    evaluateLogicalConstraints: true,
+  });
+
+  console.log("Valid:", report.valid);
+  console.log("Complete:", report.complete);
+  console.log("Max violation:", report.maxViolation);
+  console.log("Summary:", report.summary);
+
+  if (!report.valid) {
+    console.warn("Violations detected:", report.violations);
+  }
+}
+```
+
+### `SolutionValidationReport` Summary
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `valid` | `boolean` | `true` iff `complete === true`, `uncheckedConstraints.length === 0`, and `violations.length === 0`. |
+| `complete` | `boolean` | `true` when all variables, Boolean variables, linear constraints, and logical constraints were evaluated. |
+| `maxViolation` | `number` | Largest numeric violation magnitude across all evaluated bounds, integrality checks, and constraints. |
+| `violations` | `SolutionViolation[]` | Flat list of violations (`"missing_value"`, `"non_finite_value"`, `"invalid_boolean_value"`, `"lower_bound"`, `"upper_bound"`, `"integrality"`, `"linear_constraint"`, `"logical_constraint"`, `"unchecked_constraint"`). |
+| `violationsByName` | `Record<string, SolutionViolation[]>` | Violations grouped by variable or constraint name. |
+| `uncheckedConstraints` | `string[]` | Names of constraints that could not be evaluated. |
+| `missingVariables` | `string[]` | Names of numeric or Boolean variables whose values were `null` or `undefined`. |
+| `summary` | `SolutionValidationSummary` | Counts of checked vs. total variables, Boolean variables, linear constraints, and logical constraints. |
+
+---
+
+## Inspecting the LP Formulation (`m.toLpString()`)
+
+When debugging coefficients, signs, or Big-M indicator expansions, call `m.toLpString()` to export the model in standard CPLEX/HiGHS `.lp` format:
+
+```typescript
+const m = new Model("DebugModel");
+const x = m.integer("x", { lb: 0, ub: 10 });
+m.objective(maximize(expr`5 * ${x}`));
+m.constraint(expr`2 * ${x} <= 15`, "resource_limit");
+
+console.log(m.toLpString());
+/*
+Maximize
+ obj: 5 x
+Subject To
+ resource_limit: 2 x <= 15
+Bounds
+ 0 <= x <= 10
+Generals
+ x
+End
+*/
+```
+
+---
+
+## Unit Testing Application Logic with `MockSolver`
+
+When running unit tests for application code that builds or consumes a WaSHI `Model`, you can use the built-in `MockSolver` (`solver: "mock"`) to return deterministic results instantaneously without loading WebAssembly:
+
+```typescript
+import { Model, MockSolver, expr, maximize } from "@ohtaman/washi";
+
+const mock = new MockSolver({
+  status: "Optimal",
+  objectiveValue: 420,
+  values: { x: 10, y: 20 },
+});
+
+const m = new Model({ solver: mock });
+const x = m.integer("x");
+const y = m.integer("y");
+m.objective(maximize(expr`10 * ${x} + 16 * ${y}`));
+
+await m.solve();
+console.log(m.objectiveValue); // 420
+console.log(x.value, y.value); // 10, 20
+```
+
+---
+
+# Decomposition Methods (`solveColumnGeneration` & `solveBenders`)
+
+When monolithic Mixed-Integer Programming (MIP) models have exponentially many candidate patterns or large multi-stage subproblems, WaSHI provides two high-level decomposition orchestrators—`master.solveColumnGeneration()` and `master.solveBenders()`—along with low-level primitives for dual inspection and dynamic model updates.
+
+| Decomposition Method | WaSHI Orchestrator | Typical Use Case |
+| :--- | :--- | :--- |
+| **Column Generation** *(Dantzig-Wolfe)* | [`master.solveColumnGeneration()`](#column-generation-solvecolumngeneration) | Models with exponentially many patterns, routes, or schedules (e.g., Cutting Stock, Vehicle Routing, Crew Rostering). |
+| **Benders Decomposition** *(and Lazy Cuts)* | [`master.solveBenders()`](#benders-decomposition-solvebenders) | Two-stage or complicating-variable problems (e.g., Facility Location + Dispatch, Stochastic Planning, TSP Subtour Elimination). |
+
+---
+
+## Foundational Primitives
+
+WaSHI exposes four lower-level primitives used internally by the decomposition orchestrators and available directly for custom algorithms:
+
+### 1. Constraint Duals (`c.dual`)
+After solving a continuous linear program (LP), read the shadow price (marginal impact on the objective per unit change in RHS) of each constraint:
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+m.objective(maximize(expr`3 * ${x} + 2 * ${y}`));
+const c = m.constraint(expr`${x} + ${y} <= 10`, "capacity");
+await m.solve();
+
+console.log(c.dual);                    // Dual value / shadow price
+console.log(m.solution?.duals.capacity); // Lookup by constraint name
+```
+
+### 2. Continuous LP Relaxation (`m.relax()`)
+`m.relax()` temporarily relaxes all `Integer` and `Binary` variables to continuous variables within their `[lb, ub]` bounds and solves the LP relaxation so constraint duals are populated:
+
+```typescript
+// Solves the continuous LP relaxation and populates m.solution.duals
+const status = await m.relax();
+console.log("LP relaxation bound:", m.objectiveValue);
+```
+
+### 3. Dynamic Column Injection (`m.addColumn()`)
+Create a new decision variable, set its objective coefficient, and attach its non-zero coefficients to existing named constraints in a single call:
+
+```typescript
+const col = m.addColumn({
+  name: "pattern_1",
+  type: "Integer", // or "Continuous" / "Binary"
+  lb: 0,
+  cost: 1, // Objective coefficient
+  coefficients: {
+    capacity: 2,
+  },
+});
+```
+
+### 4. Dynamic Constraint Term Updates (`c.addTerm()` / `c.setTerm()`)
+Increment or overwrite the coefficient of a variable inside an existing linear constraint:
+
+```typescript
+const extra = m.continuous("extra", { lb: 0 });
+const budget = m.constraint(expr`${x} + ${y} <= 20`, "budget");
+
+budget.addTerm(extra, 5); // Adds +5 * extra to the LHS
+budget.setTerm(extra, 0); // Setting 0 removes extra from the constraint
+```
+
+---
+
+## Column Generation (`solveColumnGeneration`)
+
+`master.solveColumnGeneration(options)` starts from a **Restricted Master Problem (RMP)** containing an initial feasible subset of columns and executes the column generation loop:
+1. Solves the continuous LP relaxation of the master problem via `master.relax()`.
+2. Invokes your `pricing` callback with the current dual shadow prices (`duals`, `getDual`).
+3. Evaluates candidate columns (`ColumnProposal` or `ColumnProposal[]`), dynamically injecting those with improving reduced costs ($\bar{c} = \text{cost} - \sum_i \pi_i a_i < 0$ when minimizing).
+4. Repeats until `pricing` returns `null` / `[]` or no column improves the objective beyond `reducedCostTolerance`.
+5. Optionally solves the final master model as a MIP (`finalizeAsMIP: true`, the default) to obtain an integer solution over all generated columns.
+
+### Pricing with a WaSHI Subproblem Model
+
+```typescript
+import { Model, expr, minimize, maximize } from "@ohtaman/washi";
+
+const rollWidth = 100;
+
+// 1. Restricted Master Problem (RMP) with simple single-item initial patterns
+const master = new Model("CuttingStockMaster");
+const pA = master.integer("init_A", { lb: 0 }); // 2 of A (width 45) per roll
+const pB = master.integer("init_B", { lb: 0 }); // 2 of B (width 36) per roll
+const pC = master.integer("init_C", { lb: 0 }); // 6 of C (width 16) per roll
+
+master.objective(minimize(expr`${pA} + ${pB} + ${pC}`));
+const demandA = master.constraint(expr`2 * ${pA} >= 10`, "demand_A");
+const demandB = master.constraint(expr`2 * ${pB} >= 14`, "demand_B");
+const demandC = master.constraint(expr`6 * ${pC} >= 20`, "demand_C");
+
+// 2. Run Column Generation
+const result = await master.solveColumnGeneration({
+  finalizeAsMIP: true,
+  pricing: async () => {
+    // Knapsack pricing subproblem: find a pattern maximizing total dual value
+    const sub = new Model("KnapsackPricing");
+    const aA = sub.integer("a_A", { lb: 0, ub: 2 });
+    const aB = sub.integer("a_B", { lb: 0, ub: 2 });
+    const aC = sub.integer("a_C", { lb: 0, ub: 6 });
+
+    const dualA = demandA.dual ?? 0;
+    const dualB = demandB.dual ?? 0;
+    const dualC = demandC.dual ?? 0;
+    sub.objective(maximize(expr`${dualA} * ${aA} + ${dualB} * ${aB} + ${dualC} * ${aC}`));
+    sub.constraint(expr`45 * ${aA} + 36 * ${aB} + 16 * ${aC} <= ${rollWidth}`);
+
+    await sub.solve();
+
+    return {
+      cost: 1,
+      type: "Integer",
+      coefficients: {
+        demand_A: Math.round(aA.value ?? 0),
+        demand_B: Math.round(aB.value ?? 0),
+        demand_C: Math.round(aC.value ?? 0),
+      },
+    };
+  },
+});
+
+console.log("Optimal rolls:", result.objectiveValue); // 14
+console.log("Iterations:", result.iterations);
+console.log("Columns added:", result.columnsAdded);
+```
+
+### Pricing with a Custom Algorithm (`getDual`)
+
+Because `pricing` is a standard callback receiving `PricingContext`, you can also solve the pricing problem directly in TypeScript (e.g., via combinatorial search, dynamic programming, or shortest-path routines) instead of constructing a subproblem `Model`:
+
+```typescript
+const customResult = await master.solveColumnGeneration({
+  maxIterations: 100,
+  reducedCostTolerance: 1e-6,
+  pricing: ({ getDual }) => {
+    const dA = getDual("demand_A");
+    const dB = getDual("demand_B");
+    const dC = getDual("demand_C");
+
+    // Search feasible patterns (45*aA + 36*aB + 16*aC <= rollWidth) for negative reduced cost (1 - dualSum < -1e-6)
+    let bestDualSum = 1 + 1e-6;
+    let best: { demand_A: number; demand_B: number; demand_C: number } | null = null;
+    for (let aA = 0; 45 * aA <= rollWidth; aA++) {
+      for (let aB = 0; 45 * aA + 36 * aB <= rollWidth; aB++) {
+        for (let aC = 0; 45 * aA + 36 * aB + 16 * aC <= rollWidth; aC++) {
+          const dualSum = dA * aA + dB * aB + dC * aC;
+          if (dualSum > bestDualSum) {
+            bestDualSum = dualSum;
+            best = { demand_A: aA, demand_B: aB, demand_C: aC };
+          }
+        }
+      }
+    }
+    return best ? { cost: 1, type: "Integer", coefficients: best } : null;
+  },
+});
+```
+
+---
+
+## Benders Decomposition (`solveBenders`)
+
+`master.solveBenders(options)` partitions a problem into a **Master Problem** (holding first-stage or complicating variables) and a **Subproblem** evaluated at each master candidate solution to generate **Optimality Cuts** or **Feasibility Cuts**.
+
+### Automatic Cut Generation (`sub.link()`)
+
+Return a continuous LP subproblem `Model` from `subproblem` and declare cross-model constraints via `sub.link(...)`. WaSHI automatically manages the auxiliary cost estimator variable $\theta$, substitutes master candidate values, extracts subproblem duals, and adds Benders cuts until convergence:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+// 1. Master problem: binary facility opening decisions
+const master = new Model("FacilityMaster");
+const y1 = master.binary("open_F1");
+const y2 = master.binary("open_F2");
+
+// Fixed opening costs (theta for operational subproblem cost is managed automatically)
+master.objective(minimize(expr`100 * ${y1} + 120 * ${y2}`));
+master.constraint(expr`50 * ${y1} + 60 * ${y2} >= 75`, "total_capacity_floor");
+
+// 2. Solve with automatic Benders cut generation
+const result = await master.solveBenders({
+  gapTolerance: 1e-4,
+  subproblem: () => {
+    const sub = new Model("DispatchSubproblem");
+    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}`
+      )
+    );
+
+    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 dispatch flows to master binary variables y1, y2
+    sub.link(expr`${x11} + ${x12} + ${x13} <= 50 * ${y1}`);
+    sub.link(expr`${x21} + ${x22} + ${x23} <= 60 * ${y2}`);
+
+    return sub;
+  },
+});
+
+console.log("Optimal total cost:", result.objectiveValue); // 390
+console.log("Cuts added:", result.cutsAdded);
+console.log("Open facilities:", result.values);
+```
+
+> [!NOTE]
+> **`theta` Lower Bound for Negative Subproblem Objectives**: When `sub.link(...)` is used without an explicit `theta` variable, WaSHI injects `__benders_theta` with default `lb: 0` (assuming non-negative subproblem costs). If your subproblem objective can take negative values (e.g., rebate or profit terms), declare `const theta = master.continuous("theta", { lb: -1e6 })`, include `+ ${theta}` in `master.objective(...)`, and pass `{ theta }` in `solveBenders(options)`.
+
+### Manual Cut Generation (`BendersCut` / Lazy Constraints)
+
+For combinatorial separation (such as lazy subtour elimination) or custom analytical cuts, return one `BendersCut` object, an array `BendersCut[]`, or `null` when converged:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const master = new Model("ManualBenders");
+const y = master.binary("y");
+const theta = master.continuous("theta", { lb: 0 });
+master.objective(minimize(expr`40 * ${y} + ${theta}`));
+
+const result = await master.solveBenders({
+  theta,
+  gapTolerance: 1e-4,
+  subproblem: ({ getMasterValue }) => {
+    const yVal = getMasterValue(y);
+    const estTheta = getMasterValue(theta);
+
+    // Operational cost is 100 when y = 0, or 30 when y = 1
+    const actualSubCost = 100 - 70 * yVal;
+    if (estTheta < actualSubCost - 1e-4) {
+      return {
+        kind: "optimality", // or "feasibility" for lazy combinatorial cuts
+        constraint: expr`${theta} >= 100 - 70 * ${y}`,
+        subproblemObjective: 40 * yVal + actualSubCost,
+      };
+    }
+    return null; // Converged
+  },
+});
+
+console.log(result.objectiveValue); // 70 (y = 1, theta = 30)
+```
+
+---
+
+## Related Examples & Formulation Tips
+
+- **Full Decomposition Walkthroughs**:
+  - [Vehicle Routing Problem (`solveColumnGeneration`)](docs/examples/vehicle-routing.md)
+  - [Traveling Salesperson Problem (`solveBenders` lazy subtour elimination)](docs/examples/traveling-salesperson.md)
+- **Formulation Tips**: See [Formulation Patterns & Optimization Tips](docs/guide/formulation-tips.md#_5-decomposition-formulation-tips) for Set Covering (`>= 1`) vs. Set Partitioning (`== 1`), Price-and-Branch (`finalizeAsMIP`), and multi-cut separation.
+
+---
+
+# Formulation Patterns & Optimization Tips
+
+While the preceding Modeling Guide pages cover WaSHI's APIs (`Model`, `expr`, `m.constraint`, `m.solve`, etc.), this page collects standard mathematical optimization formulation patterns and solver tuning techniques frequently used in linear and mixed-integer programming (LP/MIP).
+
+---
+
+## 1. Variables & Domain Modeling
+
+### Semi-Continuous Decisions ($\{0\} \cup [L, U]$)
+
+A semi-continuous quantity must be either `0` (inactive) or within a positive interval `[L, U]` (e.g., a production batch with a minimum run size $L = 10$ and capacity $U = 100$).
+
+Combine a continuous variable `x` with a binary activation variable `isActive` and linking constraints $L \cdot b \le x \le U \cdot b$:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model("SemiContinuousBatch");
+const batch = m.continuous("batch", { lb: 0, ub: 100 });
+const isActive = m.binary("is_active");
+
+// If isActive === 0, batch is forced to 0; if isActive === 1, batch lies in [10, 100]
+m.constraint(expr`${batch} >= 10 * ${isActive}`, "min_batch_run");
+m.constraint(expr`${batch} <= 100 * ${isActive}`, "max_batch_run");
+```
+
+### Minimal-Perturbation Rescheduling vs. Warm Starting
+
+When re-optimizing an existing schedule after a disruption, passing yesterday's assignment via [`initialValue`](docs/guide/variables.md#primal-initial-values-warm-start-hints) only gives the MIP solver a starting search point—it does **not** prevent the solver from changing every assignment for a tiny objective gain.
+
+To keep a revised binary plan $x_i \in \{0, 1\}$ close to a baseline assignment $x_i^{\text{prev}} \in \{0, 1\}$, penalize the **Hamming distance** (number of flipped decisions) in the objective:
+
+$$\text{Changes} = \sum_{i:\, x_i^{\text{prev}} = 0} x_i + \sum_{i:\, x_i^{\text{prev}} = 1} (1 - x_i)$$
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("StableReschedule");
+const prevPlan = [1, 0, 1, 0];
+const x = prevPlan.map((prev, i) =>
+  m.binary(`slot_${i}`, { initialValue: prev })
+);
+
+// Linear terms counting how many 0/1 decisions differ from prevPlan
+const flipTerms = x.map((v, i) => (prevPlan[i] === 1 ? expr`1 - ${v}` : v));
+
+// Require at least 3 active slots while penalizing changes from prevPlan
+m.constraint(expr`sum(${x}) >= 3`, "min_active_slots");
+m.objective(minimize(expr`5 * sum(${flipTerms})`));
+```
+
+---
+
+## 2. Linearizing Non-Linear Expressions
+
+### Product of Two Binary Variables ($x_A \cdot x_B$)
+
+In integer programming, if an interaction cost or synergy bonus applies only when two binary decisions $x_A, x_B \in \{0, 1\}$ are **both** equal to `1`, avoid introducing a quadratic term. Instead, introduce an auxiliary variable $z_{AB} \in [0, 1]$ and add the three standard McCormick / Fortet linear inequalities so the model remains a pure MILP:
+
+$$z_{AB} \le x_A, \quad z_{AB} \le x_B, \quad z_{AB} \ge x_A + x_B - 1$$
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model("BinaryProductLinearization");
+const xA = m.binary("xA");
+const xB = m.binary("xB");
+// When xA and xB are binary, continuous [0, 1] bounds suffice to force bothAB into {0, 1}
+const bothAB = m.continuous("both_AB", { lb: 0, ub: 1 });
+
+m.constraint(expr`${bothAB} <= ${xA}`, "and_upper_A");
+m.constraint(expr`${bothAB} <= ${xB}`, "and_upper_B");
+m.constraint(expr`${bothAB} >= ${xA} + ${xB} - 1`, "and_lower_AB");
+
+m.objective(maximize(expr`10 * ${xA} + 10 * ${xB} + 5 * ${bothAB}`));
+```
+
+### Min-Max & Max-Min Objectives (Load Balancing)
+
+Linear and quadratic objectives cannot call `Math.max(...)` directly. To minimize a bottleneck or peak workload $\min \max_i (\text{load}_i)$, introduce an auxiliary ceiling variable $z$, constrain every individual load by $\text{load}_i \le z$, and minimize $z$:
+
+$$\min z \quad \text{subject to} \quad \text{load}_i \le z \quad \forall i$$
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("MinMaxLoadBalancing");
+const workers = ["Alice", "Bob", "Carol"] as const;
+const hours = m.continuous(workers, { lb: 0, ub: 40 });
+const maxHours = m.continuous("max_hours", { lb: 0, ub: 40 });
+
+// Bound every worker's hours by the shared ceiling maxHours
+m.constraint(workers.map((w) => expr`${hours[w]} <= ${maxHours}`));
+m.constraint(expr`sum(${hours}) >= 60`, "total_required_work");
+
+// Minimizing maxHours distributes the 60 hours evenly (20 hours each)
+m.objective(minimize(maxHours));
+```
+
+*(Symmetrically, to **maximize the minimum** level $\max \min_i u_i$, impose $u_i \ge z$ for all $i$ and set `m.objective(maximize(z))`.)*
+
+---
+
+## 3. Constraint Design & Numerical Conditioning
+
+### Hard vs. Soft Constraints (Elastic Slack Variables)
+
+Treating every business target as a strict **hard constraint** makes a model `"Infeasible"` as soon as demand exceeds capacity. Keep physical and legal invariants as hard constraints, and model non-rigid targets as **soft constraints** by adding non-negative slack variables ($s \ge 0$) with penalty weights $W$ in the objective:
+
+| Target Type | Hard Constraint | Soft Constraint ($s \ge 0$) | Objective Penalty Term (Minimize) |
+| :--- | :--- | :--- | :--- |
+| **Lower bound** | $\text{lhs} \ge b$ | $\text{lhs} + s_{\text{short}} \ge b$ | $+ W \cdot s_{\text{short}}$ |
+| **Upper bound** | $\text{lhs} \le b$ | $\text{lhs} - s_{\text{excess}} \le b$ | $+ W \cdot s_{\text{excess}}$ |
+| **Target equality** | $\text{lhs} = b$ | $\text{lhs} + s_{\text{short}} - s_{\text{excess}} = b$ | $+ W_1 \cdot s_{\text{short}} + W_2 \cdot s_{\text{excess}}$ |
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model("SoftConstraintCoverage");
+const assignedStaff = m.integer("assigned_staff", { lb: 0, ub: 4 }); // Max 4 staff available
+const shortage = m.continuous("shortage", { lb: 0 });                // Non-negative slack (s >= 0)
+
+// Soft target: aim for 5 staff, allowing shortage > 0 if unavailable
+m.constraint(expr`${assignedStaff} + ${shortage} >= 5`, "target_5_staff");
+
+// Penalize unmet shortage ($1,000) above regular wage ($100)
+m.objective(minimize(expr`100 * ${assignedStaff} + 1000 * ${shortage}`));
+
+await m.solve();
+// assignedStaff.value === 4, shortage.value === 1 (returns best compromise instead of Infeasible)
 ```
 
----
+> [!TIP]
+> **Scaling Penalty Weights ($W$)**: Choose $W$ larger than normal operational marginal costs (typically $10\times$ to $1{,}000\times$ unit cost), and avoid extreme constants such as $10^{12}$. Keeping the ratio between the largest and smallest coefficients within $10^5\text{–}10^6$ preserves floating-point numerical stability in LP/MIP solvers.
 
-## ✅ Independent Solution Validation (`m.validateSolution()`)
+### Symmetry Breaking for Identical Resources
 
-After solving a model (or supplying a custom candidate map via `values`), you can independently verify that all variable bounds, integer/binary domains, linear constraints, and logical SMT formulas hold against the original model definitions:
+When a model contains $K$ interchangeable resources—such as identical trucks, bins, or parallel machines—any feasible assignment has up to $K!$ equivalent permutations with the exact same objective value. Without symmetry breaking, a MIP solver explores redundant mirror-image subtrees before proving optimality.
 
-```typescript
-const status = await m.solve();
+Impose a canonical ordering ($u_0 \ge u_1 \ge \dots \ge u_{K-1}$) so identical resources are activated in index order:
 
-if (m.hasPrimalSolution) {
-  const report = m.validateSolution({
-    feasibilityTolerance: 1e-6,     // Max allowed violation for bounds and linear constraints
-    integralityTolerance: 1e-6,     // Max distance from nearest integer for Integer/Binary vars
-    evaluateLogicalConstraints: true,
-  });
+```typescript
+import { Model, expr } from "@ohtaman/washi";
 
-  console.log("Valid:", report.valid);
-  console.log("Complete:", report.complete);
-  console.log("Max violation:", report.maxViolation);
-  console.log("Summary:", report.summary);
+const m = new Model("SymmetryBreaking");
+const numTrucks = 4;
+const truckUsed = m.binary(numTrucks, { prefix: "truck_used" });
 
-  if (!report.valid) {
-    console.warn("Violations detected:", report.violations);
-  }
+// Only allow activating truck k+1 when truck k is also active
+for (let k = 0; k < numTrucks - 1; k++) {
+  m.constraint(
+    expr`${truckUsed[k]} >= ${truckUsed[k + 1]}`,
+    `order_truck_${k}`
+  );
 }
 ```
 
-### `SolutionValidationReport` Summary
+---
 
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `valid` | `boolean` | `true` iff `complete === true`, `uncheckedConstraints.length === 0`, and `violations.length === 0`. |
-| `complete` | `boolean` | `true` when all variables, Boolean variables, linear constraints, and logical constraints were evaluated. |
-| `maxViolation` | `number` | Largest numeric violation magnitude across all evaluated bounds, integrality checks, and constraints. |
-| `violations` | `SolutionViolation[]` | Flat list of violations (`"missing_value"`, `"non_finite_value"`, `"invalid_boolean_value"`, `"lower_bound"`, `"upper_bound"`, `"integrality"`, `"linear_constraint"`, `"logical_constraint"`, `"unchecked_constraint"`). |
-| `violationsByName` | `Record<string, SolutionViolation[]>` | Violations grouped by variable or constraint name. |
-| `uncheckedConstraints` | `string[]` | Names of constraints that could not be evaluated. |
-| `missingVariables` | `string[]` | Names of numeric or Boolean variables whose values were `null` or `undefined`. |
-| `summary` | `SolutionValidationSummary` | Counts of checked vs. total variables, Boolean variables, linear constraints, and logical constraints. |
+## 4. Multi-Objective & MIP Stopping Design
 
----
+### Weighted Sum vs. Lexicographic Two-Stage Optimization
 
-## 📄 Inspecting the LP Formulation (`m.toLpString()`)
+When balancing competing goals—such as minimizing total cost ($f_1$) while also minimizing peak workload ($f_2$)—two approaches are standard:
 
-When debugging coefficients, signs, or Big-M indicator expansions, call `m.toLpString()` to export the model in standard CPLEX/HiGHS `.lp` format:
+- **Weighted Sum (Single Solve)**: Combine normalized terms into one objective, e.g., ``minimize(expr`${totalCost} + 50 * ${maxHours}`)``.
+- **Lexicographic (Hierarchical) Two-Stage Solve**: When the primary objective has strict priority, solve for $f_1$ first, add a constraint locking $f_1$ within an acceptable tolerance of its optimum $f_1^*$, and re-solve for $f_2$:
 
 ```typescript
-const m = new Model("DebugModel");
-const x = m.integer("x", { lb: 0, ub: 10 });
-m.objective(maximize(expr`5 * ${x}`));
-m.constraint(expr`2 * ${x} <= 15`, "resource_limit");
+import { Model, expr, minimize } from "@ohtaman/washi";
 
-console.log(m.toLpString());
-/*
-Maximize
- obj: 5 x
-Subject To
- resource_limit: 2 x <= 15
-Bounds
- 0 <= x <= 10
-Generals
- x
-End
-*/
+const m = new Model("LexicographicTwoStage");
+const workers = ["Alice", "Bob"] as const;
+const wage = { Alice: 20, Bob: 20 };
+const hours = m.continuous(workers, { lb: 0, ub: 40 });
+const maxHours = m.continuous("max_hours", { lb: 0, ub: 40 });
+
+const totalCost = expr`dot(${wage}, ${hours})`;
+m.constraint(expr`sum(${hours}) >= 40`, "required_hours");
+m.constraint(workers.map((w) => expr`${hours[w]} <= ${maxHours}`));
+
+// Stage 1: Minimize primary objective (total wage cost)
+m.objective(minimize(totalCost));
+await m.solve();
+const minCost = m.objectiveValue!;
+
+// Stage 2: Keep cost within 1% of minCost and balance workload (minimize maxHours)
+m.constraint(expr`${totalCost} <= ${minCost * 1.01}`, "near_optimal_cost");
+m.objective(minimize(maxHours));
+await m.solve();
 ```
 
----
+### MIP Tail-Off & Optimality Gap Tolerances
 
-## 🧪 Unit Testing Application Logic with `MockSolver`
+In combinatorial MIP problems, solvers often find a near-optimal feasible solution within seconds, then spend most of the remaining runtime closing the final fraction of a percent in the branch-and-bound tree (**tail-off**).
 
-When running unit tests for application code that builds or consumes a WaSHI `Model`, you can use the built-in `MockSolver` (`solver: "mock"`) to return deterministic results instantaneously without loading WebAssembly:
+In interactive UIs and batch pipelines, combine `timeLimit` with business-meaningful tolerances in [`m.solve(options)`](docs/guide/objectives.md#solve-options-solveoptions):
+- **`relGap: 0.01`**: Stop immediately once the incumbent is proven within **1%** of the theoretical dual bound.
+- **`absGap: 100`**: Stop immediately once `|objectiveValue - objectiveBound| <= 100` in the objective's native units.
 
-```typescript
-import { Model, MockSolver, expr, maximize } from "@ohtaman/washi";
+---
 
-const mock = new MockSolver({
-  status: "Optimal",
-  objectiveValue: 420,
-  values: { x: 10, y: 20 },
-});
+## 5. Decomposition Formulation Tips
 
-const m = new Model({ solver: mock });
-const x = m.integer("x");
-const y = m.integer("y");
-m.objective(maximize(expr`10 * ${x} + 16 * ${y}`));
+When using [`solveColumnGeneration` or `solveBenders`](docs/guide/decomposition.md):
 
-await m.solve();
-console.log(m.objectiveValue); // 420
-console.log(x.value, y.value); // 10, 20
-```
+1. **Set Covering (`>= 1`) vs. Set Partitioning (`== 1`) in Column Generation**:
+   Formulating coverage constraints as inequalities (`>= 1`) rather than equalities (`== 1`) restricts dual shadow prices to $\pi_i \ge 0$, reducing dual oscillations and accelerating convergence whenever over-coverage can be pruned at no extra cost (e.g., Euclidean routing under the triangle inequality).
+2. **Price-and-Branch (`finalizeAsMIP: true`) vs. Exact Branch-and-Price**:
+   Solving the final Restricted Master Problem as a MIP over columns generated at the root LP relaxation (`finalizeAsMIP: true`) implements the **Price-and-Branch** heuristic—avoiding complex branching inside the pricing subproblem while producing high-quality integer solutions in practice.
+3. **Multi-Cut Separation in Benders / Lazy Constraints**:
+   When a separation callback detects multiple disconnected subtours or violated components in a candidate solution, returning cuts for **all** violated components in one batch reduces the number of master MIP re-solves (see [Traveling Salesperson (`examples/traveling-salesperson`)](docs/examples/traveling-salesperson.md)).
 
 ---
 
@@ -1611,9 +2190,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 |
 
 ---
@@ -1639,7 +2218,7 @@ const m3 = new Model({ solver: "glpk" });
 
 ## Solver Guides
 
-- [HiGHS Guide](docs/solvers/highs.md): Web Worker multithreading, MIP tolerances, and QP solving.
+- [HiGHS Guide](docs/solvers/highs.md): Background Web Worker execution, MIP tolerances, and Convex QP solving.
 - [Z3 Guide](docs/solvers/z3.md): SMT assertions, logic modeling, and Unsat Core analysis.
 - [GLPK Guide](docs/solvers/glpk.md): GLPK adapter, GPL-3.0 licensing considerations, and browser usage.
 - [Custom Solvers](docs/solvers/custom-solver.md): Step-by-step developer tutorial for integrating proprietary or cloud REST solvers.
@@ -1648,17 +2227,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 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 })`](docs/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`).
 
 ---
 
@@ -1686,7 +2287,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:
@@ -1697,6 +2298,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](docs/guide/formulation-tips.md).
+
 ---
 
 ## Solver Options
@@ -1717,6 +2321,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)}%`
+  );
+}
 ```
 
 ---
@@ -1741,6 +2353,16 @@ 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)
+
+---
+
 # Z3 SMT Solver Engine
 
 **Z3** is a theorem prover and Satisfiability Modulo Theories (SMT) solver developed by Microsoft Research. In WaSHI, Z3 provides advanced propositional logic reasoning and conflict diagnosis.
@@ -1766,6 +2388,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
@@ -2010,7 +2635,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
@@ -2419,21 +3044,23 @@ describe("Custom Solver Integration", () => {
 
 # Examples & API Finder
 
-Explore runnable optimization and logic formulations built with WaSHI. Every example can be executed directly inside its documentation page, or edited in the [Playground](https://ohtaman.github.io/washi/demo/).
+Explore runnable optimization and logic formulations built with WaSHI. Every example can be executed directly inside its documentation page, or edited in the [Playground](https://washi.ohtaman.dev/demo/).
 
 ## Examples
 
 | Example | Problem Class | Solver | Key WaSHI APIs | Description | Code Editor |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| **[Production Planning](docs/examples/production.md)** | LP / MIP | HiGHS | `m.integer()`, `m.constraint()`, `expr` | Basic variables, tagged template literal equations, and maximizing profit under resource limits. | [Playground](https://ohtaman.github.io/washi/demo/?preset=production) |
-| **[0-1 Knapsack](docs/examples/knapsack.md)** | Binary MIP | HiGHS | `m.binary(keys)`, `sum()`, `m.constraint()` | 1D dictionary of `Binary` variables and linear aggregation over item arrays. | [Playground](https://ohtaman.github.io/washi/demo/?preset=knapsack) |
-| **[Transportation Network](docs/examples/transportation.md)** | LP | HiGHS | `m.continuous(rows, cols)`, `dot()`, `m.constraint()` | 2D matrix indexing (`ship[factory][store]`) and row/column flow balance constraints. | [Playground](https://ohtaman.github.io/washi/demo/?preset=transportation) |
-| **[Diet & Sensitivity Analysis](docs/examples/diet-sensitivity.md)** | LP | HiGHS | `constr.dual`, `constr.slack`, `var.reducedCost` | Reading shadow prices (bottlenecks), constraint surpluses, and reduced costs after solving. | [Playground](https://ohtaman.github.io/washi/demo/?preset=diet_sensitivity) |
-| **[Staff Shift Scheduling](docs/examples/shift-scheduling.md)** | Binary MIP + Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `check()`, `unsatCore` | 5×7 weekly roster planner (coverage, senior duty, max shifts, day-off requests) and diagnosing conflicting vacation requests with Z3 `unsatCore`. | [Playground](https://ohtaman.github.io/washi/demo/?preset=shift_scheduling) |
-| **[E-Commerce Coupon Optimizer](docs/examples/ecommerce-coupons.md)** | Indicator MIP | HiGHS | `m.indicator()`, `sum()`, `m.constraint()` | Checkout optimizer using `m.indicator()` for minimum spend thresholds, exclusive vs. stackable rules, and smart filler add-on suggestions. | [Playground](https://ohtaman.github.io/washi/demo/?preset=cart_coupon) |
-| **[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) |
+| **[Production Planning](docs/examples/production.md)** | LP / MIP | HiGHS | `m.integer()`, `m.constraint()`, `expr` | Basic variables, tagged template literal equations, and maximizing profit under resource limits. | [Playground](https://washi.ohtaman.dev/demo/?preset=production) |
+| **[0-1 Knapsack](docs/examples/knapsack.md)** | Binary MIP | HiGHS | `m.binary(keys)`, `expr` (`dot`), `m.constraint()` | 1D dictionary of `Binary` variables and linear aggregation over item arrays. | [Playground](https://washi.ohtaman.dev/demo/?preset=knapsack) |
+| **[Transportation Network](docs/examples/transportation.md)** | LP | HiGHS | `m.continuous(rows, cols)`, `expr` (`sum`, `dot`), `m.constraint()` | 2D matrix indexing (`ship[factory][store]`) and row/column flow balance constraints. | [Playground](https://washi.ohtaman.dev/demo/?preset=transportation) |
+| **[Diet & Sensitivity Analysis](docs/examples/diet-sensitivity.md)** | LP | HiGHS | `constr.dual`, `constr.slack`, `var.reducedCost` | Reading shadow prices (bottlenecks), constraint surpluses, and reduced costs after solving. | [Playground](https://washi.ohtaman.dev/demo/?preset=diet_sensitivity) |
+| **[Staff Shift Scheduling](docs/examples/shift-scheduling.md)** | Binary MIP + Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `check()`, `unsatCore` | 5×7 weekly roster planner (coverage, senior duty, max shifts, day-off requests) and diagnosing conflicting vacation requests with Z3 `unsatCore`. | [Playground](https://washi.ohtaman.dev/demo/?preset=shift_scheduling) |
+| **[E-Commerce Coupon Optimizer](docs/examples/ecommerce-coupons.md)** | Indicator MIP | HiGHS | `m.indicator()`, `expr` (`sum`, `dot`), `m.constraint()` | Checkout optimizer using `m.indicator()` for minimum spend thresholds, exclusive vs. stackable rules, and smart filler add-on suggestions. | [Playground](https://washi.ohtaman.dev/demo/?preset=cart_coupon) |
+| **[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://washi.ohtaman.dev/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://washi.ohtaman.dev/demo/?preset=smt_security) |
+| **[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://washi.ohtaman.dev/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)
 
@@ -2444,13 +3071,15 @@ Looking for a specific modeling method or solver capability? Jump straight to th
 | ``m.constraint(expr`...`)`` | Tagged template literal constraints | [Production Planning](docs/examples/production.md) | [`01-production-planning.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) |
 | `m.binary(keys)` / `m.continuous(keys)` | 1D dictionary of indexed variables | [0-1 Knapsack](docs/examples/knapsack.md) | [`02-knapsack-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts) |
 | `m.continuous(rows, cols)` / `m.binary(rows, cols)` | 2D matrix of indexed variables | [Transportation Network](docs/examples/transportation.md), [Shift Scheduling](docs/examples/shift-scheduling.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
-| `dot(matrix, vars2d)` / `dot(vector, vars)` | Fast vector/matrix dot product | [Transportation Network](docs/examples/transportation.md), [Portfolio Optimization](docs/examples/portfolio-qp.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
+| ``expr`dot(${A}, ${X})` `` / `dot(A, X)` | Fast vector/matrix dot product | [Transportation Network](docs/examples/transportation.md), [Portfolio Optimization](docs/examples/portfolio-qp.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
 | `constr.dual` & `constr.slack` | Shadow prices & constraint surpluses | [Diet & Sensitivity Analysis](docs/examples/diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
 | `var.reducedCost` | Variable reduced costs in LP | [Diet & Sensitivity Analysis](docs/examples/diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
 | `m.indicator()` | Big-M conditional constraints (`binVar => constr`) | [E-Commerce Coupon Optimizer](docs/examples/ecommerce-coupons.md) | [`12-ecommerce-coupon-optimizer.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) |
 | `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.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
@@ -2469,6 +3098,8 @@ npx tsx examples/node/09-transportation-problem.ts
 npx tsx examples/node/10-diet-sensitivity.ts
 npx tsx examples/node/11-shift-scheduling.ts
 npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
+npx tsx examples/node/13-vehicle-routing-column-generation.ts
+npx tsx examples/node/14-traveling-salesperson-benders.ts
 ```
 
 ---
@@ -2477,7 +3108,7 @@ npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Linear / Integer Programming (LP / MIP) | HiGHS (default) | `m.integer()`, `m.constraint()`, `expr` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=production">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts">Source Code</a></li></ul> |
+| Linear / Integer Programming (LP / MIP) | HiGHS (default) | `m.integer()`, `m.constraint()`, `expr` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=production">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts">Source Code</a></li></ul> |
 
 Production planning is a classic Linear Programming problem: determine the optimal quantity of each product to manufacture in order to maximize total profit while respecting resource constraints (raw materials, machine time, labor hours).
 
@@ -2507,9 +3138,9 @@ async function runProductionOptimization() {
   // Objective: Maximize total profit ($45 per chair, $80 per table)
   m.objective(maximize(expr`45 * ${chairs} + 80 * ${tables}`));
 
-  // Resource constraints: declarative formulas via expr and fluent constraint()
-  m.constraint(expr`5 * ${chairs} + 20 * ${tables} <= 400`, "mahogany_limit")
-   .constraint(expr`10 * ${chairs} + 15 * ${tables} <= 450`, "labor_limit");
+  // Resource constraints: declarative formulas via expr and constraint()
+  m.constraint(expr`5 * ${chairs} + 20 * ${tables} <= 400`, "mahogany_limit");
+  m.constraint(expr`10 * ${chairs} + 15 * ${tables} <= 450`, "labor_limit");
 
   const status = await m.solve();
 
@@ -2527,7 +3158,7 @@ runProductionOptimization();
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| 0-1 Binary MIP | HiGHS (default) | `m.binary()`, `m.constraint()`, `expr`, `maximize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=knapsack">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts">Source Code</a></li></ul> |
+| 0-1 Binary MIP | HiGHS (default) | `m.binary()`, `m.constraint()`, `expr` (`dot`), `maximize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=knapsack">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts">Source Code</a></li></ul> |
 
 The 0-1 Knapsack problem is an essential combinatorial optimization problem: given a set of items, each with a weight and a value, determine which items to include in a collection so that the total weight does not exceed a given limit and the total value is maximized.
 
@@ -2544,7 +3175,7 @@ $$\begin{aligned}
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, maximize, dot, expr } from "@ohtaman/washi";
+import { Model, maximize, expr } from "@ohtaman/washi";
 
 async function solveKnapsack() {
   const m = new Model("Knapsack");
@@ -2564,17 +3195,18 @@ async function solveKnapsack() {
   const values = Object.fromEntries(items.map((it) => [it.name, it.value]));
   const weights = Object.fromEntries(items.map((it) => [it.name, it.weight]));
 
-  // Maximize total value via dot product
-  m.objective(maximize(dot(values, x)));
+  // Maximize total value via dot() inside expr
+  m.objective(maximize(expr`dot(${values}, ${x})`));
 
-  // Weight capacity constraint using natural expr and constraint() syntax
-  m.constraint(expr`${dot(weights, x)} <= ${maxCapacity}`, "capacity_limit");
+  // Weight capacity constraint using expr and constraint()
+  m.constraint(expr`dot(${weights}, ${x}) <= ${maxCapacity}`, "capacity_limit");
 
   const status = await m.solve();
 
   console.log(`Status: ${status}`);
   console.log(`Max Total Value: $${m.objectiveValue}`);
-  console.log("Selected Items:", m.getValues(x));
+  const packed = items.filter((it) => x[it.name].value === 1).map((it) => it.name);
+  console.log("Packed Items:", packed.join(", "));
 }
 
 solveKnapsack();
@@ -2586,7 +3218,7 @@ solveKnapsack();
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=transportation">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts">Source Code</a></li></ul> |
+| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr` (`sum`, `dot`), `minimize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=transportation">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts">Source Code</a></li></ul> |
 
 The transportation problem is one of the most fundamental network optimization models: determine how many units to ship from each supply origin (factory) to each destination (store) to minimize total shipping cost while respecting factory supply limits and meeting store demands.
 
@@ -2617,7 +3249,7 @@ $$\begin{aligned}
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 
 const factories = ["Tokyo", "Nagoya", "Osaka"] as const;
 const stores = ["North", "East", "West", "South"] as const;
@@ -2631,51 +3263,78 @@ const shippingCost = {
 const supplies = { Tokyo: 120, Nagoya: 100, Osaka: 80 };
 const demands = { North: 70, East: 90, West: 60, South: 60 };
 
-async function runTransportation() {
+async function solveScenario(label: string, cap: typeof supplies) {
   const m = new Model("TransportationNetwork");
 
   // 1. Create 2D continuous variables: ship[factory][store] >= 0
   const ship = m.continuous([...factories], [...stores], { lb: 0 });
 
   // 2. Objective: Minimize total shipping cost across all routes via 2D dot product
-  m.objective(minimize(dot(shippingCost, ship)));
+  m.objective(minimize(expr`dot(${shippingCost}, ${ship})`));
 
-  // 3. Supply constraints (row sums): outgoing from f <= supplies[f]
-  for (const f of factories) {
-    m.constraint(
-      expr`${sum(stores, (s) => ship[f][s])} <= ${supplies[f]}`,
-      `supply_${f}`
-    );
-  }
+  // 3. Supply constraints (row sums): outgoing from f <= cap[f]
+  const supplyConstrs = Object.fromEntries(
+    factories.map((f) => [
+      f,
+      m.constraint(expr`sum(${ship[f]}) <= ${cap[f]}`, `supply_${f}`),
+    ])
+  );
 
   // 4. Demand constraints (column sums): incoming to s >= demands[s]
-  for (const s of stores) {
-    m.constraint(
-      expr`${sum(factories, (f) => ship[f][s])} >= ${demands[s]}`,
-      `demand_${s}`
-    );
-  }
+  const demandConstrs = Object.fromEntries(
+    stores.map((s) => [
+      s,
+      m.constraint(
+        expr`sum(${factories}, ${(f) => ship[f][s]}) >= ${demands[s]}`,
+        `demand_${s}`
+      ),
+    ])
+  );
 
   const status = await m.solve();
-  console.log(`Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
+  console.log(`[${label}] Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
   for (const f of factories) {
+    const dual = supplyConstrs[f].dual ?? 0;
     const routes = stores
       .map((s) => `${s}:${Math.round(ship[f][s].value ?? 0)}`)
       .join(", ");
-    console.log(`  ${f.padEnd(7)} -> ${routes}`);
+    console.log(`  ${f.padEnd(7)} -> ${routes} (supply dual: $${dual}/u)`);
   }
+  const demandDuals = stores
+    .map((s) => `${s}:$${demandConstrs[s].dual ?? 0}`)
+    .join(", ");
+  console.log(`  Marginal Delivered Cost (demand duals) -> ${demandDuals}`);
+}
+
+async function runTransportation() {
+  // Scenario A: Baseline capacities ($920)
+  await solveScenario("Scenario A: Baseline", supplies);
+
+  // Scenario B: Tokyo capacity reduced (120 -> 80) due to maintenance ($1,000)
+  await solveScenario("Scenario B: Tokyo Maintenance", {
+    Tokyo: 80,
+    Nagoya: 120,
+    Osaka: 100,
+  });
 }
 
 runTransportation();
 ```
 
+## Practical Notes
+
+- **Interpreting Supply & Demand Shadow Prices (`.dual`)**:
+  - **`demand_s.dual` ($\ge 0$)**: The marginal delivered cost of supplying 1 additional unit to store $s$.
+  - **`supply_f.dual` ($\le 0$)**: How much total network shipping cost would decrease if factory $f$'s capacity were expanded by 1 unit. In Scenario B, when Tokyo is constrained at 80 units, `supply_Tokyo.dual` becomes negative (`-$2/u`), indicating that each extra unit of capacity in Tokyo saves \$2 by avoiding rerouting through Nagoya.
+- **Total Supply vs. Total Demand ($\sum \text{Supply}_f \ge \sum \text{Demand}_s$)**: If store demands exceed aggregate factory capacity, the hard demand constraints become `"Infeasible"`. In production logistics systems, add an elastic "spot-carrier / backorder" variable $u_s \ge 0$ to each store's demand constraint ($\sum_f x_{f,s} + u_s \ge \text{Demand}_s$) with a high penalty cost so the solver allocates scarce inventory optimally rather than failing.
+
 ---
 
 # Diet Problem & Sensitivity Analysis (LP Duals & Slacks)
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=diet_sensitivity">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts">Source Code</a></li></ul> |
+| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr` (`dot`), `minimize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=diet_sensitivity">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts">Source Code</a></li></ul> |
 
 When solving a Linear Programming model, the optimal variable values (`var.value`) are only half the story. In practice, decision-makers need to know:
 
@@ -2699,7 +3358,7 @@ We choose daily servings ($0 \le x_i \le 4$) among 6 food items to meet 4 daily
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, minimize, dot, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 
 const foods = [
   { name: "Oats",    cost: 0.60, calories: 150, protein: 5,  calcium: 20,  iron: 1.8 },
@@ -2722,14 +3381,16 @@ async function runDietSensitivity() {
   const calcs = Object.fromEntries(foods.map((f) => [f.name, f.calcium]));
   const irons = Object.fromEntries(foods.map((f) => [f.name, f.iron]));
 
-  // Objective: Minimize total daily cost via dot product
-  m.objective(minimize(dot(costs, srv)));
+  // Objective: Minimize total daily cost via dot() inside expr
+  m.objective(minimize(expr`dot(${costs}, ${srv})`));
 
   // Nutritional constraints defined declaratively with expr and constraint()
-  m.constraint(expr`${dot(cals, srv)} >= 2000`, "min_calories")
-   .constraint(expr`${dot(prots, srv)} >= 105`,  "min_protein")
-   .constraint(expr`${dot(calcs, srv)} >= 1000`, "min_calcium")
-   .constraint(expr`${dot(irons, srv)} >= 18`,   "min_iron");
+  const nutConstraints = [
+    m.constraint(expr`dot(${cals}, ${srv}) >= 2000`, "min_calories"),
+    m.constraint(expr`dot(${prots}, ${srv}) >= 105`,  "min_protein"),
+    m.constraint(expr`dot(${calcs}, ${srv}) >= 1000`, "min_calcium"),
+    m.constraint(expr`dot(${irons}, ${srv}) >= 18`,   "min_iron"),
+  ];
 
   const status = await m.solve();
 
@@ -2740,11 +3401,8 @@ async function runDietSensitivity() {
     console.log(`  ${f.name.padEnd(8)}: value=${v.value?.toFixed(2)}, reducedCost=${v.reducedCost?.toFixed(4)}`);
   }
   console.log("--- Nutritional Constraints (Dual & Slack) ---");
-  for (const name of ["min_calories", "min_protein", "min_calcium", "min_iron"]) {
-    const c = m.getConstraintByName(name);
-    if (c) {
-      console.log(`  ${c.name.padEnd(13)}: dual=$${c.dual?.toFixed(4)}, slack=${Math.abs(c.slack ?? 0).toFixed(2)}`);
-    }
+  for (const c of nutConstraints) {
+    console.log(`  ${c.name.padEnd(13)}: dual=$${c.dual?.toFixed(4)}, slack=${Math.abs(c.slack ?? 0).toFixed(2)}`);
   }
 }
 
@@ -2755,7 +3413,9 @@ runDietSensitivity();
 
 - **Bottleneck constraints (`slack == 0`, `dual > 0`):** Calories (`2000 kcal`) and Iron (`18 mg`) are tight at their lower bounds. Increasing the daily Iron requirement by 1 mg increases the minimum daily diet cost by **$0.3241**.
 - **Constraints with surplus (`slack > 0`, `dual == 0`):** Protein (`+46.46 g` surplus) and Calcium (`+483.02 mg` surplus) are already exceeded with room to spare, so their shadow prices are `$0`.
-- **Reduced cost (`Salmon`):** Unselected `Salmon` (`0.00` servings) has a reduced cost of `+1.5125`, meaning its price per serving would need to drop by at least **$1.51** before it enters the optimal daily menu.
+- **Reduced cost at lower bound (`Salmon`):** Unselected `Salmon` (`0.00` servings) has a reduced cost of `+1.5125`, meaning its price per serving would need to drop by at least **$1.51** before it enters the optimal daily menu.
+- **Negative reduced cost at upper bound (`Oats`, `Eggs`):** Both `Oats` (`reducedCost = -0.2581`) and `Eggs` (`reducedCost = -0.0887`) are pinned against their upper serving cap (`ub = 4.0`). In a minimization LP, a negative reduced cost on an upper-bounded variable tells you how much the total objective would **decrease** per unit increase in `ub`—raising the daily cap on `Oats` from 4 to 5 servings would save **$0.26/day**.
+- **Basis stability range:** Shadow prices (`dual`) and reduced costs (`reducedCost`) represent local marginal rates of change within the current optimal simplex basis. If a right-hand side or bound changes enough to trigger a basis change (for example, once another variable hits its bound), the marginal rate shifts to a new piece of the piecewise-linear optimal cost curve.
 
 ---
 
@@ -2763,7 +3423,7 @@ runDietSensitivity();
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Binary MIP & SMT Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `m.constraint()`, `expr`, `minimize`, `dot`, `m.check()` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=shift_scheduling">Playground (Roster)</a></li><li><a href="https://ohtaman.github.io/washi/demo/?preset=shift_conflict_unsat">Playground (Conflict)</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts">Source Code</a></li></ul> |
+| Binary MIP & SMT Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `m.constraint()`, `expr` (`sum`, `dot`), `minimize`, `m.check()` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=shift_scheduling">Playground (Roster)</a></li><li><a href="https://washi.ohtaman.dev/demo/?preset=shift_conflict_unsat">Playground (Conflict)</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts">Source Code</a></li></ul> |
 
 Staff shift scheduling is a classic real-world application of Mixed-Integer Programming in SaaS and workforce management tools. However, in real applications, **staff vacation requests frequently collide with minimum coverage or leadership rules**, causing the solver to return `Infeasible`.
 
@@ -2792,7 +3452,7 @@ We evaluate two distinct, named scenarios with different vacation inputs to illu
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as const;
@@ -2825,12 +3485,12 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
       ),
     ])
   );
-  m.objective(minimize(dot(costMatrix, shift)));
+  m.objective(minimize(expr`dot(${costMatrix}, ${shift})`));
 
   // Rule 1: Daily headcount coverage
   for (const d of days) {
     m.constraint(
-      expr`${sum(staffList, (s) => shift[s.name][d])} >= ${requiredCoverage[d]}`,
+      expr`sum(${staffList}, ${(s) => shift[s.name][d]}) >= ${requiredCoverage[d]}`,
       `coverage_${d}`
     );
   }
@@ -2839,7 +3499,7 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
   const seniors = staffList.filter((s) => s.isSenior);
   for (const d of days) {
     m.constraint(
-      expr`${sum(seniors, (s) => shift[s.name][d])} >= 1`,
+      expr`sum(${seniors}, ${(s) => shift[s.name][d]}) >= 1`,
       `senior_duty_${d}`
     );
   }
@@ -2847,7 +3507,7 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
   // Rule 3: Max working days per staff member
   for (const s of staffList) {
     m.constraint(
-      expr`${sum(days, (d) => shift[s.name][d])} <= ${s.maxShifts}`,
+      expr`sum(${shift[s.name]}) <= ${s.maxShifts}`,
       `max_shifts_${s.name}`
     );
   }
@@ -2883,7 +3543,7 @@ async function runScenario(
   if (status === "Optimal") {
     console.log(`Optimal Weekly Payroll: $${model.objectiveValue}`);
     for (const s of staffList) {
-      const schedule = days.map((d) => (Math.round(shift[s.name][d].value ?? 0) === 1 ? "ON" : " ·"));
+      const schedule = days.map((d) => (shift[s.name][d].value === 1 ? "ON" : " ·"));
       console.log(`  ${s.name.padEnd(8)}: ${schedule.join(" ")}`);
     }
     console.log("Schedule resolved successfully (no UNSAT diagnosis needed).\n");
@@ -2929,13 +3589,26 @@ async function main() {
 main();
 ```
 
+## Auto-Repairing Conflicts with Soft Constraints (Elastic Requests)
+
+Once Z3 `unsatCore` diagnoses that `senior_duty_Sat` conflicts with `day_off_Alice_Sat` and `day_off_Bob_Sat`, you can offer managers an automatic repair option by relaxing day-off requests from hard constraints (`shift[staff][day] == 0`) into **soft preferences** penalized in the objective (e.g., `+$500` per overridden day off):
+
+```typescript
+// Soft constraint pattern: penalize working on a requested day off by $500
+// instead of enforcing hard shift[req.staff][req.day] == 0
+const requestedShiftVars = dayOffRequests.map((req) => shift[req.staff][req.day]);
+m.objective(minimize(expr`dot(${costMatrix}, ${shift}) + 500 * sum(${requestedShiftVars})`));
+```
+
+With this soft formulation on Scenario B, HiGHS automatically finds a valid roster that honors 3 of the 4 requests (`Alice (Sat)`, `Charlie (Sat)`, and `Diana (Wed)`) and overrides only `Bob (Sat)`—choosing Bob over Alice because Bob's daily wage (`$210`) is `$10` lower than Alice's (`$220`).
+
 ---
 
 # E-Commerce Cart & Coupon Optimizer (Indicator MIP)
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Mixed-Integer Programming (MIP) | HiGHS (default) | `m.binary()`, `m.constraint()`, `m.indicator()`, `expr`, `minimize` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=cart_coupon">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts">Source Code</a></li></ul> |
+| Mixed-Integer Programming (MIP) | HiGHS (default) | `m.binary()`, `m.constraint()`, `m.indicator()`, `expr`, `minimize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=cart_coupon">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts">Source Code</a></li></ul> |
 
 Modern e-commerce checkouts often feature complex promotional rules: minimum spend thresholds, category-specific discounts, stackable vs. mutually exclusive coupons, and maximum coupon limits per order. Running an optimizer directly in the browser (or an edge worker) lets the checkout UI automatically apply the best coupon combination—and even recommend a small "filler" item when crossing a spend threshold lowers the customer's net bill.
 
@@ -2960,7 +3633,7 @@ By adding the `$10` cable (`$252` gross), the customer unlocks `MEGA45_250` (`-$
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, sum, minimize, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 
 async function optimizeCheckoutCart() {
   const m = new Model("CartCouponOptimizer");
@@ -2981,50 +3654,43 @@ async function optimizeCheckoutCart() {
 
   // Binary decision variables for each coupon
   const useCoupon = m.binary(coupons.map((c) => c.id));
+  const discounts = Object.fromEntries(coupons.map((c) => [c.id, c.discount]));
 
-  const merchSpend = addUsbCable.mul(usbCablePrice).add(baseCartSubtotal);
-  const techSpend  = addUsbCable.mul(usbCablePrice).add(baseTechSubtotal);
+  const merchSpend = expr`${baseCartSubtotal} + ${usbCablePrice} * ${addUsbCable}`;
+  const techSpend  = expr`${baseTechSubtotal} + ${usbCablePrice} * ${addUsbCable}`;
 
-  // 1. Indicator constraints: If useCoupon[id] == 1, minimum spend threshold must hold
+  // 1. Indicator constraints: If useCoupon[id] == 1, minimum spend threshold must hold.
+  // Omitting `M` lets WaSHI automatically derive the tightest Big-M from variable bounds!
   for (const cpn of coupons) {
     if (cpn.minCart > 0) {
-      m.indicator(useCoupon[cpn.id], merchSpend.ge(cpn.minCart), {
+      m.indicator(useCoupon[cpn.id], expr`${merchSpend} >= ${cpn.minCart}`, {
         activeValue: 1,
-        M: 500,
         name: `min_spend_${cpn.id}`,
       });
     }
     if (cpn.minTech > 0) {
-      m.indicator(useCoupon[cpn.id], techSpend.ge(cpn.minTech), {
+      m.indicator(useCoupon[cpn.id], expr`${techSpend} >= ${cpn.minTech}`, {
         activeValue: 1,
-        M: 500,
         name: `min_tech_${cpn.id}`,
       });
     }
   }
 
   // 2. Mutual exclusion among non-stackable ("Exclusive") coupons
-  const exclusiveCoupons = coupons.filter((c) => !c.stackable);
-  m.constraint(
-    expr`${sum(exclusiveCoupons, (c) => useCoupon[c.id])} <= 1`,
-    "at_most_one_exclusive"
-  );
+  const exclusiveVars = coupons.filter((c) => !c.stackable).map((c) => useCoupon[c.id]);
+  m.constraint(expr`sum(${exclusiveVars}) <= 1`, "at_most_one_exclusive");
 
   // 3. Max 2 coupons per order
-  m.constraint(
-    expr`${sum(coupons, (c) => useCoupon[c.id])} <= 2`,
-    "max_two_coupons"
-  );
+  m.constraint(expr`sum(${useCoupon}) <= 2`, "max_two_coupons");
 
   // Objective: Minimize final net payable amount (merchSpend - totalDiscounts)
-  const totalDiscount = sum(coupons, (c) => useCoupon[c.id].mul(c.discount));
-  m.objective(minimize(merchSpend.sub(totalDiscount)));
+  m.objective(minimize(expr`${merchSpend} - dot(${discounts}, ${useCoupon})`));
 
   const status = await m.solve();
   console.log(`Status: ${status}, Optimal Net Payable: $${m.objectiveValue}`);
-  console.log(`Recommended Add-on (+$10 USB-C Cable): ${(addUsbCable.value ?? 0) > 0.5 ? "YES" : "NO"}`);
+  console.log(`Recommended Add-on (+$10 USB-C Cable): ${addUsbCable.value === 1 ? "YES" : "NO"}`);
   for (const cpn of coupons) {
-    const applied = (useCoupon[cpn.id].value ?? 0) > 0.5;
+    const applied = useCoupon[cpn.id].value === 1;
     console.log(`  ${applied ? "✅ [APPLIED]" : "   [skipped]"} ${cpn.id.padEnd(11)} (-$${cpn.discount})`);
   }
 }
@@ -3038,7 +3704,7 @@ optimizeCheckoutCart();
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Convex Quadratic Programming (QP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot`, `QuadExpr` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=portfolio_qp">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts">Source Code</a></li></ul> |
+| Convex Quadratic Programming (QP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot`, `QuadExpr` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=portfolio_qp">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts">Source Code</a></li></ul> |
 
 The Markowitz mean-variance portfolio optimization problem is the foundation of modern quantitative finance: allocate capital across risky assets to minimize overall portfolio variance (risk) subject to achieving a minimum required expected return.
 
@@ -3058,7 +3724,7 @@ where $\boldsymbol{\Sigma}$ is the positive semi-definite asset return covarianc
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, QuadExpr, dot, minimize, expr } from "@ohtaman/washi";
 
 async function solvePortfolio() {
   const m = new Model("PortfolioQP");
@@ -3080,11 +3746,12 @@ async function solvePortfolio() {
   const w = m.continuous(assets, { lb: 0, ub: 1 });
 
   // 1. Budget constraint: sum(w_i) == 1.0 (100%)
-  m.constraint(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget_limit");
+  m.constraint(expr`sum(${w}) == 1.0`, "budget_limit");
 
   // 2. Expected return constraint: sum(r_i * w_i) >= 8.5%
   const retMap = Object.fromEntries(assets.map((a, i) => [a, expectedReturns[i]]));
-  m.constraint(expr`${dot(retMap, w)} >= ${targetReturn}`, "target_return");
+  const portfolioReturn = dot(retMap, w);
+  m.constraint(expr`${portfolioReturn} >= ${targetReturn}`, "target_return");
 
   // 3. Quadratic Objective: minimize risk w^T * Sigma * w
   let risk = new QuadExpr();
@@ -3103,6 +3770,7 @@ async function solvePortfolio() {
   console.log(`Status: ${status}`);
   console.log(`Variance: ${m.objectiveValue?.toFixed(6)}`);
   console.log(`Volatility (Std Dev): ${((Math.sqrt(m.objectiveValue || 0)) * 100).toFixed(2)}%`);
+  console.log(`Expected Return: ${((portfolioReturn.value ?? 0) * 100).toFixed(2)}% (target >= ${(targetReturn * 100).toFixed(2)}%)`);
 
   assets.forEach((name) => {
     console.log(`  ${name.padEnd(10)}: ${((w[name].value ?? 0) * 100).toFixed(2)}%`);
@@ -3112,13 +3780,18 @@ async function solvePortfolio() {
 solvePortfolio();
 ```
 
+## Practical Notes
+
+- **Tracing the Efficient Frontier (`targetReturn` & `portfolioReturn.value`)**: Because the achieved return (`8.50%`) matches `targetReturn` exactly, the return constraint is tightly binding on the Markowitz efficient frontier. Varying `targetReturn` across `[0.05, 0.12]` traces out the full risk-return frontier.
+- **Risk-Aversion Scalarization vs. Target Return Constraint**: If `targetReturn` is set above the highest single-asset return ($12\%$ for `Tech` under long-only weights), the hard constraint $\mathbf{r}^T \mathbf{w} \ge R_{\text{target}}$ becomes `"Infeasible"`. An alternative formulation that is always feasible for any risk appetite $\lambda > 0$ is to minimize the risk-adjusted objective $\min (\lambda \, \mathbf{w}^T \boldsymbol{\Sigma} \mathbf{w} - \mathbf{r}^T \mathbf{w})$.
+
 ---
 
 # SMT Security Policies
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Propositional Logic & SMT | Z3 (`@ohtaman/washi/solvers/z3`) | `m.bool()`, `m.integer()`, `m.constraint()`, `expr`, `m.check()` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=smt_sat_scheduling">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts">Source Code</a></li></ul> |
+| Propositional Logic & SMT | Z3 (`@ohtaman/washi/solvers/z3`) | `m.bool()`, `m.integer()`, `implies()`, `m.constraint()`, `expr`, `m.check()` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=smt_security">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts">Source Code</a></li></ul> |
 
 Satisfiability Modulo Theories (SMT) combines propositional logic (Boolean SAT) with first-order theories (linear integer arithmetic, real inequalities).
 
@@ -3135,7 +3808,7 @@ We model a security rule system with sensor readings and logic rules:
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, not, expr } from "@ohtaman/washi";
+import { Model, implies, not, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 async function verifySecurityRules() {
@@ -3153,7 +3826,7 @@ async function verifySecurityRules() {
   const luxLevel = m.integer("luxLevel", { lb: 0, ub: 1000 });
 
   // Rule 1: luxLevel <= 50 implies isNight
-  m.constraint(luxLevel.le(50).implies(isNight), "dark_implies_night");
+  m.constraint(implies(expr`${luxLevel} <= 50`, isNight), "dark_implies_night");
 
   // Rule 2: (motionDetected AND isNight AND alarmArmed) => sirenActive
   m.constraint(
@@ -3180,20 +3853,32 @@ async function verifySecurityRules() {
   console.log(`Lights On    : ${lightsOn.value}`);
   console.log(`Door Locked  : ${frontDoorUnlocked.value ? "No" : "Yes"}`);
   console.log(`Is Night     : ${isNight.value}`);
+
+  // 4. Formal Safety Verification (Counterexample Search):
+  // Prove that the siren CANNOT remain off under these sensor readings
+  m.constraint(not(sirenActive), "counterexample_siren_off");
+  const proof = await m.check({ solver: "z3" });
+  console.log(`Can siren stay off? ${proof.status} (Proven safe when Unsat)`);
+  console.log(`Active proof core : ${(proof.conflicts ?? []).join(", ")}`);
 }
 
 verifySecurityRules();
 ```
 
+## Practical Notes
+
+- **Proof by Refutation (Counterexample Search)**: A single `Sat` check shows that *a* valid assignment exists. To formally prove that a safety property $P$ (such as `sirenActive`) **must** hold in *every* valid state, assert its negation `not(P)` and verify that `m.check()` returns `"Unsat"`. If it returns `"Sat"`, the solver's variable values give you a concrete counterexample (security loophole).
+- **One-Way Implication (`implies`) vs. Equivalence**: In classical logic, `` implies(expr`${luxLevel} <= 50`, isNight) `` only constrains `isNight` when `luxLevel <= 50`. During daytime (`luxLevel > 50`), `isNight` is unconstrained ("open-world" assumption) and could be assigned either `true` or `false` unless you also add the converse rule `` implies(expr`${luxLevel} >= 51`, not(isNight)) ``.
+
 ---
 
 # Conflict Diagnosis (Unsat Core)
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
+| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `implies()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
 
-When business rules, budgets, and operational policies grow complex, constraints inevitably conflict. Traditional solvers simply report "Infeasible", leaving engineers to guess which of hundreds of rules caused the contradiction.
+When business rules, budgets, and operational policies grow complex, constraints can easily conflict. Because a standard optimization call (`m.solve()`) only reports `"Infeasible"`, WaSHI provides `m.check()` to pinpoint conflicting rules without manual trial-and-error.
 
 This example shows how to isolate the conflicting constraint subset using Z3 Unsat Core extraction.
 
@@ -3213,7 +3898,7 @@ $$8 \text{ engineers} \times \$8,000 = \$64,000 > \$50,000 \text{ budget!}$$
 ## Implementation in WaSHI
 
 ```typescript
-import { Model, expr } from "@ohtaman/washi";
+import { Model, implies, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 async function diagnoseConflicts() {
@@ -3230,7 +3915,7 @@ async function diagnoseConflicts() {
   m.constraint(rushDelivery, "rush_required");
 
   // Rule 3: Rush delivery requires at least 8 engineers
-  m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+  m.constraint(implies(rushDelivery, expr`${engineers} >= 8`), "rush_staffing_rule");
 
   // Rule 4: Board budget cap of $50,000 (Conflict!)
   m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
@@ -3242,8 +3927,381 @@ async function diagnoseConflicts() {
   const res = await m.check({ solver: "z3" });
 
   console.log(`Status: ${res.status}`);
-  console.log("Conflicting Constraints (conflicts):", m.conflicts);
+  console.log("Z3 Unsat Core (scale-invariant):", m.conflicts);
+
+  // Built-in HiGHS can also diagnose conflicts via single-solve L1 elastic slack relaxation:
+  const highsDiag = await m.check({ solver: "highs" });
+  console.log("HiGHS Elastic Repair Set:", highsDiag.conflicts);
 }
 
 diagnoseConflicts();
 ```
+
+## Practical Notes
+
+- **Z3 `unsatCore` vs. HiGHS Elastic Slack `conflicts`**:
+  - **Z3 (`m.check({ solver: "z3" })`)** performs logical assumption tracking and returns all four rules that jointly form the contradiction (`budget_limit`, `rush_required`, `rush_staffing_rule`, `strict_board_budget_cap`), while excluding the innocent `minimum_one_employee` rule.
+  - **HiGHS (`m.check({ solver: "highs" })`)** solves a single $L_1$ elastic slack minimization problem ($\min \sum s_i$). Because relaxing `rush_staffing_rule` (or `rush_required`) requires a slack of only `1`–`2` units whereas relaxing `strict_board_budget_cap` requires a slack of `14,000` dollars, unweighted $L_1$ minimization naturally highlights the smallest-magnitude repair (`rush_required`) needed to restore feasibility.
+
+---
+
+# 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`, `m.binary()`, `m.constraint()`, `expr` (`sum`) | <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">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 } 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(expr`sum(${initialRoutes})`));
+
+  // Each customer must be visited by exactly 1 vehicle
+  const visitConstrs = customers.map((c, i) =>
+    master.constraint(expr`${initialRoutes[i]} == 1`, `visit_${c.id}`)
+  );
+
+  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 === 1);
+  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.
+- **Set Partitioning (`== 1`) vs. Set Covering (`>= 1`)**: This example uses `== 1` so that the final MIP never covers a customer twice. In large-scale column generation, formulating coverage as `>= 1` restricts the dual prices to $\pi_i \ge 0$, avoiding negative dual oscillations; if the final MIP selects overlapping routes, duplicate visits can be removed by post-processing whenever distances satisfy the triangle inequality.
+- **Heuristic Pricing vs. Exact ESPPRC**: Because `findImprovingRoute` uses a fast greedy heuristic (cheapest insertion + 2-opt) instead of an exact Elementary Shortest Path Problem with Resource Constraints (ESPPRC) solver, returning `null` means no further improving columns were found by the heuristic rather than proving global LP optimality.
+- **Price-and-Branch (`finalizeAsMIP: true`)**: Solving the Restricted Master Problem as a MIP over the columns generated at the root node is known as the *Restricted Master Heuristic* (Price-and-Branch). It produces near-optimal integer fleets quickly without requiring full Branch-and-Price tree search.
+
+---
+
+# 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">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 } 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 = {};
+  const distMatrix = {};
+
+  for (let i = 0; i < n; i++) {
+    x[i] = {};
+    distMatrix[i] = {};
+    for (let j = 0; j < n; j++) {
+      if (i !== j) {
+        x[i][j] = master.binary(`x_${i}_${j}`);
+        distMatrix[i][j] = dist(i, j);
+      }
+    }
+  }
+
+  // Objective: Minimize total tour distance
+  master.objective(minimize(expr`dot(${distMatrix}, ${x})`));
+
+  // Each city must have 1 outgoing and 1 incoming edge
+  for (let i = 0; i < n; i++) {
+    master.constraint(expr`sum(${x[i]}) == 1`, `out_${i}`);
+    master.constraint(expr`sum(${n}, ${(j) => x[j][i]}) == 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 && x[i][j].value === 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 cuts for all cycles
+      if (cycles.length > 1) {
+        return cycles.map((cycle) => {
+          const S = new Set(cycle);
+          cutCounter++;
+          console.log(`Subtour detected: [${cycle.map(k => cities[k].name).join(" -> ")}]. Adding Benders cut #${cutCounter}.`);
+
+          const outCities = Array.from({ length: n }, (_, j) => j).filter((j) => !S.has(j));
+          const cutEdges = cycle.flatMap((i) => outCities.map((j) => x[i][j]));
+
+          return {
+            kind: "feasibility",
+            constraint: expr`sum(${cutEdges}) >= 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}`] === 1) {
+        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.
+- **Multi-Cut Separation**: Returning an array of cuts (`cycles.map(...)`) from `subproblem` eliminates all disconnected cycles discovered in the current candidate solution simultaneously, reducing the number of master MIP re-solves.
+- **Two Equivalent DFJ Cut Forms**: Because every city has out-degree $\sum_{j \ne i} x_{ij} = 1$, summing over $i \in S$ gives $\sum_{i \in S, j \in S} x_{ij} + \sum_{i \in S, j \notin S} x_{ij} = |S|$. Thus the cut-set inequality $\sum_{i \in S, j \notin S} x_{ij} \ge 1$ used above and the internal-edge inequality $\sum_{i \in S, j \in S} x_{ij} \le |S| - 1$ used in [`14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) are algebraically identical.
+- **Upfront 2-City Subtour Elimination**: In larger TSP instances, mutual 2-cycles ($i \leftrightarrow j$) are the most frequent initial subtours. Adding the $\binom{n}{2}$ pairwise constraints $x_{ij} + x_{ji} \le 1$ directly to the initial master problem often cuts the number of Benders iterations substantially.
+- **Termination Condition**: Returning `null` from `subproblem` indicates that no violated subtour constraints remain.