Skip to main content

khive_db/
writer_task.rs

1//! Single-writer task and bounded write queue (ADR-067 Component A).
2//!
3//! `WriterTask` (via `spawn` and the drain loop `run_writer_task`) owns a
4//! dedicated standalone writer `rusqlite::Connection` and is the only code
5//! path that issues `BEGIN IMMEDIATE` for write traffic routed through the
6//! channel it drains. Callers reach it exclusively through a
7//! [`WriterTaskHandle`], sending a typed closure and awaiting a typed
8//! oneshot reply so each store method's natural return type (e.g.
9//! `BatchWriteSummary`) survives the trip through the type-erased channel
10//! unmodified — a flat `Result<u64, StorageError>` reply would conflate
11//! `affected`/`failed` into one count and drop `first_error`.
12//!
13//! See `crates/khive-db/docs/api/writer-task.md` for migration-slice scope
14//! (which write paths currently route through this vs. the legacy
15//! pool-mutex path) and the ADR-067 component breakdown.
16//!
17//! ## ADR-136 D1 gate 5: writer classification
18//!
19//! Every connection that issues writes against a khive-db file falls into
20//! exactly one of the rows below. Request-path store writes, runtime
21//! merge/symmetric-edge transactions,
22//! and `khive_storage::SqlAccess` (`SqlBridge::writer`/`atomic_unit`) are subject
23//! to `PoolConfig::write_queue_enabled` / `write_routing_strict` routing.
24//! Everything else here is an
25//! explicit, intentional exemption — not an implicit gap left over from an
26//! incomplete migration.
27//!
28//! | Writer | Connection | Request-path write | Routing |
29//! | --- | --- | --- | --- |
30//! | Request-path writes (`create`, `update`, batch upserts, …) | `WriterTaskHandle` (queue-first) or a standalone/pool-mutex connection on degrade | Yes | Queue-first (ADR-136 D1 gate 1); strict routing fails closed on degrade |
31//! | Startup / schema migrations (`migrations::run_migrations`, `apply_schema_plan`) | The pool's own writer-mutex connection (`ConnectionPool::new`, before the `WriterTask` is ever spawned) | No | Exempt — runs once at boot, before any queue handle exists to route through |
32//! | Checkpointing (`checkpoint::CheckpointConnection`) | Dedicated standalone connection, opened once at task startup (ADR-091 Amendment 5, #1652) | No | Exempt by design — the whole point of that fix was moving checkpoint I/O OFF the pool writer's admission path; routing it back through the write queue would reintroduce the contention it removed |
33//! | Recovery (`walpin` beacon/sidecar bookkeeping) | None — file-level bookkeeping (PID beacons, heartbeats) alongside the database, not a SQL connection against it | No | N/A — never acquires a database writer connection |
34//! | Top-level maintenance (`VACUUM` via `execute_script_top_level`/`WriterTaskHandle::send_top_level`) | `WriterTaskHandle`, skipping the per-request `BEGIN IMMEDIATE`/`COMMIT` wrap only | Yes | Routed through the SAME single writer owner as every other queued request — only the transaction wrap is skipped, never the queue |
35//!
36//! Store constructors may run outside Tokio and temporarily cache no handle;
37//! every store request-path write refreshes through
38//! `ConnectionPool::writer_task_for_write` at execution time. Strict routing
39//! refuses a missing handle, while the explicit compatibility fallback emits
40//! its store-specific violation at the actual direct-writer seam. Runtime
41//! entity/note merges and symmetric edge updates use the same routing policy
42//! through a closed operation adapter. The strict default itself remains gated
43//! by ADR-135 F2 / ADR-136 D2 evidence.
44//!
45//! A `direct_route_violation` sink row (`timeout_sink::emit_direct_route_violation`,
46//! ADR-136 D1 gate 6c) is emitted ONLY for the first row's degrade path — a
47//! request-path write that bypassed an enabled queue. The other four
48//! rows are exempt by design and never emit that row.
49
50use rusqlite::Connection;
51use std::collections::HashMap;
52use std::panic::{catch_unwind, AssertUnwindSafe};
53use std::path::{Path, PathBuf};
54use std::sync::atomic::{AtomicBool, Ordering};
55use std::sync::{Arc, Mutex, OnceLock};
56use std::time::{Duration, Instant};
57use tokio::sync::{mpsc, oneshot};
58
59use khive_storage::error::{StorageError, WriterTaskRequestState};
60
61use crate::error::SqliteError;
62use crate::pool::{ConnectionPool, WriterAcquisitionCounters};
63use crate::writer_admission_metrics::{
64    AdmissionObservation, Snapshot, Unavailable, WriterAdmissionMetrics,
65};
66
67#[path = "writer_task_labels.rs"]
68mod labels;
69
70pub(crate) use labels::{collect_statement_labels, MAX_WRITE_LABELS};
71use labels::{dedup_labels, SubmitLabels};
72
73/// Retry delays after a busy/locked `BEGIN IMMEDIATE` refusal. The operation
74/// closure remains owned by the request until one BEGIN succeeds, so these
75/// are the only retries this path may perform. Persistent contention is
76/// bounded to three total BEGIN attempts and 15 ms of explicit backoff, and
77/// the attempts together share one configured `busy_timeout` acquisition
78/// budget rather than each waiting out a full window of their own.
79const WRITER_BEGIN_RETRY_DELAYS: [Duration; 2] =
80    [Duration::from_millis(5), Duration::from_millis(10)];
81
82/// Closure signature for a write operation executed against the writer
83/// task's dedicated connection.
84///
85/// `conn` is already inside a `BEGIN IMMEDIATE` transaction opened by
86/// `run_writer_task` when this runs. The closure must issue DML (and, in
87/// later slices, named `SAVEPOINT`s) only — never a bare `BEGIN` / `COMMIT`
88/// / `ROLLBACK` — a nested bare `BEGIN IMMEDIATE` would violate SQLite's
89/// nested-transaction rule and return `SQLITE_ERROR: cannot start a
90/// transaction within a transaction` (ADR-067 lines 271-276).
91type WriteOp<R> = Box<dyn FnOnce(&Connection) -> Result<R, StorageError> + Send>;
92
93/// Latest completed writer-task span for one database, decomposed at the
94/// boundaries an operator can act on (#1849). A zero value means that phase
95/// did not run (top-level/early-failure request) or completed below the
96/// microsecond clock resolution; `total_micros` retains the full span.
97#[derive(Debug, Clone, PartialEq, Eq)]
98pub struct WriterStageObservation {
99    pub queue_wait_micros: u64,
100    pub transaction_acquire_micros: u64,
101    pub body_micros: u64,
102    pub commit_micros: u64,
103    pub total_micros: u64,
104    pub queue_depth_at_entry: u64,
105    pub observed_at_unix_ms: u64,
106    /// Distinct labels the drained request ran, in first-seen order,
107    /// deduplicated and bounded at `MAX_WRITE_LABELS`. Resolved only for a
108    /// write that crossed the slow-write threshold, so empty for every write
109    /// below it; also empty when no statement in the request carried a label
110    /// and the submit site had no name in hand — e.g. an opaque closure from
111    /// a caller with no `&'static str` operation.
112    pub labels: Vec<String>,
113    /// Distinct labels dropped past `MAX_WRITE_LABELS`, when the request
114    /// named more; `None` when nothing was dropped.
115    pub labels_truncated: Option<u64>,
116}
117
118static WRITER_STAGE_OBSERVATIONS: OnceLock<
119    Mutex<HashMap<Option<PathBuf>, WriterStageObservation>>,
120> = OnceLock::new();
121
122fn writer_stage_observations() -> &'static Mutex<HashMap<Option<PathBuf>, WriterStageObservation>> {
123    WRITER_STAGE_OBSERVATIONS.get_or_init(|| Mutex::new(HashMap::new()))
124}
125
126fn writer_db_key_from_path(path: Option<&Path>) -> Option<PathBuf> {
127    path.map(Path::to_path_buf)
128}
129
130fn writer_db_key(pool: &ConnectionPool) -> Option<PathBuf> {
131    writer_db_key_from_path(pool.canonical_path())
132}
133
134fn duration_micros(duration: Duration) -> u64 {
135    duration.as_micros().min(u128::from(u64::MAX)) as u64
136}
137
138fn observed_at_unix_ms() -> u64 {
139    std::time::SystemTime::now()
140        .duration_since(std::time::UNIX_EPOCH)
141        .map(|duration| duration.as_millis() as u64)
142        .unwrap_or(0)
143}
144
145/// Pure in-memory read of the most recently completed writer-task span for
146/// this exact backend. It acquires no SQLite connection and performs no I/O.
147pub fn last_writer_stage_observation(pool: &ConnectionPool) -> Option<WriterStageObservation> {
148    writer_stage_observations()
149        .lock()
150        .unwrap_or_else(std::sync::PoisonError::into_inner)
151        .get(&writer_db_key(pool))
152        .cloned()
153}
154
155#[cfg(test)]
156trait TestWriterStageClock: Send + Sync {
157    fn now(&self) -> Instant;
158    fn at_commit(&self);
159}
160
161struct WriteTelemetry {
162    #[cfg(test)]
163    test_clock: Option<std::sync::Arc<dyn TestWriterStageClock>>,
164    backend_key: Option<PathBuf>,
165    db: String,
166    submitted_at: Instant,
167    queue_depth_at_entry: usize,
168    slow_write_threshold: Option<Duration>,
169    labels: SubmitLabels,
170    /// Per-attempt mode (`timeout_sink::writer_attempt_log_enabled`) of the
171    /// handle this request was submitted through.
172    attempt_log: bool,
173    top_level: bool,
174    /// The caller's request id, read from the submitting task's request
175    /// context at submit time, so a per-attempt row joins to the caller's
176    /// own record of the request. `None` for writes no request scoped.
177    request_id: Option<u64>,
178}
179
180impl WriteTelemetry {
181    fn new(
182        backend_key: Option<PathBuf>,
183        db: String,
184        queue_depth_at_entry: usize,
185        slow_write_threshold: Option<Duration>,
186        labels: SubmitLabels,
187        attempt_log: bool,
188        top_level: bool,
189    ) -> Self {
190        Self {
191            #[cfg(test)]
192            test_clock: None,
193            backend_key,
194            db,
195            submitted_at: Instant::now(),
196            queue_depth_at_entry,
197            slow_write_threshold,
198            labels,
199            attempt_log,
200            top_level,
201            request_id: khive_storage::current_request_correlation(),
202        }
203    }
204
205    fn queue_wait(&self) -> Duration {
206        self.submitted_at.elapsed()
207    }
208
209    /// The labels named on this request, bounded to [`MAX_WRITE_LABELS`]
210    /// plus the count of distinct labels dropped. Computed only on the slow
211    /// path, since only [`Self::finish`] calls it: the fast path never turns
212    /// a [`SubmitLabels::Site`] name into an allocation.
213    fn resolve_labels(&self) -> (Vec<String>, Option<u64>) {
214        match &self.labels {
215            SubmitLabels::None => (Vec::new(), None),
216            SubmitLabels::Site(site) => (vec![(*site).to_owned()], None),
217            SubmitLabels::Statements(labels) => {
218                if labels.len() <= MAX_WRITE_LABELS {
219                    (labels.clone(), None)
220                } else {
221                    let dropped = (labels.len() - MAX_WRITE_LABELS) as u64;
222                    (labels[..MAX_WRITE_LABELS].to_vec(), Some(dropped))
223                }
224            }
225        }
226    }
227
228    #[allow(clippy::too_many_arguments)]
229    fn finish(
230        self,
231        queue_wait: Duration,
232        transaction_acquire: Duration,
233        body: Duration,
234        commit: Duration,
235        succeeded: bool,
236        rows_changed: u64,
237    ) {
238        let total = self.submitted_at.elapsed();
239        let slow = self
240            .slow_write_threshold
241            .is_some_and(|threshold| total >= threshold);
242        // Labels are resolved only for a write that crossed the slow
243        // threshold, or for every write in per-attempt mode, so outside that
244        // mode a fast write never turns a site name into an allocation; its
245        // observation carries no labels.
246        let (labels, labels_truncated) = if slow || self.attempt_log {
247            self.resolve_labels()
248        } else {
249            (Vec::new(), None)
250        };
251        let observation = WriterStageObservation {
252            queue_wait_micros: duration_micros(queue_wait),
253            transaction_acquire_micros: duration_micros(transaction_acquire),
254            body_micros: duration_micros(body),
255            commit_micros: duration_micros(commit),
256            total_micros: duration_micros(total),
257            queue_depth_at_entry: self.queue_depth_at_entry as u64,
258            observed_at_unix_ms: observed_at_unix_ms(),
259            labels,
260            labels_truncated,
261        };
262        writer_stage_observations()
263            .lock()
264            .unwrap_or_else(std::sync::PoisonError::into_inner)
265            .insert(self.backend_key, observation.clone());
266
267        if slow {
268            crate::timeout_sink::emit_slow_write(&self.db, &observation);
269        }
270        if self.attempt_log {
271            crate::timeout_sink::emit_writer_attempt(
272                &self.db,
273                &observation,
274                crate::timeout_sink::WriterAttempt {
275                    request_id: self.request_id,
276                    succeeded,
277                    rows_changed,
278                    top_level: self.top_level,
279                },
280            );
281        }
282    }
283}
284
285struct ReplyReceipt<R> {
286    commit_issued: AtomicBool,
287    completed: Mutex<Option<Result<R, StorageError>>>,
288}
289
290impl<R> Default for ReplyReceipt<R> {
291    fn default() -> Self {
292        Self {
293            commit_issued: AtomicBool::new(false),
294            completed: Mutex::new(None),
295        }
296    }
297}
298
299impl<R> ReplyReceipt<R> {
300    fn completed(&self) -> std::sync::MutexGuard<'_, Option<Result<R, StorageError>>> {
301        self.completed
302            .lock()
303            .unwrap_or_else(std::sync::PoisonError::into_inner)
304    }
305}
306
307struct PendingWrite<R> {
308    reply_rx: oneshot::Receiver<Result<R, StorageError>>,
309    receipt: Arc<ReplyReceipt<R>>,
310}
311
312impl<R> PendingWrite<R> {
313    async fn wait(self) -> Result<R, StorageError> {
314        match self.reply_rx.await {
315            Ok(result) => result,
316            Err(source) => {
317                // A computed error is stronger evidence than a missing delivery, including
318                // a known rollback or a native SQLite failure before COMMIT.
319                if let Some(Err(error)) = self.receipt.completed().take() {
320                    return Err(error);
321                }
322                if self.receipt.commit_issued.load(Ordering::Acquire) {
323                    Err(StorageError::WriteOutcomeUnknown {
324                        source: Box::new(source),
325                    })
326                } else {
327                    Err(writer_task_terminated(
328                        WriterTaskRequestState::SideEffectsUnknown,
329                    ))
330                }
331            }
332        }
333    }
334}
335
336// Private drain tests also await the raw typed reply, without changing their assertions.
337#[cfg(test)]
338impl<R> std::future::Future for PendingWrite<R> {
339    type Output = Result<Result<R, StorageError>, oneshot::error::RecvError>;
340
341    fn poll(
342        self: std::pin::Pin<&mut Self>,
343        cx: &mut std::task::Context<'_>,
344    ) -> std::task::Poll<Self::Output> {
345        std::future::Future::poll(std::pin::Pin::new(&mut self.get_mut().reply_rx), cx)
346    }
347}
348
349/// One write request awaiting execution by the writer task.
350///
351/// Carries a typed closure and a typed oneshot reply so that the concrete
352/// return type `R` (e.g. `BatchWriteSummary`) is preserved end to end,
353/// while [`AnyWriteRequest`] lets the drain loop hold heterogeneous
354/// requests in one homogeneous channel.
355///
356/// `top_level` (ADR-067 Component A): when `true`,
357/// the drain loop runs this request's operation WITHOUT wrapping it in a
358/// `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` — still serialized through the
359/// single writer owner (only one request drains at a time regardless of
360/// this flag), but with the transaction wrap skipped entirely. Exists for
361/// statements SQLite forbids inside any open transaction (e.g. `VACUUM`);
362/// see [`WriterTaskHandle::send_top_level`].
363pub struct WriteRequest<R: Send + 'static> {
364    op: WriteOp<R>,
365    reply: oneshot::Sender<Result<R, StorageError>>,
366    receipt: Arc<ReplyReceipt<R>>,
367    top_level: bool,
368    /// Only the typed checkpoint entry point may bypass disk admission.
369    checkpoint_bypass: bool,
370    vacuum_copy_headroom: bool,
371    /// The lease class of the issuing thread's scope when the request was
372    /// queued, applied on the writer thread when it takes the volume lease.
373    lease_class: crate::disk_guard::WriteClassContext,
374    telemetry: WriteTelemetry,
375    admission: Option<AdmissionObservation>,
376}
377
378mod sealed {
379    /// Restricts [`super::AnyWriteRequest`] to implementations defined in
380    /// this module — only [`super::WriteRequest<R>`] implements it — and
381    /// carries the drain loop's internal terminal-state reporting methods
382    /// without changing the public execution-method signatures.
383    pub trait Sealed {
384        fn start_execution(&mut self);
385
386        fn execute_and_reply_reporting_terminal(
387            self: Box<Self>,
388            conn: &rusqlite::Connection,
389            tx_span: Option<khive_storage::tx_registry::TxHandle>,
390            queue_wait: std::time::Duration,
391            transaction_acquire: std::time::Duration,
392        ) -> Option<khive_storage::error::WriterTaskRequestState>;
393
394        fn execute_and_reply_top_level_reporting_terminal(
395            self: Box<Self>,
396            conn: &rusqlite::Connection,
397            queue_wait: std::time::Duration,
398        ) -> Option<khive_storage::error::WriterTaskRequestState>;
399
400        fn reply_error_after_begin(
401            self: Box<Self>,
402            err: khive_storage::error::StorageError,
403            queue_wait: std::time::Duration,
404            transaction_acquire: std::time::Duration,
405        );
406    }
407}
408
409/// Type-erased write request the writer task's drain loop can hold in a
410/// homogeneous channel (`mpsc::Sender<Box<dyn AnyWriteRequest + Send>>`),
411/// while each concrete [`WriteRequest<R>`] still carries its own typed
412/// reply. Sealed: only this module may implement it (ADR-067 lines
413/// 210-212).
414pub trait AnyWriteRequest: sealed::Sealed + Send {
415    /// Runs this request's operation against `conn`, commits or rolls back
416    /// the enclosing transaction based on the outcome, and sends the
417    /// (possibly commit-failure-adjusted) result to the request's oneshot
418    /// reply channel.
419    ///
420    /// `conn` must already be inside a successfully-opened `BEGIN IMMEDIATE`
421    /// transaction opened by the caller (`run_writer_task`) — this method
422    /// issues only `COMMIT` / `ROLLBACK`, never `BEGIN`, so `run_writer_task`
423    /// remains the sole issuer of `BEGIN IMMEDIATE` (ADR-067 Component A).
424    /// Callers must use [`Self::reply_error`] instead when the enclosing
425    /// `BEGIN IMMEDIATE` itself failed — this method must not be invoked in
426    /// that case.
427    fn execute_and_reply(self: Box<Self>, conn: &Connection);
428
429    /// Runs this request's operation directly against `conn` — no
430    /// transaction wrap, no `COMMIT`/`ROLLBACK` — and sends the result to
431    /// the request's oneshot reply channel.
432    ///
433    /// Used only for [`Self::is_top_level`] requests: the drain loop calls
434    /// this INSTEAD of `execute_and_reply` for such requests, skipping
435    /// `BEGIN IMMEDIATE` entirely so a statement that must run outside any
436    /// transaction (e.g. `VACUUM`) can still be serialized through the
437    /// single writer owner.
438    fn execute_and_reply_top_level(self: Box<Self>, conn: &Connection);
439
440    /// Replies with `err` without running this request's operation or
441    /// touching `conn`.
442    ///
443    /// Used when the enclosing `BEGIN IMMEDIATE` failed (for example,
444    /// `SQLITE_BUSY` from lock contention with an unmigrated writer path
445    /// still holding the pool's writer mutex — reachable while only
446    /// `entity.rs` is routed through this channel). Running the operation
447    /// anyway would execute its DML against `conn` in autocommit mode,
448    /// landing partial writes for a request the caller is told failed.
449    /// Skipping the operation entirely keeps "the caller got an error" and
450    /// "no rows landed" true together.
451    fn reply_error(self: Box<Self>, err: StorageError);
452
453    /// `true` if the drain loop must run this request via
454    /// [`Self::execute_and_reply_top_level`] (no transaction wrap) instead
455    /// of [`Self::execute_and_reply`] (wrapped in `BEGIN IMMEDIATE`).
456    fn is_top_level(&self) -> bool;
457
458    fn is_checkpoint_bypass(&self) -> bool;
459
460    fn needs_vacuum_headroom(&self) -> bool;
461
462    /// The issuing thread's lease-class context, captured when it was queued.
463    fn lease_class(&self) -> crate::disk_guard::WriteClassContext;
464
465    /// Time from the caller constructing this request (before bounded-channel
466    /// admission) until the writer task dequeued it.
467    fn queue_wait(&self) -> Duration;
468}
469
470#[derive(Debug, Clone, Copy, PartialEq, Eq)]
471enum RollbackDisposition {
472    RolledBack,
473    SideEffectsUnknown,
474}
475
476/// Roll back a failed wrapped request and verify that the connection really
477/// returned to autocommit mode before it can serve another request.
478fn rollback_after_failure(conn: &Connection, failure_context: &'static str) -> RollbackDisposition {
479    match conn.execute_batch("ROLLBACK") {
480        Ok(()) if conn.is_autocommit() => RollbackDisposition::RolledBack,
481        Ok(()) => {
482            tracing::error!(
483                failure_context,
484                "writer transaction: ROLLBACK returned success but the connection is still in a \
485                 transaction; request side effects are unknown"
486            );
487            RollbackDisposition::SideEffectsUnknown
488        }
489        Err(rollback_error) => {
490            tracing::error!(
491                error = %rollback_error,
492                failure_context,
493                "writer transaction: rollback after request failure failed; request side effects are \
494                 unknown"
495            );
496            RollbackDisposition::SideEffectsUnknown
497        }
498    }
499}
500
501/// Execute an operation inside an already-open transaction and apply the
502/// shared commit, rollback, panic, and autocommit verification rules.
503///
504/// This worker/owned adapter catches callback panics, attempts rollback, and
505/// returns a typed terminal outcome. In contrast, [`crate::pool::WriterGuard::transaction`]
506/// propagates callback panics and settles its owner during unwinding.
507pub(crate) fn execute_wrapped_transaction<R, F>(
508    conn: &Connection,
509    commit_operation: &'static str,
510    operation: F,
511) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
512where
513    F: FnOnce(&Connection) -> Result<R, StorageError>,
514{
515    let profiled = execute_wrapped_transaction_profiled(
516        conn,
517        commit_operation,
518        None,
519        false,
520        None,
521        operation,
522        #[cfg(test)]
523        None,
524    );
525    (profiled.result, profiled.terminal_state)
526}
527
528/// The standalone SQL bridge shares settlement rules while retaining its
529/// native commit error source and timeout/full observation site.
530pub(crate) fn execute_wrapped_sql_bridge_transaction<R, F>(
531    conn: &Connection,
532    commit_operation: &'static str,
533    db: &str,
534    operation: F,
535) -> (Result<R, StorageError>, Option<WriterTaskRequestState>)
536where
537    F: FnOnce(&Connection) -> Result<R, StorageError>,
538{
539    let profiled = execute_wrapped_transaction_profiled(
540        conn,
541        commit_operation,
542        Some(db),
543        true,
544        None,
545        operation,
546        #[cfg(test)]
547        None,
548    );
549    (profiled.result, profiled.terminal_state)
550}
551
552struct ProfiledWrappedTransaction<R> {
553    result: Result<R, StorageError>,
554    terminal_state: Option<WriterTaskRequestState>,
555    body: Duration,
556    commit: Duration,
557}
558
559fn execute_wrapped_transaction_profiled<R, F>(
560    conn: &Connection,
561    commit_operation: &'static str,
562    db: Option<&str>,
563    direct_sql_bridge: bool,
564    commit_issued: Option<&AtomicBool>,
565    operation: F,
566    #[cfg(test)] test_clock: Option<&dyn TestWriterStageClock>,
567) -> ProfiledWrappedTransaction<R>
568where
569    F: FnOnce(&Connection) -> Result<R, StorageError>,
570{
571    let body_started = Instant::now();
572    #[cfg(test)]
573    let body_started = test_clock.map_or(body_started, TestWriterStageClock::now);
574    // Keep panic-to-terminal conversion local to this adapter; the public
575    // WriterGuard transaction intentionally propagates the callback's unwind.
576    let operation_outcome = catch_unwind(AssertUnwindSafe(|| {
577        operation(conn).map_err(crate::error::statement_failure)
578    }));
579    #[cfg(not(test))]
580    let body = body_started.elapsed();
581    #[cfg(test)]
582    let body = test_clock.map_or_else(
583        || body_started.elapsed(),
584        |clock| clock.now().duration_since(body_started),
585    );
586
587    match operation_outcome {
588        Ok(Ok(value)) => {
589            let commit_started = Instant::now();
590            #[cfg(test)]
591            let commit_started = test_clock.map_or(commit_started, TestWriterStageClock::now);
592            #[cfg(test)]
593            if let Some(clock) = test_clock {
594                clock.at_commit();
595            }
596            if let Some(issued) = commit_issued {
597                issued.store(true, Ordering::Release);
598            }
599            #[cfg(any(test, feature = "test-support"))]
600            crate::test_hooks::commit_reply_issued(conn);
601            let commit_outcome = conn.execute_batch("COMMIT");
602            #[cfg(any(test, feature = "test-support"))]
603            crate::test_hooks::commit_reply_completed(
604                conn,
605                commit_outcome.is_ok(),
606                conn.is_autocommit(),
607            );
608            #[cfg(not(test))]
609            let commit = commit_started.elapsed();
610            #[cfg(test)]
611            let commit = test_clock.map_or_else(
612                || commit_started.elapsed(),
613                |clock| clock.now().duration_since(commit_started),
614            );
615            match commit_outcome {
616                Ok(()) if conn.is_autocommit() => ProfiledWrappedTransaction {
617                    result: Ok(value),
618                    terminal_state: None,
619                    body,
620                    commit,
621                },
622                Ok(()) => {
623                    tracing::error!(
624                    "writer transaction: COMMIT returned success but the connection is still in \
625                     a transaction; request side effects are unknown"
626                );
627                    let request_state = WriterTaskRequestState::SideEffectsUnknown;
628                    ProfiledWrappedTransaction {
629                        result: Err(writer_task_terminated(request_state)),
630                        terminal_state: Some(request_state),
631                        body,
632                        commit,
633                    }
634                }
635                Err(commit_error) => {
636                    if let Some(db) = db {
637                        if direct_sql_bridge {
638                            crate::timeout_sink::maybe_emit_busy(
639                                db,
640                                crate::timeout_sink::Site::StandaloneSqlBridge,
641                                &commit_error,
642                            );
643                        } else {
644                            crate::timeout_sink::maybe_emit_sqlite_full(db, &commit_error);
645                        }
646                    }
647                    match rollback_after_failure(conn, "commit failure") {
648                        RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
649                            result: Err(StorageError::WriterTaskRequestFailed {
650                                request_state: WriterTaskRequestState::TransactionRolledBack,
651                                source: Box::new({
652                                    let failure = crate::error::native_write_failure(
653                                        &commit_error,
654                                        khive_storage::error::SqliteWriteStage::Commit,
655                                    );
656                                    let error = if direct_sql_bridge {
657                                        StorageError::driver(
658                                            khive_storage::StorageCapability::Sql,
659                                            commit_operation,
660                                            commit_error,
661                                        )
662                                    } else {
663                                        StorageError::Pool {
664                                            operation: commit_operation.into(),
665                                            message: commit_error.to_string(),
666                                        }
667                                    };
668                                    match failure {
669                                        Some(failure) => error.with_sqlite_write_failure(failure),
670                                        None => error,
671                                    }
672                                }),
673                            }),
674                            terminal_state: None,
675                            body,
676                            commit,
677                        },
678                        RollbackDisposition::SideEffectsUnknown => {
679                            let request_state = WriterTaskRequestState::SideEffectsUnknown;
680                            ProfiledWrappedTransaction {
681                                result: Err(writer_task_terminated_with_cause(
682                                    request_state,
683                                    &commit_error,
684                                    khive_storage::error::SqliteWriteStage::Commit,
685                                )),
686                                terminal_state: Some(request_state),
687                                body,
688                                commit,
689                            }
690                        }
691                    }
692                }
693            }
694        }
695        Ok(Err(operation_error)) => {
696            match rollback_after_failure(conn, "request operation failure") {
697                RollbackDisposition::RolledBack => ProfiledWrappedTransaction {
698                    result: Err(StorageError::WriterTaskRequestFailed {
699                        request_state: WriterTaskRequestState::TransactionRolledBack,
700                        source: Box::new(operation_error),
701                    }),
702                    terminal_state: None,
703                    body,
704                    commit: Duration::ZERO,
705                },
706                RollbackDisposition::SideEffectsUnknown => {
707                    // SQLite may have already rolled back a failed transaction,
708                    // leaving no transaction for the explicit ROLLBACK.
709                    // Escalate the original cause once; retain native FULL evidence below.
710                    if let Some(db) = db {
711                        crate::timeout_sink::maybe_emit_sqlite_full(db, &operation_error);
712                    }
713                    let request_state = WriterTaskRequestState::SideEffectsUnknown;
714                    ProfiledWrappedTransaction {
715                        result: Err(writer_task_terminated_with_cause(
716                            request_state,
717                            &operation_error,
718                            khive_storage::error::SqliteWriteStage::Statement,
719                        )),
720                        terminal_state: Some(request_state),
721                        body,
722                        commit: Duration::ZERO,
723                    }
724                }
725            }
726        }
727        Err(_panic_payload) => {
728            let request_state = match rollback_after_failure(conn, "request panic") {
729                RollbackDisposition::RolledBack => WriterTaskRequestState::TransactionRolledBack,
730                RollbackDisposition::SideEffectsUnknown => {
731                    WriterTaskRequestState::SideEffectsUnknown
732                }
733            };
734            ProfiledWrappedTransaction {
735                result: Err(writer_task_terminated(request_state)),
736                terminal_state: Some(request_state),
737                body,
738                commit: Duration::ZERO,
739            }
740        }
741    }
742}
743
744fn reply_with_admission<R>(
745    reply: oneshot::Sender<Result<R, StorageError>>,
746    mut admission: Option<AdmissionObservation>,
747    receipt: &ReplyReceipt<R>,
748    suppress: bool,
749) {
750    if let Some(observation) = admission.as_mut() {
751        observation.reply_attempt();
752    }
753    if suppress {
754        drop(reply);
755        return;
756    }
757    let result = receipt.completed().take().expect("completed writer result");
758    let _ = reply.send(result);
759}
760
761impl<R: Send + 'static> sealed::Sealed for WriteRequest<R> {
762    fn start_execution(&mut self) {
763        if let Some(observation) = self.admission.as_mut() {
764            observation.start_execution();
765        }
766    }
767
768    fn execute_and_reply_reporting_terminal(
769        self: Box<Self>,
770        conn: &Connection,
771        tx_span: Option<khive_storage::tx_registry::TxHandle>,
772        queue_wait: Duration,
773        transaction_acquire: Duration,
774    ) -> Option<WriterTaskRequestState> {
775        // Keep the typed reply sender outside the unwind boundary. Calling
776        // `(self.op)(conn)` directly would drop `self.reply` while unwinding,
777        // leaving the active caller with only an untyped RecvError.
778        let WriteRequest {
779            op,
780            reply,
781            receipt,
782            telemetry,
783            admission,
784            ..
785        } = *self;
786        #[cfg(any(test, feature = "test-support"))]
787        let reply_probe = crate::test_hooks::begin_commit_reply_request(conn);
788        let changes_before = conn.total_changes();
789        let profiled = execute_wrapped_transaction_profiled(
790            conn,
791            "writer_task_commit",
792            Some(&telemetry.db),
793            false,
794            Some(&receipt.commit_issued),
795            op,
796            #[cfg(test)]
797            telemetry.test_clock.as_deref(),
798        );
799        let rows_changed = conn.total_changes().saturating_sub(changes_before);
800        let succeeded = profiled.result.is_ok();
801        *receipt.completed() = Some(profiled.result);
802        if let Some(Err(error)) = receipt.completed().as_ref() {
803            crate::timeout_sink::maybe_emit_sqlite_full(&telemetry.db, error);
804        }
805        // The reply wake can make the caller immediately observe the
806        // committed/error result. Deregister the transaction span first so
807        // tx_registry continues to mean "currently open SQL transaction",
808        // never "a transaction whose caller has already resumed" (#1790).
809        drop(tx_span);
810        telemetry.finish(
811            queue_wait,
812            transaction_acquire,
813            profiled.body,
814            profiled.commit,
815            succeeded,
816            rows_changed,
817        );
818        // The receiver may already be gone (caller dropped its future) —
819        // that is not this task's problem to report.
820        #[cfg(not(any(test, feature = "test-support")))]
821        let suppress = false;
822        #[cfg(any(test, feature = "test-support"))]
823        let suppress = reply_probe
824            .as_ref()
825            .is_some_and(|probe| probe.suppress_successful_reply());
826        reply_with_admission(reply, admission, &receipt, suppress);
827        profiled.terminal_state
828    }
829
830    fn execute_and_reply_top_level_reporting_terminal(
831        self: Box<Self>,
832        conn: &Connection,
833        queue_wait: Duration,
834    ) -> Option<WriterTaskRequestState> {
835        let WriteRequest {
836            op,
837            reply,
838            receipt,
839            telemetry,
840            admission,
841            ..
842        } = *self;
843        let changes_before = conn.total_changes();
844        let body_started = Instant::now();
845        let outcome = catch_unwind(AssertUnwindSafe(|| {
846            op(conn).map_err(crate::error::statement_failure)
847        }));
848        let body = body_started.elapsed();
849        let rows_changed = conn.total_changes().saturating_sub(changes_before);
850        let (result, terminal_state, open_transaction) = match outcome {
851            Ok(outcome) if conn.is_autocommit() => (outcome, None, false),
852            Ok(outcome) => {
853                let request_state = WriterTaskRequestState::SideEffectsUnknown;
854                let error = match outcome {
855                    Err(error) => writer_task_terminated_with_cause(
856                        request_state,
857                        &error,
858                        khive_storage::error::SqliteWriteStage::Statement,
859                    ),
860                    Ok(_) => writer_task_terminated(request_state),
861                };
862                (Err(error), Some(request_state), true)
863            }
864            Err(_panic_payload) => {
865                let state = WriterTaskRequestState::SideEffectsUnknown;
866                (Err(writer_task_terminated(state)), Some(state), false)
867            }
868        };
869        let succeeded = result.is_ok();
870        *receipt.completed() = Some(result);
871        let telemetry_db = telemetry.db.clone();
872        telemetry.finish(
873            queue_wait,
874            Duration::ZERO,
875            body,
876            Duration::ZERO,
877            succeeded,
878            rows_changed,
879        );
880        if open_transaction {
881            tracing::error!(
882                "writer task: top-level request returned with an open transaction; request \
883                 side effects are unknown"
884            );
885        } else if terminal_state.is_none() {
886            if let Some(Err(error)) = receipt.completed().as_ref() {
887                crate::timeout_sink::maybe_emit_sqlite_full(&telemetry_db, error);
888            }
889        }
890        reply_with_admission(reply, admission, &receipt, false);
891        terminal_state
892    }
893
894    fn reply_error_after_begin(
895        self: Box<Self>,
896        err: StorageError,
897        queue_wait: Duration,
898        transaction_acquire: Duration,
899    ) {
900        let WriteRequest {
901            reply,
902            receipt,
903            telemetry,
904            admission,
905            ..
906        } = *self;
907        *receipt.completed() = Some(Err(err));
908        telemetry.finish(
909            queue_wait,
910            transaction_acquire,
911            Duration::ZERO,
912            Duration::ZERO,
913            false,
914            0,
915        );
916        reply_with_admission(reply, admission, &receipt, false);
917    }
918}
919
920impl<R: Send + 'static> AnyWriteRequest for WriteRequest<R> {
921    fn execute_and_reply(mut self: Box<Self>, conn: &Connection) {
922        let queue_wait = self.queue_wait();
923        sealed::Sealed::start_execution(self.as_mut());
924        let _ = sealed::Sealed::execute_and_reply_reporting_terminal(
925            self,
926            conn,
927            None,
928            queue_wait,
929            Duration::ZERO,
930        );
931    }
932
933    fn execute_and_reply_top_level(mut self: Box<Self>, conn: &Connection) {
934        let queue_wait = self.queue_wait();
935        sealed::Sealed::start_execution(self.as_mut());
936        let _ =
937            sealed::Sealed::execute_and_reply_top_level_reporting_terminal(self, conn, queue_wait);
938    }
939
940    fn reply_error(self: Box<Self>, err: StorageError) {
941        let queue_wait = self.queue_wait();
942        sealed::Sealed::reply_error_after_begin(self, err, queue_wait, Duration::ZERO);
943    }
944
945    fn is_top_level(&self) -> bool {
946        self.top_level
947    }
948
949    fn is_checkpoint_bypass(&self) -> bool {
950        self.checkpoint_bypass
951    }
952
953    fn needs_vacuum_headroom(&self) -> bool {
954        self.vacuum_copy_headroom
955    }
956
957    fn lease_class(&self) -> crate::disk_guard::WriteClassContext {
958        self.lease_class
959    }
960
961    fn queue_wait(&self) -> Duration {
962        self.telemetry.queue_wait()
963    }
964}
965
966fn writer_task_terminated(request_state: WriterTaskRequestState) -> StorageError {
967    StorageError::writer_task_terminated(request_state)
968}
969
970fn writer_task_terminated_with_cause(
971    request_state: WriterTaskRequestState,
972    error: &(dyn std::error::Error + 'static),
973    stage: khive_storage::error::SqliteWriteStage,
974) -> StorageError {
975    let mut source = Some(error);
976    let mut sqlite_full_codes = None;
977    while let Some(current) = source {
978        if let Some(rusqlite::Error::SqliteFailure(code, _)) =
979            current.downcast_ref::<rusqlite::Error>()
980        {
981            if code.code == rusqlite::ErrorCode::DiskFull {
982                sqlite_full_codes = Some((code.extended_code & 0xff, code.extended_code));
983                break;
984            }
985        }
986        source = current.source();
987    }
988    // The original error was already escalated at the failing boundary.
989    // A source-free pair preserves caller evidence without duplicating that sink event.
990    let terminal = StorageError::WriterTaskTerminated {
991        request_state,
992        sqlite_full_codes,
993    };
994    match crate::error::native_write_failure(error, stage) {
995        Some(mut failure) => {
996            failure.settlement_unknown =
997                request_state == WriterTaskRequestState::SideEffectsUnknown;
998            terminal.with_sqlite_write_failure(failure)
999        }
1000        None => terminal,
1001    }
1002}
1003
1004fn writer_task_begin_error(error: rusqlite::Error, busy_timeout: Duration) -> StorageError {
1005    let failure =
1006        crate::error::native_write_failure(&error, khive_storage::error::SqliteWriteStage::Begin);
1007    let mapped = if crate::timeout_sink::is_busy_or_locked(&error) {
1008        StorageError::WriterTaskBusy {
1009            timeout_ms: u64::try_from(busy_timeout.as_millis()).unwrap_or(u64::MAX),
1010        }
1011    } else {
1012        StorageError::Pool {
1013            operation: "writer_task_begin".into(),
1014            message: error.to_string(),
1015        }
1016    };
1017    match failure {
1018        Some(failure) => mapped.with_sqlite_write_failure(failure),
1019        None => mapped,
1020    }
1021}
1022
1023/// Sender half of the write queue. Cheaply cloneable (wraps an
1024/// `mpsc::Sender`) — every migrated store that shares one writer task holds
1025/// a clone of this handle.
1026#[derive(Clone, Debug)]
1027pub struct WriterTaskHandle {
1028    tx: mpsc::Sender<Box<dyn AnyWriteRequest + Send>>,
1029    /// Exact canonical backend identity used by the in-memory stage registry.
1030    /// Kept separate from `db`, whose lossy display form is logging-only.
1031    backend_key: Option<PathBuf>,
1032    /// This handle's pool's writer-timeout sink identity (`timeout_sink::db_label`),
1033    /// captured at spawn so `send_with_timeout`'s `WriteQueueFull` path can
1034    /// report a `queue_saturation` sink row (ADR-136 D1 gate 6a) without
1035    /// needing a `&ConnectionPool` reference.
1036    db: String,
1037    /// Slow-write latency bound (`timeout_sink::slow_write_threshold`),
1038    /// resolved once at spawn. `None` disables slow-write rows. Captured
1039    /// here rather than read per send so the caller path pays no env lookup
1040    /// and tests get a deterministic value by setting the override before
1041    /// spawning their own writer task.
1042    slow_write_threshold: Option<std::time::Duration>,
1043    /// Per-attempt mode (`timeout_sink::writer_attempt_log_enabled`),
1044    /// resolved once at spawn like the slow-write bound.
1045    attempt_log: bool,
1046    /// Default enqueue-capacity deadline for [`Self::send_bounded`] /
1047    /// [`Self::send_top_level_bounded`], captured from
1048    /// `PoolConfig::write_admission_deadline_ms` at [`spawn`] (ADR-131
1049    /// Decision 2). Bounds ONLY the wait for channel capacity, the same
1050    /// boundary `send_with_timeout` already documents — never the reply wait
1051    /// after acceptance (#1382).
1052    ///
1053    /// This is a dedicated admission authority, distinct from
1054    /// `PoolConfig::checkout_timeout` (reader/pool checkout). The two used
1055    /// to be conflated here before ADR-131 Decision 2 (#1382, #1643).
1056    ///
1057    /// ADR-131 Decision 2's outer-request-budget clamp ("when the caller's outer
1058    /// request deadline leaves less time remaining than the configured
1059    /// admission deadline, the admission deadline applied to that operation
1060    /// is the remaining outer budget instead") is explicitly DEFERRED: no
1061    /// outer request deadline is plumbed to `send_bounded` /
1062    /// `send_top_level_bounded`'s call sites as of #1737, so there is no
1063    /// budget to clamp against. When an outer deadline reaches this call
1064    /// path, clamp here rather than faking a shorter deadline against a
1065    /// nonexistent budget.
1066    enqueue_timeout: std::time::Duration,
1067    admission_metrics: Arc<WriterAdmissionMetrics>,
1068    strict_routing: bool,
1069}
1070
1071impl WriterTaskHandle {
1072    pub(crate) fn is_closed(&self) -> bool {
1073        self.tx.is_closed()
1074    }
1075
1076    fn unavailable_before_acceptance(&self) -> StorageError {
1077        if self.strict_routing {
1078            StorageError::WriterOwnerUnavailable {
1079                operation: "writer_task_enqueue".into(),
1080                source: Box::new(StorageError::Pool {
1081                    operation: "writer_task_enqueue".into(),
1082                    message: "writer owner is stopped".into(),
1083                }),
1084            }
1085        } else {
1086            writer_task_terminated(WriterTaskRequestState::NotStarted)
1087        }
1088    }
1089
1090    /// Enqueue a write operation and return the oneshot receiver its reply
1091    /// will arrive on, once the request has actually been accepted onto the
1092    /// channel.
1093    ///
1094    /// Shared by [`Self::send`] and [`Self::send_with_timeout`] so that a
1095    /// caller-supplied deadline (see `send_with_timeout`) can bound ONLY
1096    /// this enqueue step — never the reply-wait that follows it. Once this
1097    /// returns `Ok`, the request has been accepted by the writer task and
1098    /// will either run to completion or receive a typed terminal error if an
1099    /// earlier request kills the task before this operation begins. The
1100    /// returned receiver must be awaited without a timeout; abandoning it
1101    /// here would silently drop the request's eventual result, not cancel the
1102    /// request itself.
1103    async fn enqueue<R, F>(&self, op: F) -> Result<PendingWrite<R>, StorageError>
1104    where
1105        R: Send + 'static,
1106        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1107    {
1108        self.enqueue_inner(op, false, false, false, SubmitLabels::None)
1109            .await
1110    }
1111
1112    /// Shared enqueue path for both transaction-wrapped ([`Self::enqueue`])
1113    /// and top-level ([`Self::send_top_level`]) requests — `top_level`
1114    /// controls which [`AnyWriteRequest`] method the drain loop invokes.
1115    /// `labels` is what the submit site knows about this request's
1116    /// statements; see [`SubmitLabels`].
1117    async fn enqueue_inner<R, F>(
1118        &self,
1119        op: F,
1120        top_level: bool,
1121        checkpoint_bypass: bool,
1122        vacuum_copy_headroom: bool,
1123        labels: SubmitLabels,
1124    ) -> Result<PendingWrite<R>, StorageError>
1125    where
1126        R: Send + 'static,
1127        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1128    {
1129        let (reply_tx, reply_rx) = oneshot::channel();
1130        let receipt = Arc::new(ReplyReceipt::default());
1131        // Normalize here (once per request) so every submit path — including
1132        // the public `send_labelled` entry points a caller can hand a raw
1133        // list — records distinct labels in first-seen order. Bounding stays
1134        // in `resolve_labels`, which runs only on the slow path.
1135        let labels = match labels {
1136            SubmitLabels::Statements(labels) => {
1137                SubmitLabels::Statements(dedup_labels(labels.iter().map(String::as_str)))
1138            }
1139            other => other,
1140        };
1141        let telemetry = WriteTelemetry::new(
1142            self.backend_key.clone(),
1143            self.db.clone(),
1144            self.queue_depth(),
1145            self.slow_write_threshold,
1146            labels,
1147            self.attempt_log,
1148            top_level,
1149        );
1150        let mut request = Box::new(WriteRequest {
1151            op: Box::new(op),
1152            reply: reply_tx,
1153            receipt: Arc::clone(&receipt),
1154            top_level,
1155            checkpoint_bypass,
1156            vacuum_copy_headroom,
1157            lease_class: crate::disk_guard::WriteClassContext::capture(),
1158            telemetry,
1159            admission: None,
1160        });
1161        request.admission = Some(self.admission_metrics.offer());
1162        let permit = self
1163            .tx
1164            .reserve()
1165            .await
1166            .map_err(|_| self.unavailable_before_acceptance())?;
1167        if let Some(observation) = request.admission.as_mut() {
1168            observation.accepted();
1169        }
1170        permit.send(request);
1171
1172        Ok(PendingWrite { reply_rx, receipt })
1173    }
1174
1175    /// Send a write operation to the writer task and await its typed reply.
1176    ///
1177    /// Backpressure: this suspends on the channel's `send().await` when the
1178    /// bounded queue is full (ADR-067 "Channel capacity and queue-full
1179    /// policy") — there is no `try_send` escape hatch. Callers that need a
1180    /// deadline on that wait should use [`Self::send_with_timeout`] instead.
1181    pub async fn send<R, F>(&self, op: F) -> Result<R, StorageError>
1182    where
1183        R: Send + 'static,
1184        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1185    {
1186        let reply_rx = self.enqueue(op).await?;
1187        reply_rx.wait().await
1188    }
1189
1190    /// Like [`Self::send`], but bounds the wait for the bounded channel to
1191    /// free capacity with `timeout`.
1192    ///
1193    /// The timeout applies ONLY to enqueueing the request (the channel
1194    /// `send().await` that can suspend on a full queue) — never to waiting
1195    /// for the writer task's reply once the request has been accepted.
1196    /// `StorageError::WriteQueueFull` means exactly "the bounded channel was
1197    /// full and this request was never accepted"; it must never be returned
1198    /// for a request that was accepted and is still executing (or already
1199    /// committed) by the time `timeout` elapses — that would misreport a
1200    /// slow op or a lock wait as a queue-capacity failure, and could tell a
1201    /// caller a write failed when it actually landed. ADR-067's queue-full
1202    /// policy has no immediate-error `try_send` path — only this caller-side
1203    /// deadline on the enqueue step.
1204    pub async fn send_with_timeout<R, F>(
1205        &self,
1206        op: F,
1207        timeout: std::time::Duration,
1208    ) -> Result<R, StorageError>
1209    where
1210        R: Send + 'static,
1211        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1212    {
1213        self.send_with_timeout_labelled(op, timeout, SubmitLabels::None)
1214            .await
1215    }
1216
1217    /// Shared body of [`Self::send_with_timeout`] and its labelled variants.
1218    /// `labels` is carried onto the request's writer-stage observation and
1219    /// `slow_write` row; see [`SubmitLabels`].
1220    async fn send_with_timeout_labelled<R, F>(
1221        &self,
1222        op: F,
1223        timeout: std::time::Duration,
1224        labels: SubmitLabels,
1225    ) -> Result<R, StorageError>
1226    where
1227        R: Send + 'static,
1228        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1229    {
1230        let reply_rx = match tokio::time::timeout(
1231            timeout,
1232            self.enqueue_inner(op, false, false, false, labels),
1233        )
1234        .await
1235        {
1236            Ok(Ok(reply_rx)) => reply_rx,
1237            Ok(Err(e)) => return Err(e),
1238            Err(_elapsed) => {
1239                let timeout_ms = timeout.as_millis() as u64;
1240                self.admission_metrics.record_capacity_deadline();
1241                crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1242                return Err(StorageError::WriteQueueFull { timeout_ms });
1243            }
1244        };
1245
1246        reply_rx.wait().await
1247    }
1248
1249    /// Like [`Self::send`], but bounds the enqueue-capacity wait with this
1250    /// handle's configured `enqueue_timeout`
1251    /// (`PoolConfig::write_admission_deadline_ms` at spawn time, ADR-131
1252    /// Decision 2) instead of waiting indefinitely (#1382).
1253    ///
1254    /// Once the request is accepted onto the channel, the reply wait is
1255    /// unbounded by this method, identical to [`Self::send`] — this bounds
1256    /// only queue-capacity admission, never SQLite execution or reply
1257    /// latency. Callers that need a non-default deadline should use
1258    /// [`Self::send_with_timeout`] directly.
1259    pub async fn send_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1260    where
1261        R: Send + 'static,
1262        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1263    {
1264        self.send_with_timeout(op, self.enqueue_timeout).await
1265    }
1266
1267    /// Send a write operation that MUST run outside any open transaction
1268    /// (e.g. `VACUUM`, which SQLite forbids inside `BEGIN`/`COMMIT`) and
1269    /// await its typed reply.
1270    ///
1271    /// Still serialized through the same single writer owner as
1272    /// [`Self::send`] — the request goes through the identical bounded
1273    /// channel and drain loop, one request at a time — but the drain loop
1274    /// skips the per-request `BEGIN IMMEDIATE`/`COMMIT`/`ROLLBACK` wrap
1275    /// entirely for this request (ADR-067 Component A). The single-writer
1276    /// guarantee is preserved; only
1277    /// the transaction wrap is skipped.
1278    pub async fn send_top_level<R, F>(&self, op: F) -> Result<R, StorageError>
1279    where
1280        R: Send + 'static,
1281        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1282    {
1283        let reply_rx = self
1284            .enqueue_inner(op, true, false, false, SubmitLabels::None)
1285            .await?;
1286        reply_rx.wait().await
1287    }
1288
1289    /// Like [`Self::send_top_level`], but bounds the enqueue-capacity wait
1290    /// with this handle's configured `enqueue_timeout`, mirroring
1291    /// [`Self::send_bounded`] for top-level (transaction-skipping) requests
1292    /// (#1382).
1293    pub async fn send_top_level_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1294    where
1295        R: Send + 'static,
1296        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1297    {
1298        self.send_top_level_bounded_inner(op, false, false, SubmitLabels::None)
1299            .await
1300    }
1301
1302    /// Checkpoint-only top-level dispatch. It remains serialized by the
1303    /// writer task but never waits for the capacity lease or floor probe.
1304    pub(crate) async fn send_checkpoint_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1305    where
1306        R: Send + 'static,
1307        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1308    {
1309        self.send_top_level_bounded_inner(op, true, false, SubmitLabels::Site("wal_checkpoint"))
1310            .await
1311    }
1312
1313    /// Typed VACUUM dispatch with a copy-sized metadata estimate at dequeue.
1314    pub(crate) async fn send_vacuum_bounded<R, F>(&self, op: F) -> Result<R, StorageError>
1315    where
1316        R: Send + 'static,
1317        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1318    {
1319        self.send_top_level_bounded_inner(op, false, true, SubmitLabels::Site("vacuum"))
1320            .await
1321    }
1322
1323    async fn send_top_level_bounded_inner<R, F>(
1324        &self,
1325        op: F,
1326        checkpoint_bypass: bool,
1327        vacuum_copy_headroom: bool,
1328        labels: SubmitLabels,
1329    ) -> Result<R, StorageError>
1330    where
1331        R: Send + 'static,
1332        F: FnOnce(&Connection) -> Result<R, StorageError> + Send + 'static,
1333    {
1334        let reply_rx = match tokio::time::timeout(
1335            self.enqueue_timeout,
1336            self.enqueue_inner(op, true, checkpoint_bypass, vacuum_copy_headroom, labels),
1337        )
1338        .await
1339        {
1340            Ok(Ok(reply_rx)) => reply_rx,
1341            Ok(Err(e)) => return Err(e),
1342            Err(_elapsed) => {
1343                let timeout_ms = self.enqueue_timeout.as_millis() as u64;
1344                self.admission_metrics.record_capacity_deadline();
1345                crate::timeout_sink::emit_queue_saturation(&self.db, timeout_ms);
1346                return Err(StorageError::WriteQueueFull { timeout_ms });
1347            }
1348        };
1349
1350        reply_rx.wait().await
1351    }
1352
1353    /// Current write-queue backlog depth: requests enqueued but not yet
1354    /// accepted by the writer task's drain loop.
1355    ///
1356    /// Reads `mpsc::Sender::max_capacity() - capacity()`, so it is a
1357    /// point-in-time snapshot racy under concurrent senders/the drain loop
1358    /// draining concurrently — acceptable for a monitoring gauge (the
1359    /// load/perf harness metrics read-surface), never used for any correctness
1360    /// decision.
1361    pub fn queue_depth(&self) -> usize {
1362        self.tx.max_capacity() - self.tx.capacity()
1363    }
1364
1365    /// The bounded channel's configured capacity
1366    /// (`PoolConfig::write_queue_capacity`).
1367    pub fn capacity(&self) -> usize {
1368        self.tx.max_capacity()
1369    }
1370
1371    pub(crate) fn admission_snapshot(&self) -> Result<Snapshot, Unavailable> {
1372        self.admission_metrics.snapshot()
1373    }
1374}
1375
1376/// Spawn the write-owner task (ADR-067 Component A) on the current Tokio
1377/// runtime.
1378///
1379/// Opens a dedicated standalone writer connection independent of the pool's
1380/// Mutex-guarded `writer()` connection used by unmigrated paths. That one-time
1381/// infrastructure open is uncounted; every dequeued top-level request or
1382/// successful `BEGIN IMMEDIATE` increments the writer-task acquisition class.
1383/// Returns the cloneable [`WriterTaskHandle`] sender half. The task normally
1384/// runs until every handle clone is dropped and the channel closes; a request
1385/// panic, failed rollback, or poisoned connection puts it into the permanent
1386/// terminal state documented below.
1387///
1388/// # Terminal settlement
1389/// Retiring an unsettled writer, including when its blocking owner unwinds,
1390/// releases the volume lease only after cleanup restored autocommit or the
1391/// connection closed. If neither is possible, path, volume, and errors are
1392/// reported to stderr and tracing and the pool is poisoned: that request
1393/// reports [`SqliteError::WriterSettlementUnknown`] and every later write is
1394/// refused with [`SqliteError::WriterPoisoned`] before it starts.
1395///
1396/// `capacity` bounds the channel (`PoolConfig::write_queue_capacity` /
1397/// `KHIVE_WRITE_QUEUE_CAPACITY`, ADR-067 recommends 256).
1398///
1399/// # Errors
1400/// Must be called from within a Tokio runtime context (calls
1401/// `tokio::spawn`). Returns an error if the pool cannot open a standalone
1402/// writer connection (e.g. an in-memory pool has no standalone-connection
1403/// support). See `crates/khive-db/docs/api/writer-task.md` for the
1404/// migration-slice scope this commits per `BEGIN IMMEDIATE`.
1405pub fn spawn(pool: &ConnectionPool, capacity: usize) -> Result<WriterTaskHandle, SqliteError> {
1406    pool.spawn_writer_task(capacity)
1407}
1408
1409/// Consume a verified lifetime connection inside its admission-owning task.
1410/// Only the pool's private connection factory opens that connection.
1411pub(crate) fn spawn_with_connection(
1412    pool: &ConnectionPool,
1413    conn: Connection,
1414    capacity: usize,
1415) -> Result<WriterTaskHandle, SqliteError> {
1416    // The lifetime connection is infrastructure, not one acquisition per
1417    // write. Each dequeued request is counted below at the task's actual
1418    // ownership boundary instead.
1419    let acquisition_counters = pool.writer_acquisition_counters();
1420    let write_admission = pool.write_admission();
1421    let busy_timeout = pool.config().busy_timeout;
1422    let origin = pool.origin();
1423    let backend_key = writer_db_key(pool);
1424    let db = crate::timeout_sink::db_label(pool);
1425    let (tx, rx) = mpsc::channel(capacity.max(1));
1426    let join = tokio::spawn(run_writer_task(
1427        (conn, pool.timeout_sink_writer_lease()),
1428        rx,
1429        origin,
1430        db.clone(),
1431        acquisition_counters,
1432        write_admission,
1433        busy_timeout,
1434    ));
1435    // Stored on the pool (not returned) so the handle's clone-and-share
1436    // contract stays untouched; see ConnectionPool::take_writer_task_join
1437    // for who awaits it and why.
1438    pool.set_writer_task_join(join);
1439    Ok(WriterTaskHandle {
1440        tx,
1441        backend_key,
1442        db,
1443        slow_write_threshold: crate::timeout_sink::slow_write_threshold(),
1444        attempt_log: crate::timeout_sink::writer_attempt_log_enabled(),
1445        enqueue_timeout: std::time::Duration::from_millis(
1446            pool.config().write_admission_deadline_ms,
1447        ),
1448        admission_metrics: WriterAdmissionMetrics::new(),
1449        strict_routing: pool.config().write_routing_strict,
1450    })
1451}
1452
1453/// Permanently close admission, then reply to every request that was already
1454/// accepted into the bounded channel without invoking its operation closure.
1455///
1456/// Closing before draining is load-bearing: draining an open receiver would
1457/// wait forever while [`WriterTaskHandle`] clones still exist, while dropping
1458/// the receiver immediately would discard buffered requests and their typed
1459/// reply senders.
1460async fn close_and_fail_queued_requests(rx: &mut mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>) {
1461    rx.close();
1462    while let Some(request) = rx.recv().await {
1463        request.reply_error(writer_task_terminated(WriterTaskRequestState::NotStarted));
1464    }
1465}
1466
1467/// Acquire the request transaction without multiplying its busy-timeout budget.
1468/// The setter is supplied so tests can fail SQLite's timeout update while still
1469/// executing real BEGIN statements; production uses `Connection::busy_timeout`.
1470fn begin_immediate_with_retry(
1471    conn: &Connection,
1472    acquisition_counters: &WriterAcquisitionCounters,
1473    busy_timeout: Duration,
1474    mut set_busy_timeout: impl FnMut(&Connection, Duration) -> rusqlite::Result<()>,
1475) -> (rusqlite::Result<()>, Duration, u32) {
1476    let transaction_acquire_started = Instant::now();
1477    let mut begin_attempt = 1_u32;
1478    let mut retry_delays = WRITER_BEGIN_RETRY_DELAYS.into_iter();
1479    let mut busy_timeout_lowered = false;
1480    let begin_outcome = loop {
1481        match conn.execute_batch("BEGIN IMMEDIATE") {
1482            Ok(()) => break Ok(()),
1483            Err(error) if crate::timeout_sink::is_busy_or_locked(&error) => {
1484                // Every busy/locked refusal is counted here,
1485                // whether or not it goes on to be retried: this
1486                // is the pre-PR meaning of the counter, and the
1487                // outer match below no longer counts the final
1488                // refusal a second time.
1489                acquisition_counters.record_writer_task_begin_busy();
1490                let Some(delay) = retry_delays.next() else {
1491                    break Err(error);
1492                };
1493                // The whole retry sequence shares one
1494                // `busy_timeout` budget: each SQLite attempt is
1495                // itself bounded by `busy_timeout`, so without a
1496                // shrinking budget three attempts could each
1497                // wait out a full window and multiply the
1498                // serialized writer's contention window instead
1499                // of bounding it.
1500                let remaining_budget =
1501                    busy_timeout.saturating_sub(transaction_acquire_started.elapsed());
1502                if remaining_budget.is_zero() {
1503                    break Err(error);
1504                }
1505                if let Err(set_err) = set_busy_timeout(conn, remaining_budget) {
1506                    tracing::warn!(
1507                        error = %set_err,
1508                        "writer task: failed to lower busy_timeout for BEGIN \
1509                         retry; surfacing the original busy refusal"
1510                    );
1511                    // A retry with the old timeout could exceed the shared budget.
1512                    break Err(error);
1513                }
1514                busy_timeout_lowered = true;
1515                // Count only refusals that will actually be retried. A failed
1516                // timeout reduction leaves this refusal visible to the caller.
1517                acquisition_counters.record_writer_task_begin_busy_absorbed();
1518                tracing::debug!(
1519                    attempt = begin_attempt,
1520                    backoff_ms = delay.as_millis() as u64,
1521                    budget_remaining_ms = remaining_budget.as_millis() as u64,
1522                    "writer task: BEGIN IMMEDIATE refused busy; retrying before \
1523                     request execution"
1524                );
1525                std::thread::sleep(delay);
1526                begin_attempt = begin_attempt.saturating_add(1);
1527            }
1528            Err(error) => break Err(error),
1529        }
1530    };
1531    let transaction_acquire = transaction_acquire_started.elapsed();
1532    // Restore the pool-configured busy_timeout only if a retry
1533    // actually lowered it, so the common uncontended request
1534    // never pays for an extra pragma write; the next request
1535    // dequeued on this same connection must still start from
1536    // the full configured budget.
1537    if busy_timeout_lowered {
1538        if let Err(restore_err) = set_busy_timeout(conn, busy_timeout) {
1539            tracing::warn!(
1540                error = %restore_err,
1541                "writer task: failed to restore busy_timeout after a BEGIN retry \
1542                 sequence"
1543            );
1544        }
1545    }
1546    (begin_outcome, transaction_acquire, begin_attempt)
1547}
1548
1549struct BlockingWriterConnection {
1550    conn: Option<Connection>,
1551    admission: Arc<crate::pool::WriteAdmission>,
1552    volume_lease: Option<crate::disk_guard::VolumeLease>,
1553}
1554
1555impl BlockingWriterConnection {
1556    fn new(conn: Connection, admission: Arc<crate::pool::WriteAdmission>) -> Self {
1557        Self {
1558            conn: Some(conn),
1559            admission,
1560            volume_lease: None,
1561        }
1562    }
1563
1564    fn finish(
1565        mut self,
1566        state: Option<WriterTaskRequestState>,
1567    ) -> (Option<Connection>, Option<WriterTaskRequestState>) {
1568        if state.is_some() {
1569            self.retire();
1570            (None, state)
1571        } else {
1572            (self.conn.take(), None)
1573        }
1574    }
1575
1576    fn retire(&mut self) {
1577        if let Some(conn) = self.conn.take() {
1578            // A terminal failure has poisoned the admission; the request that
1579            // retired this writer already carries its terminal state.
1580            let _ = self.admission.close_retired_connection(conn);
1581        }
1582    }
1583}
1584
1585impl Drop for BlockingWriterConnection {
1586    fn drop(&mut self) {
1587        self.retire();
1588    }
1589}
1590
1591impl std::ops::Deref for BlockingWriterConnection {
1592    type Target = Connection;
1593
1594    fn deref(&self) -> &Connection {
1595        self.conn
1596            .as_ref()
1597            .expect("blocking writer owns its connection until settlement")
1598    }
1599}
1600
1601/// Drain loop: the sole caller of `BEGIN IMMEDIATE` for write traffic routed
1602/// through the channel. Busy/locked `BEGIN IMMEDIATE` refusals receive the
1603/// bounded retry above before a final failure replies the request's error via
1604/// [`AnyWriteRequest::reply_error`] without invoking the request's closure.
1605///
1606/// A request-operation panic is contained inside the concrete
1607/// [`WriteRequest<R>`] so its typed reply survives. A panic, failed rollback,
1608/// or otherwise poisoned connection makes the task terminal. The task then
1609/// closes admission, explicitly fails every already-queued request as
1610/// [`WriterTaskRequestState::NotStarted`], and exits permanently. There is no
1611/// supervisor or connection restart; later sends observe the closed channel.
1612/// See
1613/// `crates/khive-db/docs/api/writer-task.md` for the full failure matrix.
1614async fn run_writer_task(
1615    mut owner: (Connection, Option<crate::timeout_sink::WriterLease>),
1616    mut rx: mpsc::Receiver<Box<dyn AnyWriteRequest + Send>>,
1617    origin: khive_storage::tx_registry::TxOrigin,
1618    db: String,
1619    acquisition_counters: Arc<WriterAcquisitionCounters>,
1620    write_admission: Arc<crate::pool::WriteAdmission>,
1621    busy_timeout: Duration,
1622) {
1623    #[cfg(any(test, feature = "test-support"))]
1624    if let Err(error) = crate::test_hooks::adopt(&mut owner.0) {
1625        tracing::error!(%error, "writer task: test hook registration failed");
1626    }
1627    while let Some(mut request) = rx.recv().await {
1628        // The bounded-channel wait ends at this exact dequeue boundary.
1629        // Sampling inside the blocking closure would misattribute a saturated
1630        // Tokio blocking pool to writer-queue contention (#1849).
1631        let queue_wait = request.queue_wait();
1632        sealed::Sealed::start_execution(request.as_mut());
1633        let origin = origin.clone();
1634        let blocking_counters = Arc::clone(&acquisition_counters);
1635        let blocking_admission = Arc::clone(&write_admission);
1636        let blocking_db = db.clone();
1637        // Tuple field order drops the connection before its sink lease, both
1638        // while idle and when a cancelled parent discards a native result.
1639        let conn = owner.0;
1640        let blocking_sink_lease = owner.1.clone();
1641        let outcome = tokio::task::spawn_blocking(move || {
1642            // The issuer's lease class applies on this thread, so the lease
1643            // taken below is recorded as what the issuer's work is for.
1644            let _lease_class = request.lease_class().enter();
1645            let outcome = (|| {
1646                let mut conn = BlockingWriterConnection::new(conn, Arc::clone(&blocking_admission));
1647                let acquisition_counters = blocking_counters;
1648                // A top-level request deliberately skips BEGIN, so it would
1649                // silently join any transaction leaked by an earlier request.
1650                // Refuse every request before dispatch if the connection is not
1651                // demonstrably clean, then retire the writer task.
1652                if !conn.is_autocommit() {
1653                    tracing::error!(
1654                    "writer task: connection is not in autocommit mode before request dispatch; \
1655                     retiring the poisoned writer without running the request"
1656                );
1657                    let request_state = WriterTaskRequestState::NotStarted;
1658                    request.reply_error(writer_task_terminated(request_state));
1659                    return conn.finish(Some(request_state));
1660                }
1661
1662                // The lease precedes SQLite writer acquisition and remains held
1663                // until the request has committed, rolled back, or returned to
1664                // autocommit. Checkpoint requests deliberately skip both steps.
1665                conn.volume_lease = if request.is_checkpoint_bypass() {
1666                    None
1667                } else {
1668                    let class = if request.needs_vacuum_headroom() {
1669                        crate::disk_guard::LeaseClass::Maintenance
1670                    } else {
1671                        crate::disk_guard::LeaseClass::WriterTask
1672                    };
1673                    match blocking_admission.acquire(class) {
1674                        Ok(lease) => lease,
1675                        Err(error) => {
1676                            request.reply_error(error.into_storage_error(
1677                                khive_storage::StorageCapability::Sql,
1678                                "writer_task_admission",
1679                            ));
1680                            return conn.finish(None);
1681                        }
1682                    }
1683                };
1684
1685                let terminal_state = if request.is_top_level() {
1686                    if !request.is_checkpoint_bypass() {
1687                        let admission = if request.needs_vacuum_headroom() {
1688                            blocking_admission.check_for_vacuum()
1689                        } else {
1690                            blocking_admission.check()
1691                        };
1692                        if let Err(error) = admission {
1693                            request.reply_error(error.into_storage_error(
1694                                khive_storage::StorageCapability::Sql,
1695                                "writer_task_admission",
1696                            ));
1697                            return conn.finish(None);
1698                        }
1699                    }
1700                    // ADR-067 Component A:
1701                    // no BEGIN IMMEDIATE for this request — some statements
1702                    // (e.g. VACUUM) are rejected by SQLite inside any open
1703                    // transaction. Still runs on this task's dedicated
1704                    // connection and still serialized one-request-at-a-time by
1705                    // this same drain loop, so the single-writer guarantee
1706                    // holds; only the transaction wrap is skipped.
1707                    acquisition_counters.record_writer_task_acquisition();
1708                    sealed::Sealed::execute_and_reply_top_level_reporting_terminal(
1709                        request, &conn, queue_wait,
1710                    )
1711                } else {
1712                    let tx_span = khive_storage::tx_registry::register_scoped(
1713                        Some("writer_task_tx".to_string()),
1714                        origin,
1715                    );
1716                    let (begin_outcome, transaction_acquire, begin_attempt) =
1717                        begin_immediate_with_retry(
1718                            &conn,
1719                            &acquisition_counters,
1720                            busy_timeout,
1721                            Connection::busy_timeout,
1722                        );
1723                    match begin_outcome {
1724                        Ok(()) => {
1725                            if let Err(error) = blocking_admission.check() {
1726                                let request_state =
1727                                    match rollback_after_failure(&conn, "capacity admission") {
1728                                        RollbackDisposition::RolledBack => None,
1729                                        RollbackDisposition::SideEffectsUnknown => {
1730                                            Some(WriterTaskRequestState::SideEffectsUnknown)
1731                                        }
1732                                    };
1733                                drop(tx_span);
1734                                let error = if let Some(state) = request_state {
1735                                    writer_task_terminated(state)
1736                                } else {
1737                                    error.into_storage_error(
1738                                        khive_storage::StorageCapability::Sql,
1739                                        "writer_task_admission",
1740                                    )
1741                                };
1742                                sealed::Sealed::reply_error_after_begin(
1743                                    request,
1744                                    error,
1745                                    queue_wait,
1746                                    transaction_acquire,
1747                                );
1748                                return conn.finish(request_state);
1749                            }
1750                            acquisition_counters.record_writer_task_acquisition();
1751                            sealed::Sealed::execute_and_reply_reporting_terminal(
1752                                request,
1753                                &conn,
1754                                Some(tx_span),
1755                                queue_wait,
1756                                transaction_acquire,
1757                            )
1758                        }
1759                        Err(e) => {
1760                            // Do NOT run the request's operation: `conn` never
1761                            // entered a transaction, so executing the op's DML
1762                            // here would run in autocommit mode and land partial
1763                            // writes for a request the caller is about to be told
1764                            // failed.
1765                            crate::timeout_sink::maybe_emit_sqlite_full(&blocking_db, &e);
1766                            tracing::warn!(
1767                                error = %e,
1768                                attempts = begin_attempt,
1769                                "writer task: BEGIN IMMEDIATE failed; replying an \
1770                                 error without running the request's operation"
1771                            );
1772                            // Although BEGIN never opened a SQL transaction, the
1773                            // scoped attempt is observable in tx_registry. Drop
1774                            // it before waking the caller for the same reply-side
1775                            // lifecycle guarantee as successful requests (#1790).
1776                            drop(tx_span);
1777                            // A busy/locked refusal was already counted inside
1778                            // the retry loop above, including this final one —
1779                            // classifying and counting it again here would
1780                            // double it. Only a non-busy BEGIN failure (which
1781                            // never enters the retry loop's busy arm) still
1782                            // needs its counter recorded at this seam.
1783                            let begin_error = writer_task_begin_error(e, busy_timeout);
1784                            if !matches!(
1785                                begin_error.without_sqlite_write_stage(),
1786                                StorageError::WriterTaskBusy { .. }
1787                            ) {
1788                                acquisition_counters.record_writer_task_begin_error();
1789                            }
1790                            sealed::Sealed::reply_error_after_begin(
1791                                request,
1792                                begin_error,
1793                                queue_wait,
1794                                transaction_acquire,
1795                            );
1796                            None
1797                        }
1798                    }
1799                };
1800                conn.finish(terminal_state)
1801            })();
1802            (outcome, blocking_sink_lease)
1803        })
1804        .await;
1805
1806        match outcome {
1807            Ok(((Some(returned_conn), None), _sink_lease)) => owner.0 = returned_conn,
1808            Ok(((_returned_conn, Some(request_state)), _sink_lease)) => {
1809                acquisition_counters.record_writer_task_request_failure();
1810                if request_state == WriterTaskRequestState::SideEffectsUnknown {
1811                    acquisition_counters.record_writer_task_side_effects_unknown();
1812                }
1813                tracing::error!(
1814                    request_state = %request_state,
1815                    "writer task reached a terminal request or connection state; closing and \
1816                     failing the queue without restarting"
1817                );
1818                crate::timeout_sink::emit_writer_task_retirement(
1819                    &db,
1820                    &format!("terminal request state: {request_state}"),
1821                );
1822                close_and_fail_queued_requests(&mut rx).await;
1823                return;
1824            }
1825            Ok(((None, None), _sink_lease)) => {
1826                unreachable!("a reusable writer returns its connection")
1827            }
1828            Err(join_err) => {
1829                acquisition_counters.record_writer_task_request_failure();
1830                tracing::error!(
1831                    error = %join_err,
1832                    "writer task blocking closure failed outside the request \
1833                     panic boundary; closing and failing the queue without restarting"
1834                );
1835                crate::timeout_sink::emit_writer_task_retirement(
1836                    &db,
1837                    &format!("blocking closure join failure: {join_err}"),
1838                );
1839                close_and_fail_queued_requests(&mut rx).await;
1840                return;
1841            }
1842        }
1843    }
1844}
1845
1846#[cfg(test)]
1847#[path = "writer_task_tests.rs"]
1848mod tests;
1849
1850#[cfg(test)]
1851#[path = "writer_task_lease_close_tests.rs"]
1852mod volume_lease_close_tests;
1853
1854#[cfg(test)]
1855#[path = "writer_task_slow_write_label_tests.rs"]
1856mod slow_write_label_tests;
1857
1858#[cfg(all(test, any(unix, windows)))]
1859#[path = "writer_task_identity_tests.rs"]
1860mod identity_tests;
1861
1862#[cfg(test)]
1863#[path = "writer_routing_outcome_tests.rs"]
1864mod writer_routing_outcome_tests;
1865
1866#[cfg(test)]
1867mod reply_evidence_tests {
1868    use super::*;
1869    use crate::test_hooks::TestHooks;
1870    use rusqlite::hooks::{AuthAction, AuthContext, Authorization, TransactionOperation};
1871
1872    #[tokio::test]
1873    async fn lost_delivery_retains_real_statement_and_commit_failures() {
1874        for fail_commit in [false, true] {
1875            let conn = crate::test_hooks::registered(Connection::open_in_memory().unwrap());
1876            conn.execute_batch("CREATE TABLE receipt_probe(id INTEGER PRIMARY KEY); INSERT INTO receipt_probe VALUES(1); BEGIN IMMEDIATE").unwrap();
1877            if fail_commit {
1878                conn.test_authorizer(Some(|context: AuthContext<'_>| match context.action {
1879                    AuthAction::Transaction {
1880                        operation: TransactionOperation::Unknown,
1881                    } => Authorization::Deny,
1882                    _ => Authorization::Allow,
1883                }))
1884                .unwrap();
1885            }
1886            let receipt = Arc::new(ReplyReceipt::default());
1887            let profiled = execute_wrapped_transaction_profiled(
1888                &conn,
1889                "receipt_commit",
1890                None,
1891                false,
1892                Some(&receipt.commit_issued),
1893                |conn| {
1894                    conn.execute(
1895                        "INSERT INTO receipt_probe VALUES(?1)",
1896                        [if fail_commit { 2 } else { 1 }],
1897                    )
1898                    .map_err(|error| {
1899                        StorageError::driver(
1900                            khive_storage::StorageCapability::Sql,
1901                            "receipt_statement",
1902                            error,
1903                        )
1904                    })
1905                },
1906                None,
1907            );
1908            assert!(
1909                conn.is_autocommit(),
1910                "both real failures must prove rollback before lost delivery"
1911            );
1912            assert_eq!(receipt.commit_issued.load(Ordering::Acquire), fail_commit);
1913            *receipt.completed() = Some(profiled.result);
1914            let (reply, reply_rx) = oneshot::channel();
1915            drop(reply);
1916            let error = PendingWrite { reply_rx, receipt }
1917                .wait()
1918                .await
1919                .expect_err("retained failure");
1920            let failure = crate::error::native_write_failure(
1921                &error,
1922                khive_storage::error::SqliteWriteStage::Statement,
1923            );
1924            let expected_code = if fail_commit {
1925                rusqlite::ffi::SQLITE_AUTH
1926            } else {
1927                rusqlite::ffi::SQLITE_CONSTRAINT
1928            };
1929            assert!(
1930                failure
1931                    .is_some_and(|failure| failure.primary_code == expected_code
1932                        && !failure.settlement_unknown),
1933                "lost delivery must retain the real native code and known rollback: {error:?}"
1934            );
1935            assert!(!error.is_write_outcome_unknown());
1936            let count: i64 = conn
1937                .query_row("SELECT count(*) FROM receipt_probe", [], |row| row.get(0))
1938                .unwrap();
1939            assert_eq!(count, 1, "real rollback preserves the original stored row");
1940        }
1941    }
1942}