@ohtaman/washi 0.3.0 → 0.5.0

package/docs/examples/ecommerce-coupons.md

@@ -0,0 +1,106 @@
+# E-Commerce Cart & Coupon Optimizer (Indicator MIP)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Mixed-Integer Programming (MIP) | HiGHS (default) | `m.binary()`, `m.constraint()`, `m.indicator()`, `expr`, `minimize` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=cart_coupon">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts">Source Code</a></li></ul> |
+
+Modern e-commerce checkouts often feature complex promotional rules: minimum spend thresholds, category-specific discounts, stackable vs. mutually exclusive coupons, and maximum coupon limits per order. Running an optimizer directly in the browser (or an edge worker) lets the checkout UI automatically apply the best coupon combination—and even recommend a small "filler" item when crossing a spend threshold lowers the customer's net bill.
+
+This example demonstrates **`m.indicator(binVar, constraint, { activeValue, M? })`**, which automatically linearizes conditional *"if coupon is selected, minimum spend must hold"* constraints using Big-M reformulation for MIP solvers like HiGHS. When `M` is omitted, WaSHI automatically derives safe, tight Big-M values from finite variable bounds.
+
+<EcommerceCouponDemo />
+
+## Scenario & Promotion Rules
+
+A customer's shopping cart currently contains **$242** of merchandise (**$210** in Tech items and **$32** in Apparel):
+- **Optional Filler Add-on:** A **$10** Braided USB-C Cable (Tech) can be added to bring the cart total from `$242` to `$252`.
+- **Available Coupons** (maximum **2 coupons** total per checkout; at most **1 Exclusive** coupon):
+
+| Coupon Code | Discount | Condition | Stacking Rule |
+| :--- | :---: | :--- | :--- |
+| `WELCOME15` | **-$15** | Total cart spend $\ge \$100$ | **Stackable** |
+| `TECH30` | **-$30** | Tech category spend $\ge \$200$ | **Exclusive** (cannot combine with `MEGA45_250`) |
+| `MEGA45_250` | **-$45** | Total cart spend $\ge \$250$ | **Exclusive** (cannot combine with `TECH30`) |
+| `MEMBER10` | **-$10** | Total cart spend $\ge \$150$ | **Stackable** |
+
+Without adding the `$10` cable, the cart (`$242`) cannot use `MEGA45_250` and pays `$242 - $30 (TECH30) - $15 (WELCOME15) = $197`.  
+By adding the `$10` cable (`$252` gross), the customer unlocks `MEGA45_250` (`-$45`) + `WELCOME15` (`-$15`) for a net total of **$192**—saving an extra **$5** while getting an extra item!
+
+## Implementation in WaSHI
+
+<CodeRunner preset="cart_coupon">
+
+```typescript
+import { Model, sum, minimize, expr } from "@ohtaman/washi";
+
+async function optimizeCheckoutCart() {
+  const m = new Model("CartCouponOptimizer");
+
+  const baseCartSubtotal = 242;
+  const baseTechSubtotal = 210;
+
+  // Binary decision: add optional $10 USB-C cable to unlock $250 tier?
+  const addUsbCable = m.binary("addon_USB_Cable");
+  const usbCablePrice = 10;
+
+  const coupons = [
+    { id: "WELCOME15",  discount: 15, minCart: 100, minTech: 0,   stackable: true  },
+    { id: "TECH30",     discount: 30, minCart: 0,   minTech: 200, stackable: false },
+    { id: "MEGA45_250", discount: 45, minCart: 250, minTech: 0,   stackable: false },
+    { id: "MEMBER10",   discount: 10, minCart: 150, minTech: 0,   stackable: true  },
+  ];
+
+  // Binary decision variables for each coupon
+  const useCoupon = m.binary(coupons.map((c) => c.id));
+
+  const merchSpend = addUsbCable.mul(usbCablePrice).add(baseCartSubtotal);
+  const techSpend  = addUsbCable.mul(usbCablePrice).add(baseTechSubtotal);
+
+  // 1. Indicator constraints: If useCoupon[id] == 1, minimum spend threshold must hold
+  for (const cpn of coupons) {
+    if (cpn.minCart > 0) {
+      m.indicator(useCoupon[cpn.id], merchSpend.ge(cpn.minCart), {
+        activeValue: 1,
+        M: 500,
+        name: `min_spend_${cpn.id}`,
+      });
+    }
+    if (cpn.minTech > 0) {
+      m.indicator(useCoupon[cpn.id], techSpend.ge(cpn.minTech), {
+        activeValue: 1,
+        M: 500,
+        name: `min_tech_${cpn.id}`,
+      });
+    }
+  }
+
+  // 2. Mutual exclusion among non-stackable ("Exclusive") coupons
+  const exclusiveCoupons = coupons.filter((c) => !c.stackable);
+  m.constraint(
+    expr`${sum(exclusiveCoupons, (c) => useCoupon[c.id])} <= 1`,
+    "at_most_one_exclusive"
+  );
+
+  // 3. Max 2 coupons per order
+  m.constraint(
+    expr`${sum(coupons, (c) => useCoupon[c.id])} <= 2`,
+    "max_two_coupons"
+  );
+
+  // Objective: Minimize final net payable amount (merchSpend - totalDiscounts)
+  const totalDiscount = sum(coupons, (c) => useCoupon[c.id].mul(c.discount));
+  m.objective(minimize(merchSpend.sub(totalDiscount)));
+
+  const status = await m.solve();
+  console.log(`Status: ${status}, Optimal Net Payable: $${m.objectiveValue}`);
+  console.log(`Recommended Add-on (+$10 USB-C Cable): ${(addUsbCable.value ?? 0) > 0.5 ? "YES" : "NO"}`);
+  for (const cpn of coupons) {
+    const applied = (useCoupon[cpn.id].value ?? 0) > 0.5;
+    console.log(`  ${applied ? "✅ [APPLIED]" : "   [skipped]"} ${cpn.id.padEnd(11)} (-$${cpn.discount})`);
+  }
+}
+
+optimizeCheckoutCart();
+```
+
+</CodeRunner>

