nene2-python 1.8.60__tar.gz → 1.8.63__tar.gz

{nene2_python-1.8.60 → nene2_python-1.8.63}/CLAUDE.md

@@ -130,6 +130,11 @@ print(sensitive_data)            # logging モジュールを使う
 - **セキュリティヘッダーをミドルウェアで付与**（X-Content-Type-Options, X-Frame-Options, etc.）
 - **SQL はパラメータ化クエリのみ**。文字列フォーマット禁止
 - **ファイルパスは `pathlib.Path` で操作**し、パストラバーサルを防ぐ
+- **XML 処理には `defusedxml` を使用**。標準の `xml.etree.ElementTree` は XXE・展開爆弾に脆弱（FT180 で確認）
+  ```bash
+  uv add defusedxml
+  ```
+  `import xml.etree.ElementTree` の代わりに `import defusedxml.ElementTree` を使う。
 
 ### 依存関係の脆弱性スキャン
 
@@ -233,6 +238,37 @@ AI エージェント（Claude 等）がこのコードベースを正確に理
 - `nene2.http.problem_details_response()` で RFC 9457 エラー応答
 - `nene2.http.PaginationQueryParser` でページネーション
 
+### APIRouter パターン（必須）
+
+すべての FastAPI アプリで `APIRouter` + `create_app()` ファクトリパターンを使うこと。
+
+```python
+# ✅ 正しい構造 — app.py
+router = APIRouter()
+
+@router.post("/items")  # ← すべてのルート定義は router に紐付ける
+def create_item(...): ...
+
+@router.get("/items/{item_id}")
+def get_item(...): ...
+
+def create_app() -> FastAPI:          # ← create_app() はファイル末尾に定義する
+    application = FastAPI(title="...")
+    application.include_router(router)
+    return application
+
+app = create_app()                    # ← モジュールレベルの app は最終行
+```
+
+**`create_app()` はファイルの末尾**（全 `@router.xxx()` デコレーター定義の後）に置くこと。
+先に `app = create_app()` を呼ぶと `router` にルートが登録される前に `include_router()` が実行され、
+エンドポイントが空になるバグが発生する（FT182 で発見）。
+
+- `router = APIRouter()` → ファイル先頭の定数・モデル定義の後
+- `@router.post(...)` デコレーター → ハンドラー関数の定義
+- `create_app()` → ファイル末尾
+- `app = create_app()` → ファイル最終行
+
 ### ミドルウェアスタック順序（重要）
 
 `app.add_middleware()` は **LIFO**（後から追加したものが外側になる）。
@@ -378,7 +414,11 @@ Python 標準ライブラリ・サードパーティライブラリを nene2-pyt
    テンプレート: docs/templates/field-trial-report.md
 6. DX Review（6ペルソナ）を実施（後述）
 7. FT番号が3の倍数なら セキュリティ診断 を実施（後述）
