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;