package/docs/examples/index.md

@@ -0,0 +1,53 @@
+# 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/).
+
+## 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) |
+
+## Find by WaSHI API (Reverse Index)
+
+Looking for a specific modeling method or solver capability? Jump straight to the example that demonstrates it:
+
+| Feature / API | Description | Example Page | Node.js Source |
+| :--- | :--- | :--- | :--- |
+| ``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) |
+| `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.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) |
+| `solver: "glpk"` | Solving LP/MIP with GLPK plugin | [GLPK Solver Guide](../solvers/glpk.md) | [`08-glpk-solver-plugin.ts`](https://github.com/ohtaman/washi/blob/main/examples/node/08-glpk-solver-plugin.ts) |
+
+## Running Examples Locally in Node.js
+
+All standalone scripts are located in [`examples/node/`](https://github.com/ohtaman/washi/tree/main/examples/node):
+
+```bash
+npx tsx examples/node/01-production-planning.ts
+npx tsx examples/node/02-knapsack-problem.ts
+npx tsx examples/node/03-portfolio-qp.ts
+npx tsx examples/node/04-smt-security-rules.ts
+npx tsx examples/node/05-unsat-core-diagnosis.ts
+npx tsx examples/node/07-hybrid-smt-mip.ts
+npx tsx examples/node/08-glpk-solver-plugin.ts
+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
+```

package/docs/examples/knapsack.md

@@ -0,0 +1,60 @@
+# 0-1 Knapsack Problem (Binary MIP)
+
+| 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> |
+
+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.
+
+## Mathematical Formulation
+
+Let $x_i \in \{0, 1\}$ be binary decision variables indicating whether item $i$ is selected ($x_i = 1$) or not ($x_i = 0$):
+
+$$\begin{aligned}
+\text{Maximize} \quad & \sum_{i} v_i x_i & (\text{Total Value}) \\
+\text{Subject to} \quad & \sum_{i} w_i x_i \le W & (\text{Weight Capacity}) \\
+& x_i \in \{0, 1\} & (\text{Binary Decisions})
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+<CodeRunner preset="knapsack">
+
+```typescript
+import { Model, maximize, dot, expr } from "@ohtaman/washi";
+
+async function solveKnapsack() {
+  const m = new Model("Knapsack");
+
+  const items = [
+    { name: "Laptop",   weight: 3, value: 50 },
+    { name: "Camera",   weight: 2, value: 40 },
+    { name: "Drone",    weight: 4, value: 65 },
+    { name: "FirstAid", weight: 1, value: 15 },
+    { name: "Tent",     weight: 5, value: 70 },
+  ];
+  const maxCapacity = 7; // kg
+
+  // Create binary variables: x[name] (0 or 1)
+  const x = m.binary(items.map((it) => it.name));
+
+  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)));
+
+  // Weight capacity constraint using natural expr and constraint() syntax
+  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));
+}
+
+solveKnapsack();
+```
+
+</CodeRunner>

package/docs/examples/portfolio-qp.md

@@ -0,0 +1,83 @@
+# Portfolio Optimization (QP)
+
+| 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> |
+
+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.
+
+<PortfolioQpDemo />
+
+## Mathematical Formulation
+
+Let $w_i \ge 0$ denote the allocation weight for asset $i$:
+
+$$\begin{aligned}
+\text{Minimize} \quad & \mathbf{w}^T \boldsymbol{\Sigma} \mathbf{w} & (\text{Portfolio Variance}) \\
+\text{Subject to} \quad & \sum_{i=1}^n w_i = 1 & (\text{Full Capital Budget}) \\
+& \sum_{i=1}^n r_i w_i \ge R_{\text{target}} & (\text{Minimum Target Return}) \\
+& 0 \le w_i \le 1 & (\text{Long-Only Weights})
+\end{aligned}$$
+
+where $\boldsymbol{\Sigma}$ is the positive semi-definite asset return covariance matrix.
+
+## Implementation in WaSHI
+
+<CodeRunner preset="portfolio_qp">
+
+```typescript
+import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
+
+async function solvePortfolio() {
+  const m = new Model("PortfolioQP");
+
+  const assets = ["Tech", "Bonds", "GlobalEq", "RealEstate", "Gold"];
+  const expectedReturns = [0.12, 0.04, 0.09, 0.07, 0.05];
+  const targetReturn = 0.085; // 8.5% minimum expected return
+
+  // 5x5 Covariance Matrix
+  const cov = [
+    [0.040, 0.002, 0.025, 0.015, 0.005],
+    [0.002, 0.005, 0.003, 0.002, 0.001],
+    [0.025, 0.003, 0.030, 0.018, 0.008],
+    [0.015, 0.002, 0.018, 0.025, 0.004],
+    [0.005, 0.001, 0.008, 0.004, 0.020],
+  ];
+
+  // Allocation weights w_i in [0, 1]
+  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");
+
+  // 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");
+
+  // 3. Quadratic Objective: minimize risk w^T * Sigma * w
+  let risk = new QuadExpr();
+  for (let i = 0; i < assets.length; i++) {
+    for (let j = 0; j < assets.length; j++) {
+      if (cov[i][j] !== 0) {
+        risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
+      }
+    }
+  }
+  m.objective(minimize(risk));
+
+  // Solve natively with HiGHS Convex QP engine
+  const status = await m.solve();
+
+  console.log(`Status: ${status}`);
+  console.log(`Variance: ${m.objectiveValue?.toFixed(6)}`);
+  console.log(`Volatility (Std Dev): ${((Math.sqrt(m.objectiveValue || 0)) * 100).toFixed(2)}%`);
+
+  assets.forEach((name) => {
+    console.log(`  ${name.padEnd(10)}: ${((w[name].value ?? 0) * 100).toFixed(2)}%`);
+  });
+}
+
+solvePortfolio();
+```
+
+</CodeRunner>

package/docs/examples/production.md

@@ -0,0 +1,51 @@
+# Production Planning (LP / MIP)
+
+| 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> |
+
+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).
+
+## Mathematical Formulation
+
+Let $x$ be the number of chairs and $y$ be the number of tables.
+
+$$\begin{aligned}
+\text{Maximize} \quad & 45x + 80y & (\text{Profit}) \\
+\text{Subject to} \quad & 5x + 20y \le 400 & (\text{Mahogany Wood limit}) \\
+& 10x + 15y \le 450 & (\text{Carpentry Labor limit}) \\
+& x, y \ge 0, \quad x, y \in \mathbb{Z} & (\text{Integer Quantities})
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+<CodeRunner preset="production">
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+async function runProductionOptimization() {
+  const m = new Model("FactoryProduction");
+
+  // Decision variables: non-negative integer quantities
+  const chairs = m.integer("chairs", { lb: 0 });
+  const tables = m.integer("tables", { lb: 0 });
+
+  // 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");
+
+  const status = await m.solve();
+
+  console.log(`Status: ${status}`);
+  console.log(`Optimal Profit: $${m.objectiveValue}`);
+  console.log(`Chairs: ${chairs.value}, Tables: ${tables.value}`);
+}
+
+runProductionOptimization();
+```
+
+</CodeRunner>

