Skip to content

m9 com api documentation

Jump to bottom
Kazushi Kamegawa edited this page Aug 2, 2026 · 1 revision

M9: COM API documentation

Status: Implemented, PRs open for review. Tracked by issue #11 and sub-issues #66, #137, and #138, delivered as a linear stack of three pull requests: #139 ← #140 ← #141. Merging and issue closure remain maintainer actions.

Goal

docs/TODO.md M9 has one checklist item — docs/com-api.md documenting COM activation steps, required capabilities, out-of-proc/in-proc differences, and fallback behavior — but docs/com-api.md already existed and was not a stub. So M9 was not "write a missing document." It was "make the existing document true again, and finish the one sub-topic it never covered."

Two things had made it untrue:

  1. The document stopped tracking the code. docs/com-api.md was last edited 2026-07-27; src/core/WingetComSource.cpp changed again 2026-07-30 (M6, issue #56, which moved COM apartment ownership from WingetComSource to main.cpp). The document still described the earlier arrangement.
  2. Parts of it were written from docs/PLAN.md's design intent, not the shipped implementation — the packageQuery capability claim and the CreateCompositePackageCatalog option were never reconciled with what was built.

Delivery: three stacked layers

  1. #66 / PR #139 — rewrite docs/com-api.md against the implementation. Restructured into sections answering each M9 checklist sub-topic plus the build-time projection story the checklist implies: "Build-time projection," "Activation" (corrected apartment ownership), "Out-of-proc vs in-proc" (the sub-topic that was previously only a passing mention — CLSCTX_LOCAL_SERVER only, no in-proc fallback, and the consequences), "What happens when" (constructor-vs-enumeratePackages() activation split), "Enumeration," "Failure and fallback" (new HRESULT/status-code tables, the corrected --source auto degrade contract), "Capabilities / permissions," and "Extending this code." Records ADR-0034 in a new docs/adr-phase-7.md (docs/adr-phase-6.md was 869 lines, well past docs/adr.md's 200-line split rule), backed by a live verification run.
  2. #137 / PR #140 — reconcile the surrounding documents. docs/PLAN.md §3/§10/§11, AGENTS.md §10, and README.md still contradicted ADR-0034 in places (the winrt::init_apartment() risk note, the hedged alias-gap note, the packageQuery claim, unchecked Definition-of-Done boxes M2 through M8 had already satisfied). No source file changed in this layer.
  3. #138 / PR #141 — retire stale source comments and close bookkeeping. src/core/PackageSourceError.h still called the --source com exit-code mapping "an open question" that #56 had settled; src/rules/RuleSet.cpp still referenced a WingetComSource-owned ComApartment that #56 removed. docs/adr-phase-2.md ADR-0009 gained a dated amendment note (not a rewrite) for the two facts it recorded that later changed. docs/TODO.md M9 and M8's stale README checkbox were both checked. Comment-only source changes; full Debug|Release × x64|ARM64 build and vstest.console.exe re-run per the project's Definition of Done.

A finding from live verification

Building Release|x64 and running scan --source com --verbose against a real, working winget installation (winget list succeeded; App Installer 1.30.80.0) reproduced winrt::create_instance<PackageManager> — the exact call WingetComSource makes — failing with HRESULT_FROM_WIN32(APPMODEL_ERROR_NO_PACKAGE) (0x80073D54). Two throwaway, non-committed probes narrowed this precisely: a bare CoCreateInstance of the same CLSID requesting only IUnknown succeeded; requesting the typed IPackageManager interface failed with that HRESULT. --source auto degraded cleanly to an identical, correct filesystem-scan result.

This is recorded in ADR-0034 and docs/com-api.md as an observed, environment- and possibly version-specific data point, not a general rule — M9 is scoped to documentation only, so no source change was attempted to investigate or fix it. Whether it warrants a follow-up bug-investigation issue is left to the project owner.

Test plan

  • Debug|Release × x64|ARM64 all build clean at every layer that touched src/ (layer 1 and layer 3; layer 2 was doc-only).
  • vstest.console.exe reports 405/405 for Debug|x64/Release|x64, unchanged across all three layers since no test or production logic changed.
  • Live COM verification (scan --source com|auto|fs --verbose) recorded in ADR-0034.
  • Documentation cross-read: docs/com-api.md, docs/PLAN.md §3/§10/§11, AGENTS.md §6/§10, README.md, and docs/TODO.md read back together to confirm agreement with each other and with src/.

Completion criteria

  • #66, #137, and #138 are merged and closed; #11 reflects their completion.
  • docs/TODO.md M9 is checked with issue + ADR evidence; M8's stale README box is resolved.
  • docs/com-api.md answers all four checklist sub-topics.
  • docs/adr-phase-7.md ADR-0034 exists, docs/adr.md's index has its row, and the live-run evidence — including what could not be verified — is recorded there.
  • No *_ja.md file was read or changed. docs/com-api_ja.md predates ADR-0009 and stays out of sync; bringing it current is an explicit human follow-up, not part of this milestone.
  • Closing #11 does not close #1 — M0's #21 (CI) and #22 (automated vulnerability gate) remain open.

Clone this wiki locally