@ohtaman/washi 0.6.0 → 0.7.0

package/docs/getting-started/runtimes.md

@@ -1,12 +1,14 @@
 # Runtime Environments & Deployment
 
-WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, vanilla browser `<script>` tags, and air-gapped intranets—without native C/C++ compilation.
+WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, static hosting, and vanilla browser `<script>` tags—without native C/C++ compilation.
 
 ---
 
-## 🟢 Node.js
+## 🟢 Node.js, Bun & Deno
 
-WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package.
+### Node.js
+
+WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package:
 
 ```typescript
 import { Model, expr, maximize } from "@ohtaman/washi";
@@ -19,8 +21,10 @@ m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
 m.constraint(expr`${x} + ${y} <= 15`, "capacity");
 
 await m.solve();
-console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
-console.log(`x = ${x.value}, y = ${y.value}`);
+if (m.hasPrimalSolution) {
+  console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
+  console.log(`x = ${x.value}, y = ${y.value}`);
+}
 ```
 
 Run directly with `tsx` or `node`:
@@ -29,11 +33,33 @@ Run directly with `tsx` or `node`:
 npx tsx app.ts
 ```
 
+### Bun & Deno
+
+```bash
+# Bun
+bun add @ohtaman/washi
+bun run app.ts
+```
+
+In Deno (v1.30+ with `npm:` specifiers):
+
+```typescript
+import { Model, maximize } from "npm:@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0, ub: 10 });
+m.objective(maximize(x));
+await m.solve();
+if (m.hasPrimalSolution) {
+  console.log("x =", x.value);
+}
+```
+
 ---
 
-## 🌐 Bundlers (Vite, Webpack, Rollup, Next.js)
+## 🌐 Bundlers & Static Hosting (Vite, Next.js, Webpack, Rollup)
 
-### Modern Bundlers (Vite / Rollup / Webpack)
+### Modern Bundlers & Static Deployment
 
 When importing `@ohtaman/washi` in a browser bundler, the `browser` export condition resolves automatically:
 
@@ -45,14 +71,16 @@ export async function runOptimization() {
   const x = m.continuous("x", { lb: 0, ub: 100 });
   m.objective(maximize(x));
   await m.solve();
-  return x.value;
+  return m.hasPrimalSolution ? x.value : null;
 }
 ```
 