-8. Follow-up Issues を GitHub Issue に変換
+8. Follow-up Issues をその場で修正してからクローズする
+   - 発見した問題（摩擦点・セキュリティ指摘）は FT PR に含めて修正する
+   - 修正 → テスト全通過 → PR に含める → GitHub Issue は PR 内でクローズ（Closes #NNN）
+   - CLAUDE.md 追記・docs 更新・サンドボックスのコード修正すべてを同じ PR に含める
+   - 「外部依存の修正待ち」など対応不可能な理由がある場合のみ Issue を残し、理由を PR 説明に記載する
 9. まとめて main merge → パッチバージョン（v1.8.N）でリリース
 ```
 
@@ -418,7 +458,7 @@ Python 標準ライブラリ・サードパーティライブラリを nene2-pyt
 
 **合否判定**:
 - **合格**: 全カテゴリ問題なし
-- **条件付き合格**: MEDIUM 以下の指摘のみ、次 FT までに修正
+- **条件付き合格**: MEDIUM 以下の指摘のみ → **同 FT の PR 内で修正してからマージ**
 - **不合格**: HIGH/CRITICAL の指摘あり → main merge 前に必須修正
 
 ---

{nene2_python-1.8.60 → nene2_python-1.8.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.60
+Version: 1.8.63
 Summary: NENE2 Python — minimal API framework following NENE2's design philosophy
 Project-URL: Homepage, https://github.com/hideyukiMORI/nene2-python
 Project-URL: Repository, https://github.com/hideyukiMORI/nene2-python

nene2_python-1.8.63/docs/field-trials/2026-05-field-trial-190.md

@@ -0,0 +1,220 @@
+# FT190: multiprocessing モジュール
+
+**日付**: 2026-05-21
+**テーマ**: プロセスベース並行処理・共有状態・プロセスプール
+**セキュリティ診断**: なし（190 % 3 = 1）
+
+---
+
+## 概要
+
+`multiprocessing` は threading と異なりプロセスを分離して実行するため、GIL（Global Interpreter Lock）の影響を受けず CPU バウンドタスクの並列化に有効。本 FT では `Pool.map` / `Pool.starmap` / `Pool.imap` / `Pool.apply_async`・共有メモリ（`Value`）・プロセス間キュー（`Queue`）・初期化関数付きプールなどの主要パターンを FastAPI エンドポイントから検証する。
+
+FT188（threading）・FT189（subprocess）の直後として、プロセスベース並行処理の違いと型安全上の注意点を記録することも目的とする。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft190-multiprocessing/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `spawn_process(name)` | 単一プロセスを起動して PID・Alive 状態を返す |
+| `pool_map(values, workers)` | Pool.map で並列二乗計算 |
+| `pool_map_cube(values, workers)` | Pool.map で並列三乗計算 |
+| `pool_starmap(pairs, workers)` | Pool.starmap で並列加算 |
+| `apply_async_demo(values, delay)` | apply_async で非同期タスク |
+| `shared_counter_demo(num_processes, increments_each)` | Value + Lock で共有カウンター |
+| `queue_producer_consumer(items)` | Queue でプロデューサー/コンシューマー |
+| `pool_imap_ordered(values, workers)` | Pool.imap（順序保証） |
+| `pool_imap_unordered(values, workers)` | Pool.imap_unordered（順序不定） |
+| `pool_map_chunksize(values, chunksize, workers)` | チャンクサイズ付き Pool.map |
+| `pool_with_initializer(values, config)` | 初期化関数付き Pool |
+| `build_task_func(operation)` | 操作名から関数を返す（match 文使用） |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/multiprocessing/spawn` | プロセス起動・PID 取得 |
+| GET | `/multiprocessing/cpu-count` | CPU コア数・start method |
+| POST | `/multiprocessing/pool-map` | 並列二乗計算 |
+| POST | `/multiprocessing/pool-map-cube` | 並列三乗計算 |
+| POST | `/multiprocessing/pool-starmap` | 並列加算 |
+| POST | `/multiprocessing/apply-async` | 非同期タスク |
+| POST | `/multiprocessing/shared-counter` | 共有カウンター（Lock 付き） |
+| POST | `/multiprocessing/queue` | プロデューサー/コンシューマー |
+| POST | `/multiprocessing/imap-ordered` | 順序保証 imap |
+| POST | `/multiprocessing/imap-unordered` | 順序不定 imap |
+| POST | `/multiprocessing/chunksize` | チャンクサイズ指定 map |
+| POST | `/multiprocessing/with-initializer` | 初期化関数付きプール |
+| GET | `/multiprocessing/daemon-demo` | デーモンプロセスデモ |
+
+---
+
+## テスト結果
+
+**56 passed**
+
+```
+56 passed in 1.18s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: Pool.starmap にローカル関数を渡すと PicklingError（深刻度: 中）
+
+**事象**: `pool_starmap()` 内でローカル関数 `add` を定義して `pool.starmap(add, pairs)` に渡したところ、`_pickle.PicklingError: Can't pickle local object` が発生した。
+
+**原因**: multiprocessing はワーカープロセスにタスクを pickle で送信する。ローカル関数はモジュールトップレベルに存在しないため、ワーカーが unpickle できない。threading ではそのまま渡せるため、つい同じように書いてしまう。
+
+**対応**: `_add(a, b)` としてモジュールレベルに定義。ワーカー用関数は必ずモジュールレベルに置くルールを確認（threading と multiprocessing の違い）。
+
+### F-2: `multiprocessing.Value` に `Synchronized[c_int]` を使うと mypy エラー（深刻度: 低）
+
+**事象**: `counter: Synchronized[c_int] = Value(c_int, 0)` と書くと、`counter.value += 1` に対して `Unsupported operand types for + ("c_int" and "int")` エラーが発生した。
+
+**原因**: typeshed の `Synchronized[_CT]` は `.value` を `_CT` 型として定義しており、`_CT = c_int` のとき `c_int + int` が不正になる。しかし実際の runtime では `Value("i", 0).value` は Python の `int` を返す。型スタブが実態と乖離している。
+
+**対応**: `Synchronized[int]` とアノテーションし `Value("i", 0)` (文字列フォーマットコード) を使用。mypy は文字列フォーマットコードからジェネリック型を解決できないため `Synchronized[int]` の明示アノテーションで型整合が取れる。
+
+---
+
+## 観察点
+
+### 観察1: Pool ワーカー関数のスコープ制約
+
+multiprocessing の Pool ワーカーは pickle でシリアライズしてワーカープロセスに送信する。pickle できるのはモジュールトップレベルで定義された関数のみ。lambda・クロージャ・ローカル関数は pickle できない。
+
+```python
+# ❌ PicklingError
+def my_func(pairs):
+    def add(a, b): return a + b
+    with Pool() as pool:
+        return pool.starmap(add, pairs)
+
+# ✅ 正しい
+def _add(a: int, b: int) -> int:  # モジュールレベル
+    return a + b
+
+def my_func(pairs):
+    with Pool() as pool:
+        return pool.starmap(_add, pairs)
+```
+
+### 観察2: GIL と multiprocessing
+
+threading では GIL により Python バイトコードの並列実行が制限される（I/O バウンドは並行可）が、multiprocessing は別プロセスなので GIL を回避して CPU バウンドタスクを並列化できる。プロセス起動コスト（～50ms）があるため、軽量タスクには Pool よりも threading が適する。
+
+### 観察3: Value の型アノテーション戦略
+
+```python
+# 実態と合うアノテーション
+from multiprocessing.sharedctypes import Synchronized
+counter: Synchronized[int] = Value("i", 0)  # 文字列フォーマットコードを使う
+```
+
+`Synchronized[int]` とすることで `counter.value` が `int` として扱われ、`counter.value += 1` が mypy --strict を通過する。`Value(c_int, 0)` の形式は typeshed との不整合を生む。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- Pool ワーカー関数はモジュールレベルに置く制約があるため、プロセスプールを使う UseCase では関数をモジュールレベルの `_private` 関数として分離するパターンが必要
+- FastAPI のリクエストハンドラー内で `Pool` を生成する場合、`with Pool() as pool:` のコンテキストマネージャーで確実にクリーンアップすること（`pool.terminate()` の漏れ防止）
+- multiprocessing は `__main__` ガード（`if __name__ == "__main__":`）が必要な start method（spawn/forkserver）があるが、FastAPI アプリとして使う場合は `fork`（Linux デフォルト）なので不要。ただし Windows 移植時は注意
+- `MAX_WORKERS: int = 8` 定数でワーカー数を上限制限し、DoS を防止
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+チュートリアルで threading を学んだ後、multiprocessing に入門する段階。
+
+**ドキュメント理解**: `Pool.map` の使い方は直感的で理解しやすい。ワーカー関数がモジュールレベルでないと `PicklingError` になる制約は、threading と混同して気づきにくい（F-1）。エラーメッセージが英語で `Can't pickle local object` と出るので原因の特定は可能だが、初心者には意味が分かりにくい。  
+**事故リスク**: 中。PicklingError は実行時エラーで早期発見できるが、初心者が「なぜ動かないのか」を理解するまでに時間がかかる。  
+**規約の使いやすさ**: `with Pool(processes=n) as pool:` のパターンは覚えやすい。ワーカー関数をモジュールレベルに置く規則は一度理解すれば機械的に適用できる。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+threading コードをコピーして multiprocessing に変えようとする場面。
+
+**コピペ可能性**: `Pool.map` のサンプルは分かりやすい。ただし、ラムダや内側クロージャを気軽に使うと PicklingError になる。threading では動いたコードをそのまま転用できないケースがある。  
+**拡張時の罠**: `Value("i", 0)` の型アノテーションを `Synchronized[c_int]` と書くと mypy エラーになる（F-2）。型を「直しよう」としてはまる。`Synchronized[int]` と書く正解はドキュメントに明示されていない。  
+**セキュリティ的な事故リスク**: 中。`workers` 上限がなければ `Pool(processes=99999)` でプロセス枯渇 DoS が可能。本実装では `MAX_WORKERS = 8` で上限制限している。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+並行処理の概念（Promise.all 的なもの）はわかるが、プロセスとスレッドの違いが曖昧な段階。
+
+**エラーレスポンスの質**: 422 Unprocessable Entity が `workers` 超過・`values` 超過で正しく返る。`PicklingError` は HTTP 500 になるが、デモコードのワーカー関数はモジュールレベルに固定しているため HTTP 経由では発生しない。  
+**Python 固有概念の学習コスト**: `Pool` が Python オブジェクトプールではなくプロセスプールであること、`fork` vs `spawn` の start method の違いは非直感的。  
+**事故リスク**: 低。HTTP 入力のバリデーションが Pydantic で守られており、エンドポイント経由では PicklingError には到達できない。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+Celery・concurrent.futures との比較で評価する。
+
+**他フレームワークとの差異**: `concurrent.futures.ProcessPoolExecutor` と `multiprocessing.Pool` は機能が重複する。FastAPI アプリで重い CPU 処理をオフロードするなら `ProcessPoolExecutor` の方が Python 公式の高レベル API として推奨されている。本 FT が `Pool` を選んだのは stdlib の低レベル API を直接学ぶため。  
+**nene2-python の薄さへの評価**: UseCase 層が HTTP・DB 非依存なので、Pool ワーカーに UseCase を渡す設計も可能（ただし pickle 可能なオブジェクトに限る）。  
+**本番投入可能性**: `MAX_WORKERS` の上限設定・`with Pool() as pool:` のコンテキスト管理が適切。本番では `ProcessPoolExecutor` との使い分けガイドが欲しい。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+チームで multiprocessing を使う場合のリスクをレビューする。
+
+**コードレビューチェックポイント**:
+- [ ] `Pool.map` のワーカー関数がモジュールレベルか（ローカル関数・lambda は PicklingError）
+- [ ] `with Pool() as pool:` でコンテキストマネージャーを使い、確実に終了しているか
+- [ ] `workers` に上限制限があるか（`min(workers, MAX_WORKERS)` パターン）
+- [ ] `join(timeout=N)` でゾンビプロセス防止が書かれているか
+- [ ] `Value` の型アノテーションが `Synchronized[int]` か（`Synchronized[c_int]` は mypy 不整合）
+
+**チームでの安全な共有パターン**: ワーカー関数ファイルを `_workers.py` として分離する規則を設けると pickle 可能性が明確になる。  
+**ツール追加の必要性**: ruff には multiprocessing 固有のルールはない。`pool.map(lambda x: x, [])` のようなラムダ誤用は静的解析では検出できない（実行時エラー）。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md ポリシーとの整合性を確認する。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 中（PicklingError は HTTP 経由では発生しないが、demos.py を直接使う場面では踏みやすい）  
+**設計上の負債・ドキュメント不足**: `multiprocessing.Value` の型アノテーション方法（`Synchronized[int]` vs `Synchronized[c_int]`）が typeshed の実態と乖離している点は How-to に記録する価値がある（→ Follow-up Issue）  
+**Follow-up Issues**: 下記参照
+
+---
+
+## Follow-up Issues
+
+今回の FT で発見した問題を同 FT PR 内で即時対応済み（バックログを残さないルール）。
+
+### 即時対応済み
+
+| 対応内容 | 対応方法 |
+|---|---|
+| Pool.starmap にローカル関数を渡して PicklingError（F-1） | `_add()` をモジュールレベルへ移動 |
+| `Synchronized[c_int]` mypy 不整合（F-2） | `Synchronized[int]` + `Value("i", 0)` に変更 |
+
+### 文書化 Issue（同 PR で作成・クローズ）
+
+| タイトル | 種別 |
+|---|---|
+| multiprocessing.Value のアノテーションには `Synchronized[int]` を使う | docs |
+
+---
+
+## まとめ
+
+multiprocessing の主要パターン（Pool.map/starmap/imap/apply_async・Value・Queue・初期化関数）を 13 エンドポイント・56 テストで検証した。FT190 固有の発見は 2 点:
+
+1. **PicklingError**: Pool ワーカー関数のモジュールレベル配置制約（threading との差異）
+2. **Value 型アノテーション**: `Synchronized[c_int]` は typeshed と乖離、`Synchronized[int]` + 文字列フォーマットコードで回避
+
+いずれも実装中に即時修正済み。FT191 に向けた懸案はなし。

