@ohtaman/washi 0.5.0 → 0.7.0

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

@@ -0,0 +1,157 @@
+# Traveling Salesperson Problem (TSP via Benders Decomposition)
+
+| 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">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.
+
+In the **Dantzig-Fulkerson-Johnson (DFJ)** formulation, preventing disconnected cycles (**subtours**) requires subtour elimination constraints for every non-empty proper subset of cities $S \subset V$:
+
+$$\sum_{i \in S, j \notin S} x_{ij} \ge 1 \quad \forall S \subset V, \; 2 \le |S| \le |V| - 1$$
+
+Because there are $2^n - 2$ subsets, enumerating all subtour constraints upfront is impractical as $n$ grows. With **Benders Decomposition (Lazy Constraint Separation)**, constraints are added only when violated:
+1. **Master Problem**: Solves the degree-assignment relaxation (each city has 1 incoming and 1 outgoing edge).
+2. **Separation Subproblem**: Inspects the candidate solution graph. If disconnected cycles exist, it adds a **Benders Feasibility Cut** eliminating the smallest cycle and resolves until a single connected tour is obtained.
+
+## Problem Inputs
+
+We consider **5 cities** on a 2D Euclidean coordinate grid:
+
+| City | Coordinates $(x, y)$ |
+| :--- | :---: |
+| **City A (0)** | $(0, 0)$ |
+| **City B (1)** | $(1, 0)$ |
+| **City C (2)** | $(1, 2)$ |
+| **City D (3)** | $(0, 2)$ |
+| **City E (4)** | $(0.5, 3)$ |
+
+## Implementation in WaSHI
+
+<CodeRunner>
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+async function runTSP() {
+  const cities = [
+    { name: "A", x: 0, y: 0 },
+    { name: "B", x: 1, y: 0 },
+    { name: "C", x: 1, y: 2 },
+    { name: "D", x: 0, y: 2 },
+    { name: "E", x: 0.5, y: 3 },
+  ];
+  const n = cities.length;
+
+  function dist(i, j) {
+    const dx = cities[i].x - cities[j].x;
+    const dy = cities[i].y - cities[j].y;
+    return Math.hypot(dx, dy);
+  }
+
+  // 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
+  master.objective(minimize(expr`dot(${distMatrix}, ${x})`));
+
+  // Each city must have 1 outgoing and 1 incoming edge
+  for (let i = 0; i < n; 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...");
+
+  // 2. Solve via Benders Decomposition
+  let cutCounter = 0;
+  const result = await master.solveBenders({
+    subproblem: () => {
+      // Find active directed edges in the master solution
+      const succ = {};
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i !== j && x[i][j].value === 1) {
+            succ[i] = j;
+          }
+        }
+      }
+
+      // Trace connected cycles
+      const visited = new Set();
+      const cycles = [];
+      for (let i = 0; i < n; i++) {
+        if (!visited.has(i)) {
+          const cycle = [];
+          let curr = i;
+          while (!visited.has(curr)) {
+            visited.add(curr);
+            cycle.push(curr);
+            curr = succ[curr];
+          }
+          cycles.push(cycle);
+        }
+      }
+
+      // If more than 1 cycle, subtours exist: inject Benders feasibility cuts for all cycles
+      if (cycles.length > 1) {
+        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
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Optimal Tour Distance: ${result.objectiveValue?.toFixed(3)}`);
+  console.log(`Total Benders Cuts Added: ${result.cutsAdded}`);
+  console.log(`Iterations: ${result.iterations}`);
+
+  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}`] === 1) {
+        console.log(`  ${cities[i].name} -> ${cities[j].name} (distance: ${dist(i, j).toFixed(3)})`);
+      }
+    }
+  }
+}
+
+runTSP();
+```
+
+</CodeRunner>
+
+## 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.
+- **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.

package/docs/examples/vehicle-routing.md

@@ -0,0 +1,208 @@
+# Capacitated Vehicle Routing Problem (CVRP, 50 Customers via Column Generation)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Combinatorial OR / Dantzig-Wolfe | HiGHS (default) | `m.solveColumnGeneration()`, `pricing`, `m.binary()`, `m.constraint()`, `expr` (`sum`) | <ul><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/13-vehicle-routing-column-generation.ts">Source Code</a></li><li><a href="/guide/decomposition">Decomposition Guide</a></li></ul> |
+
+The **Capacitated Vehicle Routing Problem (CVRP)** determines the minimum number of delivery vehicles needed to visit a set of customers, subject to vehicle cargo capacity, maximum customer stops per shift, and route duration limits.
+
+In a monolithic MIP formulation, enumerating all possible customer combinations and visit sequences leads to $O(2^n)$ binary variables. With **Column Generation (Dantzig-Wolfe Decomposition)**, routes are generated on demand:
+1. **Restricted Master Problem (RMP)**: Solves a set partitioning problem that selects a subset of candidate routes so that every customer is visited once.
+2. **Pricing Subproblem**: Uses the dual values (shadow prices) from the master LP relaxation to construct improving routes with negative reduced cost ($\bar{c} = 1 - \sum \pi_i < 0$) via cheapest insertion and 2-opt local search.
+
+## Problem Inputs
+
+We consider a distribution network with a central depot at $(0, 0)$ and **50 customer locations**:
+
+- **Vehicle Cargo Capacity**: At most **10 units** per vehicle.
+- **Maximum Stops**: At most **4 customers** per route.
+- **Maximum Shift Duration**: At most **200 minutes** (transit time + service time) per route.
+- **Transit & Service Times**: Euclidean distances between nodes (1 unit = 1 minute) plus **10 minutes** of unloading service time per customer.
+
+## Implementation in WaSHI
+
+<CodeRunner>
+
+```typescript
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+// --- Extracted Routing Helpers ---
+
+// 2-opt local search to eliminate crossing paths in a tour
+function optimize2Opt(tour, dist) {
+  let best = [...tour];
+  let improved = true;
+
+  while (improved) {
+    improved = false;
+    for (let i = 1; i < best.length - 2; i++) {
+      for (let j = i + 1; j < best.length - 1; j++) {
+        const dCurrent = dist(best[i - 1], best[i]) + dist(best[j], best[j + 1]);
+        const dSwap = dist(best[i - 1], best[j]) + dist(best[i], best[j + 1]);
+        if (dSwap < dCurrent) {
+          best = [...best.slice(0, i), ...best.slice(i, j + 1).reverse(), ...best.slice(j + 1)];
+          improved = true;
+        }
+      }
+    }
+  }
+  return best;
+}
+
+// Inserts a customer into the tour at the position that minimizes detour distance
+function insertCheapest(tour, id, dist) {
+  let bestPos = 1;
+  let minCost = Infinity;
+
+  for (let p = 1; p < tour.length; p++) {
+    const cost = dist(tour[p - 1], id) + dist(id, tour[p]) - dist(tour[p - 1], tour[p]);
+    if (cost < minCost) {
+      minCost = cost;
+      bestPos = p;
+    }
+  }
+  return [...tour.slice(0, bestPos), id, ...tour.slice(bestPos)];
+}
+
+// Calculates transit time and total duration (transit + service) for a tour
+function calcRouteTime(tour, dist, serviceTimes) {
+  let travelTime = 0;
+  for (let i = 0; i < tour.length - 1; i++) {
+    travelTime += dist(tour[i], tour[i + 1]);
+  }
+  const serviceTime = tour.slice(1, -1).reduce((acc, id) => acc + (serviceTimes[id] ?? 0), 0);
+  return { travelTime, totalTime: travelTime + serviceTime };
+}
+
+// Pricing subproblem: Finds an improving route with negative reduced cost (1 - dualSum < 0)
+function findImprovingRoute(candidates, config) {
+  let bestRoute = null;
+  let minReducedCost = -1e-4;
+
+  for (const seed of candidates.slice(0, 15)) {
+    let tour = ["Depot", seed.id, "Depot"];
+    let load = seed.demand;
+    let dualSum = seed.dual;
+
+    for (const next of candidates) {
+      if (tour.includes(next.id)) continue;
+      if (load + next.demand > config.vehicleCapacity) continue;
+      if (tour.length - 2 >= config.maxStops) continue;
+
+      const candidateTour = optimize2Opt(insertCheapest(tour, next.id, config.dist), config.dist);
+      const { totalTime } = calcRouteTime(candidateTour, config.dist, config.serviceTimes);
+
+      if (totalTime <= config.maxRouteTime) {
+        tour = candidateTour;
+        load += next.demand;
+        dualSum += next.dual;
+      }
+    }
+
+    const reducedCost = 1 - dualSum;
+    if (reducedCost < minReducedCost) {
+      minReducedCost = reducedCost;
+      bestRoute = tour;
+    }
+  }
+  return bestRoute;
+}
+
+// --- Main CVRP via Column Generation ---
+
+async function runCVRP() {
+  const vehicleCapacity = 10;
+  const maxStops = 4;
+  const maxRouteTime = 200; // minutes
+
+  // Central depot and 50 customer locations
+  const depot = { id: "Depot", x: 0, y: 0 };
+  const customers = Array.from({ length: 50 }, (_, i) => {
+    const angle = i * 2.4;
+    const radius = 15 + (i % 5) * 8;
+    return {
+      id: `C${i + 1}`,
+      x: Math.round(Math.cos(angle) * radius),
+      y: Math.round(Math.sin(angle) * radius),
+      demand: 1 + (i % 4),
+      serviceTime: 10,
+    };
+  });
+
+  const nodes = Object.fromEntries([depot, ...customers].map((n) => [n.id, n]));
+  const dist = (a, b) =>
+    Math.round(Math.hypot(nodes[a].x - nodes[b].x, nodes[a].y - nodes[b].y));
+  const serviceTimes = Object.fromEntries(customers.map((c) => [c.id, c.serviceTime]));
+
+  const routeConfig = { dist, serviceTimes, vehicleCapacity, maxStops, maxRouteTime };
+
+  // 1. Build Restricted Master Problem (RMP)
+  const master = new Model("CVRP_FleetMaster");
+
+  // Initial naive routes: 1 dedicated vehicle per customer
+  const initialRoutes = customers.map((c) => master.binary(`route_init_${c.id}`));
+  master.objective(minimize(expr`sum(${initialRoutes})`));
+
+  // Each customer must be visited by exactly 1 vehicle
+  const visitConstrs = customers.map((c, i) =>
+    master.constraint(expr`${initialRoutes[i]} == 1`, `visit_${c.id}`)
+  );
+
+  console.log(`Initial state: 50 naive single-customer routes (50 vehicles).`);
+  console.log("Solving via Column Generation with dual-directed heuristic pricing...");
+
+  // 2. Solve via Column Generation
+  const result = await master.solveColumnGeneration({
+    finalizeAsMIP: true,
+    pricing: async () => {
+      // 1. Sort customers by shadow price (dual profit) descending
+      const candidates = customers
+        .map((c, i) => ({ id: c.id, demand: c.demand, dual: visitConstrs[i].dual ?? 0 }))
+        .filter((c) => c.dual > 0)
+        .sort((a, b) => b.dual - a.dual);
+
+      // 2. Solve pricing subproblem: find route with negative reduced cost (dualSum > 1)
+      const bestRoute = findImprovingRoute(candidates, routeConfig);
+      if (!bestRoute) return null; // No improving column found
+
+      // 3. Propose new column to Restricted Master Problem
+      const { travelTime, totalTime } = calcRouteTime(bestRoute, dist, serviceTimes);
+      const coefficients = {};
+      for (const id of bestRoute.slice(1, -1)) {
+        coefficients[`visit_${id}`] = 1;
+      }
+
+      return {
+        cost: 1,
+        type: "Binary",
+        coefficients,
+        meta: { tour: bestRoute, travelTime, totalTime },
+      };
+    },
+  });
+
+  console.log(`\nStatus: ${result.status}`);
+  console.log(`Fleet Size: ${Math.round(result.objectiveValue ?? 0)} vehicles (heuristic column generation)`);
+  console.log(`Total Columns Generated: ${result.columnsAdded}`);
+
+  console.log("\nSample routes selected in fleet:");
+  const activeRoutes = result.generatedColumns.filter((c) => c.variable.value === 1);
+  for (const r of activeRoutes.slice(0, 5)) {
+    const meta = r.proposal.meta;
+    console.log(`  ${meta?.tour.join(" -> ")} (Transit: ${meta?.travelTime}m, Total: ${meta?.totalTime}m)`);
+  }
+}
+
+runCVRP();
+```
+
+</CodeRunner>
+
+## Notes
+
+- **Master Problem and Pricing Separation**: The master problem solves the LP relaxation and final set-partitioning MIP, while the `pricing` callback searches for negative-reduced-cost routes using cheapest insertion and 2-opt local search.
+- **Dual Value Access**: Dual values from the master LP relaxation are read from `visitConstrs[i].dual` to prioritize customers with higher shadow prices during route construction.
+- **Route Metadata**: Each proposed column attaches `{ tour, travelTime, totalTime }` under `meta`, allowing the ordered stop sequence to be inspected from `result.generatedColumns` after the solve completes.
+- **Set Partitioning (`== 1`) vs. Set Covering (`>= 1`)**: This example uses `== 1` so that the final MIP never covers a customer twice. In large-scale column generation, formulating coverage as `>= 1` restricts the dual prices to $\pi_i \ge 0$, avoiding negative dual oscillations; if the final MIP selects overlapping routes, duplicate visits can be removed by post-processing whenever distances satisfy the triangle inequality.
+- **Heuristic Pricing vs. Exact ESPPRC**: Because `findImprovingRoute` uses a fast greedy heuristic (cheapest insertion + 2-opt) instead of an exact Elementary Shortest Path Problem with Resource Constraints (ESPPRC) solver, returning `null` means no further improving columns were found by the heuristic rather than proving global LP optimality.
+- **Price-and-Branch (`finalizeAsMIP: true`)**: Solving the Restricted Master Problem as a MIP over the columns generated at the root node is known as the *Restricted Master Heuristic* (Price-and-Branch). It produces near-optimal integer fleets quickly without requiring full Branch-and-Price tree search.