@ohtaman/washi 0.5.0 → 0.7.0

package/llms.txt

@@ -1,8 +1,8 @@
 # WaSHI (@ohtaman/washi)
 
-> WaSHI: WebAssembly-backed, Solver-independent, High-level modeling Interface (LP, MIP, QP, SMT)
+> WaSHI: WebAssembly-backed Algebraic Modeler for Mathematical Optimization & Constraint Programming (LP, MIP, QP, SMT)
 
-WaSHI brings the algebraic modeling style of Python's **PuLP** and Julia's **JuMP** to the TypeScript and JavaScript ecosystem.
+**WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) brings the algebraic modeling style of Python's **PuLP** to the TypeScript and JavaScript ecosystem.
 
 - Full single-file documentation reference: [llms-full.txt](llms-full.txt)
 - Canonical AI agent modeling quick-reference: [docs/getting-started/ai-agents.md](docs/getting-started/ai-agents.md)
@@ -52,7 +52,7 @@ import "@ohtaman/washi/solvers/glpk";
 1. **Bundled WASM by default (no implicit CDN fallback)**:
    - In Node.js and modern bundlers, WebAssembly assets resolve relative to the module automatically.
    - In browser deployments, deploy the full `dist/browser/` directory (JS, Worker, and `.wasm` files) together. If a local WASM URL is missing or returns an HTML SPA fallback, initialization fails immediately and reports the attempted URL—it **never** silently switches to a public CDN.
-   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads the local Node `highs` package runtime).
+   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads WaSHI's bundled local `highs.wasm` runtime).
 2. **Z3 requires a Secure Context, Cross-Origin Isolation, and CORS in browsers**:
    - Z3 WebAssembly uses `SharedArrayBuffer` multithreading. Browser pages running Z3 must run in a secure context (`window.isSecureContext === true`, i.e., HTTPS or `localhost`) and be cross-origin isolated (`window.crossOriginIsolated === true`) by serving:
      - `Cross-Origin-Opener-Policy: same-origin` (on the document)
@@ -61,7 +61,7 @@ import "@ohtaman/washi/solvers/glpk";
    - Importing `@ohtaman/washi` never auto-injects a Service Worker. When a secure context or cross-origin isolation is absent in a browser, Z3 rejects immediately with a descriptive error.
 3. **Web Workers & Cancellation (`AbortSignal`)**:
    - Pre-solve cancellation (`signal.aborted` before execution starts) is supported across all solvers.
