Skip to main content

khive_db/pool/
pool_impl.rs

1//! Pool diagnostics, writer-task lifecycle and connection maintenance.
2
3use std::path::Path;
4use std::sync::atomic::Ordering;
5use std::sync::Arc;
6use std::time::{Duration, Instant};
7
8use khive_storage::error::StorageError;
9use khive_storage::tx_registry::TxOrigin;
10use khive_storage::StorageCapability;
11use rusqlite::{Connection, OpenFlags};
12use tokio::sync::Semaphore;
13
14use crate::database_owner_identity::{DatabaseOwnerIdentity, DatabaseOwnerIdentityError};
15use crate::disk_guard_config::EffectiveDiskGuardConfig;
16#[cfg(test)]
17use crate::disk_guard_config::{DiskGuardConfigSource, DEFAULT_DISK_GUARD_DEADLINE_MS};
18use crate::error::SqliteError;
19#[cfg(any(unix, windows))]
20use crate::file_identity::{database_file_identity, DatabaseFileIdentity};
21use crate::writer_task::WriterTaskHandle;
22
23#[cfg(any(unix, windows))]
24use super::opened_sqlite_file_identity;
25#[cfg(doc)]
26use super::pool_exhausted_error;
27#[cfg(feature = "namespace-trigram-proto")]
28use super::register_namespace_trigram;
29use super::{
30    claimed_file_identity, close_connection_quietly, configure_reader_connection,
31    current_journal_mode, open_reader_connection, read_database_id, reader_connection_is_healthy,
32    register_read_functions, register_writer_clock, reset_reader_connection, CheckpointFile,
33    ConnectionPool, PoolConfig, PoolIdentityRegistration, PooledReader, ReaderAcquisitionSnapshot,
34    ReaderGuard, RuntimeWriteOperation, SearchMechanismSnapshot, StandaloneCheckpoint,
35    StandaloneReaderPurpose, StandaloneWriteUnit, WriteAdmission, WriterAcquisitionCounters,
36    WriterAcquisitionSnapshot, NEXT_MAIN_POOL_GENERATION,
37};
38#[cfg(test)]
39use super::{run_identity_open_hook, IdentityOpenStage};
40
41impl ConnectionPool {
42    /// Snapshot all instrumented writer acquisition outcomes since this pool
43    /// was constructed.
44    pub fn writer_acquisition_snapshot(&self) -> WriterAcquisitionSnapshot {
45        self.writer_acquisition_counters
46            .snapshot(self.write_admission.lease_timeouts())
47    }
48
49    /// Count a coordinator call only after served-kind filtering selects this
50    /// backend. The canonical requested kind is the granular kind when one was
51    /// supplied, or the entity/note substrate otherwise.
52    pub fn record_search_dispatch(&self, backend_id: &str, requested_kind: &str) {
53        let mut dispatches = self.search_dispatches.lock();
54        let count = dispatches
55            .entry(backend_id.to_owned())
56            .or_default()
57            .entry(requested_kind.to_owned())
58            .or_default();
59        *count = count.saturating_add(1);
60    }
61
62    /// Count one actual candidate note row returned at the post-fusion
63    /// hydration seam, including rows later filtered as deleted. Absent rows
64    /// and later result metadata are excluded.
65    pub fn record_note_candidate_hydration_row(&self) {
66        let _ = self.note_candidate_hydration_rows.fetch_update(
67            Ordering::Relaxed,
68            Ordering::Relaxed,
69            |current| Some(current.saturating_add(1)),
70        );
71    }
72
73    /// Snapshot ADR-166 G4/G5 counters. Values reset only with this pool.
74    pub fn search_mechanism_snapshot(&self) -> SearchMechanismSnapshot {
75        SearchMechanismSnapshot {
76            dispatches_by_backend_and_kind: self.search_dispatches.lock().clone(),
77            note_candidate_hydration_rows: self
78                .note_candidate_hydration_rows
79                .load(Ordering::Relaxed),
80        }
81    }
82
83    /// Snapshot reader acquisition, saturation, and hold lifecycle outcomes
84    /// since this pool was constructed. Counters reset only with pool
85    /// reconstruction.
86    pub fn reader_acquisition_snapshot(&self) -> ReaderAcquisitionSnapshot {
87        self.reader_acquisition_counters.snapshot(
88            self.max_readers.max(1),
89            self.sql_bridge_reader_slots.available_permits(),
90        )
91    }
92
93    /// Record one pool-wide reader-admission wait that exhausted the configured
94    /// checkout timeout outside [`Self::reader_until`] (currently the explicit
95    /// raw-SQL read-transaction exception and reads on a standalone writer).
96    pub(crate) fn record_reader_admission_timeout(&self) {
97        self.reader_acquisition_counters.record_checkout_timeout();
98    }
99
100    /// Count a query error from an already checked-out pooled reader when it is
101    /// SQLite's `SQLITE_BUSY` surfacing after the busy handler gave up. Every
102    /// other error, including `SQLITE_LOCKED`, is ignored. Checkout exhaustion
103    /// is counted by [`Self::reader_until`] before any query runs, so the two
104    /// classes cannot overlap.
105    pub(crate) fn record_reader_query_error(&self, error: &StorageError) {
106        if crate::read_cancellation::storage_error_sqlite_code(error)
107            == Some(rusqlite::ErrorCode::DatabaseBusy)
108        {
109            self.reader_acquisition_counters.record_busy_timeout();
110        }
111    }
112
113    /// Clone the pool-scoped counter set for the lifetime-owned writer task.
114    pub(crate) fn writer_acquisition_counters(&self) -> Arc<WriterAcquisitionCounters> {
115        Arc::clone(&self.writer_acquisition_counters)
116    }
117
118    pub(crate) fn write_admission(&self) -> Arc<WriteAdmission> {
119        Arc::clone(&self.write_admission)
120    }
121
122    pub fn effective_disk_guard_config(&self) -> Option<EffectiveDiskGuardConfig> {
123        self.disk_guard_config
124    }
125
126    #[cfg(test)]
127    pub(crate) fn set_test_write_admission(
128        &mut self,
129        floor_bytes: u64,
130        probe: impl Fn(&Path) -> std::io::Result<u64> + Send + Sync + 'static,
131    ) {
132        let database_path = if self.config.read_only {
133            None
134        } else {
135            self.canonical_path().map(Path::to_path_buf)
136        };
137        let admission = Arc::new(
138            WriteAdmission::new(
139                database_path,
140                floor_bytes,
141                DEFAULT_DISK_GUARD_DEADLINE_MS,
142                self.config.volume_lock_dir.clone(),
143            )
144            .expect("test admission volume identity"),
145        );
146        admission.set_test_space_probe(probe);
147        self.write_admission = admission;
148        if self.canonical_path().is_some() && !self.config.read_only {
149            self.disk_guard_config = Some(EffectiveDiskGuardConfig {
150                reserve_bytes: floor_bytes,
151                guard_deadline_ms: DEFAULT_DISK_GUARD_DEADLINE_MS,
152                reserve_source: DiskGuardConfigSource::Backend,
153                deadline_source: DiskGuardConfigSource::Default,
154                legacy_environment_present: false,
155            });
156        }
157    }
158
159    /// Get the current number of available reader connections.
160    pub fn available_readers(&self) -> usize {
161        self.readers.len()
162    }
163
164    /// Get the total number of reader connections in the pool.
165    pub fn max_readers(&self) -> usize {
166        self.max_readers
167    }
168
169    /// Age of the oldest outstanding pooled reader checkout, including
170    /// degraded shared-reader leases and their reset/replacement work.
171    /// Returns `None` when no checkout remains; standalone readers are
172    /// separately tracked by the transaction registry.
173    pub fn oldest_checkout_age(&self) -> Option<Duration> {
174        self.oldest_checkout_age_at(Instant::now())
175    }
176
177    pub(crate) fn oldest_checkout_age_at(&self, now: Instant) -> Option<Duration> {
178        self.reader_checkouts
179            .lock()
180            .first_key_value()
181            .map(|(started, _)| now.saturating_duration_since(*started))
182    }
183
184    pub(super) fn begin_reader_checkout(&self) -> Instant {
185        let started = Instant::now();
186        // Instant resolution can give simultaneous leases the same key.
187        *self.reader_checkouts.lock().entry(started).or_default() += 1;
188        started
189    }
190
191    pub(super) fn finish_reader_checkout(&self, started: Instant) {
192        let mut checkouts = self.reader_checkouts.lock();
193        if let Some(count) = checkouts.get_mut(&started) {
194            *count -= 1;
195            if *count == 0 {
196                checkouts.remove(&started);
197            }
198        }
199    }
200
201    /// Return the pool configuration.
202    pub fn config(&self) -> &PoolConfig {
203        &self.config
204    }
205
206    /// Observe actual SQLite statement starts on this private test pool.
207    ///
208    /// The limit bounds retained SQL records. Failed steps count as attempts;
209    /// preparation alone does not count. The guard observes every pool-owned
210    /// connection, including the queued writer. Do not run unrelated background
211    /// work on the fixture pool; see the guard documentation for limitations.
212    /// Connection setup runs before observation begins on each connection and
213    /// is never recorded, including for opens during an active observation.
214    /// Reader connection opens use the existing reader acquisition counters instead.
215    #[cfg(any(test, feature = "test-support"))]
216    pub fn observe_test_statement_starts(
217        &self,
218        limit: usize,
219    ) -> Result<crate::statement_observer::StatementStartObservation, SqliteError> {
220        self.statement_observer.observe(limit)
221    }
222
223    /// Identify this pool's counter window when it is designated as main.
224    /// Repeated runtime handles and diagnostics reads reuse the same generation;
225    /// constructing secondary pools does not consume main-pool generations.
226    pub fn main_pool_generation(&self) -> u64 {
227        *self.main_pool_generation.get_or_init(|| {
228            NEXT_MAIN_POOL_GENERATION
229                .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |next| {
230                    next.checked_add(1)
231                })
232                .expect("main pool generation exhausted")
233        })
234    }
235
236    /// The typed admission failure for a pooled reader checkout that
237    /// exhausted `checkout_timeout`: no reader was acquired, so the
238    /// operation never started and a retry cannot duplicate a side effect.
239    pub(crate) fn reader_admission_timeout(&self, operation: &'static str) -> StorageError {
240        StorageError::AdmissionTimeout {
241            operation: operation.into(),
242            timeout_ms: u64::try_from(self.config.checkout_timeout.as_millis()).unwrap_or(u64::MAX),
243            pool_identity: Some(
244                self.identity_registration
245                    .as_ref()
246                    .map(PoolIdentityRegistration::label)
247                    .unwrap_or_else(|| ":memory:".to_string()),
248            ),
249        }
250    }
251
252    /// Resolve a [`Self::reader_until`] outcome into a checked-out guard or
253    /// the canonical refusal. This is the single home of the checkout
254    /// tri-state; call sites must not re-derive any arm of it:
255    ///
256    /// - `Ok(Some)` — a reader was checked out.
257    /// - `Ok(None)` — `should_stop()` fired: the request was cancelled or hit
258    ///   its deadline before checkout. NOT an admission wait, so it maps to
259    ///   the non-retryable [`StorageError::Timeout`] — emitting the retryable
260    ///   `AdmissionTimeout` here would invite an immediate retry of a request
261    ///   its caller already abandoned, into a possibly saturated pool.
262    /// - `Err` carrying the pool's own `SQLITE_BUSY` — `reader_until` executes
263    ///   no SQL, so the only `SQLITE_BUSY` it can produce is
264    ///   [`pool_exhausted_error`], raised when `checkout_timeout` elapses with
265    ///   no reader available. A genuine admission wait that ended before any
266    ///   work began maps to the retryable [`StorageError::AdmissionTimeout`].
267    /// - any other `Err` (e.g. [`Self::ensure_pooled_writer_active`] returning
268    ///   `InvalidData` for a retired pooled writer) — an opaque driver failure
269    ///   under the caller's capability, non-retryable.
270    pub(crate) fn resolve_reader_checkout<'p>(
271        &self,
272        capability: StorageCapability,
273        operation: &'static str,
274        outcome: Result<Option<ReaderGuard<'p>>, SqliteError>,
275    ) -> Result<ReaderGuard<'p>, StorageError> {
276        match outcome {
277            Ok(Some(mut guard)) => {
278                guard.label_operation(operation);
279                Ok(guard)
280            }
281            Ok(None) => Err(self.reader_checkout_refusal(capability, operation, None)),
282            Err(error) => Err(self.reader_checkout_refusal(capability, operation, Some(error))),
283        }
284    }
285
286    /// The refusal for a reader checkout that produced nothing, shared by
287    /// [`Self::resolve_reader_checkout`] and [`Self::acquire_reader_admission`]
288    /// so the arms documented on the former have one home. `None` is the
289    /// stopped-request arm; `Some` carries the failed checkout's error.
290    pub(super) fn reader_checkout_refusal(
291        &self,
292        capability: StorageCapability,
293        operation: &'static str,
294        error: Option<SqliteError>,
295    ) -> StorageError {
296        let Some(error) = error else {
297            return StorageError::Timeout {
298                operation: operation.into(),
299            };
300        };
301        let is_pool_exhausted = matches!(
302            &error,
303            SqliteError::Rusqlite(rusqlite::Error::SqliteFailure(code, _))
304                if code.code == rusqlite::ErrorCode::DatabaseBusy
305        );
306        if is_pool_exhausted {
307            self.reader_admission_timeout(operation)
308        } else {
309            StorageError::driver(capability, operation, error)
310        }
311    }
312
313    /// Pool-wide admission permits shared by pooled readers, the explicit
314    /// raw-SQL read-transaction exception, and reads on standalone writers.
315    pub(crate) fn sql_bridge_reader_slots(&self) -> Arc<Semaphore> {
316        Arc::clone(&self.sql_bridge_reader_slots)
317    }
318
319    /// Pool-wide permit for a file-backed raw-SQL writer handle.
320    pub(crate) fn sql_bridge_writer_slots(&self) -> Arc<Semaphore> {
321        Arc::clone(&self.sql_bridge_writer_slots)
322    }
323
324    /// Current writer holds that prevent voluntary daemon retirement.
325    ///
326    /// The raw-SQL writer permit remains handle-scoped even in autocommit.
327    /// This read acquires no connection and changes no admission policy.
328    pub fn retirement_writer_holds(&self) -> usize {
329        usize::from(self.writer.is_locked())
330            + usize::from(self.sql_bridge_writer_slots.available_permits() == 0)
331    }
332
333    /// This pool's ADR-091 backend-scoped attribution origin (ADR-091,
334    /// backend-scoped WAL-pin attribution design note): `Database(_)` for a
335    /// file-backed pool, `Memory` for an in-memory pool. Every
336    /// `tx_registry::register_scoped` call site threaded in this crate
337    /// passes this value as the span's origin.
338    pub fn origin(&self) -> TxOrigin {
339        self.origin.clone()
340    }
341
342    /// The canonical path this pool's `origin()` identity was minted from,
343    /// `None` for an in-memory pool. `DbIdentity` has no path accessor by
344    /// design; sidecar derivation and other filesystem consumers use this —
345    /// the same canonical value the identity was minted from — instead of
346    /// re-deriving a path from the raw configured one.
347    pub fn canonical_path(&self) -> Option<&Path> {
348        self.identity_path.as_deref()
349    }
350
351    /// Unix file identity retained for callers using the original tuple API.
352    #[cfg(unix)]
353    pub fn opened_file_identity(&self) -> Option<(u64, u64)> {
354        self.opened_file_identity
355            .map(DatabaseFileIdentity::unix_parts)
356    }
357
358    /// Physical file identity pinned to SQLite's opened main file. Construction
359    /// compares it with the path on both sides of the open before admission.
360    #[cfg(any(unix, windows))]
361    pub fn opened_file_identity_record(&self) -> Option<DatabaseFileIdentity> {
362        self.opened_file_identity
363    }
364
365    /// Ownership evidence captured through the database SQLite opened.
366    /// This does not select the topology's main backend or establish a root binding.
367    /// Legacy read-only and low-space opens without a stored UUID must reopen
368    /// after installation; this accessor never installs or re-mints an identity.
369    pub fn database_owner_identity(
370        &self,
371    ) -> Result<DatabaseOwnerIdentity, DatabaseOwnerIdentityError> {
372        if self.identity_path.is_none() {
373            return Err(DatabaseOwnerIdentityError::InMemory);
374        }
375        #[cfg(any(unix, windows))]
376        {
377            let durable_id = self
378                .opened_database_id
379                .ok_or(DatabaseOwnerIdentityError::DurableIdentityUnavailable)?;
380            let file_identity = self
381                .opened_file_identity
382                .ok_or(DatabaseOwnerIdentityError::PhysicalIdentityUnavailable)?;
383            Ok(DatabaseOwnerIdentity {
384                durable_id,
385                file_identity,
386            })
387        }
388        #[cfg(not(any(unix, windows)))]
389        {
390            Err(DatabaseOwnerIdentityError::UnsupportedPlatform)
391        }
392    }
393
394    /// Require both this opened database's UUID and physical file to match.
395    pub fn verify_database_owner(
396        &self,
397        expected: &DatabaseOwnerIdentity,
398    ) -> Result<(), DatabaseOwnerIdentityError> {
399        self.database_owner_identity()?.verify_owner(expected)
400    }
401
402    /// Whether the write queue is effectively enabled for this pool: the
403    /// resolved `write_queue_enabled` flag AND file-backed.
404    ///
405    /// `ConnectionPool::new` resolves the "no preference" (`None`) preference
406    /// to a concrete `Some(..)` once `path` is known, so every reader of
407    /// `config.write_queue_enabled` sees a resolved value; the `debug_assert`
408    /// pins that invariant and a `None` that slipped past would read as
409    /// disabled. Bypassing `ConnectionPool::new` to construct a pool is a
410    /// construction-path bug. Use this instead of repeating
411    /// `config().write_queue_enabled.unwrap_or(false) && config().path.is_some()`
412    /// at every routing/violation site.
413    pub fn write_queue_active(&self) -> bool {
414        debug_assert!(
415            self.config.write_queue_enabled.is_some(),
416            "write_queue_enabled must be resolved to Some(..) by ConnectionPool::new \
417             before any write_queue_active read"
418        );
419        self.config.write_queue_enabled.unwrap_or(false) && self.config.path.is_some()
420    }
421
422    /// Whether a writer-task JoinHandle has been stored at least once.
423    ///
424    /// Unlike [`Self::take_writer_task_join`], this remains true after the
425    /// one-shot handle slot is emptied, distinguishing a task that never
426    /// spawned from a handle another caller already consumed.
427    pub fn writer_task_join_was_stored(&self) -> bool {
428        self.writer_task_join_stored.load(Ordering::SeqCst)
429    }
430
431    /// Return the pool-wide ADR-067 Component A writer task, spawning it
432    /// lazily on first access if `PoolConfig::write_queue_enabled` is set.
433    /// Exactly one writer task exists per `ConnectionPool` (per DB file); see
434    /// crates/khive-db/docs/api/pool.md#connectionpoolwriter_task_handle--single-writer-task-rationale
435    /// for why a per-store writer task would defeat the single-writer
436    /// guarantee.
437    ///
438    /// Returns `Ok(None)` if the flag is off, or if the writer task failed to
439    /// spawn for a reason other than a missing runtime (for example, an
440    /// in-memory pool has no standalone-connection support) — callers fall
441    /// back to the legacy pool-mutex write path in either case. A spawn
442    /// failure is logged once here (at first access), not once per store.
443    ///
444    /// Returns `Err(StorageError::WriterTaskNoRuntime)` instead of panicking
445    /// when `write_queue_enabled` is set but this is the first access and no
446    /// Tokio runtime is available on the calling thread (checked via
447    /// [`tokio::runtime::Handle::try_current`]) — spawning the writer task
448    /// requires `tokio::spawn`, which panics outside a runtime. Callers that
449    /// already treat a missing writer task as best-effort (construction-time
450    /// degrade to the legacy path, matching slice 1's documented policy) can
451    /// collapse this into `None` with `.ok().flatten()`; callers that need to
452    /// fail loud on a genuine misconfiguration (write queue requested but no
453    /// runtime to run it on) can propagate the `Err` directly.
454    pub fn writer_task_handle(&self) -> Result<Option<WriterTaskHandle>, StorageError> {
455        // Same pinned invariant `write_queue_active` asserts, kept inline
456        // here because this gate keys on the flag ALONE: an explicit
457        // `Some(true)` on an in-memory pool must still attempt the spawn
458        // and degrade (documented + tested in
459        // `explicit_true_stays_on_for_memory_backed_pool`), so the
460        // file-backed half of `write_queue_active` cannot gate this early
461        // return.
462        debug_assert!(
463            self.config.write_queue_enabled.is_some(),
464            "write_queue_enabled must be resolved to Some(..) by ConnectionPool::new \
465             before any writer_task_handle read"
466        );
467        if !self.config.write_queue_enabled.unwrap_or(false) {
468            return Ok(None);
469        }
470        // Fast path: already resolved (spawned, degraded, or off) by an
471        // earlier call — no need to re-check the runtime.
472        if let Some(existing) = self.writer_task.get() {
473            return Ok(existing.clone());
474        }
475        // Not yet initialized and the flag is on: spawning requires
476        // `tokio::spawn`, which panics outside a runtime context. Check
477        // first and fail loud with a typed error instead.
478        if tokio::runtime::Handle::try_current().is_err() {
479            return Err(StorageError::WriterTaskNoRuntime);
480        }
481        Ok(self
482            .writer_task
483            .get_or_init(|| {
484                #[cfg(test)]
485                self.writer_task_spawn_count
486                    .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
487
488                match crate::writer_task::spawn(self, self.config.write_queue_capacity) {
489                    Ok(handle) => Some(handle),
490                    Err(e) => {
491                        tracing::warn!(target: "khive_db::pool",
492                            error = %e,
493                            "KHIVE_WRITE_QUEUE=1 but the writer task failed to spawn; \
494                             writes fall back to the pool-mutex path"
495                        );
496                        None
497                    }
498                }
499            })
500            .clone())
501    }
502
503    pub(crate) fn writer_admission_snapshot(
504        &self,
505    ) -> Result<crate::writer_admission_metrics::Snapshot, &'static str> {
506        if !self.config.write_queue_enabled.unwrap_or(false) {
507            return Err("writer_queue_disabled");
508        }
509        match self.writer_task.get() {
510            None => Err("writer_not_initialized"),
511            Some(None) => Err("writer_unavailable"),
512            Some(Some(handle)) => handle
513                .admission_snapshot()
514                .map_err(|reason| reason.reason()),
515        }
516    }
517
518    /// Resolve the writer task for a store write at the moment the write is
519    /// issued, rather than trusting only a handle cached by a synchronous
520    /// store constructor. Construction can legitimately run before Tokio is
521    /// entered, in which case `writer_task_handle()` returns
522    /// `WriterTaskNoRuntime` without caching a terminal `None`.
523    ///
524    /// Strict routing makes every missing handle fail closed here. The
525    /// caller remains responsible for recording a non-strict direct fallback
526    /// at the exact fallback seam with [`Self::record_direct_route`].
527    pub(crate) fn writer_task_for_write(
528        &self,
529        cached: Option<&WriterTaskHandle>,
530        operation: &'static str,
531    ) -> Result<Option<WriterTaskHandle>, StorageError> {
532        let unavailable = |source| StorageError::WriterOwnerUnavailable {
533            operation: operation.into(),
534            source: Box::new(source),
535        };
536        let handle = match cached {
537            Some(handle) => Some(handle.clone()),
538            None => match self.writer_task_handle() {
539                Ok(handle) => handle,
540                Err(error) if self.config.write_routing_strict => return Err(unavailable(error)),
541                Err(_) => None,
542            },
543        };
544        if self.config.write_routing_strict
545            && handle.as_ref().is_none_or(WriterTaskHandle::is_closed)
546        {
547            return Err(unavailable(StorageError::Pool {
548                operation: operation.into(),
549                message: "strict write routing requires a live writer owner".into(),
550            }));
551        }
552        Ok(handle)
553    }
554
555    /// Record one actual compatibility fallback around the writer task. A
556    /// file-backed pool with the queue enabled should never reach this seam
557    /// in strict mode because [`Self::writer_task_for_write`] refuses first.
558    pub(crate) fn record_direct_route(&self, site: crate::timeout_sink::Site) {
559        if self.write_queue_active() {
560            crate::timeout_sink::emit_direct_route_violation(
561                &crate::timeout_sink::db_label(self),
562                site,
563            );
564        }
565    }
566
567    /// Resolve a runtime-owned transaction through the same strict/compatibility
568    /// policy as store writes. `None` permits the caller's direct transaction and
569    /// records its compatibility fallback when the file-backed queue is enabled.
570    /// A strict refusal returns before any direct-writer acquisition or telemetry.
571    pub fn writer_task_for_runtime_write(
572        &self,
573        operation: RuntimeWriteOperation,
574    ) -> Result<Option<WriterTaskHandle>, StorageError> {
575        let handle = self.writer_task_for_write(None, operation.operation())?;
576        if handle.is_none() {
577            self.record_direct_route(operation.fallback_site());
578        }
579        Ok(handle)
580    }
581
582    /// Test-only: how many times the writer-task init closure actually ran.
583    /// Must be at most 1 for the pool's whole lifetime, regardless of how
584    /// many times [`Self::writer_task_handle`] is called or how many stores
585    /// are constructed over this pool.
586    #[cfg(test)]
587    pub(crate) fn writer_task_spawn_count(&self) -> usize {
588        self.writer_task_spawn_count
589            .load(std::sync::atomic::Ordering::SeqCst)
590    }
591
592    /// Record the writer task's `tokio::spawn` JoinHandle. Called exactly
593    /// once, by [`crate::writer_task::spawn`], immediately after spawning —
594    /// the same `writer_task` OnceLock init that makes spawn at-most-once
595    /// per pool makes this write at-most-once per pool.
596    ///
597    /// First-wins: if a handle was ever stored (including one a caller has
598    /// since taken — `writer_task_join_stored` remembers), the existing
599    /// state is kept and the new handle is dropped (dropping a `JoinHandle`
600    /// detaches its task without cancelling it). A second store violates the
601    /// at-most-once contract and trips the debug_assert in debug builds;
602    /// release builds keep the first handle rather than silently swapping
603    /// the drain owner out from under whichever caller already took it.
604    pub(crate) fn set_writer_task_join(&self, join: tokio::task::JoinHandle<()>) {
605        // `swap(true)` returns the prior value: `true` means a handle was
606        // stored at least once before, so this is a second store — even when
607        // the slot itself is empty because `take_writer_task_join` already
608        // ran (the slot alone cannot tell "never stored" from "taken").
609        let first_store = !self.writer_task_join_stored.swap(true, Ordering::SeqCst);
610        debug_assert!(
611            first_store,
612            "writer task JoinHandle stored twice (even counting a taken one); \
613             the writer_task OnceLock is supposed to make spawn at-most-once per pool"
614        );
615        if first_store {
616            *self.writer_task_join.lock() = Some(join);
617        }
618    }
619
620    /// Take the writer task's JoinHandle, if a writer task was spawned and
621    /// the handle has not already been taken.
622    ///
623    /// Intended for short-lived batch callers that drop every
624    /// [`WriterTaskHandle`] clone (closing the queue) and then need to await
625    /// the task's exit before treating the database file as settled: the
626    /// task's connection close fires SQLite's close-time WAL checkpoint, so
627    /// until the task exits the file bytes can still move after the caller's
628    /// last write returned.
629    ///
630    /// One-shot: `None` means either the write queue never spawned
631    /// (disabled, or spawn degraded) or another caller already took the
632    /// handle — in both cases there is nothing further to await here.
633    /// Exactly one subsystem may own the drain: the single caller that
634    /// receives `Some(_)` is the sole owner of the task-exit await (and of
635    /// the close-time WAL checkpoint that settles the database file); every
636    /// later caller receives `None` and must not arrange its own await.
637    pub fn take_writer_task_join(&self) -> Option<tokio::task::JoinHandle<()>> {
638        self.writer_task_join.lock().take()
639    }
640
641    pub(super) fn open_pooled_reader(&self) -> Result<Box<PooledReader>, SqliteError> {
642        let opened_at = Instant::now();
643        // Allocate once per physical reader; checkouts move the same box between
644        // the queue and lease without allocating on every borrow/return.
645        Ok(Box::new(PooledReader {
646            conn: crate::ProgressConn::new(self.open_reader_connection()?)?,
647            opened_at,
648            checkouts: 0,
649        }))
650    }
651
652    pub(super) fn open_reader_connection(&self) -> Result<Connection, SqliteError> {
653        let path = self.read_connection_path()?;
654        #[cfg(any(unix, windows))]
655        if let Some(identity_path) = self.identity_path.as_deref() {
656            self.verify_opened_file_identity(identity_path)?;
657        }
658        let conn = open_reader_connection(path, &self.config)?;
659        #[cfg(any(unix, windows))]
660        if let Some(identity_path) = self.identity_path.as_deref() {
661            self.verify_connection_file_identity(&conn, identity_path)?;
662        }
663        self.verify_opened_database_id(&conn)?;
664        #[cfg(any(test, feature = "test-support"))]
665        crate::statement_observer::install(&conn, &self.statement_observer)?;
666        Ok(conn)
667    }
668
669    fn read_connection_path(&self) -> Result<&Path, SqliteError> {
670        self.read_only_open_target
671            .as_deref()
672            .or(self.identity_path.as_deref())
673            .ok_or_else(|| {
674                SqliteError::InvalidData(
675                    "in-memory databases do not support standalone connections".to_string(),
676                )
677            })
678    }
679
680    /// Construct the complete admitted owner before the connection can leave
681    /// this module. The native opener below is private to these factories.
682    #[track_caller]
683    pub(super) fn standalone_write_unit(&self) -> Result<StandaloneWriteUnit, SqliteError> {
684        self.ensure_request_write_route("standalone_write")?;
685        if self.config.read_only {
686            return Err(SqliteError::InvalidData(
687                "database is read-only: standalone write transactions are not permitted".into(),
688            ));
689        }
690        let volume_lease = self
691            .write_admission
692            .acquire(crate::disk_guard::LeaseClass::Standalone)?;
693        let conn = self.open_standalone_connection()?;
694        self.writer_acquisition_counters
695            .standalone_acquisitions
696            .fetch_add(1, Ordering::Relaxed);
697        let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
698        if !unit.conn().is_autocommit() {
699            return Err(SqliteError::WriterSettlementUnknown);
700        }
701        Ok(unit)
702    }
703
704    /// Retain a dedicated recovery connection without granting ordinary SQL.
705    /// This bypasses logical-write admission so a checkpoint can reclaim space.
706    pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
707        Ok(StandaloneCheckpoint::new(
708            self,
709            self.open_checkpoint_file()?,
710        ))
711    }
712
713    pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
714        self.open_standalone_connection().map(CheckpointFile::new)
715    }
716
717    pub(crate) fn spawn_writer_task(
718        &self,
719        capacity: usize,
720    ) -> Result<WriterTaskHandle, SqliteError> {
721        let conn = self.open_standalone_connection()?;
722        crate::writer_task::spawn_with_connection(self, conn, capacity)
723    }
724
725    pub(crate) fn open_sql_bridge_writer(
726        self: Arc<Self>,
727        slot: tokio::sync::OwnedSemaphorePermit,
728    ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
729        self.ensure_request_write_route("sql_bridge_writer")
730            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
731        let conn = self
732            .open_standalone_connection()
733            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
734        self.writer_acquisition_counters
735            .standalone_acquisitions
736            .fetch_add(1, Ordering::Relaxed);
737        crate::sql_bridge::build_standalone_writer(self, conn, slot)
738    }
739
740    pub(crate) fn inspect_diagnostic_connection(
741        &self,
742        collect_size_composition: bool,
743    ) -> crate::diagnostics::PoolInspection {
744        crate::diagnostics::inspect_open_connection(
745            self,
746            self.open_standalone_connection(),
747            collect_size_composition,
748        )
749    }
750
751    pub(crate) fn inspect_diagnostic_connection_interruptibly(
752        &self,
753        scope: &crate::read_cancellation::InterruptibleReadScope,
754        collect_size_composition: bool,
755    ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
756        scope.ensure_active()?;
757        crate::diagnostics::inspect_open_connection_interruptibly(
758            self,
759            self.open_standalone_connection(),
760            scope,
761            collect_size_composition,
762        )
763    }
764
765    /// FTS merge INSERTs are logical writes, even when scheduled by the
766    /// checkpoint task. They use an admitted owner, never its recovery file.
767    pub(crate) fn run_fts_maintenance(
768        &self,
769        config: &crate::fts_maintenance::FtsMaintenanceConfig,
770        state: &mut crate::fts_maintenance::FtsMaintenanceState,
771        now: Instant,
772    ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
773        if !state.is_due(config, now) {
774            return Ok(None);
775        }
776        let unit = {
777            let _class =
778                crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Maintenance);
779            self.standalone_write_unit()
780        }
781        .map_err(|error| format!("FTS maintenance admission: {error}"))?;
782        crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
783            self.write_admission
784                .check()
785                .map_err(|error| format!("FTS maintenance admission: {error}"))
786        })
787    }
788
789    /// The sole raw standalone opener. Only the complete-consumer factories
790    /// above can call it; no raw connection is returned across that boundary.
791    fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
792        let path = self.identity_path.as_deref().ok_or_else(|| {
793            SqliteError::InvalidData(
794                "in-memory databases do not support standalone connections".to_string(),
795            )
796        })?;
797
798        if self.config.read_only {
799            return Err(SqliteError::InvalidData(
800                "database is read-only: standalone write connections are not permitted".to_string(),
801            ));
802        }
803
804        // The configured spelling may be a symlink that changed since this
805        // pool opened. Use its pinned target, and refuse replacement of that
806        // target before SQLite can execute the diagnostics PASSIVE checkpoint.
807        #[cfg(any(unix, windows))]
808        self.verify_opened_file_identity(path)?;
809
810        #[cfg(test)]
811        run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
812
813        let conn = claimed_file_identity::open_connection(
814            &self.config,
815            path,
816            OpenFlags::SQLITE_OPEN_READ_WRITE
817                | OpenFlags::SQLITE_OPEN_NO_MUTEX
818                | OpenFlags::SQLITE_OPEN_URI,
819            self.identity_path.as_deref(),
820        )?;
821        #[cfg(test)]
822        run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
823        #[cfg(any(unix, windows))]
824        self.verify_connection_file_identity(&conn, path)?;
825        self.verify_opened_database_id(&conn)?;
826        self.configure_standalone_connection(&conn)?;
827        Ok(conn)
828    }
829
830    /// Configure a caller-owned native connection. This does not open or
831    /// return a pool connection, and does not grant write admission.
832    pub(super) fn configure_standalone_connection(
833        &self,
834        conn: &Connection,
835    ) -> Result<(), SqliteError> {
836        #[cfg(feature = "namespace-trigram-proto")]
837        register_namespace_trigram(conn)?;
838        register_writer_clock(conn)?;
839        // Expression indexes over these keys are maintained by every writer
840        // (the write-queue task and per-store standalone writers included), so
841        // each of them needs the same functions the pooled writer registers.
842        register_read_functions(conn)?;
843        conn.busy_timeout(self.config.busy_timeout)?;
844        if self.config.code_map_vfs.is_none() {
845            self.checkpoint_ownership
846                .configure_wal_autocheckpoint(conn)?;
847        }
848        conn.pragma_update(None, "foreign_keys", "ON")?;
849        conn.pragma_update(None, "synchronous", "NORMAL")?;
850
851        let wal_enabled =
852            self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
853        if wal_enabled {
854            conn.pragma_update(
855                None,
856                "journal_size_limit",
857                self.config.journal_size_limit_bytes,
858            )?;
859        }
860
861        #[cfg(any(test, feature = "test-support"))]
862        crate::statement_observer::install(conn, &self.statement_observer)?;
863        Ok(())
864    }
865
866    #[cfg(any(unix, windows))]
867    pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
868        let Some(expected) = self.opened_file_identity else {
869            return Err(SqliteError::InvalidData(
870                "file-backed pool has no opened database file identity".to_string(),
871            ));
872        };
873        let current = database_file_identity(path).ok();
874        if current != Some(expected) {
875            return Err(SqliteError::InvalidData(
876                "pool database file identity changed since the first open; refusing standalone connection"
877                    .to_string(),
878            ));
879        }
880        Ok(())
881    }
882
883    #[cfg(any(unix, windows))]
884    pub(super) fn verify_connection_file_identity(
885        &self,
886        conn: &Connection,
887        path: &Path,
888    ) -> Result<(), SqliteError> {
889        let opened = opened_sqlite_file_identity(conn, path)?;
890        if self.opened_file_identity != Some(opened) {
891            return Err(SqliteError::InvalidData(
892                "pool database file identity changed since the first open; refusing standalone connection"
893                    .to_string(),
894            ));
895        }
896        Ok(())
897    }
898
899    fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
900        // A read-only pool, or a writable pool opened below the space reserve,
901        // may precede installation of the nonce by another process. Without a
902        // nonce to pin, use the existing file identity checks where available.
903        let Some(expected) = self.opened_database_id else {
904            return Ok(());
905        };
906        if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
907            return Err(SqliteError::InvalidData(
908                "pool database identity changed since the first open; refusing standalone connection"
909                    .to_string(),
910            ));
911        }
912        Ok(())
913    }
914
915    /// Effective `PRAGMA wal_autocheckpoint` for a writer-capable connection
916    /// opened right now: `0` once a dedicated checkpoint owner has claimed
917    /// the pool, the bounded fallback otherwise.
918    #[cfg(test)]
919    pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
920        self.checkpoint_ownership.wal_autocheckpoint_pages()
921    }
922
923    /// Whether a checkpoint owner is claiming or has claimed this pool.
924    /// A host without that owner's join must conservatively refuse teardown.
925    pub fn checkpoint_owner_present(&self) -> bool {
926        self.checkpoint_ownership.state.lock().phase
927            != super::admission::CheckpointOwnership::Unclaimed
928    }
929
930    /// Retain this pool's diagnostic sink completion witness before Drop.
931    /// Explicit close waits until all pools and writer tasks sharing the sink
932    /// have released their ownership; ordinary Drop never stops the sink.
933    pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
934        self.timeout_sink_registration
935            .as_ref()
936            .map(crate::timeout_sink::Registration::close_handle)
937    }
938
939    pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
940        self.timeout_sink_registration
941            .as_ref()
942            .map(crate::timeout_sink::Registration::writer_lease)
943    }
944
945    /// Claim routine WAL-checkpoint ownership for this pool.
946    ///
947    /// Called by the scheduled checkpoint task at startup — the one caller
948    /// that actually replaces SQLite's per-commit autocheckpoint with
949    /// dedicated PASSIVE checkpointing (ADR-091 Amendment 10). The claim
950    /// makes every subsequently opened writer-capable connection set
951    /// `PRAGMA wal_autocheckpoint = 0`, and re-applies that pragma on the
952    /// already-open pooled writer under the writer mutex. A writer task
953    /// spawned before the claim keeps its own long-lived connection;
954    /// [`Self::propagate_checkpoint_claim_to_writer_task`] reaches that one.
955    ///
956    /// Without a claim, writer-capable connections keep the bounded
957    /// `FALLBACK_WAL_AUTOCHECKPOINT_PAGES` threshold, so a writable pool
958    /// in a process that never runs the checkpoint task (embedded runtimes,
959    /// one-shot CLI executions) retains SQLite's own WAL reclamation instead
960    /// of growing its WAL without bound.
961    ///
962    /// Read-only pools record the claim but have no writer-capable
963    /// connections to reconfigure. Writable pools publish the claim only after
964    /// the pooled writer is configured successfully; a failed attempt keeps
965    /// the bounded fallback active and remains retryable.
966    pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
967        if !self.checkpoint_ownership.begin_claim() {
968            return Ok(());
969        }
970        let result = (|| {
971            if !self.config.read_only {
972                let writer = self.writer_for_checkpoint_operation()?;
973                writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
974            }
975            Ok(())
976        })();
977        self.checkpoint_ownership.finish_claim(result.is_ok());
978        result
979    }
980
981    /// Flip an already-running writer task's long-lived connection to the
982    /// claimed-owner setting.
983    ///
984    /// Connections opened after [`Self::claim_checkpoint_ownership`] inherit
985    /// `wal_autocheckpoint = 0` at open; only a writer task spawned before
986    /// the claim still holds a connection on the bounded fallback. Returns
987    /// `Ok(())` without side effects when the pool's write queue is
988    /// disabled.
989    pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
990        let Some(handle) = self.writer_task_handle()? else {
991            return Ok(());
992        };
993        handle
994            .send_top_level(|conn| {
995                conn.pragma_update(None, "wal_autocheckpoint", 0)
996                    .map_err(|e| StorageError::Pool {
997                        operation: "claim_checkpoint_ownership".into(),
998                        message: e.to_string(),
999                    })
1000            })
1001            .await
1002    }
1003
1004    /// Open a standalone read-only connection for one enumerated structural
1005    /// exception to pooled-reader routing.
1006    ///
1007    /// There is intentionally no public/generic standalone-reader fallback.
1008    /// Ordinary request reads use [`Self::reader`] and surface bounded pool
1009    /// exhaustion. Adding a purpose variant or call site is therefore a
1010    /// deliberate, scoped architecture change (ADR-165 Slice 2), not a
1011    /// routine extension.
1012    pub(crate) fn open_standalone_reader(
1013        &self,
1014        purpose: StandaloneReaderPurpose,
1015    ) -> Result<Connection, SqliteError> {
1016        let path = self.read_connection_path()?;
1017
1018        #[cfg(any(unix, windows))]
1019        if let Some(identity_path) = self.identity_path.as_deref() {
1020            self.verify_opened_file_identity(identity_path)?;
1021        }
1022
1023        let conn = claimed_file_identity::open_connection(
1024            &self.config,
1025            path,
1026            OpenFlags::SQLITE_OPEN_READ_ONLY
1027                | OpenFlags::SQLITE_OPEN_NO_MUTEX
1028                | OpenFlags::SQLITE_OPEN_URI,
1029            self.identity_path.as_deref(),
1030        )?;
1031        #[cfg(any(unix, windows))]
1032        if let Some(identity_path) = self.identity_path.as_deref() {
1033            self.verify_connection_file_identity(&conn, identity_path)?;
1034        }
1035        self.verify_opened_database_id(&conn)?;
1036        configure_reader_connection(&conn, &self.config)?;
1037        conn.pragma_update(None, "synchronous", "NORMAL")?;
1038        self.reader_acquisition_counters
1039            .record_standalone_open(purpose);
1040        #[cfg(any(test, feature = "test-support"))]
1041        crate::statement_observer::install(&conn, &self.statement_observer)?;
1042        Ok(conn)
1043    }
1044
1045    pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1046        if self.max_readers == 0 {
1047            return;
1048        }
1049
1050        if !conn.past_limit(&self.config, Instant::now())
1051            && reset_reader_connection(&conn.conn, dirty, &self.config)
1052            && reader_connection_is_healthy(&conn.conn)
1053        {
1054            self.enqueue_reader_slot(conn);
1055            return;
1056        }
1057
1058        close_connection_quietly(conn.conn.into_inner());
1059        self.replace_discarded_reader_slot();
1060    }
1061
1062    /// Push a connection back onto the physical reader queue, discarding it
1063    /// (rather than growing the queue past its configured capacity) if the
1064    /// queue is already full.
1065    fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1066        if let Err(conn) = self.readers.push(conn) {
1067            eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1068            close_connection_quietly(conn.conn.into_inner());
1069        }
1070    }
1071
1072    /// Open a fresh connection to refill one physical reader slot after its
1073    /// previous occupant was closed and discarded — either disqualified on
1074    /// an ordinary return ([`Self::return_reader`]) or abandoned by a
1075    /// non-reusable checkout ([`ReaderGuard`]'s `Drop`). Both call sites
1076    /// share this so a failed replacement is recorded and logged identically
1077    /// either way, instead of one path silently shrinking the pool.
1078    pub(super) fn replace_discarded_reader_slot(&self) {
1079        self.reader_acquisition_counters
1080            .reader_discards
1081            .fetch_add(1, Ordering::Relaxed);
1082        match self.open_pooled_reader() {
1083            Ok(conn) => self.enqueue_reader_slot(conn),
1084            Err(error) => {
1085                self.reader_acquisition_counters
1086                    .record_reader_replacement_open_failure();
1087                tracing::warn!(target: "khive_db::pool",
1088                    %error,
1089                    "sqlite-pool: reader replacement connection failed to open; the physical \
1090                     pool permanently shrinks by one slot below max_readers"
1091                );
1092            }
1093        }
1094    }
1095}
1096
1097#[cfg(test)]
1098mod checkpoint_presence_tests {
1099    use super::*;
1100
1101    #[test]
1102    fn checkpoint_owner_presence_is_conservative_during_claim() {
1103        let pool = ConnectionPool::new(PoolConfig {
1104            path: None,
1105            ..PoolConfig::default()
1106        })
1107        .unwrap();
1108        assert!(!pool.checkpoint_owner_present());
1109        assert!(pool.checkpoint_ownership.begin_claim());
1110        assert!(pool.checkpoint_owner_present());
1111        pool.checkpoint_ownership.finish_claim(false);
1112        assert!(!pool.checkpoint_owner_present());
1113        pool.claim_checkpoint_ownership().unwrap();
1114        assert!(pool.checkpoint_owner_present());
1115    }
1116}