swbt-python 0.5.1__tar.gz → 0.5.3__tar.gz

{swbt_python-0.5.1 → swbt_python-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swbt-python
-Version: 0.5.1
+Version: 0.5.3
 Summary: Python library for presenting an NX-compatible virtual Bluetooth HID input device.
 Keywords: bluetooth,bluetooth-hid,controller,gamepad,hid,nx
 Author: niart120
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
-Requires-Dist: bumble>=0.0.230,<0.0.231
+Requires-Dist: bumble==0.0.233
 Maintainer: niart120
 Maintainer-email: niart120 <38847256+niart120@users.noreply.github.com>
 Requires-Python: >=3.12
@@ -60,7 +60,9 @@ uv sync --dev
 同じ内容は `docs/` 配下でも確認できます。
 
 ## 利用例
+
 ### Pro Controller
+
 ```python
 import asyncio
 from swbt import Button, ProController
@@ -79,7 +81,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Pro Controller 相当の一時的な仮想デバイスを作成し、ペアリング後に A ボタン入力を送信するコードの例です。接続情報を永続化する場合は `ProController.create_profile()` を使います。`local_address` を省略するとアダプタが現在報告する Bluetooth アドレスを維持し、揮発領域へ書き込みません。利用者管理のローカルアドレスへ切り替える手順は[利用例](docs/usage.md)、対応する専用 USB Bluetooth ドングルと復旧手順は[実機準備手順](docs/hardware.md)を参照してください。
+Pro Controller 相当の仮想デバイスを作成し、ペアリング後に A ボタン入力を送信する例です。
+
+接続情報を保存して再利用する場合は、先に `ProController.create_profile()` で `profile_path` を作成します。アドレスの選択方法と復旧手順は[利用例](docs/usage.md)、専用 USB Bluetooth ドングルの準備は[実機準備手順](docs/hardware.md)を参照してください。
 
 ### Joy-Con L/R
 
@@ -104,9 +108,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-「持ちかた/順番を変える」画面で Joy-Con としてペアリングする場合も、接続後に登録用の SR+SL 入力を追加送信する必要はありません。ライブラリは Joy-Con 用の初期化応答を返し、0 以外のプレイヤーライトが設定されるまで `connect()` を完了しません。Joy-Con L/R の `Button.SL` と `Button.SR` は、接続後に利用者が送る通常のボタン入力として引き続き利用できます。
+「持ちかた/順番を変える」画面でペアリングするときも、登録用の SR+SL 入力を追加送信する必要はありません。`connect()` は Joy-Con 用の初期化とプレイヤーライトの設定が完了してから戻ります。
 
-Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetooth アドレスの選択方法とペアリングキーをまとめる `profile_path` を使います。新規プロファイルは各具象クラスの `create_profile()` で作成し、コントローラー形状と対象機器ごとに保存先を分けてください。v0.4.0 の `key_store_path` で使用していた JSON 形式のペアリング情報との互換経路はありません。Joy-Con L で右スティックや A/B/X/Y、Joy-Con R で左スティックや十字キーを入力すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
+`profile_path` はコントローラー形状と対象機器ごとに分けます。Joy-Con L では右スティックと A/B/X/Y、Joy-Con R では左スティックと十字キーを使えません。これらを指定すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
 
 ## 接続方法
 
@@ -116,15 +120,11 @@ Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetoo
 
 ### 確認済み構成
 
-2026-07-24 時点では、Windows 11 / CSR8510 A10 / WinUSB / `usb:0` で、Pro Controller、Joy-Con L、Joy-Con R の初回ペアリング、保存済みプロファイルを使う再接続、初期化完了後のオブジェクト返却を確認済みです。Joy-Con L/R は、登録用の SR+SL 入力を追加送信せずに初期化を完了しました。
-
-同じ Windows 構成で、Pro Controller の主要なボタン / スティック入力、ニュートラル復帰と、Joy-Con L/R の対応ボタン / スティック入力も確認しています。確認済み範囲と未確認範囲の詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
-
-macOS 15.7.7 / CSR8510 A10 では、Pro Controller のペアリング、保存済みペアリング情報を使う再接続、ボタン入力、ニュートラル復帰を記録しています。
+Windows 11 / CSR8510 A10 / WinUSB では、Pro Controller、Joy-Con L、Joy-Con R のペアリング、再接続、対応する入力操作を確認しています。macOS 15.7.7 / CSR8510 A10 では Pro Controller の限定的な動作を確認しています。条件と未確認範囲は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)を参照してください。
 
 ### 実験的構成
 
-Linux は experimental です。手順は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)に整備されていますが、専用 USB Bluetooth ドングルにアクセスできるか、ペアリングできるか、入力が反映されるかは未確認です。macOS は Pro Controller の一部挙動のみ検証済みです。Joy-Con、別ドングル、別ファームウェアでの互換性は未確認です。
+Linux は experimental です。専用 USB Bluetooth ドングルへのアクセス、ペアリング、入力反映は未確認です。macOS の Joy-Con、別ドングル、別ファームウェアでの互換性も未確認です。
 
 ## 開発
 

{swbt_python-0.5.1 → swbt_python-0.5.3}/README.md

@@ -34,7 +34,9 @@ uv sync --dev
 同じ内容は `docs/` 配下でも確認できます。
 
 ## 利用例
+
 ### Pro Controller
+
 ```python
 import asyncio
 from swbt import Button, ProController
@@ -53,7 +55,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-Pro Controller 相当の一時的な仮想デバイスを作成し、ペアリング後に A ボタン入力を送信するコードの例です。接続情報を永続化する場合は `ProController.create_profile()` を使います。`local_address` を省略するとアダプタが現在報告する Bluetooth アドレスを維持し、揮発領域へ書き込みません。利用者管理のローカルアドレスへ切り替える手順は[利用例](docs/usage.md)、対応する専用 USB Bluetooth ドングルと復旧手順は[実機準備手順](docs/hardware.md)を参照してください。
+Pro Controller 相当の仮想デバイスを作成し、ペアリング後に A ボタン入力を送信する例です。
+
+接続情報を保存して再利用する場合は、先に `ProController.create_profile()` で `profile_path` を作成します。アドレスの選択方法と復旧手順は[利用例](docs/usage.md)、専用 USB Bluetooth ドングルの準備は[実機準備手順](docs/hardware.md)を参照してください。
 
 ### Joy-Con L/R
 
@@ -78,9 +82,9 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-「持ちかた/順番を変える」画面で Joy-Con としてペアリングする場合も、接続後に登録用の SR+SL 入力を追加送信する必要はありません。ライブラリは Joy-Con 用の初期化応答を返し、0 以外のプレイヤーライトが設定されるまで `connect()` を完了しません。Joy-Con L/R の `Button.SL` と `Button.SR` は、接続後に利用者が送る通常のボタン入力として引き続き利用できます。
+「持ちかた/順番を変える」画面でペアリングするときも、登録用の SR+SL 入力を追加送信する必要はありません。`connect()` は Joy-Con 用の初期化とプレイヤーライトの設定が完了してから戻ります。
 
-Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetooth アドレスの選択方法とペアリングキーをまとめる `profile_path` を使います。新規プロファイルは各具象クラスの `create_profile()` で作成し、コントローラー形状と対象機器ごとに保存先を分けてください。v0.4.0 の `key_store_path` で使用していた JSON 形式のペアリング情報との互換経路はありません。Joy-Con L で右スティックや A/B/X/Y、Joy-Con R で左スティックや十字キーを入力すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
+`profile_path` はコントローラー形状と対象機器ごとに分けます。Joy-Con L では右スティックと A/B/X/Y、Joy-Con R では左スティックと十字キーを使えません。これらを指定すると `UnsupportedInputError` が送出されます。`JoyConPair` は未実装です。
 
 ## 接続方法
 
@@ -90,15 +94,11 @@ Pro Controller、周期送信型 Joy-Con、直接送信型はすべて、Bluetoo
 
 ### 確認済み構成
 
-2026-07-24 時点では、Windows 11 / CSR8510 A10 / WinUSB / `usb:0` で、Pro Controller、Joy-Con L、Joy-Con R の初回ペアリング、保存済みプロファイルを使う再接続、初期化完了後のオブジェクト返却を確認済みです。Joy-Con L/R は、登録用の SR+SL 入力を追加送信せずに初期化を完了しました。
-
-同じ Windows 構成で、Pro Controller の主要なボタン / スティック入力、ニュートラル復帰と、Joy-Con L/R の対応ボタン / スティック入力も確認しています。確認済み範囲と未確認範囲の詳細は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)にあります。
-
-macOS 15.7.7 / CSR8510 A10 では、Pro Controller のペアリング、保存済みペアリング情報を使う再接続、ボタン入力、ニュートラル復帰を記録しています。
+Windows 11 / CSR8510 A10 / WinUSB では、Pro Controller、Joy-Con L、Joy-Con R のペアリング、再接続、対応する入力操作を確認しています。macOS 15.7.7 / CSR8510 A10 では Pro Controller の限定的な動作を確認しています。条件と未確認範囲は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)を参照してください。
 
 ### 実験的構成
 