-   - In browsers where `Worker` is available, HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
+   - In browsers where `Worker` is available on a non-opaque effective origin (`window.origin !== "null"`), HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). On opaque effective origins (`window.origin === "null"`, such as `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), HiGHS defaults to main-thread execution (`useWorker: false`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
    - On main-thread HiGHS (`useWorker: false` or in Node.js), cooperative mid-solve cancellation is supported when `abort()` is triggered synchronously inside an `onProgress` callback at a solver interrupt checkpoint; arbitrary asynchronous aborts from outside cannot preempt a blocked synchronous WASM thread until a callback checkpoint or completion. Single-threaded WASM solvers without interrupt hooks (GLPK, Z3) check `signal` before execution starts.
 
 ---
@@ -77,6 +77,7 @@ const m = new Model("ExampleModel");
 
 // Scalar variables
 const x = m.continuous("x", { lb: 0, ub: 100 });
+const y = m.continuous("y", { lb: 0, ub: 100 });
 const n = m.integer("n", { lb: 0, ub: 10 });
 const b = m.binary("b");
 const flag = m.bool("flag"); // Propositional boolean (for Z3 / logical constraints)
@@ -98,12 +99,12 @@ const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
 ### Step 2: Build Expressions (`expr`, `sum`, `dot`)
 
 - **Unified `expr` template tag**:
-  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``
-  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` `` (variable-by-variable products and squares are supported for convex QP objectives).
-  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` `` (supports `<=`, `>=`, `==`, and `=`).
-- **Aggregations**:
-  - `sum(iterable, mapper?)` sums an `Iterable` of `Var` / `LinExpr` / `number` (e.g., `Var[]`, `grid.flat()`, or `Object.values(record)`).
-  - `dot(a, b)` computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
+  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``, `` expr`dot(${profit}, ${byItem}) - 20 * ${b}` ``, `` expr`sum((${price} - ${cost}) * ${byItem})` ``
+  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``, `` expr`sum((${vec} - ${target})^2)` `` (supported for convex QP objectives on purely continuous models using `m.continuous`; built-in HiGHS does not support MIQP models containing integer, binary, or boolean variables).
+  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` ``, `` expr`sum(${byItem}) <= 100` `` (supports `<=`, `>=`, `==`, and `=`).
+- **Aggregations & Element-Wise Container Arithmetic**:
+  - `sum(containerOrItems, mapper?)` (usable inside `` expr`sum(...)` `` or standalone `sum(...)`) sums a 1D/2D `Array`, `Iterable`, or plain `Record` of `Var` / `LinExpr` / `number` (without needing `Object.values(record)`), or maps over items/counts via `sum(items, (item, i) => ...)`. Inside `` expr`sum(...)` ``, element-wise container arithmetic (`+`, `-`, `*`, `/`, `^2`) is also supported.
+  - `dot(a, b)` (usable inside `` expr`dot(${a}, ${b})` `` or standalone `dot(a, b)`) computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`, computing the Frobenius inner product $\sum_{i,j} A_{i,j} B_{i,j}$), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
 - **Fluent methods**:
   - Arithmetic (on `LinExpr` and `QuadExpr`; `Var` supports `.add()`, `.sub()`, `.mul()`, `.neg()`): `.add(other)`, `.sub(other)`, `.mul(other)`, `.div(scalar)`, `.neg()`
   - Comparisons (on `Var` and `LinExpr`): `.le(rhs, name?)`, `.ge(rhs, name?)`, `.eq(rhs, name?)`
@@ -117,8 +118,8 @@ Constructing an `expr` or `.le()` object does **not** attach it to the model unt
 // Set objective using maximize() or minimize()
 m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
 
-// Register constraints on the model
-m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+// Register constraints on the model (returns the registered Constraint / BoolExpr or array)
+const limit = m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
 
 // Indicator constraint (MIP Big-M reformulation: b === 1 => x <= 50)
 m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
@@ -130,9 +131,10 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
   - Returns `SolverStatus` (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`, `"Sat"`, or `"Unsat"`). Built-in optimization solvers return the optimization statuses (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`), where a time-, iteration-, or solution-limited run (or an interrupted solve) that found a valid primal incumbent returns `"Feasible"`; `"Sat"` and `"Unsat"` are included in `SolverStatus` for satisfiability/custom solver adapters (such as `MockSolver`).
   - Read values via `x.value`, `expr`...`.value`, `m.getValues(x)`, `m.getValues(container)`, `m.objectiveValue`, `constr.dual`, `constr.slack`, and `x.reducedCost`.
   - Call `m.validateSolution()` after solving to independently verify variable finiteness, variable bounds (`lb`/`ub`), integer/binary/boolean domains, linear constraint residuals, and logical constraints (`SolutionValidationReport`: `{ valid, complete, maxViolation, violations, ... }`). Note that `validateSolution()` checks primal feasibility of variables and constraints; it does not recompute or compare `m.objectiveValue`.
-- **Satisfiability & Unsat Core (`await m.check(options?)`)**:
-  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` and `unsatCore` are optional and populated only when an unsat-core-capable solver (such as Z3) returns `"Unsat"`.
-  - For models containing only linear arithmetic constraints, `m.check()` works with any solver (including the default HiGHS and GLPK) by falling back to a feasibility `solve()`. Logical constraints (`BoolVar`, `and`, `or`, `implies`, etc.) and unsatisfiable-core extraction (`result.conflicts` / `result.unsatCore`) require an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `conflicts` / `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
+- **Satisfiability & Conflict Diagnosis (`await m.check(options?)`)**:
+  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` is populated when the model is proven `"Unsat"`.
+  - For models containing linear arithmetic constraints or logical constraints (`BoolVar`, `and`, `or`, `implies`, `xor`), `m.check()` works with any solver (including the default HiGHS and GLPK via single-solve elastic slack relaxation, automatically linearizing logical constraints into 0-1 MIP formulation) and diagnoses conflicting constraints as `conflicts` (leaving `unsatCore: undefined` for semantic rigor).
+  - Exact SMT unsatisfiable-core extraction (`result.unsatCore` and `result.conflicts`) is provided when using an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
 - **No concurrent mutation during async solve/check**:
   - Mutating variables, constraints, or the objective while `await m.solve()` or `await m.check()` is pending invalidates the in-flight execution and rejects the stale promise.
 
@@ -163,22 +165,24 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
 ### Getting Started
 
 - [AI Coding Agent Quick-Reference Guide](docs/getting-started/ai-agents.md): This document is the **consumer modeling quick-reference** for AI coding agents and developers building optimization or satisfiability models with `@ohtaman/washi`.
-- [Introduction & Installation](docs/getting-started/index.md): WaSHI brings the algebraic modeling style of Python's **PuLP** and Julia's **JuMP** to the TypeScript and JavaScript ecosystem.
-- [Runtime Environments & Deployment](docs/getting-started/runtimes.md): 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.
-- [Cross-Origin Isolation (Z3 & Browsers)](docs/getting-started/cross-origin.md): When running the **Z3** solver engine inside a web browser, special HTTP headers are required due to browser security models.
+- [Introduction & Installation](docs/getting-started/index.md): **WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface) brings the algebraic modeling style of Python's **PuLP** to the TypeScript and JavaScript ecosystem.
+- [Runtime Environments & Deployment](docs/getting-started/runtimes.md): WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, static hosting, and vanilla browser `<script>` tags—without native C/C++ compilation.
+- [Cross-Origin Isolation (Z3 & Browsers)](docs/getting-started/cross-origin.md): When running the **Z3** solver inside a web browser, Cross-Origin Isolation HTTP headers are required so the browser enables `SharedArrayBuffer`.
 
 ### Modeling Guide
 
