@fateforge/xpedition-cli 1.0.0

package/docs/API_INVENTORY_DESIGN.md

@@ -0,0 +1,90 @@
+# Read-only API inventory: source references and review record
+
+*Historical record: written for pull request #9 before it was merged on 2026-09-18;
+kept as the design and evidence record. The current contract is
+`xpedition-cli reference`.*
+
+Independent implementation based on main d42b226. Existing draft PRs remain
+unchanged. This is the metadata-investigation part of the public-reference adoption
+work, separate from offline pin assignment and native write hardening.
+
+## References and adoption
+
+- [SiemensEDA Python Interface, pinned 54b3c3f](https://github.com/EdgarMerger/SiemensEDA_Python_Interface/tree/54b3c3f85d9fbcf10259705e5a3a11399794c12f):
+  motivates inspecting actual installed types rather than guessing API names or
+  adopting another version's heuristic annotations. No code or library is copied.
+- [Microsoft LoadTypeLib](https://learn.microsoft.com/en-us/windows/win32/api/oleauto/nf-oleauto-loadtypelib):
+  supplying a path disables the legacy automatic-registration behavior. pywin32
+  exposes LoadTypeLib, not LoadTypeLibEx; the code explicitly requires the resolved
+  absolute path. No filename-only lookup, ProgID or activation fallback is used.
+- pywin32 published metadata definitions:
+  [TYPEATTR](https://mhammond.github.io/pywin32/TYPEATTR.html),
+  [FUNCDESC](https://mhammond.github.io/pywin32/FUNCDESC.html),
+  [VARDESC](https://mhammond.github.io/pywin32/VARDESC.html),
+  [ELEMDESC](https://mhammond.github.io/pywin32/ELEMDESC.html).
+  Member metadata stays structural, not a guessed Python or JSON input schema.
+  Documentation was checked 2026-09-18; actual Windows binding smoke is separate.
+
+No third-party source, manuals, binaries or proprietary metadata is distributed by
+this change. Installation metadata is read only when explicitly requested. Reuse
+of upstream implementation code or redistribution of product metadata needs its
+own license review; linked public examples are not blanket permission.
+
+## Interpretation
+
+This closes a discovery gap, not an execution gap. A function or property name in
+a TLB does not prove callable behavior, units, state/permission preconditions, safe
+rollback or compatibility with our adapter. All results explicitly deny application
+activation, member invocation, registration request and capability grants.
+
+Inventory is constrained and paged; it is not a complete COM browser. It does not
+resolve aliases, inherited interfaces, referenced libraries or events into a full
+object graph. Metadata errors are visible; missing entries are not removed silently.
+It uses local file hashes rather than a mutable published API listing. Hashing
+before/after is ordinary change detection, not a hostile-input sandbox.
+
+## Verification and native gate
+
+Unit tests cover discovery without member reads, exact selection, ambiguous and
+unreadable headers, getter/setter classification, omission of defaults/constants,
+failed member reporting, bounded descriptor shapes/counts, file change detection,
+COM lifecycle, non-Windows handling, unsupported inputs/flags and output controls.
+CLI tests run against fake metadata providers on the normal matrix. The separate
+Windows smoke loads stdole2.tlb without application activation and checks the real
+binding, paging data and variable/function descriptors. No Xpedition is involved.
+
+The bootstrap writes API_INVENTORY_VALIDATION.json only after the full suite and
+existing quality gates pass. That record covers fake-provider testing; the actual
+Windows smoke publishes its own run-bound JSON evidence. Keep the distinction.
+Before using a discovered product API in a native command, verify it on the target
+installation with an explicit disposable project and operation-specific safety,
+state binding, partial-failure and readback tests. Do not promote inventory findings
+automatically into supported/native-verified command metadata.
+
+
+## Real-binding correction
+
+The first Windows smoke revealed that the system stdole2.tlb is a PE resource
+container. The smoke harness now extracts its sole TYPELIB as a data/image resource
+without executable initialization; CLI input restrictions remain unchanged.
+The next run reached a binding error. Upstream PythonCOM.cpp confirms pywin32
+exports LoadTypeLib, not the initially assumed LoadTypeLibEx. The implementation
+and fake provider now use the actual one-argument binding with an absolute-path
+guard. Microsoft explicitly documents non-registration for a supplied path.
+No permissive fallback or ctypes COM-pointer wrapper was introduced.
+
+The initial 256-test validation record is historical and did not establish real
+binding compatibility. API_INVENTORY_BINDING_VALIDATION.json records the corrected
+suite; the independent Windows smoke then passed (run 35298644634, recorded in
+API_INVENTORY_WINDOWS_VALIDATION.json and API_INVENTORY_REVIEW.md), so the binding
+is tested against standard OLE metadata. System OLE metadata remains distinct from
+target Xpedition evidence.
+
+
+The remaining metadata calls were checked against the published pywin32 binding.
+GetNames accepts the member ID, not the native C++ output-buffer length argument.
+Both production calls and the strict fake provider now use the one-argument API.
+Reference: https://mhammond.github.io/pywin32/PyITypeInfo__GetNames_meth.html .
+The Windows correction run validates the full suite and the actual standard OLE
+fixture before recording API_INVENTORY_WINDOWS_VALIDATION.json. That is still not
+an Xpedition installation or a call to any discovered application method.

package/docs/API_INVENTORY_REVIEW.md

@@ -0,0 +1,59 @@
+# API inventory review handoff
+
+*Historical record: written for pull request #9 before it was merged on 2026-09-18;
+kept as the design and evidence record. The current contract is
+`xpedition-cli reference`.*
+
+Implementation verified on Windows: `323dcd4ca908edbf73af8302624ea5c6373409ba`.
+This document changes no execution behavior. The PR remains draft/unmerged.
+
+## Executed evidence
+
+[Windows validation run 35298644634](https://github.com/fatecannotbealtered/xpedition-cli/actions/runs/35298644634)
+passed the complete **257-test suite**, Ruff lint/format, version consistency and
+the local canonical-contract generation guard, then executed the public inventory
+CLI against the real standard OLE metadata installed on the Windows runner.
+
+The CLI observed 42 type headers, 22 members on `IFont`, and four variable
+descriptors on `GUID`. The smoke asserted complete-in-scope results, no issues,
+unchanged input hashes, and the command's explicit non-execution markers. The
+real metadata loader was pywin32; no Xpedition installation or license was used.
+Machine-readable results and normalized source hash are in
+`API_INVENTORY_WINDOWS_VALIDATION.json`. Raw JUnit and JSON outputs are attached
+to the run. Only JSON was uploaded, not the Windows library or extracted binary.
+
+## Corrections found before handoff
+
+The initial Linux fake-provider tests did not catch an assumed `LoadTypeLibEx`
+entry that pywin32 does not expose. The actual binding is `LoadTypeLib`; the
+implementation enforces the absolute-path input that Microsoft documents as
+non-registering. It does not fall back to a bare filename or application factory.
+`GetNames` was also aligned to its one-argument Python binding in production and
+in the strict fake provider. The real Windows smoke now passes with these calls.
+
+The system `stdole2.tlb` on this runner was actually a PE resource container. The
+smoke harness extracted its sole TYPELIB through resource-only, non-executable
+mapping into a temporary standalone fixture. The public CLI still rejects PE
+containers; its input restrictions were not relaxed to satisfy a test.
+
+Historical validation records remain scoped to what they actually tested:
+`API_INVENTORY_VALIDATION.json` is the first 256-test fake-provider run;
+`API_INVENTORY_BINDING_VALIDATION.json` is the later 257-test loader correction;
+`API_INVENTORY_WINDOWS_VALIDATION.json` verifies the corrected member calls and
+real standard-OLE smoke. None is evidence of target Xpedition API semantics.
+
+## Review boundaries
+
+Normal PR CI and the permanent metadata smoke independently validate the committed
+tree after this handoff commit. Consult their actual results; the preceding
+Windows run does not by itself establish the later workflow status.
+
+No discovered member is callable through this command. Inventory does not prove
+units, preconditions, native support, licensing, transaction/rollback semantics,
+engineer-level task completion, or save/close/reopen durability. Using a product
+API still needs its own implementation, authorization and target-version evidence.
+
+This branch does not include the other draft PRs. In particular #8 provides the
+separate saved-observation pin-plan/pin-check task workflow; #4--#7 harden different
+boundaries. Main and those branches remain unchanged. Combined-tree tests and
+preserving all Unreleased notes/Skill guidance are required before a release.

package/docs/API_INVENTORY_VALIDATION.json

@@ -0,0 +1,29 @@
+{
+  "baseline": "d42b226a5b1812b2937ded096bf618b8692c4f9a",
+  "run_id": "35297642883",
+  "platform": "Linux-6.17.0-1022-azure-x86_64-with-glibc2.39",
+  "before": {
+    "tests": 1,
+    "failures": 1,
+    "errors": 0,
+    "skipped": 0
+  },
+  "full_suite": {
+    "tests": 256,
+    "failures": 0,
+    "errors": 0,
+    "skipped": 0
+  },
+  "ruff": "passed",
+  "version_sync": "passed",
+  "contract_local_only": "passed",
+  "native_xpedition_executed": false,
+  "real_type_library_loaded": false,
+  "scope": "fake type metadata; real Windows smoke separate",
+  "source_sha256": {
+    "xpedition_cli/api_inventory.py": "921db8ee335413b79908e27035455fb4904be86807cd5c6d7e8cc68325532864",
+    "xpedition_cli/api_inventory_contract.py": "2f2b1e3c2a6bf5f141035d0c9927780df5c51567b62e34e7231afda08b5f94fc",
+    "xpedition_cli/main.py": "4ee1d74b397723566d6982215e0381edc833cf122b0f7f0868d25c3c38168193",
+    "xpedition_cli/reference_data.py": "83dd6aa55df294cee7723b85336efb5550850ef1e37178a7d7b282bd6bb55433"
+  }
+}

package/docs/API_INVENTORY_WINDOWS_VALIDATION.json

@@ -0,0 +1,29 @@
+{
+  "run_id": "35298644634",
+  "platform": "Windows-2025Server-10.0.26100-SP0",
+  "full_suite": {
+    "tests": 257,
+    "failures": 0,
+    "errors": 0,
+    "skipped": 0
+  },
+  "ruff": "passed",
+  "version_sync": "passed",
+  "contract_local_only": "passed",
+  "windows_metadata_smoke": {
+    "run_id": "35298644634",
+    "source_sha256": "58c3b3a2c798ec42eaef8155dd22e2c2f49f53d91b1f1f115a6fc5164b8078f9",
+    "system_file_sha256": "815d6c50ad934a42800e52faef5207dd9352ab8c386793422682084c8f604c5d",
+    "resource_only_fixture_extraction": true,
+    "type_count": 42,
+    "interface": "IFont",
+    "interface_members_observed": 22,
+    "variable_type": "GUID",
+    "variables_observed": 4,
+    "status": "passed",
+    "scope": "Windows standard OLE metadata only",
+    "xpedition_executed": false
+  },
+  "xpedition_executed": false,
+  "source_sha256_normalized_lf": "318b7ca470383e7f9928fec6f75bdb9580751bcf1543dc5366c25e3509bf4ab3"
+}