nene2-python 1.5.0__tar.gz → 1.7.0__tar.gz

{nene2_python-1.5.0 → nene2_python-1.7.0}/CHANGELOG.md

@@ -5,6 +5,37 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.7.0] — 2026-05-20
+
+FT14〜FT17 フィールドトライアル — プロトコル docstring 改善・ミドルウェアカスタマイズ・DB 例外統一・バグ修正。
+
+### Added
+- `SecurityHeadersMiddleware` — `csp: str | None` パラメータで Content-Security-Policy 値をカスタマイズ可能に (FT15)
+- `SecurityHeadersMiddleware` — `extra_no_csp_paths: list[str] | None` パラメータでカスタム OpenAPI パスの CSP スキップを設定可能に (FT15)
+- `DatabaseIntegrityException` — UNIQUE/FK/CHECK 制約違反時に発生する新例外クラス (FT16)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-14.md` 〜 `docs/field-trials/2026-05-field-trial-17.md`
+
+### Changed
+- `AsyncUseCaseProtocol` / `UseCaseProtocol` — docstring に `@runtime_checkable` の `isinstance` 制限と `inspect.iscoroutinefunction()` によるランタイム確認方法を明記 (FT14)
+- `SqlAlchemyTransactionManager.transactional()` — `IntegrityError` をキャッチして `DatabaseIntegrityException` にラップするよう変更 (FT16)
+
+### Fixed
+- `SqlAlchemyQueryExecutor.write()` — `IntegrityError` が `DatabaseIntegrityException` にラップされない不整合を修正 (FT17-F1)
+- `SqlAlchemyQueryExecutor.write()` と `_BoundQueryExecutor.write()` — UPDATE/DELETE で 0 行影響した場合に前の INSERT の `lastrowid` が返るバグを修正; INSERT のみ `lastrowid`、UPDATE/DELETE は `rowcount` を返すよう変更 (FT17-F2)
+
+---
+
+## [1.6.0] — 2026-05-20
+
+FT13 (ValidationException実運用) field trial — validation DX improvements.
+
+### Added
+- `ValidationException.single(field, message, code)` — convenience classmethod for single-error raises
+- `ValidationError.__post_init__` now names the specific empty field in the error message
+- Field trial report: `docs/field-trials/2026-05-field-trial-13.md`
+
+---
+
 ## [1.5.0] — 2026-05-20
 
 FT12 (ThrottleMiddleware + RequestSizeLimitMiddleware) field trial — middleware exclude_paths consistency.

{nene2_python-1.5.0 → nene2_python-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.5.0
+Version: 1.7.0
 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.7.0/docs/field-trials/2026-05-field-trial-13.md

@@ -0,0 +1,54 @@
+# Field Trial 13 — ValidationException 実運用
+
+**Date:** 2026-05-20
+**App:** User Registration API（メール・パスワード・年齢の複合バリデーション）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft13-validation/`
+**nene2-python version:** v1.5.0
+
+## 概要
+
+`ValidationException` と `ValidationError` を実際のアプリで使い、
+複数フィールドのバリデーション・複数エラーの集約・レスポンス形式を検証した。
+
+## 動作確認結果
+
+- 複数フィールドのバリデーションエラーが一度に返ること ✓（fail-fast ではなく fail-all）
+- `ErrorHandlerMiddleware` が `ValidationException` を 422 に変換すること ✓
+- レスポンスが RFC 9457 形式で `errors` 配列を含むこと ✓
+- `ValidationError` の `field`, `message`, `code` が全フィールドで返ること ✓
+
+## 摩擦点
+
+### FT13-F1 (LOW): 単一エラーでもリストラップが必要
+
+単一フィールドのエラーでも `list` でラップする必要があり、やや冗長。
+
+```python
+# 現状（毎回リストが必要）
+raise ValidationException([ValidationError("email", "invalid", "invalid_email")])
+
+# こうしたい
+raise ValidationException.single("email", "invalid", "invalid_email")
+```
+
+特に UseCase 層で早期リターンするケース（1つのエラーが致命的で後続チェック不要な場合）に
+`ValidationException([...])` は読みにくい。
+
+### FT13-F2 (LOW): ValidationError の空文字エラーメッセージがどのフィールドか不明
+
+`ValidationError("", "message", "code")` を作ると `ValueError: field, message, and code must be non-empty strings` が出るが、どのフィールドが空かわからない。開発時のデバッグに時間がかかる。
+
+```python
+# 現状
+ValidationError("", "msg", "code")
+# → ValueError: field, message, and code must be non-empty strings
+
+# 改善案
+# → ValueError: ValidationError.field must not be empty
+```
+
+## まとめ
+
+`ValidationException` の基本動作は問題なし。摩擦は軽微で、実務で使うのに大きな障壁はない。
+FT13-F1 の `ValidationException.single()` はよくある単一エラーケースの DX 改善として有用。
+FT13-F2 はデバッグ時の QoL 向上。どちらも LOW 優先度。

