@ohtaman/washi 0.4.0 → 0.5.0

package/README.md

@@ -28,20 +28,20 @@
 
 HiGHS is the default solver; Z3 and GLPK are optional plugins. The package provides Node.js and browser distributions, including WebAssembly assets. See the [browser integration guide](#-browser--web-worker-usage) for deployment requirements.
 
-[Try the browser demo](https://ohtaman.github.io/washi/demo/) · [Browse example source code](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen examples](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
+[Documentation](https://ohtaman.github.io/washi/) · [Try the browser demo](https://ohtaman.github.io/washi/demo/) · [AI Agent Quick-Reference](docs/getting-started/ai-agents.md) · [Agent Skill (`SKILL.md`)](skills/washi/SKILL.md) · [Browse example source code](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen examples](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 
 const m = new Model("WoodworkingProfit");
 const x = m.integer("desks", { lb: 0 });
 const y = m.integer("chairs", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-await m.optimize();
+await m.solve();
 console.log(`Produce: x=${x.value}, y=${y.value} (Profit: $${m.objectiveValue})`);
 ```
 
@@ -49,10 +49,10 @@ console.log(`Produce: x=${x.value}, y=${y.value} (Profit: $${m.objectiveValue})`
 
 ## 🎯 What WaSHI provides
 
-1. **Algebraic model construction**: Formulate optimization models using domain-specific variable constructors (`m.binary`, `m.integer`, `m.continuous`), tagged template literals (`expr`), vector aggregations (`dot`, `sum`), and first-class constraints (`m.constrain`).
-2. **Solver adapters**: Use a common modeling API with HiGHS, Z3, or GLPK, or [register your own adapter](https://github.com/ohtaman/washi/blob/main/docs/custom-solver-guide.md). Choose an engine that supports the model's problem class; the adapters do not make every solver support every feature.
-3. **Local execution and WebAssembly distribution**: With the local solver adapters, solving runs in the application without a separate Python service or native C/C++ build. Browser deployments must include the generated JS, Worker, and WASM assets. Offline use also requires those resources to be available locally or cached. Z3 has additional browser isolation requirements.
-4. **Named constraints and SMT results**: With Z3, explicitly check satisfiability and inspect an unsatisfiable core to investigate conflicting constraints. A returned core is a conflicting subset, not necessarily the smallest one.
+1. **Algebraic model construction**: Formulate optimization models using domain-specific variable constructors (`m.binary`, `m.integer`, `m.continuous`), unified tagged template literals (`expr`), vector aggregations (`dot`, `sum`), and first-class constraints (`m.constraint`). Because JavaScript lacks operator overloading, `` expr`...` `` parses infix math (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) while binding interpolated `${...}` values directly as typed `Var` or expression references—similar to parameterized SQL templates—preserving static type checking, IDE refactoring, and indexed variable lookups (`${flow[i][j]}`).
+2. **Solver adapters**: Use a common modeling API with HiGHS, Z3, or GLPK, or [register your own adapter](https://github.com/ohtaman/washi/blob/main/docs/solvers/custom-solver.md). Choose an engine that supports the model's problem class; the adapters do not make every solver support every feature.
+3. **Local execution and WebAssembly distribution**: With the local solver adapters, solving runs in the application without a separate Python service or native C/C++ build—removing backend provisioning as a bottleneck when shipping interactive tools or combining mathematical optimization with in-browser LLMs (e.g., WebGPU / WebLLM) on the client. Browser deployments must include the generated JS, Worker, and WASM assets. Offline use also requires those resources to be available locally or cached. Z3 has additional browser isolation requirements.
+4. **Named constraints and SMT results**: With Z3, explicitly check satisfiability and inspect conflicting constraints (`conflicts` / `unsatCore`) to investigate infeasibilities. A returned core is a conflicting subset, not necessarily the smallest one.
 
 Model construction and translation are WaSHI's responsibility. Supported problem classes, numerical behavior, and solve time depend on the selected solver, its settings, and the problem. Modeling overhead and solver execution time should be measured separately; a result for one model is not a general performance guarantee.
 
@@ -92,61 +92,54 @@ npm install z3-solver    # For SMT and unsat core diagnosis
 npm install glpk.js      # For GLPK solver (GPL-3.0)
 ```
 
+*(Optional)* For AI coding agents (Claude Code, Antigravity, Cursor, Codex, etc.), `@ohtaman/washi` ships a portable [`skills/washi/SKILL.md`](skills/washi/SKILL.md) workflow alongside the [AI Agent Quick-Reference](docs/getting-started/ai-agents.md):
+
+```bash
+mkdir -p .agents/skills/washi
+cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
+```
+
 ---
 
 ## 🚀 Usage Guide
 
-### 1. Mixed-Integer Linear Programming (MIP)
+### 1. Multidimensional Variables, Indicator Constraints & Solution Validation
 
-Formulate production scheduling, resource allocation, and facility location problems:
+Construct 1D dictionaries or 2D matrices of variables in a single call, express conditional Big-M logic with `m.indicator()`, monitor live progress (`onProgress`), and independently verify solutions with `m.validateSolution()`:
 
 ```ts
 import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model("FactoryPlanning");
-
-// Decision variables (Integer, non-negative)
-const chairs = m.integer("chairs", { lb: 0 });
-const tables = m.integer("tables", { lb: 0 });
-
-// Natural formula objective & constraints via Tagged Template Literals
-m.maximize(expr`30 * ${chairs} + 50 * ${tables}`);
-m.constrain(expr`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
-
-// Solve using default HiGHS WASM engine
-const status = await m.optimize();
-
-console.log(`Status: ${status}`); // "Optimal"
-console.log(`Objective: $${m.objectiveValue}`); // 1100
-console.log(`Chairs: ${chairs.value}, Tables: ${tables.value}`); // 20 chairs, 10 tables
-```
+const m = new Model("FacilityPlanning");
 
-#### 🗂 Multidimensional Variables Grid
-
-Construct variable arrays or multi-index matrices in one call:
-
-```ts
 // 1D dictionary of binary variables
 const openCity = m.binary(["Tokyo", "Osaka", "Nagoya"]);
 
 // 2D transport flow matrix: [Factory] x [Store]
-const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
+const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0, ub: 1000 });
 
 // 2D coordinate grid (e.g. 8x8 chessboard)
 const board = m.binary(8, 8, { prefix: "queen" });
-```
-
-#### 🔀 Big-M Indicator Constraints (`m.indicator`)
 
-Model conditional activation rules and fixed-charge economics without manual Big-M algebra:
-
-```ts
-// If factory is closed (openCity['Tokyo'] == 0), its production capacity must be 0
+// Conditional Big-M constraint: if openCity["Tokyo"] == 0, flow["F1"]["StoreA"] <= 0
+// (Omit M to let WaSHI automatically derive a tight Big-M from finite variable bounds)
 m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
   activeValue: 0,
-  M: 1000,
+  name: "tokyo_closed_no_flow",
 });
