m9 com api documentation_ja

M9: COM APIドキュメント

状態: 実装済み、レビュー待ちのPRあり。issue #11とsub-issue #66、#137、 #138で追跡。線形にスタックされた3つのプルリクエストとして提供: #139 ← #140 ← #141。マージとissueクローズはメンテナの操作として残る。

目標

docs/TODO.md M9にはチェックリスト項目が1つある - docs/com-api.md が COM activationの手順、必要な機能、プロセス外/プロセス内の違い、フォール バックの挙動を文書化すること - しかし docs/com-api.md はすでに存在して おり、スタブでもなかった。したがってM9は「欠けているドキュメントを書く」 ではなかった。「既存のドキュメントを再び真実にし、それが一度もカバー していなかった唯一のサブトピックを完成させる」ことだった。

2つのことがそれを不正確にしていた:

1. ドキュメントがコードの追跡をやめていた。 docs/com-api.md は 最後に2026-07-27に編集されており、src/core/WingetComSource.cpp は 2026-07-30に再び変更されていた（M6、issue #56。COM apartmentの所有権を WingetComSource から main.cpp へ移した）。ドキュメントはまだ 以前の構成を記述していた。
2. 一部は docs/PLAN.md の設計意図から書かれており、出荷された実装 からではなかった - packageQuery 機能の主張と CreateCompositePackageCatalog オプションは、構築されたものと 一度も照合されていなかった。

提供: 3つのスタックされたレイヤー

1. #66 / PR #139 — docs/com-api.md を実装に照らして書き直す。 M9のチェックリストの各サブトピックと、チェックリストが暗示する ビルド時のprojectionのストーリーに答えるセクションへ再構成した: 「ビルド時のprojection」、「Activation」（修正されたapartmentの 所有権）、「プロセス外 vs プロセス内」（以前は通り過ぎるだけの 言及だったサブトピック - CLSCTX_LOCAL_SERVER のみでプロセス内 フォールバックはない、その帰結）、「何がいつ起きるか」（コンストラクタ 対 enumeratePackages() のactivationの分割）、「列挙」、「失敗と フォールバック」（新しいHRESULT/ステータスコードの表、修正された --source auto のdegrade契約）、「機能/権限」、「このコードを拡張する」。 新規 docs/adr-phase-7.md にADR-0034を記録する （docs/adr-phase-6.md はすでに869行あり、docs/adr.md の200行の 分割ルールをはるかに超えていた）。実際の検証実行に裏付けられている。
2. #137 / PR #140 — 周辺のドキュメントを整合させる。 docs/PLAN.md §3/§10/§11、AGENTS.md §10、README.md は、いくつかの点で ADR-0034と矛盾していた（winrt::init_apartment() のリスクに関する 注記、ヘッジされたエイリアスギャップの注記、packageQuery の主張、 M2〜M8がすでに満たしていた未チェックのDefinition-of-Doneボックス）。 このレイヤーではソースファイルは一切変更していない。
3. #138 / PR #141 — 古びたソースコメントを退役させ、記録整理を クローズする。 src/core/PackageSourceError.h はまだ --source com の終了コードマッピングを「未解決の問題」と呼んでいたが、 #56がそれを解決していた; src/rules/RuleSet.cpp はまだ #56 が削除した WingetComSource 所有の ComApartment を参照していた。 docs/adr-phase-2.md ADR-0009は、その後変わった2つの事実について 日付入りの補記（書き直しではなく）を得た。docs/TODO.md M9とM8の 古びたREADMEチェックボックスの両方をチェックした。コメントのみの ソース変更; プロジェクトのDefinition of Doneに従って Debug|Release × x64|ARM64 のフルビルドと vstest.console.exe を再実行した。

実際の検証からの発見

Release|x64 をビルドし、実際に動作しているwingetインストール （winget list が成功; App Installer 1.30.80.0）に対して scan --source com --verbose を実行したところ、 winrt::create_instance<PackageManager> - WingetComSource がまさに 行う呼び出しそのもの - が HRESULT_FROM_WIN32(APPMODEL_ERROR_NO_PACKAGE)（0x80073D54）で失敗する ことを再現した。2つの使い捨ての、コミットされていないプローブがこれを 精密に絞り込んだ: 同じCLSIDに対する IUnknown のみを要求する素の CoCreateInstance は成功した; 型付きの IPackageManager インターフェース を要求すると、そのHRESULTで失敗した。--source auto は同一の正しい ファイルシステム走査結果へクリーンにdegradeした。

これはADR-0034と docs/com-api.md に観測された、環境・バージョンに 依存しうるデータポイントとして記録されており、一般的なルールとしては 記録していない - M9はドキュメントのみに限定されているため、これを調査 または修正するためのソース変更は試みなかった。追跡調査のissueが必要かは プロジェクトオーナーに委ねる。

テスト計画

• src/ に触れたすべてのレイヤー（レイヤー1とレイヤー3。レイヤー2は ドキュメントのみ）で Debug|Release × x64|ARM64 すべてがクリーンに ビルドする。
• vstest.console.exe は Debug|x64/Release|x64 で 405/405 を報告し、 3つのレイヤーすべてで変わっていない。テストや本番ロジックが変更されて いないため。
• ライブCOM検証（scan --source com|auto|fs --verbose）をADR-0034に 記録する。
• ドキュメントの相互確認: docs/com-api.md、docs/PLAN.md §3/§10/§11、AGENTS.md §6/§10、README.md、docs/TODO.md を 一緒に読み返し、互いに、また src/ と整合していることを確認する。

完了基準

• #66、#137、#138がマージ・クローズされ; #11がその完了を反映している。
• docs/TODO.md M9がissueとADRの証拠とともにチェックされている; M8の 古びたREADMEボックスが解決されている。
• docs/com-api.md が4つのチェックリストのサブトピックすべてに答えている。
• docs/adr-phase-7.md ADR-0034が存在し、docs/adr.md のインデックスに その行があり、ライブ実行の証拠 - 検証できなかったことを含む - が そこに記録されている。
• *_ja.md ファイルは一切読み取り・変更していない。docs/com-api_ja.md はADR-0009より前のもので同期していないままである。それを最新にするのは 明示的な人間のフォローアップであり、このマイルストーンの一部ではない。
• #11をクローズすることは#1をクローズしない - M0の#21（CI）と#22 （自動脆弱性ゲート）は未解決のまま残る。