nene2_python-1.8.63/docs/field-trials/2026-05-field-trial-191.md

@@ -0,0 +1,214 @@
+# FT191: concurrent.futures モジュール
+
+**日付**: 2026-05-21
+**テーマ**: ThreadPoolExecutor / ProcessPoolExecutor / Future — 高レベル並行処理 API
+**セキュリティ診断**: なし（191 % 3 = 2）
+
+---
+
+## 概要
+
+`concurrent.futures` は threading と multiprocessing の上に薄い高レベル API を提供する stdlib モジュール。`ThreadPoolExecutor` / `ProcessPoolExecutor` を同一インターフェースで操作でき、`Future` オブジェクトで非同期タスクを管理できる。
+
+本 FT では `.map()` / `.submit()` / `as_completed()` / `wait()` / タイムアウト / キャンセル / エラーハンドリングを FastAPI エンドポイントから検証する。FT188（threading）・FT189（subprocess）・FT190（multiprocessing）の高レベル抽象として位置付ける。
+
+---
+
+## 実装したサンプルアプリ
+
+**場所**: `/home/xi/docker/nene2-python-FT/ft191-concurrent-futures/`
+
+### 主要機能
+
+| 関数/クラス | 概要 |
+|---|---|
+| `thread_pool_map(values, workers)` | ThreadPoolExecutor.map で並列二乗 |
+| `thread_pool_submit(values, workers)` | ThreadPoolExecutor.submit で Future 取得 |
+| `thread_as_completed(values, workers)` | as_completed で完了順に収集 |
+| `thread_wait_all_completed(values, workers)` | wait(ALL_COMPLETED) |
+| `thread_wait_first_completed(values, workers)` | wait(FIRST_COMPLETED) |
+| `thread_wait_first_exception(values, workers)` | wait(FIRST_EXCEPTION) |
+| `batch_with_error_handling(values, workers)` | 例外を握りつぶさず成功/失敗分類 |
+| `process_pool_map(values, workers)` | ProcessPoolExecutor.map で CPU バウンド |
+| `process_pool_submit(values, workers)` | ProcessPoolExecutor.submit |
+| `process_as_completed(values, workers)` | ProcessPoolExecutor + as_completed |
+| `submit_with_timeout(seconds, timeout)` | タイムアウト付き Future |
+| `submit_and_cancel(values)` | キャンセル試行 |
+| `thread_map_with_chunksize(values, chunksize, workers)` | チャンクサイズ指定 map |
+
+### HTTP エンドポイント
+
+| メソッド | パス | 概要 |
+|---|---|---|
+| POST | `/futures/thread-map` | ThreadPoolExecutor.map |
+| POST | `/futures/thread-submit` | submit で Future 取得 |
+| POST | `/futures/thread-as-completed` | as_completed |
+| POST | `/futures/thread-wait-all` | wait(ALL_COMPLETED) |
+| POST | `/futures/thread-wait-first` | wait(FIRST_COMPLETED) |
+| POST | `/futures/thread-wait-exception` | wait(FIRST_EXCEPTION) |
+| POST | `/futures/batch-errors` | エラーハンドリング付きバッチ |
+| POST | `/futures/process-map` | ProcessPoolExecutor.map |
+| POST | `/futures/process-submit` | ProcessPoolExecutor.submit |
+| POST | `/futures/process-as-completed` | ProcessPoolExecutor + as_completed |
+| POST | `/futures/timeout` | タイムアウト付き Future |
+| POST | `/futures/chunksize` | チャンクサイズ指定 |
+| POST | `/futures/cancel` | キャンセル試行 |
+| GET | `/futures/info` | 実行環境情報 |
+
+---
+
+## テスト結果
+
+**51 passed**
+
+```
+51 passed in 10.86s
+```
+
+---
+
+## 摩擦ポイント
+
+### F-1: `submit_and_cancel` の戻り値型 `dict[str, int]` が `dict[str, object]` に非互換（深刻度: 低）
+
+**事象**: `submit_and_cancel()` が `dict[str, int]` を返し、エンドポイントの戻り値型 `dict[str, object]` に対して mypy --strict が `Incompatible return value type` エラーを出した。
+
+**原因**: mypy では `dict[str, int]` は `dict[str, object]` の部分型でない（`dict` は invariant）。TS の `Record<string, number>` を `Record<string, unknown>` に代入できないのと同じ理屈。
+
+**対応**: `submit_and_cancel` の戻り値型を `dict[str, object]` に変更。戻り値の幅を広げても型安全性は失われない（返す値はすべて `int`）。
+
+---
+
+## 観察点
+
+### 観察1: ThreadPoolExecutor vs ProcessPoolExecutor の使い分け
+
+```python
+# I/O バウンド → ThreadPoolExecutor（GIL 解放待ちの間に他スレッドが走る）
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(fetch_url, urls))
+
+# CPU バウンド → ProcessPoolExecutor（GIL を完全に回避）
+with ProcessPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(heavy_compute, values))
+```
+
+threading と multiprocessing の低レベル API と同一の選択基準だが、インターフェースが統一されているため交換が容易。
+
+### 観察2: as_completed vs map の選択
+
+```python
+# map: 送信順で結果が返る（遅いタスクがブロック）
+results = list(executor.map(func, values))
+
+# as_completed: 完了順で返る（高速タスクの結果を先に処理可能）
+for future in as_completed(futures):
+    result = future.result()
+    process_early(result)
+```
+
+HTTP API でストリームレスポンスを返す場合や、部分結果を早期返却する設計では `as_completed` が有利。
+
+### 観察3: wait() の return_when フラグ
+
+| フラグ | 用途 |
+|---|---|
+| `ALL_COMPLETED` | 全タスク完了を待つ（デフォルト） |
+| `FIRST_COMPLETED` | 最初のタスクが終わったら戻る |
+| `FIRST_EXCEPTION` | 最初の例外発生で戻る（残タスクはキャンセルしない） |
+
+`FIRST_EXCEPTION` は例外をすぐ検知したいが残タスクは並行継続したい場合に使う。
+
+### 観察4: Future.cancel() の制約
+
+`cancel()` はタスクが**まだ実行開始されていない**場合のみ成功する。既に実行中のタスクはキャンセルできない（Python の Future はキャンセル可能 Flag のみで、OS レベルのプロセス終了は行わない）。max_workers=1 でタスクを大量投入した場合のみキャンセルが効果的。
+
+---
+
+## nene2-python フレームワークとの統合
+
+- `ThreadPoolExecutor` は I/O バウンド UseCase（外部 API 並列呼び出し等）に適用可能。ただし FastAPI はデフォルト非同期（asyncio）であり、重い I/O は `httpx.AsyncClient` での `asyncio.gather` が自然な選択
+- `ProcessPoolExecutor` は CPU バウンド変換処理（画像変換・暗号化・データ集計）を同期 UseCase として切り出す際に使う
+- `max_workers` の上限制限は DoS 防止のために必須。`min(workers, MAX_WORKERS)` パターンを全関数で適用
+- ProcessPoolExecutor のワーカー関数も multiprocessing と同様 pickle 可能なモジュールレベル関数に限定される（FT190 F-1 と同じ制約）
+
+---
+
+## Developer Experience (DX) Review
+
+### ペルソナ1: 初心者（Python 歴1年・独学中・女性・バックエンド志望）
+
+threading/multiprocessing を学んだ後、高レベル API として concurrent.futures を使おうとしている段階。
+
+**ドキュメント理解**: `with ThreadPoolExecutor() as executor: executor.map(func, data)` のパターンは直感的で理解しやすい。`as_completed`・`wait` は公式ドキュメントの例が豊富で困らない。`FIRST_EXCEPTION` フラグの意味は名前から推測できる。  
+**事故リスク**: 低。エラーハンドリングを省略すると `future.result()` で例外が再 raise されるため、未処理の例外は実行時に気づける。  
+**規約の使いやすさ**: `with executor:` の `with` ブロックは必須習慣で、抜け漏れ時は executor が自動終了するため安全。
+
+### ペルソナ2: ロースキル経験者（Python 歴3-4年・スクリプト系・男性・SES）
+
+既存スクリプトの `for` ループを並列化したくてコピーして使うスタイル。
+
+**コピペ可能性**: `executor.map(func, data)` のサンプルはそのままコピーして動く。`as_completed` のパターンも明確。  
+**拡張時の罠**: ProcessPoolExecutor でラムダを渡すと PicklingError（FT190 F-1 の再現）。threading でも同じコードで動くため気づきにくい。  
+**セキュリティ的な事故リスク**: 中。`max_workers` に上限がないと DoS につながる。本実装では `MAX_WORKERS = 8` で制限。
+
+### ペルソナ3: フロントエンド寄り経験者（React/TS 歴4年・バックエンド転向中・ノンバイナリ）
+
+JavaScript の `Promise.all` / `Promise.race` との比較で理解しようとしている段階。
+
+**エラーレスポンスの質**: `batch_with_error_handling` パターンで成功/失敗を分けて返すと、クライアントが部分成功を処理しやすい。422 バリデーションエラーは自動返却される。  
+**Python 固有概念の学習コスト**: `Future` は JS の `Promise` に近い。`as_completed` は `Promise.race` の複数解決版として理解できる。`wait(FIRST_COMPLETED)` が `Promise.race`、`wait(ALL_COMPLETED)` が `Promise.all` に相当する。  
+**事故リスク**: 低。HTTP 入力のバリデーションが Pydantic で保護されている。
+
+### ペルソナ4: バックエンド経験者（Django/FastAPI 歴5-6年・男性・リードエンジニア）
+
+asyncio vs concurrent.futures の使い分けを判断する立場。
+
+**他フレームワークとの差異**: FastAPI は async/await が基本なので、I/O 並列は `asyncio.gather` が自然な選択。`concurrent.futures` は CPU バウンドと、非同期対応していないレガシーライブラリの同期 I/O をスレッドプールで包む用途に限定される。`loop.run_in_executor()` で asyncio と統合できる。  
+**nene2-python の薄さへの評価**: UseCase 層が HTTP 非依存なので、`ThreadPoolExecutor` を UseCase 内で直接使う設計も許容される。ただし `asyncio` 移行を前提とする場合は技術的負債になりやすい。  
+**本番投入可能性**: チームが asyncio に慣れているなら concurrent.futures は補助的な役割に留めるべき。混在するとコードの可読性が下がる。
+
+### ペルソナ5: シニアエンジニア（設計・コードレビュー担当・女性・10-12年）
+
+コードレビューで concurrent.futures の誤用を検出する立場。
+
+**コードレビューチェックポイント**:
+- [ ] `max_workers` に上限制限があるか（無制限はリソース枯渇）
+- [ ] `with executor:` のコンテキストマネージャーを使っているか（`executor.shutdown()` の漏れ防止）
+- [ ] ProcessPoolExecutor のワーカー関数がモジュールレベルか（PicklingError 防止）
+- [ ] `future.result()` の例外ハンドリングが書かれているか（未処理は実行時エラーが伝播する）
+- [ ] タイムアウトが指定されているか（`future.result(timeout=N)` や `wait(timeout=N)`）
+
+**チームでの安全な共有パターン**: ワーカー関数を `_workers.py` に分離する規則を設けると、pickle 可能性と単体テスト可能性が高まる。  
+**ツール追加の必要性**: なし（ruff には concurrent.futures 固有の追加ルールはない）。
+
+### ペルソナ6: 設計者・ポリシー照合（nene2-python 設計ポリシー目線）
+
+CLAUDE.md ポリシーとの整合性を確認する。
+
+**ポリシー達成度**: 高  
+**「初心者でも安全な API」達成度**: 高（`with executor:` がリソースリーク防止を保証、HTTP 境界の Pydantic バリデーションで DoS 制限）  
+**設計上の負債・ドキュメント不足**: `asyncio` と concurrent.futures の使い分けガイドが CLAUDE.md に不足。FastAPI アプリでは asyncio が優先される旨を追記する価値がある。  
+**Follow-up Issues**: なし（即時対応済み）
+
+---
+
+## Follow-up Issues
+
+### 即時対応済み
+
+| 対応内容 | 対応方法 |
+|---|---|
+| `dict[str, int]` を `dict[str, object]` に変更（F-1） | `submit_and_cancel` の戻り値型を修正 |
+
+### 新規 Issue
+
+なし（セキュリティ診断なし、全問題は即時解決済み）
+
+---
+
+## まとめ
+
+concurrent.futures の主要パターン（ThreadPoolExecutor / ProcessPoolExecutor・submit / map / as_completed / wait・タイムアウト・キャンセル・エラーハンドリング）を 14 エンドポイント・51 テストで検証した。FT191 固有の発見は 1 点: `dict[str, int]` → `dict[str, object]` の invariant 問題（mypy --strict 即時検出）。
+
+threading（FT188）・multiprocessing（FT190）の高レベル API として concurrent.futures は使いやすく、処理系（スレッド/プロセス）の交換コストが低い。FastAPI + asyncio 環境では補助的な位置付けになるが、CPU バウンド処理のオフロードには有効。

