@ohtaman/washi 0.4.0 → 0.6.0

package/docs/guide/objectives.md

@@ -0,0 +1,170 @@
+# Objectives & Solving (`m.solve` & `m.check`)
+
+The objective function defines the goal of mathematical optimization—whether to maximize profits, minimize costs, or minimize quadratic risk variance. When you only need to verify constraint feasibility or solve pure SMT logic, you can also run `m.check()` without an objective.
+
+---
+
+## Setting the Objective Function
+
+Set the objective direction and formula declaratively using `m.objective(maximize(...))` or `m.objective(minimize(...))`:
+
+```typescript
+import { Model, expr, maximize, minimize } from "@ohtaman/washi";
+
+const m = new Model("ProductionRevenue");
+const x = m.integer("x", { lb: 0, ub: 40 });
+const y = m.integer("y", { lb: 0, ub: 40 });
+
+// Maximize revenue: 50*x + 40*y subject to resource capacity
+m.objective(maximize(expr`50 * ${x} + 40 * ${y}`));
+m.constraint(expr`2 * ${x} + 3 * ${y} <= 100`, "resource_limit");
+
+// Or minimize cost:
+// m.objective(minimize(expr`10 * ${x} + 15 * ${y}`));
+```
+
+Calling `m.objective()` with no arguments returns the current objective expression (`LinExpr | QuadExpr`). If you omit setting an objective, the model defaults to minimizing `0`.
+
+---
+
+## 🚀 Solving the Model (`m.solve()` vs. `m.check()`)
+
+WaSHI provides two asynchronous execution entrypoints:
+
+| Method | Return Value | Purpose |
+| :--- | :--- | :--- |
+| **`await m.solve(options?)`** | `Promise<SolverStatus>` | Optimizes the objective (`Minimize` or `Maximize`) subject to all constraints. Populates primal values, objective value, MIP bounds/gaps, and LP duals/slacks. |
+| **`await m.check(options?)`** | `Promise<CheckResult>` | Checks constraint satisfiability without an objective. Returns `{ status, values, conflicts?, unsatCore?, runTime? }` where `values: Record<string, number \| boolean>` contains both numeric and Boolean variable assignments. Ideal for SMT/SAT verification and Z3 `unsatCore` extraction. |
+
+```typescript
+const status = await m.solve({
+  timeLimit: 10.0, // Timeout in seconds
+  mipGap: 0.01,    // Stop within 1% of global optimum
+  outputFlag: false, // Enable/disable solver console logging (HiGHS: outputFlag, GLPK: verbose)
+});
+```
+
+### Solve Options (`SolveOptions`)
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `solver` | `string` \| `Solver` | Model's solver (`"highs"`) | Registered solver name (e.g. `"highs"`, `"z3"`, `"glpk"`, or custom) or `Solver` instance for this run. |
+| `timeLimit` | `number` | `undefined` | Maximum solve duration in seconds. |
+| `mipGap` / `relGap` | `number` | `undefined` | Relative MIP optimality gap tolerance (e.g. `0.01` for 1%). |
+| `absGap` | `number` | `undefined` | Absolute MIP optimality gap tolerance (HiGHS `mip_abs_gap`). |
+| `presolve` | `"on"` \| `"off"` \| `"choose"` | `"choose"` | Controls solver presolve reduction prior to optimization. |
+| `outputFlag` / `verbose` | `boolean` | `false` | Emits internal solver iteration logs (`outputFlag` for HiGHS, `verbose` for GLPK). |
+| `useWorker` | `boolean` | `true` (browser) | Offloads HiGHS to a dedicated Web Worker in browsers. Set `false` for main-thread execution. |
+| `wasmUrl` | `string` | Auto-resolved | Custom URL to load `highs.wasm` in browser deployments. |
+| `signal` | `AbortSignal` | `undefined` | Cooperative cancellation signal (`AbortController.signal`). |
+| `onProgress` | `(e: SolveProgressEvent) => void` | `undefined` | Callback receiving live solver progress snapshots. |
+
+You can also pass a solver name directly as the first argument: `await m.solve("glpk", { timeLimit: 5 })`.
+
+---
+
+## ⏱️ Real-Time Progress (`onProgress`) & Cancellation (`AbortSignal`)
+
+For long-running MIP optimizations in interactive UIs, you can stream live branch-and-bound progress (`SolveProgressEvent`) and allow users to cancel the solve cleanly with `AbortController`:
+
+```typescript
+const controller = new AbortController();
+
+// Example: cancel if the user clicks a "Stop" button or after a custom condition
+const status = await m.solve({
+  signal: controller.signal,
+  onProgress: (event) => {
+    console.log(
+      `[${event.elapsedTime.toFixed(1)}s] ` +
+      `Best: ${event.objectiveValue ?? "—"}, ` +
+      `Bound: ${event.objectiveBound ?? "—"}, ` +
+      `Gap: ${event.mipGap !== undefined ? (event.mipGap * 100).toFixed(2) + "%" : "—"}`
+    );
+
+    // Optional: stop early as soon as a good-enough incumbent is found
+    if (event.objectiveValue !== undefined && event.objectiveValue >= 1000) {
+      controller.abort();
+    }
+  },
+});
+
+console.log("Status:", m.status);                   // "Feasible" (if an incumbent was found before abort) or "Unknown"
+console.log("Termination:", m.terminationStatus);   // "Interrupted"
+console.log("Has incumbent:", m.hasPrimalSolution); // true if an incumbent was available
+```
+
+### `SolveProgressEvent` Fields
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `elapsedTime` | `number` | Elapsed solver time in seconds (optional alias: `elapsedSeconds`). |
+| `phase` | `"simplex" \| "ipm" \| "mip" \| undefined` | Current solver phase when known. |
+| `objectiveValue` | `number \| undefined` | Current best feasible incumbent objective value (MIP). |
+| `objectiveBound` | `number \| undefined` | Current best proven dual / objective bound (MIP). |
+| `relGap` / `mipGap` | `number \| undefined` | Current relative MIP optimality gap (`0.05` = 5%). |
+| `absGap` | `number \| undefined` | Current absolute MIP optimality gap `\|objectiveValue - objectiveBound\|`. |
+| `nodes` | `number \| undefined` | Branch-and-bound nodes explored so far. |
+| `iterations` | `number \| undefined` | Solver iteration count (simplex, IPM, or MIP LP iterations). |
+| `message` | `string \| undefined` | Raw progress line emitted by the solver. |
+
+---
+
+## 📊 Reading Results, Bounds & Solver Status
+
+After solving, query the status, optimal values, and MIP optimality bounds on the `Model`:
+
+```typescript
+const status = await m.solve();
+
+console.log("Status:", m.status);                         // e.g. "Optimal" or "Feasible"
+console.log("Termination Reason:", m.terminationStatus);  // e.g. "Optimal", "TimeLimit", "Interrupted"
+console.log("Has Primal Solution:", m.hasPrimalSolution); // true when x.value / m.objectiveValue are populated
+
+// Objective & MIP Gap Metrics
+console.log("Objective Value:", m.objectiveValue);        // Best primal objective (or null)
+console.log("Objective Bound:", m.objectiveBound);        // Best dual bound (or undefined)
+console.log("Relative Gap:", m.relGap);                   // Relative MIP gap (alias: m.mipGap)
+console.log("Absolute Gap:", m.absGap);                   // |objectiveValue - objectiveBound|
+
+// Individual & Bulk Variable Values
+console.log("x =", x.value, "y =", y.value);
+console.log(m.getValues({ x, y }));                       // { x: ..., y: ... }
+```
+
+### Understanding `m.status` vs. `m.terminationStatus`
+
+When a MIP solver stops early due to a time limit, iteration limit, or `AbortSignal`, two distinct questions matter:
+1. **Is there a usable solution?** (`m.hasPrimalSolution` / `m.status`)
+2. **Why did the solver stop?** (`m.terminationStatus`)
+
+If an integer-feasible incumbent was found before hitting `timeLimit` or `signal.abort()`, WaSHI sets `m.status = "Feasible"` (so you know `x.value` and `m.objectiveValue` hold a valid solution) and sets `m.terminationStatus = "TimeLimit"` (or `"Interrupted"`). If no incumbent was found before stopping, `m.hasPrimalSolution` is `false`, `m.terminationStatus` records why the solver stopped (`"TimeLimit"`, `"IterationLimit"`, or `"Interrupted"`), and `m.status` is `"TimeLimit"`, `"IterationLimit"`, or `"Unknown"` (when aborted via `AbortSignal` without an incumbent).
+
+### All `SolverStatus` Values
+
+| Status | `hasPrimalSolution` | Meaning |
+| :--- | :--- | :--- |
+| `"Optimal"` | `true` | Global optimal solution proven (within tolerances). |
+| `"Feasible"` | `true` | Valid primal solution (incumbent) found, but optimality was not proven before stopping (`terminationStatus` indicates why: `"TimeLimit"`, `"IterationLimit"`, `"Interrupted"`, etc.). |
+| `"Sat"` | `true` | Constraints are satisfiable (`m.check()`). |
+| `"Infeasible"` | `false` | Proven mathematically infeasible; no solution satisfies all constraints. |
+| `"Unsat"` | `false` | Logical/arithmetic constraints are unsatisfiable (`m.check()`). |
+| `"Unbounded"` | `false` | Objective can improve indefinitely without violating constraints. |
+| `"TimeLimit"` | `false` | Time limit reached before finding any feasible primal solution. |
+| `"IterationLimit"` | `false` | Iteration limit reached before finding any feasible primal solution. |
+| `"Unknown"` | `false` | Solver stopped inconclusively without a valid primal solution (including when cancelled via `AbortSignal` before finding an incumbent, where `terminationStatus === "Interrupted"`). |
+| `"Error"` | `false` | Solver encountered an internal execution error. |
+| `"NotSolved"` | `false` | Initial state before solving, or after the model has been mutated. |
+
+---
+
+## 🔄 Model Mutations & Execution Validity
+
+A `Model` instance keeps its solution state synchronized across mutations made through `Model` methods and `Model` / `Var` / `Constraint` property setters:
+
+1. **Post-Solve Mutations Reset Solution State**: Adding variables or constraints, updating the objective (`m.objective(...)`, `m.objectiveExpr = ...`, `m.sense = ...`), or modifying variable bounds/types (`v.lb`, `v.ub`, `v.type`) or constraint properties (`c.lhs`, `c.sense`, `c.rhs`) immediately resets `m.status` to `"NotSolved"`, clears `m.solution` and `m.objectiveValue`, and resets variable/constraint primal and dual values to `null`.
+2. **Mid-Flight Mutations Discard Stale Runs**: If the model is modified via these APIs while an asynchronous `m.solve()` or `m.check()` call is in progress, the stale solver result is discarded, the model remains in `"NotSolved"`, and the in-flight promise rejects with an explicit error.
+3. **Overlapping Executions**: Starting a new `m.solve()` or `m.check()` call supersedes any earlier in-flight call on the same model so out-of-order completions can never overwrite the latest run's state.
+4. **Transactional Batch Edits**: If an invalid edit is rejected (including batch array calls like `m.constraint([...])`), the model rolls back the failed edit without leaving partial entities registered or invalidating an existing valid solution.
+
+> [!NOTE]
+> Renaming already-registered variables or constraints (e.g., reassigning `c.name` after registration) or mutating internal backing collections and ASTs directly (such as `c.lhs.terms`, `m.constraints.splice(...)`, or `BoolOp.children`) is unsupported and will be rejected by model integrity validation on the next solve/check/export call.

