@ohtaman/washi 0.3.0 → 0.5.0

package/README.ja.md

@@ -16,7 +16,7 @@
   <p>
     <a href="https://www.npmjs.com/package/@ohtaman/washi"><img src="https://img.shields.io/npm/v/@ohtaman/washi?color=crimson&label=npm" alt="npm version" /></a>
     <a href="https://github.com/ohtaman/washi/actions/workflows/distribution.yml"><img src="https://github.com/ohtaman/washi/actions/workflows/distribution.yml/badge.svg" alt="CI Status" /></a>
-    <a href="https://ohtaman.github.io/washi/"><img src="https://img.shields.io/badge/docs-online-blue" alt="docs" /></a>
+    <a href="https://ohtaman.github.io/washi/ja/"><img src="https://img.shields.io/badge/docs-online-blue" alt="docs" /></a>
     <a href="https://ohtaman.github.io/washi/demo/"><img src="https://img.shields.io/badge/demo-playground-brightgreen" alt="live demo" /></a>
     <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
   </p>
@@ -24,24 +24,24 @@
 
 ---
 
-**WaSHI** は、Python の **PuLP** や Julia の **JuMP** に着想を得た、TypeScript / JavaScript 向けの代数モデラーです。アプリケーションのコードで変数・目的関数・数値制約や論理制約を記述できます。WaSHI はモデルの構築、ソルバー向けの変換、変数への結果の反映を担当し、最適化や充足可能性の判定は **HiGHS**・**Z3**・**GLPK** が行います。
+**WaSHI**（WebAssembly-backed, Solver-independent, High-level modeling Interface）は、Python の **PuLP** や Julia の **JuMP** に着想を得た、TypeScript / JavaScript 向けの代数モデラーです。アプリケーションのコードで変数・目的関数・数値制約や論理制約を記述できます。WaSHI はモデルの構築、ソルバー向けの変換、変数への結果の反映を担当し、最適化や充足可能性の判定は **HiGHS**・**Z3**・**GLPK** が行います。
 
 HiGHS が標準ソルバーで、Z3 と GLPK は任意で追加するプラグインです。Node.js 用とブラウザ用の配布物に WebAssembly アセットを含みます。配信に必要な設定は[ブラウザでの利用方法](#-ブラウザ--web-worker-での利用方法)を参照してください。
 
-[ブラウザデモを試す](https://ohtaman.github.io/washi/demo/) · [サンプルのソースと実行方法](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen のサンプル](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
+[ドキュメント](https://ohtaman.github.io/washi/ja/) · [ブラウザデモを試す](https://ohtaman.github.io/washi/demo/) · [AIエージェント向けクイックリファレンス](docs/ja/getting-started/ai-agents.md) · [Agent Skill (`SKILL.md`)](skills/washi/SKILL.md) · [サンプルのソースと実行方法](https://github.com/ohtaman/washi/blob/main/examples/README.md) · [ESM / script / CodePen のサンプル](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 
 const m = new Model("木工製品の利益最大化");
 const x = m.integer("机", { lb: 0 });
 const y = m.integer("椅子", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "木材上限");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "労働力上限");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "木材上限");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "労働力上限");
 
