@ohtaman/washi 0.6.0 → 0.7.0

package/docs/examples/index.md

@@ -1,20 +1,20 @@
 # Examples & API Finder
 
-Explore runnable optimization and logic formulations built with WaSHI. Every example can be executed directly inside its documentation page, or edited in the [Playground](https://ohtaman.github.io/washi/demo/).
+Explore runnable optimization and logic formulations built with WaSHI. Every example can be executed directly inside its documentation page, or edited in the [Playground](https://washi.ohtaman.dev/demo/).
 
 ## Examples
 
 | Example | Problem Class | Solver | Key WaSHI APIs | Description | Code Editor |
 | :--- | :--- | :--- | :--- | :--- | :--- |
-| **[Production Planning](./production.md)** | LP / MIP | HiGHS | `m.integer()`, `m.constraint()`, `expr` | Basic variables, tagged template literal equations, and maximizing profit under resource limits. | [Playground](https://ohtaman.github.io/washi/demo/?preset=production) |
-| **[0-1 Knapsack](./knapsack.md)** | Binary MIP | HiGHS | `m.binary(keys)`, `sum()`, `m.constraint()` | 1D dictionary of `Binary` variables and linear aggregation over item arrays. | [Playground](https://ohtaman.github.io/washi/demo/?preset=knapsack) |
-| **[Transportation Network](./transportation.md)** | LP | HiGHS | `m.continuous(rows, cols)`, `dot()`, `m.constraint()` | 2D matrix indexing (`ship[factory][store]`) and row/column flow balance constraints. | [Playground](https://ohtaman.github.io/washi/demo/?preset=transportation) |
-| **[Diet & Sensitivity Analysis](./diet-sensitivity.md)** | LP | HiGHS | `constr.dual`, `constr.slack`, `var.reducedCost` | Reading shadow prices (bottlenecks), constraint surpluses, and reduced costs after solving. | [Playground](https://ohtaman.github.io/washi/demo/?preset=diet_sensitivity) |
-| **[Staff Shift Scheduling](./shift-scheduling.md)** | Binary MIP + Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `check()`, `unsatCore` | 5×7 weekly roster planner (coverage, senior duty, max shifts, day-off requests) and diagnosing conflicting vacation requests with Z3 `unsatCore`. | [Playground](https://ohtaman.github.io/washi/demo/?preset=shift_scheduling) |
-| **[E-Commerce Coupon Optimizer](./ecommerce-coupons.md)** | Indicator MIP | HiGHS | `m.indicator()`, `sum()`, `m.constraint()` | Checkout optimizer using `m.indicator()` for minimum spend thresholds, exclusive vs. stackable rules, and smart filler add-on suggestions. | [Playground](https://ohtaman.github.io/washi/demo/?preset=cart_coupon) |
-| **[Portfolio Optimization](./portfolio-qp.md)** | Convex QP | HiGHS | `m.continuous()`, `m.constraint()`, `dot()`, `QuadExpr` | Markowitz mean-variance risk minimization ($w^T \Sigma w$) using `QuadExpr` subject to return targets. | [Playground](https://ohtaman.github.io/washi/demo/?preset=portfolio_qp) |
-| **[SMT Security Policies](./smt-security.md)** | SMT Logic | Z3 | `m.bool()`, `m.constraint()`, `m.check()` | Propositional variables (`BoolVar`) and logical connectives (`implies`, `and`, `not`, `xor`) mixed with integer bounds. | [Playground](https://ohtaman.github.io/washi/demo/?preset=smt_sat_scheduling) |
-| **[Conflict Diagnosis (`unsatCore`)](./unsat-core.md)** | Unsat Core | Z3 | `m.constraint()`, `m.check()`, `m.unsatCore` | Extracting a conflicting constraint subset (`unsatCore`) when staffing and budget rules contradict each other. | [Playground](https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat) |
+| **[Production Planning](./production.md)** | LP / MIP | HiGHS | `m.integer()`, `m.constraint()`, `expr` | Basic variables, tagged template literal equations, and maximizing profit under resource limits. | [Playground](https://washi.ohtaman.dev/demo/?preset=production) |
+| **[0-1 Knapsack](./knapsack.md)** | Binary MIP | HiGHS | `m.binary(keys)`, `expr` (`dot`), `m.constraint()` | 1D dictionary of `Binary` variables and linear aggregation over item arrays. | [Playground](https://washi.ohtaman.dev/demo/?preset=knapsack) |
+| **[Transportation Network](./transportation.md)** | LP | HiGHS | `m.continuous(rows, cols)`, `expr` (`sum`, `dot`), `m.constraint()` | 2D matrix indexing (`ship[factory][store]`) and row/column flow balance constraints. | [Playground](https://washi.ohtaman.dev/demo/?preset=transportation) |
+| **[Diet & Sensitivity Analysis](./diet-sensitivity.md)** | LP | HiGHS | `constr.dual`, `constr.slack`, `var.reducedCost` | Reading shadow prices (bottlenecks), constraint surpluses, and reduced costs after solving. | [Playground](https://washi.ohtaman.dev/demo/?preset=diet_sensitivity) |
+| **[Staff Shift Scheduling](./shift-scheduling.md)** | Binary MIP + Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `check()`, `unsatCore` | 5×7 weekly roster planner (coverage, senior duty, max shifts, day-off requests) and diagnosing conflicting vacation requests with Z3 `unsatCore`. | [Playground](https://washi.ohtaman.dev/demo/?preset=shift_scheduling) |
+| **[E-Commerce Coupon Optimizer](./ecommerce-coupons.md)** | Indicator MIP | HiGHS | `m.indicator()`, `expr` (`sum`, `dot`), `m.constraint()` | Checkout optimizer using `m.indicator()` for minimum spend thresholds, exclusive vs. stackable rules, and smart filler add-on suggestions. | [Playground](https://washi.ohtaman.dev/demo/?preset=cart_coupon) |
+| **[Portfolio Optimization](./portfolio-qp.md)** | Convex QP | HiGHS | `m.continuous()`, `m.constraint()`, `dot()`, `QuadExpr` | Markowitz mean-variance risk minimization ($w^T \Sigma w$) using `QuadExpr` subject to return targets. | [Playground](https://washi.ohtaman.dev/demo/?preset=portfolio_qp) |
+| **[SMT Security Policies](./smt-security.md)** | SMT Logic | Z3 | `m.bool()`, `m.constraint()`, `m.check()` | Propositional variables (`BoolVar`) and logical connectives (`implies`, `and`, `not`, `xor`) mixed with integer bounds. | [Playground](https://washi.ohtaman.dev/demo/?preset=smt_security) |
+| **[Conflict Diagnosis (`unsatCore`)](./unsat-core.md)** | Unsat Core | Z3 | `m.constraint()`, `m.check()`, `m.unsatCore` | Extracting a conflicting constraint subset (`unsatCore`) when staffing and budget rules contradict each other. | [Playground](https://washi.ohtaman.dev/demo/?preset=conflict_diagnosis_unsat) |
 | **[Vehicle Routing (CVRP)](./vehicle-routing.md)** | Combinatorial OR / Dantzig-Wolfe | HiGHS | `m.solveColumnGeneration()`, `pricing` | Dynamic route column generation from customer dual shadow prices to minimize total fleet vehicles. | [Decomposition Guide](../guide/decomposition.md) |
 | **[Traveling Salesperson (TSP)](./traveling-salesperson.md)** | Combinatorial OR / Benders | HiGHS | `m.solveBenders()`, `subproblem` | Subtour elimination on degree-assignment relaxation using dynamic Benders feasibility cuts. | [Decomposition Guide](../guide/decomposition.md) |
 
@@ -27,12 +27,12 @@ Looking for a specific modeling method or solver capability? Jump straight to th
 | ``m.constraint(expr`...`)`` | Tagged template literal constraints | [Production Planning](./production.md) | [`01-production-planning.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) |
 | `m.binary(keys)` / `m.continuous(keys)` | 1D dictionary of indexed variables | [0-1 Knapsack](./knapsack.md) | [`02-knapsack-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts) |
 | `m.continuous(rows, cols)` / `m.binary(rows, cols)` | 2D matrix of indexed variables | [Transportation Network](./transportation.md), [Shift Scheduling](./shift-scheduling.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
-| `dot(matrix, vars2d)` / `dot(vector, vars)` | Fast vector/matrix dot product | [Transportation Network](./transportation.md), [Portfolio Optimization](./portfolio-qp.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
+| ``expr`dot(${A}, ${X})` `` / `dot(A, X)` | Fast vector/matrix dot product | [Transportation Network](./transportation.md), [Portfolio Optimization](./portfolio-qp.md) | [`09-transportation-problem.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) |
 | `constr.dual` & `constr.slack` | Shadow prices & constraint surpluses | [Diet & Sensitivity Analysis](./diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
 | `var.reducedCost` | Variable reduced costs in LP | [Diet & Sensitivity Analysis](./diet-sensitivity.md) | [`10-diet-sensitivity.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) |
 | `m.indicator()` | Big-M conditional constraints (`binVar => constr`) | [E-Commerce Coupon Optimizer](./ecommerce-coupons.md) | [`12-ecommerce-coupon-optimizer.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) |
 | `new QuadExpr()` | Convex quadratic objectives ($x^T Q x$) | [Portfolio Optimization](./portfolio-qp.md) | [`03-portfolio-qp.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) |
-| `m.bool()` & `.implies()` | Propositional logic & SMT rules | [SMT Security Policies](./smt-security.md) | [`04-smt-security-rules.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) |
+| `m.bool()` & `implies()` | Propositional logic & SMT rules | [SMT Security Policies](./smt-security.md) | [`04-smt-security-rules.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) |
 | `m.check()` & `m.unsatCore` | Feasibility check & conflict diagnosis | [Conflict Diagnosis](./unsat-core.md), [Shift Scheduling](./shift-scheduling.md) | [`05-unsat-core-diagnosis.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) |
 | `m.solveColumnGeneration()` | Dantzig-Wolfe Column Generation | [Vehicle Routing](./vehicle-routing.md) | [`13-vehicle-routing-column-generation.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts) |
 | `m.solveBenders()` | Benders Decomposition & cut separation | [Traveling Salesperson](./traveling-salesperson.md) | [`14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) |
@@ -54,4 +54,6 @@ npx tsx examples/node/09-transportation-problem.ts
 npx tsx examples/node/10-diet-sensitivity.ts
 npx tsx examples/node/11-shift-scheduling.ts
 npx tsx examples/node/12-ecommerce-coupon-optimizer.ts
+npx tsx examples/node/13-vehicle-routing-column-generation.ts
+npx tsx examples/node/14-traveling-salesperson-benders.ts
 ```

package/docs/examples/knapsack.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| 0-1 Binary MIP | HiGHS (default) | `m.binary()`, `m.constraint()`, `expr`, `maximize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=knapsack">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts">Source Code</a></li></ul> |
+| 0-1 Binary MIP | HiGHS (default) | `m.binary()`, `m.constraint()`, `expr` (`dot`), `maximize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=knapsack">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/02-knapsack-problem.ts">Source Code</a></li></ul> |
 
 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.
 
@@ -21,7 +21,7 @@ $$\begin{aligned}
 <CodeRunner preset="knapsack">
 
 ```typescript
-import { Model, maximize, dot, expr } from "@ohtaman/washi";
+import { Model, maximize, expr } from "@ohtaman/washi";
 
 async function solveKnapsack() {
   const m = new Model("Knapsack");
@@ -41,17 +41,18 @@ async function solveKnapsack() {
   const values = Object.fromEntries(items.map((it) => [it.name, it.value]));
   const weights = Object.fromEntries(items.map((it) => [it.name, it.weight]));
 
-  // Maximize total value via dot product
-  m.objective(maximize(dot(values, x)));
+  // Maximize total value via dot() inside expr
+  m.objective(maximize(expr`dot(${values}, ${x})`));
 
-  // Weight capacity constraint using natural expr and constraint() syntax
-  m.constraint(expr`${dot(weights, x)} <= ${maxCapacity}`, "capacity_limit");
+  // Weight capacity constraint using expr and constraint()
+  m.constraint(expr`dot(${weights}, ${x}) <= ${maxCapacity}`, "capacity_limit");
 
   const status = await m.solve();
 
   console.log(`Status: ${status}`);
   console.log(`Max Total Value: $${m.objectiveValue}`);
-  console.log("Selected Items:", m.getValues(x));
+  const packed = items.filter((it) => x[it.name].value === 1).map((it) => it.name);
+  console.log("Packed Items:", packed.join(", "));
 }
 
 solveKnapsack();

package/docs/examples/portfolio-qp.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Convex Quadratic Programming (QP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot`, `QuadExpr` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=portfolio_qp">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts">Source Code</a></li></ul> |
+| Convex Quadratic Programming (QP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot`, `QuadExpr` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=portfolio_qp">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts">Source Code</a></li></ul> |
 
 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.
 
@@ -26,7 +26,7 @@ where $\boldsymbol{\Sigma}$ is the positive semi-definite asset return covarianc
 <CodeRunner preset="portfolio_qp">
 
 ```typescript
-import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, QuadExpr, dot, minimize, expr } from "@ohtaman/washi";
 
 async function solvePortfolio() {
   const m = new Model("PortfolioQP");
@@ -48,11 +48,12 @@ async function solvePortfolio() {
   const w = m.continuous(assets, { lb: 0, ub: 1 });
 
   // 1. Budget constraint: sum(w_i) == 1.0 (100%)
-  m.constraint(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget_limit");
+  m.constraint(expr`sum(${w}) == 1.0`, "budget_limit");
 
   // 2. Expected return constraint: sum(r_i * w_i) >= 8.5%
   const retMap = Object.fromEntries(assets.map((a, i) => [a, expectedReturns[i]]));
-  m.constraint(expr`${dot(retMap, w)} >= ${targetReturn}`, "target_return");
+  const portfolioReturn = dot(retMap, w);
+  m.constraint(expr`${portfolioReturn} >= ${targetReturn}`, "target_return");
 
   // 3. Quadratic Objective: minimize risk w^T * Sigma * w
   let risk = new QuadExpr();
@@ -71,6 +72,7 @@ async function solvePortfolio() {
   console.log(`Status: ${status}`);
   console.log(`Variance: ${m.objectiveValue?.toFixed(6)}`);
   console.log(`Volatility (Std Dev): ${((Math.sqrt(m.objectiveValue || 0)) * 100).toFixed(2)}%`);
+  console.log(`Expected Return: ${((portfolioReturn.value ?? 0) * 100).toFixed(2)}% (target >= ${(targetReturn * 100).toFixed(2)}%)`);
 
   assets.forEach((name) => {
     console.log(`  ${name.padEnd(10)}: ${((w[name].value ?? 0) * 100).toFixed(2)}%`);
@@ -81,3 +83,8 @@ solvePortfolio();
 ```
 
 </CodeRunner>
+
+## Practical Notes
+
+- **Tracing the Efficient Frontier (`targetReturn` & `portfolioReturn.value`)**: Because the achieved return (`8.50%`) matches `targetReturn` exactly, the return constraint is tightly binding on the Markowitz efficient frontier. Varying `targetReturn` across `[0.05, 0.12]` traces out the full risk-return frontier.
+- **Risk-Aversion Scalarization vs. Target Return Constraint**: If `targetReturn` is set above the highest single-asset return ($12\%$ for `Tech` under long-only weights), the hard constraint $\mathbf{r}^T \mathbf{w} \ge R_{\text{target}}$ becomes `"Infeasible"`. An alternative formulation that is always feasible for any risk appetite $\lambda > 0$ is to minimize the risk-adjusted objective $\min (\lambda \, \mathbf{w}^T \boldsymbol{\Sigma} \mathbf{w} - \mathbf{r}^T \mathbf{w})$.

package/docs/examples/production.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Linear / Integer Programming (LP / MIP) | HiGHS (default) | `m.integer()`, `m.constraint()`, `expr` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=production">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts">Source Code</a></li></ul> |
+| Linear / Integer Programming (LP / MIP) | HiGHS (default) | `m.integer()`, `m.constraint()`, `expr` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=production">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts">Source Code</a></li></ul> |
 
 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).
 
@@ -34,9 +34,9 @@ async function runProductionOptimization() {
   // Objective: Maximize total profit ($45 per chair, $80 per table)
   m.objective(maximize(expr`45 * ${chairs} + 80 * ${tables}`));
 
-  // Resource constraints: declarative formulas via expr and fluent constraint()
-  m.constraint(expr`5 * ${chairs} + 20 * ${tables} <= 400`, "mahogany_limit")
-   .constraint(expr`10 * ${chairs} + 15 * ${tables} <= 450`, "labor_limit");
+  // Resource constraints: declarative formulas via expr and constraint()
+  m.constraint(expr`5 * ${chairs} + 20 * ${tables} <= 400`, "mahogany_limit");
+  m.constraint(expr`10 * ${chairs} + 15 * ${tables} <= 450`, "labor_limit");
 
   const status = await m.solve();
 

package/docs/examples/shift-scheduling.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Binary MIP & SMT Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `m.constraint()`, `expr`, `minimize`, `dot`, `m.check()` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=shift_scheduling">Playground (Roster)</a></li><li><a href="https://ohtaman.github.io/washi/demo/?preset=shift_conflict_unsat">Playground (Conflict)</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts">Source Code</a></li></ul> |
+| Binary MIP & SMT Unsat Core | HiGHS + Z3 | `m.binary(staff, days)`, `m.constraint()`, `expr` (`sum`, `dot`), `minimize`, `m.check()` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=shift_scheduling">Playground (Roster)</a></li><li><a href="https://washi.ohtaman.dev/demo/?preset=shift_conflict_unsat">Playground (Conflict)</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts">Source Code</a></li></ul> |
 
 Staff shift scheduling is a classic real-world application of Mixed-Integer Programming in SaaS and workforce management tools. However, in real applications, **staff vacation requests frequently collide with minimum coverage or leadership rules**, causing the solver to return `Infeasible`.
 
@@ -35,7 +35,7 @@ We evaluate two distinct, named scenarios with different vacation inputs to illu
 <CodeRunner preset="shift_scheduling">
 
 ```typescript
-import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as const;
@@ -68,12 +68,12 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
       ),
     ])
   );
-  m.objective(minimize(dot(costMatrix, shift)));
+  m.objective(minimize(expr`dot(${costMatrix}, ${shift})`));
 
   // Rule 1: Daily headcount coverage
   for (const d of days) {
     m.constraint(
-      expr`${sum(staffList, (s) => shift[s.name][d])} >= ${requiredCoverage[d]}`,
+      expr`sum(${staffList}, ${(s) => shift[s.name][d]}) >= ${requiredCoverage[d]}`,
       `coverage_${d}`
     );
   }
@@ -82,7 +82,7 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
   const seniors = staffList.filter((s) => s.isSenior);
   for (const d of days) {
     m.constraint(
-      expr`${sum(seniors, (s) => shift[s.name][d])} >= 1`,
+      expr`sum(${seniors}, ${(s) => shift[s.name][d]}) >= 1`,
       `senior_duty_${d}`
     );
   }
@@ -90,7 +90,7 @@ function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; da
   // Rule 3: Max working days per staff member
   for (const s of staffList) {
     m.constraint(
-      expr`${sum(days, (d) => shift[s.name][d])} <= ${s.maxShifts}`,
+      expr`sum(${shift[s.name]}) <= ${s.maxShifts}`,
       `max_shifts_${s.name}`
     );
   }
@@ -126,7 +126,7 @@ async function runScenario(
   if (status === "Optimal") {
     console.log(`Optimal Weekly Payroll: $${model.objectiveValue}`);
     for (const s of staffList) {
-      const schedule = days.map((d) => (Math.round(shift[s.name][d].value ?? 0) === 1 ? "ON" : " ·"));
+      const schedule = days.map((d) => (shift[s.name][d].value === 1 ? "ON" : " ·"));
       console.log(`  ${s.name.padEnd(8)}: ${schedule.join(" ")}`);
     }
     console.log("Schedule resolved successfully (no UNSAT diagnosis needed).\n");
@@ -173,3 +173,16 @@ main();
 ```
 
 </CodeRunner>
+
+## Auto-Repairing Conflicts with Soft Constraints (Elastic Requests)
+
+Once Z3 `unsatCore` diagnoses that `senior_duty_Sat` conflicts with `day_off_Alice_Sat` and `day_off_Bob_Sat`, you can offer managers an automatic repair option by relaxing day-off requests from hard constraints (`shift[staff][day] == 0`) into **soft preferences** penalized in the objective (e.g., `+$500` per overridden day off):
+
+```typescript
+// Soft constraint pattern: penalize working on a requested day off by $500
+// instead of enforcing hard shift[req.staff][req.day] == 0
+const requestedShiftVars = dayOffRequests.map((req) => shift[req.staff][req.day]);
+m.objective(minimize(expr`dot(${costMatrix}, ${shift}) + 500 * sum(${requestedShiftVars})`));
+```
+
+With this soft formulation on Scenario B, HiGHS automatically finds a valid roster that honors 3 of the 4 requests (`Alice (Sat)`, `Charlie (Sat)`, and `Diana (Wed)`) and overrides only `Bob (Sat)`—choosing Bob over Alice because Bob's daily wage (`$210`) is `$10` lower than Alice's (`$220`).

package/docs/examples/smt-security.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Propositional Logic & SMT | Z3 (`@ohtaman/washi/solvers/z3`) | `m.bool()`, `m.integer()`, `m.constraint()`, `expr`, `m.check()` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=smt_sat_scheduling">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts">Source Code</a></li></ul> |
+| Propositional Logic & SMT | Z3 (`@ohtaman/washi/solvers/z3`) | `m.bool()`, `m.integer()`, `implies()`, `m.constraint()`, `expr`, `m.check()` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=smt_security">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts">Source Code</a></li></ul> |
 
 Satisfiability Modulo Theories (SMT) combines propositional logic (Boolean SAT) with first-order theories (linear integer arithmetic, real inequalities).
 
@@ -18,10 +18,10 @@ We model a security rule system with sensor readings and logic rules:
 
 ## Implementation in WaSHI
 
-<CodeRunner preset="smt_sat_scheduling">
+<CodeRunner preset="smt_security">
 
 ```typescript
-import { Model, not, expr } from "@ohtaman/washi";
+import { Model, implies, not, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 async function verifySecurityRules() {
@@ -39,7 +39,7 @@ async function verifySecurityRules() {
   const luxLevel = m.integer("luxLevel", { lb: 0, ub: 1000 });
 
   // Rule 1: luxLevel <= 50 implies isNight
-  m.constraint(luxLevel.le(50).implies(isNight), "dark_implies_night");
+  m.constraint(implies(expr`${luxLevel} <= 50`, isNight), "dark_implies_night");
 
   // Rule 2: (motionDetected AND isNight AND alarmArmed) => sirenActive
   m.constraint(
@@ -66,9 +66,21 @@ async function verifySecurityRules() {
   console.log(`Lights On    : ${lightsOn.value}`);
   console.log(`Door Locked  : ${frontDoorUnlocked.value ? "No" : "Yes"}`);
   console.log(`Is Night     : ${isNight.value}`);
+
+  // 4. Formal Safety Verification (Counterexample Search):
+  // Prove that the siren CANNOT remain off under these sensor readings
+  m.constraint(not(sirenActive), "counterexample_siren_off");
+  const proof = await m.check({ solver: "z3" });
+  console.log(`Can siren stay off? ${proof.status} (Proven safe when Unsat)`);
+  console.log(`Active proof core : ${(proof.conflicts ?? []).join(", ")}`);
 }
 
 verifySecurityRules();
 ```
 
 </CodeRunner>
+
+## Practical Notes
+
+- **Proof by Refutation (Counterexample Search)**: A single `Sat` check shows that *a* valid assignment exists. To formally prove that a safety property $P$ (such as `sirenActive`) **must** hold in *every* valid state, assert its negation `not(P)` and verify that `m.check()` returns `"Unsat"`. If it returns `"Sat"`, the solver's variable values give you a concrete counterexample (security loophole).
+- **One-Way Implication (`implies`) vs. Equivalence**: In classical logic, `` implies(expr`${luxLevel} <= 50`, isNight) `` only constrains `isNight` when `luxLevel <= 50`. During daytime (`luxLevel > 50`), `isNight` is unconstrained ("open-world" assumption) and could be assigned either `true` or `false` unless you also add the converse rule `` implies(expr`${luxLevel} >= 51`, not(isNight)) ``.

package/docs/examples/transportation.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=transportation">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts">Source Code</a></li></ul> |
+| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr` (`sum`, `dot`), `minimize` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=transportation">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts">Source Code</a></li></ul> |
 
 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.
 
@@ -35,7 +35,7 @@ $$\begin{aligned}
 <CodeRunner preset="transportation">
 
 ```typescript
-import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import { Model, minimize, expr } from "@ohtaman/washi";
 
 const factories = ["Tokyo", "Nagoya", "Osaka"] as const;
 const stores = ["North", "East", "West", "South"] as const;
@@ -49,42 +49,69 @@ const shippingCost = {
 const supplies = { Tokyo: 120, Nagoya: 100, Osaka: 80 };
 const demands = { North: 70, East: 90, West: 60, South: 60 };
 
-async function runTransportation() {
+async function solveScenario(label: string, cap: typeof supplies) {
   const m = new Model("TransportationNetwork");
 
   // 1. Create 2D continuous variables: ship[factory][store] >= 0
   const ship = m.continuous([...factories], [...stores], { lb: 0 });
 
   // 2. Objective: Minimize total shipping cost across all routes via 2D dot product
-  m.objective(minimize(dot(shippingCost, ship)));
+  m.objective(minimize(expr`dot(${shippingCost}, ${ship})`));
 
-  // 3. Supply constraints (row sums): outgoing from f <= supplies[f]
-  for (const f of factories) {
-    m.constraint(
-      expr`${sum(stores, (s) => ship[f][s])} <= ${supplies[f]}`,
-      `supply_${f}`
-    );
-  }
+  // 3. Supply constraints (row sums): outgoing from f <= cap[f]
+  const supplyConstrs = Object.fromEntries(
+    factories.map((f) => [
+      f,
+      m.constraint(expr`sum(${ship[f]}) <= ${cap[f]}`, `supply_${f}`),
+    ])
+  );
 
   // 4. Demand constraints (column sums): incoming to s >= demands[s]
-  for (const s of stores) {
-    m.constraint(
-      expr`${sum(factories, (f) => ship[f][s])} >= ${demands[s]}`,
-      `demand_${s}`
-    );
-  }
+  const demandConstrs = Object.fromEntries(
+    stores.map((s) => [
+      s,
+      m.constraint(
+        expr`sum(${factories}, ${(f) => ship[f][s]}) >= ${demands[s]}`,
+        `demand_${s}`
+      ),
+    ])
+  );
 
   const status = await m.solve();
-  console.log(`Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
+  console.log(`[${label}] Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
   for (const f of factories) {
+    const dual = supplyConstrs[f].dual ?? 0;
     const routes = stores
       .map((s) => `${s}:${Math.round(ship[f][s].value ?? 0)}`)
       .join(", ");
-    console.log(`  ${f.padEnd(7)} -> ${routes}`);
+    console.log(`  ${f.padEnd(7)} -> ${routes} (supply dual: $${dual}/u)`);
   }
+  const demandDuals = stores
+    .map((s) => `${s}:$${demandConstrs[s].dual ?? 0}`)
+    .join(", ");
+  console.log(`  Marginal Delivered Cost (demand duals) -> ${demandDuals}`);
+}
+
+async function runTransportation() {
+  // Scenario A: Baseline capacities ($920)
+  await solveScenario("Scenario A: Baseline", supplies);
+
+  // Scenario B: Tokyo capacity reduced (120 -> 80) due to maintenance ($1,000)
+  await solveScenario("Scenario B: Tokyo Maintenance", {
+    Tokyo: 80,
+    Nagoya: 120,
+    Osaka: 100,
+  });
 }
 
 runTransportation();
 ```
 
 </CodeRunner>
+
+## Practical Notes
+
+- **Interpreting Supply & Demand Shadow Prices (`.dual`)**:
+  - **`demand_s.dual` ($\ge 0$)**: The marginal delivered cost of supplying 1 additional unit to store $s$.
+  - **`supply_f.dual` ($\le 0$)**: How much total network shipping cost would decrease if factory $f$'s capacity were expanded by 1 unit. In Scenario B, when Tokyo is constrained at 80 units, `supply_Tokyo.dual` becomes negative (`-$2/u`), indicating that each extra unit of capacity in Tokyo saves \$2 by avoiding rerouting through Nagoya.
+- **Total Supply vs. Total Demand ($\sum \text{Supply}_f \ge \sum \text{Demand}_s$)**: If store demands exceed aggregate factory capacity, the hard demand constraints become `"Infeasible"`. In production logistics systems, add an elastic "spot-carrier / backorder" variable $u_s \ge 0$ to each store's demand constraint ($\sum_f x_{f,s} + u_s \ge \text{Demand}_s$) with a high penalty cost so the solver allocates scarce inventory optimally rather than failing.

package/docs/examples/traveling-salesperson.md

@@ -2,7 +2,7 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Combinatorial OR / Benders | HiGHS (default) | `m.solveBenders()`, `subproblem`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts">Source Code</a></li><li><a href="../guide/decomposition.md">Decomposition Guide</a></li></ul> |
+| Combinatorial OR / Benders | HiGHS (default) | `m.solveBenders()`, `subproblem`, `m.binary()`, `m.constraint()`, `expr` | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts">Source Code</a></li><li><a href="/guide/decomposition">Decomposition Guide</a></li></ul> |
 
 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.
 
@@ -31,7 +31,7 @@ We consider **5 cities** on a 2D Euclidean coordinate grid:
 <CodeRunner>
 
 ```typescript
-import { Model, expr, minimize, LinExpr } from "@ohtaman/washi";
+import { Model, expr, minimize } from "@ohtaman/washi";
 
 async function runTSP() {
   const cities = [
@@ -52,39 +52,26 @@ async function runTSP() {
   // 1. Master Problem: Degree assignment relaxation
   const master = new Model("TSP_BendersMaster");
   const x = {};
+  const distMatrix = {};
 
   for (let i = 0; i < n; i++) {
     x[i] = {};
+    distMatrix[i] = {};
     for (let j = 0; j < n; j++) {
       if (i !== j) {
         x[i][j] = master.binary(`x_${i}_${j}`);
+        distMatrix[i][j] = dist(i, j);
       }
     }
   }
 
   // Objective: Minimize total tour distance
-  let totalDistance = new LinExpr();
-  for (let i = 0; i < n; i++) {
-    for (let j = 0; j < n; j++) {
-      if (i !== j) {
-        totalDistance = totalDistance.add(x[i][j].mul(dist(i, j)));
-      }
-    }
-  }
-  master.objective(minimize(totalDistance));
+  master.objective(minimize(expr`dot(${distMatrix}, ${x})`));
 
   // Each city must have 1 outgoing and 1 incoming edge
   for (let i = 0; i < n; i++) {
-    let outExpr = new LinExpr();
-    let inExpr = new LinExpr();
-    for (let j = 0; j < n; j++) {
-      if (i !== j) {
-        outExpr = outExpr.add(x[i][j]);
-        inExpr = inExpr.add(x[j][i]);
-      }
-    }
-    master.constraint(expr`${outExpr} == 1`, `out_${i}`);
-    master.constraint(expr`${inExpr} == 1`, `in_${i}`);
+    master.constraint(expr`sum(${x[i]}) == 1`, `out_${i}`);
+    master.constraint(expr`sum(${n}, ${(j) => x[j][i]}) == 1`, `in_${i}`);
   }
 
   console.log("Solving TSP with Benders lazy subtour elimination...");
@@ -97,7 +84,7 @@ async function runTSP() {
       const succ = {};
       for (let i = 0; i < n; i++) {
         for (let j = 0; j < n; j++) {
-          if (i !== j && Math.round(x[i][j].value ?? 0) === 1) {
+          if (i !== j && x[i][j].value === 1) {
             succ[i] = j;
           }
         }
@@ -119,27 +106,22 @@ async function runTSP() {
         }
       }
 
-      // If more than 1 cycle, subtours exist: inject Benders feasibility cut
+      // If more than 1 cycle, subtours exist: inject Benders feasibility cuts for all cycles
       if (cycles.length > 1) {
-        const smallestCycle = cycles.reduce((min, c) => (c.length < min.length ? c : min));
-        const S = new Set(smallestCycle);
-        cutCounter++;
-        console.log(`Subtour detected: [${smallestCycle.map(k => cities[k].name).join(" -> ")}]. Adding Benders cut #${cutCounter}.`);
-
-        let cutLhs = new LinExpr();
-        for (const i of S) {
-          for (let j = 0; j < n; j++) {
-            if (!S.has(j)) {
-              cutLhs = cutLhs.add(x[i][j]);
-            }
-          }
-        }
-
-        return {
-          kind: "feasibility",
-          constraint: expr`${cutLhs} >= 1`,
-          name: `subtour_cut_${cutCounter}`,
-        };
+        return cycles.map((cycle) => {
+          const S = new Set(cycle);
+          cutCounter++;
+          console.log(`Subtour detected: [${cycle.map(k => cities[k].name).join(" -> ")}]. Adding Benders cut #${cutCounter}.`);
+
+          const outCities = Array.from({ length: n }, (_, j) => j).filter((j) => !S.has(j));
+          const cutEdges = cycle.flatMap((i) => outCities.map((j) => x[i][j]));
+
+          return {
+            kind: "feasibility",
+            constraint: expr`sum(${cutEdges}) >= 1`,
+            name: `subtour_cut_${cutCounter}`,
+          };
+        });
       }
 
       return null; // Single connected tour found
@@ -154,7 +136,7 @@ async function runTSP() {
   console.log("\nOptimal tour edges:");
   for (let i = 0; i < n; i++) {
     for (let j = 0; j < n; j++) {
-      if (i !== j && (result.values[`x_${i}_${j}`] ?? 0) > 0.5) {
+      if (i !== j && result.values[`x_${i}_${j}`] === 1) {
         console.log(`  ${cities[i].name} -> ${cities[j].name} (distance: ${dist(i, j).toFixed(3)})`);
       }
     }
@@ -169,5 +151,7 @@ runTSP();
 ## Notes
 
 - **Lazy Subtour Elimination**: The master problem starts with only the $2n$ degree constraints, and subtour elimination cuts are added on demand when disconnected cycles appear in the master solution.
-- **Separation Callback**: The `subproblem` callback reads candidate edge values via `x[i][j].value`, traces connected components in $O(n)$, and returns `{ kind: "feasibility", constraint: ... }` when multiple cycles are present.
+- **Multi-Cut Separation**: Returning an array of cuts (`cycles.map(...)`) from `subproblem` eliminates all disconnected cycles discovered in the current candidate solution simultaneously, reducing the number of master MIP re-solves.
+- **Two Equivalent DFJ Cut Forms**: Because every city has out-degree $\sum_{j \ne i} x_{ij} = 1$, summing over $i \in S$ gives $\sum_{i \in S, j \in S} x_{ij} + \sum_{i \in S, j \notin S} x_{ij} = |S|$. Thus the cut-set inequality $\sum_{i \in S, j \notin S} x_{ij} \ge 1$ used above and the internal-edge inequality $\sum_{i \in S, j \in S} x_{ij} \le |S| - 1$ used in [`14-traveling-salesperson-benders.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/14-traveling-salesperson-benders.ts) are algebraically identical.
+- **Upfront 2-City Subtour Elimination**: In larger TSP instances, mutual 2-cycles ($i \leftrightarrow j$) are the most frequent initial subtours. Adding the $\binom{n}{2}$ pairwise constraints $x_{ij} + x_{ji} \le 1$ directly to the initial master problem often cuts the number of Benders iterations substantially.
 - **Termination Condition**: Returning `null` from `subproblem` indicates that no violated subtour constraints remain.

package/docs/examples/unsat-core.md

@@ -2,9 +2,9 @@
 
 | Problem Class | Solver | Key APIs | Links |
 | :--- | :--- | :--- | :--- |
-| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
+| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `implies()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://washi.ohtaman.dev/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
 
-When business rules, budgets, and operational policies grow complex, constraints inevitably conflict. Traditional solvers simply report "Infeasible", leaving engineers to guess which of hundreds of rules caused the contradiction.
+When business rules, budgets, and operational policies grow complex, constraints can easily conflict. Because a standard optimization call (`m.solve()`) only reports `"Infeasible"`, WaSHI provides `m.check()` to pinpoint conflicting rules without manual trial-and-error.
 
 This example shows how to isolate the conflicting constraint subset using Z3 Unsat Core extraction.
 
@@ -26,7 +26,7 @@ $$8 \text{ engineers} \times \$8,000 = \$64,000 > \$50,000 \text{ budget!}$$
 <CodeRunner preset="conflict_diagnosis_unsat">
 
 ```typescript
-import { Model, expr } from "@ohtaman/washi";
+import { Model, implies, expr } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/z3";
 
 async function diagnoseConflicts() {
@@ -43,7 +43,7 @@ async function diagnoseConflicts() {
   m.constraint(rushDelivery, "rush_required");
 
   // Rule 3: Rush delivery requires at least 8 engineers
-  m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+  m.constraint(implies(rushDelivery, expr`${engineers} >= 8`), "rush_staffing_rule");
 
   // Rule 4: Board budget cap of $50,000 (Conflict!)
   m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
@@ -55,10 +55,20 @@ async function diagnoseConflicts() {
   const res = await m.check({ solver: "z3" });
 
   console.log(`Status: ${res.status}`);
-  console.log("Conflicting Constraints (conflicts):", m.conflicts);
+  console.log("Z3 Unsat Core (scale-invariant):", m.conflicts);
+
+  // Built-in HiGHS can also diagnose conflicts via single-solve L1 elastic slack relaxation:
+  const highsDiag = await m.check({ solver: "highs" });
+  console.log("HiGHS Elastic Repair Set:", highsDiag.conflicts);
 }
 
 diagnoseConflicts();
 ```
 
 </CodeRunner>
+
+## Practical Notes
+
+- **Z3 `unsatCore` vs. HiGHS Elastic Slack `conflicts`**:
+  - **Z3 (`m.check({ solver: "z3" })`)** performs logical assumption tracking and returns all four rules that jointly form the contradiction (`budget_limit`, `rush_required`, `rush_staffing_rule`, `strict_board_budget_cap`), while excluding the innocent `minimum_one_employee` rule.
+  - **HiGHS (`m.check({ solver: "highs" })`)** solves a single $L_1$ elastic slack minimization problem ($\min \sum s_i$). Because relaxing `rush_staffing_rule` (or `rush_required`) requires a slack of only `1`–`2` units whereas relaxing `strict_board_budget_cap` requires a slack of `14,000` dollars, unweighted $L_1$ minimization naturally highlights the smallest-magnitude repair (`rush_required`) needed to restore feasibility.