+Because both the modeler and solver run on WebAssembly, the static output of `vite build` (or your bundler's production build) can be deployed directly to **GitHub Pages, Cloudflare Pages, Vercel, or Netlify** with no backend server required. (The default HiGHS and GLPK solvers require no special HTTP headers; if you use Z3 in the browser, see [Cross-Origin Isolation](./cross-origin.md).)
+
 #### Background Web Worker Execution (Default)
-In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so long-running LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
+In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
 
-If your environment prohibits Web Workers or you explicitly want synchronous main-thread execution, pass `useWorker: false`:
+If your environment prohibits Web Workers or you explicitly want main-thread execution, pass `useWorker: false`:
 
 ```typescript
 await m.solve({ useWorker: false });
@@ -91,7 +119,9 @@ export default function OptimizerComponent() {
     const x = m.continuous("x", { lb: 0, ub: 50 });
     m.objective(maximize(x));
     await m.solve();
-    setVal(x.value);
+    if (m.hasPrimalSolution) {
+      setVal(x.value);
+    }
   };
 
   return (
@@ -107,36 +137,36 @@ export default function OptimizerComponent() {
 
 ## 📦 Browser ESM (`<script type="module">`)
 
-You can import the pre-bundled browser ESM modules directly from a local static server (or from an npm CDN once a compatible release is published) without a build step:
+Without a bundler, you can import the pre-built browser ESM module directly from your own static server or an npm CDN:
 
 ```html
 <script type="module">
-  // Serve from your local static server / dist:
-  import { Model, expr, maximize } from "./dist/browser/washi.js";
-  // Or from an npm CDN once a compatible release is published:
-  // import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.js";
+  // From an npm CDN (or "./dist/browser/washi.js" when self-hosted):
+  import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.js";
   // Optional solver plugins:
-  // import "./dist/browser/solvers/glpk.js";
-  // import "./dist/browser/solvers/z3.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.js";
+  // import "https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.js";
 
   const m = new Model("BrowserESM");
-  const x = m.integer("x", { lb: 0 });
-  const y = m.integer("y", { lb: 0 });
+  const x = m.integer("x", { lb: 0, ub: 100 });
+  const y = m.integer("y", { lb: 0, ub: 100 });
 
   m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
   m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
   m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor");
 
   await m.solve();
-  console.log("Optimal Objective:", m.objectiveValue);
+  if (m.hasPrimalSolution) {
+    console.log("Optimal Objective:", m.objectiveValue);
+  }
 </script>
 ```
 
 ---
 
-## 🟨 Classic `<script>` Tags (IIFE / Standalone Build / CDN)
+## 🟨 Classic `<script>` Tags (IIFE / Standalone HTML / CDN)
 
-For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
+For single-file HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
 
 ```html
 <!DOCTYPE html>
@@ -149,13 +179,11 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
     <h1>WaSHI Browser Optimization</h1>
     <pre id="output">Solving...</pre>
 
-    <!-- Core WaSHI + HiGHS (MIT) from local static build / assets -->
-    <script src="./dist/browser/washi.min.js"></script>
-    <!-- Or via CDN once a compatible release is published: -->
-    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js"></script> -->
+    <!-- Core WaSHI + HiGHS (MIT) via CDN (or "./dist/browser/washi.min.js" when self-hosted) -->
+    <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/washi.min.js"></script>
     <!-- Optional plugins (auto-register on window.Washi): -->
-    <!-- <script src="./dist/browser/solvers/glpk.min.js"></script> -->
-    <!-- <script src="./dist/browser/solvers/z3.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/glpk.min.js"></script> -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.6/dist/browser/solvers/z3.min.js"></script> -->
 
     <script>
       (async () => {
@@ -170,10 +198,12 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 
         await m.solve();
 
-        document.getElementById("output").textContent =
-          `Status: ${m.status}\n` +
-          `Objective: ${m.objectiveValue}\n` +
-          `x = ${x.value}, y = ${y.value}`;
+        if (m.hasPrimalSolution) {
+          document.getElementById("output").textContent =
+            `Status: ${m.status}\n` +
+            `Objective: ${m.objectiveValue}\n` +
+            `x = ${x.value}, y = ${y.value}`;
+        }
       })();
     </script>
   </body>
@@ -181,7 +211,7 @@ For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard
 ```
 
 > [!NOTE]
-> When loading `washi.min.js` from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction due to the same-origin policy. WaSHI automatically bridges cross-origin workers via a lightweight `Blob` wrapper using `importScripts()`, so Web Worker execution works out of the box from CDNs.
+> When loading from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction under the same-origin policy. On standard web origins (`https://` / `http://`), WaSHI automatically bridges cross-origin workers via a lightweight ES module `Blob` bootstrap (`import "https://..."`). On opaque effective origins (`window.origin === "null"`, such as local `file:` URLs or `sandbox="allow-scripts"` `<iframe>` embeds without `allow-same-origin`), WaSHI automatically runs HiGHS on the main thread when `useWorker` is omitted.
 
 ---
 
@@ -195,33 +225,8 @@ WaSHI never phones home or falls back to public CDNs. To self-host in an air-gap
    - Optional Z3: `solvers/z3.js` / `solvers/z3.min.js`, `solvers/z3-built.js`, `solvers/z3-built.wasm`
 2. **Content Security Policy (CSP) Headers**:
    - Allow WebAssembly compilation (`'wasm-unsafe-eval'` in `script-src`).
-   - If using the default Web Worker or cross-origin Blob worker fallback, allow `worker-src 'self' blob:;`.
+   - If using the default Web Worker or cross-origin Blob worker bootstrap, allow `worker-src 'self' blob:;`.
    - If `blob:` workers are prohibited by policy, either serve `highs-worker.js` from `'self'` or run on the main thread with `await m.solve({ useWorker: false })`.
 3. **Cross-Origin Isolation (Z3 Only)**:
    - HiGHS and GLPK run in standard browser contexts without special headers.
-   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). See the [Cross-Origin Isolation Guide](./cross-origin.md) for setup details.
-
----
-
-## ⚡ Bun & Deno
-
-### Bun
-
-```bash
-bun add @ohtaman/washi
-bun run app.ts
-```
-
-### Deno
-
-In Deno (v1.30+ with `npm:` specifiers):
-
-```typescript
-import { Model, maximize } from "npm:@ohtaman/washi";
-
-const m = new Model();
-const x = m.continuous("x", { lb: 0, ub: 10 });
-m.objective(maximize(x));
-await m.solve();
-console.log("x =", x.value);
-```
+   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (`credentialless` works in Chromium/Firefox, whereas Safari requires `require-corp`). See the [Cross-Origin Isolation Guide](./cross-origin.md) for setup details.

