docs: record Stage 2, and the two decisions that bind S3
A Stage 2 table in ROADMAP Phase 2 in the shape of Stage 1's: what landed, the four bugs that were not in the plan, and the decisions a later slice has to honour. Three of those four were found by running — timing the probe, doing one real `pip install -e`, and logging what actually crossed the bridge. CLAUDE.md's "run it, don't just test it" note now carries both stages' tallies, because the pattern has held across every slice so far and is the single most useful thing to know before starting the next. Two S2 decisions are called out where S3 will actually read them. "N pinned excluded" in the table is presentation and S3's preview must use the flow's `excluded_pins()` instead, or the two numbers drift. And row state is three-valued because one of its two sources is networked — anything rendering package state inherits that obligation. Also added: `probe.py` is on the hot path. The Installed screen re-probes on every environment open, so anything added to `_dists()` is paid 200+ times per open — which is how an innocuous-looking `Distribution.files` became a 10× regression. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
a9363e91d5
commit
e81dd1c811
2 files changed
+68
-13
No files matched your search
@@ -61,14 +61,23 @@ Every caller needs an explicit `permissions:` block — callers without one defa
|
||||
|
||||
## Current state
|
||||
|
||||
**M1 complete. M2 Stage 1 (the IPC bridge) complete 2026-07-30.** The app runs: legal gate →
|
||||
Environments → Settings, over real commands. `docs/ROADMAP.md` Phase 2 has the full Stage 1 table
|
||||
and says where to pick up — read it before starting a slice.
|
||||
**M1 complete. M2 Stage 1 (IPC bridge) complete 2026-07-30; Stage 2 (Installed + Updates)
|
||||
complete 2026-08-04.** The app runs: legal gate → Environments → Installed → Updates → Settings,
|
||||
over real commands. `docs/ROADMAP.md` Phase 2 has the Stage 1 and Stage 2 tables and says where to
|
||||
pick up — read it before starting a slice.
|
||||
|
||||
Next is **S2** (Installed + Updates, read-only), then **S3** (the mutation spine, the biggest
|
||||
slice). Three things are deliberately deferred to the slice that can verify them, and ROADMAP
|
||||
Phase 2 lists them: the `plan-progress` lifecycle enum, a Windows Job Object for whole-tree kill,
|
||||
and the post-cancel summary copy.
|
||||
Next is **S3, the mutation spine** — the biggest and riskiest slice. Three things are deliberately
|
||||
deferred to it because it is the first slice that can verify them: the `plan-progress` lifecycle
|
||||
enum, a Windows Job Object for whole-tree kill, and the post-cancel summary copy.
|
||||
|
||||
Two S2 decisions bind S3 directly:
|
||||
|
||||
- **"N pinned excluded" in the table is presentation, not enforcement.** DATA-FLOW §9.5 is enforced
|
||||
by `pins::filter_upgrades` at the plan boundary. S3's preview must show the flow's
|
||||
`excluded_pins()`, not the number the table computed, or the two will drift.
|
||||
- **Row state is three-valued** (`unknown` / `current` / `outdated`), because `pkg_list` is local
|
||||
and `pkg_outdated` is networked. Anything that renders package state has the same obligation:
|
||||
never assert a state you have not actually loaded yet.
|
||||
|
||||
Things worth knowing before you change any of it:
|
||||
|
||||
@@ -79,10 +88,16 @@ Things worth knowing before you change any of it:
|
||||
They are what made the `core::flow` refactor provably behaviour-preserving.
|
||||
- **Two tests hold the wire format**: `Code::ALL` must serialize as `as_str()`, and no
|
||||
`SCHEMA_TYPES` property may contain `_`. Both fail at `cargo test`.
|
||||
- **Run it, don't just test it.** Every one of the four unplanned bugs found during Stage 1 came
|
||||
from executing against a real environment or a real runner, not from reading code or passing
|
||||
tests: the watchdog that never killed anything, `--json` that never parsed, attribution that
|
||||
told 3.12 users something false, and a drift job that could not go green.
|
||||
- **Run it, don't just test it.** Every unplanned bug in Stage 1 *and* Stage 2 came from executing
|
||||
against a real environment, a real runner or a real browser — never from reading code or from a
|
||||
passing suite. Stage 1: the watchdog that never killed anything, `--json` that never parsed,
|
||||
attribution that told 3.12 users something false, a drift job that could not go green. Stage 2:
|
||||
a probe 10× slower than before (found by timing it), a size that was *wrong* rather than missing
|
||||
for editable installs and a package listed twice (both found by one real `pip install -e`), and
|
||||
every screen fetching twice on mount (found by logging what actually crossed the bridge).
|
||||
- **`probe.py` is on the hot path.** The Installed screen re-probes on every environment open, so
|
||||
anything added to `_dists()` is paid 200+ times per open. `Distribution.files` looks harmless and
|
||||
costs 10×; read the metadata files directly and measure before committing.
|
||||
|
||||
## Things that look like bugs but are not
|
||||
|
||||
|
||||
+42
-2
@@ -149,9 +149,49 @@ Ten commits, `0ccee04..a553bf7`. Everything M2's screens stand on now exists, an
|
||||
|
||||
**Four bugs turned up that were not in the plan**, all found by running things rather than reading them: the watchdog leak; `--json` unparseable because `snapshot … written` went to stdout; blocker attribution naming constraints from other Pythons (the SP-5 dogfood); and `updater:default` granted to a plugin whose pubkey was a placeholder.
|
||||
|
||||
### Stage 2 onward — where to pick up
|
||||
### Stage 2 — Installed + Updates (read-only) — **done 2026-08-04**
|
||||
|
||||
Slices, sizing and exit checks are in the plan; the order is **S2 → S3 → S4 → S5 → S6 → S7**. S2 (Installed + Updates, read-only) is next and needs a virtualization library — `@tanstack/react-virtual` is the recommendation, and any addition must survive `npm audit --audit-level=high`.
|
||||
Three PRs, `d7da4d7..`. Both screens render from a real environment, and the slice's exit criteria
|
||||
are met.
|
||||
|
||||
| | What landed |
|
||||
|---|---|
|
||||
| **Docs** | ARCHITECTURE §7's command list rewritten as a table of **32** — it was prose with `a\|b\|c` groupings, ambiguous enough that Stage 1 added `app_info` and `plan_decide` without amending it. Closes open owner decision #1. DATA-FLOW §7's "List installed" row corrected: it claimed an engine command **neither head has ever called**. |
|
||||
| **Core** | `engine::for_id` — the CLI held the only copy of engine selection plus a duplicate `KEY_ENGINE` and a byte-for-byte copy of `store::default_app_data`. `Dist.sizeBytes`, summed from RECORD. `PkgName` validates on deserialize. |
|
||||
| **Bridge** | `pkg_list`, `pkg_outdated`, `pin_list\|add\|remove`, registered and wrapped. `pkg_list` reads the probe, not the engine; both take a `PyEnv` so the outdated path never probes. |
|
||||
| **UI** | `PdBadge`, `PdEmptyState`, `PdPackageRow`, `PdPackageTable` (virtualized) — 8 of 16 components now exist. One screen serving both tabs, `useEnvStore` grown, EN+VI catalogs, `Space`/`Ctrl+A`. |
|
||||
| **L3** | The repo's first rendered-component tests, fed from fixtures generated out of the real Rust types by `cargo run -p xtask -- ipc-fixtures` and held current by a staleness test. |
|
||||
|
||||
**Four bugs turned up that were not in the plan, three of them found by running:**
|
||||
|
||||
1. **`Distribution.files` is a 10× trap.** The obvious way to sum RECORD took the probe from 551 ms
|
||||
to **5,492 ms** on a 352-package environment — on the path the Installed screen runs on every
|
||||
environment open. Parsing RECORD text directly costs 79 ms.
|
||||
2. **The naive size is wrong for editables, not merely missing.** A PEP 660 install has a *valid*
|
||||
RECORD listing only its import shim: **240 bytes for a package whose sources are 8.1 MiB**.
|
||||
Detected via `direct_url.json` and reported as absent, because a wrong number is worse than none.
|
||||
3. **A distribution could be listed twice.** An editable puts its own `.egg-info` on `sys.path`, so
|
||||
`importlib.metadata` finds it there *and* at the venv's `.dist-info`. `pip list` shows it once.
|
||||
For the table it is an ambiguous join key and two rows a user cannot tell apart.
|
||||
4. **Every screen fetched twice on mount.** React runs effects twice in development and the
|
||||
`loadedFor` guard is set only *after* the await, so both runs proceed. `env_scan` had done this
|
||||
since Stage 1, invisibly, because both scans return the same rows.
|
||||
|
||||
**Two decisions worth knowing before S3:**
|
||||
|
||||
- **Row state is three-valued, not two.** `pkg_list` is local, `pkg_outdated` is networked, so there
|
||||
is a window where outdatedness is unknown. Treating it as "up to date" dims all 200 rows and
|
||||
un-dims a handful a second later — visibly wrong, and untrue while it lasts.
|
||||
- **"N pinned excluded" is presentation, not enforcement.** DATA-FLOW §9.5 is enforced by
|
||||
`pins::filter_upgrades` at the plan boundary. **S3's preview must report the flow's
|
||||
`excluded_pins()`, not the number the table computed.**
|
||||
|
||||
Also resolved: UI-SPEC §8's "select-all-visible", which has no meaning under virtualization. It is
|
||||
the current filtered set, and §8 now says so.
|
||||
|
||||
### Stage 3 onward — where to pick up
|
||||
|
||||
Slices, sizing and exit checks are in the plan; the order is **S2 → S3 → S4 → S5 → S6 → S7**. S2 is done (above); **S3, the mutation spine, is next** — it is the biggest and riskiest slice, and the one everything since Stage 1 has been building toward.
|
||||
|
||||
Three things are deliberately deferred and should be picked up **with the slice that can verify them**, not before:
|
||||
|
||||
|
||||
Reference in new issue
Block a user