nene2-python 1.8.3__tar.gz → 1.8.5__tar.gz

{nene2_python-1.8.3 → nene2_python-1.8.5}/CHANGELOG.md

@@ -5,6 +5,32 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
+## [1.8.5] — 2026-05-20
+
+FT37〜FT40 フィールドトライアル — RequestSizeLimitMiddleware パスごとサイズ制限とドキュメント改善。
+
+### Added
+- `RequestSizeLimitMiddleware` に `path_limits: dict[str, int] | None = None` パラメータを追加 — パスごとに異なるリクエストボディサイズ制限を設定可能に (FT39)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-37.md` 〜 `docs/field-trials/2026-05-field-trial-40.md`
+
+---
+
+## [1.8.4] — 2026-05-20
+
+FT33〜FT36 フィールドトライアル — バリデーション・DB整合性・混合認証・非同期ヘルスチェック改善。
+
+### Added
+- `AsyncHealthCheckProtocol` — `async def check() -> HealthStatus` の Protocol (FT36)
+- `AsyncCompositeHealthCheck` — 複数の非同期ヘルスチェックを `asyncio.gather` で並列実行して集約するクラス (FT36)
+- `docs/how-to/validation.md` — `ValidationCode(StrEnum)` パターンと複数フィールドバリデーションの how-to ガイドを追加 (FT33)
+- Field trial reports: `docs/field-trials/2026-05-field-trial-33.md` 〜 `docs/field-trials/2026-05-field-trial-36.md`
+
+### Changed
+- `docs/how-to/run-tests.md` — インメモリ SQLite テスト用 `StaticPool` パターンを追記 (FT34)
+- `docs/how-to/configure-auth.md` — AND / OR 条件の違いと `EitherOrAuthMiddleware` パターンを追記 (FT35)
+
+---
+
 ## [1.8.3] — 2026-05-20
 
 FT31〜FT32 フィールドトライアル — HealthCheck・SecurityHeaders 改善。

{nene2_python-1.8.3 → nene2_python-1.8.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nene2-python
-Version: 1.8.3
+Version: 1.8.5
 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.5/docs/field-trials/2026-05-field-trial-33.md

@@ -0,0 +1,111 @@
+# Field Trial 33: ValidationException カスタムエラーコード実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `ValidationException` と `ValidationError.code` フィールドを活用した型安全なエラーコードの実運用パターン検証
+
+---
+
+## 概要
+
+ユーザー登録 API を題材に、`ValidationCode(StrEnum)` パターンでドメイン固有のバリデーションコードを定義し、
+`ValidationException` / `ValidationError` と組み合わせて複数フィールドの検証エラーをクライアントに返すフローを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft33-validation-codes/` に以下を作成:
+
+- **`app.py`** — `ValidationCode(StrEnum)` + `ValidationException` によるユーザー登録 API
+- **`test_app.py`** — 正常系・各バリデーションエラー・複数エラー収集の動作テスト (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+```python
+class ValidationCode(StrEnum):
+    REQUIRED = "required"
+    INVALID_FORMAT = "invalid_format"
+    TOO_SHORT = "too_short"
+    TOO_LONG = "too_long"
+    ALREADY_EXISTS = "already_exists"
+    OUT_OF_RANGE = "out_of_range"
+
+def _validate_registration(body: RegisterBody) -> list[ValidationError]:
+    errors: list[ValidationError] = []
+    if len(body.username) < 3:
+        errors.append(ValidationError("username", "3文字以上必要です", ValidationCode.TOO_SHORT))
+    if "@" not in body.email:
+        errors.append(ValidationError("email", "有効なメールアドレスを入力してください", ValidationCode.INVALID_FORMAT))
+    if body.age < 0 or body.age > 150:
+        errors.append(ValidationError("age", "年齢は 0〜150 の範囲で入力してください", ValidationCode.OUT_OF_RANGE))
+    return errors
+```
+
+**テスト結果**: 8 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP33-1: フレームワークが標準エラーコードを定義していない
+
+**分類**: 設計通り（摩擦なし）
+
+`required` / `invalid_format` / `too_short` / `too_long` 等のよく使うコードを
+フレームワーク側が `ValidationCode` として提供していない。
+各プロジェクトで自前定義が必要。
+
+**判断**: ドメイン固有のコードはプロジェクトで定義するのが適切。フレームワークが網羅的に
+定義すると過剰な依存・名前衝突・拡張困難になる。`StrEnum` パターンを how-to ドキュメントに
+追記することで、新規プロジェクトの立ち上がりをサポートする。
+
+**対応**: `docs/how-to/validation.md` への `StrEnum` パターン記載（ドキュメントのみ）
+
+---
+
+### FP33-2: `ValidationException.single()` の `code` パラメータにデフォルト値がない
+
+**分類**: 既知の設計制約（摩擦なし）
+
+`code` パラメータは必須。`"required"` 等よく使うコードでもデフォルト値なし。
+
+**判断**: 明示的なコードが可読性・型安全性を高める設計上の意図。
+デフォルト値をつけると「コードなし」での利用が増え、クライアント側でのエラーハンドリングが困難になる。
+これは摩擦ではなく既知の制約として受け入れる。
+
+---
+
+### FP33-3: ネストフィールドのエラーパスに点記法ヘルパーがない
+
+**分類**: 軽微な摩擦
+
+`body.email` のようなネストパスを `ValidationError.field` に渡す際、正規化ヘルパーがない。
+任意文字列として渡すのみ。
+
+```python
+error = ValidationError(field="address.city", message="必須です", code="required")
+# 正規化なし — 任意の文字列を受け入れる
+```
+
+**判断**: ネストパスの表現方法（ドット区切り・スラッシュ・配列表記）はプロジェクトにより異なるため、
+フレームワーク側でヘルパーを提供するメリットは小さい。
+ドキュメントでの推奨パターン（ドット区切り）記載で対応。
+
+---
+
+## 所感
+
+`ValidationCode(StrEnum)` パターンは極めて自然に機能する。
+`ValidationError` コンストラクタに `StrEnum` 値をそのまま渡せるため、型安全性と
+JSON シリアライズ（文字列として出力）が同時に確保される。複数フィールドのエラー収集も
+リストに積み上げるだけで直感的。
+
+フレームワーク側で追加の変更は不要。how-to ドキュメントへの `StrEnum` パターン追記のみ対応する。
+
+---
+
+## 関連
+
+- `nene2.validation.ValidationException`
+- `nene2.validation.ValidationError`
+- FT13 (ValidationException実運用, v1.6.0) の後継検証

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-34.md

@@ -0,0 +1,119 @@
+# Field Trial 34: DatabaseIntegrityException + SimpleDomainHandler 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: UNIQUE 制約違反 → `DatabaseIntegrityException` → `SimpleDomainHandler` → 409 Problem Details のパイプライン実運用検証
+
+---
+
+## 概要
+
+SQLite UNIQUE 制約を持つ `users` テーブルに `SqlAlchemyQueryExecutor` でアクセスし、
+重複 username の登録が自動的に `DatabaseIntegrityException` へ変換され、
+`SimpleDomainHandler` が 409 Conflict Problem Details を返す完全なパイプラインを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft34-db-integrity/` に以下を作成:
+
+- **`app.py`** — SQLite インメモリ DB + `SqlAlchemyQueryExecutor` + `SimpleDomainHandler` による UNIQUE 違反ハンドリング
+- **`test_app.py`** — 正常系・409・Problem Details 構造・バリデーションエラー混在 (6 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+```python
+handlers = [
+    SimpleDomainHandler(
+        DatabaseIntegrityException,
+        "username-already-taken",
+        "Username Already Taken",
+        409,
+        detail="このユーザー名はすでに使用されています",
+    ),
+]
+app.add_middleware(ErrorHandlerMiddleware, domain_handlers=handlers)
+```
+
+**テスト結果**: 10 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP34-1: `DatabaseIntegrityException` のメッセージが SQLAlchemy の生テキスト
+
+**分類**: 既知の制約（摩擦あり・軽微）
+
+```
+(sqlite3.IntegrityError) UNIQUE constraint failed: users.username
+```
+
+どのフィールドが重複したかを取り出すには文字列パースが必要。
+DB エンジンごとにメッセージ形式が異なる（SQLite / MySQL / PostgreSQL）。
+
+**判断**: フレームワーク側でフィールド抽出 API を提供することも可能だが、
+エンジン依存のパースロジックを組み込むと移植性が下がる。
+アプリ側でドメイン固有の例外（`UsernameTakenException` など）に変換するパターンを推奨。
+
+---
+
+### FP34-2: 制約種別を示すサブクラスがない
+
+**分類**: 既知の制約（摩擦あり・軽微）
+
+`DatabaseIntegrityException` は UNIQUE / FK / CHECK 制約を区別しない。
+違反種別で異なるレスポンスを返したい場合は文字列パースが必要。
+
+**判断**: 制約種別サブクラスの追加は有用だが、DB エンジンごとの判定ロジックが複雑になる。
+現時点はアプリ側で try/except してドメイン例外に変換する方針を how-to ドキュメントで説明。
+
+---
+
+### FP34-3: テスト用インメモリ SQLite に `StaticPool` が必要
+
+**分類**: 摩擦あり → **ドキュメント対応**
+
+`SqlAlchemyQueryExecutor` はクエリごとに `engine.begin()` / `engine.connect()` で
+コネクションを開く。`sqlite:///:memory:` はコネクションごとに独立した DB を作成するため、
+`StaticPool` なしではクエリ間でテーブルが見えなくなる場合がある。
+
+```python
+# 推奨パターン
+engine = create_engine(
+    "sqlite:///:memory:",
+    connect_args={"check_same_thread": False},
+    poolclass=StaticPool,
+)
+```
+
+**対応**: `docs/how-to/run-tests.md` に `StaticPool` 使用を明記。
+
+---
+
+### FP34-4: `SimpleDomainHandler` は制約種別を区別できない
+
+**分類**: 設計通り（摩擦なし）
+
+`SimpleDomainHandler` は例外クラスのみで判定する。
+UNIQUE 違反と FK 違反を別々の HTTP ステータスにマップしたい場合は
+`DomainExceptionHandlerProtocol` を実装する必要がある。
+
+**判断**: `SimpleDomainHandler` はシンプルケース専用のヘルパーという設計意図通り。
+複雑なケースには Protocol 実装を使うのが正しい。
+
+---
+
+## フレームワーク変更
+
+- `docs/how-to/run-tests.md` に `StaticPool` パターンを追記 (FP34-3 対応)
+
+---
+
+## 関連
+
+- `nene2.database.DatabaseIntegrityException`
+- `nene2.database.SqlAlchemyQueryExecutor`
+- `nene2.middleware.SimpleDomainHandler`
+- FT16 (DatabaseIntegrityException 実装, v1.7.0)
+- FT21 (SimpleDomainHandler 実装, v1.8.0)

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-35.md

@@ -0,0 +1,90 @@
+# Field Trial 35: 混合認証（Bearer Token OR API Key）実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `BearerTokenMiddleware` と `ApiKeyAuthMiddleware` の組み合わせパターン、
+および「いずれか一方で可（OR 条件）」認証の実装コストを確認する
+
+---
+
+## 概要
+
+Bearer Token 専用・API Key 専用の各ベースラインを確認した後、
+2 つのミドルウェアをスタックした場合の挙動と、
+OR 条件認証のカスタム実装を比較した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft35-mixed-auth/` に以下を作成:
+
+- **`app.py`** — 4 パターンのアプリ（Bearer のみ・API Key のみ・両方スタック・EitherOr カスタム）
+- **`test_app.py`** — 全パターンの動作検証 (13 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 16 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP35-1: ミドルウェアを2つスタックすると AND 条件になる
+
+**分類**: 摩擦あり（設計上の制約）
+
+`BearerTokenMiddleware` と `ApiKeyAuthMiddleware` を両方 `add_middleware` すると、
+各ミドルウェアが独立して検証するため「両方必須（AND）」になる。
+Bearer Token のみ・API Key のみの場合どちらも 401。
+
+```python
+# この設定は AND 条件（両方必須）
+app.add_middleware(ApiKeyAuthMiddleware, ...)
+app.add_middleware(BearerTokenMiddleware, ...)
+```
+
+**判断**: Starlette のミドルウェアスタックの仕様通り。
+`configure-auth.md` に明記し、AND と OR の違いを説明する。
+
+---
+
+### FP35-2: OR 条件の認証にはカスタムミドルウェアの実装が必要
+
+**分類**: 摩擦あり（実装コスト発生）
+
+「Bearer または API Key のいずれかで可」を実現するには
+`BaseHTTPMiddleware` を継承してカスタム実装する必要がある。
+フレームワークに汎用 OR ミドルウェアはない。
+
+ただし、`LocalTokenVerifier` / `TokenVerifierProtocol` は再利用可能なため、
+カスタム実装のコードは約 30 行と軽量。
+
+**判断**: OR 条件の仕様はプロジェクトによって多様すぎるため、
+フレームワークが汎用実装を提供するより、パターンをドキュメントで示す方が適切。
+
+**対応**: `docs/how-to/configure-auth.md` に `EitherOrAuthMiddleware` パターンを追記。
+
+---
+
+### FP35-3: TokenVerifierProtocol の再利用性が高い（好印象）
+
+**分類**: 良い設計の確認
+
+`LocalTokenVerifier` はそのままカスタムミドルウェア内で使えるため、
+トークン比較ロジック（`secrets.compare_digest`）を重複実装する必要がない。
+Protocol 分離の設計が効いている。
+
+---
+
+## フレームワーク変更
+
+- `docs/how-to/configure-auth.md` に「AND / OR の違い」と `EitherOrAuthMiddleware` パターンを追記 (FP35-1, FP35-2 対応)
+
+---
+
+## 関連
+
+- `nene2.auth.BearerTokenMiddleware`
+- `nene2.auth.ApiKeyAuthMiddleware`
+- `nene2.auth.LocalTokenVerifier`
+- FT11 (exclude_paths, LocalTokenVerifier.from_env, v1.4.0)

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-36.md

@@ -0,0 +1,92 @@
+# Field Trial 36: CompositeHealthCheck 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.3 時点
+**テーマ**: `CompositeHealthCheck` で複数の依存サービス（DB・外部 API・キャッシュ）の健全性を集約し、`HealthStatus.http_status_code` を使って `/health` エンドポイントを実装するパターン。および非同期ヘルスチェックのギャップを発見・修正。
+
+---
+
+## 概要
+
+SQLite DB・外部 API（モック）・キャッシュ（モック）の 3 つの依存を `CompositeHealthCheck` で集約し、
+部分障害時に個別のチェック名と全体 `"error"` ステータスを返すパターンを検証した。
+
+主な発見: 非同期チェックに対応するプロトコルとクラスがなく、外部 HTTP API を非同期で確認するヘルスチェックが書けない摩擦を発見。`AsyncHealthCheckProtocol` と `AsyncCompositeHealthCheck` を追加して対応。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft36-composite-health/` に以下を作成:
+
+- **`app.py`** — DB / 外部 API / キャッシュの 3 チェックを集約した `/health` エンドポイント
+- **`test_app.py`** — 全正常・DB 障害・部分障害・各チェック名の確認 (5 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP36-1: 非同期ヘルスチェックに対応するプロトコルがない
+
+**分類**: 摩擦あり → **実装で対応**
+
+`HealthCheckProtocol.check()` は同期のみ。外部 HTTP API への非同期 `httpx.AsyncClient` 呼び出しや
+非同期 DB クライアントを使うヘルスチェックを書けない。
+
+**対応**: `AsyncHealthCheckProtocol` と `AsyncCompositeHealthCheck` を `nene2.http` に追加 (#254)。
+`asyncio.gather` で全チェックを並列実行するため、レスポンスタイムも最適化される。
+
+```python
+class AsyncApiHealthCheck:
+    async def check(self) -> HealthStatus:
+        async with httpx.AsyncClient() as client:
+            r = await client.get("https://api.example.com/health")
+        status = "ok" if r.status_code == 200 else "error"
+        return HealthStatus(status=status, checks={"external_api": status})
+
+composite = AsyncCompositeHealthCheck([db_check, AsyncApiHealthCheck()])
+```
+
+---
+
+### FP36-2: チェックの名前を集約時に指定できない
+
+**分類**: 設計通り（摩擦なし）
+
+チェックの名前は `HealthStatus.checks` の dict キーで決まる（チェック実装側が定義する）。
+集約側での名前 override はできない。
+
+**判断**: チェック実装がその名前を知っているべきという責務分離の観点で正しい設計。
+集約側での名前指定を可能にすると DRY 違反になりやすい。
+
+---
+
+### FP36-3: 同名キーを持つチェックが複数あると後勝ちになる
+
+**分類**: 軽微な摩擦（ドキュメント対応）
+
+2 つのチェックが同じキーを `checks` に返した場合、`dict.update()` で後のチェックが勝つ。
+衝突検出の仕組みはない。
+
+**判断**: 各チェックがユニークな名前を使う規約で対応。
+
+---
+
+## フレームワーク変更
+
+- `nene2.http.AsyncHealthCheckProtocol` — `async def check() -> HealthStatus` の Protocol を追加 (FP36-1)
+- `nene2.http.AsyncCompositeHealthCheck` — 並列実行の集約クラスを追加 (FP36-1)
+- テスト 6 件追加
+
+---
+
+## 関連
+
+- `nene2.http.CompositeHealthCheck`
+- `nene2.http.HealthStatus`
+- FT22 (CompositeHealthCheck 実装, v1.8.0)
+- FT31 (HealthStatus.http_status_code, v1.8.3)
+- Issue #254

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-37.md

@@ -0,0 +1,77 @@
+# Field Trial 37: PaginationResponse + PaginationQueryParser 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: `PaginationQueryParser` の `Depends()` パターンと `PaginationResponse.to_dict()` を使ったページネーションパイプラインの実運用確認
+
+---
+
+## 概要
+
+50 件の `Product` データを `PaginationQueryParser` で limit/offset 制御し、
+`PaginationResponse.to_dict()` で slotted dataclass を自動シリアライズして `JSONResponse` に変換するパイプラインを検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft37-pagination/` に以下を作成:
+
+- **`app.py`** — `Annotated[PaginationQueryParser, Depends()]` パターンの `/api/products` エンドポイント
+- **`test_app.py`** — デフォルト・カスタム・最終ページ・無効値・Depends 動作確認 (9 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (4 件)
+
+**テスト結果**: 13 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP37-1: `Annotated[PaginationQueryParser, Depends()]` と書く必要がある
+
+**分類**: 軽微な摩擦（FastAPI 標準パターン）
+
+`def list(pagination: PaginationQueryParser = Depends())` ではなく
+`def list(pagination: Annotated[PaginationQueryParser, Depends()])` が推奨パターン。
+FastAPI の仕様に従っているが、初見では迷いやすい。
+
+**判断**: `docs/how-to/validation.md` および新規作成する how-to への記載で対応。
+
+---
+
+### FP37-2: `to_dict()` は dataclass のみ自動シリアライズ
+
+**分類**: 既知の制約（軽微）
+
+`PaginationResponse.to_dict()` は `dataclasses.is_dataclass()` で判定する。
+Pydantic モデルの items は `.model_dump()` を個別に呼ぶ必要がある。
+通常の dict はそのまま通過する。
+
+**判断**: dataclass 向け最適化という設計意図通り。
+Pydantic モデルとの混在ユースケースは how-to ドキュメントに記載する。
+
+---
+
+### FP37-3: `total` 省略時に `"total"` キーが消える（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+`PaginationResponse(items=[], limit=10, offset=0)` のように `total` を渡さないと
+`to_dict()` の結果に `"total"` キーが含まれない。
+`total=None` を明示しても同じ結果。
+
+**判断**: 全件数を取得しない効率的なページネーションをサポートする意図通り。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.http.PaginationQueryParser`
+- `nene2.http.PaginationResponse`
+- FT10 (PaginationResponse.to_dict() スロット対応, v1.3.0)

nene2_python-1.8.5/docs/field-trials/2026-05-field-trial-38.md

@@ -0,0 +1,85 @@
+# Field Trial 38: SqlAlchemyTransactionManager.transactional() 実運用検証
+
+**日付**: 2026-05-20
+**バージョン**: v1.8.4 時点
+**テーマ**: 注文作成（在庫更新 + 注文レコード作成）をトランザクションで包み、途中での例外発生時のロールバック動作を確認する
+
+---
+
+## 概要
+
+`SqlAlchemyTransactionManager.transactional(callback)` を使って複数の DB 書き込みを一つのトランザクションに包み、途中で例外が発生した場合のロールバック動作を検証した。
+
+---
+
+## 実装内容
+
+`/home/xi/docker/nene2-python-FT/ft38-transactions/` に以下を作成:
+
+- **`app.py`** — 在庫チェック + 在庫減少 + 注文作成を `transactional()` で包んだ注文 API
+- **`test_app.py`** — 正常注文・在庫不足・ロールバック確認・連続注文 (6 件)
+- **`test_friction.py`** — 摩擦点の確認テスト (3 件)
+
+**テスト結果**: 9 件全通過 ✅
+
+---
+
+## 摩擦点
+
+### FP38-1: コールバック内で型アノテーションに `DatabaseQueryExecutorInterface` が必要
+
+**分類**: 軽微な摩擦（mypy --strict 使用時）
+
+```python
+def _do_create(db: object) -> int:
+    ...
+```
+
+`db` を `object` 型にするとメソッド呼び出しに mypy エラーが出る。
+`DatabaseQueryExecutorInterface` をインポートして型アノテーションする必要がある。
+
+**判断**: mypy --strict の設計上当然の制約。インポートはやや冗長だが許容範囲。
+`db: DatabaseQueryExecutorInterface` が推奨パターンとしてドキュメントに記載されている。
+
+---
+
+### FP38-2: savepoint（ネストトランザクション）はサポートしない
+
+**分類**: 既知の制約（設計通り）
+
+`DatabaseQueryExecutorInterface` が持つのは `fetch_all` / `fetch_one` / `write` のみ。
+SQLAlchemy の savepoint 機能（`SAVEPOINT` / `ROLLBACK TO SAVEPOINT`）は使えない。
+
+**判断**: フレームワークの抽象化レイヤーが Pure SQL テキストベースの設計を採用しているため、
+ORM/Connection 固有の高度な機能は意図的に除外されている。
+savepoint が必要な場合は SQLAlchemy を直接使う Repository を実装するのが正しいパターン。
+
+---
+
+### FP38-3: トランザクション途中の例外はすべてロールバックされる（設計通り）
+
+**分類**: 設計通り（摩擦なし）
+
+```python
+def _callback(db: DatabaseQueryExecutorInterface) -> None:
+    db.write("INSERT ...")  # ← この変更も
+    raise ValueError("oops")  # ← ここで例外 → 全部ロールバック
+```
+
+例外の種類に関わらず（`DatabaseIntegrityException` 以外でも）全変更がロールバックされる。
+これは `SqlAlchemyTransactionManager.transactional()` の期待される動作。
+
+---
+
+## フレームワーク変更
+
+なし（全て設計通りの挙動）
+
+---
+
+## 関連
+
+- `nene2.database.SqlAlchemyTransactionManager`
+- `nene2.database.DatabaseQueryExecutorInterface`
+- FT16 (DatabaseIntegrityException, v1.7.0)
+- FT34 (DatabaseIntegrityException 実運用, v1.8.3)