18 fixtures (9 scenarios x 2 engines) plus a reproducible capture harness. Findings written up in spikes/README.md and summarised in the ROADMAP Phase 0 table. Verdict: GO for shipping both engines, but for a different reason than the roadmap anticipated. SP-1 asked whether uv's plan output is too lossy to ship uv in v1.0. The question turned out to be the wrong shape. Neither engine holds packages back on `install -U <pkg>` — seeded with httpx 0.23.0, which requires httpcore<0.16, both pip and uv plan httpcore 1.0.9 and exit 0, silently breaking it. Restating the installed set as explicit requirements is what produces the correct held-back plan. That makes it a hard requirement on both adapters, not an optimisation: without it PipDock would preview a plan that breaks the environment. uv also writes its entire plan to stderr, and its conflict attribution is markedly better than pip's — uv names the exact blocking constraint where pip says only that versions conflict. SP-2 found a blocker. `pip install --dry-run --report -` crashes with UnicodeEncodeError on Windows under cp1252, because pip routes the report JSON through vendored rich and the console codec. Confirmed on pip 25.0.1 and 26.1.2, so it is current, not legacy. It is data-dependent — an all-ASCII report succeeds — which means it would pass local testing and fail on users' machines. PYTHONIOENCODING=utf-8 plus PYTHONUTF8=1 fixes it, and the crash is kept as a fixture so a regression is recognisable. Also: yanked releases exit 0 in both engines, so PD-PKG-003 belongs in the preview as a warning rather than in the failure path the catalog implies; and the two engines disagree on Requires-Python enforcement. SP-3 passes: 858k projects, 2.95s cold refresh against a 60s budget, 42.1ms worst keystroke against 50ms. But only in memory — scanning SQLite per keystroke costs 218ms, four times over. Two cautions recorded: 16% headroom on fast hardware is thin for the low-end VM the spike asked about, and raw nucleo ranking puts requests-ntlm above requests, so the Search screen needs an exact/prefix boost to be usable. SP-4 confirms SECURITY section 6 as written: --path cannot combine with --no-deps, so freeze-file mode is the only option for a foreign env. SP-5 is answered by SP-1 — no engine reports held-back items at all, so resolved version, latest version and blocker must all be derived by PipDock, for pip as much as for uv. SP-6 avoided two identity bugs. `uv python list` returns downloadable entries and shims that duplicate real interpreters, and the same interpreter reports different path casing depending on how it was launched, so env_hash must lowercase on Windows or a single environment silently splits its pins and snapshot history in two. Microsoft Store Python is not installed here and remains unverified. Four decisions are queued for the owner at the end of spikes/README.md; two of them change adapter behaviour and should land before M1. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
6.1 KiB
PipDock — Roadmap
Version 0.1 · 2026-07-17
Phase 0 — Spike week (before any feature code) — RUN 2026-07-27
The entire architecture stands on assumptions that must be verified on a real machine first (the FrameLedger/QuoteAtlas discipline). Each spike is a small script + captured fixtures committed to crates/pipdock-core/tests/fixtures/.
Outcomes — full write-up in spikes/README.md.
| Spike | Verdict | The one thing that changed |
|---|---|---|
| SP-1 | GO — ship both engines | Neither engine holds packages back on install -U <pkg>; both silently break installed dependents. Every plan must restate the full installed set as explicit requirements. uv's conflict attribution is better than pip's; uv writes its plan to stderr, not stdout. uv minimum pinned at 0.10.0. |
| SP-2 | Corpus captured; blocker found and fixed | pip install --dry-run --report - crashes with UnicodeEncodeError on Windows/cp1252 (pip 25 and 26). Every pip invocation must set PYTHONIOENCODING=utf-8 + PYTHONUTF8=1. Also: yanked releases exit 0 (a preview warning, not a failure), and pip/uv disagree on Requires-Python enforcement. |
| SP-3 | PASS | 858 k projects; cold refresh 2.95 s (budget 60 s); worst keystroke 42.1 ms (budget 50 ms) — but only in memory: scanning SQLite per keystroke costs 218 ms. Margin is thin on fast hardware, and raw nucleo ranking puts requests-ntlm above requests. |
| SP-4 | Answered | --path cannot be combined with --no-deps; freeze-file mode (-r <freeze> --no-deps -f json) is the only option. SECURITY §6 confirmed. Findings arrive with duplicate advisory ids. |
| SP-5 | Answered by SP-1 | No engine reports held-back items at all. Resolved version, latest version and blocker must all be derived by PipDock — for pip as much as for uv, contrary to ARCHITECTURE §3's implication. |
| SP-6 | Answered | uv python list returns downloadable entries and duplicate shims; env_hash must lowercase the interpreter path on Windows or pins and snapshots split in two. probe.py -I hides 24 user-site packages on a system Python — open decision. Microsoft Store Python still unverified. |
Four open questions for the owner are listed at the end of spikes/README.md; M1 should not start until at least the Requires-Python and -I decisions are made, since both change adapter behaviour.
| # | Spike | Question to answer | Exit criterion |
|---|---|---|---|
| SP-1 | uv dry-run shape | Exact stdout of uv pip install -U --dry-run (current + previous uv) across: clean upgrade, held-back, impossible. Is held-back attribution derivable, or does uv only show the resolved set? |
Fixture set committed; adapter parsing strategy written; uv minimum version pinned. Go/no-go for launching with both engines — if uv's plan output is too lossy, v1.0 ships pip-primary with uv behind a "beta engine" flag. |
| SP-2 | pip report & stderr corpus | Capture --dry-run --report JSON + real stderr for every ERROR-CATALOG build/network/permission case (broken sdist, MSVC-missing, PEP 668, locked file, yanked, hash mismatch). |
≥ 1 fixture per launch catalog code. |
| SP-3 | PEP 691 index economics | Full name-index size, download time on VN broadband, SQLite ingest time, fuzzy-search latency on ~600 k names. | < 60 s cold refresh, < 50 ms search on the i7-14700KF and on a low-end reference VM; else design delta/compression fallback. |
| SP-4 | pip-audit foreign-env mode | Correct invocation for auditing an env the tool isn't installed in (freeze-file --no-deps vs newer options). |
Command line + JSON fixture pinned (P1 feature, but flags decided now). |
| SP-5 | Held-back attribution accuracy | On a real numpy/scipy/pandas pin tangle: does graph-based blocker attribution match reality? | Preview sentences verified by hand against the tangle; ambiguity fallback path exercised. |
| SP-6 | Windows env discovery sweep | PEP 514 registry + py -0p + Microsoft Store Python + uv-managed on a real machine; Store-Python aliasing quirks. |
Discovery module design note updated; Store Python either supported or explicitly detected-and-explained. |
Phase 1 — M1 "Core + CLI" (~3–4 weeks)
Engine trait + both adapters (per SP-1 outcome), probe.py, discovery, index cache + search, plan/resolve/execute two-phase, snapshots, pins, guard graph, error catalog, CLI over all of it. Exit: TESTING L1+L2+L4 green in CI; pipdock update --all survives the SP-5 tangle env with correct summary; dogfood on Kokone's own bot venvs begins.
Phase 2 — M2 "GUI shell + core flows" (~3–4 weeks)
Tauri app, design tokens, Environments/Installed/Updates/Search/Pins screens, preview + 3-way conflict UX, console drawer, summary sheet, snapshots UI, legal gate, EN/VI catalogs, settings. Exit: all UI-SPEC click budgets met by manual count; L3 green; VI sweep clean.
Phase 3 — M3 "Health + polish" (~2 weeks)
Tools venv, deptry/vulture/ruff runners + report UI + gated fix, pip upkeep, bug-report deep link, offline states, keyboard map, icon/branding pass. Exit: CODE-HEALTH flows pass on two real projects (one pyproject, one requirements-only).
Phase 4 — RC → v1.0 (~1–2 weeks)
Release pipeline live (signing, updater, checksums), manual charter executed, docs/README screenshots, legal files public, updater tested from RC→GA. Exit: RELEASE-CI §5 checklist fully checked; v1.0.0 published + notify fan-out.
Post-1.0 (P1 wave)
Security tab (pip-audit), pin auto-suggest, requirements/constraints export-import, cache manager, command palette, dependency graph view, scheduled check. Then P2 candidates by demand: macOS/Linux, per-env engine, elevation broker, winget, JP locale.
Standing risks
| Risk | Mitigation |
|---|---|
| uv output churn between releases | weekly latest-engine parser CI job (TESTING L1) + PD-ENG-003 graceful degrade + "switch to pip" escape hatch |
| pip UX flags deprecations (e.g. report format changes) | same job covers pip; adapter version-gates per engine version |
| Index size growth | SP-3 fallback design kept in the drawer |
| Scope creep from Health into a linter IDE | CODE-HEALTH §7 non-goals are contractual |