nene2-python 1.8.0__tar.gz → 1.8.2__tar.gz

{nene2_python-1.8.0 → nene2_python-1.8.2}/CHANGELOG.md

@@ -5,6 +5,32 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.2] — 2026-05-20
+
+FT29〜FT30 フィールドトライアル — AsyncUseCase ドキュメント・RequestLoggingMiddleware 改善。
+
+### Added
+- `docs/how-to/async-use-case.md` — `AsyncUseCaseProtocol` + FastAPI `Depends` の DI パターンガイドを追加 (FT29)
+- `RequestLoggingMiddleware` に `extra_context: dict[str, str] | None = None` パラメータを追加し、全ログに静的フィールドを付加できるように (FT30)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-29.md`、`docs/field-trials/2026-05-field-trial-30.md`
+
+---
+
+## [1.8.1] — 2026-05-20
+
+FT25〜FT28 フィールドトライアル — RequestId ヘルパー・structlog ログレベル・ThrottleMiddleware 改善。
+
+### Added
+- `nene2.middleware.get_request_id()` — FastAPI `Depends` で注入できる request ID ヘルパー関数 (FT25)
+- `setup_logging()` に `log_level: str = "INFO"` パラメータを追加し `AppSettings.log_level` との統合が容易に (FT26)
+- `ThrottleMiddleware` に `path_limits: dict[str, int] | None` パラメータを追加し、パスごとに異なるレート制限を設定可能に (FT28)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-25.md` 〜 `docs/field-trials/2026-05-field-trial-28.md`
+
+### Fixed
+- `ThrottleMiddleware` — ウィンドウ経過後も `_counts` に古いエントリが残り続ける問題を修正（定期クリーンアップを実装）(FT27)
+
+---
+
 ## [1.8.0] — 2026-05-20
 
 FT18〜FT23 フィールドトライアル — ログテスト・Problem Details・ThrottleMiddleware・ドメイン例外・HealthCheck・RequestSizeLimit の各改善。

