@ohtaman/washi 0.4.0 → 0.5.0

package/llms-full.txt

@@ -0,0 +1,3249 @@
+# AI Coding Agent Quick-Reference Guide
+
+> **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
+>   mkdir -p .agents/skills/washi
+>   cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
+>   ```
+> - **Repository Review Guidelines**: For repository contribution and pull-request review rules, see [`AGENTS.md`](https://github.com/ohtaman/washi/blob/main/AGENTS.md) in the repository root.
+
+---
+
+## 1. Package Imports & Deployment
+
+### Node.js / Bundlers (Vite, Webpack, Next.js, Bun)
+
+```ts
+import {
+  Model,
+  expr,
+  sum,
+  dot,
+  maximize,
+  minimize,
+  and,
+  or,
+  not,
+  implies,
+  xor,
+  setHighsWasmUrl,
+} from "@ohtaman/washi";
+
+// Optional solver plugins (require installing peer dependencies first):
+// npm install z3-solver
+import "@ohtaman/washi/solvers/z3";
+// npm install glpk.js
+import "@ohtaman/washi/solvers/glpk";
+```
+
+### Browser ESM & Classic Script Tags
+
+- **Browser ESM**:
+  - Core (HiGHS built-in): `import { Model, expr, maximize } from "./washi/washi.js";`
+  - GLPK plugin: `import "./washi/solvers/glpk.js";`
+  - Z3 plugin: `import "./washi/solvers/z3.js";`
+- **Classic `<script>` / CodePen (IIFE)**:
+  - Core: `<script src="./washi/washi.min.js"></script>` (exposes global `Washi`)
+  - GLPK plugin: `<script src="./washi/solvers/glpk.min.js"></script>` (registers `"glpk"`, exposes `WashiGLPK`)
+  - Z3 plugin: `<script src="./washi/solvers/z3.min.js"></script>` (registers `"z3"`, exposes `WashiZ3`)
+
+### WebAssembly Asset & Runtime Rules
+
+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).
+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)
+     - `Cross-Origin-Embedder-Policy: require-corp` (on the document)
+     - `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin` (on cross-origin script/WASM asset responses)
+   - 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).
+   - 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.
+
+---
+
+## 2. Canonical Modeling Workflow
+
+Formulating and solving a model consists of four distinct steps:
+
+### Step 1: Create Model & Decision Variables
+
+```ts
+const m = new Model("ExampleModel");
+
+// Scalar variables
+const x = m.continuous("x", { 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)
+
+// Indexed variable containers:
+// - Numeric dimension -> Array
+// - Key-array dimension -> Record
+const vec = m.continuous(4, { lb: 0, prefix: "v" }); // Var[] (length 4)
+const grid = m.binary(2, 3, { prefix: "g" }); // Var[][] (2x3)
+const byItem = m.integer(["desk", "chair"] as const, { lb: 0 }); // Record<"desk" | "chair", Var>
+const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
+```
+
+- **Optional Primal Initial Values (`initialValue?: number`)**:
+  - Numeric variable constructors (`m.continuous`, `m.integer`, `m.binary`, and `new Var`) and the mutable `v.initialValue` property accept an optional finite primal hint (validated with tolerance `1e-6` against bounds `[lb, ub]` and integer/binary domains), kept distinct from the solved `v.value`.
+  - A start may be complete or partial (e.g., transferred by stable variable names when rebuilding a MIP model). Supplying `initialValue` is a hint only—it does **not** fix the variable, add a hard constraint, or guarantee solver acceptance or a runtime speedup.
+  - Supported by **HiGHS** (`supportsWarmStart: true`); solvers without warm-start support (**GLPK**, **Z3**) throw an error if any variable has `initialValue !== undefined`.
+
+### 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.
+- **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?)`
+  - Boolean logic (on `BoolVar`, `BoolExpr`, and `Constraint` for Z3): standalone `and(...)`, `or(...)`, `not(...)`, `implies(a, b)`, `xor(a, b)` and fluent `.and(...)`, `.or(...)`, `.not()`, `.implies(...)`, `.xor(...)`
+
+### Step 3: Register Objective & Constraints on the Model
+
+Constructing an `expr` or `.le()` object does **not** attach it to the model until you pass it to `m.constraint(...)` or `m.objective(...)`:
+
+```ts
+// 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");
+
+// Indicator constraint (MIP Big-M reformulation: b === 1 => x <= 50)
+m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
+```
+
+### Step 4: Execute (`solve` or `check`) & Verify (`validateSolution`)
+
+- **Optimization (`await m.solve(options?)`)**:
+  - 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).
+- **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.
+
+---
+
+## 3. Executable Examples
+
+### Example A: Mixed-Integer Linear Programming (MIP) with Indexed Containers & Solution Validation
+
+```ts
+import { Model, expr, dot, sum, maximize } from "@ohtaman/washi";
+
+export async function runMipExample() {
+  const m = new Model("ProductionMIP");
+  const products = ["desk", "chair"] as const;
+  const profit = { desk: 30, chair: 50 };
+  const woodPerUnit = { desk: 1, chair: 2 };
+  const laborPerUnit = { desk: 2, chair: 1 };
+
+  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");
+
+  const status = await m.solve();
+  const report = m.validateSolution();
+  const values = m.getValues(qty);
+
+  return {
+    status,
+    objectiveValue: m.objectiveValue,
+    values,
+    setup: setup.value,
+    valid: report.valid,
+    maxViolation: report.maxViolation,
+  };
+}
+```
+
+### Example B: Convex Quadratic Programming (QP)
+
+Variable-by-variable products (`${x} * ${y}`) and squares (`${x}^2`) are supported in `expr` for quadratic objectives:
+
+```ts
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+export async function runQpExample() {
+  const m = new Model("PortfolioQP");
+  const x = m.continuous("x", { lb: 0 });
+  const y = m.continuous("y", { lb: 0 });
+
+  // Minimize x^2 + y^2 subject to x + y >= 4
+  m.objective(minimize(expr`${x}^2 + ${y}^2`));
+  m.constraint(expr`${x} + ${y} >= 4`, "budget");
+
+  const status = await m.solve();
+  const report = m.validateSolution();
+
+  return {
+    status,
+    objectiveValue: m.objectiveValue,
+    x: x.value,
+    y: y.value,
+    valid: report.valid,
+  };
+}
+```
+
+### Example C: Z3 Feasibility Check & Unsat Core Diagnosis
+
+```ts
+import { Model, expr, implies } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+export async function runZ3Example() {
+  const m = new Model("PolicyCheck", { solver: "z3" });
+  const vip = m.bool("vip");
+  const discount = m.integer("discount", { lb: 0, ub: 50 });
+
+  m.constraint(vip, "customer_is_vip");
+  m.constraint(implies(vip, expr`${discount} >= 20`), "vip_min_discount");
+  m.constraint(expr`${discount} <= 10`, "campaign_cap");
+
+  const unsatResult = await m.check();
+  return {
+    status: unsatResult.status,
+    conflicts: unsatResult.conflicts,
+  };
+}
+```
+
+---
+
+## 4. Negative Examples & Common Pitfalls
+
+Avoid these invalid patterns and retired aliases:
+
+```ts
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+export function verifyNegativePatterns() {
+  const m = new Model("NegativeExamples");
+  const x = m.continuous("x", { lb: 0 });
+  const y = m.continuous("y", { lb: 0 });
+
+  // 1. DO NOT pass a Constraint to m.objective() or arithmetic methods:
+  // WRONG: m.objective(maximize(expr`${x} <= 10` as any)); -> throws Error
+  // WRONG: expr`${x} + 1`.add(expr`${y} <= 5` as any); -> throws Error
+
+  // 2. DO NOT pass an arithmetic expression without (<=, >=, ==) to m.constraint():
+  // WRONG: m.constraint(expr`${x} + ${y}` as any); -> throws Error
+
+  // 3. DO NOT use quadratic terms inside linear constraints:
+  // WRONG: expr`${x}^2 <= 10`; -> throws Error ("Quadratic constraints are not supported")
+
+  // 4. DO NOT use retired aliases (removed in #59 / #81):
+  // - Use `expr` instead of retired `c` template tag
+  // - Use `m.constraint(...)` instead of `m.constrain(...)` or `m.add(...)`
+  // - Use `m.objective(maximize(...))` / `m.objective(minimize(...))` instead of `m.maximize(...)` / `m.minimize(...)` / `m.setObjective(...)`
+  // - Use `await m.solve()` instead of `await m.optimize()`
+  // - Use `.le()`, `.ge()`, `.eq()` instead of `.lessThanOrEqual()`, `.greaterThanOrEqual()`, `.equalTo()`
+  // - Use `.value` or `m.getValues(...)` instead of `expr.getValue()`
+  // - Use `m.variables` / `m.constraints` instead of `m.vars` / `m.constrs`
+  return { m, x, y, maximize };
+}
+```
+
+---
+
+# Introduction & Installation
+
+Welcome to **WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface).
+
+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.
+
+### Why TypeScript & WebAssembly?
+
+- **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]}`).
+
+---
+
+## 📦 Installation
+
+Install WaSHI using your preferred package manager:
+
+```bash [npm]
+npm install @ohtaman/washi
+```
+
+```bash [pnpm]
+pnpm add @ohtaman/washi
+```
+
+```bash [yarn]
+yarn add @ohtaman/washi
+```
+
+```bash [bun]
+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:
+
+```bash
+# For SMT logic and Unsat Core conflict diagnosis
+npm install z3-solver
+
+# For GLPK solver (GPL-3.0)
+npm install glpk.js
+```
+
+---
+
+## 🚀 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:
+
+```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}`));
+```
+
+### 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):
+
+```typescript
+const status = await model.solve();
+
+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
+```
+
+---
+
+## 🧭 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).
+
+---
+
+# 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.
+
+---
+
+## 🟢 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";
+
+const m = new Model("NodeExample");
+const x = m.continuous("x", { lb: 0, ub: 10 });
+const y = m.continuous("y", { lb: 0, ub: 20 });
+
+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}`);
+```
+
+Run directly with `tsx` or `node`:
+
+```bash
+npx tsx app.ts
+```
+
+---
+
+## 🌐 Bundlers (Vite, Webpack, Rollup, Next.js)
+
+### Modern Bundlers (Vite / Rollup / Webpack)
+
+When importing `@ohtaman/washi` in a browser bundler, the `browser` export condition resolves automatically:
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+export async function runOptimization() {
+  const m = new Model({ solver: "highs" });
+  const x = m.continuous("x", { lb: 0, ub: 100 });
+  m.objective(maximize(x));
+  await m.solve();
+  return x.value;
+}
+```
+
+#### 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`).
+
+If your environment prohibits Web Workers or you explicitly want synchronous main-thread execution, pass `useWorker: false`:
+
+```typescript
+await m.solve({ useWorker: false });
+```
+
+#### Customizing the HiGHS WASM Asset URL
+By default, WaSHI resolves `highs.wasm` relative to the bundle (`new URL("./highs.wasm", import.meta.url)`). It **never** makes implicit requests to external CDNs (`jsdelivr`, `unpkg`, etc.).
+
+If your bundler or static server hosts `.wasm` files under a custom path, configure the URL globally or per solve:
+
+```typescript
+import { setHighsWasmUrl } from "@ohtaman/washi";
+
+// Option A: Configure globally before solving
+setHighsWasmUrl("/assets/wasm/highs.wasm");
+
+// Option B: Configure per solve call
+await m.solve({ wasmUrl: "/assets/wasm/highs.wasm" });
+```
+
+### Next.js & Server-Side Rendering (SSR)
+
+In Next.js App Router or Pages Router, optimization models can run either in Server Actions / API Routes (Node.js runtime) or on the client inside `"use client"` components:
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { Model, maximize } from "@ohtaman/washi";
+
+export default function OptimizerComponent() {
+  const [val, setVal] = useState<number | null>(null);
+
+  const handleSolve = async () => {
+    const m = new Model();
+    const x = m.continuous("x", { lb: 0, ub: 50 });
+    m.objective(maximize(x));
+    await m.solve();
+    setVal(x.value);
+  };
+
+  return (
+    <div>
+      <button onClick={handleSolve}>Run Optimization</button>
+      {val !== null && <p>Result: {val}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## 📦 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:
+
+```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";
+  // Optional solver plugins:
+  // import "./dist/browser/solvers/glpk.js";
+  // import "./dist/browser/solvers/z3.js";
+
+  const m = new Model("BrowserESM");
+  const x = m.integer("x", { lb: 0 });
+  const y = m.integer("y", { lb: 0 });
+
+  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);
+</script>
+```
+
+---
+
+## 🟨 Classic `<script>` Tags (IIFE / Standalone Build / 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:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>WaSHI Browser Demo</title>
+  </head>
+  <body>
+    <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> -->
+    <!-- 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>
+      (async () => {
+        const { Model, expr, maximize } = Washi;
+
+        const m = new Model("BrowserDemo");
+        const x = m.continuous("x", { lb: 0, ub: 10 });
+        const y = m.continuous("y", { lb: 0, ub: 20 });
+
+        m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
+        m.constraint(expr`${x} + ${y} <= 15`);
+
+        await m.solve();
+
+        document.getElementById("output").textContent =
+          `Status: ${m.status}\n` +
+          `Objective: ${m.objectiveValue}\n` +
+          `x = ${x.value}, y = ${y.value}`;
+      })();
+    </script>
+  </body>
+</html>
+```
+
+> [!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.
+
+---
+
+## 🔒 Offline, Intranet & Strict CSP Environments
+
+WaSHI never phones home or falls back to public CDNs. To self-host in an air-gapped intranet or under a strict Content Security Policy (CSP):
+
+1. **Copy Static Assets**: Serve the files from `node_modules/@ohtaman/washi/dist/browser/` on your own origin:
+   - `washi.js` / `washi.min.js`, `highs.wasm`, and `highs-worker.js`
+   - Optional GLPK: `solvers/glpk.js` / `solvers/glpk.min.js`
+   - 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 `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);
+```
+
+---
+
+# 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.
+
+---
+
+## 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**.
+
+---
+
+## Required HTTP Response Headers
+
+To establish cross-origin isolation, your web server must serve the top-level HTML document with the following HTTP headers:
+
+```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:
+
+```http
+Cross-Origin-Resource-Policy: cross-origin
+```
+
+---
+
+## Solutions by Hosting Environment
+
+### 1. 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();
+});
+```
+
+### 2. Next.js (`next.config.js`)
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
+          { key: "Cross-Origin-Embedder-Policy", value: "require-corp" },
+        ],
+      },
+    ];
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### 3. Static Hosting without Header Control (e.g., GitHub Pages)
+
+Platforms like GitHub Pages or preview environments do not allow customizing response headers directly.
+
+For these environments, you can use **`coi-serviceworker`** (a lightweight Service Worker that injects isolation headers on the client side):
+
+1. Place `coi-serviceworker.js` in your website root.
+2. In your HTML `<head>`, include:
+
+```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`.
+
+---
+
+## Graceful Degradation 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.
+
+---
+
+# Variables & Domains
+
+Variables represent the mathematical decision variables in your optimization model.
+WaSHI provides domain-specific factory methods on the `Model` instance: `m.continuous()`, `m.integer()`, `m.binary()`, and `m.bool()`.
+
+---
+
+## 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:
+
+```typescript
+import { Model } from "@ohtaman/washi";
+
+const m = new Model();
+
+// Single continuous variable bounded in [0, 1000]
+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):
+
+```typescript
+// Single integer variable bounded in [0, 15]
+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:
+
+```typescript
+// Single binary variable
+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:
+
+```typescript
+// Single propositional boolean variable
+const isNight = m.bool("isNight");
+const alarmTriggered = m.bool("alarmTriggered");
+
+// First-class boolean operators: and, or, not, implies, xor
+m.constraint(alarmTriggered.implies(isNight), "alarm_policy");
+```
+
+### 💡 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).
+
+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");
+
+// 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");
+```
+
+---
+
+## 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.
+
+### By Count
+Pass a number to create an array of variables:
+
+```typescript
+const x = m.continuous(5, { lb: 0 }); // Var[] (x_0, ..., x_4)
+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>`:
+
+```typescript
+const items = ["laptop", "phone", "tablet"];
+
+// Record<"laptop" | "phone" | "tablet", Var>
+const selected = m.binary(items);
+
+const perms = m.bool(["read", "write", "execute"]);
+// perms.read, perms.write, perms.execute
+```
+
+### 2D Variable Matrices & Grids
+Each dimension follows a consistent rule: passing a numeric count (`number`) produces an `Array`, and passing a collection of keys produces a `Record`:
+- `(rowsCount, colsCount)` $\rightarrow$ `Var[][]` (or `BoolVar[][]`)
+- `(rowKeys, colKeys)` $\rightarrow$ `Record<R, Record<C, Var>>` (or `Record<R, Record<C, BoolVar>>`)
+- `(rowsCount, colKeys)` $\rightarrow$ `Array<Record<C, Var>>`
+- `(rowKeys, colsCount)` $\rightarrow$ `Record<R, Var[]>`
+
+```typescript
+const factories = ["Tokyo", "Osaka"];
+const stores = ["StoreA", "StoreB", "StoreC"];
+
+// 1. Named keys x Named keys -> Record<string, Record<string, Var>>
+const ship = m.continuous(factories, stores, { lb: 0 });
+// ship.Tokyo.StoreA
+
+// 2. Numeric count x Numeric count -> Var[][] (2D Array)
+const board = m.binary(8, 8, { prefix: "queen" });
+// board[0][0], board.map(...)
+
+// 3. Mixed dimensions: Named keys x Numeric count -> Record<string, Var[]>
+const schedule = m.binary(factories, 7, { prefix: "open_day" });
+// schedule.Tokyo[0]
+```
+
+---
+
+## Variable Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `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`. |
+
+---
+
+## 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 = ...`):
+
+```typescript
+const prevValues: Record<string, number | null> = { trucks: 8, open_warehouse: 1 };
+
+const m2 = new Model("RebuiltMIP");
+const trucks2 = m2.integer("trucks", {
+  lb: 0,
+  ub: 15,
+  initialValue: prevValues.trucks ?? undefined,
+});
+const openWarehouse2 = m2.binary("open_warehouse", {
+  initialValue: prevValues.open_warehouse ?? undefined,
+});
+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.
+- **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()`:
+
+```typescript
+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)
+console.log(`fuel reduced cost: ${fuel.reducedCost}`);
+
+// Bulk extraction for 1D or 2D collections (works for both Var and BoolVar collections)
+const selectedValues = m.getValues(selected);
+// { laptop: 1, phone: 0, tablet: 1 }
+
+const flowValues = m.getValues(ship);
+// { Tokyo: { StoreA: 50, ... }, Osaka: { ... } }
+```
+
+---
+
+## Looking Up Variables by Name
+
+You can retrieve registered decision variables by name or inspect the total variable count on the model:
+
+```typescript
+const v = m.getVarByName("trucks");           // Var | undefined
+const b = m.getBoolVarByName("isNight");      // BoolVar | undefined
+console.log("Total numeric variables:", m.numVars);
+```
+
+---
+
+# Expressions (`expr`, `sum`, `dot`)
+
+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.
+
+| Approach | Example | Infix readability | Type safety & IDE rename | Indexed variables (`flow[i][j]`) |
+| :--- | :--- | :--- | :--- | :--- |
+| Method chaining | `x.mul(30).add(y.mul(50)).le(40)` | Low | Yes | Yes |
+| Raw string parsing | `parseConstraint("30 * x + 50 * y <= 40", resolver)` | High | No (runtime string lookup) | Fragile (string concatenation) |
+| **Tagged template (`expr`)** | `` expr`30 * ${x} + 50 * ${y} <= 40` `` | **High** | **Yes (actual TS references)** | **Yes (bound by object reference)** |
+
+---
+
+## ✍️ 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.
+
+Use `expr` for both arithmetic expressions (`LinExpr | QuadExpr`) and relational constraints (`Constraint`):
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// 1. Linear combination: 3*x + 5*y - 10
+const linearExpr = expr`3 * ${x} + 5 * ${y} - 10`;
+
+// 2. Quadratic expression: x * y + 2 * x^2
+const quadExpr = expr`${x} * ${y} + 2 * ${x} * ${x}`;
+
+// 3. Relational constraint:
+const balanceConstraint = expr`${x} + 2 * ${y} <= 40`;
+```
+
+### Supported Syntax in `expr`
+- **Addition & Subtraction**: `${x} + ${y} - 5`
+- **Scalar Multiplication**: `4 * ${x}`, `${x} * 4`
+- **Variable Multiplication (Quadratic terms)**: `${x} * ${y}`, `2 * ${x} * ${x}`
+- **Powers & Exponentiation**: `${x}^2`, `${x}**2`
+- **Unary Negation**: `-${x} + 10`
+- **Parentheses**: `2 * (${x} + ${y})`
+- **Nested Expressions**: `expr` seamlessly interpolates variables, numbers, `sum()` results, and nested expressions.
+
+> [!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.
+
+---
+
+## ⚡ High-Performance Summation (`sum`)
+
+For iterating over large collections of variables or indices:
+
+```typescript
+import { sum } from "@ohtaman/washi";
+
+const items = ["A", "B", "C"];
+const weights = { A: 10, B: 20, C: 30 };
+const x = m.binary(items);
+
+// 1. Transform elements with a mapping callback:
+const totalWeight = sum(items, (item) => x[item].mul(weights[item]));
+
+// 2. Direct array summation:
+const count = sum(Object.values(x));
+```
+
+`sum()` runs in $O(N)$ linear time without AST overhead.
+
+---
+
+## 🎯 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)`).
+
+Supported 1D and 2D container shapes:
+- **1D Arrays**: `number[]` $\times$ `(Var | LinExpr)[]`
+- **1D Records**: `Record<K, number>` $\times$ `Record<K, Var | LinExpr>`
+- **2D Arrays**: `number[][]` $\times$ `(Var | LinExpr)[][]`
+- **2D Records**: `Record<R, Record<C, number>>` $\times$ `Record<R, Record<C, Var | LinExpr>>`
+- **2D Mixed**: `Array<Record<C, ...>>` or `Record<R, Array<...>>`
+
+Mismatched array lengths, missing dictionary keys, or non-finite/non-linear leaves throw an explicit error indicating the offending path (e.g., `at '[0].StoreB'`).
+
+### 1D Vector Dot Product
+```typescript
+import { dot } from "@ohtaman/washi";
+
+const profits = { desk: 30, chair: 50 };
+const vars = m.integer(["desk", "chair"]);
+
+// Computes 30 * vars.desk + 50 * vars.chair
+const totalProfit = dot(profits, vars);
+```
+
+### 2D Matrix Dot 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 costs = {
+  Tokyo: { StoreA: 4, StoreB: 7 },
+  Osaka: { StoreA: 8, StoreB: 3 },
+};
+
+const ship = m.continuous(factories, stores);
+
+// Total shipping cost in one line:
+m.objective(minimize(dot(costs, ship)));
+```
+
+---
+
+## 🧮 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()`:
+
+### 1. Using `expr` (Recommended)
+You can write quadratic formulas naturally with `*`, `^2`, or `**2`:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// Quadratic objective using expr:
+m.objective(minimize(expr`3 * ${x} + ${x}^2 + ${y}^2`));
+
+// Linear constraint using expr:
+m.constraint(expr`${x} + ${y} >= 4`);
+```
+
+### 2. Method Chaining with `.mul()` or `QuadExpr`
+Alternatively, you can construct quadratic expressions programmatically:
+
+```typescript
+import { Model, QuadExpr, minimize } from "@ohtaman/washi";
+
+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
+const quad = x.mul(y).add(x.mul(x).mul(2));
+
+// 2. Build portfolio risk objective: w^T * Sigma * w
+const assets = ["Tech", "Bonds"];
+const w = m.continuous(assets, { lb: 0, ub: 1 });
+
+let risk = new QuadExpr();
+risk = risk.add(w.Tech.mul(w.Tech).mul(0.04));
+risk = risk.add(w.Tech.mul(w.Bonds).mul(0.005));
+risk = risk.add(w.Bonds.mul(w.Bonds).mul(0.01));
+
+m.objective(minimize(risk));
+```
+
+---
+
+## 📊 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:
+
+```typescript
+const revenue = expr`30 * ${x} + 50 * ${y}`;
+const laborUsed = expr`2 * ${x} + ${y}`;
+
+m.objective(maximize(revenue));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_cap");
+m.constraint(expr`${laborUsed} <= 50`, "labor_cap");
+
+await m.solve();
+
+console.log("Total Revenue:", revenue.value);   // 1100 (x = 20, y = 10)
+console.log("Labor Used:", laborUsed.value);    // 50
+```
+
+If the model has not been solved (or any variable in the expression has `value === null`), `.value` returns `null`.
+
+---
+
+## 🔗 Fluent Arithmetic & Relational Methods
+
+In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent methods for programmatic expression building:
+
+| Method | Supported On | Return Type | Description |
+| :--- | :--- | :--- | :--- |
+| `.add(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Adds a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.sub(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Subtracts a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.mul(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Multiplies by a scalar `number`, or multiplies two linear terms into a `QuadExpr`. |
+| `.div(divisor)` | `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Divides by a non-zero finite scalar `number`. |
+| `.neg()` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Negates all terms ($-e$). |
+| `.le(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\le$ constraint (`lhs <= rhs`). |
+| `.ge(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\ge$ constraint (`lhs >= rhs`). |
+| `.eq(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds an $==$ equality constraint (`lhs == rhs`). |
+
+---
+
+# 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()`**:
+
+```typescript
+m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_limit");
+```
+
+---
+
+## ✍️ Algebraic Linear Constraints (`expr`)
+
+The `expr` tagged template literal syntax allows writing equations and inequalities with natural mathematical notation:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// Upper bound inequality (<=)
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+
+// Lower bound inequality (>=)
+m.constraint(expr`3 * ${x} + ${y} >= 20`, "min_demand");
+
+// Exact equality (==)
+m.constraint(expr`${x} + ${y} == 30`, "exact_quota");
+```
+
+### 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:
+
+```typescript
+m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
+```
+
+---
+
+## 🏷️ Naming Constraints
+
+Every constraint can be given 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.
+3. **Direct Lookup (`m.getConstraintByName()`)**: Retrieve a constraint by name after solving to inspect its `dual` or `slack` value.
+
+---
+
+## 🔁 Adding Constraints over Iterables & Sums
+
+Use `sum()` or `dot()` inside `expr` to express linear aggregations cleanly:
+
+```typescript
+import { Model, sum, expr } from "@ohtaman/washi";
+
+const items = ["A", "B", "C"];
+const weights = { A: 5, B: 10, C: 15 };
+const selected = m.binary(items);
+
+// Total weight cannot exceed capacity 25
+m.constraint(
+  expr`${sum(items, (i) => selected[i].mul(weights[i]))} <= 25`,
+  "capacity_limit"
+);
+```
+
+---
+
+## 🎯 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()`:
+
+```typescript
+const useDiscount = m.binary("use_discount");
+const cartTotal = m.continuous("cart_total", { lb: 0, ub: 10_000 });
+
+// If useDiscount == 1, then cartTotal >= 100
+// WaSHI automatically derives a safe, tight Big-M from the variable bounds
+m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
+  activeValue: 1,
+  name: "min_spend_for_discount",
+});
+```
+
+### 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:
+- 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`).
+
+If any referenced variable lacks the required finite bounds, `m.indicator()` throws an actionable error prompting for finite bounds or an explicit `options.M`.
+
+### Explicit Override & Numerical Stability
+
+You can override the derived Big-M by providing `{ M: number }`:
+
+```typescript
+m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
+  activeValue: 1,
+  M: 10_000, // Explicit override
+});
+```
+
+> [!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.
+
+---
+
+## 🧠 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:
+
+```typescript
+import { Model, expr, and, or, not, implies, xor } from "@ohtaman/washi";
+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 });
+
+// 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`),
+  "admin_clearance_level"
+);
+
+// Top-level helper functions (and, or, not, implies, xor):
+m.constraint(and(or(isAdmin, hasMfa), not(xor(isAdmin, hasMfa))), "policy");
+```
+
+### Choosing Between `m.indicator()` and `implies()`
+
+| Feature | `m.indicator(binVar, constraint, opts)` | `implies(a, b)` / `a.implies(b)` |
+| :--- | :--- | :--- |
+| **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()`) |
+
+---
+
+## 📐 Dual Values, Shadow Prices & Lookups
+
+For continuous Linear Programming (LP) problems, query the economic shadow price (`dual`) and surplus (`slack`) on each constraint:
+
+```typescript
+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("Total linear constraints:", m.numConstrs);
+```
+
+For logical constraints registered with a name, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+
+---
+
+# Objectives & Solving (`m.solve` & `m.check`)
+
+The objective function defines the goal of mathematical optimization—whether to maximize profits, minimize costs, or minimize quadratic risk variance. When you only need to verify constraint feasibility or solve pure SMT logic, you can also run `m.check()` without an objective.
+
+---
+
+## Setting the Objective Function
+
+Set the objective direction and formula declaratively using `m.objective(maximize(...))` or `m.objective(minimize(...))`:
+
+```typescript
+import { Model, expr, maximize, minimize } from "@ohtaman/washi";
+
+const m = new Model("ProductionRevenue");
+const x = m.integer("x", { lb: 0, ub: 40 });
+const y = m.integer("y", { lb: 0, ub: 40 });
+
+// Maximize revenue: 50*x + 40*y subject to resource capacity
+m.objective(maximize(expr`50 * ${x} + 40 * ${y}`));
+m.constraint(expr`2 * ${x} + 3 * ${y} <= 100`, "resource_limit");
+
+// Or minimize cost:
+// m.objective(minimize(expr`10 * ${x} + 15 * ${y}`));
+```
+
+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`.
+
+---
+
+## 🚀 Solving the Model (`m.solve()` vs. `m.check()`)
+
+WaSHI provides two asynchronous execution entrypoints:
+
+| Method | Return Value | Purpose |
+| :--- | :--- | :--- |
+| **`await m.solve(options?)`** | `Promise<SolverStatus>` | Optimizes the objective (`Minimize` or `Maximize`) subject to all constraints. Populates primal values, objective value, MIP bounds/gaps, and LP duals/slacks. |
+| **`await m.check(options?)`** | `Promise<CheckResult>` | Checks constraint satisfiability without an objective. Returns `{ status, values, conflicts?, unsatCore?, runTime? }` where `values: Record<string, number \| boolean>` contains both numeric and Boolean variable assignments. Ideal for SMT/SAT verification and Z3 `unsatCore` extraction. |
+
+```typescript
+const status = await m.solve({
+  timeLimit: 10.0, // Timeout in seconds
+  mipGap: 0.01,    // Stop within 1% of global optimum
+  outputFlag: false, // Enable/disable solver console logging (HiGHS: outputFlag, GLPK: verbose)
+});
+```
+
+### Solve Options (`SolveOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `solver` | `string` \| `Solver` | Model's solver (`"highs"`) | Registered solver name (e.g. `"highs"`, `"z3"`, `"glpk"`, or custom) or `Solver` instance for this run. |
+| `timeLimit` | `number` | `undefined` | Maximum solve duration in seconds. |
+| `mipGap` / `relGap` | `number` | `undefined` | Relative MIP optimality gap tolerance (e.g. `0.01` for 1%). |
+| `absGap` | `number` | `undefined` | Absolute MIP optimality gap tolerance (HiGHS `mip_abs_gap`). |
+| `presolve` | `"on"` \| `"off"` \| `"choose"` | `"choose"` | Controls solver presolve reduction prior to optimization. |
+| `outputFlag` / `verbose` | `boolean` | `false` | Emits internal solver iteration logs (`outputFlag` for HiGHS, `verbose` for GLPK). |
+| `useWorker` | `boolean` | `true` (browser) | Offloads HiGHS to a dedicated Web Worker in browsers. Set `false` for main-thread execution. |
+| `wasmUrl` | `string` | Auto-resolved | Custom URL to load `highs.wasm` in browser deployments. |
+| `signal` | `AbortSignal` | `undefined` | Cooperative cancellation signal (`AbortController.signal`). |
+| `onProgress` | `(e: SolveProgressEvent) => void` | `undefined` | Callback receiving live solver progress snapshots. |
+
+You can also pass a solver name directly as the first argument: `await m.solve("glpk", { timeLimit: 5 })`.
+
+---
+
+## ⏱️ 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`:
+
+```typescript
+const controller = new AbortController();
+
+// Example: cancel if the user clicks a "Stop" button or after a custom condition
+const status = await m.solve({
+  signal: controller.signal,
+  onProgress: (event) => {
+    console.log(
+      `[${event.elapsedTime.toFixed(1)}s] ` +
+      `Best: ${event.objectiveValue ?? "—"}, ` +
+      `Bound: ${event.objectiveBound ?? "—"}, ` +
+      `Gap: ${event.mipGap !== undefined ? (event.mipGap * 100).toFixed(2) + "%" : "—"}`
+    );
+
+    // Optional: stop early as soon as a good-enough incumbent is found
+    if (event.objectiveValue !== undefined && event.objectiveValue >= 1000) {
+      controller.abort();
+    }
+  },
+});
+
+console.log("Status:", m.status);                   // "Feasible" (if an incumbent was found before abort) or "Unknown"
+console.log("Termination:", m.terminationStatus);   // "Interrupted"
+console.log("Has incumbent:", m.hasPrimalSolution); // true if an incumbent was available
+```
+
+### `SolveProgressEvent` Fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `elapsedTime` | `number` | Elapsed solver time in seconds (optional alias: `elapsedSeconds`). |
+| `phase` | `"simplex" \| "ipm" \| "mip" \| undefined` | Current solver phase when known. |
+| `objectiveValue` | `number \| undefined` | Current best feasible incumbent objective value (MIP). |
+| `objectiveBound` | `number \| undefined` | Current best proven dual / objective bound (MIP). |
+| `relGap` / `mipGap` | `number \| undefined` | Current relative MIP optimality gap (`0.05` = 5%). |
+| `absGap` | `number \| undefined` | Current absolute MIP optimality gap `\|objectiveValue - objectiveBound\|`. |
+| `nodes` | `number \| undefined` | Branch-and-bound nodes explored so far. |
+| `iterations` | `number \| undefined` | Solver iteration count (simplex, IPM, or MIP LP iterations). |
+| `message` | `string \| undefined` | Raw progress line emitted by the solver. |
+
+---
+
+## 📊 Reading Results, Bounds & Solver Status
+
+After solving, query the status, optimal values, and MIP optimality bounds on the `Model`:
+
+```typescript
+const status = await m.solve();
+
+console.log("Status:", m.status);                         // e.g. "Optimal" or "Feasible"
+console.log("Termination Reason:", m.terminationStatus);  // e.g. "Optimal", "TimeLimit", "Interrupted"
+console.log("Has Primal Solution:", m.hasPrimalSolution); // true when x.value / m.objectiveValue are populated
+
+// Objective & MIP Gap Metrics
+console.log("Objective Value:", m.objectiveValue);        // Best primal objective (or null)
+console.log("Objective Bound:", m.objectiveBound);        // Best dual bound (or undefined)
+console.log("Relative Gap:", m.relGap);                   // Relative MIP gap (alias: m.mipGap)
+console.log("Absolute Gap:", m.absGap);                   // |objectiveValue - objectiveBound|
+
+// Individual & Bulk Variable Values
+console.log("x =", x.value, "y =", y.value);
+console.log(m.getValues({ x, y }));                       // { x: ..., y: ... }
+```
+
+### Understanding `m.status` vs. `m.terminationStatus`
+
+When a MIP solver stops early due to a time limit, iteration limit, or `AbortSignal`, two distinct questions matter:
+1. **Is there a usable solution?** (`m.hasPrimalSolution` / `m.status`)
+2. **Why did the solver stop?** (`m.terminationStatus`)
+
+If an integer-feasible incumbent was found before hitting `timeLimit` or `signal.abort()`, WaSHI sets `m.status = "Feasible"` (so you know `x.value` and `m.objectiveValue` hold a valid solution) and sets `m.terminationStatus = "TimeLimit"` (or `"Interrupted"`). If no incumbent was found before stopping, `m.hasPrimalSolution` is `false`, `m.terminationStatus` records why the solver stopped (`"TimeLimit"`, `"IterationLimit"`, or `"Interrupted"`), and `m.status` is `"TimeLimit"`, `"IterationLimit"`, or `"Unknown"` (when aborted via `AbortSignal` without an incumbent).
+
+### All `SolverStatus` Values
+
+| Status | `hasPrimalSolution` | Meaning |
+| :--- | :--- | :--- |
+| `"Optimal"` | `true` | Global optimal solution proven (within tolerances). |
+| `"Feasible"` | `true` | Valid primal solution (incumbent) found, but optimality was not proven before stopping (`terminationStatus` indicates why: `"TimeLimit"`, `"IterationLimit"`, `"Interrupted"`, etc.). |
+| `"Sat"` | `true` | Constraints are satisfiable (`m.check()`). |
+| `"Infeasible"` | `false` | Proven mathematically infeasible; no solution satisfies all constraints. |
+| `"Unsat"` | `false` | Logical/arithmetic constraints are unsatisfiable (`m.check()`). |
+| `"Unbounded"` | `false` | Objective can improve indefinitely without violating constraints. |
+| `"TimeLimit"` | `false` | Time limit reached before finding any feasible primal solution. |
+| `"IterationLimit"` | `false` | Iteration limit reached before finding any feasible primal solution. |
+| `"Unknown"` | `false` | Solver stopped inconclusively without a valid primal solution (including when cancelled via `AbortSignal` before finding an incumbent, where `terminationStatus === "Interrupted"`). |
+| `"Error"` | `false` | Solver encountered an internal execution error. |
+| `"NotSolved"` | `false` | Initial state before solving, or after the model has been mutated. |
+
+---
+
+## 🔄 Model Mutations & Execution Validity
+
+A `Model` instance keeps its solution state synchronized across mutations made through `Model` methods and `Model` / `Var` / `Constraint` property setters:
+
+1. **Post-Solve Mutations Reset Solution State**: Adding variables or constraints, updating the objective (`m.objective(...)`, `m.objectiveExpr = ...`, `m.sense = ...`), or modifying variable bounds/types (`v.lb`, `v.ub`, `v.type`) or constraint properties (`c.lhs`, `c.sense`, `c.rhs`) immediately resets `m.status` to `"NotSolved"`, clears `m.solution` and `m.objectiveValue`, and resets variable/constraint primal and dual values to `null`.
+2. **Mid-Flight Mutations Discard Stale Runs**: If the model is modified via these APIs while an asynchronous `m.solve()` or `m.check()` call is in progress, the stale solver result is discarded, the model remains in `"NotSolved"`, and the in-flight promise rejects with an explicit error.
+3. **Overlapping Executions**: Starting a new `m.solve()` or `m.check()` call supersedes any earlier in-flight call on the same model so out-of-order completions can never overwrite the latest run's state.
+4. **Transactional Batch Edits**: If an invalid edit is rejected (including batch array calls like `m.constraint([...])`), the model rolls back the failed edit without leaving partial entities registered or invalidating an existing valid solution.
+
+> [!NOTE]
+> Renaming already-registered variables or constraints (e.g., reassigning `c.name` after registration) or mutating internal backing collections and ASTs directly (such as `c.lhs.terms`, `m.constraints.splice(...)`, or `BoolOp.children`) is unsupported and will be rejected by model integrity validation on the next solve/check/export call.
+
+---
+
+# Conflict Diagnosis (`unsatCore`) & Solution Validation
+
+When building real-world optimization and configuration systems, two verification questions arise constantly:
+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`).
+
+---
+
+## 🔍 Conflict Diagnosis (`unsatCore` / `conflicts`)
+
+When a model is **Infeasible**, traditional MIP solvers simply report that no solution exists without indicating *which* constraints are contradictory.
+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
+import { Model, expr } from "@ohtaman/washi";
+// Register the Z3 solver plugin
+import "@ohtaman/washi/solvers/z3";
+
+const m = new Model();
+
+const x = m.continuous("reserve", { lb: 0 });
+
+// Add named business requirements
+m.constraint(expr`${x} >= 100`, "minimum_regulatory_reserve");
+m.constraint(expr`${x} <= 50`, "budget_ceiling");
+m.constraint(expr`${x} >= 10`, "routine_operating_cost");
+
+const result = await m.check({ solver: "z3" });
+
+if (result.status === "Unsat") {
+  console.log("Contradictory constraints identified:");
+  console.log(m.conflicts); // or result.conflicts / result.unsatCore / m.unsatCore
+  // Output: ["minimum_regulatory_reserve", "budget_ceiling"]
+}
+```
+
+Notice that `routine_operating_cost` is **not** in the core, because only `minimum_regulatory_reserve` ($x \ge 100$) and `budget_ceiling` ($x \le 50$) directly contradict each other.
+
+> [!IMPORTANT]
+> - **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
+
+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"`:
+
+```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);
+}
+```
+
+---
+
+## ✅ 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
+```
+
+---
+
+# Solvers Overview
+
+WaSHI is designed around a pluggable, decoupled solver architecture. You formulate mathematical models using a unified algebraic API, then solve them with the engine best suited for your problem class.
+
+---
+
+## ⚡ Solvers Matrix & Comparison
+
+| 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`) |
+| **Mock** | **MIT** | *Any* | Ultra-fast unit testing in CI without loading WebAssembly | Built-in |
+
+---
+
+## Selecting a Solver
+
+Specify the solver by name when creating your `Model`:
+
+```typescript
+// 1. Built-in HiGHS (default)
+const m1 = new Model({ solver: "highs" });
+
+// 2. Z3 SMT solver
+import "@ohtaman/washi/solvers/z3";
+const m2 = new Model({ solver: "z3" });
+
+// 3. GLPK solver
+import "@ohtaman/washi/solvers/glpk";
+const m3 = new Model({ solver: "glpk" });
+```
+
+---
+
+## Solver Guides
+
+- [HiGHS Guide](docs/solvers/highs.md): Web Worker multithreading, MIP tolerances, and 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.
+
+---
+
+# 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).
+
+---
+
+## Key Features in WaSHI
+
+- **Built-in & Zero-Config**: Bundled directly with `@ohtaman/washi`. No separate peer dependency or compilation required.
+- **Permissive MIT License**: 100% commercially friendly.
+- **Web Worker Multithreading**: Automatically offloads intensive solving to background Web Workers in browser environments to avoid freezing the UI thread.
+- **Warm-Start Support (`initialValue`)**: Supports passing variable primal initial value hints (`initialValue`) to HiGHS `setSolution` for warm starting.
+- **Fast WASM Execution**: Emscripten-compiled 32-bit WASM runs at near-native speed.
+
+---
+
+## Supported Problem Classes
+
+### 1. Linear Programming (LP)
+Solves continuous problems via Primal and Dual Simplex algorithms or Interior Point (IPM) methods. After solving, you can inspect constraint shadow prices (`c.dual`), slacks (`c.slack`), and variable reduced costs (`v.reducedCost`):
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const model = new Model({ solver: "highs" });
+const x = model.continuous("x", { lb: 0 });
+const y = model.continuous("y", { lb: 0 });
+model.objective(maximize(expr`10 * ${x} + 6 * ${y}`));
+model.constraint(expr`${x} + ${y} <= 100`, "cap");
+await model.solve();
+```
+
+### 2. Mixed-Integer Linear Programming (MIP)
+Solves discrete problems using Branch-and-Bound and cutting plane techniques:
+
+```typescript
+const count = model.integer("count", { lb: 0, ub: 50 });
+```
+
+### 3. Convex Quadratic Programming (QP)
+Solves quadratic objective functions subject to linear constraints:
+
+```typescript
+// Minimize risk/variance uniformly using expr:
+model.objective(minimize(expr`0.5 * ${x}^2 + 0.5 * ${y}^2`));
+
+// Or programmatically with .mul():
+// const quadObj = x.mul(x).mul(0.5).add(y.mul(y).mul(0.5));
+// model.objective(minimize(quadObj));
+```
+
+---
+
+## Solver Options
+
+Pass solver options into `model.solve()`:
+
+```typescript
+const controller = new AbortController();
+
+await model.solve({
+  timeLimit: 60.0,       // Maximum solve time in seconds
+  mipGap: 0.001,         // Terminate when within 0.1% of global optimality (alias: relGap)
+  absGap: 1.0,           // Absolute MIP optimality gap tolerance
+  presolve: "on",        // Presolve control ("on" | "off" | "choose")
+  outputFlag: true,      // Output internal simplex / branch-and-bound logs (output_flag)
+  signal: controller.signal,
+  onProgress: (ev) => {
+    console.log(`Elapsed: ${ev.elapsedTime.toFixed(1)}s, Best: ${ev.objectiveValue}`);
+  },
+});
+```
+
+---
+
+## Worker & WASM Configuration in Browsers
+
+By default in browsers, WaSHI spawns a dedicated Web Worker to execute HiGHS in the background so UI rendering stays responsive and `onProgress` / `AbortSignal` work seamlessly.
+
+If you need to run synchronously on the main thread (or in environments where Web Workers are prohibited), pass `useWorker: false` to `model.solve()` or instantiate `HighsSolver`:
+
+```typescript
+import { Model, HighsSolver } from "@ohtaman/washi";
+
+// Option 1: Per solve call
+await model.solve({ useWorker: false });
+
+// Option 2: When instantiating the solver
+const syncModel = new Model({
+  solver: new HighsSolver({ useWorker: false }),
+});
+```
+
+---
+
+# 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.
+
+---
+
+## Installation
+
+Z3 is provided as an optional peer dependency:
+
+```bash
+npm install z3-solver
+```
+
+---
+
+## When to Use Z3?
+
+1. **Unsat Core Conflict Diagnosis**:
+   When your MIP model is infeasible and you need to isolate which constraints are contradictory.
+2. **Boolean / Logical Formulations**:
+   When solving problems containing complex logical relations (implications, XOR, nested Boolean expressions).
+3. **Exact Mathematical Guarantees**:
+   Z3 can perform exact rational arithmetic without floating-point inaccuracies.
+
+---
+
+## Basic Usage
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+const model = new Model({ solver: "z3" });
+
+const x = model.integer("x", { lb: 0, ub: 10 });
+const y = model.integer("y", { lb: 0, ub: 10 });
+
+model.constraint(expr`${x} + ${y} == 15`, "sum_15");
+model.constraint(expr`${x} >= 8`, "x_at_least_8");
+
+await model.solve();
+console.log(`x = ${x.value}, y = ${y.value}`);
+```
+
+---
+
+## Unsat Core Extraction (`model.check()`)
+
+Use `await model.check()` with Z3 to verify satisfiability and extract the conflicting subset of named constraints (`conflicts` / `unsatCore`) when a model is unsatisfiable:
+
+```typescript
+const model = new Model({ solver: "z3" });
+const a = model.continuous("a");
+
+model.constraint(expr`${a} >= 10`, "req_A");
+model.constraint(expr`${a} <= 5`, "req_B");
+
+const result = await model.check();
+
+if (result.status === "Unsat") {
+  console.log("Conflicting constraints:", result.conflicts); // or model.conflicts / model.unsatCore
+  // ["req_A", "req_B"]
+}
+```
+
+---
+
+## Browser Security Note
+
+In browser environments, the Z3 WASM engine relies on pthreads and `SharedArrayBuffer`, which require cross-origin isolation headers (`COOP` / `COEP`). See the [Cross-Origin Isolation Guide](docs/getting-started/cross-origin.md) for detailed setup.
+
+## Runtime Failures and Thread Cleanup
+
+If a Z3 worker encounters a fatal runtime error, pending operations on that instance reject with an error and the broken runtime is invalidated; subsequent `solve()` or `check()` calls automatically initialize a fresh Z3 runtime rather than misclassifying failures as `Sat` or `Unsat`.
+
+To explicitly terminate Z3 pthread workers when tearing down a browser view or worker pool, call `killZ3Threads()` from `@ohtaman/washi/solvers/z3`.
+
+---
+
+# GLPK Solver Engine
+
+The **GNU Linear Programming Kit (GLPK)** is a long-standing, robust simplex and interior-point solver package intended for solving large-scale linear programming (LP) and mixed integer programming (MIP).
+
+---
+
+## Installation
+
+GLPK is provided as an optional peer dependency via `glpk.js`:
+
+```bash
+npm install glpk.js
+```
+
+---
+
+## Licensing Consideration (GPL-3.0)
+
+GLPK is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.
+
+- Because WaSHI is MIT-licensed, `glpk.js` is **never bundled statically** in the core package.
+- It is dynamically imported only if you explicitly register or invoke `@ohtaman/washi/solvers/glpk`.
+- Ensure your project's distribution requirements comply with the GPL-3.0 license when shipping products that bundle GLPK.
+
+---
+
+## Basic Usage
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/glpk";
+
+const model = new Model({ solver: "glpk" });
+
+const x = model.continuous("x", { lb: 0, ub: 10 });
+const y = model.continuous("y", { lb: 0, ub: 20 });
+
+model.objective(maximize(expr`3 * ${x} + 2 * ${y}`));
+model.constraint(expr`${x} + ${y} <= 15`, "cap");
+
+await model.solve();
+
+console.log("GLPK Status:", model.status);
+console.log("Objective:", model.objectiveValue);
+```
+
+---
+
+## Result Semantics & Status Mapping
+
+### Solver Statuses
+GLPK return codes are mapped strictly to WaSHI `SolverStatus`:
+- `GLP_OPT` (5) $\to$ `"Optimal"`
+- `GLP_FEAS` (2) $\to$ `"Feasible"` (feasible MIP incumbent found)
+- `GLP_INFEAS` (3) / `GLP_NOFEAS` (4) $\to$ `"Infeasible"`
+- `GLP_UNBND` (6) $\to$ `"Unbounded"`
+- `GLP_UNDEF` (1) and unrecognized/missing statuses $\to$ `"Unknown"` (never misclassified as `"Optimal"`)
+
+### Solution Availability
+- Variable values (`model.values`, `var.value`) and objective values (`model.objectiveValue`) are exposed **only** when a valid primal solution is available (`"Optimal"` or `"Feasible"`).
+- For unsuccessful or non-optimal solves (`Infeasible`, `Unbounded`, `Unknown`, `Error`), `model.objectiveValue` is `null` and variable values remain `null` without fabricating fake all-zero solutions.
+
+### Differences Between LP and MIP
+- **Linear Programming (LP)**: Solved using the simplex algorithm. Dual values (shadow prices via `constraint.dual`) and slacks are populated for optimal solutions.
+- **Mixed-Integer Programming (MIP)**: Solved using the branch-and-cut algorithm. Produces integer-feasible primal variable solutions; dual values are mathematically undefined for discrete optimization and omitted.
+
+---
+
+# WaSHI Custom Solver Developer Guide
+
+This guide describes how to build, test, and distribute custom solver plugins for **WaSHI** (`@ohtaman/washi`).
+
+WaSHI features a pluggable, decoupled solver architecture. Core `@ohtaman/washi` bundles only the zero-config HiGHS WASM engine and a Mock solver. Any third-party solver—whether implemented in WebAssembly, native C++, a Web Worker, or an external cloud REST/RPC backend—can be registered and used through the unified `Model` API.
+
+---
+
+## 1. Pluggable Solvers Architecture Overview
+
+```mermaid
+graph TD
+    A[WaSHI Model] --> B[Solver Registry Map Symbol.for]
+    B --> C[HiGHS WASM Engine Core]
+    B --> D[Mock Solver Core]
+    B --> E[GLPK Plugin @ohtaman/washi/solvers/glpk]
+    B --> F[Z3 SMT Plugin @ohtaman/washi/solvers/z3]
+    B --> G[Your Custom Solver Plugin]
+```
+
+### Key Architectural Characteristics
+1. **Unified Global Registry**: The solver registry is backed by `Symbol.for("washi.solverRegistry")` on `globalThis`. This ensures that even across different ESM chunks, dynamic imports, or `<script>` tags, every bundle accesses the identical solver map.
+2. **Behavioral Symmetry**: Node.js and browser environments share identical error messages, solver naming, and capability handling.
+3. **Decoupled Bundling**: Core WaSHI does not import optional or custom plugins. A plugin only registers itself when explicitly imported.
+
+---
+
+## 2. API Contracts & TypeScript Interfaces
+
+All custom solvers must implement the `Solver` interface defined in `@ohtaman/washi`:
+
+```typescript
+import {
+  generateLpString,
+  buildLpSymbolMaps,
+  isLpExportResult,
+  sanitizeIdentifier,
+  type Solver,
+  type SolverOptions,
+  type SolverResult,
+  type SolverCheckResult,
+  type SolverCapabilities,
+  type SolveModelData,
+  type CheckModelData,
+  type LogicalConstraintItem,
+  type LpModelData,
+  type LpExportResult,
+  type LpSymbolMaps,
+  type SolverStatus,
+  type TerminationStatus,
+  type SolveProgressEvent,
+} from "@ohtaman/washi";
+```
+
+### The `Solver` Interface
+
+```typescript
+export interface Solver {
+  /** Unique human-readable name of the solver (e.g. "GLPK", "AcmeCloudSolver") */
+  readonly name: string;
+
+  /** Solver version string (e.g. "1.2.0") */
+  readonly version?: string;
+
+  /** Capability flags declaring which problem classes the solver supports */
+  readonly capabilities?: SolverCapabilities;
+
+  /**
+   * Main solve method for LP, MIP, QP, and SMT optimization models.
+   *
+   * @param modelData Typed in-memory model structure (variables, constraints, objective, sense, boolVars, logicalConstraints)
+   * @param options Runtime execution options (timeLimit, mipGap, verbose, signal, onProgress, etc.)
+   */
+  solve(
+    modelData: SolveModelData,
+    options?: SolverOptions
+  ): Promise<SolverResult>;
+
+  /**
+   * Optional check method for Pure SAT / SMT or feasibility checking without an objective.
+   *
+   * @param modelData Objective-free in-memory model structure (variables, boolVars, constraints, logicalConstraints)
+   * @param options Runtime execution options
+   */
+  check?(
+    modelData: CheckModelData,
+    options?: SolverOptions
+  ): Promise<SolverCheckResult>;
+}
+```
+
+### `CheckModelData` & `SolveModelData`
+
+`Model.solve()` and `Model.check()` pass the structured model directly to your adapter without serializing an LP string upfront:
+
+```typescript
+export interface CheckModelData {
+  /** Model name */
+  name?: string;
+  /** Decision variables registered in the model */
+  variables: Var[];
+  /** Propositional Boolean variables registered in the model */
+  boolVars?: BoolVar[];
+  /** Linear arithmetic constraints registered in the model */
+  constraints: Constraint[];
+  /** Logical / SMT constraints registered in the model */
+  logicalConstraints?: LogicalConstraintItem[];
+}
+
+export interface SolveModelData extends CheckModelData {
+  /** Optimization direction ("Minimize" | "Maximize") */
+  sense: OptimizationSense;
+  /** Linear or quadratic objective expression */
+  objective: LinExpr | QuadExpr;
+}
+```
+
+### `SolverCapabilities`
+
+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
+- `supportsWarmStart !== true` when any variable has a primal `initialValue` set.
+
+```typescript
+export interface SolverCapabilities {
+  /** Supports mixed-integer programming (integer/binary variables) */
+  supportsMIP?: boolean;
+
+  /** Supports quadratic objectives (QP: x^T Q x + c^T x) */
+  supportsQP?: boolean;
+
+  /** Supports second-order cone or quadratic constraints */
+  supportsQCQP?: boolean;
+
+  /** Supports satisfiability modulo theories / boolean logic constraints */
+  supportsSMT?: boolean;
+
+  /** Supports extracting an unsatisfiable core (conflicting constraint subset) */
+  supportsUnsatCore?: boolean;
+
+  /** Supports primal initial values / MIP warm starts (Var.initialValue) */
+  supportsWarmStart?: boolean;
+}
+```
+
+### `SolverOptions` & `SolveProgressEvent`
+
+Runtime options passed to `solve` and `check` include cancellation and progress hooks (note that the routing `solver` field from `SolveOptions` is stripped before options are passed to your adapter):
+
+```typescript
+export interface SolverOptions {
+  /** Time limit in seconds */
+  timeLimit?: number;
+
+  /** Relative MIP optimality gap tolerance */
+  mipGap?: number;
+
+  /** Enable solver console logging */
+  verbose?: boolean;
+
+  /** Cooperative cancellation signal; when aborted, return terminationStatus: "Interrupted" */
+  signal?: AbortSignal;
+
+  /** Progress callback invoked with normalized SolveProgressEvent snapshots */
+  onProgress?: (progress: SolveProgressEvent) => void;
+
+  /** Additional solver-specific options */
+  [key: string]: any;
+}
+```
+
+### Optional LP Serialization & Symbol-Mapping Helpers
+
+Solvers that consume structured JS/WASM data (such as `GLPKSolver` and `Z3Solver`) work directly with `SolveModelData` / `CheckModelData`.
+If your adapter targets a backend that requires CPLEX/HiGHS LP text or restricted identifier syntax, WaSHI exports opt-in helpers:
+
+- `generateLpString(modelData): LpExportResult` — serializes `modelData` into a CPLEX LP format string (`lpString`) along with collision-safe symbol lookup maps (`nameToVar`, `nameToConstraint`).
+- `buildLpSymbolMaps(modelData): LpSymbolMaps` — builds collision-safe sanitized symbol maps (`nameToVar`, `varToName`, `nameToConstraint`, `constraintToName`) without serializing an LP string.
+- `isLpExportResult(value): value is LpExportResult` — runtime type guard for `LpExportResult` (useful when supporting legacy 3-argument `solve(modelData, lpResult, options)` overloads).
+- `sanitizeIdentifier(raw, fallbackPrefix = "x", id = 0)` — sanitizes an arbitrary display name into a valid LP identifier.
+
+```typescript
+export interface LpExportResult {
+  /** Standard CPLEX/HiGHS LP formatted string */
+  lpString: string;
+
+  /** Map translating sanitized LP variable identifiers back to WaSHI Var objects */
+  nameToVar: Map<string, Var>;
+
+  /** Map translating sanitized LP constraint identifiers back to WaSHI Constraint objects */
+  nameToConstraint: Map<string, Constraint>;
+}
+```
+
+### `SolverResult` Normalization & Identity Decoding
+
+The `solve` method must return normalized results keyed by the model's canonical variable/constraint names (`v.name`, `bv.name`, `c.name`). Adapters that use `generateLpString(modelData)` or `buildLpSymbolMaps(modelData)` for an LP backend must translate sanitized LP identifiers back to canonical model names using `nameToVar` and `nameToConstraint`:
+
+```typescript
+export interface SolverResult {
+  /** Standardized status string */
+  status: SolverStatus;
+
+  /** Exact termination reason independent of whether a feasible incumbent is available (defaults to status) */
+  terminationStatus?: TerminationStatus;
+
+  /** Whether a feasible primal solution / incumbent is available (inferred from status/values if omitted) */
+  hasPrimalSolution?: boolean;
+
+  /** Optimal or best objective value (null if no primal solution is available) */
+  objectiveValue: number | null;
+
+  /** Best proven dual/objective bound when provided by the solver */
+  objectiveBound?: number;
+
+  /** Relative MIP optimality gap when provided by the solver */
+  relGap?: number;
+
+  /** Alias for relGap: relative MIP optimality gap when provided by the solver */
+  mipGap?: number;
+
+  /** Absolute MIP optimality gap |objectiveValue - objectiveBound| (computed automatically when both are finite) */
+  absGap?: number;
+
+  /** Variable primal values keyed by canonical variable name (non-finite values are ignored) */
+  values: Record<string, number>;
+
+  /** Propositional Boolean variable assignments keyed by BoolVar name (optional, SMT/SAT) */
+  boolValues?: Record<string, boolean>;
+
+  /** Variable reduced costs (optional, LP only) */
+  reducedCosts?: Record<string, number>;
+
+  /** Constraint dual values / shadow prices (optional, LP only) */
+  duals?: Record<string, number>;
+
+  /** Constraint slack values (optional) */
+  slacks?: Record<string, number>;
+
+  /** Solve execution duration in seconds */
+  runTime?: number;
+
+  /** Diagnostic solver logs / text outputs */
+  logs?: string[];
+
+  /** Raw solver response object for inspection */
+  raw?: any;
+}
+```
+
+#### Standardized `SolverStatus` Values
+- `"Optimal"`: Global optimal solution found (for MIP within tolerance, for LP proven optimal).
+- `"Feasible"`: Feasible solution found, but optimality not yet proven (e.g., hit time limit with an incumbent).
+- `"Infeasible"`: Model is proven mathematically infeasible.
+- `"Unbounded"`: Model objective is unbounded.
+- `"TimeLimit"`: Solver terminated due to `timeLimit` without proof of optimality.
+- `"IterationLimit"`: Solver terminated due to iteration limit.
+- `"Sat"` / `"Unsat"`: Satisfiable / unsatisfiable status returned by `check()` or SMT solvers.
+- `"Error"` / `"NotSolved"` / `"Unknown"`: Error, not yet solved, or unrecognized status. **Never convert Unknown/Error to Optimal.**
+
+---
+
+## 3. Step-by-Step Implementation Tutorials
+
+### Tutorial A: In-House Cloud REST Solver Adapter
+
+Here is a complete, production-ready custom solver connecting to an HTTP microservice that accepts LP format strings on demand via `generateLpString(modelData)`:
+
+```typescript
+import {
+  generateLpString,
+  registerSolver,
+  type Solver,
+  type SolverOptions,
+  type SolverResult,
+  type SolverStatus,
+  type SolveModelData,
+} from "@ohtaman/washi";
+
+export interface CloudSolverConfig extends SolverOptions {
+  endpoint?: string;
+  apiKey?: string;
+}
+
+export class CloudSolver implements Solver {
+  public readonly name = "CloudSolver";
+  public readonly version = "1.0.0";
+  public readonly capabilities = {
+    supportsMIP: true,
+    supportsQP: false,
+  };
+
+  private endpoint: string;
+  private apiKey: string;
+
+  constructor(config: CloudSolverConfig = {}) {
+    this.endpoint = config.endpoint || "https://solver.mycompany.internal/v1/solve";
+    this.apiKey = config.apiKey || "";
+  }
+
+  async solve(
+    modelData: SolveModelData,
+    options: SolverOptions = {}
+  ): Promise<SolverResult> {
+    const startTime = performance.now();
+    const { lpString, nameToVar, nameToConstraint } = generateLpString(modelData);
+
+    let payload: any;
+    try {
+      const response = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+        },
+        body: JSON.stringify({
+          lp: lpString,
+          timeLimit: options.timeLimit,
+          mipGap: options.mipGap,
+        }),
+        signal: options.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`[CloudSolver] Server returned HTTP ${response.status}: ${await response.text()}`);
+      }
+
+      payload = await response.json();
+    } catch (err: any) {
+      if (options.signal?.aborted || err?.name === "AbortError") {
+        return {
+          status: "Unknown",
+          terminationStatus: "Interrupted",
+          objectiveValue: null,
+          values: {},
+          runTime: (performance.now() - startTime) / 1000,
+        };
+      }
+      throw err;
+    }
+
+    const runTime = (performance.now() - startTime) / 1000;
+
+    const values: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.values || {}) as Record<string, number>)) {
+      values[nameToVar.get(k)?.name ?? k] = val;
+    }
+    const duals: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.duals || {}) as Record<string, number>)) {
+      duals[nameToConstraint.get(k)?.name ?? k] = val;
+    }
+    const slacks: Record<string, number> = Object.create(null);
+    for (const [k, val] of Object.entries((payload.slacks || {}) as Record<string, number>)) {
+      slacks[nameToConstraint.get(k)?.name ?? k] = val;
+    }
+
+    const statusMap: Record<string, SolverStatus> = {
+      OPTIMAL: "Optimal",
+      FEASIBLE: "Feasible",
+      INFEASIBLE: "Infeasible",
+      UNBOUNDED: "Unbounded",
+      TIME_LIMIT: "TimeLimit",
+      TIMELIMIT: "TimeLimit",
+      ITERATION_LIMIT: "IterationLimit",
+      ERROR: "Error",
+      NOT_SOLVED: "NotSolved",
+      SAT: "Sat",
+      UNSAT: "Unsat",
+    };
+    const rawStatus: SolverStatus = statusMap[String(payload.status).toUpperCase()] ?? "Unknown";
+    const hasIncumbent =
+      (typeof payload.objectiveValue === "number" && Number.isFinite(payload.objectiveValue)) ||
+      Object.values(values).some((val) => typeof val === "number" && Number.isFinite(val));
+    const isLimitStop = rawStatus === "TimeLimit" || rawStatus === "IterationLimit";
+    const status: SolverStatus = isLimitStop && hasIncumbent ? "Feasible" : rawStatus;
+
+    return {
+      status,
+      terminationStatus: rawStatus,
+      objectiveValue: payload.objectiveValue ?? null,
+      values,
+      duals,
+      slacks,
+      runTime: payload.solveDuration || runTime,
+      logs: payload.logs || [],
+      raw: payload,
+    };
+  }
+}
+
+// Auto-register so `import "my-cloud-solver"` enables `solver: "cloud"`
+export function registerCloudSolver(): void {
+  registerSolver("cloud", (opts) => new CloudSolver(opts));
+}
+registerCloudSolver();
+```
+
+---
+
+### Tutorial B: Registering and Using the Custom Solver
+
+Once implemented, the custom solver can be selected in three different ways:
+
+#### Option 1: By Registered Name String
+```typescript
+import { Model } from "@ohtaman/washi";
+import "./cloud-solver.js"; // Auto-registers "cloud"
+
+const model = new Model({ name: "SupplyChain", solver: "cloud" });
+// Or model.solve("cloud")
+```
+
+#### Option 2: By Passing the Solver Instance Directly
+```typescript
+import { Model } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+const customInstance = new CloudSolver({
+  endpoint: "https://dedicated-gpu-cluster.internal/solve",
+  apiKey: "secret-token",
+});
+
+const model = new Model({ name: "FacilityLocation", solver: customInstance });
+const status = await model.solve();
+```
+
+#### Option 3: Setting Global Default Solver
+```typescript
+import { setDefaultSolver, Model } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+setDefaultSolver(() => new CloudSolver());
+
+// All subsequent models use CloudSolver by default
+const model = new Model("DefaultedModel");
+```
+
+---
+
+## 4. Distribution: Packaging as a Plugin
+
+To publish your solver as an independent npm package (e.g. `@my-org/washi-solver-cplex`):
+
+### 1. `package.json` Exports Structure
+```json
+{
+  "name": "@my-org/washi-solver-cplex",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/lib/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/lib/index.js",
+      "default": "./dist/lib/index.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/browser/index.js",
+      "default": "./dist/browser/index.js"
+    },
+    "./browser/index.min.js": "./dist/browser/index.min.js"
+  },
+  "peerDependencies": {
+    "@ohtaman/washi": ">=0.1.0"
+  }
+}
+```
+
+### 2. Browser IIFE Build
+When building the browser standalone script (`.min.js`), configure your bundler (Vite or Rollup) to:
+- Output format: `iife`
+- Global name: `WashiCplex`
+- Rely on `Symbol.for("washi.solverRegistry")` so that `<script src="washi.min.js"></script><script src="washi-cplex.min.js"></script>` automatically connects.
+
+---
+
+## 5. Testing Your Custom Solver
+
+You can test your solver using Vitest or Jest without bundling:
+
+```typescript
+import { describe, it, expect, vi } from "vitest";
+import { Model, expr, maximize, registerSolver, listAvailableSolvers } from "@ohtaman/washi";
+import { CloudSolver } from "./cloud-solver.js";
+
+describe("Custom Solver Integration", () => {
+  it("registers in available solvers list", () => {
+    registerSolver("cloud-test", () => new CloudSolver());
+    expect(listAvailableSolvers()).toContain("cloud-test");
+  });
+
+  it("propagates primal values and duals into WaSHI Model", async () => {
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          status: "OPTIMAL",
+          objectiveValue: 34,
+          values: { x: 2, y: 10 },
+          duals: { budget: 2 },
+        }),
+        { status: 200, headers: { "Content-Type": "application/json" } }
+      )
+    );
+
+    try {
+      const model = new Model({ solver: new CloudSolver() });
+      const x = model.continuous("x", { lb: 0, ub: 10 });
+      const y = model.continuous("y", { lb: 0, ub: 10 });
+      model.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
+      model.constraint(expr`${x} + ${y} <= 12`, "budget");
+
+      const status = await model.solve();
+      expect(status).toBe("Optimal");
+      expect(x.value).toBe(2);
+      const c1 = model.getConstraintByName("budget");
+      expect(c1?.dual).toBe(2);
+    } finally {
+      fetchSpy.mockRestore();
+    }
+  });
+});
+```
+
+---
+
+# 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/).
+
+## 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) |
+
+## Find by WaSHI API (Reverse Index)
+
+Looking for a specific modeling method or solver capability? Jump straight to the example that demonstrates it:
+
+| Feature / API | Description | Example Page | Node.js Source |
+| :--- | :--- | :--- | :--- |
+| ``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) |
+| `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.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) |
+| `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
+
+All standalone scripts are located in [`examples/node/`](https://github.com/ohtaman/washi/tree/main/examples/node):
+
+```bash
+npx tsx examples/node/01-production-planning.ts
+npx tsx examples/node/02-knapsack-problem.ts
+npx tsx examples/node/03-portfolio-qp.ts
+npx tsx examples/node/04-smt-security-rules.ts
+npx tsx examples/node/05-unsat-core-diagnosis.ts
+npx tsx examples/node/07-hybrid-smt-mip.ts
+npx tsx examples/node/08-glpk-solver-plugin.ts
+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
+```
+
+---
+
+# Production Planning (LP / MIP)
+
+| 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> |
+
+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).
+
+## Mathematical Formulation
+
+Let $x$ be the number of chairs and $y$ be the number of tables.
+
+$$\begin{aligned}
+\text{Maximize} \quad & 45x + 80y & (\text{Profit}) \\
+\text{Subject to} \quad & 5x + 20y \le 400 & (\text{Mahogany Wood limit}) \\
+& 10x + 15y \le 450 & (\text{Carpentry Labor limit}) \\
+& x, y \ge 0, \quad x, y \in \mathbb{Z} & (\text{Integer Quantities})
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+async function runProductionOptimization() {
+  const m = new Model("FactoryProduction");
+
+  // Decision variables: non-negative integer quantities
+  const chairs = m.integer("chairs", { lb: 0 });
+  const tables = m.integer("tables", { lb: 0 });
+
+  // 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");
+
+  const status = await m.solve();
+
+  console.log(`Status: ${status}`);
+  console.log(`Optimal Profit: $${m.objectiveValue}`);
+  console.log(`Chairs: ${chairs.value}, Tables: ${tables.value}`);
+}
+
+runProductionOptimization();
+```
+
+---
+
+# 0-1 Knapsack Problem (Binary MIP)
+
+| 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> |
+
+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.
+
+## Mathematical Formulation
+
+Let $x_i \in \{0, 1\}$ be binary decision variables indicating whether item $i$ is selected ($x_i = 1$) or not ($x_i = 0$):
+
+$$\begin{aligned}
+\text{Maximize} \quad & \sum_{i} v_i x_i & (\text{Total Value}) \\
+\text{Subject to} \quad & \sum_{i} w_i x_i \le W & (\text{Weight Capacity}) \\
+& x_i \in \{0, 1\} & (\text{Binary Decisions})
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, maximize, dot, expr } from "@ohtaman/washi";
+
+async function solveKnapsack() {
+  const m = new Model("Knapsack");
+
+  const items = [
+    { name: "Laptop",   weight: 3, value: 50 },
+    { name: "Camera",   weight: 2, value: 40 },
+    { name: "Drone",    weight: 4, value: 65 },
+    { name: "FirstAid", weight: 1, value: 15 },
+    { name: "Tent",     weight: 5, value: 70 },
+  ];
+  const maxCapacity = 7; // kg
+
+  // Create binary variables: x[name] (0 or 1)
+  const x = m.binary(items.map((it) => it.name));
+
+  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)));
+
+  // Weight capacity constraint using natural expr and constraint() syntax
+  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));
+}
+
+solveKnapsack();
+```
+
+---
+
+# Transportation & Allocation Network (LP)
+
+| 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> |
+
+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.
+
+This example demonstrates how to construct a **2D matrix of decision variables** using `m.continuous(factories, stores)` and write aggregated constraints declaratively via `dot()` and `m.constraint(expr`...`)`.
+
+## Problem Inputs
+
+We have **3 factories** (`Tokyo`, `Nagoya`, `Osaka`) shipping to **4 regional stores** (`North`, `East`, `West`, `South`):
+
+| Factory \ Store | North ($/unit) | East ($/unit) | West ($/unit) | South ($/unit) | Supply Capacity |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Tokyo** | $4 | $2 | $7 | $8 | **120** units |
+| **Nagoya** | $6 | $4 | $3 | $5 | **100** units |
+| **Osaka** | $9 | $7 | $2 | $3 | **80** units |
+| **Store Demand** | **70** units | **90** units | **60** units | **60** units | Total: 280 / 300 |
+
+## Mathematical Formulation
+
+Let $x_{f, s} \ge 0$ be the quantity shipped from factory $f \in F$ to store $s \in S$, and $c_{f, s}$ be the unit shipping cost.
+
+$$\begin{aligned}
+\text{Minimize} \quad & \sum_{f \in F} \sum_{s \in S} c_{f,s} \, x_{f,s} \\
+\text{Subject to} \quad & \sum_{s \in S} x_{f,s} \le \text{Supply}_f \quad \forall f \in F \quad (\text{Factory capacity}) \\
+& \sum_{f \in F} x_{f,s} \ge \text{Demand}_s \quad \forall s \in S \quad (\text{Store demand}) \\
+& x_{f,s} \ge 0 \quad \forall f \in F, s \in S
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+
+const factories = ["Tokyo", "Nagoya", "Osaka"] as const;
+const stores = ["North", "East", "West", "South"] as const;
+
+const shippingCost = {
+  Tokyo:  { North: 4, East: 2, West: 7, South: 8 },
+  Nagoya: { North: 6, East: 4, West: 3, South: 5 },
+  Osaka:  { North: 9, East: 7, West: 2, South: 3 },
+};
+
+const supplies = { Tokyo: 120, Nagoya: 100, Osaka: 80 };
+const demands = { North: 70, East: 90, West: 60, South: 60 };
+
+async function runTransportation() {
+  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)));
+
+  // 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}`
+    );
+  }
+
+  // 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 status = await m.solve();
+  console.log(`Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
+  for (const f of factories) {
+    const routes = stores
+      .map((s) => `${s}:${Math.round(ship[f][s].value ?? 0)}`)
+      .join(", ");
+    console.log(`  ${f.padEnd(7)} -> ${routes}`);
+  }
+}
+
+runTransportation();
+```
+
+---
+
+# 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> |
+
+When solving a Linear Programming model, the optimal variable values (`var.value`) are only half the story. In practice, decision-makers need to know:
+
+1. **Bottlenecks (`constr.dual` — Shadow Price):** Which minimum requirements are actively driving up the total cost, and by how much per unit?
+2. **Surpluses (`constr.slack`):** Which constraints have room to spare?
+3. **Reduced Costs (`var.reducedCost`):** For items not selected in the optimal plan, how much cheaper would they need to become before entering the solution?
+
+## Problem Inputs
+
+We choose daily servings ($0 \le x_i \le 4$) among 6 food items to meet 4 daily nutritional minimums (`Calories >= 2000 kcal`, `Protein >= 105 g`, `Calcium >= 1000 mg`, `Iron >= 18 mg`) at minimum cost:
+
+| Food Item | Cost / Serving | Calories (kcal) | Protein (g) | Calcium (mg) | Iron (mg) | Max Servings |
+| :--- | :---: | :---: | :---: | :---: | :---: | :---: |
+| **Oats** | $0.60 | 150 | 5 | 20 | 1.8 | 4.0 |
+| **Chicken** | $2.40 | 220 | 32 | 15 | 1.2 | 4.0 |
+| **Eggs** | $0.80 | 140 | 12 | 50 | 1.7 | 4.0 |
+| **Milk** | $0.90 | 120 | 8 | 280 | 0.1 | 4.0 |
+| **Spinach** | $1.50 | 40 | 4 | 120 | 3.5 | 4.0 |
+| **Salmon** | $3.60 | 200 | 25 | 20 | 0.8 | 4.0 |
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, minimize, dot, expr } from "@ohtaman/washi";
+
+const foods = [
+  { name: "Oats",    cost: 0.60, calories: 150, protein: 5,  calcium: 20,  iron: 1.8 },
+  { name: "Chicken", cost: 2.40, calories: 220, protein: 32, calcium: 15,  iron: 1.2 },
+  { name: "Eggs",    cost: 0.80, calories: 140, protein: 12, calcium: 50,  iron: 1.7 },
+  { name: "Milk",    cost: 0.90, calories: 120, protein: 8,  calcium: 280, iron: 0.1 },
+  { name: "Spinach", cost: 1.50, calories: 40,  protein: 4,  calcium: 120, iron: 3.5 },
+  { name: "Salmon",  cost: 3.60, calories: 200, protein: 25, calcium: 20,  iron: 0.8 },
+];
+
+async function runDietSensitivity() {
+  const m = new Model("DietSensitivity");
+
+  // Continuous servings per day (0 to 4 servings max per food)
+  const srv = m.continuous(foods.map((f) => f.name), { lb: 0, ub: 4 });
+
+  const costs = Object.fromEntries(foods.map((f) => [f.name, f.cost]));
+  const cals  = Object.fromEntries(foods.map((f) => [f.name, f.calories]));
+  const prots = Object.fromEntries(foods.map((f) => [f.name, f.protein]));
+  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)));
+
+  // 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 status = await m.solve();
+
+  console.log(`Status: ${status}, Minimum Daily Cost: $${m.objectiveValue?.toFixed(2)}`);
+  console.log("--- Food Servings & Reduced Costs ---");
+  for (const f of foods) {
+    const v = srv[f.name];
+    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)}`);
+    }
+  }
+}
+
+runDietSensitivity();
+```
+
+## Interpretation of Results
+
+- **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.
+
+---
+
+# Staff Shift Scheduling & Conflict Diagnosis (MIP + Z3)
+
+| 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> |
+
+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`.
+
+This example demonstrates a practical production workflow:
+1. **Try HiGHS MIP Optimization First:** Solve the shift model under the given vacation requests and operational constraints.
+2. **Accept Solution if Optimal:** If a feasible roster is found, display the schedule and minimized payroll cost without unnecessary diagnostic overhead.
+3. **Diagnose with Z3 `unsatCore` Only When Infeasible:** If HiGHS reports `Infeasible`, diagnose the **exact same model and constraints** with Z3 to isolate the conflicting constraint subset (`unsatCore`), pinpointing which day's coverage rules and which staff requests collided.
+
+> [!IMPORTANT]
+> **Vacation Requests are Hard Constraints:**
+> In this model, vacation requests are enforced as strict hard constraints (`shift[staff][day] == 0`), not soft constraints with penalty relaxation. When requests collide with mandatory staffing requirements, the model is strictly infeasible.
+
+## Scenario & Rules
+
+We schedule **5 staff members** (`Alice`, `Bob`, `Charlie`, `Diana`, `Evan`) across **7 days** (`Mon`–`Sun`):
+
+- **Daily Headcount:** `Mon–Thu`: 3 staff, `Fri`: 4 staff, `Sat`: 3 staff, `Sun`: 2 staff.
+- **Senior Duty:** At least 1 senior staff member (`Alice` or `Bob`) must be on duty every day.
+- **Work Limit:** Each staff member works at most **5 days** per week.
+- **Weekend Premium:** Weekend shifts (`Sat`, `Sun`) incur an extra `+$30` shift premium on top of base daily wage.
+
+We evaluate two distinct, named scenarios with different vacation inputs to illustrate the full workflow:
+- **Scenario A (Balanced Requests — Feasible):** Alice (Sun), Bob (Mon), Charlie (Sat), Diana (Wed). All constraints can be satisfied simultaneously. HiGHS outputs an optimal roster.
+- **Scenario B (Conflicting Requests — Infeasible & Diagnosis):** Alice (Sat), Bob (Sat), Charlie (Sat), Diana (Wed). Because both senior leaders (Alice and Bob) request Saturday off simultaneously, the rule requiring at least 1 senior on duty every day cannot be satisfied. HiGHS reports `Infeasible`, triggering Z3 conflict diagnosis.
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as const;
+type Day = (typeof days)[number];
+
+const staffList = [
+  { name: "Alice",   isSenior: true,  dailyWage: 220, maxShifts: 5 },
+  { name: "Bob",     isSenior: true,  dailyWage: 210, maxShifts: 5 },
+  { name: "Charlie", isSenior: false, dailyWage: 160, maxShifts: 5 },
+  { name: "Diana",   isSenior: false, dailyWage: 160, maxShifts: 5 },
+  { name: "Evan",    isSenior: false, dailyWage: 150, maxShifts: 5 },
+];
+
+const requiredCoverage: Record<Day, number> = {
+  Mon: 3, Tue: 3, Wed: 3, Thu: 3, Fri: 4, Sat: 3, Sun: 2,
+};
+
+function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; day: Day }>) {
+  const m = new Model(name);
+
+  // 2D binary matrix: shift[staff][day] ∈ {0, 1}
+  const shift = m.binary(staffList.map((s) => s.name), [...days]);
+
+  // Objective: Minimize weekly payroll cost via 2D dot product
+  const costMatrix = Object.fromEntries(
+    staffList.map((s) => [
+      s.name,
+      Object.fromEntries(
+        days.map((d) => [d, s.dailyWage + (d === "Sat" || d === "Sun" ? 30 : 0)])
+      ),
+    ])
+  );
+  m.objective(minimize(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]}`,
+      `coverage_${d}`
+    );
+  }
+
+  // Rule 2: At least 1 senior staff member per day
+  const seniors = staffList.filter((s) => s.isSenior);
+  for (const d of days) {
+    m.constraint(
+      expr`${sum(seniors, (s) => shift[s.name][d])} >= 1`,
+      `senior_duty_${d}`
+    );
+  }
+
+  // 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}`,
+      `max_shifts_${s.name}`
+    );
+  }
+
+  // Rule 4: Named day-off requests as HARD constraints (shift[staff][day] == 0)
+  for (const req of dayOffRequests) {
+    m.constraint(
+      expr`${shift[req.staff][req.day]} == 0`,
+      `day_off_${req.staff}_${req.day}`
+    );
+  }
+
+  return { model: m, shift };
+}
+
+async function runScenario(
+  title: string,
+  modelName: string,
+  dayOffRequests: Array<{ staff: string; day: Day }>
+) {
+  console.log(`=== ${title} ===`);
+  console.log(
+    "Hard Vacation Requests: " +
+      dayOffRequests.map((r) => `${r.staff} (${r.day})`).join(", ")
+  );
+
+  const { model, shift } = buildShiftModel(modelName, dayOffRequests);
+
+  // Step 1: Optimize with HiGHS
+  const status = await model.solve();
+  console.log(`HiGHS Optimize Status: ${status}`);
+
+  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" : " ·"));
+      console.log(`  ${s.name.padEnd(8)}: ${schedule.join(" ")}`);
+    }
+    console.log("Schedule resolved successfully (no UNSAT diagnosis needed).\n");
+  } else if (status === "Infeasible") {
+    // Step 2: Diagnose the exact same model and constraints with Z3
+    console.log("HiGHS returned Infeasible! Diagnosing conflict with Z3 unsatCore...");
+    const checkRes = await model.check({ solver: "z3" });
+    console.log(`Z3 Check Status: ${checkRes.status}`);
+    console.log("Conflicting Constraint Subset (unsatCore):", model.unsatCore);
+    console.log(
+      "Note: unsatCore returns a conflicting subset (minimality/order not guaranteed). " +
+      "Independent requests like Diana's Wednesday off are excluded.\n"
+    );
+  }
+}
+
+async function main() {
+  // Scenario A: Balanced requests (Solvable)
+  await runScenario(
+    "Scenario A: Balanced Vacation Requests",
+    "FeasibleRoster",
+    [
+      { staff: "Alice", day: "Sun" },
+      { staff: "Bob", day: "Mon" },
+      { staff: "Charlie", day: "Sat" },
+      { staff: "Diana", day: "Wed" },
+    ]
+  );
+
+  // Scenario B: Conflicting Saturday requests (Infeasible)
+  await runScenario(
+    "Scenario B: Conflicting Saturday Requests",
+    "ConflictRoster",
+    [
+      { staff: "Alice", day: "Sat" }, // Senior
+      { staff: "Bob", day: "Sat" },   // Senior
+      { staff: "Charlie", day: "Sat" },
+      { staff: "Diana", day: "Wed" },
+    ]
+  );
+}
+
+main();
+```
+
+---
+
+# 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> |
+
+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.
+
+This example demonstrates **`m.indicator(binVar, constraint, { activeValue, M? })`**, which automatically linearizes conditional *"if coupon is selected, minimum spend must hold"* constraints using Big-M reformulation for MIP solvers like HiGHS. When `M` is omitted, WaSHI automatically derives safe, tight Big-M values from finite variable bounds.
+
+## Scenario & Promotion Rules
+
+A customer's shopping cart currently contains **$242** of merchandise (**$210** in Tech items and **$32** in Apparel):
+- **Optional Filler Add-on:** A **$10** Braided USB-C Cable (Tech) can be added to bring the cart total from `$242` to `$252`.
+- **Available Coupons** (maximum **2 coupons** total per checkout; at most **1 Exclusive** coupon):
+
+| Coupon Code | Discount | Condition | Stacking Rule |
+| :--- | :---: | :--- | :--- |
+| `WELCOME15` | **-$15** | Total cart spend $\ge \$100$ | **Stackable** |
+| `TECH30` | **-$30** | Tech category spend $\ge \$200$ | **Exclusive** (cannot combine with `MEGA45_250`) |
+| `MEGA45_250` | **-$45** | Total cart spend $\ge \$250$ | **Exclusive** (cannot combine with `TECH30`) |
+| `MEMBER10` | **-$10** | Total cart spend $\ge \$150$ | **Stackable** |
+
+Without adding the `$10` cable, the cart (`$242`) cannot use `MEGA45_250` and pays `$242 - $30 (TECH30) - $15 (WELCOME15) = $197`.  
+By adding the `$10` cable (`$252` gross), the customer unlocks `MEGA45_250` (`-$45`) + `WELCOME15` (`-$15`) for a net total of **$192**—saving an extra **$5** while getting an extra item!
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, sum, minimize, expr } from "@ohtaman/washi";
+
+async function optimizeCheckoutCart() {
+  const m = new Model("CartCouponOptimizer");
+
+  const baseCartSubtotal = 242;
+  const baseTechSubtotal = 210;
+
+  // Binary decision: add optional $10 USB-C cable to unlock $250 tier?
+  const addUsbCable = m.binary("addon_USB_Cable");
+  const usbCablePrice = 10;
+
+  const coupons = [
+    { id: "WELCOME15",  discount: 15, minCart: 100, minTech: 0,   stackable: true  },
+    { id: "TECH30",     discount: 30, minCart: 0,   minTech: 200, stackable: false },
+    { id: "MEGA45_250", discount: 45, minCart: 250, minTech: 0,   stackable: false },
+    { id: "MEMBER10",   discount: 10, minCart: 150, minTech: 0,   stackable: true  },
+  ];
+
+  // Binary decision variables for each coupon
+  const useCoupon = m.binary(coupons.map((c) => c.id));
+
+  const merchSpend = addUsbCable.mul(usbCablePrice).add(baseCartSubtotal);
+  const techSpend  = addUsbCable.mul(usbCablePrice).add(baseTechSubtotal);
+
+  // 1. Indicator constraints: If useCoupon[id] == 1, minimum spend threshold must hold
+  for (const cpn of coupons) {
+    if (cpn.minCart > 0) {
+      m.indicator(useCoupon[cpn.id], merchSpend.ge(cpn.minCart), {
+        activeValue: 1,
+        M: 500,
+        name: `min_spend_${cpn.id}`,
+      });
+    }
+    if (cpn.minTech > 0) {
+      m.indicator(useCoupon[cpn.id], techSpend.ge(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"
+  );
+
+  // 3. Max 2 coupons per order
+  m.constraint(
+    expr`${sum(coupons, (c) => useCoupon[c.id])} <= 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)));
+
+  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"}`);
+  for (const cpn of coupons) {
+    const applied = (useCoupon[cpn.id].value ?? 0) > 0.5;
+    console.log(`  ${applied ? "✅ [APPLIED]" : "   [skipped]"} ${cpn.id.padEnd(11)} (-$${cpn.discount})`);
+  }
+}
+
+optimizeCheckoutCart();
+```
+
+---
+
+# Portfolio Optimization (QP)
+
+| 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> |
+
+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.
+
+## Mathematical Formulation
+
+Let $w_i \ge 0$ denote the allocation weight for asset $i$:
+
+$$\begin{aligned}
+\text{Minimize} \quad & \mathbf{w}^T \boldsymbol{\Sigma} \mathbf{w} & (\text{Portfolio Variance}) \\
+\text{Subject to} \quad & \sum_{i=1}^n w_i = 1 & (\text{Full Capital Budget}) \\
+& \sum_{i=1}^n r_i w_i \ge R_{\text{target}} & (\text{Minimum Target Return}) \\
+& 0 \le w_i \le 1 & (\text{Long-Only Weights})
+\end{aligned}$$
+
+where $\boldsymbol{\Sigma}$ is the positive semi-definite asset return covariance matrix.
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
+
+async function solvePortfolio() {
+  const m = new Model("PortfolioQP");
+
+  const assets = ["Tech", "Bonds", "GlobalEq", "RealEstate", "Gold"];
+  const expectedReturns = [0.12, 0.04, 0.09, 0.07, 0.05];
+  const targetReturn = 0.085; // 8.5% minimum expected return
+
+  // 5x5 Covariance Matrix
+  const cov = [
+    [0.040, 0.002, 0.025, 0.015, 0.005],
+    [0.002, 0.005, 0.003, 0.002, 0.001],
+    [0.025, 0.003, 0.030, 0.018, 0.008],
+    [0.015, 0.002, 0.018, 0.025, 0.004],
+    [0.005, 0.001, 0.008, 0.004, 0.020],
+  ];
+
+  // Allocation weights w_i in [0, 1]
+  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");
+
+  // 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");
+
+  // 3. Quadratic Objective: minimize risk w^T * Sigma * w
+  let risk = new QuadExpr();
+  for (let i = 0; i < assets.length; i++) {
+    for (let j = 0; j < assets.length; j++) {
+      if (cov[i][j] !== 0) {
+        risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
+      }
+    }
+  }
+  m.objective(minimize(risk));
+
+  // Solve natively with HiGHS Convex QP engine
+  const status = await m.solve();
+
+  console.log(`Status: ${status}`);
+  console.log(`Variance: ${m.objectiveValue?.toFixed(6)}`);
+  console.log(`Volatility (Std Dev): ${((Math.sqrt(m.objectiveValue || 0)) * 100).toFixed(2)}%`);
+
+  assets.forEach((name) => {
+    console.log(`  ${name.padEnd(10)}: ${((w[name].value ?? 0) * 100).toFixed(2)}%`);
+  });
+}
+
+solvePortfolio();
+```
+
+---
+
+# 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> |
+
+Satisfiability Modulo Theories (SMT) combines propositional logic (Boolean SAT) with first-order theories (linear integer arithmetic, real inequalities).
+
+This example demonstrates how to formally verify and deduce system states in an IoT home security system using WaSHI and the Z3 solver engine.
+
+## The Scenario
+
+We model a security rule system with sensor readings and logic rules:
+1. When ambient light $\le 50$, it implies night time (`isNight`).
+2. When motion is detected at night and the alarm is armed, the siren must sound.
+3. If the alarm is armed, the front door must never be unlocked.
+4. When motion is detected at night, comfort lights should turn on.
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, not, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+async function verifySecurityRules() {
+  const m = new Model({ name: "SmartHomeSecurity", solver: "z3" });
+
+  // 1. Boolean Propositional Variables
+  const isNight = m.bool("isNight");
+  const motionDetected = m.bool("motionDetected");
+  const alarmArmed = m.bool("alarmArmed");
+  const frontDoorUnlocked = m.bool("frontDoorUnlocked");
+  const sirenActive = m.bool("sirenActive");
+  const lightsOn = m.bool("lightsOn");
+
+  // 2. Arithmetic metric (lux sensor)
+  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");
+
+  // Rule 2: (motionDetected AND isNight AND alarmArmed) => sirenActive
+  m.constraint(
+    motionDetected.and(isNight).and(alarmArmed).implies(sirenActive),
+    "intrusion_rule"
+  );
+
+  // Rule 3: alarmArmed => NOT(frontDoorUnlocked)
+  m.constraint(alarmArmed.implies(not(frontDoorUnlocked)), "lock_safety_rule");
+
+  // Rule 4: (motionDetected AND isNight) => lightsOn
+  m.constraint(motionDetected.and(isNight).implies(lightsOn), "comfort_lights");
+
+  // 3. Observed Context
+  m.constraint(expr`${luxLevel} <= 20`, "sensor_reading_dark");
+  m.constraint(alarmArmed, "user_armed_alarm");
+  m.constraint(motionDetected, "sensor_motion_triggered");
+
+  // Check satisfiability and deduce state
+  const res = await m.check({ solver: "z3" });
+
+  console.log(`Status: ${res.status}`);
+  console.log(`Siren Active : ${sirenActive.value}`);
+  console.log(`Lights On    : ${lightsOn.value}`);
+  console.log(`Door Locked  : ${frontDoorUnlocked.value ? "No" : "Yes"}`);
+  console.log(`Is Night     : ${isNight.value}`);
+}
+
+verifySecurityRules();
+```
+
+---
+
+# 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> |
+
+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.
+
+This example shows how to isolate the conflicting constraint subset using Z3 Unsat Core extraction.
+
+## The Conflicting Scenario
+
+A tech team is staffing a customer project:
+1. Each engineer costs $8,000 against the project budget (`budget_limit`).
+2. The customer requires rush delivery (`rush_required`).
+3. Rush delivery mandates at least 8 engineers (`rush_staffing_rule`).
+4. The board has imposed a strict budget cap of $50,000 (`strict_board_budget_cap`).
+5. Labor law requires at least 1 employee on staff (`minimum_one_employee`).
+
+Notice that:
+
+$$8 \text{ engineers} \times \$8,000 = \$64,000 > \$50,000 \text{ budget!}$$
+
+## Implementation in WaSHI
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+async function diagnoseConflicts() {
+  const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
+
+  const engineers = m.integer("engineers", { lb: 0, ub: 20 });
+  const budget = m.continuous("budget", { lb: 0, ub: 100000 });
+  const rushDelivery = m.bool("rushDelivery");
+
+  // Rule 1: Each engineer costs $8,000
+  m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+
+  // Rule 2: Customer requires rush delivery
+  m.constraint(rushDelivery, "rush_required");
+
+  // Rule 3: Rush delivery requires at least 8 engineers
+  m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+
+  // Rule 4: Board budget cap of $50,000 (Conflict!)
+  m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
+
+  // Rule 5: Innocent bystander rule
+  m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
+
+  // Run diagnosis
+  const res = await m.check({ solver: "z3" });
+
+  console.log(`Status: ${res.status}`);
+  console.log("Conflicting Constraints (conflicts):", m.conflicts);
+}
+
+diagnoseConflicts();
+```