-await m.optimize();
+await m.solve();
 console.log(`生産量: x=${x.value}, y=${y.value} (最大利益: $${m.objectiveValue})`);
 ```
 
@@ -49,10 +49,10 @@ console.log(`生産量: x=${x.value}, y=${y.value} (最大利益: $${m.objective
 
 ## 🎯 WaSHI が提供するもの
 
-1. **代数的なモデル記述**: 直感的なドメイン変数メソッド（`m.binary`, `m.integer`, `m.continuous`）、タグ付きテンプレート（`expr`）、ベクトル集計関数（`dot`, `sum`）、そして第1推奨の `m.constrain()` により、数学的定義に忠実なモデルを簡潔に記述できます。
-2. **ソルバーアダプター**: 共通のモデリング API から HiGHS・Z3・GLPK を利用でき、[独自アダプターも登録できます](https://github.com/ohtaman/washi/blob/main/docs/custom-solver-guide.md)。モデルの問題クラスを扱えるソルバーを選ぶ必要があり、対応機能はソルバーごとに異なります。
-3. **ローカル実行と WebAssembly の配布**: ローカルソルバーのアダプターでは、別途 Python サービスや C/C++ のネイティブビルドを用意せず、アプリケーション内で求解できます。ブラウザへの配布には生成された JS・Worker・WASM が必要です。オフライン利用には、これらをローカルに配置するかキャッシュしておく必要があります。Z3 には追加のブラウザ隔離設定があります。
-4. **名前付き制約と SMT の結果**: Z3 を明示的に使って充足可能性を確認し、矛盾する制約の調査に Unsat Core を利用できます。返されるのは矛盾する制約の部分集合であり、最小の集合とは限りません。
+1. **代数的なモデル記述**: ドメイン変数メソッド（`m.binary`, `m.integer`, `m.continuous`）、タグ付きテンプレート（`expr`）、ベクトル集計関数（`dot`, `sum`）、およびファーストクラスの制約（`m.constraint`）によりモデルを記述します。JavaScript には演算子オーバーロードがないため、`` expr`...` `` は SQL のパラメータバインディングと同様に、中置記法の演算子（`+`, `-`, `*`, `^2`, `<=`, `>=`, `==`）を構文解析しつつ `${...}` に渡された値を型付きの `Var` や式のオブジェクト参照として直接バインドします。これにより、TypeScript の型検査、IDE のシンボルリネーム、多次元変数の添字参照（`${flow[i][j]}`）がそのまま機能します。
+2. **ソルバーアダプター**: 共通のモデリング API から HiGHS・Z3・GLPK を利用でき、[独自アダプターも登録できます](https://github.com/ohtaman/washi/blob/main/docs/ja/solvers/custom-solver.md)。モデルの問題クラスを扱えるソルバーを選ぶ必要があり、対応機能はソルバーごとに異なります。
+3. **ローカル実行と WebAssembly の配布**: ローカルソルバーのアダプターでは、別途 Python サービスや C/C++ のネイティブビルドを用意せずアプリケーション内で求解できるため、プロトタイプから Web ツールを公開する際のバックエンド構築のボトルネックを解消でき、ブラウザ内 LLM（WebGPU / WebLLM 等）とのクライアントサイド連携も容易です。ブラウザへの配布には生成された JS・Worker・WASM が必要です。オフライン利用には、これらをローカルに配置するかキャッシュしておく必要があります。Z3 には追加のブラウザ隔離設定があります。
+4. **名前付き制約と SMT の結果**: Z3 を明示的に使って充足可能性を確認し、矛盾する制約の調査に競合制約（`conflicts` / `unsatCore`）を利用できます。返されるのは矛盾する制約の部分集合であり、最小の集合とは限りません。
 
 モデルの構築と変換は WaSHI が担当します。扱える問題クラス、数値計算の挙動、求解時間は、選択したソルバー・設定・問題に依存します。モデル構築のオーバーヘッドとソルバーの実行時間は分けて計測する必要があり、特定のモデルでの結果は一般的な性能保証ではありません。
 
@@ -92,61 +92,54 @@ npm install z3-solver    # SMT・矛盾診断を利用する場合
 npm install glpk.js      # GLPK ソルバーを利用する場合 (GPL-3.0)
 ```
 
+*(任意)* AI コーディングエージェント（Claude Code, Antigravity, Cursor, Codex 等）向けに、[AIエージェント向けクイックリファレンス](docs/ja/getting-started/ai-agents.md)とあわせてポータブルな [`skills/washi/SKILL.md`](skills/washi/SKILL.md) を同梱しています：
+
+```bash
+mkdir -p .agents/skills/washi
+cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
+```
+
 ---
 
 ## 🚀 使い方ガイド
 
-### 1. 混合整数線形計画法 (MIP: 生産計画問題)
+### 1. 多次元変数・条件付き制約 (`m.indicator`)・解の検証 (`m.validateSolution`)
 
-リソース制約の下で利益を最大化する生産計画：
+1次元辞書や2次元マトリクス変数を1行で宣言し、`m.indicator()` による条件付き Big-M 制約、進捗イベント（`onProgress`）とキャンセル（`AbortSignal`）、および `m.validateSolution()` による独立解検証を行えます：
 
 ```ts
 import { Model, expr } from "@ohtaman/washi";
 
-const m = new Model("FactoryPlanning");
-
-// 決定変数（整数・非負）
-const chairs = m.integer("chairs", { lb: 0 });
-const tables = m.integer("tables", { lb: 0 });
-
-// テンプレートリテラル記法による自然な目的関数と制約
-m.maximize(expr`30 * ${chairs} + 50 * ${tables}`);
-m.constrain(expr`${chairs} + 2 * ${tables} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${chairs} + ${tables} <= 50`, "labor_limit");
-
-// 標準の HiGHS WASM エンジンで求解
-const status = await m.optimize();
-
-console.log(`ステータス: ${status}`); // "Optimal"
-console.log(`最大利益: $${m.objectiveValue}`); // 1100
-console.log(`生産数: 椅子=${chairs.value}, 机=${tables.value}`); // 椅子 20, 机 10
-```
+const m = new Model("FacilityPlanning");
 
-#### 🗂 多次元変数グリッド
-
-キー一覧や多次元インデックスから、1 行で変数群を定義：
-
-```ts
 // 1次元辞書形式のバイナリ変数群
 const openCity = m.binary(["Tokyo", "Osaka", "Nagoya"]);
 
 // 2次元輸送量行列: [工場] x [店舗]
-const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0 });
+const flow = m.continuous(["F1", "F2"], ["StoreA", "StoreB"], { lb: 0, ub: 1000 });
 
 // 2次元グリッド (例: 8x8 チェス盤)
 const board = m.binary(8, 8, { prefix: "queen" });
-```
-
-#### 🔀 Big-M インジケータ制約 (`m.indicator`)
 
-条件分岐や固定費の発生ルールを、煩雑な手動 Big-M 計算なしに記述：
-
-```ts
-// 「東京工場が稼働していない (openCity['Tokyo'] == 0) なら、生産量 flow は 0」
+// 条件付き Big-M 制約: 東京拠点が閉鎖 (openCity['Tokyo'] == 0) なら flow <= 0
+// (M を省略すると、変数の有限な上下限から安全な最小の Big-M が自動導出されます)
 m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
   activeValue: 0,
-  M: 1000,
+  name: "tokyo_closed_no_flow",
 });