nene2_python-1.7.0/docs/field-trials/2026-05-field-trial-14.md

@@ -0,0 +1,45 @@
+# Field Trial 14 — AsyncUseCaseProtocol 実運用
+
+**Date:** 2026-05-20
+**App:** Weather Dashboard API（複数都市の天気を asyncio.gather で並列取得）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft14-async/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`AsyncUseCaseProtocol` を使った非同期 UseCase を実際に実装し、
+`asyncio.gather` による並列 I/O の動作とプロトコルの挙動を検証した。
+
+## 動作確認結果
+
+- `AsyncUseCaseProtocol` の `isinstance` 検査が正しく動くこと ✓
+- `asyncio.gather` で 4 都市を並列取得した場合、50ms（直列の場合 200ms）で完了すること ✓
+- `FetchDashboardUseCase(fetch_weather: AsyncUseCaseProtocol[...])` のコンストラクタインジェクションが機能すること ✓
+- FastAPI の `async def` ハンドラーから非同期 UseCase を `await` で呼び出せること ✓
+
+## 摩擦点
+
+### FT14-F1 (LOW, ドキュメント): runtime_checkable の制限がプロトコルの docstring に記載されていない
+
+`isinstance(sync_obj, AsyncUseCaseProtocol)` が `True` を返す（Python の `@runtime_checkable` は
+メソッド名の存在のみを検査し、async/sync を区別しない）。
+
+```python
+class FakeSyncWeather:
+    def execute(self, input_: WeatherInput) -> str:  # async ではない
+        return "fake"
+
+isinstance(FakeSyncWeather(), AsyncUseCaseProtocol)  # → True（注意が必要）
+```
+
+この制限は ADR-0010 に記録済みだが、`AsyncUseCaseProtocol` の docstring には記載されていない。
+利用者が docstring だけ見て `isinstance` でランタイムガードを書くと誤動作する。
+
+**対応**: プロトコルの docstring に「mypy --strict が静的に保証する; isinstance はメソッド名のみを検査する」旨を追記する。
+
+## まとめ
+
+基本動作は問題なし。`asyncio.gather` パターン・コンストラクタインジェクション・FastAPI 統合のいずれも
+摩擦なく動作した。唯一の摩擦は docstring によるドキュメントギャップ（LOW）のみ。
+
+FT14 は「設計が正しく実装されている」ことの確認として有用だった。

nene2_python-1.7.0/docs/field-trials/2026-05-field-trial-15.md