package/docs/guide/constraints.md

@@ -1,17 +1,17 @@
 # Constraints (`m.constraint` & `m.indicator`)
 
 Constraints restrict the feasible solution space of your mathematical or logical model.
-In WaSHI, both linear arithmetic constraints and propositional SMT formulas are registered using **`m.constraint()`**:
+In WaSHI, both linear arithmetic constraints and propositional logic formulas are registered using **`m.constraint()`**:
 
 ```typescript
-m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_limit");
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
 ```
 
 ---
 
-## ✍️ Algebraic Linear Constraints (`expr`)
+## Algebraic Linear Constraints (`expr`)
 
-The `expr` tagged template literal syntax allows writing equations and inequalities with natural mathematical notation:
+The `expr` tagged template literal allows writing equations and inequalities with standard mathematical notation:
 
 ```typescript
 import { Model, expr } from "@ohtaman/washi";
@@ -30,13 +30,15 @@ m.constraint(expr`3 * ${x} + ${y} >= 20`, "min_demand");
 m.constraint(expr`${x} + ${y} == 30`, "exact_quota");
 ```
 
+`m.constraint()` returns the registered `Constraint` (or `BoolExpr` for logical formulas), or an array when passed a batch array.
+
 ### Supported Comparison Operators
 - `<=`: Upper bound constraint
 - `>=`: Lower bound constraint
 - `==` or `=`: Exact equality constraint
 
 ### Batch Registration
-You can pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
+Pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
 
 ```typescript
 m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
@@ -44,50 +46,51 @@ m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
 
 ---
 
-## 🏷️ Naming Constraints
+## Naming Constraints
 
-Every constraint can be given a unique, descriptive name as the second argument of `m.constraint(c, name)`:
+Pass a unique, descriptive name as the second argument of `m.constraint(c, name)`:
 
 ```typescript
 m.constraint(expr`${x} + ${y} <= 100`, "budget_cap");
 ```
 
 ### Why Name Constraints?
-1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the exact generated formulation.
-2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, Z3 `m.check()` returns the exact constraint names forming the conflicting subset.
+1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the generated formulation.
+2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, `m.check()` returns the conflicting constraint names (via built-in HiGHS elastic relaxation or Z3 `unsatCore`).
 3. **Direct Lookup (`m.getConstraintByName()`)**: Retrieve a constraint by name after solving to inspect its `dual` or `slack` value.
 
 ---
 
-## 🔁 Adding Constraints over Iterables & Sums
+## Aggregated Constraints (`sum` & `dot`)
 
-Use `sum()` or `dot()` inside `expr` to express linear aggregations cleanly:
+Use `sum(...)` and `dot(..., ...)` directly inside `expr` to express linear aggregations over arrays and dictionaries cleanly:
 
 ```typescript
