From 8431711d4e01135544cd778d1e9f4b2dfad40dd4 Mon Sep 17 00:00:00 2001 From: Neil Date: Thu, 10 Sep 2026 23:31:11 -0700 Subject: [PATCH] docs(windows): record the packaged rollback measurement against v1.4.199 --- .gitignore | 1 + docs/reference/windows-packaged-rollback.md | 76 +++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/reference/windows-packaged-rollback.md diff --git a/.gitignore b/.gitignore index 669ec4528f9..10c765a717e 100644 --- a/.gitignore +++ b/.gitignore @@ -115,6 +115,7 @@ docs/** !docs/reference/windows-daemon-host-relocation.md !docs/reference/windows-edr-posture.md !docs/reference/windows-msys-job-breakaway.md +!docs/reference/windows-packaged-rollback.md !docs/reference/windows-process-enumeration.md !docs/reference/wsl-runner-verification.md !docs/reference/remote-wire-compatibility.md diff --git a/docs/reference/windows-packaged-rollback.md b/docs/reference/windows-packaged-rollback.md new file mode 100644 index 00000000000..882ed528231 --- /dev/null +++ b/docs/reference/windows-packaged-rollback.md @@ -0,0 +1,76 @@ +# Rolling a packaged Windows build back to an older release + +The on-disk suite drives both builds' real `Store` over a real `orca-data.json`. +That leaves three things it cannot reach: electron-builder packaging, the boot +sequence that decides where userData lives and which cohort migrations run, and +a real userData directory. This page records what those add, measured rather +than assumed. + +## The measurement + +On Windows 11 `10.0.26200` (x64), two packages built from source on the same +host with `pnpm run build:unpack`, each from its own `node_modules`: + +- **new** — the composed stack at `84e703ce97a`, 241 commits ahead of the tag +- **old** — the `v1.4.199` tag + +Both ran headless against an isolated `--user-data-dir`; nothing touched the +real profile. State was written by the new build through its own packaged CLI — +a repo, a worktree, a terminal tab — and an `ssh:*` host partition was injected +so the rollback could be asked about rows an old build did not write. + +Every leg ran with a **same-version control** on a byte-identical copy of the +same state, because a restart mutates the session blob on its own and the +downgrade would otherwise be credited with that churn. + +| question | result | +| ----------------------------------------------- | -------------------------------------------------------------------- | +| old build reads new state | yes — no throw, no salvage, no dropped row | +| old build writes back a shape new still accepts | yes — return leg diffs 0 keys removed, 0 added | +| old build deletes what it does not understand | no — its diff matches the control except the running build's version | + +`workspaceSessionsByHostId["ssh:*"]` tab rows survived all three legs, as did +`repos`, `projects`, `projectHostSetups`, `worktreeMeta`, +`worktreeIdentityAliases` and `worktreeMetaByIdentity`. + +## Read the control, not the downgrade diff + +A restart of **either** build on this state empties +`workspaceSession.unifiedTabs` and `tabGroups` for the worktree and drops +`tabGroupLayouts`, `activeGroupIdByWorktree` and the pane title under +`terminalLayoutsByTabId`. It also writes `_sortBySmartMigrated` and flips +`ui.sortBy` from `recent` to `smart`. + +None of that is rollback behaviour — the same-version control produces the same +removals on the same input. Reading the downgrade diff alone reports terminal +tab-group loss that is not there. + +An injected partition has to satisfy the session schema or both builds discard +it identically (`[persistence] Corrupt workspace session for host …, using +defaults`). A partition built field-by-field failed `activeRepoId: required`; +copying the whole local session and re-keying its worktree-keyed maps is what +makes the row survive long enough to be a test of anything. + +## Two things a userData rollback cannot answer + +- **The old-client empty-publish skew** + (`workspace-session.ssh-host-partition-round-trip`) is a client/host wire + disagreement: an older _client_ reads only the local partition and publishes a + `replace-session` naming the workspace with no tabs. Reproducing it needs two + paired runtimes, not one userData directory read twice. +- **Relay protocol-version negotiation** is likewise a wire surface. A packaged + rollback with no pairing never opens a relay connection, so it exercises + neither the version check nor its refusal path. + +## Practical notes + +- A packaged build takes Chromium's `--user-data-dir`; `configureDevUserDataPath` + only overrides userData for dev and E2E, so an isolated profile needs no + special build. +- `autoDownload` is off and `autoInstallOnAppQuit` is Linux-non-root only, so a + packaged test instance will not install an update over the host's own app. Do + not run the NSIS installer to obtain the old build — build the tag instead. +- Each packaged build copies itself to + `%LOCALAPPDATA%\Orca\daemon-host\` on first boot. That is outside the + isolated userData and has to be cleaned up by hand; match the copy's + `Orca.exe` hash against the build before removing one.