@@ -0,0 +1,67 @@
+# Field Trial 15 — SecurityHeadersMiddleware 実運用
+
+**Date:** 2026-05-20
+**App:** FT15 Security Headers API（セキュリティヘッダーの付与・CSP 動作確認）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft15-security-headers/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`SecurityHeadersMiddleware` を実際のアプリに組み込み、各ヘッダーの付与動作・
+CSP スキップロジック・カスタマイズ可能性を検証した。
+
+## 動作確認結果
+
+- 通常エンドポイントに `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Content-Security-Policy`, `Permissions-Policy` の全ヘッダーが付与されること ✓
+- `/docs`, `/redoc`, `/openapi.json` では `Content-Security-Policy` がスキップされること ✓
+- CSP スキップ時も他のヘッダーは引き続き付与されること ✓
+
+## 摩擦点
+
+### FT15-F1 (MEDIUM, 拡張性): カスタム OpenAPI パスで CSP スキップが効かない
+
+`SecurityHeadersMiddleware` がスキップする OpenAPI パスは `_OPENAPI_PATHS` 定数で
+`{"/docs", "/redoc", "/openapi.json"}` にハードコードされている。
+
+FastAPI では `docs_url` / `redoc_url` でカスタムパスを設定できるが、
+カスタムパス（例: `/api-docs`）では CSP スキップが効かず、Swagger UI が CDN アセットを
+ブロックされる可能性がある。
+
+```python
+app = FastAPI(docs_url="/api-docs", redoc_url="/api-redoc")
+app.add_middleware(SecurityHeadersMiddleware)
+# → /api-docs に CSP "default-src 'self'" が付いてしまう
+```
+
+**対応**: コンストラクタに `extra_no_csp_paths: list[str] | None = None` を追加し、
+ユーザーがカスタム OpenAPI パスを指定できるようにする。または `ThrottleMiddleware` と
+同様の `exclude_paths` パターンで完全スキップを可能にする。
+
+### FT15-F2 (LOW, 拡張性): CSP をコンストラクタで上書きできない
+
+CSP の値 `"default-src 'self'"` はモジュールレベルの `_HEADERS` 定数にハードコードされており、
+コンストラクタから上書きできない。
+
+CDN アセットを許可したい（`content-src 'self' cdn.example.com`）など、
+CSP を変更したいユーザーは `_HEADERS` をモジュールレベルで直接書き換えるしかなく、
+グローバルな副作用が発生する。
+
+```python
+# 現状の唯一の方法（副作用あり）
+from nene2.middleware import security_headers
+security_headers._HEADERS["Content-Security-Policy"] = "default-src 'self' cdn.example.com"
+```
+
+**対応**: `SecurityHeadersMiddleware(csp: str | None = None)` でコンストラクタから
+CSP 値を上書きできるようにする。
+
+## まとめ
+
+基本動作は問題なし。全セキュリティヘッダーの付与・OpenAPI パスでの CSP スキップも
+正常に機能した。摩擦は拡張性の面で2点あり：
+
+- FT15-F1 (MEDIUM): カスタム OpenAPI パスで CSP スキップが効かない
+- FT15-F2 (LOW): CSP 値をコンストラクタから変更できない
+
+`ThrottleMiddleware` が `exclude_paths` を持つのに対し、`SecurityHeadersMiddleware` は
+カスタマイズポイントがゼロであるため、実用アプリでの柔軟性が低い。

nene2_python-1.7.0/docs/field-trials/2026-05-field-trial-16.md

