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