-- [Variables & Domains](docs/guide/variables.md): Variables represent the mathematical decision variables in your optimization model.
+- [Variables & Domains](docs/guide/variables.md): Variables represent the mathematical decision variables in your optimization or logical model.
 - [Expressions (`expr`, `sum`, `dot`)](docs/guide/expressions.md): Mathematical expressions are linear or quadratic combinations of decision variables and numeric coefficients.
 - [Constraints (`m.constraint` & `m.indicator`)](docs/guide/constraints.md): Constraints restrict the feasible solution space of your mathematical or logical model.
 - [Objectives & Solving (`m.solve` & `m.check`)](docs/guide/objectives.md): The objective function defines the goal of mathematical optimization—whether to maximize profits, minimize costs, or minimize quadratic risk variance.
-- [Conflict Diagnosis (`unsatCore`) & Solution Validation](docs/guide/unsat-core.md): 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`) & Solution Validation](docs/guide/unsat-core.md): WaSHI provides built-in tools for both: **conflict diagnosis** via built-in HiGHS elastic relaxation or Z3 Unsat Core (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
+- [Decomposition Methods (`solveColumnGeneration` & `solveBenders`)](docs/guide/decomposition.md): When monolithic Mixed-Integer Programming (MIP) models have exponentially many candidate patterns or large multi-stage subproblems, WaSHI provides two high-level decomposition orchestrators—`master.solveColumnGeneration()` and `master.solveBenders()`—along with low-level primitives for dual inspection and dynamic model updates.
+- [Formulation Patterns & Optimization Tips](docs/guide/formulation-tips.md): While the preceding Modeling Guide pages cover WaSHI's APIs (`Model`, `expr`, `m.constraint`, `m.solve`, etc.), this page collects standard mathematical optimization formulation patterns and solver tuning techniques frequently used in linear and mixed-integer programming (LP/MIP).
 
 ### Solvers
 
 - [Solvers Overview](docs/solvers/index.md): WaSHI is designed around a pluggable, decoupled solver architecture.
-- [HiGHS Solver Engine](docs/solvers/highs.md): **HiGHS** is high-performance mathematical optimization software developed at the University of Edinburgh.
+- [HiGHS Solver Engine](docs/solvers/highs.md): **HiGHS** is high-performance mathematical optimization software initiated at the University of Edinburgh (highs.dev · ERGO-Code/HiGHS).
 - [Z3 SMT Solver Engine](docs/solvers/z3.md): **Z3** is a theorem prover and Satisfiability Modulo Theories (SMT) solver developed by Microsoft Research.
 - [GLPK Solver Engine](docs/solvers/glpk.md): 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).
 - [WaSHI Custom Solver Developer Guide](docs/solvers/custom-solver.md): This guide describes how to build, test, and distribute custom solver plugins for **WaSHI** (`@ohtaman/washi`).
@@ -194,4 +198,6 @@ m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
 - [E-Commerce Cart & Coupon Optimizer (Indicator MIP)](docs/examples/ecommerce-coupons.md): 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.
 - [Portfolio Optimization (QP)](docs/examples/portfolio-qp.md): 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.
 - [SMT Security Policies](docs/examples/smt-security.md): Satisfiability Modulo Theories (SMT) combines propositional logic (Boolean SAT) with first-order theories (linear integer arithmetic, real inequalities).
-- [Conflict Diagnosis (Unsat Core)](docs/examples/unsat-core.md): When business rules, budgets, and operational policies grow complex, constraints inevitably conflict.
+- [Conflict Diagnosis (Unsat Core)](docs/examples/unsat-core.md): When business rules, budgets, and operational policies grow complex, constraints can easily conflict.
+- [Capacitated Vehicle Routing Problem (CVRP, 50 Customers via Column Generation)](docs/examples/vehicle-routing.md): The **Capacitated Vehicle Routing Problem (CVRP)** determines the minimum number of delivery vehicles needed to visit a set of customers, subject to vehicle cargo capacity, maximum customer stops per shift, and route duration limits.
+- [Traveling Salesperson Problem (TSP via Benders Decomposition)](docs/examples/traveling-salesperson.md): The **Traveling Salesperson Problem (TSP)** seeks the shortest closed tour that visits every city in a given set once and returns to the starting city.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ohtaman/washi",
-  "version": "0.5.0",
-  "description": "WaSHI: WebAssembly-backed, Solver-independent, High-level modeling Interface (LP, MIP, QP, SMT)",
+  "version": "0.7.0",
+  "description": "WaSHI: WebAssembly-backed Algebraic Modeler for Mathematical Optimization & Constraint Programming (LP, MIP, QP, SMT)",
   "type": "module",
   "main": "./dist/lib/washi.js",
   "module": "./dist/lib/washi.js",
@@ -66,35 +66,39 @@
   ],
   "scripts": {
     "dev": "vite",
+    "ensure:highs": "node scripts/ensure-highs-wasm.mjs",
+    "build:highs-wasm": "bash scripts/build-highs-wasm.sh",
     "build:demo": "vite build",
     "build:types": "node -e \"import('node:fs').then(fs => fs.rmSync('dist/types', { recursive: true, force: true }))\" && tsc -p tsconfig.lib.json",
-    "build:lib": "node scripts/build-library.mjs",
+    "build:lib": "node scripts/ensure-highs-wasm.mjs && node scripts/build-library.mjs",
     "build:llms": "node scripts/generate-llms.mjs",
-    "build": "npm run build:types && npm run build:lib && npm run build:browser && npm run build:demo",
-    "build:site": "node scripts/build-site.mjs",
+    "build": "node scripts/ensure-highs-wasm.mjs && npm run build:types && npm run build:lib && npm run build:browser && npm run build:demo",
+    "build:site": "node scripts/ensure-highs-wasm.mjs && node scripts/build-site.mjs",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs && node scripts/generate-llms.mjs",
     "docs:preview": "vitepress preview docs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:e2e": "RUN_E2E=1 vitest run test/e2e.test.ts",
-    "prepublishOnly": "npm run build:types && npm run build:lib && npm run build:browser && npm run build:llms",
-    "build:browser": "node scripts/build-browser.mjs",
-    "test:distribution": "npm run build:types && npm run build:lib && npm run build:browser && npm run build:llms && node --experimental-vm-modules scripts/check-distribution.mjs",
-    "test:demo": "BASE_URL=/washi/ npm run build:demo && node scripts/check-demo-browser.mjs",
+    "prepublishOnly": "node scripts/ensure-highs-wasm.mjs && npm run build:types && npm run build:lib && npm run build:browser && npm run build:llms",
+    "build:browser": "node scripts/ensure-highs-wasm.mjs && node scripts/build-browser.mjs",
+    "test:distribution": "node scripts/ensure-highs-wasm.mjs && npm run build:types && npm run build:lib && npm run build:browser && npm run build:llms && node --experimental-vm-modules scripts/check-distribution.mjs",
+    "test:demo": "BASE_URL=/ npm run build:demo && node scripts/check-demo-browser.mjs",
     "bench": "node scripts/run-benchmarks.mjs"
   },
   "keywords": [
     "optimization",
     "mathematical-programming",
+    "constraint-programming",
     "linear-programming",
     "mixed-integer-programming",
     "quadratic-programming",
-    "lp",
-    "mip",
-    "qp",
+    "smt",
+    "z3",
     "highs",
     "pulp",
+    "jump",
+    "operations-research",
     "wasm",
     "webassembly",
     "typescript"
@@ -112,10 +116,8 @@
   "bugs": {
     "url": "https://github.com/ohtaman/washi/issues"
   },
-  "homepage": "https://github.com/ohtaman/washi#readme",
-  "dependencies": {
-    "highs": "^1.15.3"
-  },
+  "homepage": "https://washi.ohtaman.dev/",
+  "dependencies": {},
   "peerDependencies": {
     "glpk.js": "^5.0.0",
     "z3-solver": "^5.2.0"
@@ -132,6 +134,7 @@
     "@types/node": "^26.6.3",
     "async-mutex": "^0.3.2",
     "glpk.js": "^5.0.0",
+    "katex": "^0.16.21",
     "mermaid": "^11.17.2",
     "playwright": "^1.63.0",
     "typescript": "^7.0.2",

package/skills/washi/SKILL.md

@@ -16,9 +16,9 @@ Select the solver engine and execution method that match the problem class:
 | Problem Class | Recommended Solver | Setup & Import | Execution Method |
 | :--- | :--- | :--- | :--- |
 | **LP / MIP / Convex QP** (including `m.indicator()` Big-M and `initialValue` warm starts) | **HiGHS** (default) | Built-in (`import { Model } from "@ohtaman/washi"`) | `await m.solve()` |
-| **SMT Propositional Logic** (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`) | **Z3** plugin | `npm install z3-solver` + `import "@ohtaman/washi/solvers/z3"` | `await m.check({ solver: "z3" })` or `await m.solve({ solver: "z3" })` |
-| **Infeasibility / Conflict Diagnosis** (`conflicts` / `unsatCore`) | **Z3** plugin | `npm install z3-solver` + `import "@ohtaman/washi/solvers/z3"` | `await m.check({ solver: "z3" })` |
-| **LP / MIP with GLPK** (GPL-3.0; no QP, SMT, or `initialValue`) | **GLPK** plugin | `npm install glpk.js` + `import "@ohtaman/washi/solvers/glpk"` | `await m.solve({ solver: "glpk" })` |
+| **SMT Propositional Logic** (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`) | **HiGHS** (auto 0-1 MIP) or **Z3** (native SMT) | Built-in for HiGHS; `npm install z3-solver` + `import "@ohtaman/washi/solvers/z3"` for Z3 | `await m.solve()` or `await m.check()` |
+| **Infeasibility / Conflict Diagnosis** (`conflicts` / `unsatCore`) | **HiGHS** (elastic slack `conflicts`) or **Z3** (`unsatCore`) | Built-in for HiGHS; `import "@ohtaman/washi/solvers/z3"` for Z3 | `await m.check()` |
+| **LP / MIP with GLPK** (GPL-3.0; no QP or `initialValue`) | **GLPK** plugin | `npm install glpk.js` + `import "@ohtaman/washi/solvers/glpk"` | `await m.solve({ solver: "glpk" })` |
 
 - **Browser runtime notes**:
   - HiGHS and GLPK load local `.wasm` and Worker assets relative to the bundle (never falling back to an external CDN).
@@ -30,19 +30,19 @@ Select the solver engine and execution method that match the problem class:
 
 1. **Define decision variables on `Model`**:
    - Numeric (`Var`): `m.continuous(nameOrDims, { lb, ub, initialValue })`, `m.integer(...)`, `m.binary(...)`
-   - Propositional boolean (`BoolVar`, for Z3): `m.bool(nameOrDims)`
+   - Propositional boolean (`BoolVar`): `m.bool(nameOrDims)`
    - Indexed containers: pass a count (`number` -> `Var[]` / `Var[][]`) or key array (`readonly string[]` -> `Record<K, Var>` / `Record<R, Record<C, Var>>`).
    - Provide finite `lb` and `ub` bounds whenever known—especially on variables used in `m.indicator()` so WaSHI can automatically derive a tight Big-M when `M` is omitted.
 2. **Build expressions (`expr`, `sum`, `dot`)**:
-   - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${y} - 10` ``
-   - Quadratic expression (`QuadExpr`, **objectives only**): `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``
-   - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${y} <= 40` `` (supports `<=`, `>=`, `==`, `=`)
-   - Vector aggregations: `sum(iterable, mapper?)` and `dot(a, b)`
-   - Propositional logic (for Z3): `and(...)`, `or(...)`, `not(...)`, `implies(a, b)`, `xor(a, b)` (or fluent `.and()`, `.or()`, `.not()`, `.implies()`, `.xor()`)
+   - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${y} - 10` ``, `` expr`dot(${profit}, ${qty}) - 20 * ${lineOpen}` ``
+   - Quadratic expression (`QuadExpr`, **objectives only**): `` expr`${x}^2 + 2 * ${x} * ${y} + ${y}^2` ``, `` expr`sum((${xVec} - ${target})^2)` `` (purely continuous models on HiGHS; MIQP with integer/binary/boolean variables is not supported)
+   - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${y} <= 40` ``, `` expr`sum(${qty}) <= 100` `` (supports `<=`, `>=`, `==`, `=`)
+   - Vector & Record aggregations: `sum(containerOrItems, mapper?)` and `dot(a, b)` (both usable inside `expr` or standalone; `sum` accepts 1D/2D `Array`, `Iterable`, and `Record` directly without `Object.values()`, plus element-wise container arithmetic `+`, `-`, `*`, `/`, `^2` inside `expr`; `dot` computes the 1D inner product or 2D Frobenius inner product)
+   - Propositional logic: `and(...)`, `or(...)`, `not(...)`, `implies(a, b)`, `xor(a, b)` (or fluent `.and()`, `.or()`, `.not()`, `.implies()`, `.xor()`). Automatically linearized into 0-1 MIP binary variables and linear constraints on HiGHS/GLPK, or solved natively on Z3.
 3. **Register objective and named constraints**:
    - Constructing an `expr` or `.le()` / `.ge()` / `.eq()` object does **not** attach it to the model.
    - Register the objective with `m.objective(maximize(e))` or `m.objective(minimize(e))`.
-   - Register every constraint with a descriptive name: `m.constraint(c, "resource_limit")` or `m.indicator(binVar, c, { activeValue: 1, name: "cap_when_open" })`. Descriptive names are essential for LP inspection and Z3 `unsatCore` conflict diagnosis.
+   - Register every constraint with a descriptive name: `const limit = m.constraint(c, "resource_limit")` (returns the registered `Constraint` / `BoolExpr`, or array for batch inputs) or `m.indicator(binVar, c, { activeValue: 1, name: "cap_when_open" })`. Descriptive names are essential for LP inspection and conflict diagnosis (`conflicts` / `unsatCore`).
 
 ---
 
@@ -65,8 +65,8 @@ Never report a model solution as final without executing the verification step:
    - If `report.valid === false`, inspect `report.violations`, `report.missingVariables`, `report.uncheckedConstraints`, and `report.maxViolation`.
    - Note: `m.validateSolution()` independently checks variable finiteness, variable bounds (`lb`/`ub`), integrality (`Integer`, `Binary`, `BoolVar`), linear constraint residuals, and logical constraints. It does **not** recompute `m.objectiveValue` or verify natural-language problem coverage.
 2. **When a model is infeasible (`"Infeasible"` or `"Unsat"`)**:
-   - Run `const res = await m.check({ solver: "z3" })`.
-   - When `res.status === "Unsat"`, inspect `res.conflicts` (alias for `res.unsatCore`, also stored on `m.conflicts` / `m.unsatCore`).
+   - Run `const res = await m.check()` (diagnoses with built-in HiGHS via single-solve elastic slack relaxation) or `const res = await m.check({ solver: "z3" })` (for exact SMT unsat core).
+   - When `res.status === "Unsat"`, inspect `res.conflicts` (also stored on `m.conflicts`). On HiGHS, `conflicts` reports the subset of constraints requiring relaxation to restore feasibility (with `unsatCore: undefined` for semantic rigor). On Z3, both `unsatCore` and `conflicts` report the contradictory constraint subset.
    - Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking named constraints, `res.conflicts` returns a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (not guaranteed minimal).
 
 ---
@@ -88,10 +88,10 @@ export async function solveAndVerifyMip() {
   const qty = m.integer(products, { lb: 0, ub: 100 });
   const lineOpen = m.binary("lineOpen");
 
-  m.objective(maximize(expr`${dot(profit, qty)} - 20 * ${lineOpen}`));
-  m.constraint(expr`${dot(woodPerUnit, qty)} <= 40`, "wood_limit");
-  m.constraint(expr`${dot(laborPerUnit, qty)} <= 50`, "labor_limit");
-  m.indicator(lineOpen, expr`${sum(Object.values(qty))} <= 0`, {
+  m.objective(maximize(expr`dot(${profit}, ${qty}) - 20 * ${lineOpen}`));
+  m.constraint(expr`dot(${woodPerUnit}, ${qty}) <= 40`, "wood_limit");
+  m.constraint(expr`dot(${laborPerUnit}, ${qty}) <= 50`, "labor_limit");
+  m.indicator(lineOpen, expr`sum(${qty}) <= 0`, {
     activeValue: 0,
     name: "closed_line_zero_output",
   });
@@ -191,7 +191,11 @@ export async function diagnoseAndVerifyWithZ3() {
 
 ## 6. Guardrails & Common Pitfalls
 
-- **No quadratic constraints**: Quadratic terms (`${x}^2`, `${x} * ${y}`) are only valid in `m.objective(...)`. Using them in `m.constraint(...)` throws `"Quadratic constraints are not supported"`.
+- **No quadratic constraints or MIQP**: Quadratic terms (`${x}^2`, `${x} * ${y}`) are only valid in `m.objective(...)` (using them in `m.constraint(...)` throws `"Quadratic constraints are not supported"`), and built-in HiGHS requires Convex QP models to contain only continuous variables (`m.continuous`).
 - **Do not confuse `LinExpr` and `Constraint`**: `m.objective(maximize(...))` requires a `LinExpr`, `QuadExpr`, `Var`, or `number` (never a `Constraint`). `m.constraint(...)` requires a `Constraint` (with `<=`, `>=`, `==`, or `=`) or `BoolExpr` (never a bare `LinExpr`).
 - **Do not mutate during async solve/check**: Modifying variables, bounds, constraints, or the objective while `await m.solve()` or `await m.check()` is pending invalidates the in-flight run and rejects the promise.
 - **Do not use retired aliases**: Always use `expr` (not `c`), `m.constraint(...)` (not `m.constrain` or `m.add`), `m.objective(maximize(...))` (not `m.maximize` or `m.setObjective`), `await m.solve()` (not `m.optimize`), `.le()` / `.ge()` / `.eq()` (not `.lessThanOrEqual()`), `.value` / `m.getValues(...)` (not `.getValue()`), and `m.variables` / `m.constraints` (not `m.vars` / `m.constrs`).
+- **Practical OR formulation guardrails**:
+  - **Prefer inequalities (`>=` / `<=`) over `==`** for demand coverage and capacity limits when costs are non-negative; reserve `==` for flow conservation or normalization identities.
+  - **Provide finite `lb` and `ub` bounds** on variables inside `m.indicator(...)` and omit `M` so WaSHI automatically derives the tightest valid Big-M instead of a loose `1e6` fallback.
+  - **Use soft constraints (non-negative slack variables)** with tiered objective penalties for non-rigid business targets (preferred staffing, safety stock, day-off requests) so minor data contention produces a prioritized trade-off rather than `"Infeasible"`.