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:
poli0981andClaude Opus 5 committed 2026-08-09 21:46:25 +07:00
1 parent a3ad170c00
commit 8042bdb5f8
5 files changed
+95 -19

No files matched your search

+11 -6
View File
@@ -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
+12
View File
@@ -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
View File
@@ -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
View File
@@ -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
View File
@@ -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