# Optimistic Apply: show an already-prepared theme ahead of the durable commit

Implements OpenSpec task 7 from
`openspec/changes/archive/2026-10-12-the-shell-swaps-themes-without-a-python-stall/tasks.md`,
against the user's explicit approval (2026-09-25 coordinator message: "The
user has explicitly approved the optimistic theme apply") of the design the
change's `design.md` records in full. This is a **host-only** result: no
board, glass, or real-finger observation. Worktree
`perf/optimistic-theme-apply`, base `master` `600171bc`.

## Starting point

Board re-check after skipping the redundant prepare
(`docs/evidence/omarchy-themes/instant-theme-swap/board-chooser-2026-09-25.md`'s
own "Re-check after skip-redundant-prepare" section, system
`v84gna5s1qnabg5mqhwa55anml2q8amh...`, master `bc0cf82f`): tap Apply -> Rust
`appearance-commit-accepted` 397 ms, helper `parse=2.2ms prepare_entry=
63.0ms activate_generation=226.2ms`. Still short of the user's original
~100 ms target ("theme swaps should be instant"); the remaining cost is
`activate_generation`'s own durable pointer-swap/preference/app-sync work,
none of which can be skipped without risking the transaction's own
correctness.

## What changed

- `nix/rust-shell-client/src/main.rs`:
  - `should_apply_optimistically(request, prepared_generation)` -- pure:
    true only for an `Activate` request whose `expected_generation` exactly
    matches the local `AppearanceReceiver`'s own `prepared` snapshot.
  - `optimistic_apply_due(already_attempted_for, pending_id)` -- pure:
    true exactly once per fresh `pending_id`, so a still-pending Apply is
    never re-checked tick after tick and a rapid second Apply (its own
    fresh, higher id) is never suppressed by the first's bookkeeping.
  - `show_theme_optimistically` -- renders an already-prepared snapshot
    through the same `draw_wallpaper`/`draw`/flush calls the real commit
    path already uses, skipping only for a video-backed selection, an
    unrenderable snapshot (defensive), or an overlay not immediately ready
    for a new frame. Logs `rust-shell <ms>ms optimistic-apply shown
    ms=<tap-to-frame>`. Never touches `AppearanceReceiver`'s own
    `prepared`/`active` bookkeeping or the `Activate` request already
    dispatched to `ThemeWorker` -- both are left entirely to the real,
    unmodified `AppearancePhase::Commit`/`Rollback` handling to settle
    authoritatively (including reverting the display and surfacing an
    error via `ThemeView::accept`'s existing `Err` handling on failure).
  - `show_appearance_optimistically` -- a best-effort, fire-and-forget
    "show" message to the card-shell compositor's own appearance socket
    (`K230_CARD_APPEARANCE_SOCKET`, defaulting to `nix/shell.nix`'s
    existing `SWAY_K230_CARD_APPEARANCE_SOCKET` production path), sent
    *after* the local render/log so a slow or unreachable compositor never
    inflates the logged latency.
  - `ShellClient` gains `theme_apply_tapped_at`, `theme_optimistic_shown_
    for`, and `card_appearance_socket`; `submit_theme` records the tap
    instant and resets the per-Apply attempted-marker whenever a fresh
    `Activate` is submitted; `serve`'s own loop checks `optimistic_apply_
    due` once, right after Wayland event dispatch (the same tick a
    touch-up already ran `theme_action(ThemeIntent::Apply)` in).
- `nix/card-shell/appearance.c`: an additive `"show"` protocol phase.
  Renders `service.candidate` immediately when it is already `service.
  prepared` and matches the requested id/path, with the same best-effort
  restore-on-apply-failure as the existing `commit` branch, but never
  touches `service.prepared`/`service.candidate_path`/`service.current` --
  a subsequent real `commit` or `rollback` for the same candidate is
  unaffected by whether `show` was ever sent, was late, or was duplicated.

## Why this is safe (see `design.md`'s own "Optimistic Apply" section for the full reasoning)

A receiver only ever holds a `prepared` candidate after it has already
validated that candidate byte-for-byte via the same checks a real `prepare`
exchange runs. Rendering it early therefore risks nothing a real `prepare`
ack would not already have accepted. The optimistic render is *stateless*
with respect to the durable transaction -- it reads `prepared`, renders,
and is done -- so there is nothing to reconcile if the two ever disagree:
the real `commit`/`rollback` event, unaware optimism ever ran, always wins
and settles the receiver's actual state and the visible appearance
correctly, including on a durable failure.

## What was deliberately not done

- **The wire acknowledgement contract is unchanged.** No `prepare`/
  `commit`/`rollback` exchange's own success criteria, or the "ack only
  after a real, flushed frame" rule, changed in any way. `proposal.md`'s
  own "What This Does Not Do" section is revised to say this precisely
  (its earlier wording read as ruling this whole feature out permanently).
- **The compositor fanout is not wired into production here.** `theme-
  helper.service`'s `--rust-socket`/`--deck-socket` flags are not passed
  in `nix/shell.nix` on this branch's base (`master` `600171bc`) -- that is
  a separate, not-yet-landed integration (see this repository's own
  `impl/card-appearance-endpoint` worktree). The compositor's `show`
  phase and `main.rs`'s sender are therefore correct and tested in
  isolation, but dormant in production until that fanout lands; sending
  `show` to an unreachable/not-listening compositor is silently ignored,
  by design.
- **A genuine touch-driven QEMU proof was not built.** The existing
  `tests/rust_theme_chooser_qemu.py` harness stands in a synthetic
  `K230_THEME_COMMAND` script for `k230-theme`, which never runs the real
  two-phase protocol against the real `AppearanceReceiver` socket -- so
  `appearance.prepared()` is never populated there and this feature's own
  code is structurally unreachable in that harness (every Apply in it is
  effectively "cold" from the receiver's point of view, which is also
  why running it unmodified is still a valid regression check -- see
  below). A harness combining real touch injection with the real `theme-
  helper`/two-phase backend (closer to `tests/test_theme_commit_under_
  occlusion_runtime.py`'s own real-CLI approach) would be needed to
  exercise `should_apply_optimistically` end to end under QEMU, and was
  not built in this task given the time this stage already spent; this is
  named here as an explicit gap, not a claimed pass.

## Test-suite proof

- `cargo test --offline` (nix/rust-shell-client): 159+9+14+8+8+5 = 203
  cases, all passing. New: `route_tests::optimistic_apply_fires_only_for_
  an_activate_matching_the_prepared_generation` (warm/cold/mismatched/
  non-Activate-request cases for `should_apply_optimistically`),
  `route_tests::optimistic_apply_due_is_scoped_to_each_fresh_pending_id_
  for_a_rapid_double_apply` (the rapid-double-Apply scoping property),
  `theme_ui::tests::a_failed_activate_clears_pending_and_surfaces_a_
  visible_error` (the existing, unmodified `Err`-reply handling proven
  specifically for an Activate reply, not just Preview/background).
- `python3 -m unittest tests.test_card_shell_appearance`: 10 cases (7
  pre-existing + 3 new), all passing against the real, compiled
  `appearance.c` over a real Unix socket (built with `-Werror`, so the new
  C branch itself is warning-clean). New:
  `test_show_renders_a_prepared_candidate_without_disturbing_the_two_
  phase_state` (show renders, twice, then a real commit for the same
  candidate still succeeds -- proving `show` never cleared `prepared`),
  `test_show_is_rejected_for_a_generation_that_was_never_prepared`
  (cold and mismatched-id cases both rejected, connection never blocks),
  `test_show_never_blocks_a_later_rollback_from_restoring_the_previous_
  generation` (show, then a real rollback still restores the previous
  generation's own pixels/palette).
- `python3 tools/blob-scan.py`: exit 0 ("every binary is accounted for").
- `openspec validate the-shell-swaps-themes-without-a-python-stall
  --strict`: valid.
- `nix build --no-link --print-out-paths --max-jobs 1 --cores 6
  .#handheld-shell-rust .#card-shell .#handheld-theme-command
  .#handheld-theme-default .#card-composition-probe`: all five built
  cleanly for riscv64 (exit 0), including `card-shell`'s own build of
  `sway-unwrapped`/`sway` against the new `"show"` branch in
  `appearance.c` -- the real C cross-compile check for that change, not
  just the host `cc -Werror` build the unit tests above already ran.
  Output paths:
  `/nix/store/j8fnc6jr4hhsvp3hff9k2hjjy7k2d9il-k230-shell-rust-riscv64-unknown-linux-gnu-0.1.0`,
  `/nix/store/1va4angandva4xbm5i0v7367p0nd9jry-k230-card-shell`,
  `/nix/store/nh386rn5qkdbcl11lqyxx538s4mc2niv-handheld-theme-command-0.1`,
  `/nix/store/1dqfry706fj780v5byiklmaawakwphid-handheld-theme-default-28ceaae7`,
  `/nix/store/ih8mq5lq53w7p8mcv6aarz6z55il0f4s-k230-card-composition-probe`.
- `nix eval .#nixosConfigurations.k230-coherent-shell.config.system.build.toplevel.drvPath`:
  evaluates to
  `/nix/store/2j8yam3w04lhj3qhhssi0hyp8m1awip0-nixos-system-nixos-26.11.20260919.20b1ddd.drv`,
  no eval error.

## Board commands for the coordinator (task 7.4)

```sh
journalctl -u shell-ui -u shell -o json --since "-2min" \
  | grep -E "optimistic-apply|appearance-(prepare|commit)-accepted|appearance-commit-rejected"
```

Steps: Settings, Themes, dwell on (or swipe to a neighbour-warmed) a
non-active theme long enough for its own prepare-ahead to land, then tap
Apply. Expected on a warm Apply: an `optimistic-apply shown ms=<N>` line
appears before (or very close to) the durable `activate`'s own reply, and
`<N>` is the number to compare against the ~100 ms target. Expected on a
cold Apply (a theme the chooser never had time to prepare ahead): no
`optimistic-apply shown` line at all, and the pre-existing busy-state
behaviour. For the failure/rollback scenario, the coordinator's own
existing failure-injection approach (see
`docs/evidence/omarchy-themes/instant-theme-swap/board-diagnosis-2026-09-24.md`/
`tests/test_theme_commit_under_occlusion_runtime.py` for the shape of a
reproducible commit failure) should show a subsequent `appearance-commit-
rejected` and the wallpaper/chooser visibly reverting to the previous
theme with an error message, never settling on the optimistically-shown
one.