+
+// 進捗コールバック (onProgress) と AbortSignal によるキャンセル制御
+const controller = new AbortController();
+await m.solve({
+  signal: controller.signal,
+  onProgress: (ev) => {
+    // 分枝限定法のライブ指標: ev.elapsedTime, ev.objectiveValue, ev.objectiveBound, ev.mipGap
+  },
+});
+
+// 求解結果が境界・整数性・線形/論理制約を満たすか独立検証
+const report = m.validateSolution();
+console.log("解の検証結果:", report.valid);
 ```
 
 ---
@@ -156,7 +149,7 @@ m.indicator(openCity["Tokyo"], expr`${flow["F1"]["StoreA"]} <= 0`, {
 期待リターンと予算制約を満たしつつ、共分散行列に基づく投資リスクを最小化：
 
 ```ts
-import { Model, QuadExpr, sum, dot, expr } from "@ohtaman/washi";
+import { Model, QuadExpr, sum, dot, minimize, expr } from "@ohtaman/washi";
 
 const m = new Model("MarkowitzPortfolio");
 const assets = ["Tech", "Bonds", "RealEstate"];
@@ -166,11 +159,11 @@ const returns = [0.14, 0.04, 0.08];
 const w = m.continuous(assets, { lb: 0, ub: 1 });
 
 // 1. 予算制約: 合計 100%
