所有者（owner）システム

所有者（owner）は、モジュールの「プラグインとして即時利用」の基盤です。モジュールがロード時に登録するフレームワークリソースはすべて自動的に所有者に記名され、モジュールのアンロード/無効化時に所有者ごとに一括で回収されます。モジュール開発者はリソースを宣言するだけで、手動でクリーンアップロジックを書く必要はありません。

関連システム：スコープ（scope）はイベント配信時に「リソースが有効かどうか」を決定し、所有者はライフサイクル中に「リソースは誰のものか、誰がアンロード時に回収されるか」を決定します。スコープの詳細は統一制御面（scope）、バックグラウンドタスクの詳細はライフサイクル管理をご覧ください。

{!--< tips >!--}

1. 所有者は登録瞬間に current_owner によって自動的に記録され、モジュールコードは変更不要です。
2. アンロード/無効化は共通のクリーンアップチェーン（_cleanup_module_registrations）を使用し、各ステップで失敗しても警告のみ表示され、処理は中断されません。
3. ユーザー設定のリソース（永続化オーバーライド / scope 規則 / コマンド ACL）は、モジュールのアンロード時にクリーンアップされません。
4. ツールモジュールが管理する外部ハンドルは、on_cleanup(cb) を使ってクリーンアップチェーンに登録し、他のモジュールがアンロードされた際に自動的にコールバックされます（ツールモジュールガイドを参照）。 {!--< /tips >!--}

owner コンテキストメカニズム

owner はコンテキスト変数 current_owner によって伝達されます（ErisPulse.runtime.context）：

from ErisPulse.runtime import owner_scope, get_current_owner

with owner_scope("MyModule"):
    # この区間内で登録されるすべてのリソースは自動的に MyModule に所有されます
    assert get_current_owner() == "MyModule"

フレームワークは以下のタイミングで owner を自動的に注入します（モジュール/アダプタのコードは手動でラップする必要はありません）：

実行中の再注入とは、モジュールが on_load で宣言したコマンドハンドラが実行中に登録型 API（sdk.adapter.on()、overrides.*.set(persist=False)）を呼び出す場合でも、自動的に本モジュールに所有されることを意味します。

所有リソースの全貌

モジュールがロードコンテキスト内で登録した以下のリソースはすべて所有を記録し、アンロード/無効化時に自動的に回収されます：

アダプタ側の対応リソース（プラットフォーム名を所有者として）は、アダプタ shutdown() / restart() 時に _cleanup_adapter_resources によって回収され、以下も含まれます：

アンロード/無効化クリーンアップシーケンス

unload() と disable() は共通のクリーンアップチェーンを使用します（各ステップは独立して try/except で、失敗してもログに記録され、後続のクリーンアップは中断されません）：

flowchart TD
    A["unload / disable"] --> B["on_unload()（タイムアウト保護）"]
    B --> C["バックグラウンドタスクのキャンセル（cancel_owner_tasks）"]
    C --> C1["外部所有クリーンアップフック<br/>（ツールモジュール on_cleanup 登録、run_owner_cleanups トリガー）"]
    C1 --> D["_cleanup_module_registrations<br/>＝ 所有者権限のファサード ownership.reclaim_sync()"]
    D --> D1["i18n 翻訳ドメイン"]
    D1 --> D2["ルーティング：名前空間 + owner バックアップ<br/>（ルーティングオブジェクト同一性に基づく正確な削除、<br/>ミドルウェア / ホームエントリを含む）"]
    D2 --> D3["アダプタイベントハンドラ / ミドルウェア"]
    D3 --> D4["コマンド + イベントハンドラ"]
    D4 --> D5["自定義セッションタイプ"]
    D5 --> D5b["プラットフォームイベントメソッド注入"]
    D5b --> D6["実行時イベントオーバーライド（persist=False）"]
    D6 --> D7["主人身源 provider"]
    D7 --> D8["ライフサイクルフック"]
    D8 --> E["SDK 属性の削除 + ラグジュアリプロキシ"]
    E --> F["自動軽量監査：孤児の owner 警告"]

sdk.uninit() による終了時には、以下のグローバルバックアップ処理が実行されます：すべてのアダプタの shutdown → すべてのモジュールの unload → router.stop()（ルーティング/ミドルウェア/ホームエントリのクリア）→ cancel_all_background_tasks() → イベントハンドラとフックのクリア。

所有者権限統一ファサード（ownership）

クリーンアップチェーンの16ステップは、所有者権限統一ファサード ErisPulse.Core.ownership に収束され、4つの動詞が「登録解除、カウント、スキャン、監査」をカバーします。サブシステム独自の *_by_owner 登録関数は変更されず、ファサードの内部実装として残ります：

