fix(app): a claim that finds nothing must release the slot, not wedge it

`plan_decide` and `plan_execute` called `AppState::claim()` and turned its `None`
into PD-INT-001 at the call site. But `claim()` writes `Busy` before it discovers
there is nothing to take, and neither of those paths released it — so one
out-of-order call from the UI wedged the slot for the rest of the process, and
every later command answered PD-RES-003 for a plan that had never existed.

The empty case cannot be shared, because the two callers want opposite things
from it. `plan_resolve` is *starting* work and needs the slot held for the whole
resolve, so `Ok(None)` there is a successful claim. `plan_decide` and
`plan_execute` want a session that already exists, and finding none is not
claiming anything. That is `claim_one()`, which leaves the slot idle and clears
the token it did not set.

The slot and its cancellation token move out of `AppState` into `Sessions`,
generic over what it parks. Their protocol — claim, park, release, exactly once
each — is the delicate part and is now testable on its own: a test drives it with
a `u32` where it could never build an `UpdateFlow`, which needs a real
interpreter to probe. That is this crate's first `[dev-dependencies]` and its
first tests; `AppState` keeps delegating methods, so no command body changes
except the two that were wrong.

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 d5ea886ada
commit ad167cf71e
4 files changed
+250 -64

No files matched your search

+6
View File
@@ -35,3 +35,9 @@ tokio = { version = "1", features = ["rt-multi-thread"] }
tokio-util = "0.7"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
[dev-dependencies]
# `Sessions` is the one thing in this crate with a protocol worth testing on its own, and every
# method on it is async. The runtime is already a dependency; `macros` and `rt` are what
# `#[tokio::test]` needs on top.
tokio = { version = "1", features = ["macros", "rt"] }
+2 -11
View File
@@ -10,7 +10,6 @@
use pipdock_core::engine;
use pipdock_core::envs::{self, ScanProgress};
use pipdock_core::errors::Code;
use pipdock_core::flow;
use pipdock_core::index::{self, NameIndex};
use pipdock_core::model::EnvSource;
@@ -405,7 +404,7 @@ pub async fn plan_decide(
state: tauri::State<'_, AppState>,
decisions: std::collections::BTreeMap<String, Decision>,
) -> Wire<flow::FlowStep> {
let mut flow = state.claim().await?.ok_or_else(no_plan)?;
let mut flow = state.claim_one().await?;
let parsed = decisions
.into_iter()
@@ -448,7 +447,7 @@ pub async fn plan_execute(
app: tauri::AppHandle,
state: tauri::State<'_, AppState>,
) -> Wire<ExecutionOutcome> {
let mut flow = state.claim().await?.ok_or_else(no_plan)?;
let mut flow = state.claim_one().await?;
state.set_cancel(Some(flow.cancel_handle()));
let snapshot = match flow
@@ -494,14 +493,6 @@ pub fn plan_cancel(state: tauri::State<'_, AppState>) -> bool {
state.cancel_current()
}
/// There is no parked plan — the UI called out of order, or a previous call already consumed it.
fn no_plan() -> PdError {
PdError::new(
Code::IntUnexpected,
"no plan is in progress; resolve one first",
)
}
/// Read the stored settings.
///
/// # Errors
+2
View File
@@ -4,6 +4,8 @@
//! wrapper over a `pipdock_core` function — if a code path here starts making decisions, it
//! belongs in the core so the CLI gets the same behaviour (G5: GUI and CLI never diverge).
#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
pub mod commands;
pub mod state;
+240 -53
View File
@@ -11,7 +11,13 @@
//! A third arrived with S3, and it is the reason the mutation spine works at all: `UpdateFlow` is
//! a **resumable state machine** and IPC is stateless. `plan_resolve` builds the flow, the user
//! looks at the preview, and `plan_decide` or `plan_execute` arrives as a separate message some
//! seconds later. Something has to hold the flow in between, and that is [`PlanSlot`].
//! seconds later. Something has to hold the flow in between, and that is [`Sessions`].
//!
//! The slot and its cancellation token live in [`Sessions`] rather than directly on [`AppState`]
//! because their protocol is the delicate part — claim, park, release, exactly once each — and it
//! is worth testing on its own. [`Sessions`] is generic over what it holds for the same reason: a
//! test can drive the protocol with a `u32` where it could never construct an `UpdateFlow`, which
//! needs a real interpreter to probe.
use std::path::PathBuf;
@@ -27,11 +33,11 @@ use tokio_util::sync::CancellationToken;
/// single environment, and DATA-FLOW §9.3's staleness check would be comparing the installed set
/// against one the other plan is busy changing — so the second is refused with `PD-RES-003`
/// rather than allowed to race.
pub enum PlanSlot {
pub enum PlanSlot<T> {
/// No plan.
Idle,
/// A flow is waiting for the user: a decision, or the final confirm.
Ready(Box<UpdateFlow>),
Ready(T),
/// Engine work is in flight, so the flow is owned by whichever command is driving it.
///
/// The flow is *moved out* for the duration rather than borrowed, because `execute` awaits for
@@ -40,13 +46,136 @@ pub enum PlanSlot {
Busy,
}
impl PlanSlot {
impl<T> PlanSlot<T> {
/// True while engine work is in flight.
pub const fn is_busy(&self) -> bool {
matches!(*self, Self::Busy)
}
}
/// The one mutation session this process may have, and the token that stops it.
///
/// Generic over the parked value so the protocol below can be tested without an `UpdateFlow`.
pub struct Sessions<T> {
slot: tokio::sync::Mutex<PlanSlot<T>>,
/// The token for whatever engine work is in flight.
///
/// Deliberately **not** inside [`PlanSlot`]: `plan_cancel` must be able to trip it while the
/// slot is `Busy` and its flow is owned elsewhere. Its own lock is only ever held for the
/// moment it takes to read or replace an `Option`, never across an await.
cancel: std::sync::Mutex<Option<CancellationToken>>,
}
impl<T> Default for Sessions<T> {
fn default() -> Self {
Self {
slot: tokio::sync::Mutex::new(PlanSlot::Idle),
cancel: std::sync::Mutex::new(None),
}
}
}
impl<T> Sessions<T> {
/// Claim the slot for work that is about to *start*, returning whatever was parked.
///
/// `Ok(None)` means the slot was idle and is now claimed — which is what `plan_resolve` wants,
/// because it is beginning a plan and must exclude a second one for the whole of the resolve.
/// A caller that needs an *existing* session wants [`Self::claim_one`] instead.
///
/// # Errors
/// `PD-RES-003` when a plan is already in flight.
pub async fn claim(&self) -> Result<Option<T>> {
let mut slot = self.slot.lock().await;
if slot.is_busy() {
return Err(in_flight());
}
Ok(match std::mem::replace(&mut *slot, PlanSlot::Busy) {
PlanSlot::Ready(session) => Some(session),
PlanSlot::Idle | PlanSlot::Busy => None,
})
}
/// Claim the session a caller expects to already be parked.
///
/// The difference from [`Self::claim`] is the empty case, and it is the whole reason this
/// method exists. `plan_decide` and `plan_execute` used to call `claim()` and turn its `None`
/// into `PD-INT-001` at the call site — but `claim()` had already written `Busy`, and nothing
/// on that path released it. One out-of-order call from the UI therefore wedged the slot for
/// the rest of the process: every later command answered `PD-RES-003`, for a plan that did not
/// exist. Finding nothing is not claiming anything, so this leaves the slot idle.
///
/// # Errors
/// `PD-RES-003` when a plan is already in flight; `PD-INT-001` when there is nothing parked.
pub async fn claim_one(&self) -> Result<T> {
let mut slot = self.slot.lock().await;
if slot.is_busy() {
return Err(in_flight());
}
match std::mem::replace(&mut *slot, PlanSlot::Busy) {
PlanSlot::Ready(session) => Ok(session),
PlanSlot::Idle | PlanSlot::Busy => {
*slot = PlanSlot::Idle;
drop(slot);
self.set_cancel(None);
Err(no_session())
}
}
}
/// Put a session back for the next call to pick up.
pub async fn park(&self, session: T) {
*self.slot.lock().await = PlanSlot::Ready(session);
}
/// Release the slot with no session — the plan finished, or failed.
///
/// Called on **every** exit path out of a claimed slot. A claim that is never released leaves
/// the session permanently refusing plans with `PD-RES-003`, which is the failure mode this
/// design has to be careful about.
pub async fn release(&self) {
*self.slot.lock().await = PlanSlot::Idle;
self.set_cancel(None);
}
/// Record the token for the work about to start.
pub fn set_cancel(&self, token: Option<CancellationToken>) {
if let Ok(mut guard) = self.cancel.lock() {
*guard = token;
}
}
/// Trip the in-flight token, if there is one. Returns whether anything was cancelled.
pub fn cancel_current(&self) -> bool {
let token: Option<CancellationToken> = self
.cancel
.lock()
.ok()
.and_then(|guard| guard.as_ref().cloned());
match token {
Some(t) => {
t.cancel();
true
}
None => false,
}
}
}
/// A second plan was asked for while one is running.
fn in_flight() -> PdError {
PdError::new(
Code::ResPlanInFlight,
"a plan is already resolving or executing",
)
}
/// There is no parked plan — the UI called out of order, or a previous call already consumed it.
fn no_session() -> PdError {
PdError::new(
Code::IntUnexpected,
"no plan is in progress; resolve one first",
)
}
/// How far the in-memory name index has got.
///
/// **Measured on the real 864k-project index: `NameIndex::load` costs 140 ms in release** (572 ms
@@ -84,13 +213,7 @@ pub struct AppState {
/// queued behind the 613 ms load — the exact thing this design exists to prevent.
pub index: std::sync::Mutex<IndexSlot>,
/// The plan being driven across several IPC calls.
pub plan: tokio::sync::Mutex<PlanSlot>,
/// The token for whatever engine work is in flight.
///
/// Deliberately **not** inside [`PlanSlot`]: `plan_cancel` must be able to trip it while the
/// slot is `Busy` and its flow is owned elsewhere. Its own lock is only ever held for the
/// moment it takes to read or replace an `Option`, never across an await.
pub cancel: std::sync::Mutex<Option<CancellationToken>>,
pub sessions: Sessions<Box<UpdateFlow>>,
}
impl AppState {
@@ -105,8 +228,7 @@ impl AppState {
app_data,
store: tokio::sync::Mutex::new(store),
index: std::sync::Mutex::new(IndexSlot::Cold),
plan: tokio::sync::Mutex::new(PlanSlot::Idle),
cancel: std::sync::Mutex::new(None),
sessions: Sessions::default(),
})
}
@@ -169,59 +291,124 @@ impl AppState {
}
}
/// Claim the plan slot for engine work, returning whatever flow was waiting there.
/// See [`Sessions::claim`].
///
/// # Errors
/// `PD-RES-003` when a plan is already in flight.
pub async fn claim(&self) -> Result<Option<Box<UpdateFlow>>> {
let mut slot = self.plan.lock().await;
if slot.is_busy() {
return Err(PdError::new(
Code::ResPlanInFlight,
"a plan is already resolving or executing",
));
}
Ok(match std::mem::replace(&mut *slot, PlanSlot::Busy) {
PlanSlot::Ready(flow) => Some(flow),
PlanSlot::Idle | PlanSlot::Busy => None,
})
self.sessions.claim().await
}
/// Put a flow back for the next call to pick up.
pub async fn park(&self, flow: Box<UpdateFlow>) {
*self.plan.lock().await = PlanSlot::Ready(flow);
}
/// Release the slot with no flow — the plan finished, or failed.
/// See [`Sessions::claim_one`].
///
/// Called on **every** exit path out of a claimed slot. A claim that is never released leaves
/// the session permanently refusing plans with `PD-RES-003`, which is the failure mode this
/// design has to be careful about.
/// # Errors
/// `PD-RES-003` when a plan is in flight; `PD-INT-001` when there is nothing parked.
pub async fn claim_one(&self) -> Result<Box<UpdateFlow>> {
self.sessions.claim_one().await
}
/// See [`Sessions::park`].
pub async fn park(&self, flow: Box<UpdateFlow>) {
self.sessions.park(flow).await;
}
/// See [`Sessions::release`].
pub async fn release(&self) {
*self.plan.lock().await = PlanSlot::Idle;
self.set_cancel(None);
self.sessions.release().await;
}
/// Record the token for the work about to start.
/// See [`Sessions::set_cancel`].
pub fn set_cancel(&self, token: Option<CancellationToken>) {
if let Ok(mut guard) = self.cancel.lock() {
*guard = token;
}
self.sessions.set_cancel(token);
}
/// Trip the in-flight token, if there is one. Returns whether anything was cancelled.
/// See [`Sessions::cancel_current`].
pub fn cancel_current(&self) -> bool {
let token: Option<CancellationToken> = self
.cancel
.lock()
.ok()
.and_then(|guard| guard.as_ref().cloned());
match token {
Some(t) => {
t.cancel();
true
}
None => false,
}
self.sessions.cancel_current()
}
}
#[cfg(test)]
mod tests {
use super::*;
/// The protocol is driven with a `u32` because an `UpdateFlow` cannot be constructed without a
/// real interpreter to probe — and the protocol is what has the bugs, not the payload.
fn sessions() -> Sessions<u32> {
Sessions::default()
}
#[tokio::test]
async fn claiming_an_empty_slot_leaves_it_claimed_for_the_caller() {
let s = sessions();
assert!(s.claim().await.expect("idle slot is claimable").is_none());
// `plan_resolve` is about to start work, so the slot must exclude a second resolve for the
// whole of it — the empty case is a successful claim, not a miss.
let second = s.claim().await;
assert_eq!(
second.err().map(|e| e.code),
Some(Code::ResPlanInFlight),
"a second plan must be refused while the first holds the slot"
);
}
#[tokio::test]
async fn claiming_a_session_that_is_not_there_does_not_wedge_the_slot() {
let s = sessions();
let missed = s.claim_one().await;
assert_eq!(missed.err().map(|e| e.code), Some(Code::IntUnexpected));
// The regression this whole method exists for: the old code wrote `Busy` before
// discovering there was nothing to take, so every later command answered `PD-RES-003`
// for a plan that had never existed.
s.park(7).await;
assert_eq!(s.claim_one().await.ok(), Some(7));
}
#[tokio::test]
async fn a_failed_claim_clears_the_token_it_did_not_set() {
let s = sessions();
let token = CancellationToken::new();
s.set_cancel(Some(token.clone()));
let _ = s.claim_one().await;
// Releasing means releasing: a stale token left behind would let the *next* plan's
// `plan_cancel` report that it stopped something.
assert!(!s.cancel_current(), "the stale token must be gone");
assert!(!token.is_cancelled());
}
#[tokio::test]
async fn a_parked_session_survives_until_someone_claims_it() {
let s = sessions();
s.park(1).await;
s.park(2).await;
assert_eq!(s.claim_one().await.ok(), Some(2), "parking replaces");
s.park(3).await;
s.release().await;
assert_eq!(
s.claim_one().await.err().map(|e| e.code),
Some(Code::IntUnexpected),
"release discards whatever was parked"
);
}
#[tokio::test]
async fn cancel_reaches_a_session_the_slot_no_longer_owns() {
let s = sessions();
let token = CancellationToken::new();
s.park(1).await;
let _claimed = s.claim_one().await.expect("parked");
s.set_cancel(Some(token.clone()));
// The slot is `Busy` and the session is owned by the caller — which is exactly when
// `plan_cancel` has to work, and why the token is not stored inside the slot.
assert!(s.cancel_current());
assert!(token.is_cancelled());
}
}