@ohtaman/washi 0.4.0 → 0.5.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 | **Z3 SMT solver** (`capabilities.supportsSMT: true`) |
+| **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`.

package/docs/guide/expressions.md

@@ -0,0 +1,204 @@
+# Expressions (`expr`, `sum`, `dot`)
+
+Mathematical expressions are linear or quadratic combinations of decision variables and numeric coefficients.
+
+In JavaScript and TypeScript—which do not support operator overloading—WaSHI provides the **unified tagged template literal (`expr`)**, **`sum()`**, and matrix/vector **`dot()`** to construct algebraic expressions without losing static type safety.
+
+| Approach | Example | Infix readability | Type safety & IDE rename | Indexed variables (`flow[i][j]`) |
+| :--- | :--- | :--- | :--- | :--- |
+| Method chaining | `x.mul(30).add(y.mul(50)).le(40)` | Low | Yes | Yes |
+| Raw string parsing | `parseConstraint("30 * x + 50 * y <= 40", resolver)` | High | No (runtime string lookup) | Fragile (string concatenation) |
+| **Tagged template (`expr`)** | `` expr`30 * ${x} + 50 * ${y} <= 40` `` | **High** | **Yes (actual TS references)** | **Yes (bound by object reference)** |
+
+---
+
+## ✍️ Tagged Template Literal (`expr`)
+
+Similar to parameterized `sql` tagged templates, `expr` receives the static operator text (`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`) separately from the interpolated `${...}` values (`Var`, `LinExpr`, `QuadExpr`, or finite `number`). Variables are bound by object reference rather than resolved by string name, avoiding naming collisions and preserving TypeScript type checking and IDE refactoring.
+
+Use `expr` for both arithmetic expressions (`LinExpr | QuadExpr`) and relational constraints (`Constraint`):
+
+```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 });
+
+// 1. Linear combination: 3*x + 5*y - 10
+const linearExpr = expr`3 * ${x} + 5 * ${y} - 10`;
+
+// 2. Quadratic expression: x * y + 2 * x^2
+const quadExpr = expr`${x} * ${y} + 2 * ${x} * ${x}`;
+
+// 3. Relational constraint:
+const balanceConstraint = expr`${x} + 2 * ${y} <= 40`;
+```
+
+### Supported Syntax in `expr`
+- **Addition & Subtraction**: `${x} + ${y} - 5`
+- **Scalar Multiplication**: `4 * ${x}`, `${x} * 4`
+- **Variable Multiplication (Quadratic terms)**: `${x} * ${y}`, `2 * ${x} * ${x}`
+- **Powers & Exponentiation**: `${x}^2`, `${x}**2`
+- **Unary Negation**: `-${x} + 10`
+- **Parentheses**: `2 * (${x} + ${y})`
+- **Nested Expressions**: `expr` seamlessly interpolates variables, numbers, `sum()` results, and nested expressions.
+
+> [!NOTE]
+> For relational comparisons (`<=`, `>=`, `==`), `expr` (e.g., ``expr`${x} + 2 * ${y} <= 40` ``) returns a first-class `Constraint`.
+> For arithmetic expressions without comparison operators, `expr` uniformly handles linear and quadratic expressions (up to degree 2): if quadratic terms are present, `expr` returns a `QuadExpr`; otherwise, it returns a `LinExpr`. Polynomial terms of degree $> 2$ (e.g. ``${x} * ${y} * ${z}``, ``${x}^3``) and non-linear constraints (e.g. ``${x} * ${y} <= 10``) are rejected because standard MILP/LP/QP formulations only support linear constraints and quadratic objectives.
+
+---
+
+## ⚡ High-Performance Summation (`sum`)
+
+For iterating over large collections of variables or indices:
+
+```typescript
+import { sum } from "@ohtaman/washi";
+
+const items = ["A", "B", "C"];
+const weights = { A: 10, B: 20, C: 30 };
+const x = m.binary(items);
+
+// 1. Transform elements with a mapping callback:
+const totalWeight = sum(items, (item) => x[item].mul(weights[item]));
+
+// 2. Direct array summation:
+const count = sum(Object.values(x));
+```
+
+`sum()` runs in $O(N)$ linear time without AST overhead.
+
+---
+
+## 🎯 Dot Product (`dot`)
+
+The `dot(a, b)` helper computes linear combinations of numeric coefficients (`number`) and variables or linear expressions (`Var | LinExpr`) in either operand order (`dot(coeffs, vars)` or `dot(vars, coeffs)`).
+
+Supported 1D and 2D container shapes:
+- **1D Arrays**: `number[]` $\times$ `(Var | LinExpr)[]`
+- **1D Records**: `Record<K, number>` $\times$ `Record<K, Var | LinExpr>`
+- **2D Arrays**: `number[][]` $\times$ `(Var | LinExpr)[][]`
+- **2D Records**: `Record<R, Record<C, number>>` $\times$ `Record<R, Record<C, Var | LinExpr>>`
+- **2D Mixed**: `Array<Record<C, ...>>` or `Record<R, Array<...>>`
+
+Mismatched array lengths, missing dictionary keys, or non-finite/non-linear leaves throw an explicit error indicating the offending path (e.g., `at '[0].StoreB'`).
+
+### 1D Vector Dot Product
+```typescript
+import { dot } from "@ohtaman/washi";
+
+const profits = { desk: 30, chair: 50 };
+const vars = m.integer(["desk", "chair"]);
+
+// Computes 30 * vars.desk + 50 * vars.chair
+const totalProfit = dot(profits, vars);
+```
+
+### 2D Matrix Dot Product
+Works directly with 2D arrays (`m.continuous(rows, cols)`), nested dictionaries (`m.continuous(rowKeys, colKeys)`), or mixed 2D containers:
+
+```typescript
+const factories = ["Tokyo", "Osaka"];
+const stores = ["StoreA", "StoreB"];
+
+const costs = {
+  Tokyo: { StoreA: 4, StoreB: 7 },
+  Osaka: { StoreA: 8, StoreB: 3 },
+};
+
+const ship = m.continuous(factories, stores);
+
+// Total shipping cost in one line:
+m.objective(minimize(dot(costs, ship)));
+```
+
+---
+
+## 🧮 Quadratic Expressions (`QuadExpr` & `expr`)
+
+WaSHI natively supports Convex Quadratic Programming (QP) with the HiGHS solver. Quadratic objectives can be written uniformly using the `expr` template literal, or algebraically using `QuadExpr` and `.mul()`:
+
+### 1. Using `expr` (Recommended)
+You can write quadratic formulas naturally with `*`, `^2`, or `**2`:
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// Quadratic objective using expr:
+m.objective(minimize(expr`3 * ${x} + ${x}^2 + ${y}^2`));
+
+// Linear constraint using expr:
+m.constraint(expr`${x} + ${y} >= 4`);
+```
+
+### 2. Method Chaining with `.mul()` or `QuadExpr`
+Alternatively, you can construct quadratic expressions programmatically:
+
+```typescript
+import { Model, QuadExpr, minimize } from "@ohtaman/washi";
+
+const m = new Model();
+const x = m.continuous("x", { lb: 0 });
+const y = m.continuous("y", { lb: 0 });
+
+// 1. Construct quadratic terms with .mul()
+// Represents x * y + 2 * x^2
+const quad = x.mul(y).add(x.mul(x).mul(2));
+
+// 2. Build portfolio risk objective: w^T * Sigma * w
+const assets = ["Tech", "Bonds"];
+const w = m.continuous(assets, { lb: 0, ub: 1 });
+
+let risk = new QuadExpr();
+risk = risk.add(w.Tech.mul(w.Tech).mul(0.04));
+risk = risk.add(w.Tech.mul(w.Bonds).mul(0.005));
+risk = risk.add(w.Bonds.mul(w.Bonds).mul(0.01));
+
+m.objective(minimize(risk));
+```
+
+---
+
+## 📊 Evaluating Expressions After Solving (`.value`)
+
+Both `LinExpr` and `QuadExpr` expose a `.value` getter (`number | null`). Once a model has been solved and all referenced variables have finite primal values, you can evaluate any sub-expression—such as total department cost, portfolio return, or resource utilization—directly without manual arithmetic:
+
+```typescript
+const revenue = expr`30 * ${x} + 50 * ${y}`;
+const laborUsed = expr`2 * ${x} + ${y}`;
+
+m.objective(maximize(revenue));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_cap");
+m.constraint(expr`${laborUsed} <= 50`, "labor_cap");
+
+await m.solve();
+
+console.log("Total Revenue:", revenue.value);   // 1100 (x = 20, y = 10)
+console.log("Labor Used:", laborUsed.value);    // 50
+```
+
+If the model has not been solved (or any variable in the expression has `value === null`), `.value` returns `null`.
+
+---
+
+## 🔗 Fluent Arithmetic & Relational Methods
+
+In addition to `expr`, `Var`, `LinExpr`, and `QuadExpr` provide immutable fluent methods for programmatic expression building:
+
+| Method | Supported On | Return Type | Description |
+| :--- | :--- | :--- | :--- |
+| `.add(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Adds a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.sub(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Subtracts a number, `Var`, `LinExpr`, or `QuadExpr`. |
+| `.mul(other)` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Multiplies by a scalar `number`, or multiplies two linear terms into a `QuadExpr`. |
+| `.div(divisor)` | `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Divides by a non-zero finite scalar `number`. |
+| `.neg()` | `Var`, `LinExpr`, `QuadExpr` | `LinExpr` or `QuadExpr` | Negates all terms ($-e$). |
+| `.le(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\le$ constraint (`lhs <= rhs`). |
+| `.ge(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds a $\ge$ constraint (`lhs >= rhs`). |
+| `.eq(rhs)` | `Var`, `LinExpr` | `Constraint` | Builds an $==$ equality constraint (`lhs == rhs`). |
+