+
+// Solve with optional progress callback & AbortSignal cancellation
+const controller = new AbortController();
+await m.solve({
+  signal: controller.signal,
+  onProgress: (ev) => {
+    // Live branch-and-bound metrics: ev.elapsedTime, ev.objectiveValue, ev.objectiveBound, ev.mipGap
+  },
+});
+
+// Independently verify variable bounds, integrality, and linear/logical constraints
+const report = m.validateSolution();
+console.log("Solution valid?", report.valid);
 ```
 
 ---
@@ -156,7 +149,7 @@ m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
 Minimize investment risk based on a covariance matrix subject to return and budget constraints:
 
 ```ts
-import { Model, QuadExpr, sum, dot, expr } from "@ohtaman/washi";
+import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
 
 const m = new Model("MarkowitzPortfolio");
 const assets = ["Tech", "Bonds", "RealEstate"];
@@ -166,11 +159,11 @@ const returns = [0.14, 0.04, 0.08];
 const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 // 1. Fully invested budget: sum(w) == 1.0
-m.constrain(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
+m.constraint(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
 
 // 2. Minimum target return: portfolio return >= 8.5%
 const retMap = Object.fromEntries(assets.map((a, i) => [a, returns[i]]));
-m.constrain(expr`${dot(retMap, w)} >= 0.085`, "min_return");
+m.constraint(expr`${dot(retMap, w)} >= 0.085`, "min_return");
 
 // 3. Covariance risk matrix
 const cov = [
@@ -186,9 +179,9 @@ for (let i = 0; i < assets.length; i++) {
     risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
   }
 }
-m.minimize(risk);
+m.objective(minimize(risk));
 
-await m.optimize();
+await m.solve();
 console.log(`Minimal Variance: ${m.objectiveValue?.toFixed(6)}`);
 assets.forEach((name) => {
   console.log(`  ${name}: ${((w[name].value || 0) * 100).toFixed(2)}%`);
@@ -214,13 +207,13 @@ const siren = m.bool("siren");
 const lux = m.integer("lux", { lb: 0 });
 
 // Logical rules
-m.constrain(lux.le(50).implies(isNight), "dark_implies_night");
-m.constrain(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
+m.constraint(lux.le(50).implies(isNight), "dark_implies_night");
+m.constraint(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
 
 // Current sensor observations
-m.constrain(expr`${lux} <= 10`, "sensor_dark");
-m.constrain(motion, "sensor_motion");
-m.constrain(alarm, "alarm_on");
+m.constraint(expr`${lux} <= 10`, "sensor_dark");
+m.constraint(motion, "sensor_motion");
+m.constraint(alarm, "alarm_on");
 
 // Check satisfiability and deduce state without an objective function
 const res = await m.check({ solver: "z3" });
@@ -231,7 +224,7 @@ console.log(`Siren active? ${m.values.get("siren")}`); // true
 
 ---
 
-### 4. Conflict Diagnosis (`unsatCore`)
+### 4. Conflict Diagnosis (`conflicts` / `unsatCore`)
 
 When business rules or constraints contradict each other, extract a **conflicting constraint subset** (unsatisfiable core; minimality is not guaranteed) for troubleshooting (requires Z3):
 
@@ -245,24 +238,24 @@ const budget = m.continuous("budget", { lb: 0, ub: 100000 });
 const rushDelivery = m.bool("rushDelivery");
 
 // Rule 1: Each engineer costs $8,000
-m.constrain(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
 
 // Rule 2: Customer requires rush delivery
-m.constrain(rushDelivery, "rush_required");
+m.constraint(rushDelivery, "rush_required");
 
 // Rule 3: Rush delivery requires at least 8 engineers
-m.constrain(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
 
 // Rule 4: Hard board budget cap of $50,000 (Conflict: 8 * $8000 = $64,000 > $50,000!)
-m.constrain(expr`${budget} <= 50000`, "strict_board_budget_cap");
+m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
 
 // Rule 5: Innocent bystander rule
-m.constrain(expr`${engineers} >= 1`, "minimum_one_employee");
+m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
 
 const res = await m.check({ solver: "z3" });
 
 console.log(`Status: ${res.status}`); // "Unsat"
-console.log("Conflicting constraints:", res.unsatCore);
+console.log("Conflicting constraints:", res.conflicts);
 // Output: ["budget_limit", "rush_required", "rush_staffing_rule", "strict_board_budget_cap"]
 // Note: "minimum_one_employee" is correctly excluded!
 ```
@@ -274,18 +267,18 @@ console.log("Conflicting constraints:", res.unsatCore);
 To use the GNU Linear Programming Kit (GLPK) solver plugin:
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/glpk";
 
 const m = new Model({ solver: "glpk" });
 const x = m.integer("x", { lb: 0 });
 const y = m.integer("y", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-const status = await m.optimize();
+const status = await m.solve();
 console.log(`Status: ${status}`); // "Optimal"
 console.log(`Objective: ${m.objectiveValue}`); // 1100
 ```
@@ -297,7 +290,7 @@ console.log(`Objective: ${m.objectiveValue}`); // 1100
 Cleanly compute 1D/2D linear combinations without nested loops:
 
 ```ts
-import { Model, dot } from "@ohtaman/washi";
+import { Model, dot, minimize } from "@ohtaman/washi";
 
 const m = new Model();
 const factories = ["Tokyo", "Osaka"];
@@ -311,8 +304,8 @@ const costs = {
 const ship = m.continuous(factories, stores);
 
 // Total transportation cost in one line:
-m.minimize(dot(costs, ship));
-await m.optimize();
+m.objective(minimize(dot(costs, ship)));
+await m.solve();
 
 // Extract all optimal variable values as a structured object
 const solution = m.getValues(ship);
@@ -362,23 +355,23 @@ The package also includes `dist/browser/washi.min.js`, which exports the `Washi`
 </script>
 ```
 
-For CDN usage, replace the local URL with `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js` (or pin your desired release version `>= 0.1.2`). For ESM use the corresponding `dist/browser/washi.js` URL. Selecting the CDN URL is an explicit choice; local copies never switch to a CDN.
+For CDN usage, replace the local URL with `https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js` (specifying a compatible release version once published). For ESM use the corresponding `dist/browser/washi.js` URL. Selecting the CDN URL is an explicit choice; local copies never switch to a CDN.
 
 ### Solver Plugins in the Browser (GLPK & Z3)
 
-The browser distribution includes pre-bundled, standalone solver plugins under `dist/browser/solvers/` (available from `>= 0.2.0` or `@latest` on CDN):
+The browser distribution includes pre-bundled, standalone solver plugins under `dist/browser/solvers/`:
 - **GLPK**: `dist/browser/solvers/glpk.js` (ESM) and `dist/browser/solvers/glpk.min.js` (IIFE, registers global `WashiGLPK`)
 - **Z3**: `dist/browser/solvers/z3.js` (ESM) and `dist/browser/solvers/z3.min.js` (IIFE, registers global `WashiZ3`), accompanied by `z3-built.js` and `z3-built.wasm`
 
 #### Browser ESM with GLPK
 ```html
 <script type="module">
-  import { Model } from "./washi/washi.js";
+  import { Model, maximize } from "./washi/washi.js";
   import "./washi/solvers/glpk.js";
 
   const model = new Model({ solver: "glpk" });
   const x = model.continuous("x", { lb: 0, ub: 10 });
-  model.maximize(x);
+  model.objective(maximize(x));
   await model.solve();
   console.log("GLPK status:", model.status);
 </script>
@@ -391,52 +384,34 @@ The browser distribution includes pre-bundled, standalone solver plugins under `
 <script>
   const model = new Washi.Model({ solver: "glpk" });
   const x = model.continuous("x", { lb: 0, ub: 10 });
-  model.maximize(x);
+  model.objective(Washi.maximize(x));
   model.solve().then(status => console.log("GLPK status:", status));
 </script>
 ```
 
 > [!NOTE]
 > **Z3 in Browser Environments & Cross-Origin Isolation**:
-> Because the Z3 WebAssembly engine uses multithreading (`SharedArrayBuffer`), modern browsers require cross-origin isolation. The HTML document response must send:
-> ```http
-> Cross-Origin-Opener-Policy: same-origin
-> Cross-Origin-Embedder-Policy: require-corp
-> ```
-> And any cross-origin assets must serve `Cross-Origin-Resource-Policy: cross-origin`.
-> 
-> General static sites without custom header control (e.g. standard GitHub Pages or preview platforms) and third-party iframe embeds (e.g. CodePen / JSFiddle) do not satisfy these requirements without extra setup. Importing `@ohtaman/washi` never automatically injects or registers a Service Worker into consumer applications.
-> 
-> To enable Z3 on GitHub Pages, the official WaSHI Web Demo bundles a dedicated `coi-serviceworker.js` strictly scoped to `/washi/`. On fresh browser sessions, it registers the worker and reloads once to establish `window.crossOriginIsolated === true` before running Z3. Environments lacking Service Workers or failing isolation abort Z3 execution with a descriptive explanation rather than hanging.
-
-Complete standalone examples for ESM, script tags, and CodePen are available in `examples/distribution/`.
-
-### Offline distribution, Workers and custom hosting
-
-Deploy the full application build or the entire browser distribution to a local HTTP / intranet server. With all assets locally available, an empty browser cache does not require access to the internet. Saving only the HTML or the first JS file is insufficient. `file://` execution and automatic PWA caching are not supported by this distribution.
-
-ESM assets resolve relative to their module URL; the script build captures its own script URL at load time. CDN Workers use a Blob module bootstrap. The server must permit cross-origin JS / WASM loading; CSP must permit the selected script / connection origins and `worker-src blob:` for CDN Workers. If that is unavailable, use `useWorker: false`. Worker load / message failures reject pending solves rather than leaving them unresolved.
+> Because the Z3 WebAssembly engine uses multithreading (`SharedArrayBuffer`), modern browsers require cross-origin isolation (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`). See the [Cross-Origin Isolation Guide](docs/getting-started/cross-origin.md) and [Runtime Environments Guide](docs/getting-started/runtimes.md) for full details on static hosting, `coi-serviceworker.js`, offline/intranet deployment, CSP (`worker-src blob:`), and custom WASM URLs (`setHighsWasmUrl`).
 
-For custom hosting, `setHighsWasmUrl(url)` and `options.wasmUrl` remain available. To explicitly use the existing HiGHS CDN:
+Complete standalone examples for ESM, script tags, and CodePen are available in [`examples/distribution/`](examples/distribution/README.md).
 
-```typescript
-import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
-setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
-```
+---
 
-Failed initialization reports the attempted URL and does not try a different host. This changes the previous local-root/CDN fallback behavior: deploy the generated assets or configure an explicit URL.
+## 🛠️ Custom Solvers & Extensibility
 
-### Verify the distributable
+WaSHI features a decoupled, pluggable solver architecture. You can easily build and register your own custom solver adapter (e.g., for cloud REST optimizers, WebAssembly engines, or proprietary solvers):
 
-`npm run test:distribution` packs and installs the actual npm tarball, builds Vite / webpack consumers without optional peers, and runs their emitted JS with real WASM in a VM. This is not a browser/CORS test. For Playwright Chromium checks, run `npx playwright install chromium` and `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution`. CI also runs that browser mode, including separate-origin browser bundles with external network requests blocked.
+- See the complete [Custom Solver Developer Guide](docs/solvers/custom-solver.md) for step-by-step tutorials, complete API contracts (`Solver`, `SolveModelData`, `CheckModelData`, `SolverResult`), and testing best practices.
 
 ---
 
-## 🛠️ Custom Solvers & Extensibility
+## 📚 Documentation
 
-WaSHI features a decoupled, pluggable solver architecture. You can easily build and register your own custom solver adapter (e.g., for cloud REST optimizers, WebAssembly engines, or proprietary solvers):
+Full documentation is available at **[ohtaman.github.io/washi](https://ohtaman.github.io/washi/)** and in the repository's [`docs/`](docs/) directory:
 
-- See the complete [Custom Solver Developer Guide](docs/custom-solver-guide.md) for step-by-step tutorials, complete API contracts (`Solver`, `LpModelData`, `SolverResult`), and testing best practices.
+- **Getting Started**: [Quick Start](docs/getting-started/index.md) · [AI Agent Quick-Reference](docs/getting-started/ai-agents.md) · [Runtime Environments](docs/getting-started/runtimes.md) · [Cross-Origin Isolation (Z3)](docs/getting-started/cross-origin.md)
+- **Modeling Guide**: [Variables (`Var`, `BoolVar`)](docs/guide/variables.md) · [Expressions (`expr`, `sum`, `dot`)](docs/guide/expressions.md) · [Constraints & Logic (`indicator`, SMT)](docs/guide/constraints.md) · [Objectives & Solving (`solve`, `validateSolution`)](docs/guide/objectives.md) · [Feasibility & Unsat Core (`check`)](docs/guide/unsat-core.md)
+- **Solvers**: [Solver Overview](docs/solvers/index.md) · [HiGHS](docs/solvers/highs.md) · [Z3](docs/solvers/z3.md) · [GLPK](docs/solvers/glpk.md) · [Custom Solvers](docs/solvers/custom-solver.md)
 
 ---
 
@@ -446,7 +421,7 @@ Start with the [example gallery](https://github.com/ohtaman/washi/blob/main/exam
 
 | Category | Example | What it demonstrates | Solver |
 | :--- | :--- | :--- | :--- |
-| **Fundamentals** | [Production planning](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | Integer variables, a profit objective, and resource constraints (`expr`, `c`) | HiGHS |
+| **Fundamentals** | [Production planning](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | Integer variables, a profit objective, and resource constraints (`expr`) | HiGHS |
 | **Fundamentals** | [Transportation network](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) | 2D origin-destination variable matrix (`continuous(rows, cols)`) and flow balance | HiGHS |
 | **Fundamentals** | [Diet & sensitivity analysis](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) | Shadow prices (`constr.dual`), surpluses (`constr.slack`), and reduced costs (`var.reducedCost`) | HiGHS |
 | **Practical** | [Staff shift scheduling](https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts) | Weekly roster optimization + diagnosing conflicting Saturday vacation requests | HiGHS + Z3 |
@@ -477,7 +452,7 @@ The example sources import the repository's `src/` modules. In an application us
 
 ---
 
-## 🧪 Testing
+## 🧪 Testing & Reproducible Benchmarks
 
 Run the repository's unit and integration tests, and build the distributions:
 
@@ -489,6 +464,24 @@ npm test
 npm run build
 ```
 
+### Optional Reproducible Benchmarks
+
+To measure modeling and solver phases on deterministic `small-lp` (24 variables, 18 constraints) and `scheduling-mip` (315 variables, 231 constraints, including rebuilt `initialValue` warm starts) scenarios without mixing performance timings into correctness test thresholds:
+
+```bash
+# Run Node.js in-process WASM benchmarks (HiGHS and GLPK, 5 warm iterations by default)
+npm run bench
+
+# Customize iteration count or emit structured JSON
+node scripts/run-benchmarks.mjs --iterations=10 --json
+
+# Also measure headless Chromium Web Worker execution (requires Playwright Chromium)
+node scripts/run-benchmarks.mjs --browser
+```
+
+- **Explicit phase boundaries**: Reports cold runtime initialization (`coldRuntimeInitMs`, `coldFirstSolveMs`) separately from repeated warm-runtime measurements (`modelBuildMs`, `validationMs`, `lpSerializationMs` for LP-string adapters or `symbolMapMs` for structured adapters, `resultMappingMs` via `MockSolver`, `adapterSolveMs`, and `endToEndSolveMs`). Timings are measured directly per phase and are never subtracted to estimate "native solver time".
+- **Distinct execution environments**: Node.js in-process WASM (`usesBrowserWorker: false`) and Browser Web Worker execution (`usesBrowserWorker: true`, which includes Worker lifecycle and `postMessage` structured-clone transfer) are reported as separate environments, not interchangeable baselines.
+
 ---
 
 ## 📄 License