-import { Model, sum, expr } from "@ohtaman/washi";
+import { Model, expr } from "@ohtaman/washi";
 
-const items = ["A", "B", "C"];
+const m = new Model();
+const items = ["A", "B", "C"] as const;
 const weights = { A: 5, B: 10, C: 15 };
 const selected = m.binary(items);
 
+// Select at most 2 items
+m.constraint(expr`sum(${selected}) <= 2`, "max_items");
+
 // Total weight cannot exceed capacity 25
-m.constraint(
-  expr`${sum(items, (i) => selected[i].mul(weights[i]))} <= 25`,
-  "capacity_limit"
-);
+m.constraint(expr`dot(${weights}, ${selected}) <= 25`, "capacity_limit");
 ```
 
 ---
 
-## 🎯 Conditional / Indicator Constraints (`m.indicator`)
+## Conditional / Indicator Constraints (`m.indicator`)
 
-When a linear constraint should only take effect when a binary decision variable is active (`1` or `0`), use `m.indicator()`:
+When a linear constraint should only take effect when a binary decision variable (`m.binary()`) equals `1` (or `0`), use `m.indicator()`:
 
 ```typescript
 const useDiscount = m.binary("use_discount");
 const cartTotal = m.continuous("cart_total", { lb: 0, ub: 10_000 });
 
-// If useDiscount == 1, then cartTotal >= 100
+// If useDiscount == 1, enforce cartTotal >= 100
 // WaSHI automatically derives a safe, tight Big-M from the variable bounds
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
   activeValue: 1,
@@ -97,16 +100,16 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 
 ### Safe Automatic Big-M Derivation & Bounds
 
-When `options.M` is omitted, WaSHI automatically derives a safe, minimal Big-M value from the finite variable bounds:
+When `options.M` is omitted, WaSHI automatically derives a minimal valid Big-M value from finite variable bounds (`lb` and `ub`):
 - For `<=` constraints, variables with positive coefficients require finite upper bounds (`ub`), and negative coefficients require finite lower bounds (`lb`).
 - For `>=` constraints, variables with positive coefficients require finite lower bounds (`lb`), and negative coefficients require finite upper bounds (`ub`).
-- For `==` constraints, safe bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
+- For `==` constraints, bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
 
-If any referenced variable lacks the required finite bounds, `m.indicator()` throws an actionable error prompting for finite bounds or an explicit `options.M`.
+If any referenced variable lacks the required finite bound, `m.indicator()` throws an error prompting for finite bounds or an explicit `options.M`.
 
-### Explicit Override & Numerical Stability
+### Explicit `M` Override
 
-You can override the derived Big-M by providing `{ M: number }`:
+You can override the derived Big-M by passing `{ M: number }`:
 
 ```typescript
 m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
@@ -116,15 +119,13 @@ m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
 ```
 
 > [!TIP]
-> **Numerical Stability vs. Correctness**:
-> An $M$ value that is too small can inadvertently cut off valid solutions. Conversely, an excessively large $M$ (e.g., $10^9$) causes poor matrix conditioning and numerical instability in MIP solvers.
-> By setting explicit, realistic variable bounds (`lb` and `ub`), WaSHI derives the tightest possible safe Big-M automatically.
+> **Prefer Finite Variable Bounds Over Arbitrary Large `M`**: An $M$ value that is too small can cut off valid feasible solutions, whereas an excessively large $M$ (e.g., $10^9$) degrades numerical conditioning in MIP solvers. Setting realistic `lb` and `ub` bounds on variables lets WaSHI compute the tightest safe Big-M automatically.
 
 ---
 
-## 🧠 Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
+## Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
 