package/docs/guide/unsat-core.md

@@ -0,0 +1,154 @@
+# Conflict Diagnosis (`unsatCore`) & Solution Validation
+
+When building real-world optimization and configuration systems, two verification questions arise constantly:
+1. **Why is my model infeasible?** Which specific business rules contradict each other?
+2. **Does the solver's solution genuinely satisfy every constraint?** How do I verify tolerances, integrality, and formulations?
+
+WaSHI provides built-in tools for both: **Unsat Core conflict diagnosis** via Z3 (`m.check()`), **independent solution validation** (`m.validateSolution()`), **LP formulation export** (`m.toLpString()`), and **fast unit testing** (`MockSolver`).
+
+---
+
+## 🔍 Conflict Diagnosis (`unsatCore` / `conflicts`)
+
+When a model is **Infeasible**, traditional MIP solvers simply report that no solution exists without indicating *which* constraints are contradictory.
+By calling **`await m.check({ solver: "z3" })`**, WaSHI uses Z3's `assertAndTrack` mechanism to compute an **Unsatisfiable Core (`unsatCore`)**—a conflicting subset of named constraints that cannot be satisfied simultaneously:
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+// Register the Z3 solver plugin
+import "@ohtaman/washi/solvers/z3";
+
+const m = new Model();
+
+const x = m.continuous("reserve", { lb: 0 });
+
+// Add named business requirements
+m.constraint(expr`${x} >= 100`, "minimum_regulatory_reserve");
+m.constraint(expr`${x} <= 50`, "budget_ceiling");
+m.constraint(expr`${x} >= 10`, "routine_operating_cost");
+
+const result = await m.check({ solver: "z3" });
+
+if (result.status === "Unsat") {
+  console.log("Contradictory constraints identified:");
+  console.log(m.conflicts); // or result.conflicts / result.unsatCore / m.unsatCore
+  // Output: ["minimum_regulatory_reserve", "budget_ceiling"]
+}
+```
+
+Notice that `routine_operating_cost` is **not** in the core, because only `minimum_regulatory_reserve` ($x \ge 100$) and `budget_ceiling` ($x \le 50$) directly contradict each other.
+
+> [!IMPORTANT]
+> - **Use `m.check({ solver: "z3" })` for Unsat Core extraction**: `m.solve()` runs optimization (`Z3.Optimize`), whereas `m.check()` runs tracked satisfiability checking (`Z3.Solver.assertAndTrack`) and populates `result.conflicts` / `m.conflicts` (and alias `m.unsatCore`).
+> - **Name your constraints**: Variable bounds (`lb`, `ub`) act as background domain declarations. To include a bound or business rule in the reported `unsatCore` list, register it as a named constraint via `m.constraint(expr`...`, "rule_name")`.
+
+### Workflow: Infeasibility Diagnosis with HiGHS or Z3
+
+Because WaSHI models are solver-independent, you can diagnose infeasibilities using either solver:
+1. **Built-in HiGHS & GLPK (default)**: `await m.check()` uses a single-solve elastic slack formulation ($\min \sum s_i$) to identify which constraints required relaxation (`diag.conflicts`), requiring no extra dependencies.
+2. **Z3 SMT Solver**: `await m.check({ solver: "z3" })` uses SMT tracking to extract an exact unsatisfiable core (`diag.unsatCore` / `diag.conflicts`).
+
+```typescript
+const status = await m.solve(); // Fast MIP solve with default HiGHS
+
+if (status === "Infeasible") {
+  // Option 1: Built-in single-solve elastic diagnosis with HiGHS
+  const diag = await m.check();
+  console.error("Model is infeasible due to conflicting rules:", diag.conflicts);
+
+  // Option 2: Exact SMT unsat core diagnosis with Z3 (requires import "@ohtaman/washi/solvers/z3")
+  // const z3Diag = await m.check({ solver: "z3" });
+  // console.error("Z3 Unsat Core:", z3Diag.unsatCore);
+}
+```
+
+---
+
+## ✅ Independent Solution Validation (`m.validateSolution()`)
+
+After solving a model (or supplying a custom candidate map via `values`), you can independently verify that all variable bounds, integer/binary domains, linear constraints, and logical SMT formulas hold against the original model definitions:
+
+```typescript
+const status = await m.solve();
+
+if (m.hasPrimalSolution) {
+  const report = m.validateSolution({
+    feasibilityTolerance: 1e-6,     // Max allowed violation for bounds and linear constraints
+    integralityTolerance: 1e-6,     // Max distance from nearest integer for Integer/Binary vars
+    evaluateLogicalConstraints: true,
+  });
+
+  console.log("Valid:", report.valid);
+  console.log("Complete:", report.complete);
+  console.log("Max violation:", report.maxViolation);
+  console.log("Summary:", report.summary);
+
+  if (!report.valid) {
+    console.warn("Violations detected:", report.violations);
+  }
+}
+```
+
+### `SolutionValidationReport` Summary
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `valid` | `boolean` | `true` iff `complete === true`, `uncheckedConstraints.length === 0`, and `violations.length === 0`. |
+| `complete` | `boolean` | `true` when all variables, Boolean variables, linear constraints, and logical constraints were evaluated. |
+| `maxViolation` | `number` | Largest numeric violation magnitude across all evaluated bounds, integrality checks, and constraints. |
+| `violations` | `SolutionViolation[]` | Flat list of violations (`"missing_value"`, `"non_finite_value"`, `"invalid_boolean_value"`, `"lower_bound"`, `"upper_bound"`, `"integrality"`, `"linear_constraint"`, `"logical_constraint"`, `"unchecked_constraint"`). |
+| `violationsByName` | `Record<string, SolutionViolation[]>` | Violations grouped by variable or constraint name. |
+| `uncheckedConstraints` | `string[]` | Names of constraints that could not be evaluated. |
+| `missingVariables` | `string[]` | Names of numeric or Boolean variables whose values were `null` or `undefined`. |
+| `summary` | `SolutionValidationSummary` | Counts of checked vs. total variables, Boolean variables, linear constraints, and logical constraints. |
+
+---
+
+## 📄 Inspecting the LP Formulation (`m.toLpString()`)
+
+When debugging coefficients, signs, or Big-M indicator expansions, call `m.toLpString()` to export the model in standard CPLEX/HiGHS `.lp` format:
+
+```typescript
+const m = new Model("DebugModel");
+const x = m.integer("x", { lb: 0, ub: 10 });
+m.objective(maximize(expr`5 * ${x}`));
+m.constraint(expr`2 * ${x} <= 15`, "resource_limit");
+
+console.log(m.toLpString());
+/*
+Maximize
+ obj: 5 x
+Subject To
+ resource_limit: 2 x <= 15
+Bounds
+ 0 <= x <= 10
+Generals
+ x
+End
+*/
+```
+
+---
+
+## 🧪 Unit Testing Application Logic with `MockSolver`
+
+When running unit tests for application code that builds or consumes a WaSHI `Model`, you can use the built-in `MockSolver` (`solver: "mock"`) to return deterministic results instantaneously without loading WebAssembly:
+
+```typescript
+import { Model, MockSolver, expr, maximize } from "@ohtaman/washi";
+
+const mock = new MockSolver({
+  status: "Optimal",
+  objectiveValue: 420,
+  values: { x: 10, y: 20 },
+});
+
+const m = new Model({ solver: mock });
+const x = m.integer("x");
+const y = m.integer("y");
+m.objective(maximize(expr`10 * ${x} + 16 * ${y}`));
+
+await m.solve();
+console.log(m.objectiveValue); // 420
+console.log(x.value, y.value); // 10, 20
+```

package/docs/guide/variables.md

@@ -0,0 +1,188 @@
+# Variables & Domains
+
+Variables represent the mathematical decision variables in your optimization model.
+WaSHI provides domain-specific factory methods on the `Model` instance: `m.continuous()`, `m.integer()`, `m.binary()`, and `m.bool()`.
+
+---
+
+## Decision Variable Types
+
+### 1. Continuous Variables (`m.continuous`)
+Can take any real number value within `[lb, ub]`. Ideal for physical measurements, flow rates, budgets, and weights:
+
+```typescript
+import { Model } from "@ohtaman/washi";
+
+const m = new Model();
+
+// Single continuous variable bounded in [0, 1000]
+const fuel = m.continuous("fuel", { lb: 0, ub: 1000 });
+```
+
+### 2. Integer Variables (`m.integer`)
+Restricted to integers. Ideal for countable assets (machines, trucks, staff count):
+
+```typescript
+// Single integer variable bounded in [0, 15]
+const trucks = m.integer("trucks", { lb: 0, ub: 15 });
+```
+
+### 3. Binary Variables (`m.binary`)
+Restricted to $\{0, 1\}$ as mathematical 0-1 values. Ideal for MIP selection, yes/no decisions, and facility selections:
+
+```typescript
+// Single binary variable
+const openWarehouse = m.binary("open_warehouse");
+// lb is automatically 0, ub is automatically 1
+```
+
+### 4. Propositional Boolean Variables (`m.bool`)
+Pure boolean logic propositions for SMT / SAT modeling with Z3:
+
+```typescript
+// Single propositional boolean variable
+const isNight = m.bool("isNight");
+const alarmTriggered = m.bool("alarmTriggered");
+
+// First-class boolean operators: and, or, not, implies, xor
+m.constraint(alarmTriggered.implies(isNight), "alarm_policy");
+```
+
+### 💡 Modeling Semi-Continuous Decisions
+Semi-continuous variables take values in $\{0\} \cup [L, U]$ (either zero or between a positive lower and upper bound, useful for minimum production batches or operational thresholds).
+
+While not a primitive `VarType` in `Model`, semi-continuous behavior is cleanly modeled by combining a continuous variable with a binary indicator variable and linking constraints ($L \cdot b \le x \le U \cdot b$):
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+
+const m = new Model();
+const batch = m.continuous("batch", { lb: 0, ub: 100 });
+const isActive = m.binary("is_active");
+
+// If isActive === 0, batch is forced to 0; if 1, batch is within [10, 100]
+m.constraint(expr`${batch} >= 10 * ${isActive}`, "min_batch_run");
+m.constraint(expr`${batch} <= 100 * ${isActive}`, "max_batch_run");
+```
+
+---
+
+## Multi-Dimensional & Array Creation
+
+The domain factory methods (`continuous`, `integer`, `binary`, `bool`) support count, arrays of keys, and row/column keys to create 1D arrays, typed dictionaries, and 2D matrices in a single call.
+
+### By Count
+Pass a number to create an array of variables:
+
+```typescript
+const x = m.continuous(5, { lb: 0 }); // Var[] (x_0, ..., x_4)
+const flags = m.bool(3);              // BoolVar[] (p_0, p_1, p_2)
+```
+
+### 1D Variable Dictionaries
+Pass an array of keys to get a typed dictionary `Record<string, Var>` or `Record<string, BoolVar>`:
+
+```typescript
+const items = ["laptop", "phone", "tablet"];
+
+// Record<"laptop" | "phone" | "tablet", Var>
+const selected = m.binary(items);
+
+const perms = m.bool(["read", "write", "execute"]);
+// perms.read, perms.write, perms.execute
+```
+
+### 2D Variable Matrices & Grids
+Each dimension follows a consistent rule: passing a numeric count (`number`) produces an `Array`, and passing a collection of keys produces a `Record`:
+- `(rowsCount, colsCount)` $\rightarrow$ `Var[][]` (or `BoolVar[][]`)
+- `(rowKeys, colKeys)` $\rightarrow$ `Record<R, Record<C, Var>>` (or `Record<R, Record<C, BoolVar>>`)
+- `(rowsCount, colKeys)` $\rightarrow$ `Array<Record<C, Var>>`
+- `(rowKeys, colsCount)` $\rightarrow$ `Record<R, Var[]>`
+
+```typescript
+const factories = ["Tokyo", "Osaka"];
+const stores = ["StoreA", "StoreB", "StoreC"];
+
+// 1. Named keys x Named keys -> Record<string, Record<string, Var>>
+const ship = m.continuous(factories, stores, { lb: 0 });
+// ship.Tokyo.StoreA
+
+// 2. Numeric count x Numeric count -> Var[][] (2D Array)
+const board = m.binary(8, 8, { prefix: "queen" });
+// board[0][0], board.map(...)
+
+// 3. Mixed dimensions: Named keys x Numeric count -> Record<string, Var[]>
+const schedule = m.binary(factories, 7, { prefix: "open_day" });
+// schedule.Tokyo[0]
+```
+
+---
+
+## Variable Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `lb` | `number` | `0` | Lower bound. Defaults to 0 (non-negative). |
+| `ub` | `number` | `Infinity` (or `1` for binary) | Upper bound. |
+| `type` | `"Continuous"` \| `"Integer"` \| `"Binary"` | Inferred from method | Underlying variable domain category. |
+| `initialValue` | `number` | `undefined` | Optional primal solution hint (MIP start), kept distinct from solved `variable.value`. |
+
+---
+
+## Primal Initial Values (Warm-Start Hints)
+
+When rebuilding a model across iterations with stable variable names, you can supply optional primal initial values (`initialValue`) on a subset or all numeric variables (`m.continuous`, `m.integer`, `m.binary`, or `v.initialValue = ...`):
+
+```typescript
+const prevValues: Record<string, number | null> = { trucks: 8, open_warehouse: 1 };
+
+const m2 = new Model("RebuiltMIP");
+const trucks2 = m2.integer("trucks", {
+  lb: 0,
+  ub: 15,
+  initialValue: prevValues.trucks ?? undefined,
+});
+const openWarehouse2 = m2.binary("open_warehouse", {
+  initialValue: prevValues.open_warehouse ?? undefined,
+});
+const extraCapacity = m2.continuous("extra_capacity", { lb: 0 }); // Partial start: no initialValue needed
+```
+
+- **Hint vs. Hard Constraint**: `initialValue` is strictly an optional solver hint (passed to HiGHS via `setSolution`). It does **not** fix the variable, add a constraint, or guarantee either solver acceptance or a runtime speedup. It remains separate from `variable.value` (which is `null` until solved and populated with the solver's primal solution).
+- **Validation & Tolerance (`1e-6`)**: Supplied values must be finite numbers within `[lb - 1e-6, ub + 1e-6]` (and within `1e-6` of an integer inside bounds for `"Integer"` and `"Binary"` variables). Partial starts are not required to satisfy every model constraint.
+- **Solver Support**: Supported by **HiGHS** (`capabilities.supportsWarmStart === true`). Solvers without warm-start support (**GLPK**, **Z3**, or custom adapters without `supportsWarmStart: true`) reject `solve()` and `check()` with a descriptive error rather than silently ignoring `initialValue`.
+
+---
+
+## Accessing Solution Values & Reduced Costs
+
+After calling `await m.solve()` or `await m.check()`, assigned variable values (optimal or incumbent primal values from `solve()`, or a satisfying assignment from `check()`) are accessible via `variable.value` (returns `number | null` for `Var`, or `boolean | null` for `BoolVar`) or the bulk accessor `m.getValues()`:
+
+```typescript
+await m.solve();
+
+// Single variable primal value
+console.log(`trucks: ${trucks.value}`);
+
+// Reduced cost (LP sensitivity analysis — how much an objective coefficient must improve before a variable at its bound enters the basis)
+console.log(`fuel reduced cost: ${fuel.reducedCost}`);
+
+// Bulk extraction for 1D or 2D collections (works for both Var and BoolVar collections)
+const selectedValues = m.getValues(selected);
+// { laptop: 1, phone: 0, tablet: 1 }
+
+const flowValues = m.getValues(ship);
+// { Tokyo: { StoreA: 50, ... }, Osaka: { ... } }
+```
+
+---
+
+## Looking Up Variables by Name
+
+You can retrieve registered decision variables by name or inspect the total variable count on the model:
+
+```typescript
+const v = m.getVarByName("trucks");           // Var | undefined
+const b = m.getBoolVarByName("isNight");      // BoolVar | undefined
+console.log("Total numeric variables:", m.numVars);
+```