-m.constrain(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
+m.constraint(expr`${sum(assets, (a) => w[a])} == 1.0`, "budget");
 
 // 2. 目標リターン: 最低 8.5%
 const retMap = Object.fromEntries(assets.map((a, i) => [a, returns[i]]));
-m.constrain(expr`${dot(retMap, w)} >= 0.085`, "min_return");
+m.constraint(expr`${dot(retMap, w)} >= 0.085`, "min_return");
 
 // 3. 共分散行列 (リスク & 相関)
 const cov = [
@@ -186,9 +179,9 @@ for (let i = 0; i < assets.length; i++) {
     risk = risk.add(w[assets[i]].mul(w[assets[j]]).mul(cov[i][j]));
   }
 }
-m.minimize(risk);
+m.objective(minimize(risk));
 
-await m.optimize();
+await m.solve();
 console.log(`最小分散: ${m.objectiveValue?.toFixed(6)}`);
 assets.forEach((name) => {
   console.log(`  ${name}: ${((w[name].value || 0) * 100).toFixed(2)}%`);
@@ -207,20 +200,20 @@ import "@ohtaman/washi/solvers/z3";
 
 const m = new Model({ name: "SmartSecurityRules" });
 
-const isNight = m.addBoolVar("isNight");
-const motion = m.addBoolVar("motion");
-const alarm = m.addBoolVar("alarm");
-const siren = m.addBoolVar("siren");
+const isNight = m.bool("isNight");
+const motion = m.bool("motion");
+const alarm = m.bool("alarm");
+const siren = m.bool("siren");
 const lux = m.integer("lux", { lb: 0 });
 
 // 論理ルール
-m.constrain(lux.le(50).implies(isNight), "dark_implies_night");
-m.constrain(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
+m.constraint(lux.le(50).implies(isNight), "dark_implies_night");
+m.constraint(motion.and(isNight).and(alarm).implies(siren), "alarm_rule");
 
 // 観測されたセンサー値
-m.constrain(expr`${lux} <= 10`, "sensor_dark");
-m.constrain(motion, "sensor_motion");
-m.constrain(alarm, "alarm_on");
+m.constraint(expr`${lux} <= 10`, "sensor_dark");
+m.constraint(motion, "sensor_motion");
+m.constraint(alarm, "alarm_on");
 
 // 目的関数なしで制約充足可能性（SAT）を判定
 const res = await m.check({ solver: "z3" });
@@ -231,9 +224,9 @@ console.log(`サイレン作動？ ${m.values.get("siren")}`); // true
 
 ---
 
-### 4. 矛盾原因の自動特定 (`unsatCore`)
+### 4. 矛盾原因の自動特定 (`conflicts` / `unsatCore`)
 
-業務ルールや制約群が互いに矛盾している場合、**矛盾を引き起こしている制約の部分集合**（Unsat Core。最小性は保証しません）を特定してデバッグ（Z3 が必要）：
+業務ルールや制約群が互いに矛盾している場合、**矛盾を引き起こしている制約の部分集合**（Unsat Core / Conflicts。最小性は保証しません）を特定してデバッグ（Z3 が必要）：
 
 ```ts
 import { Model, expr } from "@ohtaman/washi";
@@ -242,27 +235,27 @@ import "@ohtaman/washi/solvers/z3";
 const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
 const engineers = m.integer("engineers", { lb: 0, ub: 20 });
 const budget = m.continuous("budget", { lb: 0, ub: 100000 });
-const rushDelivery = m.addBoolVar("rushDelivery");
+const rushDelivery = m.bool("rushDelivery");
 
 // ルール 1: エンジニア1人あたり $8,000
-m.constrain(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
 
 // ルール 2: 特急納品が必須
-m.constrain(rushDelivery, "rush_required");
+m.constraint(rushDelivery, "rush_required");
 
 // ルール 3: 特急納品には最低 8 人のエンジニアが必要
-m.constrain(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
 
 // ルール 4: 役員会の予算上限 $50,000 (矛盾: 8人 * $8000 = $64,000 > $50,000!)
-m.constrain(expr`${budget} <= 50000`, "strict_board_budget_cap");
+m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
 
 // ルール 5: 最低 1 人雇用の労働基準（無関係なルール）
-m.constrain(expr`${engineers} >= 1`, "minimum_one_employee");
+m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
 
 const res = await m.check({ solver: "z3" });
 
 console.log(`ステータス: ${res.status}`); // "Unsat"
-console.log("矛盾している制約:", res.unsatCore);
+console.log("矛盾している制約:", res.conflicts);
 // 出力: ["budget_limit", "rush_required", "rush_staffing_rule", "strict_board_budget_cap"]
 // ※ 無関係な "minimum_one_employee" は的確に除外されます
 ```
@@ -274,18 +267,18 @@ console.log("矛盾している制約:", res.unsatCore);
 GNU Linear Programming Kit (GLPK) ソルバープラグインを利用する場合：
 
 ```ts
-import { Model, expr } from "@ohtaman/washi";
+import { Model, expr, maximize } from "@ohtaman/washi";
 import "@ohtaman/washi/solvers/glpk";
 
 const m = new Model({ solver: "glpk" });
 const x = m.integer("x", { lb: 0 });
 const y = m.integer("y", { lb: 0 });
 
-m.maximize(expr`30 * ${x} + 50 * ${y}`);
-m.constrain(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
-m.constrain(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
+m.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+m.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_limit");
+m.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_limit");
 
-const status = await m.optimize();
+const status = await m.solve();
 console.log(`ステータス: ${status}`); // "Optimal"
 console.log(`目的関数値: ${m.objectiveValue}`); // 1100
 ```
@@ -297,7 +290,7 @@ console.log(`目的関数値: ${m.objectiveValue}`); // 1100
 ネストしたループを書くことなく、1次元・2次元の線形結合を1行で記述：
 
 ```ts
-import { Model, dot } from "@ohtaman/washi";
+import { Model, dot, minimize } from "@ohtaman/washi";
 
 const m = new Model();
 const factories = ["Tokyo", "Osaka"];
@@ -311,8 +304,8 @@ const costs = {
 const ship = m.continuous(factories, stores);
 
 // 総輸送コストを1行で最小化:
-m.minimize(dot(costs, ship));
-await m.optimize();
+m.objective(minimize(dot(costs, ship)));
+await m.solve();
 
 // 最適解の全変数値を取得
 const solution = m.getValues(ship);
@@ -362,23 +355,23 @@ await model.solve();
 </script>
 ```
 
-CDN から直接読み込む場合は、URL を `https://cdn.jsdelivr.net/npm/@ohtaman/washi@0.1.2/dist/browser/washi.min.js`（`0.1.2` 以降のバージョンを固定）に指定できます。ESM は同じ版の `dist/browser/washi.js` を指定します。CDN の URL を選ぶことが明示的な CDN 利用になり、ローカル配信が勝手に CDN へ切り替わることはありません。
+CDN から直接読み込む場合は、URL を `https://cdn.jsdelivr.net/npm/@ohtaman/washi@<version>/dist/browser/washi.min.js`（対応版リリースが公開された後にそのバージョンを指定）に指定できます。ESM は同じ版の `dist/browser/washi.js` を指定します。CDN の URL を選ぶことが明示的な CDN 利用になり、ローカル配信が勝手に CDN へ切り替わることはありません。
 
 ### ブラウザ環境でのソルバープラグイン（GLPK & Z3）
 
-ブラウザ配布物には、`dist/browser/solvers/` 配下に事前バンドルされたスタンドアロンソルバープラグインが含まれています（CDN 利用時は `>= 0.2.0` または `@latest` で利用可能）：
+ブラウザ配布物には、`dist/browser/solvers/` 配下に事前バンドルされたスタンドアロンソルバープラグインが含まれています：
 - **GLPK**: `dist/browser/solvers/glpk.js` (ESM) および `dist/browser/solvers/glpk.min.js` (IIFE、グローバル `WashiGLPK` を登録)
 - **Z3**: `dist/browser/solvers/z3.js` (ESM) および `dist/browser/solvers/z3.min.js` (IIFE、グローバル `WashiZ3` を登録)、ならびに `z3-built.js` / `z3-built.wasm`
 
 #### ブラウザ ESM での GLPK 利用
 ```html
 <script type="module">
-  import { Model } from "./washi/washi.js";
+  import { Model, maximize } from "./washi/washi.js";
   import "./washi/solvers/glpk.js";
 
   const model = new Model({ solver: "glpk" });
-  const x = model.addVar({ lb: 0, ub: 10 });
-  model.maximize(x);
+  const x = model.continuous("x", { lb: 0, ub: 10 });
+  model.objective(maximize(x));
   await model.solve();
   console.log("GLPK ステータス:", model.status);
 </script>
@@ -390,53 +383,35 @@ CDN から直接読み込む場合は、URL を `https://cdn.jsdelivr.net/npm/@o
 <script src="./washi/solvers/glpk.min.js"></script>
 <script>
   const model = new Washi.Model({ solver: "glpk" });
-  const x = model.addVar({ lb: 0, ub: 10 });
-  model.maximize(x);
+  const x = model.continuous("x", { lb: 0, ub: 10 });
+  model.objective(Washi.maximize(x));
   model.solve().then(status => console.log("GLPK ステータス:", status));
 </script>
 ```
 
 > [!NOTE]
 > **ブラウザ環境での Z3 利用と Cross-Origin Isolation**:
-> Z3 の WebAssembly エンジンはマルチスレッド（`SharedArrayBuffer`）を必要とするため、ブラウザのセキュリティ仕様により Cross-Origin Isolation が必須となります。ドキュメントレスポンスに以下のヘッダーが必要です：
-> ```http
-> Cross-Origin-Opener-Policy: same-origin
-> Cross-Origin-Embedder-Policy: require-corp
-> ```
-> また、別オリジンからアセットを読み込む場合は `Cross-Origin-Resource-Policy: cross-origin` の返却が必要です。
-> 
-> 任意のヘッダーを設定できない一般的な静的配信（GitHub Pages や CodePen 等の iframe プレビュー環境）では、追加対応なしで条件を満たすことはできません。なお、ライブラリ本体 `@ohtaman/washi` のインポートによって利用者のページに Service Worker が勝手に登録されることはありません。
-> 
-> GitHub Pages で公開している公式 Web デモでは、`/washi/` スコープ限定の独立した `coi-serviceworker.js` を同オリジンに配置・登録し、初回アクセス時に1回だけ安全に再読み込みを行って `window.crossOriginIsolated === true` を確立してから Z3 を実行します。Service Worker が利用できない環境や隔離の確立に失敗した環境では、原因を明示して安全に実行を中断します。
-
-完全なスタンドアロンサンプル（ESM、スクリプトタグ、CodePen）は `examples/distribution/` に用意されています。
-
-### 工場内・オフライン配布、Worker、自前配信
-
-アプリのビルド出力一式、または `dist/browser` 一式をローカル HTTP サーバー・社内サーバーに配布します。必要なアセットがローカルにあれば、ブラウザのキャッシュが空でも外部ネットワークは不要です。HTML や最初の JS だけでは不足します。`file://` 実行や PWA の自動キャッシュは対象外です。
-
-ESM はモジュール URL、script 版は読み込み時に保持した script URL からアセットを解決します。CDN の Worker は Blob のモジュールから起動します。配信元の CORS と、CSP の script・通信先許可が必要です。CDN Worker では `worker-src blob:` も許可してください。使えない場合は `useWorker: false` を指定します。Worker の読み込み・メッセージ処理に失敗した場合は、求解 Promise がエラーになります。
+> Z3 の WebAssembly エンジンはマルチスレッド（`SharedArrayBuffer`）を必要とするため、`Cross-Origin-Opener-Policy: same-origin` および `Cross-Origin-Embedder-Policy: require-corp` ヘッダーによる Cross-Origin Isolation が必要です。静的ホスティング（`coi-serviceworker.js`）、イントラネット・オフライン配置、CSP（`worker-src blob:`）、カスタム WASM URL（`setHighsWasmUrl`）の詳細は [Cross-Origin Isolation 設定](docs/ja/getting-started/cross-origin.md) および [ランタイム環境とデプロイ構成](docs/ja/getting-started/runtimes.md) を参照してください。
 
-自前 URL は `setHighsWasmUrl(url)` / `options.wasmUrl` で指定できます。従来の HiGHS CDN を明示的に選ぶ場合：
+完全なスタンドアロンサンプル（ESM、スクリプトタグ、CodePen）は [`examples/distribution/`](examples/distribution/README.md) に用意されています。
 
-```typescript
-import { setHighsWasmUrl, OFFICIAL_HIGHS_CDN_WASM_URL } from "@ohtaman/washi";
-setHighsWasmUrl(OFFICIAL_HIGHS_CDN_WASM_URL);
-```
+---
 
-初期化に失敗すると取得先を含むエラーを返し、別ホストには切り替えません。従来のオリジンルート / CDN 自動フォールバックを利用していた場合は、生成アセットを配布するか URL を明示してください。
+## 🛠️ カスタムソルバー開発と拡張性
 
-### 配布物の検証
+WaSHI は疎結合なプラグイン方式のソルバーアーキテクチャを採用しています。独自の最適化エンジン（クラウド REST ソルバー、WebAssembly エンジン、商用ソルバーアダプターなど）を容易に構築・登録できます：
 
-`npm run test:distribution` は実際の npm tarball をインストールし、任意依存なしの Vite / webpack アプリをビルドして、生成 JS と実 WASM を VM で実行します。ブラウザ・CORS の検証とは別です。`npx playwright install chromium` 後に `RUN_DISTRIBUTION_BROWSER=1 npm run test:distribution` で Chromium の検証も実行できます。CI はそのモードを使い、別オリジン配信と外部ネットワーク遮断も確認します。
+- 詳細な開発手順、API コントラクト仕様（`Solver`, `SolveModelData`, `CheckModelData`, `SolverResult`）、およびテスト手法については [カスタムソルバー開発ガイド](docs/ja/solvers/custom-solver.md) をご覧ください。
 
 ---
 
-## 🛠️ カスタムソルバー開発と拡張性
+## 📚 ドキュメント
 
-WaSHI は疎結合なプラグイン方式のソルバーアーキテクチャを採用しています。独自の最適化エンジン（クラウド REST ソルバー、WebAssembly エンジン、商用ソルバーアダプターなど）を容易に構築・登録できます：
+完全なドキュメントは **[ohtaman.github.io/washi/ja/](https://ohtaman.github.io/washi/ja/)** およびリポジトリの [`docs/ja/`](docs/ja/)（[英語版 `docs/`](docs/)）で公開されています：
 
-- 詳細な開発手順、API コントラクト仕様（`Solver`, `LpModelData`, `SolverResult`）、およびテスト手法については [Custom Solver Developer Guide](docs/custom-solver-guide.md) をご覧ください。
+- **はじめに**: [クイックスタート](docs/ja/getting-started/index.md) · [AIエージェント向けクイックリファレンス](docs/ja/getting-started/ai-agents.md) · [ランタイム環境とデプロイ構成](docs/ja/getting-started/runtimes.md) · [Cross-Origin Isolation (Z3)](docs/ja/getting-started/cross-origin.md)
+- **モデリングガイド**: [決定変数 (`Var`, `BoolVar`)](docs/ja/guide/variables.md) · [数式と集計 (`expr`, `sum`, `dot`)](docs/ja/guide/expressions.md) · [制約と論理条件 (`indicator`, SMT)](docs/ja/guide/constraints.md) · [目的関数と求解 (`solve`, `validateSolution`)](docs/ja/guide/objectives.md) · [充足可能性と Unsat Core (`check`)](docs/ja/guide/unsat-core.md)
+- **ソルバー**: [ソルバー概要](docs/ja/solvers/index.md) · [HiGHS](docs/ja/solvers/highs.md) · [Z3](docs/ja/solvers/z3.md) · [GLPK](docs/ja/solvers/glpk.md) · [カスタムソルバー](docs/ja/solvers/custom-solver.md)
 
 ---
 
@@ -446,13 +421,13 @@ WaSHI は疎結合なプラグイン方式のソルバーアーキテクチャ
 
 | カテゴリ | サンプル | 確認できること | ソルバー |
 | :--- | :--- | :--- | :--- |
-| **基本モデル** | [生産計画](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | 整数変数、利益の最大化、資源制約 (`expr`, `c`) | HiGHS |
-| **基本モデル** | [輸送・物流ネットワーク](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) | 2次元マトリクス変数 (`addVars(rows, cols)`) と供給・需要バランス | HiGHS |
+| **基本モデル** | [生産計画](https://github.com/ohtaman/washi/blob/main/examples/node/01-production-planning.ts) | 整数変数、利益の最大化、資源制約 (`expr`) | HiGHS |
+| **基本モデル** | [輸送・物流ネットワーク](https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts) | 2次元マトリクス変数 (`continuous(rows, cols)`) と供給・需要バランス | HiGHS |
 | **基本モデル** | [栄養問題と感度分析](https://github.com/ohtaman/washi/blob/main/examples/node/10-diet-sensitivity.ts) | 潜在価格 (`constr.dual`)、余剰 (`constr.slack`)、被約費用 (`var.reducedCost`) | HiGHS |
 | **実践応用** | [スタッフのシフト作成](https://github.com/ohtaman/washi/blob/main/examples/node/11-shift-scheduling.ts) | 週間シフト最適化と、土曜日の希望休が衝突した際の原因特定 | HiGHS + Z3 |
-| **実践応用** | [ECカートのクーポン最適適用](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) | 条件付き購入金額閾値 (`addIndicator`)、併用不可ルール、追加購入提案 | HiGHS |
+| **実践応用** | [ECカートのクーポン最適適用](https://github.com/ohtaman/washi/blob/main/examples/node/12-ecommerce-coupon-optimizer.ts) | 条件付き購入金額閾値 (`indicator`)、併用不可ルール、追加購入提案 | HiGHS |
 | **実践応用** | [ポートフォリオ配分](https://github.com/ohtaman/washi/blob/main/examples/node/03-portfolio-qp.ts) | 凸二次目的関数 (`QuadExpr`) と配分の制約 | HiGHS |
-| **論理 / SMT** | [業務ルールの検証](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) | 数値・論理制約 (`addBoolVar`, `implies`) の充足可能性の確認 | Z3 |
+| **論理 / SMT** | [業務ルールの検証](https://github.com/ohtaman/washi/blob/main/examples/node/04-smt-security-rules.ts) | 数値・論理制約 (`bool`, `implies`) の充足可能性の確認 | Z3 |
 | **論理 / SMT** | [矛盾する制約の診断](https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts) | 名前付き制約と Unsat Core (`unsatCore`) | Z3 |
 
 [公開ブラウザデモ](https://ohtaman.github.io/washi/demo/)では、モデルを編集して実行できます。ブラウザ標準 ESM、script タグ、CodePen での使い方は[配布形式のサンプル](https://github.com/ohtaman/washi/blob/main/examples/distribution/README.md)を参照してください。Z3 は Cross-Origin Isolation が必要です。詳細は上記のブラウザ要件に記載しています。
@@ -477,7 +452,7 @@ npm run dev
 
 ---
 
-## 🧪 テスト & 信頼性
+## 🧪 テスト & 再現可能なベンチマーク
 
 リポジトリのユニット・統合テストを実行し、配布物をビルドできます：
 
@@ -489,6 +464,24 @@ npm test
 npm run build
 ```
 
+### オプションの再現可能なベンチマーク
+
+正しさのテストの合否閾値に実行時間を含めることなく、決定論的な `small-lp`（24変数・18制約）および `scheduling-mip`（315変数・231制約、再構築モデルの `initialValue` ウォームスタートを含む）の各フェーズを計測できます：
+
+```bash
+# Node.js インプロセス WASM ベンチマークを実行（HiGHS・GLPK、デフォルト5回反復）
+npm run bench
+
+# 反復回数の指定や JSON 出力
+node scripts/run-benchmarks.mjs --iterations=10 --json
+
+# ヘッドレス Chromium の Web Worker 実行も計測（Playwright Chromium が必要）
+node scripts/run-benchmarks.mjs --browser
+```
+
+- **明示的な計測境界**: コールド初期化（`coldRuntimeInitMs`, `coldFirstSolveMs`）と再利用ランタイムでの反復計測（`modelBuildMs`, `validationMs`, LP文字列アダプタ向けの `lpSerializationMs` または構造化アダプタ向けの `symbolMapMs`, `MockSolver` による `resultMappingMs`, `adapterSolveMs`, `endToEndSolveMs`）を分離して直接計測します（無関係なフェーズ時間を差し引いて「ネイティブソルバー時間」とみなすことはしません）。
+- **実行環境の区別**: Node.js のインプロセス WASM（`usesBrowserWorker: false`）とブラウザ Web Worker 実行（`usesBrowserWorker: true`、Worker ライフサイクルや `postMessage` 転送を含む）は異なる実行環境として区別してレポートされます。
+
 ---
 
 ## 📄 ライセンス