@ohtaman/washi 0.4.0 → 0.6.0

package/llms.txt

@@ -0,0 +1,201 @@
+# WaSHI (@ohtaman/washi)
+
+> 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.
+
+- 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)
+
+---
+
+## 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 & Key Rules
+
+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 & 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.
+
+---
+
+## 3. Common Pitfalls & Retired Aliases
+
+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`
+
+---
+
+## 4. Canonical English Documentation Index
+
+### 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.
+
+### Modeling Guide
+
+- [Variables & Domains](docs/guide/variables.md): Variables represent the mathematical decision variables in your optimization 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`).
+- [Advanced Decomposition Methods & Best Practices](docs/guide/decomposition.md): Mixed-Integer Programming (MIP) formulations can become slow when symmetry or coupling constraints cause branch-and-bound trees to grow large.
+
+### 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 (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`).
+
+### Examples
+
+- [Examples & API Finder](docs/examples/index.md): Explore runnable optimization and logic formulations built with WaSHI.
+- [Production Planning (LP / MIP)](docs/examples/production.md): 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).
+- [0-1 Knapsack Problem (Binary MIP)](docs/examples/knapsack.md): 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.
+- [Transportation & Allocation Network (LP)](docs/examples/transportation.md): 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.
+- [Diet Problem & Sensitivity Analysis (LP Duals & Slacks)](docs/examples/diet-sensitivity.md): When solving a Linear Programming model, the optimal variable values (`var.value`) are only half the story.
+- [Staff Shift Scheduling & Conflict Diagnosis (MIP + Z3)](docs/examples/shift-scheduling.md): Staff shift scheduling is a classic real-world application of Mixed-Integer Programming in SaaS and workforce management tools.
+- [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.
+- [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.4.0",
-  "description": "WaSHI: WebAssembly-backed, Solver-independent, High-level modeling Interface (LP, MIP, QP, SMT)",
+  "version": "0.6.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",
@@ -48,6 +48,16 @@
     "dist/lib",
     "dist/browser",
     "dist/types",
+    "docs/getting-started/ai-agents.md",
+    "docs/ja/getting-started/ai-agents.md",
+    "docs/zh/getting-started/ai-agents.md",
+    "docs/getting-started",
+    "docs/guide",
+    "docs/solvers",
+    "docs/examples",
+    "skills/washi/SKILL.md",
+    "llms.txt",
+    "llms-full.txt",
     "README.md",
     "README.ja.md",
     "README.zh-CN.md",
@@ -56,33 +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": "npm run build:types && npm run build:lib && npm run build:browser && npm run build:demo",
-    "build:site": "node scripts/build-site.mjs",
+    "build:lib": "node scripts/ensure-highs-wasm.mjs && node scripts/build-library.mjs",
+    "build:llms": "node scripts/generate-llms.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",
+    "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",
-    "build:browser": "node scripts/build-browser.mjs",
-    "test:distribution": "npm run build:types && npm run build:lib && npm run build:browser && 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=/washi/ 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"
@@ -101,9 +117,7 @@
     "url": "https://github.com/ohtaman/washi/issues"
   },
   "homepage": "https://github.com/ohtaman/washi#readme",
-  "dependencies": {
-    "highs": "^1.15.3"
-  },
+  "dependencies": {},
   "peerDependencies": {
     "glpk.js": "^5.0.0",
     "z3-solver": "^5.2.0"
@@ -118,7 +132,9 @@
   },
   "devDependencies": {
     "@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

@@ -0,0 +1,197 @@
+---
+name: washi
+description: Formulate, inspect, solve, and verify mathematical optimization (LP, MIP, convex QP) and SMT satisfiability or unsat-core models in TypeScript and JavaScript using @ohtaman/washi (HiGHS, Z3, GLPK).
+---
+
+# WaSHI Modeling & Verification Skill
+
+Use this skill when building, debugging, or verifying mathematical optimization (LP, MIP, convex QP) or satisfiability (SMT / SAT) models with `@ohtaman/washi`. For the full API reference and browser/bundler deployment rules, see [`docs/getting-started/ai-agents.md`](https://github.com/ohtaman/washi/blob/main/docs/getting-started/ai-agents.md) (available locally at `node_modules/@ohtaman/washi/docs/getting-started/ai-agents.md` in consumer projects or `docs/getting-started/ai-agents.md` in the repository).
+
+---
+
+## 1. Problem & Solver Selection
+
+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`) | **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).
+  - Z3 uses `SharedArrayBuffer` pthreads and requires `window.isSecureContext === true` and `window.crossOriginIsolated === true` (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp`).
+
+---
+
+## 2. Algebraic Formulation Workflow
+
+1. **Define decision variables on `Model`**:
+   - Numeric (`Var`): `m.continuous(nameOrDims, { lb, ub, initialValue })`, `m.integer(...)`, `m.binary(...)`
+   - 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: `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 conflict diagnosis (`conflicts` / `unsatCore`).
+
+---
+
+## 3. Model Inspection (`validateIntegrity` & `toLpString`)
+
+Before solving or when debugging formulation bugs:
+
+- **`m.validateIntegrity()`**: Validates variable ownership (variables and constraints cannot be shared across `Model` instances), bound sanity (`lb <= ub`, finite `initialValue` within bounds/integrality tolerance `1e-6`), and finite objective/constraint coefficients.
+- **`m.toLpString()`**: Calls `validateIntegrity()` and exports the numeric LP / MIP / QP formulation in standard CPLEX LP format (`Maximize` / `Minimize`, `Subject To`, `Bounds`, `General`, `Binary`, `End`). Inspect this string to confirm objective sense, signs, coefficients, and right-hand sides match the mathematical specification.
+
+---
+
+## 4. Execution & Mandatory Self-Verification
+
+Never report a model solution as final without executing the verification step:
+
+1. **After `const status = await m.solve(options?)`**:
+   - Verify `status === "Optimal"` (or `status === "Feasible"` / `m.hasPrimalSolution === true` when solver limits apply).
+   - Call `const report = m.validateSolution()` and assert `report.valid === true`.
+   - 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()` (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).
+
+---
+
+## 5. Executable Workflow Recipes
+
+### Recipe 1: MIP Formulation, `toLpString()` Inspection & `validateSolution()` Verification
+
+```ts
+import { Model, expr, dot, sum, maximize } from "@ohtaman/washi";
+
+export async function solveAndVerifyMip() {
+  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 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`, {
+    activeValue: 0,
+    name: "closed_line_zero_output",
+  });
+
+  // 1. Pre-solve integrity & LP formulation inspection
+  m.validateIntegrity();
+  const lpText = m.toLpString();
+
+  // 2. Solve with default HiGHS solver
+  const status = await m.solve();
+
+  // 3. Mandatory independent solution verification
+  const report = m.validateSolution();
+
+  return {
+    status,
+    lpText,
+    objectiveValue: m.objectiveValue,
+    quantities: m.getValues(qty),
+    lineOpen: lineOpen.value,
+    valid: report.valid,
+    maxViolation: report.maxViolation,
+  };
+}
+```
+
+### Recipe 2: Convex Quadratic Programming (QP) & Verification
+
+```ts
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+export async function solveAndVerifyQp() {
+  const m = new Model("AllocationQP");
+  const x = m.continuous("x", { lb: 0 });
+  const y = m.continuous("y", { lb: 0 });
+
+  m.objective(minimize(expr`${x}^2 + ${y}^2`));
+  m.constraint(expr`${x} + ${y} >= 4`, "target_total");
+
+  const lpText = m.toLpString();
+  const status = await m.solve();
+  const report = m.validateSolution();
+
+  return {
+    status,
+    lpText,
+    objectiveValue: m.objectiveValue,
+    x: x.value,
+    y: y.value,
+    valid: report.valid,
+  };
+}
+```
+
+### Recipe 3: Z3 Propositional Logic, `unsatCore` Conflict Diagnosis & Verification
+
+```ts
+import { Model, expr, implies } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+export async function diagnoseAndVerifyWithZ3() {
+  // Part A: Diagnose conflicting rules with Z3 unsatCore / conflicts
+  const unsatModel = new Model("PolicyConflict", { solver: "z3" });
+  const vip = unsatModel.bool("vip");
+  const discount = unsatModel.integer("discount", { lb: 0, ub: 50 });
+
+  unsatModel.constraint(vip, "customer_is_vip");
+  unsatModel.constraint(implies(vip, expr`${discount} >= 20`), "vip_min_discount");
+  unsatModel.constraint(expr`${discount} <= 10`, "campaign_cap");
+
+  const unsatRes = await unsatModel.check();
+
+  // Part B: Relax the conflicting cap and verify the satisfiable assignment
+  const satModel = new Model("PolicyResolved", { solver: "z3" });
+  const vipSat = satModel.bool("vip");
+  const discountSat = satModel.integer("discount", { lb: 0, ub: 50 });
+
+  satModel.constraint(vipSat, "customer_is_vip");
+  satModel.constraint(implies(vipSat, expr`${discountSat} >= 20`), "vip_min_discount");
+  satModel.constraint(expr`${discountSat} <= 25`, "campaign_cap");
+
+  const satRes = await satModel.check();
+  const report = satModel.validateSolution();
+
+  return {
+    unsatStatus: unsatRes.status,
+    conflicts: unsatRes.conflicts,
+    unsatCore: unsatRes.unsatCore,
+    satStatus: satRes.status,
+    resolvedDiscount: discountSat.value,
+    valid: report.valid,
+  };
+}
+```
+
+---
+
+## 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"`.
+- **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`).