docs: record Stage 6, and the DATA-FLOW §8 step nothing performs
DATA-FLOW §8 has always listed "dry-run resolve the restore set" between the plan and the snapshot, and **neither head has ever done it**. S6 did not add it, so §8 now says which part is real: `RollbackFlow` diffs, plans, and reports the entries no index can supply — but it does not ask the engine whether each restore spec is still fetchable, so a release yanked since the snapshot surfaces at execute time. Adding it is a network round trip on an interaction budgeted as instant, and it would resolve against the *pre-removal* environment, reporting conflicts the two-phase execution never hits. It needs its own design and belongs with M3's engine work. Until then the preview's promise is precise rather than broad: it lists what *cannot* be restored, not everything that might fail. UI-SPEC §4 records why the env detail is a mode of the Environments tab rather than a ninth sidebar entry (§8 fixes `Ctrl+1..8`), why the trigger label is load-bearing rather than decoration, and why the diff copy names a direction — "added" is ambiguous the moment you read it from the snapshot's side. §5's rollback row gains the real path and the 2-click route from a summary. §6 goes to 14 of 16, `PdSnapshotTimeline` having arrived; `PdEnvSwitcher` is now the only one absent that is not M3's, and nothing needs it. TESTING §2's L1 list gains the partition property, which is the one a rollback preview actually stands on. ROADMAP's Stage 6 table records the four bugs, three of which no test written for them would have found: the uncancellable restore loop, the freeze lines both parsers dropped, `snapshot_list` firing twice, and the rollback that left the timeline empty. CLAUDE.md: Stages 1–6, goldens 52 → 54, and the rule S6 leaves behind — two slices that key on different things need two resets. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
a3ad170c00
commit
8042bdb5f8
5 files changed
+95
-19
No files matched your search
@@ -64,17 +64,16 @@ Every caller needs an explicit `permissions:` block — callers without one defa
|
||||
|
||||
## Current state
|
||||
|
||||
**M1 complete. M2 Stages 1–5 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine
|
||||
**M1 complete. M2 Stages 1–6 done** (IPC bridge 2026-07-30; Installed+Updates, the mutation spine
|
||||
and search+install all 2026-08-04). The app discovers, lists, previews, decides, executes, streams,
|
||||
summarises and installs over real commands. **"Update everything" is 4 clicks and "install one" is
|
||||
4 clicks**, both counted by hand in the running app; search is **22 ms median per keystroke**
|
||||
against a 50 ms budget. All 16 of UI-SPEC §6's components exist. `docs/ROADMAP.md` Phase 2 has a
|
||||
table per stage and says where to pick up; read it before starting a slice.
|
||||
|
||||
Next is **S6 — snapshots, the env detail and rollback**. S5 landed `Session::Rollback` and
|
||||
`RollbackFlow::cancel_handle`, so S6 adds a call site rather than another widening; what it needs is
|
||||
`RollbackPreview` crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4
|
||||
assumes and which does not exist.
|
||||
Next is **S7 — the shell: i18n, keyboard, a11y, the error row**. Its largest piece is the one
|
||||
nobody has counted: **26 of the 32 catalog codes have no one-liner in either locale**, so they
|
||||
render as "An unexpected error occurred." with a code.
|
||||
|
||||
Three rules from S2/S3 that bind everything after them:
|
||||
|
||||
@@ -89,6 +88,12 @@ Three rules from S2/S3 that bind everything after them:
|
||||
(inside core) it serializes every other command behind a network call. Read what you need, drop
|
||||
the guard, then await. This is why `UpdateFlow::start` takes pins rather than a `&Store`, and why
|
||||
`index::metadata`/`refresh` take the app-data path. It has bitten twice; assume it will again.
|
||||
- **Two slices that key on different things need two resets.** The package slice is keyed to the
|
||||
*selected* environment and the snapshot timeline to the *open* one, and they move independently —
|
||||
so folding the timeline into `NO_PACKAGES` meant a rescan wiped a freshly-loaded timeline whenever
|
||||
the package slice happened to be stale. After a rollback that is exactly the case. A shared reset
|
||||
constant is only correct for fields with a shared key.
|
||||
|
||||
- **A dialog is not an enforcement point.** DATA-FLOW §5's three options are what the user *sees*;
|
||||
what stops a removal is `GuardAck` inside `UninstallFlow::execute`, beside `SnapshotProof`. The
|
||||
same shape twice: the report and the proof are produced in one call and consumed in another, so
|
||||
@@ -104,7 +109,7 @@ Things worth knowing before you change any of it:
|
||||
|
||||
- **`cargo test` fails when `ui/src/ipc/generated.ts` is stale.** Fix with
|
||||
`cargo run -p xtask -- bindings`; the failure names that command and the first differing line.
|
||||
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 52 snapshots) are the CLI's output
|
||||
- **The L4 goldens (`crates/pipdock-cli/tests/golden.rs`, 54 snapshots) are the CLI's output
|
||||
contract.** A diff there is a real behaviour change — re-bless deliberately, never reflexively.
|
||||
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
|
||||
|
||||
@@ -135,6 +135,18 @@ Snapshot selected → Diff = (current freeze) vs (snapshot freeze)
|
||||
→ snapshot current state first (rollback is itself reversible) → execute two-phase → summary
|
||||
```
|
||||
|
||||
**The dry-run resolve step is implemented in neither head**, and S6 deliberately did not add it.
|
||||
`RollbackFlow::start` diffs, plans, and reports `unrestorable_lines` — the entries no index can
|
||||
supply, which is what the preview lists as `PD-SNP-002`. What it does *not* do is ask the engine
|
||||
whether each restore spec is still fetchable, so a release yanked since the snapshot was taken
|
||||
surfaces as a per-package failure at execute time rather than in the preview.
|
||||
|
||||
Adding it is a network round trip on an interaction budgeted as instant, and it would resolve
|
||||
against the *pre-removal* environment — reporting conflicts the two-phase execution never hits,
|
||||
because the removals happen first. It needs its own design, and it belongs with the engine work in
|
||||
M3 rather than bolted onto a preview. Until then the preview's promise is precise: it lists what
|
||||
*cannot* be restored, not everything that might fail.
|
||||
|
||||
## 9. Data-flow invariants (enforced in `pipdock-core`, tested)
|
||||
|
||||
1. No mutating engine call without an **accepted proof** for this session: a `ResolutionReport` for
|
||||
|
||||
+48
-7
@@ -310,14 +310,55 @@ session", which the uninstall path cannot produce — there is nothing to resolv
|
||||
proof per plan shape, so the one flow with no preview is no longer the one flow the invariant did not
|
||||
describe.
|
||||
|
||||
### Stage 6 onward — where to pick up
|
||||
### Stage 6 — snapshots, the env detail and rollback — **done 2026-08-09**
|
||||
|
||||
The order is **S5 → S6 → S7**, then Phase 3. S5 is done (above). **S6 — snapshots, the env detail and
|
||||
rollback — is next.** `Session::Rollback` and `RollbackFlow::cancel_handle` already landed in S5, so
|
||||
S6 adds a constructor call site rather than another widening; what it needs is `RollbackPreview`
|
||||
crossing IPC, the five `snapshot_*` commands, and the env-detail surface UI-SPEC §4 assumes and which
|
||||
does not exist. Exit: rollback = 4 clicks, and the preview lists `unrestorable_lines` explicitly as
|
||||
`PD-SNP-002` rather than dropping them.
|
||||
Eight commits. Every snapshot the app has been writing since S1 is now reachable from it, and P0-8
|
||||
is complete in both heads.
|
||||
|
||||
| | What landed |
|
||||
|---|---|
|
||||
| **Core** | `RollbackPreview` and `RollbackPlan` cross IPC; `snapshot::Meta` gains a schema rename so embedding it does not mint a second interface. `parse_freeze` and `unrestorable_lines` rebuilt on one classifier. |
|
||||
| **Bridge** | `snapshot_list\|create\|diff\|rollback_preview\|rollback`. ARCHITECTURE §7's single rollback row becomes two, 32 → 33. |
|
||||
| **UI** | `PdSnapshotTimeline`, `PdRollbackPreview`, the env detail as a *mode* of the Environments tab, the diff viewer, and the rollback the summary's copy has promised since S3. |
|
||||
| **L3** | Two more generated fixtures; 9 → 11 test files, 79 → 91 tests. Goldens 52 → 54. |
|
||||
|
||||
**Exit criteria, verified by running.** At the CLI against a real venv: create → mutate → `snapshot
|
||||
rollback <id>` → `snapshot diff <id>` prints *environment matches snapshot* — PRD §6's metric, and
|
||||
the timeline afterwards shows the `rollback of …` entry above the one it restored, which is
|
||||
`latest` moving twice, live. In the app: **rollback = 4 clicks** (Open → entry → *Rollback…* →
|
||||
*Roll back*), 2 from a run's summary; the preview lists `PD-SNP-002` with the verbatim freeze line
|
||||
**before** the confirm.
|
||||
|
||||
**Four bugs, three of which no test would have found:**
|
||||
|
||||
1. **A cancelled rollback killed the package in flight and installed the rest.** The restore loop
|
||||
had no token check — S5 gave one to the removal half and not to the install half. Found by
|
||||
writing the cancellation test the plan asked for.
|
||||
2. **`parse_freeze` and `unrestorable_lines` did not partition their input.** Two independent
|
||||
filters that disagreed: a line like `Foo Bar==1.0` was dropped by both and vanished. In a
|
||||
rollback preview, whose whole job is saying what it cannot put back, that silence is the worst
|
||||
possible failure.
|
||||
3. **`snapshot_list` fired twice on open** — Stage 2's double fetch, reintroduced exactly, because
|
||||
the guard is written after the await. Invisible in the UI, since both calls return the same rows.
|
||||
4. **A rollback left the timeline empty.** The refetch and the rescan race, and the rescan wiped the
|
||||
result: the snapshot fields were inside `NO_PACKAGES`, whose reset is keyed to the *package*
|
||||
slice's environment. The two slices key on different things and now reset separately.
|
||||
|
||||
**Deliberately not done:** DATA-FLOW §8's dry-run resolve of the restore set, which is implemented
|
||||
in **neither** head. It is a network round trip on an interaction budgeted as instant, and it would
|
||||
resolve against the pre-removal environment — reporting conflicts the two-phase execution never
|
||||
hits. §8 now says so, and the preview's promise is precise instead: it lists what *cannot* be
|
||||
restored, not everything that might fail. Snapshot retention (`snapshot::delete` + keep-N) also
|
||||
stays out; a destructive command against the user's only way back needs its own confirm.
|
||||
|
||||
### Stage 7 onward — where to pick up
|
||||
|
||||
The order is **S5 → S6 → S7**, then Phase 3. S5 and S6 are done (above). **S7 — the shell: i18n,
|
||||
keyboard, a11y, the error row — is next**, and its largest piece is the one nobody has counted:
|
||||
**26 of the 32 catalog codes have no one-liner in either locale**, so they render as "An unexpected
|
||||
error occurred." with a code. Exit: every `Code::ALL` variant has copy in EN and VI, the
|
||||
pseudo-locale shows no clipping, the VI sweep of every mutation dialog is clean, the token contrast
|
||||
test survives the font change, and every `Ctrl+1..8` works.
|
||||
|
||||
**All three Stage 1 deferrals are closed**, each in S3 as planned — the `plan-progress` lifecycle enum, the Windows Job Object, and the `ExecutionSummary.cancelled` copy. Deferring them to the slice that could verify them worked: each was finished against a running UI or a real process tree rather than against a guess.
|
||||
|
||||
|
||||
+1
-1
@@ -17,7 +17,7 @@
|
||||
- **Parser fixtures:** captured real outputs under `tests/fixtures/{pip,uv}/{list,outdated,report,errors}/…` (seeded by spikes SP-1/SP-2, grown from every new engine release and every triaged bug). `insta` snapshot tests assert the normalized `ResolutionReport`. A CI job runs the capture script against the *latest* engine versions weekly and fails on unrecognized shapes → PD-ENG-003 before users hit it.
|
||||
- **Error classifiers:** every catalog code has ≥ 1 stderr fixture; a test enforces "no code without fixture."
|
||||
- **Graph:** reverse-dep construction and blocker attribution over synthetic metadata sets, including cycles and extras (`pkg[extra]`) markers.
|
||||
- **Snapshot diff/rollback planner:** property-style tests — `apply(plan(diff(a,b)), b) == a` over generated freeze pairs.
|
||||
- **Snapshot diff/rollback planner:** property-style tests — `apply(plan(diff(a,b)), b) == a` over generated freeze pairs, and the **partition**: every significant freeze line is either parsed into a pin or reported unrestorable, never neither. The second is the one a rollback preview stands on — a line both functions dropped disappeared silently, and the preview then promised a restore it could not perform.
|
||||
- **Name/spec validation:** PEP 508/440 accept/reject tables.
|
||||
|
||||
### L2 — Engine integration (disposable venvs, Windows CI runner)
|
||||
|
||||
+23
-5
@@ -76,6 +76,22 @@ packages depend on it. Pin?".
|
||||
|
||||
**Snapshots** (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), `Rollback…` with its own preview per DATA-FLOW §8.
|
||||
|
||||
The detail view is a **mode of the Environments tab**, not a ninth sidebar entry — §8 fixes
|
||||
`Ctrl+1..8` to the eight that exist, and a ninth would renumber every shortcut after it. Which
|
||||
environment is open lives in `useEnvStore`, because the plan panel replaces the whole content area
|
||||
while a rollback runs and component state would be unmounted with it.
|
||||
|
||||
The **trigger label is load-bearing**, not decoration. A restore snapshots the current state before
|
||||
restoring, so one rollback moves `latest` twice and two entries a minute apart are otherwise
|
||||
indistinguishable — while one is the state the user wants back and the other is the state they are
|
||||
leaving. Nothing in the UI ever names `latest`; the timeline hands ids to every command.
|
||||
|
||||
An environment whose interpreter is gone still reaches the detail view: snapshots are keyed by
|
||||
`env_hash` and outlive the Python that made them, so the timeline lists while the diff and the
|
||||
rollback are disabled with a line saying why. The diff's copy names the *direction* — "here but not
|
||||
in the snapshot — restoring removes it" — because "added" is ambiguous the moment you read it from
|
||||
the snapshot's side.
|
||||
|
||||
**Health.** Project-folder picker (persisted per env) → run panel with three result tabs (deptry / vulture / ruff) per CODE-HEALTH-SPEC; `Fix with ruff` gated behind explicit confirm listing file count.
|
||||
|
||||
**Settings.** Engine (pip/uv radio + detected versions), locale (EN/VI), thresholds (pin auto-suggest count, snapshot retention), index refresh, PEP 668 override (off by default, scary copy), *Open logs folder*, *Legal & About* (links to GitHub legal docs + re-open legal gate).
|
||||
@@ -93,7 +109,7 @@ app lands. Counted by hand in the running app, never inferred from the markup.
|
||||
| Update everything, 1 conflict kept compatible | **4** | default choice needs no extra click |
|
||||
| Install one package | **4** + typing | Search (autofocus) → result [Add] → Install → Confirm |
|
||||
| Uninstall one package | **3** | Installed → row ✕ → *Remove* (4 when the guard trips: → *Remove the dependents too* → *Remove*) |
|
||||
| Rollback last snapshot | **4** | Env detail → snapshot → Rollback → Confirm |
|
||||
| Rollback last snapshot | **4** | Environments → *Open* → timeline entry → *Rollback…* → *Roll back* (2 from a run's summary, via *Roll back to this*) |
|
||||
| Switch engine | **3** | Settings → engine radio → (auto-saved) back |
|
||||
| Run Code Health | **3** | Health → Run (folder persisted) → view |
|
||||
|
||||
@@ -101,14 +117,16 @@ app lands. Counted by hand in the running app, never inferred from the markup.
|
||||
|
||||
`PdSidebar`, `PdStatusLine`, `PdEnvSwitcher`, `PdPackageTable` (virtualized), `PdPackageRow`, `PdBadge`, `PdPreviewDiff`, `PdConflictRow` (segmented 3-way), `PdDockBay` (queue), `PdConsoleDrawer`, `PdSummarySheet`, `PdSnapshotTimeline`, `PdHealthReport`, `PdLegalGate`, `PdEmptyState`, `PdOfflineBanner`.
|
||||
|
||||
**13 of those 16 exist** as of S5. Absent: `PdEnvSwitcher` and `PdSnapshotTimeline`, which arrive
|
||||
with the env detail in S6, and `PdHealthReport`, which arrives with Code Health in M3. (ROADMAP and
|
||||
**14 of those 16 exist** as of S6, `PdSnapshotTimeline` having arrived with the env detail. Absent:
|
||||
`PdEnvSwitcher`, which nothing needs while the header shows the selected interpreter and the
|
||||
Environments tab switches it, and `PdHealthReport`, which arrives with Code Health in M3. (ROADMAP and
|
||||
CLAUDE.md both claimed 16 of 16 after S4; the count had quietly folded in components that are not on
|
||||
this list.) Four components not on this list have
|
||||
turned out to be load-bearing and are listed here so the inventory stays honest: `PdErrorRow`
|
||||
(ERROR-CATALOG §3's row, used by every error surface), `PdDialog` (the shared modal §7's destructive
|
||||
confirms need), `PdUninstallDialog` (§5's three options) and `PdPinChip` (the 🔒 chip, shared by the
|
||||
table and the Pins screen).
|
||||
confirms need), `PdUninstallDialog` (§5's three options), `PdPinChip` (the 🔒 chip, shared by the
|
||||
table and the Pins screen) and `PdRollbackPreview` (DATA-FLOW §8's preview, including its
|
||||
`PD-SNP-002` list).
|
||||
|
||||
## 7. States & feedback
|
||||
|
||||
|
||||
Reference in new issue
Block a user