@ohtaman/washi 0.4.0 → 0.6.0

package/docs/getting-started/runtimes.md

@@ -0,0 +1,227 @@
+# Runtime Environments & Deployment
+
+WaSHI runs across JavaScript and TypeScript runtimes—from Node.js, Bun, and Deno to modern bundlers, vanilla browser `<script>` tags, and air-gapped intranets—without native C/C++ compilation.
+
+---
+
+## 🟢 Node.js
+
+WaSHI supports Node.js (v18+) out of the box with standard ECMAScript Modules (ESM). The built-in HiGHS WebAssembly binary is loaded directly from the installed package.
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+const m = new Model("NodeExample");
+const x = m.continuous("x", { lb: 0, ub: 10 });
+const y = m.continuous("y", { lb: 0, ub: 20 });
+
+m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
+m.constraint(expr`${x} + ${y} <= 15`, "capacity");
+
+await m.solve();
+console.log(`Status: ${m.status}, Objective: ${m.objectiveValue}`);
+console.log(`x = ${x.value}, y = ${y.value}`);
+```
+
+Run directly with `tsx` or `node`:
+
+```bash
+npx tsx app.ts
+```
+
+---
+
+## 🌐 Bundlers (Vite, Webpack, Rollup, Next.js)
+
+### Modern Bundlers (Vite / Rollup / Webpack)
+
+When importing `@ohtaman/washi` in a browser bundler, the `browser` export condition resolves automatically:
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+export async function runOptimization() {
+  const m = new Model({ solver: "highs" });
+  const x = m.continuous("x", { lb: 0, ub: 100 });
+  m.objective(maximize(x));
+  await m.solve();
+  return x.value;
+}
+```
+
+#### Background Web Worker Execution (Default)
+In browsers, HiGHS automatically runs inside a dedicated **Web Worker** so long-running LP/MIP/QP solves never freeze the main UI thread, animations, or user input, while enabling real-time progress events (`onProgress`) and cancellation (`AbortSignal`).
+
+If your environment prohibits Web Workers or you explicitly want synchronous main-thread execution, pass `useWorker: false`:
+
+```typescript
+await m.solve({ useWorker: false });
+```
+
+#### Customizing the HiGHS WASM Asset URL
+By default, WaSHI resolves `highs.wasm` relative to the bundle (`new URL("./highs.wasm", import.meta.url)`). It **never** makes implicit requests to external CDNs (`jsdelivr`, `unpkg`, etc.).
+
+If your bundler or static server hosts `.wasm` files under a custom path, configure the URL globally or per solve:
+
+```typescript
+import { setHighsWasmUrl } from "@ohtaman/washi";
+
+// Option A: Configure globally before solving
+setHighsWasmUrl("/assets/wasm/highs.wasm");
+
+// Option B: Configure per solve call
+await m.solve({ wasmUrl: "/assets/wasm/highs.wasm" });
+```
+
+### Next.js & Server-Side Rendering (SSR)
+
+In Next.js App Router or Pages Router, optimization models can run either in Server Actions / API Routes (Node.js runtime) or on the client inside `"use client"` components:
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import { Model, maximize } from "@ohtaman/washi";
+
+export default function OptimizerComponent() {
+  const [val, setVal] = useState<number | null>(null);
+
+  const handleSolve = async () => {
+    const m = new Model();
+    const x = m.continuous("x", { lb: 0, ub: 50 });
+    m.objective(maximize(x));
+    await m.solve();
+    setVal(x.value);
+  };
+
+  return (
+    <div>
+      <button onClick={handleSolve}>Run Optimization</button>
+      {val !== null && <p>Result: {val}</p>}
+    </div>
+  );
+}
+```
+
+---
+
+## 📦 Browser ESM (`<script type="module">`)
+
+You can import the pre-bundled browser ESM modules directly from a local static server (or from an npm CDN once a compatible release is published) without a build step:
+
+```html
+<script type="module">
+  // Serve from your local static server / dist:
+  import { Model, expr, maximize } from "./dist/browser/washi.js";
+  // Or from an npm CDN once a compatible release is published:
+  // import { Model, expr, maximize } from "https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.js";
+  // Optional solver plugins:
+  // import "./dist/browser/solvers/glpk.js";
+  // import "./dist/browser/solvers/z3.js";
+
+  const m = new Model("BrowserESM");
+  const x = m.integer("x", { lb: 0 });
+  const y = m.integer("y", { lb: 0 });
+
+  m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+  m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
+  m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor");
+
+  await m.solve();
+  console.log("Optimal Objective:", m.objectiveValue);
+</script>
+```
+
+---
+
+## 🟨 Classic `<script>` Tags (IIFE / Standalone Build / CDN)
+
+For static HTML pages, CodePen, or JSFiddle, load `washi.min.js` via a standard `<script>` tag. All exports are attached to the global `window.Washi` object:
+
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>WaSHI Browser Demo</title>
+  </head>
+  <body>
+    <h1>WaSHI Browser Optimization</h1>
+    <pre id="output">Solving...</pre>
+
+    <!-- Core WaSHI + HiGHS (MIT) from local static build / assets -->
+    <script src="./dist/browser/washi.min.js"></script>
+    <!-- Or via CDN once a compatible release is published: -->
+    <!-- <script src="https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js"></script> -->
+    <!-- Optional plugins (auto-register on window.Washi): -->
+    <!-- <script src="./dist/browser/solvers/glpk.min.js"></script> -->
+    <!-- <script src="./dist/browser/solvers/z3.min.js"></script> -->
+
+    <script>
+      (async () => {
+        const { Model, expr, maximize } = Washi;
+
+        const m = new Model("BrowserDemo");
+        const x = m.continuous("x", { lb: 0, ub: 10 });
+        const y = m.continuous("y", { lb: 0, ub: 20 });
+
+        m.objective(maximize(expr`2 * ${x} + 3 * ${y}`));
+        m.constraint(expr`${x} + ${y} <= 15`);
+
+        await m.solve();
+
+        document.getElementById("output").textContent =
+          `Status: ${m.status}\n` +
+          `Objective: ${m.objectiveValue}\n` +
+          `x = ${x.value}, y = ${y.value}`;
+      })();
+    </script>
+  </body>
+</html>
+```
+
+> [!NOTE]
+> When loading `washi.min.js` from a cross-origin CDN (such as jsDelivr or unpkg), browsers block direct `new Worker("https://cdn...")` construction due to the same-origin policy. WaSHI automatically bridges cross-origin workers via a lightweight `Blob` wrapper using `importScripts()`, so Web Worker execution works out of the box from CDNs.
+
+---
+
+## 🔒 Offline, Intranet & Strict CSP Environments
+
+WaSHI never phones home or falls back to public CDNs. To self-host in an air-gapped intranet or under a strict Content Security Policy (CSP):
+
+1. **Copy Static Assets**: Serve the files from `node_modules/@ohtaman/washi/dist/browser/` on your own origin:
+   - `washi.js` / `washi.min.js`, `highs.wasm`, and `highs-worker.js`
+   - Optional GLPK: `solvers/glpk.js` / `solvers/glpk.min.js`
+   - Optional Z3: `solvers/z3.js` / `solvers/z3.min.js`, `solvers/z3-built.js`, `solvers/z3-built.wasm`
+2. **Content Security Policy (CSP) Headers**:
+   - Allow WebAssembly compilation (`'wasm-unsafe-eval'` in `script-src`).
+   - If using the default Web Worker or cross-origin Blob worker fallback, allow `worker-src 'self' blob:;`.
+   - If `blob:` workers are prohibited by policy, either serve `highs-worker.js` from `'self'` or run on the main thread with `await m.solve({ useWorker: false })`.
+3. **Cross-Origin Isolation (Z3 Only)**:
+   - HiGHS and GLPK run in standard browser contexts without special headers.
+   - Z3 WASM uses pthreads + `SharedArrayBuffer` and requires `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` (or `credentialless`). See the [Cross-Origin Isolation Guide](./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);
+```

package/docs/guide/constraints.md

@@ -0,0 +1,177 @@
+# Constraints (`m.constraint` & `m.indicator`)
+
+Constraints restrict the feasible solution space of your mathematical or logical model.
+In WaSHI, both linear arithmetic constraints and propositional SMT formulas are registered using **`m.constraint()`**:
+
+```typescript
+m.constraint(expr`${desks} + 2 * ${chairs} <= 40`, "wood_limit");
+```
+
+---
+
+## ✍️ Algebraic Linear Constraints (`expr`)
+
+The `expr` tagged template literal syntax allows writing equations and inequalities with natural mathematical notation:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// Upper bound inequality (<=)
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+
+// Lower bound inequality (>=)
+m.constraint(expr`3 * ${x} + ${y} >= 20`, "min_demand");
+
+// Exact equality (==)
+m.constraint(expr`${x} + ${y} == 30`, "exact_quota");
+```
+
+### Supported Comparison Operators
+- `<=`: Upper bound constraint
+- `>=`: Lower bound constraint
+- `==` or `=`: Exact equality constraint
+
+### Batch Registration
+You can pass an array of constraints to `m.constraint([...])` to register them transactionally in a single call:
+
+```typescript
+m.constraint([expr`${x} <= 10`, expr`${y} <= 20`]);
+```
+
+---
+
+## 🏷️ Naming Constraints
+
+Every constraint can be given a unique, descriptive name as the second argument of `m.constraint(c, name)`:
+
+```typescript
+m.constraint(expr`${x} + ${y} <= 100`, "budget_cap");
+```
+
+### Why Name Constraints?
+1. **Model Inspection (`m.toLpString()`)**: Exported CPLEX LP strings retain these descriptive names (sanitized if needed) so you can inspect the exact generated formulation.
+2. **Conflict Diagnosis (`conflicts` / `unsatCore`)**: When constraints contradict each other, Z3 `m.check()` returns the exact constraint names forming the conflicting subset.
+3. **Direct Lookup (`m.getConstraintByName()`)**: Retrieve a constraint by name after solving to inspect its `dual` or `slack` value.
+
+---
+
+## 🔁 Adding Constraints over Iterables & Sums
+
+Use `sum()` or `dot()` inside `expr` to express linear aggregations cleanly:
+
+```typescript
+import { Model, sum, expr } from "@ohtaman/washi";
+
+const items = ["A", "B", "C"];
+const weights = { A: 5, B: 10, C: 15 };
+const selected = m.binary(items);
+
+// Total weight cannot exceed capacity 25
+m.constraint(
+  expr`${sum(items, (i) => selected[i].mul(weights[i]))} <= 25`,
+  "capacity_limit"
+);
+```
+
+---
+
+## 🎯 Conditional / Indicator Constraints (`m.indicator`)
+
+When a linear constraint should only take effect when a binary decision variable is active (`1` or `0`), use `m.indicator()`:
+
+```typescript
+const useDiscount = m.binary("use_discount");
+const cartTotal = m.continuous("cart_total", { lb: 0, ub: 10_000 });
+
+// If useDiscount == 1, then cartTotal >= 100
+// WaSHI automatically derives a safe, tight Big-M from the variable bounds
+m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
+  activeValue: 1,
+  name: "min_spend_for_discount",
+});
+```
+
+### Safe Automatic Big-M Derivation & Bounds
+
+When `options.M` is omitted, WaSHI automatically derives a safe, minimal Big-M value from the finite variable bounds:
+- For `<=` constraints, variables with positive coefficients require finite upper bounds (`ub`), and negative coefficients require finite lower bounds (`lb`).
+- For `>=` constraints, variables with positive coefficients require finite lower bounds (`lb`), and negative coefficients require finite upper bounds (`ub`).
+- For `==` constraints, safe bounds are derived separately for both the `<=` and `>=` directions (generating `name_le` and `name_ge`).
+
+If any referenced variable lacks the required finite bounds, `m.indicator()` throws an actionable error prompting for finite bounds or an explicit `options.M`.
+
+### Explicit Override & Numerical Stability
+
+You can override the derived Big-M by providing `{ M: number }`:
+
+```typescript
+m.indicator(useDiscount, expr`${cartTotal} >= 100`, {
+  activeValue: 1,
+  M: 10_000, // Explicit override
+});
+```
+
+> [!TIP]
+> **Numerical Stability vs. Correctness**:
+> An $M$ value that is too small can inadvertently cut off valid solutions. Conversely, an excessively large $M$ (e.g., $10^9$) causes poor matrix conditioning and numerical instability in MIP solvers.
+> By setting explicit, realistic variable bounds (`lb` and `ub`), WaSHI derives the tightest possible safe Big-M automatically.
+
+---
+
+## 🧠 Propositional Logic & SMT Constraints (`BoolVar`, `and`, `or`, `not`, `implies`, `xor`)
+
+When solving with the **Z3** SMT engine (`@ohtaman/washi/solvers/z3`), you can combine propositional boolean variables (`m.bool()`) and linear constraints (`Constraint`) using first-class logical operators:
+
+```typescript
+import { Model, expr, and, or, not, implies, xor } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+const m = new Model({ solver: "z3" });
+const isAdmin = m.bool("isAdmin");
+const hasMfa = m.bool("hasMfa");
+const Clearance = m.integer("clearance", { lb: 0, ub: 5 });
+
+// Method syntax on BoolVar / BoolOp:
+m.constraint(isAdmin.implies(hasMfa), "admin_requires_mfa");
+
+// Mixing boolean propositions with linear arithmetic comparisons:
+m.constraint(
+  implies(isAdmin, expr`${Clearance} >= 4`),
+  "admin_clearance_level"
+);
+
+// Top-level helper functions (and, or, not, implies, xor):
+m.constraint(and(or(isAdmin, hasMfa), not(xor(isAdmin, hasMfa))), "policy");
+```
+
+### Choosing Between `m.indicator()` and `implies()`
+
+| Feature | `m.indicator(binVar, constraint, opts)` | `implies(a, b)` / `a.implies(b)` |
+| :--- | :--- | :--- |
+| **Trigger variable** | Numeric `Binary` variable (`m.binary()`) | `BoolVar` (`m.bool()`), `BoolOp`, or `Constraint` |
+| **Consequent** | Linear `Constraint` (`<=`, `>=`, `==`) | `BoolVar`, `BoolOp`, or linear `Constraint` |
+| **Target Solvers** | **All MIP/LP solvers** (HiGHS, GLPK, Z3) via Big-M linearization | **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()`) |
+
+---
+
+## 📐 Dual Values, Shadow Prices & Lookups
+
+For continuous Linear Programming (LP) problems, query the economic shadow price (`dual`) and surplus (`slack`) on each constraint:
+
+```typescript
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood");
+
+await m.solve();
+
+const woodConstraint = m.getConstraintByName("wood");
+console.log("Shadow price (dual):", woodConstraint?.dual);
+console.log("Slack surplus:", woodConstraint?.slack);
+console.log("Total linear constraints:", m.numConstrs);
+```
+
+For logical constraints registered with a name, use `m.getLogicalConstraintByName(name)` to look up the registered `LogicalConstraintItem`.