package/docs/examples/shift-scheduling.md

@@ -0,0 +1,175 @@
+# Staff Shift Scheduling & Conflict Diagnosis (MIP + Z3)
+
+| 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> |
+
+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`.
+
+This example demonstrates a practical production workflow:
+1. **Try HiGHS MIP Optimization First:** Solve the shift model under the given vacation requests and operational constraints.
+2. **Accept Solution if Optimal:** If a feasible roster is found, display the schedule and minimized payroll cost without unnecessary diagnostic overhead.
+3. **Diagnose with Z3 `unsatCore` Only When Infeasible:** If HiGHS reports `Infeasible`, diagnose the **exact same model and constraints** with Z3 to isolate the conflicting constraint subset (`unsatCore`), pinpointing which day's coverage rules and which staff requests collided.
+
+> [!IMPORTANT]
+> **Vacation Requests are Hard Constraints:**
+> In this model, vacation requests are enforced as strict hard constraints (`shift[staff][day] == 0`), not soft constraints with penalty relaxation. When requests collide with mandatory staffing requirements, the model is strictly infeasible.
+
+<ShiftSchedulingDemo />
+
+## Scenario & Rules
+
+We schedule **5 staff members** (`Alice`, `Bob`, `Charlie`, `Diana`, `Evan`) across **7 days** (`Mon`–`Sun`):
+
+- **Daily Headcount:** `Mon–Thu`: 3 staff, `Fri`: 4 staff, `Sat`: 3 staff, `Sun`: 2 staff.
+- **Senior Duty:** At least 1 senior staff member (`Alice` or `Bob`) must be on duty every day.
+- **Work Limit:** Each staff member works at most **5 days** per week.
+- **Weekend Premium:** Weekend shifts (`Sat`, `Sun`) incur an extra `+$30` shift premium on top of base daily wage.
+
+We evaluate two distinct, named scenarios with different vacation inputs to illustrate the full workflow:
+- **Scenario A (Balanced Requests — Feasible):** Alice (Sun), Bob (Mon), Charlie (Sat), Diana (Wed). All constraints can be satisfied simultaneously. HiGHS outputs an optimal roster.
+- **Scenario B (Conflicting Requests — Infeasible & Diagnosis):** Alice (Sat), Bob (Sat), Charlie (Sat), Diana (Wed). Because both senior leaders (Alice and Bob) request Saturday off simultaneously, the rule requiring at least 1 senior on duty every day cannot be satisfied. HiGHS reports `Infeasible`, triggering Z3 conflict diagnosis.
+
+## Implementation in WaSHI
+
+<CodeRunner preset="shift_scheduling">
+
+```typescript
+import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+const days = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] as const;
+type Day = (typeof days)[number];
+
+const staffList = [
+  { name: "Alice",   isSenior: true,  dailyWage: 220, maxShifts: 5 },
+  { name: "Bob",     isSenior: true,  dailyWage: 210, maxShifts: 5 },
+  { name: "Charlie", isSenior: false, dailyWage: 160, maxShifts: 5 },
+  { name: "Diana",   isSenior: false, dailyWage: 160, maxShifts: 5 },
+  { name: "Evan",    isSenior: false, dailyWage: 150, maxShifts: 5 },
+];
+
+const requiredCoverage: Record<Day, number> = {
+  Mon: 3, Tue: 3, Wed: 3, Thu: 3, Fri: 4, Sat: 3, Sun: 2,
+};
+
+function buildShiftModel(name: string, dayOffRequests: Array<{ staff: string; day: Day }>) {
+  const m = new Model(name);
+
+  // 2D binary matrix: shift[staff][day] ∈ {0, 1}
+  const shift = m.binary(staffList.map((s) => s.name), [...days]);
+
+  // Objective: Minimize weekly payroll cost via 2D dot product
+  const costMatrix = Object.fromEntries(
+    staffList.map((s) => [
+      s.name,
+      Object.fromEntries(
+        days.map((d) => [d, s.dailyWage + (d === "Sat" || d === "Sun" ? 30 : 0)])
+      ),
+    ])
+  );
+  m.objective(minimize(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]}`,
+      `coverage_${d}`
+    );
+  }
+
+  // Rule 2: At least 1 senior staff member per day
+  const seniors = staffList.filter((s) => s.isSenior);
+  for (const d of days) {
+    m.constraint(
+      expr`${sum(seniors, (s) => shift[s.name][d])} >= 1`,
+      `senior_duty_${d}`
+    );
+  }
+
+  // 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}`,
+      `max_shifts_${s.name}`
+    );
+  }
+
+  // Rule 4: Named day-off requests as HARD constraints (shift[staff][day] == 0)
+  for (const req of dayOffRequests) {
+    m.constraint(
+      expr`${shift[req.staff][req.day]} == 0`,
+      `day_off_${req.staff}_${req.day}`
+    );
+  }
+
+  return { model: m, shift };
+}
+
+async function runScenario(
+  title: string,
+  modelName: string,
+  dayOffRequests: Array<{ staff: string; day: Day }>
+) {
+  console.log(`=== ${title} ===`);
+  console.log(
+    "Hard Vacation Requests: " +
+      dayOffRequests.map((r) => `${r.staff} (${r.day})`).join(", ")
+  );
+
+  const { model, shift } = buildShiftModel(modelName, dayOffRequests);
+
+  // Step 1: Optimize with HiGHS
+  const status = await model.solve();
+  console.log(`HiGHS Optimize Status: ${status}`);
+
+  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" : " ·"));
+      console.log(`  ${s.name.padEnd(8)}: ${schedule.join(" ")}`);
+    }
+    console.log("Schedule resolved successfully (no UNSAT diagnosis needed).\n");
+  } else if (status === "Infeasible") {
+    // Step 2: Diagnose the exact same model and constraints with Z3
+    console.log("HiGHS returned Infeasible! Diagnosing conflict with Z3 unsatCore...");
+    const checkRes = await model.check({ solver: "z3" });
+    console.log(`Z3 Check Status: ${checkRes.status}`);
+    console.log("Conflicting Constraint Subset (unsatCore):", model.unsatCore);
+    console.log(
+      "Note: unsatCore returns a conflicting subset (minimality/order not guaranteed). " +
+      "Independent requests like Diana's Wednesday off are excluded.\n"
+    );
+  }
+}
+
+async function main() {
+  // Scenario A: Balanced requests (Solvable)
+  await runScenario(
+    "Scenario A: Balanced Vacation Requests",
+    "FeasibleRoster",
+    [
+      { staff: "Alice", day: "Sun" },
+      { staff: "Bob", day: "Mon" },
+      { staff: "Charlie", day: "Sat" },
+      { staff: "Diana", day: "Wed" },
+    ]
+  );
+
+  // Scenario B: Conflicting Saturday requests (Infeasible)
+  await runScenario(
+    "Scenario B: Conflicting Saturday Requests",
+    "ConflictRoster",
+    [
+      { staff: "Alice", day: "Sat" }, // Senior
+      { staff: "Bob", day: "Sat" },   // Senior
+      { staff: "Charlie", day: "Sat" },
+      { staff: "Diana", day: "Wed" },
+    ]
+  );
+}
+
+main();
+```
+
+</CodeRunner>

package/docs/examples/smt-security.md

@@ -0,0 +1,74 @@
+# SMT Security Policies
+
+| 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> |
+
+Satisfiability Modulo Theories (SMT) combines propositional logic (Boolean SAT) with first-order theories (linear integer arithmetic, real inequalities).
+
+This example demonstrates how to formally verify and deduce system states in an IoT home security system using WaSHI and the Z3 solver engine.
+
+## The Scenario
+
+We model a security rule system with sensor readings and logic rules:
+1. When ambient light $\le 50$, it implies night time (`isNight`).
+2. When motion is detected at night and the alarm is armed, the siren must sound.
+3. If the alarm is armed, the front door must never be unlocked.
+4. When motion is detected at night, comfort lights should turn on.
+
+## Implementation in WaSHI
+
+<CodeRunner preset="smt_sat_scheduling">
+
+```typescript
+import { Model, not, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+async function verifySecurityRules() {
+  const m = new Model({ name: "SmartHomeSecurity", solver: "z3" });
+
+  // 1. Boolean Propositional Variables
+  const isNight = m.bool("isNight");
+  const motionDetected = m.bool("motionDetected");
+  const alarmArmed = m.bool("alarmArmed");
+  const frontDoorUnlocked = m.bool("frontDoorUnlocked");
+  const sirenActive = m.bool("sirenActive");
+  const lightsOn = m.bool("lightsOn");
+
+  // 2. Arithmetic metric (lux sensor)
+  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");
+
+  // Rule 2: (motionDetected AND isNight AND alarmArmed) => sirenActive
+  m.constraint(
+    motionDetected.and(isNight).and(alarmArmed).implies(sirenActive),
+    "intrusion_rule"
+  );
+
+  // Rule 3: alarmArmed => NOT(frontDoorUnlocked)
+  m.constraint(alarmArmed.implies(not(frontDoorUnlocked)), "lock_safety_rule");
+
+  // Rule 4: (motionDetected AND isNight) => lightsOn
+  m.constraint(motionDetected.and(isNight).implies(lightsOn), "comfort_lights");
+
+  // 3. Observed Context
+  m.constraint(expr`${luxLevel} <= 20`, "sensor_reading_dark");
+  m.constraint(alarmArmed, "user_armed_alarm");
+  m.constraint(motionDetected, "sensor_motion_triggered");
+
+  // Check satisfiability and deduce state
+  const res = await m.check({ solver: "z3" });
+
+  console.log(`Status: ${res.status}`);
+  console.log(`Siren Active : ${sirenActive.value}`);
+  console.log(`Lights On    : ${lightsOn.value}`);
+  console.log(`Door Locked  : ${frontDoorUnlocked.value ? "No" : "Yes"}`);
+  console.log(`Is Night     : ${isNight.value}`);
+}
+
+verifySecurityRules();
+```
+
+</CodeRunner>