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