-When solving with the **Z3** SMT engine (`@ohtaman/washi/solvers/z3`), you can combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`) using first-class logical operators:
+WaSHI provides first-class logical operators to combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`). Logical formulas are solved natively by the **Z3** SMT adapter (`@ohtaman/washi/solvers/z3`) and automatically linearized to 0-1 MIP constraints on **HiGHS** and **GLPK**:
 
 ```typescript
 import { Model, expr, and, or, not, implies, xor } from "@ohtaman/washi";
@@ -133,14 +134,14 @@ import "@ohtaman/washi/solvers/z3";
 const m = new Model({ solver: "z3" });
 const isAdmin = m.bool("isAdmin");
 const hasMfa = m.bool("hasMfa");
-const Clearance = m.integer("clearance", { lb: 0, ub: 5 });
+const clearance = m.integer("clearance", { lb: 0, ub: 5 });
 
 // Method syntax on BoolVar / BoolOp:
 m.constraint(isAdmin.implies(hasMfa), "admin_requires_mfa");
 
 // Mixing boolean propositions with linear arithmetic comparisons:
 m.constraint(
-  implies(isAdmin, expr`${Clearance} >= 4`),
+  implies(isAdmin, expr`${clearance} >= 4`),
   "admin_clearance_level"
 );
 
@@ -155,23 +156,28 @@ m.constraint(and(or(isAdmin, hasMfa), not(xor(isAdmin, hasMfa))), "policy");
 | **Trigger variable** | Numeric `Binary` variable (`m.binary()`) | `BoolVar` (`m.bool()`), `BoolOp`, or `Constraint` |
 | **Consequent** | Linear `Constraint` (`<=`, `>=`, `==`) | `BoolVar`, `BoolOp`, or linear `Constraint` |
 | **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **All solvers** (HiGHS and GLPK via automatic 0-1 MIP linearization, Z3 natively) |
-| **Best For** | Operations research & MIP optimization with an objective (`m.solve()`) | Rule engines, policy verification, and SMT feasibility (`m.check()`) |
+| **Primary Use Case** | MIP optimization models with arithmetic binary variables (`m.solve()`) | Logical rule systems and SMT feasibility (`m.check()`) |
+
+> [!NOTE]
+> **General Inequality Antecedents in `implies()`**: On **Z3** (`solver: "z3"`), the antecedent `a` in `implies(a, b)` can be any linear inequality—for example, ``implies(expr`${clearance} >= 4`, hasMfa)`` using `clearance` and `hasMfa` above. On MIP solvers (**HiGHS** / **GLPK**), conditional constraints should use a `BoolVar` (`m.bool()`) antecedent or `m.indicator(binVar, constraint)` with a `Binary` trigger variable.
 
 ---
 
-## 📐 Dual Values, Shadow Prices & Lookups
+## Dual Values, Shadow Prices & Lookups
 
-For continuous Linear Programming (LP) problems, query the economic shadow price (`dual`) and surplus (`slack`) on each constraint:
+For continuous Linear Programming (LP) problems, query the shadow price (`dual`) and surplus (`slack`) on each constraint (returned by `m.constraint()` or looked up via `m.getConstraintByName()`):
 
 ```typescript
-m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
+const woodConstraint = m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
 
 await m.solve();
 
-const woodConstraint = m.getConstraintByName("wood");
-console.log("Shadow price (dual):", woodConstraint?.dual);
-console.log("Slack surplus:", woodConstraint?.slack);
+console.log("Shadow price (dual):", woodConstraint.dual);
+console.log("Slack surplus:", woodConstraint.slack);
 console.log("Total linear constraints:", m.numConstrs);
 ```
 
-For logical constraints registered with a name, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+For named logical constraints, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.
+
+> [!TIP]
+> For modeling techniques such as **soft constraints with slack variables** and **symmetry breaking**, see [Formulation Patterns & Optimization Tips](./formulation-tips.md#_3-constraint-design-numerical-conditioning).