-Linux は experimental です。手順は[実機準備手順](https://niart120.github.io/swbt-python/hardware/)に整備されていますが、専用 USB Bluetooth ドングルにアクセスできるか、ペアリングできるか、入力が反映されるかは未確認です。macOS は Pro Controller の一部挙動のみ検証済みです。Joy-Con、別ドングル、別ファームウェアでの互換性は未確認です。
+Linux は experimental です。専用 USB Bluetooth ドングルへのアクセス、ペアリング、入力反映は未確認です。macOS の Joy-Con、別ドングル、別ファームウェアでの互換性も未確認です。
 
 ## 開発
 

{swbt_python-0.5.1 → swbt_python-0.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "swbt-python"
-version = "0.5.1"
+version = "0.5.3"
 description = "Python library for presenting an NX-compatible virtual Bluetooth HID input device."
 readme = "README.md"
 authors = [
@@ -34,7 +34,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "bumble>=0.0.230,<0.0.231",
+    "bumble==0.0.233",
 ]
 
 [project.scripts]

{swbt_python-0.5.1/spec/wip → swbt_python-0.5.3/spec/complete}/unit_056/PAIRING_PROFILE_NAMING.md

@@ -61,16 +61,16 @@
 
 | status | item | type | layer | hardware | notes |
 |---|---|---|---|---|---|
-| implemented / smoke passed | `local_address` で作成した profile が従来の JSON payload を保存・読み込みできる | regression | unit | no | system Python の smoke test で確認。pytest は環境遮断 |
-| implemented / blocked | adapter identity 準備失敗が新しい例外型で復旧を要求する | regression | unit | no | adapter は開かない fake session。pytest は環境遮断 |
-| implemented / blocked | concrete controller が `local_address` で profile を作成して再利用できる | regression | integration | no | fake transport。pytest は環境遮断 |
+| green | `local_address` で作成した profile が従来の JSON payload を保存・読み込みできる | regression | unit | no | 現行 unit test と CI で確認 |
+| green | adapter identity 準備失敗が新しい例外型で復旧を要求する | regression | unit | no | adapterを開かない fake sessionで確認 |
+| green | concrete controller が `local_address` で profile を作成して再利用できる | regression | integration | no | fake transport integrationで確認 |
 
 ## 8. 文書検証計画
 
 | document | audience / task | source of truth | mechanical check | review result | unresolved |
 |---|---|---|---|---|---|
-| API / usage / hardware docs | profile の作成と再利用 | 本仕様 §6、実装 | `uv run mkdocs build --strict` | manual pass / build blocked | `uv` cache が read-only |
-| release notes / agent brief | 例外名と用語 | 本仕様 §6、実装 | link / build | manual pass / build blocked | `uv` cache が read-only |
+| API / usage / hardware docs | profile の作成と再利用 | 本仕様 §6、実装 | `uv run --group docs mkdocs build --strict` | done | none |
+| release notes / agent brief | 例外名と用語 | 本仕様 §6、実装 | link / diff review | done | none |
 
 ## 9. 設計メモ
 
@@ -97,10 +97,10 @@
 | GitHub Actions CI #142 | passed | 新規 shape-only 値の保存と `direct_*` の未対応扱いを含む unit / integration test |
 | `ruff 0.15.20 format --check .` | passed | CI と同じ Ruff version を一時領域で実行 |
 | `ruff 0.15.20 check .` | passed | CI と同じ Ruff version を一時領域で実行 |
-| `uv run ty check --no-progress` | blocked | 同上 |
-| `uv run pytest tests/unit` | blocked | 同上。Bumble を含む依存が未導入 |
-| `uv run pytest tests/integration` | blocked | 同上 |
-| `uv run mkdocs build --strict` | blocked | 同上 |
+| `uv run ty check --no-progress` | pass | current mainでAll checks passed |
+| `uv run pytest tests/unit` | pass | current mainで439 passed |
+| `uv run pytest tests/integration` | pass | current mainで154 passed |
+| `uv run --group docs mkdocs build --strict` | pass | current mainでstrict build成功 |
 
 ## 12. 実機実行条件
 
@@ -115,7 +115,7 @@
 
 ## 13. 先送り事項
 
-- ReportingMode 分類の削除は unit_057 で扱う。
+- none（ReportingMode 分類の削除は unit_057 で完了）
 
 ## 14. チェックリスト
 

{swbt_python-0.5.1/spec/wip → swbt_python-0.5.3/spec/complete}/unit_057/PAIRING_PROFILE_CONTROLLER_KIND.md

@@ -64,17 +64,17 @@ pairing profile の `controller_kind` から、入力レポートの送信方式
 
 | status | item | type | layer | hardware | notes |
 |---|---|---|---|---|---|
-| implemented / CI passed | 新規 profile が ReportingMode を含まない controller shape を保存する | regression | unit | no | 新規保存は `pro` / `joycon_l` / `joycon_r`。GitHub Actions CI #142 で確認 |
-| implemented / CI passed | 旧 direct kind を持つ JSON が未対応値として adapter open 前に失敗する | regression | unit | no | `direct_*` を特別扱いせず、既存の `controller_kind` 検証で拒否。GitHub Actions CI #142 で確認 |
-| implemented / local passed | 同じ controller shape の periodic / direct が profile を相互利用できる | regression | unit | no | Direct controller の `open()` が profile path と local address を fake transport factory へ渡すことを確認 |
-| implemented / CI passed | controller shape が異なる profile は adapter open 前に拒否される | regression | unit | no | `ControllerKind` 比較の guard を GitHub Actions CI #142 で確認 |
+| green | 新規 profile が ReportingMode を含まない controller shape を保存する | regression | unit | no | 新規保存は `pro` / `joycon_l` / `joycon_r`。CIと現行unitで確認 |
+| green | 旧 direct kind を持つ JSON が未対応値として adapter open 前に失敗する | regression | unit | no | `direct_*` を特別扱いせず、既存の `controller_kind` 検証で拒否 |
+| green | 同じ controller shape の periodic / direct が profile を相互利用できる | regression | unit | no | fake transport regression 3 passed |
+| green | controller shape が異なる profile は adapter open 前に拒否される | regression | unit | no | `ControllerKind`比較のguardを確認 |
 | deferred | Direct / Periodic 間 profile 再利用の実機 pairing / reconnect | characterization | hardware | yes | 明示承認と専用 adapter が必要 |
 
 ## 8. 文書検証計画
 
 | document | audience / task | source of truth | mechanical check | review result | unresolved |
 |---|---|---|---|---|---|
-| API / usage / hardware docs | プロファイルの再利用範囲 | 本仕様 §6、実装、対象 test | `uv run --with mkdocs mkdocs build --strict` | 2026-07-21 の docs-quality-review と strict build が pass | 実機共有は未検証 |
+| API / usage / hardware docs | プロファイルの再利用範囲 | 本仕様 §6、実装、対象 test | `uv run --group docs mkdocs build --strict` | done | Direct / Periodicの実機共有はdeferred |
 
 ## 9. 設計メモ
 
@@ -88,7 +88,7 @@ pairing profile の `controller_kind` から、入力レポートの送信方式
 |---|---|---|
 | `src/swbt/transport/_pairing_profile.py` | modify | `ControllerKind` 化と shape-only の値だけの受理 |
 | `src/swbt/gamepad/_config.py` | modify | profile kind config の削除 |
-| `src/swbt/gamepad/core.py` | modify | direct / periodic 共通の shape 利用 |
+| `src/swbt/gamepad/controllers.py` | modify | direct / periodic 共通の shape 利用 |
 | `src/swbt/gamepad/runtime.py` | modify | protocol profile の kind による guard |
 | `tests/` | modify | legacy / cross-mode / mismatch 回帰 |
 | `docs/`, `spec/initial/` | modify | profile 共有範囲の説明 |
@@ -102,10 +102,10 @@ pairing profile の `controller_kind` から、入力レポートの送信方式
 | GitHub Actions CI #142 | passed | 新規 shape-only 値の保存と `direct_*` の未対応扱いを含む unit / integration test |
 | `ruff 0.15.20 format --check .` | passed | CI と同じ Ruff version を一時領域で実行 |
 | `ruff 0.15.20 check .` | passed | CI と同じ Ruff version を一時領域で実行 |
-| `uv run ty check --no-progress` | blocked | 同上 |
-| `uv run pytest tests/unit` | blocked | 同上。Bumble を含む依存が未導入 |
-| `uv run pytest tests/integration` | blocked | 同上 |
-| `uv run mkdocs build --strict` | blocked | 同上 |
+| `uv run ty check --no-progress` | pass | current mainでAll checks passed |
+| `uv run pytest tests/unit` | pass | current mainで439 passed |
+| `uv run pytest tests/integration` | pass | current mainで154 passed |
+| `uv run --group docs mkdocs build --strict` | pass | current mainでstrict build成功 |
 | `uv run pytest tests/unit/test_pairing_profile_runtime.py::test_direct_controller_reuses_profile_for_the_same_controller_shape -q` | passed | 3 passed。P2 review finding の fake transport regression |
 | `uv run --with mkdocs mkdocs build --strict` | passed | 2026-07-21。公開 docs の strict build |
 
@@ -113,16 +113,16 @@ pairing profile の `controller_kind` から、入力レポートの送信方式
 
 | 項目 | 内容 |
 |---|---|
-| 実機要否 | required for deferred characterization |
-| 承認範囲 | dedicated adapter open、target Switch pairing、active reconnect、normal close |
-| adapter | 実行直前に確認する専用 adapter |
+| 実機要否 | not required for this unit（deferred characterization only） |
+| 承認範囲 | この完了ではなし。将来実行する場合は明示承認を取得する |
+| adapter | この完了では該当なし |
 | 実行遮断 | 環境変数による実行遮断は採用しない。明示承認、対象 adapter、command、cleanup plan で管理する |
-| log / artifact | `spec/hardware-test-log.md` に環境、command、result、cleanup を記録する |
-| cleanup | normal close 後に dedicated adapter を切り離す |
+| log / artifact | この完了では新規記録なし。将来実行時は `spec/hardware-test-log.md` に記録する |
+| cleanup | この完了では該当なし |
 
 ## 13. 先送り事項
 
-- Direct / Periodic 間での実機 pairing / reconnect は hardware characterization として別途実行する。
+- Direct / Periodic 間での実機 pairing / reconnect は、今回のprofile shape分離の完了条件に含めない。fake transportで公開契約を確認済みであり、実機再検証の追加価値は低いため、release gateで必要になった場合だけ専用hardware runとして扱う。
 
 ## 14. チェックリスト
 

swbt_python-0.5.3/spec/complete/unit_070/DIAGNOSTICS_AND_UNUSED_PATHS_CLEANUP.md

@@ -0,0 +1,174 @@
+# 診断履歴と未使用経路の削除 仕様書
+
+## 1. 概要
+
+### 1.1 目的
+
+公開 API、HID report、送信順序を変えずに、無制限に増える診断 event 履歴と本番から使われない内部経路を削除する。
+
+### 1.2 起点 / source
+
+| source | 内容 | path |
+|---|---|---|
+| GitHub Issue | 診断履歴、test-only reply queue、状態更新 helper、未使用 control 送信経路の削除 | `https://github.com/niart120/swbt-python/issues/115` |
+| 親 Issue | 観測可能な公開挙動を維持した内部境界の整理 | `https://github.com/niart120/swbt-python/issues/114` |
+| 初期設計 | sender、report loop、transport、diagnostics の責務 | `spec/initial/architecture.md` |
+| 初期設計 | output report と subcommand reply の送信経路 | `spec/initial/protocol.md` |
+| 初期設計 | transport interface と Bumble 実装境界 | `spec/initial/transport-bumble.md` |
+
+### 1.3 use case
+
+| actor / boundary | 入力または状態 | 期待する観測結果 | 制約 |
+|---|---|---|---|
+| 長時間動作する gamepad | trace writer なしで周期 `0x30` を送信する | report counter は増えるが、送信回数に比例した event 履歴を保持しない | `GamepadStatus` の集計値は維持する |
+| diagnostics 利用者 | trace writer ありで lifecycle、report、subcommand、error を記録する | 既存 schema の JSON Lines を受け取る | event 名と field を変えない |
+| Switch output report 処理 | subcommand を含む `0x01` を受信する | reply と periodic input が同じ sender lock と timer を使い、reply 後の holdoff が働く | reply bytes と送信順序を変えない |
+| public gamepad API | button、stick、IMU、neutral を更新する | 従来と同じ `InputState` が確定する | `InputStateStore.update()` / `apply()` に集約する |
+| transport 上位層 | host から control channel data を受信する | `on_control_data()` callback が従来どおり呼ばれる | 未使用の device-to-host `send_control()` は削除する |
+
+## 2. 対象範囲
+
+- `DiagnosticsRecorder` の全 event 履歴と `events` property を削除する。
+- report counter、last subcommand ID、last raw rumble、last error を有界な状態として保持する。
+- trace writer への JSON Lines 出力を維持する。
+- 本番 call site がない `record_state_transition()` を削除する。
+- `ReportLoop` の test-only reply queue と専用送信経路を削除する。
+- 実際の `send_subcommand_reply()`、共通 sender lock、timer、reply 後 holdoff を維持する。
+- `InputStateStore` の個別 helper を削除し、production call site を `update()` / `apply()` へ移す。
+- 本番 call site がない `HidDeviceTransport.send_control()` と Fake / Bumble 実装を削除する。
+- `on_control_data()` を維持する。
+- 関連する初期設計とテストを現行経路へ合わせる。
+
+## 3. 対象外
+
+- `GamepadStatus` の公開フィールド変更。
+- public gamepad の `press()`、`release()`、`sticks()`、`imu()`、`neutral()` の変更。
+- input report、output report、subcommand reply、SPI、rumble の byte layout 変更。
+- report period、reply holdoff 時間、timer の進め方の変更。
+- Direct の transport 受理後 commit 条件の変更。
+- Bumble adapter、Switch 実機を使う検証。
+- 親 Issue #114 の他の子 Issue。
+
+## 4. 関連 docs
+
+- `spec/initial/architecture.md`
+- `spec/initial/api.md`
+- `spec/initial/protocol.md`
+- `spec/initial/transport-bumble.md`
+- `spec/initial/lifecycle.md`
+- `spec/initial/testing.md`
+- `spec/initial/roadmap.md`
+
+## 5. 根拠監査
+
+| 項目 | 要否 | 状態 | 根拠 / 理由 |
+|---|---|---|---|
+| Switch HID / report bytes | required | done | `ReportSender.send_subcommand_reply()` と既存 unit / integration test を維持し、report builder、parser、定数、payload は変更しない |
+| Bumble / transport | required | done | `rg` で `send_control()` の production call site は定義以外 0 件。host-to-device の `on_control_data()` は `ControllerRuntime` が登録しているため維持する |
+| OS / driver / adapter | not applicable | not applicable | adapter を開かず、driver や OS 依存挙動を変更しない |
+
+### 5.1 監査結果
+
+| 項目 | 値 / 判断 | 根拠分類 | source | status |
+|---|---|---|---|---|
+| subcommand reply 経路 | `OutputReportDispatcher` から `send_subcommand_reply()` を呼び、`ReportSender` の lock 内で reply を生成・送信する | implementation fact | `src/swbt/gamepad/output.py`, `src/swbt/gamepad/runtime.py`, `src/swbt/report_loop.py` | confirmed |
+| reply と input の直列化 | `0x21` と `0x30` は同じ `ReportSender._send_lock` と timer を使う | implementation fact | `src/swbt/report_loop.py`, `tests/unit/test_report_loop.py` | confirmed |
+| outbound control 送信 | `send_control()` は protocol 定義、Fake、Bumble 実装と test にだけ存在し、本番 call site はない | implementation fact | `rg -n "send_control" src tests` | confirmed |
+| inbound control 受信 | `ControllerRuntime` が `on_control_data()` を登録し、integration test が reply まで確認する | implementation fact | `src/swbt/gamepad/runtime.py`, `tests/integration/test_switch_gamepad_fake_transport.py` | confirmed |
+| protocol bytes | builder、parser、profile、定数を変更しない | implementation fact | 対象差分と既存 unit / integration test | unit 475 件、integration 154 件で確認 |
+
+## 6. 振る舞い仕様
+
+| 振る舞い | 入力・状態 | 期待結果 | 備考 |
+|---|---|---|---|
+| diagnostics の有界保持 | trace writer なしで多数の report event を記録 | recorder が通常 event を履歴として保持せず、counter だけが増える | last error 1 件の保持は許容する |
+| status 集計 | report、subcommand、rumble、error を記録 | 従来と同じ counter、last ID、raw bytes、last error を返す | dict / bytes は防御的に返す |
+| trace 出力 | trace writer ありで event を記録 | 既存 event schema の JSON Lines を逐次出力する | flush を維持する |
+| reply 送信 | periodic input と subcommand reply が競合する | 同じ lock と timer で直列化し、reply 後は periodic を holdoff する | test-only queue は使わない |
+| state 更新 | public API から IMU または neutral を更新 | `update()` / `apply()` 経由で従来と同じ state になる | Direct commit 条件は不変 |
+| control channel 受信 | Fake transport へ control data を注入 | output dispatcher を通って `0x21` reply を送る | `on_control_data()` を維持する |
+
+## 7. TDD Test List
+
+| status | item | type | layer | hardware | notes |
+|---|---|---|---|---|---|
+| refactor-done | trace writer なしで report event を繰り返しても過去 event object を保持せず、counter は正しく増える | regression | unit | no | `_events` 保持による red 後に有界集計へ変更して green |
+| refactor-done | trace writer が既存 schema を維持し、last error を含む集計値を返す | characterization | unit / integration | no | `events` property の検査を trace または集計値へ置換 |
+| refactor-done | subcommand reply と input report が共通 timer / lock を使い、reply 後 holdoff を維持する | characterization | unit / integration | no | 実際の `send_subcommand_reply()` 経路で検証し、reply queue 専用 test を削除 |
+| refactor-done | state store helper 削除後も public IMU / neutral / concurrent state update と Direct commit が維持される | regression | unit / integration | no | `update()` / `apply()` へ集約 |
+| refactor-done | outbound `send_control()` 削除後も inbound control data が subcommand reply へ到達する | regression | integration | no | Bumble adapter を開かず fake transport で確認 |
+
+## 8. 文書検証計画
+
+公開文書は変更しない。`spec/initial` と本作業仕様は、実装の call graph、検索結果、unit / integration test と照合する。
+
+## 9. 設計メモ
+
+- diagnostics event は trace writer へ同期出力した後に破棄する。`last_error` だけは `GamepadStatus` のため 1 件保持する。
+- reply は queue へ積まず、output report callback から共有 sender へ直接渡す。共有 lock 内で reply を構築するため、session state 変更と ACK の順序を維持できる。
+- Periodic holdoff は `ReportLoop.send_subcommand_reply()` の完了後に設定する。
+- `InputStateStore` は complete state の `apply()` と atomic read-modify-write の `update()` に絞る。
+- HID control channel は host-to-device 受信に必要である。device-to-host の未使用送信 method を削除しても control channel 自体は削除しない。
+
+## 10. 対象ファイル
+
+| path | change | 内容 |
+|---|---|---|
+| `src/swbt/diagnostics.py` | modify | event 履歴、`events`、未使用 transition helper を削除 |
+| `src/swbt/report_loop.py` | modify | reply queue と既成 reply 送信経路を削除 |
+| `src/swbt/state_store.py` | modify | 個別 state helper を削除 |
+| `src/swbt/gamepad/runtime.py` | modify | IMU / neutral 更新を `update()` / `apply()` へ移行 |
+| `src/swbt/gamepad/output.py` | modify | reply 経路の説明を現行実装へ合わせる |
+| `src/swbt/transport/base.py` | modify | `send_control()` を protocol から削除 |
+| `src/swbt/transport/fake.py` | modify | outbound control report の保持と送信を削除 |
+| `src/swbt/transport/bumble.py` | modify | outbound control 送信実装を削除 |
+| `tests/unit/test_diagnostics.py` | modify | 無制限保持と集計値を検証 |
+| `tests/unit/test_report_loop.py` | modify | 実際の reply 経路で timer / holdoff を検証 |
+| `tests/unit/test_bumble_transport.py` | modify | `events` / `send_control()` 専用検査を trace / interrupt 検査へ置換 |
+| `tests/unit/test_public_api_boundary.py` | modify | test transport から未使用 method を削除 |
+| `tests/integration/test_switch_gamepad_fake_transport.py` | modify | reply queue 用語を実際の送信順序へ置換 |
+| `spec/initial/protocol.md` | modify | direct reply + shared sender 経路へ更新 |
+| `spec/initial/transport-bumble.md` | modify | outbound control method を interface から削除 |
+| `spec/initial/roadmap.md` | modify | M1 の完了表現を現行 reply 経路へ更新 |
+
+## 11. 検証
+
+| command | result | notes |
+|---|---|---|
+| `uv run pytest tests/unit/test_diagnostics.py::test_report_events_are_not_retained_without_a_trace_writer -q` | red | `_events` が最初の `report_tx` event を保持して `1 failed` |
+| 同上 | pass | 履歴削除後に `1 passed` |
+| `uv run pytest tests/unit/test_diagnostics.py tests/unit/test_report_loop.py::test_imu_mode_transition_and_ack_share_periodic_send_lock ... -q` | pass | 変更前 characterization と診断変更後の対象検査 `10 passed` |
+| `uv run pytest tests/unit/test_report_loop.py tests/integration/test_switch_gamepad_fake_transport.py::test_subcommand_reply_precedes_the_next_periodic_input tests/integration/test_switch_gamepad_fake_transport.py::test_imu_mode_ack_precedes_first_periodic_input_in_the_new_format -q` | pass | queue 削除後の timer / lock / holdoff `10 passed` |
+| state store 対象 integration 4 件 | pass | IMU、neutral、disconnect、Direct commit を変更前後とも `4 passed` |
+| `uv run pytest tests/unit/test_bumble_transport.py::test_bumble_interrupt_send_fails_until_l2cap_channel_is_connected tests/integration/test_switch_gamepad_fake_transport.py::test_control_output_report_injection_sends_subcommand_reply -q` | pass | outbound method 削除と inbound control 維持 `2 passed` |
+| `uv sync --dev` | pass | `Resolved 53 packages` |
+| `uv run ruff format --check .` | pass | `100 files already formatted` |
+| `uv run ruff check .` | pass | `All checks passed!` |
+| `uv run ty check --no-progress` | pass | `All checks passed!` |
+| `uv run pytest tests/unit` | pass | `475 passed in 2.23s` |
+| `uv run pytest tests/integration` | pass | `154 passed in 8.27s` |
+| `git diff --check` | pass | whitespace error なし |
+| `uv run mkdocs build --strict` | not run | `mkdocs` が project の開発依存に含まれず program not found。Issue #115 の指定 gate ではないため依存を追加せず、正本との手動照合を実施 |
+
+## 12. 実機実行条件
+
+| 項目 | 内容 |
+|---|---|
+| 実機要否 | not required |
+| 承認範囲 | adapter / Switch-facing command を実行しない |
+| adapter | none |
+| 実行遮断 | 環境変数による遮断は採用しない。`bumble` / `hardware` marker を実行対象から除外する |
+| log / artifact | local unit / integration test output |
+| cleanup | none |
+
+## 13. 先送り事項
+
+- none
+
+## 14. チェックリスト
+
+- [x] 対象範囲と対象外を確認した
+- [x] TDD Test List または文書検証計画を更新した
+- [x] 必要な根拠監査を記録した
+- [x] 実機実行条件を記録した
+- [x] 検証結果または未実行理由を記録した

swbt_python-0.5.3/spec/complete/unit_071/CONTROLLER_CONSTRUCTION_PATH.md

@@ -0,0 +1,174 @@
+# Controller 構築経路一本化 仕様書
+
+## 1. 概要
+
+### 1.1 目的
+
+公開 controller から `ControllerRuntime` と transport を構築する内部経路を1本にし、値のコピーだけを行う設定型、factory object、constructor 回避、production package 内の test-only factory を削除する。公開 constructor と観測可能な runtime 挙動は変えない。
+
+### 1.2 起点 / source
+
+| source | 内容 | path |
+|---|---|---|
+| GitHub Issue | controller 構築経路、設定型、runtime constructor、transport 生成、test injection の一本化 | `https://github.com/niart120/swbt-python/issues/116` |
+| 親 Issue | 観測可能な公開挙動を維持した不要境界の段階的削除 | `https://github.com/niart120/swbt-python/issues/114` |
+| 依存 Issue | 診断履歴と未使用経路の削除 | `https://github.com/niart120/swbt-python/issues/115` |
+| 初期設計 | public gamepad、runtime、transport の所有関係 | `spec/initial/architecture.md` |
+| 初期設計 | 6 concrete controller の constructor 契約 | `spec/initial/api.md` |
+| 初期設計 | fake transport と import boundary の検証方針 | `spec/initial/testing.md` |
+
+### 1.3 use case
+
+| actor / boundary | 入力または状態 | 期待する観測結果 | 制約 |
+|---|---|---|---|
+| public API 利用者 | 6 concrete controller を既存引数で構築 | constructor 名、parameter、default、例外が変わらない | transport / profile seam を公開しない |
+| runtime | 正規化済み controller 設定と optional injected transport を受け取る | 1個の constructor だけで全内部状態を構築する | `__new__()` 回避を使わない |
+| default transport 利用者 | injected transport なしで controller を open | `create_default_transport()` を直接使う | adapter 必須、Bumble は遅延 import |
+| fake integration test | Fake transport で public controller の lifecycle を検証 | tests 配下の support から公開 constructor 経路を使う | production package に test factory を置かない |
+| pairing profile 利用者 | 異なる controller kind の profile path を渡す | adapter preparation / transport 作成前に mismatch を拒否する | profile schema は変更しない |
+
+## 2. 対象範囲
+
+- `_SwitchGamepadConfig` と `_RuntimeConfig` を、正規化済みの内部設定型1個へ統合する。
+- `_ControllerSpec` を削除し、各 concrete controller が固定 profile を class 属性で直接所有する。
+- profile の `device_name` / `default_report_period_us` と明示値の優先規則を維持する。
+- `controller_colors` の明示上書きと profile default を維持する。
+- `ControllerRuntime.__init__()` へ初期化を集約し、`_init_from_config()` / `from_config()` / `__new__()` 回避を削除する。
+- production から未使用の runtime async context manager を削除する。
+- `_TransportFactory`、`_BumbleTransportFactory`、`_StaticTransportFactory` を削除する。
+- injected transport はその instance を使い、未指定時は `create_default_transport()` を直接呼ぶ。
+- `create_default_transport()` の Bumble 遅延 import を維持する。
+- `src/swbt/_testing/gamepad.py` の6 factory と `_RuntimeBackedGamepad._from_config()` を削除する。
+- fake transport test を tests 配下の support と公開 constructor 経路へ移す。
+- 関連する初期設計とテストを現行構築経路へ更新する。
+
+## 3. 対象外
+
+- `SwitchGamepad` / `PeriodicSwitchGamepad` / `DirectSwitchGamepad` の公開型階層変更。
+- `ConnectionWorkflow` の削除や callback 構成変更。
+- HID report、subcommand、SPI、SDP、pairing profile schema、CSR identity preparation の変更。
+- public constructor への transport / profile 引数追加。
+- dependency injection container、registry、manager の追加。
+- Issue #117 以降の親 Issue 子項目。
+
+## 4. 関連 docs
+
+- `spec/initial/architecture.md`
+- `spec/initial/api.md`
+- `spec/initial/testing.md`
+- `spec/initial/transport-bumble.md`
+- `spec/initial/lifecycle.md`
+- `spec/complete/unit_070/DIAGNOSTICS_AND_UNUSED_PATHS_CLEANUP.md`
+
+## 5. 根拠監査
+
+| 項目 | 要否 | 状態 | 根拠 / 理由 |
+|---|---|---|---|
+| Switch HID / report bytes | not applicable | not applicable | protocol builder、parser、定数、payload を変更しない |
+| Bumble / transport | required | done | factory object を削除するが `create_default_transport()` とその関数内の遅延 import、Bumble constructor 引数は維持する。既存 import boundary test と transport factory test を根拠にする |
+| OS / driver / adapter | not applicable | not applicable | adapter を開かず、driver / identity preparation の意味を変更しない |
+
+### 5.1 監査結果
+
+| 項目 | 値 / 判断 | 根拠分類 | source | status |
+|---|---|---|---|---|
+| public import | `import swbt` は Bumble module を import / resolve しない | implementation fact | `tests/unit/test_public_api_boundary.py` | baseline green |
+| transport factory import | `import swbt.gamepad.transport_factory` は Bumble module を import しない | implementation fact | `tests/unit/test_gamepad_transport_factory.py` | baseline green |
+| default transport | `create_default_transport()` だけが `swbt.transport.bumble` を遅延 import する | implementation fact | `src/swbt/gamepad/transport_factory.py` | 維持 |
+| profile kind mismatch | `PairingProfile.require_controller_kind()` が transport 作成前に拒否する | implementation fact | `src/swbt/gamepad/runtime.py`, `tests/unit/test_pairing_profile_runtime.py` | 維持 |
+| construction result | concrete controller、`_GamepadConfig`、`ControllerRuntime.__init__()`、`create_default_transport()` の順に一本化した | implementation fact | `src/swbt/gamepad/` と unit / integration gate | done |
+
+## 6. 振る舞い仕様
+
+| 振る舞い | 入力・状態 | 期待結果 | 備考 |
+|---|---|---|---|
+| public signature | 6 concrete controller を introspection | parameter 名と default が変更前と一致する | Direct に `report_period_us` を追加しない |
+| adapter validation | default transport で adapter を省略 | `InvalidInputError` を constructor で送出する | injected runtime transport は adapter なしを許す |
+| profile default | device name / report period の明示値なし | concrete profile の default を正規化済み設定へ入れる | profile object の値をコピーするだけの第2設定型は作らない |
+| explicit override | report period / controller colors を指定 | explicit 値を runtime / report builder へ渡す | profile 自体は変更しない |
+| profile kind | profile path の kind が concrete controller と不一致 | adapter preparation / transport creation 前に拒否する | 既存例外型を維持 |
+| default transport | controller open 時に injected transport なし | `create_default_transport()` を直接1回呼ぶ | factory object を生成しない |
+| injected transport | runtime に transport instance を渡す | default transport を作らず、その instance を使用する | tests support から利用 |
+| import boundary | public API または transport factory module を import | Bumble を import / resolve しない | `create_default_transport()` 呼び出し時だけ解決 |
+| resource ownership | public gamepad の `async with` | gamepad が open / close を所有する | runtime 自体は context manager を公開しない |
+
+## 7. TDD Test List
+
+| status | item | type | layer | hardware | notes |
+|---|---|---|---|---|---|
+| done | production package に test-only gamepad factory module が存在しない | regression | unit | no | 削除前の red と削除後の green を確認 |
+| done | 6 concrete controller の signature、型階層、adapter validation が維持される | characterization | unit | no | public API boundary test |
+| done | profile default と明示 report period / controller colors の優先規則が維持される | characterization | unit / integration | no | `_GamepadConfig` と fake transport test |
+| done | profile kind mismatch が transport 作成前に拒否される | characterization | unit | no | pairing profile runtime test |
+| done | injected transport と default transport が同じ runtime constructor を使い、default 側だけ factory 関数を呼ぶ | regression | unit / integration | no | factory object を削除 |
+| done | public import と transport factory import が Bumble を import / resolve しない | characterization | unit | no | subprocess / guarded import |
+| done | fake transport integration が production test factory なしで Periodic / Direct 全経路を維持する | regression | integration | no | tests support は公開 constructor を使用 |
+
+## 8. 文書検証計画
+
+公開 docs site は変更しない。`spec/initial` の内部構築説明と fake transport test 方針を、実装 call graph、import boundary test、constructor signature test と照合する。
+
+## 9. 設計メモ
+
+- 正規化済み設定型は `profile`、adapter / profile path、確定済み device name / report period、optional colors override を保持する。
+- concrete controller は `_profile` class 属性を直接持つ。profile 選択用 wrapper object は置かない。
+- public constructor は `_profile` から設定を作り、`ControllerRuntime(config, ...)` を1回呼ぶ。
+- runtime は optional transport を受け取る。transport が `None` の場合だけ、open 時に `create_default_transport()` を直接呼ぶ。
+- tests 配下の support は public controller constructor を呼ぶ際に runtime constructor を差し替え、Fake transport を注入する。production controller に `_from_config()` を戻さない。
+- `create_default_transport()` は `transport_factory.py` に残し、Bumble import を関数内に閉じ込める。
+
+## 10. 対象ファイル
+
+| path | change | 内容 |
+|---|---|---|
+| `src/swbt/gamepad/_config.py` | modify | 設定型を正規化済み1個へ統合 |
+| `src/swbt/gamepad/core.py` | modify | class profile、public constructor から runtime への単一路 |
+| `src/swbt/gamepad/runtime.py` | modify | constructor 一本化、factory object / context manager 削除 |
+| `src/swbt/gamepad/transport_factory.py` | modify | factory class を削除し関数だけ維持 |
+| `src/swbt/_testing/gamepad.py` | delete | production test factories を削除 |
+| `src/swbt/_testing/__init__.py` | delete | 空の test-only package を削除 |
+| `tests/gamepad_factory.py` | new | public constructor と runtime injection を使う test support |
+| `tests/unit/test_public_api_boundary.py` | modify | 単一設定型、class profile、seam 削除、既存契約 |
+| `tests/unit/test_gamepad_transport_factory.py` | modify | 関数と import boundary の検証へ集約 |
+| `tests/integration/test_switch_gamepad_fake_transport.py` | modify | production test factory / `_from_config()` を除去 |
+| `tests/integration/test_examples.py` | modify | tests support を利用 |
+| `spec/initial/architecture.md` | modify | controller 構築経路を記録 |
+| `spec/initial/api.md` | modify | production test helper 参照を削除 |
+| `spec/initial/testing.md` | modify | tests support と public constructor 経路へ更新 |
+
+## 11. 検証
+
+| command | result | notes |
+|---|---|---|
+| `uv run pytest tests/unit/test_package_import.py::test_production_package_has_no_test_gamepad_factory_module -q` | red / green | 削除前は `swbt._testing.gamepad` が見つかり失敗、削除後は unit gate 内で成功 |
+| `uv run pytest tests/unit/test_package_import.py tests/unit/test_gamepad_transport_factory.py tests/unit/test_public_api_boundary.py tests/unit/test_pairing_profile_runtime.py -q` | pass | 54 passed |
+| `uv sync --dev` | pass | 53 packages resolved、41 packages checked |
+| `uv run ruff format --check .` | pass | 102 files already formatted |
+| `uv run ruff check .` | pass | All checks passed |
+| `uv run ty check --no-progress` | pass | All checks passed |
+| `uv run pytest tests/unit` | pass | 468 passed |
+| `uv run pytest tests/integration` | pass | 154 passed |
+| `git diff --check` | pass | whitespace error なし |
+
+## 12. 実機実行条件
+
+| 項目 | 内容 |
+|---|---|
+| 実機要否 | not required |
+| 承認範囲 | adapter / Switch-facing command を実行しない |
+| adapter | none |
+| 実行遮断 | 環境変数による遮断は採用しない。`bumble` / `hardware` marker を実行対象から除外する |
+| log / artifact | local unit / integration / CI output |
+| cleanup | none |
+
+## 13. 先送り事項
+
+- none
+
+## 14. チェックリスト
+
+- [x] 対象範囲と対象外を確認した
+- [x] TDD Test List または文書検証計画を更新した
+- [x] 必要な根拠監査を記録した
+- [x] 実機実行条件を記録した
+- [x] 検証結果または未実行理由を記録した