{nene2_python-1.8.0 → nene2_python-1.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.0
+Version: 1.8.2
 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.2/docs/field-trials/2026-05-field-trial-24.md

@@ -0,0 +1,89 @@
+# FT24: AppSettings 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `AppSettings` を使った環境変数ベースの設定管理パターンの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft24-app-settings/`
+
+---
+
+## 目的
+
+`nene2.config.AppSettings` を実際のアプリに組み込み、
+環境変数から設定を読み込んでミドルウェアを設定するパターンを検証する。
+
+---
+
+## 実施内容
+
+`AppSettings` の各フィールドを使って以下を設定:
+- `ErrorHandlerMiddleware(debug=settings.app_debug)`
+- `RequestSizeLimitMiddleware(max_bytes=settings.max_body_size)`
+- `ThrottleMiddleware(limit=settings.throttle_limit, window=settings.throttle_window)` (conditional)
+- `SecurityHeadersMiddleware` (conditional)
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_health_endpoint_returns_env | PASS |
+| test_debug_false_by_default | PASS |
+| test_settings_loaded_from_env_vars | PASS |
+| test_throttle_disabled_via_settings | PASS |
+| test_max_body_size_from_settings | PASS |
+| test_db_url_sqlite_default | PASS |
+| test_db_url_mysql_format | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_list_fields_not_parseable_from_env_string | PASS | あり（ドキュメント） |
+| test_no_log_level_setting | PASS | あり |
+| test_no_middleware_factory_helper | PASS | あり（設計上の判断） |
+
+---
+
+## 発見した摩擦点
+
+### FT24-F1: list[str] フィールドを環境変数で設定する方法がドキュメントにない
+
+**概要**: `cors_origins`、`bearer_tokens`、`api_keys` は `list[str]` 型だが、
+環境変数から設定するには JSON 形式 (`["a","b"]`) が必要。
+単純な `"token1,token2"` ではパースされない。
+
+**判断**: pydantic-settings の標準動作のため、リファレンスドキュメントに記載する。
+
+---
+
+### FT24-F2: ログレベルの設定フィールドがない
+
+**概要**: `app_debug: bool` しかなく、`INFO`/`WARNING`/`ERROR` の粒度制御ができない。
+
+**影響**: ステージング環境で `INFO` ログを出しつつ、本番では `WARNING` に絞りたいが、
+現在は `app_debug=true` でしか詳細ログを出す方法がない。
+
+**期待する解決策**: `log_level: str = "INFO"` フィールドを追加。
+
+---
+
+### FT24-F3: AppSettings からミドルウェアを自動設定するヘルパーがない
+
+**概要**: AppSettings の設定値をミドルウェアに適用するには、
+毎回条件分岐付きのボイラープレートを手書きする必要がある。
+
+**判断**: `configure_middleware(app, settings)` ヘルパーは「薄い HTTP 層」の設計哲学に反し、
+フレームワークの主張が強くなりすぎる。FT アプリ側でパターンを提示する対応が適切。
+今回はドキュメント追加のみ。
+
+---
+
+## まとめ
+
+`AppSettings` は環境変数から型安全に設定を読み込む機能として正しく動作する。
+実運用での摩擦は:
+
+1. **list[str] 環境変数の書き方がわかりにくい** → ドキュメント追加対応
+2. **log_level フィールドがない** → Issue 化・修正対象
+3. **ミドルウェア自動設定ヘルパーがない** → 設計上の判断で修正しない

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-25.md

@@ -0,0 +1,82 @@
+# FT25: RequestIdMiddleware 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `RequestIdMiddleware` のリクエスト ID 生成・伝播・ContextVar 統合の実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft25-request-id/`
+
+---
+
+## 目的
+
+`nene2.middleware.RequestIdMiddleware` と `request_id_var` を使って、
+リクエスト ID を生成・伝播するパターンを検証する。
+
+---
+
+## 実施内容
+
+- `/api/echo` エンドポイントで `request_id_var.get()` を返す
+- クライアント提供の有効 UUID v4 の伝播確認
+- 無効な ID が新しい UUID に置き換えられることを確認
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_response_includes_x_request_id_header | PASS |
+| test_request_id_is_available_in_handler | PASS |
+| test_client_supplied_valid_uuid_is_preserved | PASS |
+| test_client_supplied_invalid_id_is_replaced | PASS |
+| test_each_request_gets_unique_id | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_request_id_not_accessible_from_middleware_stack | PASS | あり（ドキュメント） |
+| test_no_helper_to_get_request_id_from_header_in_handler | PASS | あり |
+| test_request_id_contextvars_isolation_per_request | PASS | なし（正しい動作） |
+
+---
+
+## 発見した摩擦点
+
+### FT25-F1: ミドルウェア順序依存がドキュメントに明記されていない
+
+**概要**: `request_id_var` はミドルウェアの実行順序に依存するが、
+これがドキュメントに明記されていない。
+`RequestIdMiddleware` より先に実行されるミドルウェアでは `request_id_var.get()` が空になる。
+
+**判断**: ミドルウェア追加順のドキュメント化で対応（how-to に記載）。
+
+---
+
+### FT25-F2: FastAPI Depends 用の get_request_id() ヘルパーがない
+
+**概要**: `request_id_var.get()` で直接取得できるが、
+FastAPI の依存性注入パターンと統合するヘルパーがない。
+
+```python
+# 各プロジェクトで毎回書く必要がある
+async def get_request_id() -> str:
+    return request_id_var.get()
+
+@app.get("/")
+async def handler(request_id: str = Depends(get_request_id)):
+    ...
+```
+
+**期待する解決策**: `nene2.middleware` から `get_request_id` を直接インポートできると便利。
+
+---
+
+## まとめ
+
+`RequestIdMiddleware` の基本機能（UUID v4 生成・検証・ContextVar 伝播・レスポンスヘッダー付与）は
+問題なく動作する。
+
+摩擦点:
+1. **ミドルウェア順序依存のドキュメント不備** → how-to に追記
+2. **`get_request_id()` Depends ヘルパーがない** → Issue 化・修正対象

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-26.md

@@ -0,0 +1,73 @@
+# FT26: nene2.log structlog 統合検証
+
+**日付**: 2026-05-20
+**テーマ**: `setup_logging()` と `AppSettings.log_level` の連携検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft26-logging/`
+
+---
+
+## 目的
+
+`nene2.log.setup_logging()` を実際のアプリで使い、
+`AppSettings.log_level`（FT24 で追加）との統合フローを検証する。
+
+---
+
+## 実施内容
+
+- `setup_logging()` の `local` / `production` 環境での動作確認
+- `RequestLoggingMiddleware` と structlog の連携確認
+- `AppSettings.log_level` を `setup_logging()` に渡す方法の検証
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_log_test_endpoint_returns_200 | PASS |
+| test_request_logging_middleware_logs_request | PASS |
+| test_log_levels_endpoint_returns_200 | PASS |
+| test_setup_logging_local_env | PASS |
+| test_setup_logging_production_env | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_setup_logging_does_not_accept_log_level_param | PASS | あり |
+| test_setup_logging_hardcodes_info_level | PASS | あり |
+| test_no_way_to_integrate_app_settings_log_level_with_setup_logging | PASS | あり（ボイラープレート） |
+
+---
+
+## 発見した摩擦点
+
+### FT26-F1: setup_logging() が log_level を受け取れない
+
+**概要**: FT24 で `AppSettings.log_level` が追加されたが、
+`setup_logging()` はそれを受け取るパラメータを持たない。
+`setup_logging()` は常に `logging.INFO` をハードコードするため、
+`AppSettings.log_level = "DEBUG"` を設定しても反映されない。
+
+```python
+# 現状: ボイラープレートが必要
+settings = AppSettings(log_level="DEBUG")
+setup_logging(app_env=settings.app_env)
+logging.getLogger().setLevel(settings.log_level)  # ← 別途必要
+
+# 期待する使い方
+setup_logging(app_env=settings.app_env, log_level=settings.log_level)
+```
+
+**期待する解決策**: `setup_logging(app_env="local", log_level="INFO")` のように
+`log_level` パラメータを追加して `AppSettings` と統合しやすくする。
+
+---
+
+## まとめ
+
+`setup_logging()` の基本機能（ConsoleRenderer / JSONRenderer の切り替え）は問題なく動作する。
+
+摩擦点:
+1. **`setup_logging()` に `log_level` パラメータがない** → `AppSettings.log_level` との統合時にボイラープレートが必要 → Issue 化・修正対象

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-27.md

@@ -0,0 +1,66 @@
+# FT27: ThrottleMiddleware 長時間運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `ThrottleMiddleware` の長時間稼働時のメモリ蓄積問題を検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft27-throttle-cleanup/`
+
+---
+
+## 目的
+
+`ThrottleMiddleware` の `_counts` ディクショナリに古いエントリが蓄積する問題（Issue #223）を実証し、
+修正方針を検討する。
+
+---
+
+## 実施内容
+
+- 複数 IP からのリクエストシミュレーション
+- ウィンドウ経過後のエントリ残存を確認
+- クリーンアップ機能の有無を検証
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_ping_returns_200 | PASS |
+| test_rate_limit_headers_present | PASS |
+| test_rate_limit_exceeded_returns_429 | PASS |
+| test_different_ips_have_separate_counters | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_stale_entries_accumulate_in_memory | PASS | あり（バグ） |
+| test_no_cleanup_method_exists_on_throttle_middleware | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT27-F1: 古いエントリが _counts から削除されない（Issue #223）
+
+**概要**: 異なるクライアント IP からリクエストが来るたびに `_counts` にエントリが追加されるが、
+ウィンドウ期間が過ぎても古いエントリは削除されない。
+長時間稼働・多数の異なるクライアントが存在する環境ではメモリが際限なく増加する。
+
+**確認した動作**:
+```python
+# 10 IP のエントリを作成 → window (1秒) 経過後も 10 エントリが残る
+# 新しい IP のリクエスト後も 11 エントリ (10 古い + 1 新しい)
+```
+
+**修正方針**: `_check_rate()` 内で定期的にクリーンアップを実施する。
+`_last_cleanup` タイムスタンプを持ち、`window` 秒経過したときに期限切れエントリを一括削除する。
+
+---
+
+## まとめ
+
+`ThrottleMiddleware` の基本機能は正常に動作する。
+
+摩擦点:
+1. **古いエントリのメモリ蓄積** → Issue #223 として登録済み、修正対象

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-28.md

@@ -0,0 +1,54 @@
+# FT28: ThrottleMiddleware パスごとのレート制限検証
+
+**日付**: 2026-05-20
+**テーマ**: `ThrottleMiddleware` のパスごとのレート制限（Issue #222）
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft28-path-throttle/`
+
+---
+
+## 目的
+
+重いエンドポイントだけ厳しいレート制限をかけたい実運用ニーズを検証する。
+
+---
+
+## 実施内容
+
+- `path_limits` パラメータの不在を確認
+- 現状では全エンドポイントで同じ `limit`/`window` しか設定できないことを実証
+
+---
+
+## テスト結果
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_throttle_middleware_does_not_support_path_limits | PASS | あり |
+| test_workaround_requires_multiple_middlewares | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT28-F1: ThrottleMiddleware がパスごとのレート制限をサポートしない（Issue #222）
+
+**概要**: 全エンドポイントで同じ `limit`/`window` しか設定できない。
+`/api/expensive` だけ `limit=10` にして残りは `limit=100` にする、という設定ができない。
+
+**期待する使い方**:
+```python
+app.add_middleware(
+    ThrottleMiddleware,
+    limit=100,
+    window=60,
+    path_limits={"/api/expensive": 10, "/api/search": 30},
+)
+```
+
+---
+
+## まとめ
+
+摩擦点:
+1. **`path_limits` 未対応** → Issue #222 として登録済み、修正対象

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-29.md

@@ -0,0 +1,74 @@
+# FT29: AsyncUseCaseProtocol 実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `AsyncUseCaseProtocol` を使った非同期 UseCase パターンの実運用検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft29-async-usecase/`
+
+---
+
+## 目的
+
+`AsyncUseCaseProtocol` の実装・FastAPI ハンドラーへの統合・並行処理の動作を検証する。
+
+---
+
+## 実施内容
+
+- 外部 API 呼び出しを模した `FetchDataUseCase` を実装
+- `asyncio.gather()` で並行実行を確認
+- Protocol 適合性と isinstance() の既知制限を検証
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_get_item_returns_200 | PASS |
+| test_slow_endpoint_returns_200 | PASS |
+| test_async_use_case_executes_correctly | PASS |
+| test_async_use_case_satisfies_protocol | PASS |
+| test_multiple_async_calls_are_independent | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_isinstance_cannot_distinguish_sync_vs_async_protocol | PASS | 既知（ADR-0010） |
+| test_no_async_usecase_base_class_provided | PASS | 軽微（設計通り） |
+| test_no_generic_di_container_for_async_use_cases | PASS | あり（ドキュメント不備） |
+
+---
+
+## 発見した摩擦点
+
+### FT29-F1: FastAPI Depends を使った AsyncUseCase DI パターンがドキュメント化されていない
+
+**概要**: `AsyncUseCaseProtocol` を FastAPI の依存性注入と統合する標準的なパターンがない。
+ユーザーは毎回自分でパターンを決める必要がある。
+
+```python
+# ユーザーが毎回書く必要があるボイラープレート
+def get_fetch_use_case() -> FetchDataUseCase:
+    return FetchDataUseCase()
+
+@app.get("/items/{item_id}")
+async def get_item(
+    item_id: int,
+    use_case: FetchDataUseCase = Depends(get_fetch_use_case),
+) -> JSONResponse:
+    result = await use_case.execute(FetchDataInput(item_id=item_id))
+    ...
+```
+
+**判断**: how-to ドキュメントに DI パターンを追記する（Issue 化）。
+
+---
+
+## まとめ
+
+`AsyncUseCaseProtocol` の基本機能（実装・FastAPI 統合・並行処理）は問題なく動作する。
+
+摩擦点:
+1. **AsyncUseCase + FastAPI DI パターンがドキュメント化されていない** → Issue 化・how-to に追記
+2. **isinstance() の sync/async 区別不可** → ADR-0010 記載の既知制限、修正不要

nene2_python-1.8.2/docs/field-trials/2026-05-field-trial-30.md

@@ -0,0 +1,66 @@
+# FT30: RequestLoggingMiddleware + structlog バインディング実運用検証
+
+**日付**: 2026-05-20
+**テーマ**: `RequestLoggingMiddleware` と structlog contextvars の実運用パターン検証
+**FT アプリ**: `/home/xi/docker/nene2-python-FT/ft30-request-logging/`
+
+---
+
+## 目的
+
+`RequestLoggingMiddleware` と structlog の contextvars 統合を実際のアプリで検証し、
+カスタムフィールドの付加方法を確認する。
+
+---
+
+## 実施内容
+
+- `RequestLoggingMiddleware` が自動バインドするコンテキスト（request_id, method, path）を確認
+- 追加のコンテキストフィールドを渡す方法を検証
+- `clear_contextvars()` の挙動確認
+
+---
+
+## テスト結果
+
+### test_app.py（正常系・機能確認）
+| テスト | 結果 |
+|---|---|
+| test_log_test_endpoint_returns_200 | PASS |
+| test_with_user_context_returns_200 | PASS |
+| test_request_id_is_in_response_header | PASS |
+
+### test_friction.py（摩擦点確認）
+| テスト | 結果 | 摩擦 |
+|---|---|---|
+| test_clear_contextvars_wipes_pre_bound_context | PASS | 軽微（設計上の制限） |
+| test_no_way_to_add_extra_fields_to_request_log | PASS | あり |
+
+---
+
+## 発見した摩擦点
+
+### FT30-F1: RequestLoggingMiddleware に extra_context パラメータがない
+
+**概要**: `service_name` や `version` などの静的フィールドを全リクエストログに含めたい場合、
+`RequestLoggingMiddleware` にパラメータとして渡す方法がない。
+
+```python
+# 期待する使い方
+app.add_middleware(
+    RequestLoggingMiddleware,
+    extra_context={"service": "my-api", "version": "1.0.0"},
+)
+```
+
+**期待する解決策**: `extra_context: dict[str, str] | None = None` パラメータを追加し、
+`bind_contextvars()` に追加フィールドとして渡す。
+
+---
+
+## まとめ
+
+`RequestLoggingMiddleware` の基本機能は問題なく動作する。
+
+摩擦点:
+1. **`extra_context` パラメータがない** → Issue 化・修正対象

nene2_python-1.8.2/docs/how-to/async-use-case.md

@@ -0,0 +1,121 @@
+# How-to: AsyncUseCase と FastAPI の統合
+
+## AsyncUseCaseProtocol の基本実装
+
+`AsyncUseCaseProtocol` は Protocol（構造的部分型）なので継承不要です。
+`async def execute(self, input_: I) -> O` を実装するだけで適合します。
+
+```python
+from dataclasses import dataclass
+from nene2.use_case import AsyncUseCaseProtocol
+
+
+@dataclass(frozen=True, slots=True)
+class FetchUserInput:
+    user_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class FetchUserOutput:
+    user_id: int
+    name: str
+
+
+class FetchUserUseCase:
+    async def execute(self, input_: FetchUserInput) -> FetchUserOutput:
+        # 外部 API 呼び出し・DB アクセスなど非同期処理
+        return FetchUserOutput(user_id=input_.user_id, name="Alice")
+```
+
+---
+
+## FastAPI Depends との統合
+
+ファクトリ関数を `Depends()` に渡すのが標準パターンです。
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+
+def get_fetch_user_use_case() -> FetchUserUseCase:
+    return FetchUserUseCase()
+
+
+@app.get("/users/{user_id}")
+async def get_user(
+    user_id: int,
+    use_case: FetchUserUseCase = Depends(get_fetch_user_use_case),
+) -> JSONResponse:
+    result = await use_case.execute(FetchUserInput(user_id=user_id))
+    return JSONResponse({"user_id": result.user_id, "name": result.name})
+```
+
+---
+
+## 外部依存を持つ UseCase の DI
+
+リポジトリや外部クライアントを受け取る UseCase は、依存も Depends で注入します。
+
+```python
+class FetchUserUseCase:
+    def __init__(self, repository: UserRepositoryInterface) -> None:
+        self._repository = repository
+
+    async def execute(self, input_: FetchUserInput) -> FetchUserOutput:
+        user = await self._repository.find_by_id(input_.user_id)
+        return FetchUserOutput(user_id=user.id, name=user.name)
+
+
+def get_user_repository() -> UserRepositoryInterface:
+    return InMemoryUserRepository()
+
+
+def get_fetch_user_use_case(
+    repository: UserRepositoryInterface = Depends(get_user_repository),
+) -> FetchUserUseCase:
+    return FetchUserUseCase(repository)
+```
+
+---
+
+## 並行実行
+
+複数の AsyncUseCase を並行実行するには `asyncio.gather()` を使います。
+
+```python
+import asyncio
+
+
+@app.get("/dashboard")
+async def dashboard(
+    user_id: int,
+    fetch_user: FetchUserUseCase = Depends(get_fetch_user_use_case),
+    fetch_stats: FetchStatsUseCase = Depends(get_fetch_stats_use_case),
+) -> JSONResponse:
+    user, stats = await asyncio.gather(
+        fetch_user.execute(FetchUserInput(user_id=user_id)),
+        fetch_stats.execute(FetchStatsInput(user_id=user_id)),
+    )
+    return JSONResponse({"user": user.name, "stats": stats.count})
+```
+
+---
+
+## isinstance() の注意点
+
+`AsyncUseCaseProtocol` は `@runtime_checkable` ですが、`isinstance()` は
+`execute` 属性の存在のみを確認します（sync/async の区別はしません）。
+
+```python
+# isinstance() は sync UseCase も True を返す（false positive）
+isinstance(sync_use_case, AsyncUseCaseProtocol)  # → True
+
+# 正しい非同期確認方法
+import inspect
+inspect.iscoroutinefunction(use_case.execute)  # → True/False
+```
+
+型安全性は `mypy --strict` の静的解析で保証します。詳細は ADR-0010 を参照してください。

{nene2_python-1.8.0 → nene2_python-1.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nene2-python"
-version = "1.8.0"
+version = "1.8.2"
 description = "NENE2 Python — minimal API framework following NENE2's design philosophy"
 readme = "README.md"
 license = {text = "MIT"}