from ErisPulse.Core import ownership

ownership.reclaim_sync("MyModule")       # {'commands': 1, 'routes_http': 2, ...}
ownership.counts("MyModule")             # 登録リソースのカウント
ownership.orphans()                      # [{"owner": "ghost", "total": 2, ...}]

監査エントリポイント：

• アンロード / 再ロード後に自動軽量監査：孤児の所有者リソースが見つかると WARNING 警告（コストゼロのカウントスキャン）
• sdk.module.audit(name, deep=True)：モジュールインスタンスの gc 調査——インスタンスが再利用できない場合、参照元のタイプを示す（「誰が古いインスタンスを保持しているか」を特定）；グローバル停止のコストがかかるため、明示的なトラブルシューティングでのみ使用
• 深層調査は明示的操作であり、設定キーは設定せず、自動修復も行いません。

ホットリロード失敗ロールバック

ホットリロードは「アンロード前のスナップショット → 失敗時に自動回復」に変更されました：新バージョンの構文エラー、依存性の欠落、ロード失敗時には、旧インスタンスと登録状態（登録表エントリ、sdk 属性、sys.modules エントリ）が自動的に復元され、サービスは中断されず、ログに「旧インスタンスにロールバックしてサービスを継続しました」と表示されます。

可能な限りの意味（ドキュメント化された境界）：

• on_unload で既に実行された副作用（切断された接続、キャンセルされたタスク）は取り消せません——復元後、旧インスタンスは「終了済み」状態になり、完全に利用可能になるには再びロードをトリガーする必要があります
• 実行時に第三者が手動でキャッシュした旧インスタンスへの参照は復元範囲外です
• 目標パッケージがアンロード済み（entry-point が消滅）の場合は、アンロード成功と見なし、ロールバックは行いません

設計境界：アンロード時にクリーンアップされないリソース

所有者権限はモジュールコードが登録する実行時リソースのみを回収します。以下のリソースはユーザー設定の意味（コントロール権はユーザーにあり、意図的に設定される）に属し、モジュールのアンロード後も設定に従って永続的に保持されます：

実行時に一時的に書き込まれたもの（persist=False）は、owner に従って回収されます。永続化の有無が「ユーザー資産」と「モジュール実行時状態」の境界線です。

内部実装：所有権の仕組み

所有権システムは2つの独立したチェーンで構成されており、それらの役割を理解することは、所有権の問題を解決するための前提です。

帰属チェーン（contextvar 伝播）

runtime/context.py の current_owner などの ContextVar は帰属を担当します——「このコードが登録するリソース/呼び出しが誰の名前に記録されるか」。伝播ルールは Python の contextvars 言語仕様に従います：

帰属 ≠ 登録：context 伝播は「誰の名前に記録されるか」を決定しますが、リソースがクリーンアップされるかどうかは、登録チェーンに入っているかどうかにかかっています。

キャンセルチェーン（タスク登録表）

runtime/tasks.py の _owner_tasks 登録表はライフサイクルを担当します——「owner 名下に未完了のタスクが何個あるか、アンロード時に一括でキャンセルするか」。タスクが登録表に入る方法：

1. 明示的なスケジューリング：spawn_background() / self.spawn() → 作成時に current_owner（または明示的な owner= パラメータ）をキャプチャ → 登録表に登録；
2. Task Factory 自動登録（2.8.3）：install_owner_task_factory() はフレームワーク起動時にメインイベントループにインストールされる——すべてのタスク作成（サードパーティライブラリの内部の create_task を含む）は、ファクトリを経由して current_owner を読み取り、None でなければ登録される。

登録表は自動でクリーンアップされます：各タスクには done_callback が付いており、完了すると表から削除され、リークしません。

キャンセルタイミング（モジュールアンロード）

module.unload()
  → on_unload(event)                    # モジュール独自のクリーンアップ（バックアップタイムアウト保護）
  → フレームワークがこの owner のコマンド/イベント/フック/ルーティングを登録解除
  → cancel_owner_tasks(owner)           # タスク登録表のバックアップキャンセル
      → 各タスク.cancel()              # キャンセルロジック自体のタスクは除外
      → await gather(pending, timeout)  # 回収を待つ（タイムアウト後にブロックしない）

問題解決のアプローチ

• リソースがクリーンアップされない → 登録表を確認：get_owner_tasks("MyModule") に該当タスクが含まれているかを確認；含まれていない場合は登録経路が所有権チェーンを通過していない（import 時 / スレッド / 独立ループ）、上表を参照して位置を特定。
• 帰属が間違っている → get_current_owner() をエラー発生時の値で確認；非同期遅延実行（コールバック/タスク）の帰属は作成時の context に従い、実行時の値とは異なる。

