Commit e555f7cca8a01b01a44cb5a6689d4e8f7072491a | snowbound

author	clover caruso <git@paperclover.net> 2026-10-03 21:25:41-07:00
committer	clover caruso <git@paperclover.net> 2026-10-03 21:43:41-07:00
log	e555f7cca8a01b01a44cb5a6689d4e8f7072491a
tree	f194aacb8e619b9acd6e5c183c79bff3f7be68bf
parent	724f7aa7062d2a561f051778a85ee35deb71ebf7
signature	Signed by SSH key SHA256:52mNGHRsVFBDED9IAX5pe+LRWUefqTbxEReunq21QvU

docs: clarify sync shutdown in the browser

Native stop waits for in-flight work; browser cancellation lets that work finish while it retains cache ownership. Remove comments that assumed every browser sync step was synchronous.

Validation: cargo fmt and notebook doctests.

Assisted-by: gpt-6.1-sol

3 files changed, 5 insertions(+), 9 deletions(-)

crates
- notebook
  - src
    background.rs
    session.rs
    worker.rs

crates/notebook/src/background.rs+1-3

 @@ -508,13 +508,11 @@ impl Background {
         self.0.signal.wake();
     }
-    /// Stops for good, waiting for the step in flight, so that no replica stays open and no
+    /// Stops future checks; native threads finish the current step before returning.
-    /// watch holds the notebook's folder.
     pub fn stop(&self) {
         self.0.signal.stopped.store(true, Ordering::Release);
         self.0.signal.wake();
         let thread = self.1.lock().ok().and_then(|mut thread| thread.take());
-        // In the browser no step is in flight while another task runs.
         #[cfg(not(target_arch = "wasm32"))]
         if let Some(thread) = thread {
             let _ = thread.join();

crates/notebook/src/session.rs+2-3

 @@ -2390,9 +2390,8 @@ impl Section {
         &self.replica
     }
-    /// Waits for the in-flight operation and callback before releasing the replica.
+    /// Stops future sync steps; native threads finish the current operation before returning.
-    /// Dropping instead requests cancellation without waiting; the worker retains
+    /// The worker retains cache ownership until its in-flight operation finishes.
-    /// cache ownership until that operation finishes. Remote calls must be bounded.
     pub fn close(mut self) -> Result<()> {
         match self.worker.take() {
             Some(worker) => worker.stop(),

crates/notebook/src/worker.rs+2-3

 @@ -79,7 +79,7 @@ impl Signal {
 }
 /// Owns automatic reconciliation. Dropping requests cancellation without blocking.
-/// The in-flight sync step finishes before ownership is released; `stop` waits for it.
+/// The in-flight sync step retains cache ownership until it finishes.
 pub struct SyncWorker {
     signal: Arc<Signal>,
     thread: Option<JoinHandle<Result<()>>>,
 @@ -116,14 +116,13 @@ impl SyncWorker {
         self.signal.wake();
     }
-    /// Cancels future steps and waits for the current step and callback to finish.
+    /// Cancels future steps; native threads finish the current step and callback before returning.
     /// A stopped worker leaves pending edits and uncertain attempts in the cache.
     /// Call outside the worker's own callback, which cannot join its calling thread.
     pub fn stop(mut self) -> Result<()> {
         self.signal.stopped.store(true, Ordering::Release);
         self.signal.wake();
         let thread = self.thread.take().expect("Worker owns its thread");
-        // In the browser no step is in flight outside the worker's own callback.
         #[cfg(target_arch = "wasm32")]
         return thread.finished().unwrap_or(Ok(()));
         #[cfg(not(target_arch = "wasm32"))]