deeptrade-quant 0.6.0__tar.gz → 0.8.0__tar.gz

{deeptrade_quant-0.6.0 → deeptrade_quant-0.8.0}/CHANGELOG.md

@@ -2,6 +2,79 @@
 
 All notable changes to DeepTrade. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and SemVer.
 
+## [v0.8.0] — 2026-05-16 — 插件 install / upgrade 走 CDN，零 GitHub API 调用
+
+`deeptrade plugin install` 与 `deeptrade plugin upgrade` 此前在解析"最新版本"与下载 tarball 时各打一次 ``api.github.com``，未认证用户共享 60/h 的 IP 级配额。一旦插件用户数上来，或者用户与浏览器 / `gh` CLI / `git clone` 公共仓库共用同一公网 IP，``HTTP 403: rate limit exceeded`` 就会把 install / upgrade 直接打死。共享 token 会违反 GitHub ToS，且配额仍会在那个 token 上聚合——不是解。
+
+本版改造将插件分发热路径全部搬到 CDN 端点：
+
+- **Tarball 下载**改走 ``codeload.github.com/<owner>/<repo>/tar.gz/<ref>``。codeload 是 CDN-backed 静态端点，不计入 REST API 限流。
+- **"最新版本"**改从注册表 ``index.json`` 的新字段 ``latest_version`` 读取（``raw.githubusercontent.com`` 同样不限流，且已有 ETag 缓存）。
+- **URL 形式安装**（``deeptrade plugin install https://github.com/...``）无 ``--ref`` 时默认 ``main`` 分支；其他默认分支需显式 ``--ref``。
+
+净效果：未认证用户走 ``install`` / ``upgrade`` 全流程**零 API 调用**，60/h 限制对默认路径不再存在。``GITHUB_TOKEN`` 不再被框架读取，文档不再推荐设置。
+
+### Changed
+
+- ``deeptrade/core/github_fetch.py``：删除 ``latest_release_tag`` / ``NoMatchingReleaseError``；``fetch_tarball`` 改写为 codeload 单端点（移除 ``GITHUB_TOKEN`` / ``X-GitHub-Api-Version`` header）。
+- ``deeptrade/core/registry.py``：``RegistryEntry`` 新增可选字段 ``latest_version: str | None``；解析器引入 ``_OPTIONAL_FIELDS`` 集合，含字段时填入，缺省 ``None``。schema_version 不变（仍为 1，向后兼容旧注册表文件）。
+- ``deeptrade/core/plugin_source.py``：``_resolve_short_name`` 用 ``entry.latest_version`` 替代 ``latest_release_tag``；缺字段且无 ``--ref`` 时抛 ``SourceResolveError`` 提示需补 ``--ref``。``_resolve_url`` 无 ``--ref`` 默认 ``main``；codeload 失败时错误信息提示用户切换 ``--ref``。
+- ``deeptrade/cli_plugin.py``：移除 ``NoMatchingReleaseError`` 引用。
+
+### Removed
+
+- ``latest_release_tag`` 公共函数与 ``NoMatchingReleaseError`` 异常类。
+- 对 ``GITHUB_TOKEN`` 环境变量的读取（github_fetch.py 中）。
+
+### Migration notes
+
+- **注册表维护者**：在 ``DeepTradePluginOfficial/registry/index.json`` 每个 plugin entry 中加 ``latest_version`` 字段，每次插件发版后同步该字段。可由 plugin 仓库 release workflow 自动 PR 到注册表仓库。
+- **存量旧版框架用户**：旧版（v0.7 及以下）仍会调 ``api.github.com``。``latest_version`` 字段是可选的、旧框架读取时会被忽略，不破坏现有用户；旧用户升级到本版后限流问题自动消失。
+- **URL 形式高级用户**：若你 host 的仓库默认分支不是 ``main``，``deeptrade plugin install https://github.com/<your>/<repo>`` 需显式 ``--ref <branch>``。
+
+### Why not "use a shared token"
+
+GitHub ToS 明确禁止 token 跨用户共享（被发现 token 会被吊销）；即便允许，5000/h 也会被规模化使用快速吃掉，且 token 泄露需要维护者承担权限滥用风险。CDN 改造是唯一既不需要每用户认证、又能稳定服务的方案。未来若需要支持私有仓库或企业内部分发，再走 OAuth Device Flow（``gh auth login`` 同款流程）让每个用户认证自己的 token。
+
+## [v0.7.0] — 2026-05-15 — 依赖隔离稳健化 + timezone IANA 校验
+
+本版按 2026-05-15 评审研判文档 §5 v0.7 路线落地 2 项主线，至此 v0.5 § 5 全部"采纳项"清零：
+
+1. **H6 依赖隔离稳健化**：
+   - **dry-run 预检**：``run_install`` 之前先跑 ``uv pip install --dry-run`` 抓 uv 的 change plan；解析 ``~`` (update) / ``-`` (remove) 行，与 ``framework_core_canonicals()`` 求交集。若插件依赖会顺带升级 / 降级 / 移除任何框架核心 dep，默认拒绝，要求显式 ``--allow-core-bump`` 才放行。``uv`` 不在 PATH 时降级为不做检查（``pip`` 没有对等结构化 dry-run），保持 v0.4 装机不动手的承诺。
+   - **dep snapshot**：``run_install`` 之前把 ``pip list --format=freeze`` 输出落到 ``~/.deeptrade/dep_snapshots/<plugin_id>/pre-install-<UTC>.txt``。失败时错误信息把这个目录甩到用户面前，便于 ``diff`` 回滚。
+   - 仍**不做**：venv-per-plugin / subprocess 隔离（重型方案，违反"框架轻"）；框架 deps 的 pin lockfile（会污染用户项目的解析）。
+2. **L1 timezone IANA 校验**：``AppConfig.app_timezone`` 改用 ``zoneinfo.available_timezones()`` 做硬校验，把 ``Asia/Shangai`` 这种近似拼写在写时拦住，而不是延迟到第一次 ``ZoneInfo(...)`` 调用爆 ``ZoneInfoNotFoundError``。``base_url`` HTTPS 强制按方案 §4 评估**仍不做**（本地 LLM 网关 / Ollama 常用 http）。
+
+### Added
+
+- ``deeptrade/core/dep_installer.py``：
+  - ``framework_core_canonicals()``——读取 ``deeptrade-quant`` distribution 的 ``Requires``，过滤掉 ``extra`` marker，输出框架核心 dep 的 canonical 名字集合。从源码运行（未 ``pip install -e``）时返回空集合，让预检自动降级为 no-op。
+  - ``preflight_dry_run(reqs, *, watched)``——best-effort 跑 ``uv pip install --dry-run``；解析 stderr / stdout 中的 ``~`` 与 ``-`` 行；返回与 ``watched`` 相交的 canonical 名字集合。``uv`` 缺席、resolution 失败、超时——一律返回空集合，让真正的 ``run_install`` 路径报底层错误，预检不抢话语权。
+  - ``_parse_dry_run_changes(text, watched)``——dry-run 输出解析的纯函数版本，便于单测覆盖。
+  - ``write_dep_snapshot(plugin_id, dir_root)``——优先 ``uv pip list``，回退 ``python -m pip list``（uv 管理的 venv 通常不带 pip）；写 ``<dir_root>/<plugin_id>/pre-install-<UTC>.txt``，返回 ``Path`` 或失败时 ``None``。
+  - ``DRY_RUN_TIMEOUT_SECONDS`` 短超时常量，避免被卡住的 uv 阻塞真正的 install。
+- ``deeptrade/core/paths.py::dep_snapshots_dir()``——``~/.deeptrade/dep_snapshots/``；纳入 ``ensure_layout()`` 自动创建。
+- ``deeptrade/core/plugin_manager.py::PluginManager.install`` / ``upgrade`` 接 ``allow_core_bump: bool = False``；``_handle_dependencies`` 在 ``run_install`` 之前先跑 preflight 与 snapshot，并在 install error 信息里附上 snapshot 目录 hint。
+- ``deeptrade/cli_plugin.py``：``plugin install`` 与 ``plugin upgrade`` 加 ``--allow-core-bump`` flag（中文 help 文案）。
+- ``deeptrade/core/config.py::AppConfig._validate_app_timezone``——基于 ``zoneinfo.available_timezones()`` 的 ``@field_validator``；非法值抛 Pydantic ``ValidationError`` 并指出如何打印当前主机支持的全部 zones。
+- 测试：``tests/core/test_config.py`` 5 个新用例（默认值通过、典型 IANA 名通过、typo / 空串 / 任意字符串拒绝）。``tests/core/test_plugin_dependencies.py`` 10 个新用例（``framework_core_canonicals`` 列出 must-have、``_parse_dry_run_changes`` 识别 update / remove、忽略 install 行、uv 缺席返回空集、空 requirements 返回空集、watched 为空跳过 subprocess、``_handle_dependencies`` 默认拒绝 core bump 与 ``--allow-core-bump`` 放行、``write_dep_snapshot`` 写文件、pip 缺失返回 ``None``、CLI 双向）。
+
+### Changed
+
+- ``deeptrade/core/plugin_manager.py::_handle_dependencies``：新增 ``allow_core_bump`` kwarg；``run_install`` 调用包了 ``try/except DepInstallError``，把异常包裹一层附上 snapshot 目录提示，便于排障。
+- ``deeptrade/core/dep_installer.py::write_dep_snapshot``：拆出 ``_snapshot_argv()`` 帮助选择 ``uv pip list`` vs ``python -m pip list``，与 ``detect_installer()`` 的优先级一致。
+
+### Migration notes
+
+- **用户视角零强制动作**：默认行为是更严的（核心 dep 改动需要显式确认），但常见插件不会动框架核心 dep——绝大多数 ``deeptrade plugin install <短名>`` 命令仍然零摩擦。
+- **遇到核心依赖冲突如何处理**：v0.7 之后若看到 ``plugin install would change framework core dep(s) [...]`` 的拒绝信息，先看 dry-run 报告的具体包：
+    - 如果是 ``duckdb`` / ``pydantic`` / ``click`` / ``typer`` 等加载链路上的运行时关键件——大概率是插件 spec 写得太死，反馈给插件作者放宽；强行 ``--allow-core-bump`` 可能让框架进程立刻 import 失败。
+    - 如果只是 minor 版本提升且已读过 release note——加 ``--allow-core-bump`` 显式确认放行。
+- **uv 缺席的主机**：``preflight_dry_run`` 自动跳过，行为与 v0.4 一致。``write_dep_snapshot`` 也能用 ``python -m pip list`` 兜底（虽然 uv-only venv 上 pip 通常缺席，此时 snapshot 静默 no-op）。
+- **dep_snapshots 目录的清理**：框架本身不做轮转。如果该目录变大，可以放心 ``rm`` 老的 ``pre-install-*.txt`` 文件——它们只用于回溯，不影响运行时。
+- **timezone**：升级到 v0.7 之后第一次 ``Database()`` 打开会触发自动迁移，迁移本身不动 ``app.timezone``；但如果你之前不小心存了 typo 进 ``app_config``，下一次 ``ConfigService.get_app_config()`` 会抛 ``ValidationError``。修法：``deeptrade config set app.timezone Asia/Shanghai``（或你本地的正确 IANA 名）。
+
 ## [v0.6.0] — 2026-05-15 — 插件运行时 API + LLM 方言 + 杂项收尾
 
 本版按 2026-05-15 评审研判文档 `DeepTrade-review-assessment-and-fix-plan-2026-05-15.md` §5 中 v0.6 路线落地 6 项主线：