モジュール開発者ガイド

推奨書き方

from ErisPulse import sdk
from ErisPulse.Core.Event import command
from ErisPulse.runtime import owner_scope, spawn_background

class MyModule(BaseModule):
    async def on_load(self, event):
        # フレームワークリソース：自動的に所有される、手動でクリーンアップする必要はない
        self.task = self.spawn(self.polling())      # バックグラウンドタスク
        sdk.router.register_home_entry("私のモジュール", "/my")  # ホームエントリ

        # モジュール独自リソース：owner_scope に包むことで所有権体系に組み込む
        with owner_scope("MyModule"):
            self.client.on_event(self._handle)      # 假想の独自登録

    async def on_unload(self, event):
        # フレームワークリソースは自動的に回収される、owner_scope でカバーできない独自リソースのみクリーンアップする
        await self.client.close()

注意事項

• import 時の登録には所有権がない：モジュールのトップレベル（import 時）に登録されたフック/ハンドラは owner_scope 以前に発生するため、フレームワークリソース（owner=None）として扱われ、クリーンアップされない。すべて on_load() 内に登録すること。
• 独自 domain の i18n 登録：i18n.register(domain=...) の domain がモジュール名と異なる場合、自動回収されないため、domain=モジュール名を保持すること。
• バックグラウンドタスクは self.spawn() を推奨：2.8.3 以降、裸の asyncio.create_task も自動的に暗黙的に所有（Task Factory が自動登録、アンロード時にバックアップキャンセル）される。ただし、self.spawn() は非メインループスレッドからメインループにスケジューリング、明示的な owner= 指定、fire-and-forget の GC 防止のため、引き続き推奨書き方です。2.8.3 以前のバージョンでは、裸のタスクは所有されず、self.spawn() を使用する必要がある。
• クリーンアップチェーンは「失敗しても警告のみ」：1ステップのクリーンアップエラーは他のリソースの回収を中断せず、ログの DEBUG/WARNING レベルで確認可能。トラブルシューティング時は TRACE を有効にすること。

登録タイミング → 所有結果対照表

原則：所有は登録瞬間の current_owner コンテキストに従う；非同期の遅延、スレッドプール、独自ループはすべてこのコンテキストから外れるため、所有が必要な場合は明示的に owner_scope に入る必要がある。

ツールモジュールガイド：他のモジュールのハンドルを管理する

シナリオ：定時タスク、レジストリ、接続プールなどの「ツールモジュール」は、他のモジュールが保管するものを代わりに管理します。
他のモジュールが on_load で sdk.Cron.on_trigger(handler) を呼び出すと、あなたのコンテナはそのモジュールのインスタンスを指すコールバックを保持します。
フレームワークは、モジュールが登録したフレームワークリソースは自動的にクリーンアップしますが、あなたが私有コンテナに保持している参照はクリーンアップできません。
モジュールがアンロードされた後も、あなたのコンテナはそのインスタンスを保持しているため、GC によって回収されず（メモリリーク）、purge 泄漏診断では「回収不可能」と表示されます。

解決策：登録処理を行う関数内で on_cleanup() を呼び出すと、フレームワークはモジュールがアンロードまたは無効化された際にあなたのクリーンアップ関数を自動的にコールバックします：

from ErisPulse.Core.Bases import BaseModule
from ErisPulse.runtime import off_cleanup, on_cleanup

class CronModule(BaseModule):
    def __init__(self):
        self._entries = {}  # {モジュール名: そのモジュールが管理するコールバックリスト}

    def on_trigger(self, handler):
        # 呼び出し元モジュール名を自動的に識別（on_load からの直接呼び出し / module.call ともに正しく動作）
        # 戻り値は owner として使用できる解析されたモジュール名
        owner = on_cleanup(self._drop)
        self._entries.setdefault(owner, []).append(handler)

    def _drop(self, owner: str):
        """モジュールがアンロードまたは無効化された際にフレームワークによって自動的にコールバックされる：ハンドルを破棄するだけ"""
        self._entries.pop(owner, None)

    async def on_unload(self, event):
        off_cleanup(self._drop)  # ③ 自分がアンロードされる前にハンドルを解除し、ハンドルテーブルが self を保持しないようにする

フレームワークが保証する動作：

必要ない場合：もしモジュールが登録するのはフレームワークリソース（コマンド、イベントハンドラー、ルーティング、バックグラウンドタスクなど）であれば、フレームワークはすでに自動的にクリーンアップします（上記のリソースの所有権の全体像を参照）。
フレームワークリソース以外に、あなたが私有コンテナに保持しているモジュールのハンドルだけが on_cleanup を必要とします。
モジュール開発者向けの速見版は、ベストプラクティス · ツールモジュール を参照してください。