From 5fb9cffaa7e706d664498307c9417efebcc07f6d Mon Sep 17 00:00:00 2001 From: Pigbibi <20649888+Pigbibi@users.noreply.github.com> Date: Sat, 31 Oct 2026 19:42:04 +0800 Subject: [PATCH] docs: propose explicit runtime monitoring dependencies --- README.md | 1 + README.zh-CN.md | 1 + ...declare-runtime-monitoring-dependencies.md | 132 ++++++++++++++++++ 3 files changed, 134 insertions(+) create mode 100644 docs/adr/0002-declare-runtime-monitoring-dependencies.md diff --git a/README.md b/README.md index 020ce66..7268ebc 100644 --- a/README.md +++ b/README.md @@ -170,6 +170,7 @@ trials nor grants research, DSR/PBO or trading approval. ## Useful docs +- [Runtime monitoring dependency proposal](docs/adr/0002-declare-runtime-monitoring-dependencies.md) - [`docs/crypto-cross-platform-strategy-spec.md`](docs/crypto-cross-platform-strategy-spec.md) - [`docs/crypto-cross-platform-strategy-spec.zh-CN.md`](docs/crypto-cross-platform-strategy-spec.zh-CN.md) - [`docs/crypto-portability-checklist.md`](docs/crypto-portability-checklist.md) diff --git a/README.zh-CN.md b/README.zh-CN.md index 074894b..8faebc3 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -113,6 +113,7 @@ python -m pytest -q ## 延伸文档 +- [运行时监控依赖提案](docs/adr/0002-declare-runtime-monitoring-dependencies.md) - [`docs/crypto-cross-platform-strategy-spec.md`](docs/crypto-cross-platform-strategy-spec.md) - [`docs/crypto-cross-platform-strategy-spec.zh-CN.md`](docs/crypto-cross-platform-strategy-spec.zh-CN.md) - [`docs/crypto-portability-checklist.md`](docs/crypto-portability-checklist.md) diff --git a/docs/adr/0002-declare-runtime-monitoring-dependencies.md b/docs/adr/0002-declare-runtime-monitoring-dependencies.md new file mode 100644 index 0000000..fbf06e6 --- /dev/null +++ b/docs/adr/0002-declare-runtime-monitoring-dependencies.md @@ -0,0 +1,132 @@ +# ADR 0002: Declare runtime monitoring dependencies + +Status: proposed + +## Context + +A normal installation should provide the libraries needed to import its +supported runtime entrypoints. Research extras and the developer test +environment serve different purposes and should not supply an undeclared +requirement of that import path. + +The inspected dependency declarations and sources expose a gap: + +| Boundary | Evidence | +| --- | --- | +| Consumer metadata | [Crypto dependency declarations][crypto-deps] list QPK as the only normal dependency. NumPy and Pandas appear in the optional `research` extra. | +| Consumer import | [The common runtime entrypoint][crypto-common] imports QPK's `PerformanceMonitor` at module scope. | +| Consumed package metadata | [The pinned QPK declaration][qpk-deps] has an empty normal dependency list. NumPy and Pandas appear only in its `dev` extra. | +| Consumed import path | [The monitor][qpk-monitor] imports Pandas and its metrics module. [The metrics module][qpk-metrics] imports both NumPy and Pandas at module scope. | +| Existing verification | [CI installation][ci-install] explicitly installs NumPy and Pandas. [The catalog/entrypoint check][entrypoint-check] skips when the import reports missing Pandas. | + +The QPK links identify the revision consumed by the referenced Crypto manifest, +rather than QPK's current default branch. This is static dependency and import +evidence. A failure in a clean wheel installation has not been reproduced by +this decision record, and no production failure is inferred. This path also +does not establish the complete dependency closure of every runtime module. + +Passing tests in an environment that separately installs these libraries do +not answer whether the normal package declaration is sufficient. The existing +tests remain useful for the behavior they exercise. + +## Proposed decision + +First reproduce the normal-install import boundary in an isolated environment. +If the gap is confirmed, prefer the smallest packaging correction: explicitly +declare the libraries required by the retained runtime import path in Crypto's +normal dependencies, while preserving the QPK source pin and runtime code. +The observed path requires consideration of both Pandas and NumPy. + +The supported version constraints must be established against the existing +consumer environments before that correction. Do not copy the research-extra +minimums into normal dependencies without compatibility evidence, broaden +constraints to make resolution succeed, or upgrade a platform implicitly. +Keep the existing `research` installation interface compatible when deciding +where its requirements belong. + +This proposal selects no new dependency version and makes no change to package +metadata, locks, runtime imports, workflows or deployment configuration. A +dependency-adoption change remains separate from a behavior-preserving code +extraction. + +## Alternatives + +### Add a QPK monitoring extra + +An explicit QPK extra would give the monitoring implementation ownership of its +requirements. Crypto would then depend on that extra. The currently consumed +QPK revision has no such extra, so this approach needs a shared-package change +and a separately reviewed consumer adoption. It has a larger release scope than +correcting the immediate consumer declaration. + +### Separate monitoring from strategy imports first + +An explicit observation sink at application composition can keep evaluation +imports independent of monitoring infrastructure. That requires +characterization of monitor reuse, record payloads, persistence, warning paths +and call order. It is a broader architecture change and should not be combined +with the packaging correction. + +### Delay or suppress the import error + +Moving the import into a best-effort recording function changes when a missing +dependency becomes visible. If the existing broad exception handler then +continues, an import failure could become a returned strategy decision without +the expected observation. This does not establish a complete installation and +must not be presented as a behavior-preserving fix. + +## Validation required before implementation + +1. Build and install the baseline wheel in a fresh environment using only its + declared normal dependencies. Keep research and development extras absent; + do not add NumPy or Pandas through test setup. +2. Import the supported runtime entrypoint without a sibling source checkout. + Record the actual imported module paths and installed distribution metadata. + Separate an import failure from a resolver, network or build failure. +3. Test the proposed declaration against the same boundary and the supported + consumer constraints. Keep the QPK source revision fixed. Run dependency + consistency checks without silently changing the consumer's lock file. +4. Run the affected strategy and monitoring tests with synthetic inputs and + controlled storage substitutes. Compare decisions, exceptions, observation + payloads, call order and warning behavior. No broker or real storage access + is needed for this packaging validation. +5. Retain the existing checks. A normal-install smoke check must fail on a + missing required import; a skip is not evidence that the installation works. + Verify that the research extra remains installable and compatible. + +The current metadata, import path and CI setup can be inspected independently +of this proposed validation. A successful documentation check does not complete +the clean-install experiment. + +## Consequences and rollback + +A declaration correction preserves the current runtime code and makes its +installation requirements explicit. It can enlarge the normal installation and +affect dependency resolution, so it still requires consumer compatibility +review. It does not remove monitoring's storage-dependent side effects. + +The alternative import-boundary change may reduce ordinary runtime +dependencies, but it must preserve observable monitoring behavior or be treated +as a separate behavior change. + +This proposed record requires no migration. If a later packaging change is +adopted, revert that consumer adoption separately to the previously supported +package and lock state. Retain the previous implementation and its compatibility +evidence; do not rewrite published history or hide the unresolved import gap. + +## Open decision + +Choose whether to proceed with a normal dependency declaration, develop a QPK +monitoring extra for separate adoption, or first isolate monitoring from the +strategy import path. The proposed first choice is the normal declaration, +conditional on the clean-install result and an agreed compatible constraint +set. Neither dependency adoption nor the alternative architecture change is +implemented by this record. + +[crypto-deps]: https://github.com/QuantStrategyLab/CryptoStrategies/blob/b537248094f3cd123b1400c421a4bb89c71b1981/pyproject.toml#L11-L19 +[crypto-common]: https://github.com/QuantStrategyLab/CryptoStrategies/blob/b537248094f3cd123b1400c421a4bb89c71b1981/src/crypto_strategies/entrypoints/_common.py#L9-L14 +[qpk-deps]: https://github.com/QuantStrategyLab/QuantPlatformKit/blob/c7646a7168b3dafa763ef7751a182d23e8de7790/pyproject.toml#L15-L25 +[qpk-monitor]: https://github.com/QuantStrategyLab/QuantPlatformKit/blob/c7646a7168b3dafa763ef7751a182d23e8de7790/src/quant_platform_kit/strategy_lifecycle/performance_monitor.py#L17-L35 +[qpk-metrics]: https://github.com/QuantStrategyLab/QuantPlatformKit/blob/c7646a7168b3dafa763ef7751a182d23e8de7790/src/quant_platform_kit/strategy_lifecycle/performance_metrics.py#L12-L13 +[ci-install]: https://github.com/QuantStrategyLab/CryptoStrategies/blob/b537248094f3cd123b1400c421a4bb89c71b1981/.github/workflows/ci.yml#L69-L78 +[entrypoint-check]: https://github.com/QuantStrategyLab/CryptoStrategies/blob/b537248094f3cd123b1400c421a4bb89c71b1981/tests/test_contract_governance.py#L96-L103