{deeptrade_quant-0.6.0 → deeptrade_quant-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deeptrade-quant
-Version: 0.6.0
+Version: 0.8.0
 Summary: LLM-driven A-share (Shanghai/Shenzhen main board) stock screening CLI
 Project-URL: Homepage, https://github.com/ty19880929/deeptrade
 Project-URL: Repository, https://github.com/ty19880929/deeptrade

{deeptrade_quant-0.6.0 → deeptrade_quant-0.8.0}/deeptrade/__init__.py

@@ -2,5 +2,5 @@
 
 from __future__ import annotations
 
-__version__ = "0.6.0"
+__version__ = "0.8.0"
 __all__ = ["__version__"]

{deeptrade_quant-0.6.0 → deeptrade_quant-0.8.0}/deeptrade/cli_plugin.py

@@ -12,7 +12,6 @@ from deeptrade.core import paths
 from deeptrade.core.db import Database
 from deeptrade.core.github_fetch import (
     GitHubFetchError,
-    NoMatchingReleaseError,
     TarballFetchError,
 )
 from deeptrade.core.plugin_manager import (
@@ -41,7 +40,6 @@ _RESOLVE_ERRORS: tuple[type[Exception], ...] = (
     RegistryNotFoundError,
     RegistryFetchError,
     RegistrySchemaError,
-    NoMatchingReleaseError,
     TarballFetchError,
     GitHubFetchError,
     SourceResolveError,
@@ -75,6 +73,11 @@ def cmd_install(
     reinstall_deps: bool = typer.Option(
         False, "--reinstall-deps", help="对全部依赖重新运行安装器（uv/pip --upgrade）"
     ),
+    allow_core_bump: bool = typer.Option(
+        False,
+        "--allow-core-bump",
+        help="允许该插件的依赖安装顺带升级 / 降级 / 移除框架核心 dep（默认拒绝）",
+    ),
 ) -> None:
     """从注册表 / GitHub URL / 本地目录安装一个插件。"""
     resolver = SourceResolver()
@@ -109,6 +112,7 @@ def cmd_install(
                 resolved.path,
                 install_deps=not no_deps,
                 reinstall_deps=reinstall_deps,
+                allow_core_bump=allow_core_bump,
             )
         except PluginInstallError as e:
             typer.echo(f"✘ 安装失败：{e}")
@@ -269,6 +273,11 @@ def cmd_upgrade(
     reinstall_deps: bool = typer.Option(
         False, "--reinstall-deps", help="对全部依赖重新运行安装器（uv/pip --upgrade）"
     ),
+    allow_core_bump: bool = typer.Option(
+        False,
+        "--allow-core-bump",
+        help="允许该插件的依赖升级顺带升级 / 降级 / 移除框架核心 dep（默认拒绝）",
+    ),
 ) -> None:
     """升级一个已安装的插件。
 
@@ -292,6 +301,7 @@ def cmd_upgrade(
                     resolved.path,
                     install_deps=not no_deps,
                     reinstall_deps=reinstall_deps,
+                    allow_core_bump=allow_core_bump,
                 )
             except PluginNotFoundError as e:
                 try:

{deeptrade_quant-0.6.0 → deeptrade_quant-0.8.0}/deeptrade/core/config.py

@@ -118,6 +118,28 @@ class AppConfig(BaseModel):
                 return time(int(parts[0]), int(parts[1]), int(parts[2]))
         return v
 
+    @field_validator("app_timezone")
+    @classmethod
+    def _validate_app_timezone(cls, v: str) -> str:
+        """v0.7 L1 — reject ``app.timezone`` values that aren't IANA zone names.
+
+        ``zoneinfo.available_timezones()`` is the authoritative source on the
+        runtime host (Python 3.11+; reads ``/usr/share/zoneinfo`` on Linux,
+        falls back to the bundled ``tzdata`` wheel on Windows). Without this,
+        a typo like ``Asia/Shangai`` reaches the eventual ``ZoneInfo(...)``
+        call and crashes much later with a confusing ``ZoneInfoNotFoundError``.
+        """
+        from zoneinfo import available_timezones  # noqa: PLC0415
+
+        zones = available_timezones()
+        if v not in zones:
+            raise ValueError(
+                f"app.timezone {v!r} is not a valid IANA zone; "
+                f"see `python -c 'import zoneinfo; print(sorted(zoneinfo.available_timezones()))'` "
+                f"for the list this host supports"
+            )
+        return v
+
     @field_validator("llm_providers", mode="before")
     @classmethod
     def _parse_llm_providers(cls, v: Any) -> Any:

deeptrade_quant-0.8.0/deeptrade/core/dep_installer.py

@@ -0,0 +1,434 @@
+"""Plugin dependency resolution & installation.
+
+Called by :class:`PluginManager` during install / upgrade to satisfy a
+plugin's declared third-party Python dependencies (PEP 508 specifiers
+in ``deeptrade_plugin.yaml::dependencies``).
+
+Design context: ``CHANGELOG.md`` v0.4.0 (per-plugin Python dependency
+management; framework-interpreter install model rather than per-plugin venv).
+
+Key invariants:
+  * Plugins share the framework's Python interpreter — deps must be
+    importable from ``sys.executable``'s site-packages.
+  * Installer preference: ``uv`` (with ``--python <sys.executable>``) →
+    ``python -m pip``. Both missing → :class:`DepInstallError`.
+  * Conflicts (installed version not satisfying spec) are detected at
+    install time and raised, not silently overridden.
+  * Failed installs leave any already-installed deps in the environment
+    (do not unwind — common deps would be wrongly removed).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from datetime import datetime
+from importlib import metadata as importlib_metadata
+from pathlib import Path
+
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.utils import canonicalize_name
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_TIMEOUT_SECONDS = 300
+# Plan §2.6: dry-run preflight gets its own short timeout so a stuck `uv`
+# can't block the real install path.
+DRY_RUN_TIMEOUT_SECONDS = 60
+
+
+class DepInstallError(Exception):
+    """Dependency resolution, conflict, or install-subprocess failure."""
+
+
+@dataclass
+class DepConflict:
+    requirement: Requirement
+    installed_version: str
+    owner: str  # human-readable attribution string
+
+    def __str__(self) -> str:
+        return (
+            f"{self.requirement} not satisfied by installed "
+            f"{self.requirement.name}=={self.installed_version} (owner: {self.owner})"
+        )
+
+
+@dataclass
+class DepPlan:
+    to_install: list[Requirement] = field(default_factory=list)
+    skipped: list[tuple[Requirement, str]] = field(default_factory=list)
+    conflicts: list[DepConflict] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+
+def parse_specs(specs: Iterable[str]) -> list[Requirement]:
+    """Parse PEP 508 specifier strings into ``Requirement`` objects.
+
+    Rejects VCS/URL forms and duplicate package names. Same validation
+    as :meth:`PluginMetadata._dependencies_valid` — kept here so callers
+    that pre-validated metadata can reuse the parsed objects, and so
+    runtime code (not just Pydantic) reads idiomatically.
+    """
+    out: list[Requirement] = []
+    seen: dict[str, str] = {}
+    for raw in specs:
+        try:
+            req = Requirement(raw)
+        except InvalidRequirement as e:
+            raise DepInstallError(f"invalid dependency spec {raw!r}: {e}") from e
+        if req.url:
+            raise DepInstallError(
+                f"dependency {raw!r}: VCS/URL forms not allowed; use PEP 508 specifiers"
+            )
+        canonical = canonicalize_name(req.name)
+        if canonical in seen:
+            raise DepInstallError(
+                f"duplicate dependency {req.name!r} (also {seen[canonical]!r}); combine into one spec"
+            )
+        seen[canonical] = raw
+        out.append(req)
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Planning (satisfied / conflict / to-install)
+# ---------------------------------------------------------------------------
+
+
+def plan_install(
+    requirements: list[Requirement],
+    *,
+    attribute_conflict: Callable[[str], str | None] | None = None,
+) -> DepPlan:
+    """Sort each requirement into ``skipped`` / ``to_install`` / ``conflicts``.
+
+    ``attribute_conflict(canonical_name)`` returns a human-readable owner
+    (e.g. ``"framework core dependency"``, ``"plugin foo"``) for the package
+    when a conflict is detected. Falls back to ``"external (already in
+    environment)"`` if ``None`` or returns ``None``.
+
+    Marker-gated requirements (``"x>=1; python_version < '3.10'"``) whose
+    marker evaluates to False in the current environment are dropped.
+    """
+    plan = DepPlan()
+    for req in requirements:
+        if req.marker is not None and not req.marker.evaluate():
+            logger.debug("Skipping %s — marker did not match current env", req)
+            continue
+        try:
+            installed = importlib_metadata.version(req.name)
+        except importlib_metadata.PackageNotFoundError:
+            plan.to_install.append(req)
+            continue
+        if not req.specifier or req.specifier.contains(installed, prereleases=True):
+            plan.skipped.append((req, installed))
+            continue
+        owner = (
+            attribute_conflict(canonicalize_name(req.name)) if attribute_conflict else None
+        ) or "external (already in environment)"
+        plan.conflicts.append(DepConflict(req, installed, owner))
+    return plan
+
+
+# ---------------------------------------------------------------------------
+# Installer detection + subprocess invocation
+# ---------------------------------------------------------------------------
+
+
+def detect_installer() -> tuple[str, list[str]]:
+    """Return ``(label, argv_prefix)`` for the chosen installer.
+
+    Prefers ``uv`` (with ``--python <sys.executable>`` so packages land in
+    the framework's interpreter). Falls back to ``python -m pip``. Raises
+    :class:`DepInstallError` if neither is available.
+    """
+    uv_path = shutil.which("uv")
+    if uv_path:
+        return ("uv", [uv_path, "pip", "install", "--python", sys.executable])
+    try:
+        pip_check = subprocess.run(  # noqa: S603 — args fully controlled
+            [sys.executable, "-m", "pip", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        pip_check = None
+    if pip_check is not None and pip_check.returncode == 0:
+        return ("pip", [sys.executable, "-m", "pip", "install"])
+    raise DepInstallError(
+        "no installer available: neither 'uv' (on PATH) nor 'pip' (python -m pip) usable"
+    )
+
+
+def run_install(
+    requirements: list[Requirement],
+    *,
+    reinstall: bool = False,
+    timeout_seconds: int | None = None,
+) -> None:
+    """Spawn the installer subprocess. Raises :class:`DepInstallError` on
+    timeout, missing binary, or non-zero exit. stdout/stderr are inherited
+    so users see pip/uv progress in real time."""
+    if not requirements:
+        return
+    label, argv = detect_installer()
+    if reinstall:
+        argv.append("--upgrade")
+    argv.extend(str(r) for r in requirements)
+    timeout = timeout_seconds if timeout_seconds is not None else _resolved_timeout()
+    logger.info(
+        "Installing %d plugin dep(s) via %s: %s",
+        len(requirements),
+        label,
+        [str(r) for r in requirements],
+    )
+    try:
+        result = subprocess.run(  # noqa: S603 — args fully controlled
+            argv,
+            timeout=timeout,
+            text=True,
+        )
+    except subprocess.TimeoutExpired as e:
+        raise DepInstallError(
+            f"dependency install timed out after {timeout}s ({label}): "
+            f"{[str(r) for r in requirements]}"
+        ) from e
+    except FileNotFoundError as e:
+        raise DepInstallError(f"installer disappeared mid-run: {e}") from e
+    if result.returncode != 0:
+        raise DepInstallError(
+            f"{label} install failed (exit {result.returncode}) for: "
+            f"{[str(r) for r in requirements]}"
+        )
+
+
+def _resolved_timeout() -> int:
+    raw = os.environ.get("DEEPTRADE_DEP_INSTALL_TIMEOUT")
+    if raw is None:
+        return DEFAULT_TIMEOUT_SECONDS
+    try:
+        v = int(raw)
+        if v <= 0:
+            raise ValueError("must be positive")
+        return v
+    except ValueError:
+        logger.warning(
+            "Invalid DEEPTRADE_DEP_INSTALL_TIMEOUT=%r; using default %ds",
+            raw,
+            DEFAULT_TIMEOUT_SECONDS,
+        )
+        return DEFAULT_TIMEOUT_SECONDS
+
+
+# ---------------------------------------------------------------------------
+# v0.7 H6 — dry-run preflight + dep snapshot
+# ---------------------------------------------------------------------------
+
+
+def framework_core_canonicals() -> set[str]:
+    """Return canonical names of every direct dependency declared by the
+    installed ``deeptrade-quant`` distribution. Used by the dry-run
+    preflight (H6-a) to flag plugin installs that would silently mutate
+    framework deps.
+
+    Returns an empty set when the framework isn't installed via a wheel
+    (running from source without ``pip install -e``); the protection is
+    best-effort and shouldn't block development setups."""
+    try:
+        dist = importlib_metadata.distribution("deeptrade-quant")
+    except importlib_metadata.PackageNotFoundError:
+        return set()
+    out: set[str] = set()
+    for raw in dist.requires or []:
+        try:
+            req = Requirement(raw)
+        except InvalidRequirement:
+            continue
+        # Drop extras-only requirements (e.g. dev / plugin-runtime entries
+        # whose marker is "extra == 'dev'"). They are not part of the
+        # base install footprint we want to protect.
+        if req.marker is not None:
+            try:
+                if not req.marker.evaluate({"extra": ""}):
+                    continue
+            except Exception:  # noqa: BLE001 — marker eval edge cases
+                continue
+        out.add(canonicalize_name(req.name))
+    return out
+
+
+def _parse_dry_run_changes(text: str, watched: set[str]) -> set[str]:
+    """Pull canonical package names out of a uv dry-run output that appear
+    with a change-indicating marker. Returns names that intersect
+    ``watched``.
+
+    uv's dry-run lines we treat as "would touch the existing install":
+
+    * ``- pkg==ver``  — would remove (or downgrade away from current)
+    * ``~ pkg ...``    — would update/downgrade in place
+
+    ``+ pkg==ver`` lines are skipped because they represent a fresh
+    install — by definition that package wasn't already in the env, so it
+    cannot be a framework core dep currently in use."""
+    if not watched:
+        return set()
+    affected: set[str] = set()
+    for line in text.splitlines():
+        stripped = line.strip()
+        if len(stripped) < 3:
+            continue
+        if not (stripped.startswith("- ") or stripped.startswith("~ ")):
+            continue
+        # Grab the first whitespace-separated token after the marker,
+        # then trim any version suffix (``pkg==1.2.3`` → ``pkg``;
+        # ``pkg`` alone is also valid for the ``~`` "from a to b" form).
+        rest = stripped[2:].lstrip().split()[0].split("==", 1)[0]
+        if not rest:
+            continue
+        try:
+            canonical = canonicalize_name(rest)
+        except Exception:  # noqa: BLE001 — defensive against odd uv output
+            continue
+        if canonical in watched:
+            affected.add(canonical)
+    return affected
+
+
+def preflight_dry_run(
+    requirements: list[Requirement],
+    *,
+    watched: set[str] | None = None,
+    timeout_seconds: int = DRY_RUN_TIMEOUT_SECONDS,
+) -> set[str]:
+    """Best-effort preflight: run ``uv pip install --dry-run`` against
+    ``requirements`` and return the subset of ``watched`` (canonical
+    names) the install would upgrade / downgrade / remove.
+
+    Returns an empty set silently when:
+
+    * ``requirements`` is empty;
+    * ``uv`` is not on PATH (``pip`` has no equivalent dry-run shape);
+    * uv exits non-zero (let the real install path surface the real error);
+    * uv times out — we don't want to block on a stuck resolver.
+
+    The caller decides what to do with the affected names: in the v0.7
+    H6 plan, ``PluginManager._handle_dependencies`` raises ``DepInstallError``
+    when the set is non-empty and ``--allow-core-bump`` wasn't passed."""
+    if not requirements:
+        return set()
+    if watched is None:
+        watched = framework_core_canonicals()
+    if not watched:
+        return set()
+
+    uv_path = shutil.which("uv")
+    if not uv_path:
+        # ``pip`` has no analogous structured dry-run output; fall back to
+        # no preflight rather than block the install path.
+        return set()
+
+    argv = [uv_path, "pip", "install", "--dry-run", "--python", sys.executable]
+    argv.extend(str(r) for r in requirements)
+    try:
+        result = subprocess.run(  # noqa: S603 — args fully controlled
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout_seconds,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+        logger.warning("uv dry-run preflight skipped: %s", e)
+        return set()
+
+    if result.returncode != 0:
+        logger.info(
+            "uv dry-run exited %d; skipping core-bump preflight (real install "
+            "will surface the underlying resolver error)",
+            result.returncode,
+        )
+        return set()
+
+    # uv prints the change plan to stderr; stdout used as fallback for
+    # uv versions that route it differently.
+    output = result.stderr or result.stdout or ""
+    return _parse_dry_run_changes(output, watched)
+
+
+def _snapshot_argv() -> list[str] | None:
+    """Pick the freeze-list command to use for snapshots.
+
+    Mirrors :func:`detect_installer` priority: prefer ``uv pip list``
+    (works on uv-managed venvs which often ship without pip) and fall
+    back to ``python -m pip list``. Returns ``None`` when neither path
+    is usable — snapshot becomes a no-op rather than blocking install."""
+    uv_path = shutil.which("uv")
+    if uv_path:
+        return [uv_path, "pip", "list", "--python", sys.executable, "--format=freeze"]
+    try:
+        check = subprocess.run(  # noqa: S603 — args fully controlled
+            [sys.executable, "-m", "pip", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return None
+    if check.returncode == 0:
+        return [sys.executable, "-m", "pip", "list", "--format=freeze"]
+    return None
+
+
+def write_dep_snapshot(plugin_id: str, dir_root: Path) -> Path | None:
+    """Capture a ``pip list --format=freeze`` baseline to
+    ``<dir_root>/<plugin_id>/pre-install-<UTC-ISO>.txt`` so users have a
+    point-in-time record to diff against when an install goes sideways.
+
+    The snapshotting subprocess prefers ``uv pip list`` (uv venvs often
+    ship without pip) and falls back to ``python -m pip list``. Returns
+    the file path on success; ``None`` if neither is available or the
+    write failed (best-effort — never aborts install)."""
+    argv = _snapshot_argv()
+    if argv is None:
+        logger.warning("dep snapshot skipped — neither uv nor pip is usable for `pip list`")
+        return None
+    try:
+        proc = subprocess.run(  # noqa: S603 — args fully controlled
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=DRY_RUN_TIMEOUT_SECONDS,
+        )
+    except (subprocess.TimeoutExpired, FileNotFoundError) as e:
+        logger.warning("dep snapshot skipped — list subprocess failed: %s", e)
+        return None
+    if proc.returncode != 0:
+        logger.warning(
+            "dep snapshot skipped — list exited %d:\n%s",
+            proc.returncode,
+            (proc.stderr or "").strip(),
+        )
+        return None
+
+    target_dir = dir_root / plugin_id
+    target_dir.mkdir(parents=True, exist_ok=True)
+    # Use UTC for the filename so multi-host installs collated from one
+    # NAS sort sensibly; safe-ish for filenames across OSes (no ``:``).
+    ts = datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
+    path = target_dir / f"pre-install-{ts}.txt"
+    try:
+        path.write_text(proc.stdout, encoding="utf-8")
+    except OSError as e:
+        logger.warning("dep snapshot write failed: %s", e)
+        return None
+    return path