Add bounded client calls and abort support

Author: ktsaou

.agents/sow/current/SOW-0015-20260605-codacy-scope-and-maintainability.md

@@ -2,9 +2,9 @@
 
 ## Status
 
-Status: in-progress
+Status: paused
 
-Sub-state: Codacy test/bench exclusion and refreshed production-source maintainability baseline in progress.
+Sub-state: paused by user decision on 2026-06-11 so `SOW-0016` can take current active slot for a timeout/abort liveness fix. Resume from Codacy test/bench exclusion and refreshed production-source maintainability baseline work.
 
 ## Requirements
 

.agents/sow/done/SOW-0016-20260610-client-call-timeout-and-abort.md

@@ -153,6 +153,12 @@ if client.Ready() {
 }
 ```
 
+Typed client calls are bounded by a client call timeout. Passing an
+explicit timeout of zero uses the client context default, which is
+30000 ms. Clients also expose an abort signal so shutdown code can
+release a call blocked in receive; the abort remains active until it is
+cleared or the client is closed.
+
 ## Managed Server (L2)
 
 The managed server receives wire messages, but that is internal to the

docs/getting-started.md

@@ -89,6 +89,26 @@ chunk header is used.
 
 See the wire envelope spec for chunk header layout and validation rules.
 
+## Receive timeout and abort
+
+The baseline receive primitive remains a blocking Level 1 operation for
+callers that want raw transport semantics. Level 1 also provides a
+timeout-aware receive form used by Level 2 typed calls.
+
+The timeout-aware receive form must:
+
+- wait for each required SEQPACKET chunk with a deadline derived from the
+  caller-provided timeout
+- apply the same deadline to the first packet and all continuation
+  packets that make up one logical message
+- poll an explicit abort file descriptor at the same time as the socket
+  file descriptor
+- return a distinct timeout error when the deadline expires
+- return a distinct aborted error when the abort descriptor is signaled
+
+Level 2 is responsible for deciding whether a timeout or abort should
+break the session. Level 1 only reports the condition precisely.
+
 ## SHM file path derivation
 
 When the handshake negotiates a SHM profile, the server creates a

docs/level1-posix-uds.md

@@ -89,6 +89,27 @@ sequentially.
 
 See the wire envelope spec for chunk header layout and validation.
 
+## Receive timeout and abort
+
+The baseline receive primitive remains a blocking Level 1 operation for
+callers that want raw transport semantics. Level 1 also provides a
+timeout-aware receive form used by Level 2 typed calls.
+
+The timeout-aware receive form must:
+
+- wait for each required pipe message with a deadline derived from the
+  caller-provided timeout
+- apply the same deadline to the first packet and all continuation
+  packets that make up one logical message
+- observe an explicit abort event while waiting for pipe readability
+- return a distinct timeout error when the deadline expires
+- return a distinct aborted error when the abort event is signaled
+
+Level 2 is responsible for deciding whether a timeout or abort should
+break the session. Level 1 reports timeout and abort distinctly; peer
+disconnect is reported when the pipe read path observes the corresponding
+Win32 pipe error.
+
 ## SHM mapping name derivation
 
 When the handshake negotiates a SHM profile, the shared memory region

docs/level1-windows-np.md

@@ -184,6 +184,9 @@ There are two important cases:
 
 - For ordinary transport / peer failures, Level 2 reconnects and retries
   once.
+- Timeout and caller-requested abort are terminal for the current call:
+  Level 2 reports the explicit error, disconnects or marks the current
+  session broken, and does not reconnect/retry that same request.
 - For overflow-driven resize recovery, Level 2 may reconnect more than
   once while negotiated request/response capacities grow. This is a
   fallback safety net, not the primary sizing strategy for typed APIs.
@@ -197,6 +200,19 @@ without attempting reconnection.
 
 If recovery fails, Level 2 reports failure to the caller.
 
+Every synchronous Level 2 client call is bounded. A per-call timeout of
+zero means "use the client context default"; the default is 30000 ms.
+The deadline applies to the complete logical response, including baseline
+transport chunk continuations and SHM response waits. A timeout returns a
+distinct timeout error rather than being collapsed into disconnect or
+protocol failure.
+
+Every Level 2 client context also exposes an abort signal that is safe to
+trigger from another thread while one thread is blocked in a typed call.
+Abort is sticky until the caller explicitly clears it or closes the
+client. A call that observes the abort signal returns a distinct aborted
+error and is not retried.
+
 Negotiated request payload ceilings are capped at 1 MiB. If a peer
 proposes a larger request ceiling, handshake rejects with
 `transport_status = LIMIT_EXCEEDED`. The cap is enforced before the value

docs/level2-typed-api.md

@@ -142,6 +142,17 @@ reconnect attempt. On overflow-driven resize recovery it may reconnect
 more than once while negotiated capacities grow (up to 8 overflow
 retries). If recovery still fails, the previous cache is preserved.
 
+Refresh is bounded by the underlying Level 2 client call timeout. The
+default timeout is 30000 ms unless the caller sets a different client
+context default or uses an explicit timeout-capable refresh/call form.
+Timeout and caller-requested abort preserve the previous cache, return a
+distinct error, and do not retry the same snapshot request.
+
+Level 3 exposes the underlying Level 2 abort lifecycle for shutdown paths:
+an abort signal may be triggered from another thread to unblock a refresh
+that is waiting in transport receive, and remains active until explicitly
+cleared or the helper is closed.
+
 This is intentional:
 
 - providers may start late

docs/level3-snapshot-api.md

@@ -324,6 +324,9 @@ as explicit assumptions, not as implementation details they can reinterpret.
 - L2 clients and L3 caches should be treated as single-owner mutable objects
   unless the integrator adds external synchronization.
   - They are not documented as internally synchronized shared objects.
+  - The only cross-thread operation provided by the public client contract is
+    the abort signal, which may be triggered by a shutdown thread to release a
+    call blocked in transport receive.
   - On the same object instance, do not concurrently call:
     - `refresh()`
     - blocking typed methods
@@ -542,16 +545,30 @@ L2 typed calls are at-least-once:
   - reconnect
   - retry
 - ordinary failures retry once
+- timeout and caller-requested abort are terminal for that call and are not
+  retried
 - overflow-driven resize recovery may reconnect multiple times while capacities
   grow
 - managed servers close a session after terminal service errors such as
   `LIMIT_EXCEEDED`, `BAD_ENVELOPE`, or `INTERNAL_ERROR`; recovery is a new
   handshake on a new session
 
+L2 typed calls are also bounded:
+
+- a per-call timeout of zero uses the client context default
+- the default client context timeout is 30000 ms
+- the deadline covers the complete logical response, including chunked
+  baseline messages and SHM waits
+- timeout and abort have distinct errors, so shutdown handling does not need
+  to guess whether the peer disconnected
+- abort is sticky until the caller clears it or closes the client/cache helper
+
 Implication:
 
 - server handlers must be duplicate-safe
 - do not design exactly-once business semantics around L2 calls
+- shutdown paths can abort a blocked call, but normal shared-client access
+  still needs external synchronization in C and Go
 
 ### SHM attach failure
 

docs/netipc-integrator-skill.md

@@ -103,6 +103,10 @@ pub enum NipcError {
     BadItemCount,
     /// Builder ran out of space.
     Overflow,
+    /// Synchronous call timed out before a complete response arrived.
+    Timeout,
+    /// Synchronous call was aborted by the caller.
+    Aborted,
 }
 
 impl core::fmt::Display for NipcError {
@@ -119,6 +123,8 @@ impl core::fmt::Display for NipcError {
             NipcError::BadAlignment => write!(f, "item not 8-byte aligned"),
             NipcError::BadItemCount => write!(f, "item count inconsistent"),
             NipcError::Overflow => write!(f, "builder out of space"),
+            NipcError::Timeout => write!(f, "synchronous call timed out"),
+            NipcError::Aborted => write!(f, "synchronous call aborted"),
         }
     }
 }

src/crates/netipc/src/protocol/mod.rs

@@ -16,7 +16,7 @@ use crate::transport::windows::{
 use std::sync::atomic::AtomicBool;
 use std::sync::Arc;
 
-pub use raw::{AppsLookupHandler, ClientState, ClientStatus};
+pub use raw::{AppsLookupHandler, ClientAbortHandle, ClientState, ClientStatus};
 
 #[derive(Debug, Clone)]
 pub struct ClientConfig {
@@ -109,8 +109,32 @@ impl AppsLookupClient {
         self.inner.status()
     }
 
+    pub fn set_call_timeout(&mut self, timeout_ms: u32) {
+        self.inner.set_call_timeout(timeout_ms);
+    }
+
+    pub fn abort_handle(&self) -> ClientAbortHandle {
+        self.inner.abort_handle()
+    }
+
+    pub fn abort(&self) {
+        self.inner.abort();
+    }
+
+    pub fn clear_abort(&self) {
+        self.inner.clear_abort();
+    }
+
     pub fn call(&mut self, pids: &[u32]) -> Result<AppsLookupResponseView<'_>, NipcError> {
-        self.inner.call_apps_lookup(pids)
+        self.call_with_timeout(pids, 0)
+    }
+
+    pub fn call_with_timeout(
+        &mut self,
+        pids: &[u32],
+        timeout_ms: u32,
+    ) -> Result<AppsLookupResponseView<'_>, NipcError> {
+        self.inner.call_apps_lookup_with_timeout(pids, timeout_ms)
     }
 
     pub fn close(&mut self) {