{nene2_python-1.8.60 → nene2_python-1.8.63}/docs/field-trials/INDEX.md

@@ -223,6 +223,8 @@
 | [FT187](2026-05-field-trial-187.md) | collections モジュール — Counter・defaultdict・deque・ChainMap・NamedTuple・OrderedDict | | |
 | [FT188](2026-05-field-trial-188.md) | threading モジュール — Thread・Lock・RLock・Semaphore・Event・ThreadPoolExecutor・Queue・Timer | 🔍 | |
 | [FT189](2026-05-field-trial-189.md) | subprocess モジュール — 安全なプロセス実行・stdin/stdout 制御・ストリーミング | 🔒 | [#524](https://github.com/hideyukiMORI/nene2-python/issues/524) |
+| [FT190](2026-05-field-trial-190.md) | multiprocessing モジュール — プロセスベース並行処理・共有状態・プロセスプール | | |
+| [FT191](2026-05-field-trial-191.md) | concurrent.futures モジュール — ThreadPoolExecutor / ProcessPoolExecutor / Future | | |
 
 ---
 
@@ -238,4 +240,4 @@ FT172, FT176, FT180, FT184, FT188
 
 ---
 
-*最終更新: 2026-05-21 (FT189 / v1.8.60)*
+*最終更新: 2026-05-21 (FT191 / v1.8.63)*

nene2_python-1.8.63/docs/how-to/decimal-unicode-input.md

@@ -0,0 +1,61 @@
+# How-to: decimal モジュールと Unicode 数字入力
+
+## Python の Decimal は Unicode 全角数字を受け入れる
+
+`decimal.Decimal()` は Unicode の全角数字（U+FF10〜U+FF19: ０１２３４５６７８９）を
+そのまま数値として解釈します。HTTP API を通じてユーザーが全角数字を入力した場合、
+**Pydantic の `str` フィールドを通過してしまう**ことがあります。
+
+```python
+from decimal import Decimal
+
+Decimal("１２３")   # → Decimal('123')  ← 正常に変換される
+Decimal("１.５")   # → Decimal('1.5')
+```
+
+## 問題: 想定外の入力が通過する可能性
+
+金融計算 API で `price: str = Field(...)` としている場合、
+クライアントが `"１０００"` を送ると `Decimal("１０００")` → `Decimal('1000')` として処理されます。
+これ自体はエラーではありませんが、**入力の正規化が必要な場合**（ログ記録・DB 保存等）は
+Unicode 正規化を行ってから処理してください。
+
+```python
+import unicodedata
+from decimal import Decimal
+
+def parse_decimal_safe(value: str) -> Decimal:
+    """Unicode 正規化（NFKC）して Decimal に変換する."""
+    normalized = unicodedata.normalize("NFKC", value.strip())
+    return Decimal(normalized)
+```
+
+`unicodedata.normalize("NFKC", ...)` は全角数字を半角に変換します。
+
+```python
+unicodedata.normalize("NFKC", "１２３")  # → "123"
+unicodedata.normalize("NFKC", "１.５")  # → "1.5"
+```
+
+## Pydantic でのバリデーション
+
+Pydantic の `model_validator` を使って入力値の正規化を強制することを推奨します。
+
+```python
+from pydantic import BaseModel, Field, model_validator
+
+class PriceRequest(BaseModel):
+    price: str = Field(max_length=20, description="価格（半角数字）")
+
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_unicode(cls, values: dict) -> dict:
+        import unicodedata
+        if "price" in values and isinstance(values["price"], str):
+            values["price"] = unicodedata.normalize("NFKC", values["price"])
+        return values
+```
+
+## 関連 Issue
+
+- [FT176] #500: parse_decimal_safe() の Unicode 全角数字受け入れ挙動を文書化

nene2_python-1.8.63/docs/how-to/email-address-parsing.md

@@ -0,0 +1,57 @@
+# How-to: メールアドレスのパースと parseaddr() の挙動
+
+## parseaddr() は寛容なパーサー
+
+`email.utils.parseaddr()` は RFC 2822 準拠のフォーマット（`"Name <addr@example.com>"` 形式）を解析しますが、
+**不正なアドレスを渡してもエラーを送出せず、空文字列を返します**。
+
+```python
+from email.utils import parseaddr
+
+# 正常ケース
+parseaddr("Alice <alice@example.com>")  # → ("Alice", "alice@example.com")
+parseaddr("alice@example.com")          # → ("", "alice@example.com")
+
+# 不正なアドレス — エラーにならず ("", "") を返す
+parseaddr("not-an-email")               # → ("", "")
+parseaddr("")                           # → ("", "")
+parseaddr("bad @ format")              # → ("", "")
+```
+
+## HTTP 境界での検証は別途行うこと
+
+`parseaddr()` の戻り値が空かどうかで有効性を確認しても、
+**セキュリティ上の検証としては不十分**です。ユーザーが入力したアドレスは
+Pydantic の `EmailStr` や正規表現で検証した後に `parseaddr()` を使ってください。
+
+```python
+import re
+from email.utils import parseaddr
+
+_EMAIL_RE = re.compile(r"^[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}$")
+
+def validate_and_parse(raw: str) -> tuple[str, str] | None:
+    name, addr = parseaddr(raw)
+    if not addr or not _EMAIL_RE.match(addr):
+        return None
+    return name, addr
+```
+
+## ヘッダーインジェクション対策
+
+`Subject` や `From` ヘッダーに CR/LF (`\r\n`) が含まれると
+**メールヘッダーインジェクション**が発生します。`email.message.EmailMessage` を使えば
+自動的にエスケープされますが、`smtplib.sendmail()` に生文字列を渡す場合は
+事前に CR/LF を除去してください。
+
+```python
+import re
+_INJECT_RE = re.compile(r"[\r\n]")
+
+def sanitize_header(value: str) -> str:
+    return _INJECT_RE.sub("", value)
+```
+
+## 関連 Issue
+
+- [FT182] #511: parseaddr() の寛容な挙動を How-to ドキュメントに記載