@@ -0,0 +1,62 @@
+# Field Trial 16 — transactional(callback) パターン実運用
+
+**Date:** 2026-05-20
+**App:** 銀行口座送金 API（送金元の残高を減らして送金先に加算する atomic 操作）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft16-transaction/`
+**nene2-python version:** v1.6.0
+
+## 概要
+
+`transactional(callback)` パターンを実際の送金ユースケースに適用し、
+ロールバック挙動・例外処理・async コンテキストとの相互作用を検証した。
+
+## 動作確認結果
+
+- `transactional(callback)` が atomic に実行されること ✓
+- `CHECK 制約違反`（残高 < 0）発生時に全操作がロールバックされること ✓
+- `UNIQUE 制約違反`（IntegrityError）でもロールバックが正しく行われること ✓
+- SQLite `:memory:` + `StaticPool` で `SqlAlchemyQueryExecutor` と `SqlAlchemyTransactionManager` を同一 DB に向けられること ✓
+
+## 摩擦点
+
+### FT16-F1 (MEDIUM, API一貫性): IntegrityError が DatabaseConnectionException にラップされない
+
+`SqlAlchemyTransactionManager.transactional()` は `OperationalError` のみを
+`DatabaseConnectionException` に変換し、`IntegrityError`（UNIQUE 制約違反・FK 制約違反など）は
+生の SQLAlchemy 例外として呼び出し側に伝播する。
+
+UseCase 層でフレームワーク独自例外に統一されていないため、
+呼び出し元が SQLAlchemy の例外型に依存した `except IntegrityError` を書く必要がある。
+
+```python
+from sqlalchemy.exc import IntegrityError
+
+with pytest.raises(IntegrityError):  # 摩擦: SQLAlchemy 依存が漏れ出す
+    tx_manager.transactional(_duplicate_insert)
+```
+
+**対応案**: `IntegrityError` も `DatabaseConnectionException`（または新設の `DatabaseIntegrityException`）にラップする。または `transactional()` がキャッチすべき SQLAlchemy 例外一覧をドキュメントに明記する。
+
+### FT16-F2 (LOW, 非同期対応): async コンテキストから transactional() を呼ぶとイベントループをブロックする
+
+`SqlAlchemyTransactionManager.transactional()` は同期 API であるため、
+FastAPI の `async def` ハンドラーから直接呼ぶとイベントループをブロックする。
+現状の実装でも動作はするが、高負荷時にパフォーマンス劣化の原因になりうる。
+
+```python
+@app.post("/transfer")
+async def transfer(...) -> JSONResponse:
+    # 同期 transactional() を直接呼んでいる（イベントループブロッキング）
+    result = transfer_uc.execute(...)
+```
+
+**対応案**: `asyncio.to_thread()` でのラップをドキュメントに記載する。
+または `AsyncSqlAlchemyTransactionManager` を将来的に追加する（SQLAlchemy async core を利用）。
+
+## まとめ
+
+コアの atomic 保証（コミット・ロールバック）は期待通りに機能した。
+摩擦は例外ハンドリングの API 一貫性（F1: MEDIUM）と非同期対応（F2: LOW）の2点。
+
+F1 は UseCase 層が SQLAlchemy に依存するアーキテクチャ上の問題であり、
+Clean Architecture の原則に照らして対応が必要。

nene2_python-1.7.0/docs/field-trials/2026-05-field-trial-17.md

@@ -0,0 +1,66 @@
+# Field Trial 17 — 複数ドメイン連携実運用
+
+**Date:** 2026-05-20
+**App:** タスク管理API（Task + Category の2ドメイン連携）
+**Directory:** `/home/xi/docker/nene2-python-FT/ft17-multi-domain/`
+**nene2-python version:** v1.6.0 (local dev build)
+
+## 概要
+
+Task（タスク）と Category（カテゴリ）の2ドメインを連携させたアプリを実装し、
+`SqlAlchemyQueryExecutor.write()` と `DatabaseIntegrityException`、
+`transactional(callback)` の混在パターンの DX を検証した。
+
+## 動作確認結果
+
+- カテゴリ一覧・タスク一覧・カテゴリでのフィルタリングが動作すること ✓
+- タスク完了（UPDATE）操作が正常に機能すること ✓（ただし FT17-F2 の制約あり）
+- `transactional()` 内の `IntegrityError` が `DatabaseIntegrityException` に変換されること ✓
+
+## 摩擦点
+
+### FT17-F1 (HIGH, バグ): SqlAlchemyQueryExecutor.write() が IntegrityError をキャッチしない
+
+`_BoundQueryExecutor.write()`（`transactional()` 内部で使われる）は FT16 で `IntegrityError` を
+`DatabaseIntegrityException` に変換するよう修正されたが、
+`SqlAlchemyQueryExecutor.write()`（直接呼び出し）は対応していない。
+
+同じ「INSERT が重複するケース」でも、使う API によって異なる例外型が飛ぶ：
+
+```python
+# 直接 write() → IntegrityError (SQLAlchemy)
+executor.write("INSERT INTO categories (name) VALUES (:name)", {"name": "dup"})
+
+# transactional() 内 write() → DatabaseIntegrityException (nene2)
+tx_manager.transactional(lambda ex: ex.write("INSERT INTO categories (name) VALUES (:name)", {"name": "dup"}))
+```
+
+UseCase 層でどちらの API を使うかによって `except` 節を変える必要があり、一貫性がない。
+
+**対応**: `SqlAlchemyQueryExecutor.write()` でも `IntegrityError` をキャッチして
+`DatabaseIntegrityException` にラップする。
+
+### FT17-F2 (HIGH, バグ): write() が UPDATE/DELETE で 0 行影響した場合に誤った値を返す
+
+`write()` は `result.lastrowid or result.rowcount` を返すが、SQLite では UPDATE/DELETE の後も
+`cursor.lastrowid` が前の INSERT の rowid を保持する。
+
+```python
+# DB に id=1 の行がある状態で
+result = executor.write("UPDATE items SET name = 'x' WHERE id = 999")  # 0行影響
+# result == 1 (前のINSERTのlastrowid) — 期待値は 0
+```
+
+`if affected == 0: raise NotFound` のパターンが正しく動かない。
+
+**対応**: SQL が `INSERT` で始まる場合のみ `lastrowid` を使い、UPDATE/DELETE は `rowcount` を返す。
+
+## まとめ
+
+ドメイン間連携（JOIN クエリ、カテゴリフィルタリング）は問題なく動作した。
+ただし `SqlAlchemyQueryExecutor.write()` に HIGH レベルのバグが2件あり:
+
+- FT17-F1: `IntegrityError` が `DatabaseIntegrityException` に変換されない（API 非対称）
+- FT17-F2: UPDATE/DELETE で 0 行影響した場合の戻り値が不正
+
+両方とも `_BoundQueryExecutor.write()` には修正済みだが、`SqlAlchemyQueryExecutor.write()` に未適用。

{nene2_python-1.5.0 → nene2_python-1.7.0}/pyproject.toml

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

{nene2_python-1.5.0 → nene2_python-1.7.0}/src/nene2/database/__init__.py

@@ -1,6 +1,6 @@
 """NENE2 database abstraction layer."""
 
-from .exceptions import DatabaseConnectionException
+from .exceptions import DatabaseConnectionException, DatabaseIntegrityException
 from .health import DatabaseHealthCheck
 from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManagerInterface
 from .sqlalchemy_executor import SqlAlchemyQueryExecutor, SqlAlchemyTransactionManager
@@ -8,6 +8,7 @@ from .utils import parse_db_datetime
 
 __all__ = [
     "DatabaseConnectionException",
+    "DatabaseIntegrityException",
     "DatabaseHealthCheck",
     "DatabaseQueryExecutorInterface",
     "DatabaseTransactionManagerInterface",

{nene2_python-1.5.0 → nene2_python-1.7.0}/src/nene2/database/exceptions.py

@@ -3,3 +3,7 @@
 
 class DatabaseConnectionException(Exception):
     """Raised when a database connection cannot be established."""
+
+
+class DatabaseIntegrityException(Exception):
+    """Raised when a database integrity constraint is violated (UNIQUE, FK, CHECK, etc.)."""

{nene2_python-1.5.0 → nene2_python-1.7.0}/src/nene2/database/sqlalchemy_executor.py

@@ -7,9 +7,9 @@ from collections.abc import Callable
 from typing import Any
 
 from sqlalchemy import Connection, Engine, text
-from sqlalchemy.exc import OperationalError
+from sqlalchemy.exc import IntegrityError, OperationalError
 
-from .exceptions import DatabaseConnectionException
+from .exceptions import DatabaseConnectionException, DatabaseIntegrityException
 from .interfaces import DatabaseQueryExecutorInterface, DatabaseTransactionManagerInterface
 
 
@@ -41,7 +41,7 @@ class SqlAlchemyQueryExecutor(DatabaseQueryExecutorInterface):
 
         Return value semantics:
         - INSERT with AUTOINCREMENT/SERIAL column → ``lastrowid`` (the new row's PK, always > 0)
-        - INSERT without auto-PK, or multi-row INSERT → falls back to ``rowcount``
+        - INSERT without auto-PK, or multi-row INSERT → ``rowcount``
         - UPDATE / DELETE → ``rowcount`` (number of rows affected; 0 means nothing matched)
 
         Use the return value to detect missing rows::
@@ -53,7 +53,11 @@ class SqlAlchemyQueryExecutor(DatabaseQueryExecutorInterface):
         try:
             with self._engine.begin() as conn:
                 result = conn.execute(text(sql), params or {})
-                return result.lastrowid or result.rowcount
+                if sql.strip().upper().startswith("INSERT"):
+                    return result.lastrowid or result.rowcount
+                return result.rowcount
+        except IntegrityError as exc:
+            raise DatabaseIntegrityException(str(exc)) from exc
         except OperationalError as exc:
             raise DatabaseConnectionException(str(exc)) from exc
 
@@ -82,9 +86,13 @@ class _BoundQueryExecutor(DatabaseQueryExecutorInterface):
     def write(self, sql: str, params: dict[str, Any] | None = None) -> int:
         try:
             result = self._conn.execute(text(sql), params or {})
+        except IntegrityError as exc:
+            raise DatabaseIntegrityException(str(exc)) from exc
         except OperationalError as exc:
             raise DatabaseConnectionException(str(exc)) from exc
-        return result.lastrowid or result.rowcount
+        if sql.strip().upper().startswith("INSERT"):
+            return result.lastrowid or result.rowcount
+        return result.rowcount
 
 
 class SqlAlchemyTransactionManager(DatabaseTransactionManagerInterface):
@@ -104,6 +112,10 @@ class SqlAlchemyTransactionManager(DatabaseTransactionManagerInterface):
         try:
             with self._engine.begin() as conn:
                 return callback(_BoundQueryExecutor(conn))
+        except DatabaseIntegrityException:
+            raise
+        except IntegrityError as exc:
+            raise DatabaseIntegrityException(str(exc)) from exc
         except OperationalError as exc:
             raise DatabaseConnectionException(str(exc)) from exc
 

{nene2_python-1.5.0 → nene2_python-1.7.0}/src/nene2/middleware/security_headers.py

@@ -9,15 +9,16 @@ from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoin
 from starlette.requests import Request
 from starlette.responses import Response
 
-_HEADERS: dict[str, str] = {
+_DEFAULT_CSP = "default-src 'self'"
+
+_NON_CSP_HEADERS: dict[str, str] = {
     "X-Content-Type-Options": "nosniff",
     "X-Frame-Options": "DENY",
     "Referrer-Policy": "strict-origin-when-cross-origin",
-    "Content-Security-Policy": "default-src 'self'",
     "Permissions-Policy": "geolocation=(), microphone=()",
 }
 
-_OPENAPI_PATHS: frozenset[str] = frozenset({"/docs", "/redoc", "/openapi.json"})
+_DEFAULT_NO_CSP_PATHS: frozenset[str] = frozenset({"/docs", "/redoc", "/openapi.json"})
 
 
 class SecurityHeadersMiddleware(BaseHTTPMiddleware):
@@ -25,13 +26,29 @@ class SecurityHeadersMiddleware(BaseHTTPMiddleware):
 
     Content-Security-Policy is omitted for OpenAPI documentation paths so that
     Swagger UI and ReDoc (which load assets from CDN) continue to work in development.
+
+    Args:
+        csp: Custom Content-Security-Policy header value.
+            Defaults to ``"default-src 'self'"`` when not specified.
+        extra_no_csp_paths: Additional paths to skip the CSP header for.
+            Useful when FastAPI is configured with custom ``docs_url`` / ``redoc_url``.
+            The built-in paths ``/docs``, ``/redoc``, and ``/openapi.json`` are always included.
     """
 
+    def __init__(
+        self,
+        app: object,
+        csp: str | None = None,
+        extra_no_csp_paths: list[str] | None = None,
+    ) -> None:
+        super().__init__(app)  # type: ignore[arg-type]
+        self._csp = csp if csp is not None else _DEFAULT_CSP
+        self._no_csp_paths = _DEFAULT_NO_CSP_PATHS | frozenset(extra_no_csp_paths or [])
+
     async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
         response = await call_next(request)
-        is_openapi_path = request.url.path in _OPENAPI_PATHS
-        for header, value in _HEADERS.items():
-            if is_openapi_path and header == "Content-Security-Policy":
-                continue
+        for header, value in _NON_CSP_HEADERS.items():
             response.headers[header] = value
+        if request.url.path not in self._no_csp_paths:
+            response.headers["Content-Security-Policy"] = self._csp
         return response

nene2_python-1.7.0/src/nene2/use_case/protocols.py

@@ -0,0 +1,51 @@
+"""Structural type contracts for UseCase and AsyncUseCase.
+
+UseCaseProtocol — synchronous execute(input_) -> output
+AsyncUseCaseProtocol — async execute(input_) -> output (awaitable)
+
+Both use Python 3.12 generic syntax; any class with a matching
+execute() signature satisfies them structurally (no inheritance needed).
+
+Runtime isinstance() limitation
+---------------------------------
+Both protocols are @runtime_checkable, but Python's isinstance() only
+checks that the ``execute`` attribute exists — it does NOT distinguish
+between sync and async implementations. As a result:
+
+    isinstance(sync_obj, AsyncUseCaseProtocol)  # → True (false positive)
+    isinstance(async_obj, UseCaseProtocol)       # → True (false positive)
+
+Static type safety (sync vs async) is guaranteed by mypy --strict, not
+by isinstance() at runtime. If you need a runtime async check, use:
+
+    import inspect
+    inspect.iscoroutinefunction(obj.execute)
+
+See ADR-0010 for the full rationale.
+"""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class UseCaseProtocol[I, O](Protocol):
+    """Synchronous use-case contract.
+
+    Warning: isinstance() only checks that ``execute`` exists, not whether
+    it is synchronous. Use mypy --strict for compile-time enforcement, or
+    ``not inspect.iscoroutinefunction(obj.execute)`` for a runtime check.
+    """
+
+    def execute(self, input_: I) -> O: ...
+
+
+@runtime_checkable
+class AsyncUseCaseProtocol[I, O](Protocol):
+    """Asynchronous use-case contract — execute must be a coroutine.
+
+    Warning: isinstance() only checks that ``execute`` exists, not whether
+    it is async. Use mypy --strict for compile-time enforcement, or
+    ``inspect.iscoroutinefunction(obj.execute)`` for a runtime check.
+    """
+
+    async def execute(self, input_: I) -> O: ...

{nene2_python-1.5.0 → nene2_python-1.7.0}/src/nene2/validation/exceptions.py

@@ -16,8 +16,9 @@ class ValidationError:
     code: str
 
     def __post_init__(self) -> None:
-        if not self.field or not self.message or not self.code:
-            raise ValueError("field, message, and code must be non-empty strings")
+        for attr in ("field", "message", "code"):
+            if not getattr(self, attr):
+                raise ValueError(f"ValidationError.{attr} must not be empty")
 
     def to_dict(self) -> dict[str, str]:
         return {"field": self.field, "message": self.message, "code": self.code}
@@ -27,8 +28,25 @@ class ValidationException(Exception):
     """Raised when one or more validation rules fail.
 
     ErrorHandlerMiddleware maps this to a 422 validation-failed Problem Details response.
+
+    For a single error, use the convenience method::
+
+        raise ValidationException.single("email", "invalid", "invalid_email")
+
+    For multiple errors accumulated during validation::
+
+        errors = []
+        if not valid_email:
+            errors.append(ValidationError("email", "invalid", "invalid_email"))
+        if errors:
+            raise ValidationException(errors)
     """
 
     def __init__(self, errors: list[ValidationError]) -> None:
         super().__init__("Validation failed")
         self.errors = errors
+
+    @classmethod
+    def single(cls, field: str, message: str, code: str) -> "ValidationException":
+        """Convenience constructor for a single validation error."""
+        return cls([ValidationError(field, message, code)])