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 handle = match cached {
533            Some(handle) => Some(handle.clone()),
534            None => match self.writer_task_handle() {
535                Ok(handle) => handle,
536                Err(error) if self.config.write_routing_strict => return Err(error),
537                Err(_) => None,
538            },
539        };
540
541        if handle.is_none() && self.config.write_routing_strict {
542            return Err(StorageError::Pool {
543                operation: operation.into(),
544                message: "strict write routing requires a writer-task handle; no handle is \
545                          available, so the direct writer fallback was refused"
546                    .into(),
547            });
548        }
549        Ok(handle)
550    }
551
552    /// Record one actual compatibility fallback around the writer task. A
553    /// file-backed pool with the queue enabled should never reach this seam
554    /// in strict mode because [`Self::writer_task_for_write`] refuses first.
555    pub(crate) fn record_direct_route(&self, site: crate::timeout_sink::Site) {
556        if self.write_queue_active() {
557            crate::timeout_sink::emit_direct_route_violation(
558                &crate::timeout_sink::db_label(self),
559                site,
560            );
561        }
562    }
563
564    /// Resolve a runtime-owned transaction through the same strict/compatibility
565    /// policy as store writes. `None` permits the caller's direct transaction and
566    /// records its compatibility fallback when the file-backed queue is enabled.
567    /// A strict refusal returns before any direct-writer acquisition or telemetry.
568    pub fn writer_task_for_runtime_write(
569        &self,
570        operation: RuntimeWriteOperation,
571    ) -> Result<Option<WriterTaskHandle>, StorageError> {
572        let handle = self.writer_task_for_write(None, operation.operation())?;
573        if handle.is_none() {
574            self.record_direct_route(operation.fallback_site());
575        }
576        Ok(handle)
577    }
578
579    /// Test-only: how many times the writer-task init closure actually ran.
580    /// Must be at most 1 for the pool's whole lifetime, regardless of how
581    /// many times [`Self::writer_task_handle`] is called or how many stores
582    /// are constructed over this pool.
583    #[cfg(test)]
584    pub(crate) fn writer_task_spawn_count(&self) -> usize {
585        self.writer_task_spawn_count
586            .load(std::sync::atomic::Ordering::SeqCst)
587    }
588
589    /// Record the writer task's `tokio::spawn` JoinHandle. Called exactly
590    /// once, by [`crate::writer_task::spawn`], immediately after spawning —
591    /// the same `writer_task` OnceLock init that makes spawn at-most-once
592    /// per pool makes this write at-most-once per pool.
593    ///
594    /// First-wins: if a handle was ever stored (including one a caller has
595    /// since taken — `writer_task_join_stored` remembers), the existing
596    /// state is kept and the new handle is dropped (dropping a `JoinHandle`
597    /// detaches its task without cancelling it). A second store violates the
598    /// at-most-once contract and trips the debug_assert in debug builds;
599    /// release builds keep the first handle rather than silently swapping
600    /// the drain owner out from under whichever caller already took it.
601    pub(crate) fn set_writer_task_join(&self, join: tokio::task::JoinHandle<()>) {
602        // `swap(true)` returns the prior value: `true` means a handle was
603        // stored at least once before, so this is a second store — even when
604        // the slot itself is empty because `take_writer_task_join` already
605        // ran (the slot alone cannot tell "never stored" from "taken").
606        let first_store = !self.writer_task_join_stored.swap(true, Ordering::SeqCst);
607        debug_assert!(
608            first_store,
609            "writer task JoinHandle stored twice (even counting a taken one); \
610             the writer_task OnceLock is supposed to make spawn at-most-once per pool"
611        );
612        if first_store {
613            *self.writer_task_join.lock() = Some(join);
614        }
615    }
616
617    /// Take the writer task's JoinHandle, if a writer task was spawned and
618    /// the handle has not already been taken.
619    ///
620    /// Intended for short-lived batch callers that drop every
621    /// [`WriterTaskHandle`] clone (closing the queue) and then need to await
622    /// the task's exit before treating the database file as settled: the
623    /// task's connection close fires SQLite's close-time WAL checkpoint, so
624    /// until the task exits the file bytes can still move after the caller's
625    /// last write returned.
626    ///
627    /// One-shot: `None` means either the write queue never spawned
628    /// (disabled, or spawn degraded) or another caller already took the
629    /// handle — in both cases there is nothing further to await here.
630    /// Exactly one subsystem may own the drain: the single caller that
631    /// receives `Some(_)` is the sole owner of the task-exit await (and of
632    /// the close-time WAL checkpoint that settles the database file); every
633    /// later caller receives `None` and must not arrange its own await.
634    pub fn take_writer_task_join(&self) -> Option<tokio::task::JoinHandle<()>> {
635        self.writer_task_join.lock().take()
636    }
637
638    pub(super) fn open_pooled_reader(&self) -> Result<Box<PooledReader>, SqliteError> {
639        let opened_at = Instant::now();
640        // Allocate once per physical reader; checkouts move the same box between
641        // the queue and lease without allocating on every borrow/return.
642        Ok(Box::new(PooledReader {
643            conn: crate::ProgressConn::new(self.open_reader_connection()?)?,
644            opened_at,
645            checkouts: 0,
646        }))
647    }
648
649    pub(super) fn open_reader_connection(&self) -> Result<Connection, SqliteError> {
650        let path = self.read_connection_path()?;
651        #[cfg(any(unix, windows))]
652        if let Some(identity_path) = self.identity_path.as_deref() {
653            self.verify_opened_file_identity(identity_path)?;
654        }
655        let conn = open_reader_connection(path, &self.config)?;
656        #[cfg(any(unix, windows))]
657        if let Some(identity_path) = self.identity_path.as_deref() {
658            self.verify_connection_file_identity(&conn, identity_path)?;
659        }
660        self.verify_opened_database_id(&conn)?;
661        #[cfg(any(test, feature = "test-support"))]
662        crate::statement_observer::install(&conn, &self.statement_observer)?;
663        Ok(conn)
664    }
665
666    fn read_connection_path(&self) -> Result<&Path, SqliteError> {
667        self.read_only_open_target
668            .as_deref()
669            .or(self.identity_path.as_deref())
670            .ok_or_else(|| {
671                SqliteError::InvalidData(
672                    "in-memory databases do not support standalone connections".to_string(),
673                )
674            })
675    }
676
677    /// Construct the complete admitted owner before the connection can leave
678    /// this module. The native opener below is private to these factories.
679    #[track_caller]
680    pub(super) fn standalone_write_unit(&self) -> Result<StandaloneWriteUnit, SqliteError> {
681        if self.config.read_only {
682            return Err(SqliteError::InvalidData(
683                "database is read-only: standalone write transactions are not permitted".into(),
684            ));
685        }
686        let volume_lease = self
687            .write_admission
688            .acquire(crate::disk_guard::LeaseClass::Standalone)?;
689        let conn = self.open_standalone_connection()?;
690        self.writer_acquisition_counters
691            .standalone_acquisitions
692            .fetch_add(1, Ordering::Relaxed);
693        let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
694        if !unit.conn().is_autocommit() {
695            return Err(SqliteError::WriterSettlementUnknown);
696        }
697        Ok(unit)
698    }
699
700    /// Retain a dedicated recovery connection without granting ordinary SQL.
701    /// This bypasses logical-write admission so a checkpoint can reclaim space.
702    pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
703        Ok(StandaloneCheckpoint::new(
704            self,
705            self.open_checkpoint_file()?,
706        ))
707    }
708
709    pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
710        self.open_standalone_connection().map(CheckpointFile::new)
711    }
712
713    pub(crate) fn spawn_writer_task(
714        &self,
715        capacity: usize,
716    ) -> Result<WriterTaskHandle, SqliteError> {
717        let conn = self.open_standalone_connection()?;
718        crate::writer_task::spawn_with_connection(self, conn, capacity)
719    }
720
721    pub(crate) fn open_sql_bridge_writer(
722        self: Arc<Self>,
723        slot: tokio::sync::OwnedSemaphorePermit,
724    ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
725        let conn = self
726            .open_standalone_connection()
727            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
728        self.writer_acquisition_counters
729            .standalone_acquisitions
730            .fetch_add(1, Ordering::Relaxed);
731        crate::sql_bridge::build_standalone_writer(self, conn, slot)
732    }
733
734    pub(crate) fn inspect_diagnostic_connection(
735        &self,
736        collect_size_composition: bool,
737    ) -> crate::diagnostics::PoolInspection {
738        crate::diagnostics::inspect_open_connection(
739            self,
740            self.open_standalone_connection(),
741            collect_size_composition,
742        )
743    }
744
745    pub(crate) fn inspect_diagnostic_connection_interruptibly(
746        &self,
747        scope: &crate::read_cancellation::InterruptibleReadScope,
748        collect_size_composition: bool,
749    ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
750        scope.ensure_active()?;
751        crate::diagnostics::inspect_open_connection_interruptibly(
752            self,
753            self.open_standalone_connection(),
754            scope,
755            collect_size_composition,
756        )
757    }
758
759    /// FTS merge INSERTs are logical writes, even when scheduled by the
760    /// checkpoint task. They use an admitted owner, never its recovery file.
761    pub(crate) fn run_fts_maintenance(
762        &self,
763        config: &crate::fts_maintenance::FtsMaintenanceConfig,
764        state: &mut crate::fts_maintenance::FtsMaintenanceState,
765        now: Instant,
766    ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
767        if !state.is_due(config, now) {
768            return Ok(None);
769        }
770        let unit = {
771            let _class =
772                crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Maintenance);
773            self.standalone_write_unit()
774        }
775        .map_err(|error| format!("FTS maintenance admission: {error}"))?;
776        crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
777            self.write_admission
778                .check()
779                .map_err(|error| format!("FTS maintenance admission: {error}"))
780        })
781    }
782
783    /// The sole raw standalone opener. Only the complete-consumer factories
784    /// above can call it; no raw connection is returned across that boundary.
785    fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
786        let path = self.identity_path.as_deref().ok_or_else(|| {
787            SqliteError::InvalidData(
788                "in-memory databases do not support standalone connections".to_string(),
789            )
790        })?;
791
792        if self.config.read_only {
793            return Err(SqliteError::InvalidData(
794                "database is read-only: standalone write connections are not permitted".to_string(),
795            ));
796        }
797
798        // The configured spelling may be a symlink that changed since this
799        // pool opened. Use its pinned target, and refuse replacement of that
800        // target before SQLite can execute the diagnostics PASSIVE checkpoint.
801        #[cfg(any(unix, windows))]
802        self.verify_opened_file_identity(path)?;
803
804        #[cfg(test)]
805        run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
806
807        let conn = claimed_file_identity::open_connection(
808            &self.config,
809            path,
810            OpenFlags::SQLITE_OPEN_READ_WRITE
811                | OpenFlags::SQLITE_OPEN_NO_MUTEX
812                | OpenFlags::SQLITE_OPEN_URI,
813            self.identity_path.as_deref(),
814        )?;
815        #[cfg(test)]
816        run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
817        #[cfg(any(unix, windows))]
818        self.verify_connection_file_identity(&conn, path)?;
819        self.verify_opened_database_id(&conn)?;
820        self.configure_standalone_connection(&conn)?;
821        Ok(conn)
822    }
823
824    /// Configure a caller-owned native connection. This does not open or
825    /// return a pool connection, and does not grant write admission.
826    pub(super) fn configure_standalone_connection(
827        &self,
828        conn: &Connection,
829    ) -> Result<(), SqliteError> {
830        #[cfg(feature = "namespace-trigram-proto")]
831        register_namespace_trigram(conn)?;
832        register_writer_clock(conn)?;
833        // Expression indexes over these keys are maintained by every writer
834        // (the write-queue task and per-store standalone writers included), so
835        // each of them needs the same functions the pooled writer registers.
836        register_read_functions(conn)?;
837        conn.busy_timeout(self.config.busy_timeout)?;
838        if self.config.code_map_vfs.is_none() {
839            self.checkpoint_ownership
840                .configure_wal_autocheckpoint(conn)?;
841        }
842        conn.pragma_update(None, "foreign_keys", "ON")?;
843        conn.pragma_update(None, "synchronous", "NORMAL")?;
844
845        let wal_enabled =
846            self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
847        if wal_enabled {
848            conn.pragma_update(
849                None,
850                "journal_size_limit",
851                self.config.journal_size_limit_bytes,
852            )?;
853        }
854
855        #[cfg(any(test, feature = "test-support"))]
856        crate::statement_observer::install(conn, &self.statement_observer)?;
857        Ok(())
858    }
859
860    #[cfg(any(unix, windows))]
861    pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
862        let Some(expected) = self.opened_file_identity else {
863            return Err(SqliteError::InvalidData(
864                "file-backed pool has no opened database file identity".to_string(),
865            ));
866        };
867        let current = database_file_identity(path).ok();
868        if current != Some(expected) {
869            return Err(SqliteError::InvalidData(
870                "pool database file identity changed since the first open; refusing standalone connection"
871                    .to_string(),
872            ));
873        }
874        Ok(())
875    }
876
877    #[cfg(any(unix, windows))]
878    pub(super) fn verify_connection_file_identity(
879        &self,
880        conn: &Connection,
881        path: &Path,
882    ) -> Result<(), SqliteError> {
883        let opened = opened_sqlite_file_identity(conn, path)?;
884        if self.opened_file_identity != Some(opened) {
885            return Err(SqliteError::InvalidData(
886                "pool database file identity changed since the first open; refusing standalone connection"
887                    .to_string(),
888            ));
889        }
890        Ok(())
891    }
892
893    fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
894        // A read-only pool, or a writable pool opened below the space reserve,
895        // may precede installation of the nonce by another process. Without a
896        // nonce to pin, use the existing file identity checks where available.
897        let Some(expected) = self.opened_database_id else {
898            return Ok(());
899        };
900        if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
901            return Err(SqliteError::InvalidData(
902                "pool database identity changed since the first open; refusing standalone connection"
903                    .to_string(),
904            ));
905        }
906        Ok(())
907    }
908
909    /// Effective `PRAGMA wal_autocheckpoint` for a writer-capable connection
910    /// opened right now: `0` once a dedicated checkpoint owner has claimed
911    /// the pool, the bounded fallback otherwise.
912    #[cfg(test)]
913    pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
914        self.checkpoint_ownership.wal_autocheckpoint_pages()
915    }
916
917    /// Whether a checkpoint owner is claiming or has claimed this pool.
918    /// A host without that owner's join must conservatively refuse teardown.
919    pub fn checkpoint_owner_present(&self) -> bool {
920        self.checkpoint_ownership.state.lock().phase
921            != super::admission::CheckpointOwnership::Unclaimed
922    }
923
924    /// Retain this pool's diagnostic sink completion witness before Drop.
925    /// Explicit close waits until all pools and writer tasks sharing the sink
926    /// have released their ownership; ordinary Drop never stops the sink.
927    pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
928        self.timeout_sink_registration
929            .as_ref()
930            .map(crate::timeout_sink::Registration::close_handle)
931    }
932
933    pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
934        self.timeout_sink_registration
935            .as_ref()
936            .map(crate::timeout_sink::Registration::writer_lease)
937    }
938
939    /// Claim routine WAL-checkpoint ownership for this pool.
940    ///
941    /// Called by the scheduled checkpoint task at startup — the one caller
942    /// that actually replaces SQLite's per-commit autocheckpoint with
943    /// dedicated PASSIVE checkpointing (ADR-091 Amendment 10). The claim
944    /// makes every subsequently opened writer-capable connection set
945    /// `PRAGMA wal_autocheckpoint = 0`, and re-applies that pragma on the
946    /// already-open pooled writer under the writer mutex. A writer task
947    /// spawned before the claim keeps its own long-lived connection;
948    /// [`Self::propagate_checkpoint_claim_to_writer_task`] reaches that one.
949    ///
950    /// Without a claim, writer-capable connections keep the bounded
951    /// `FALLBACK_WAL_AUTOCHECKPOINT_PAGES` threshold, so a writable pool
952    /// in a process that never runs the checkpoint task (embedded runtimes,
953    /// one-shot CLI executions) retains SQLite's own WAL reclamation instead
954    /// of growing its WAL without bound.
955    ///
956    /// Read-only pools record the claim but have no writer-capable
957    /// connections to reconfigure. Writable pools publish the claim only after
958    /// the pooled writer is configured successfully; a failed attempt keeps
959    /// the bounded fallback active and remains retryable.
960    pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
961        if !self.checkpoint_ownership.begin_claim() {
962            return Ok(());
963        }
964        let result = (|| {
965            if !self.config.read_only {
966                let writer = self.writer_for_checkpoint_operation()?;
967                writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
968            }
969            Ok(())
970        })();
971        self.checkpoint_ownership.finish_claim(result.is_ok());
972        result
973    }
974
975    /// Flip an already-running writer task's long-lived connection to the
976    /// claimed-owner setting.
977    ///
978    /// Connections opened after [`Self::claim_checkpoint_ownership`] inherit
979    /// `wal_autocheckpoint = 0` at open; only a writer task spawned before
980    /// the claim still holds a connection on the bounded fallback. Returns
981    /// `Ok(())` without side effects when the pool's write queue is
982    /// disabled.
983    pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
984        let Some(handle) = self.writer_task_handle()? else {
985            return Ok(());
986        };
987        handle
988            .send_top_level(|conn| {
989                conn.pragma_update(None, "wal_autocheckpoint", 0)
990                    .map_err(|e| StorageError::Pool {
991                        operation: "claim_checkpoint_ownership".into(),
992                        message: e.to_string(),
993                    })
994            })
995            .await
996    }
997
998    /// Open a standalone read-only connection for one enumerated structural
999    /// exception to pooled-reader routing.
1000    ///
1001    /// There is intentionally no public/generic standalone-reader fallback.
1002    /// Ordinary request reads use [`Self::reader`] and surface bounded pool
1003    /// exhaustion. Adding a purpose variant or call site is therefore a
1004    /// deliberate, scoped architecture change (ADR-165 Slice 2), not a
1005    /// routine extension.
1006    pub(crate) fn open_standalone_reader(
1007        &self,
1008        purpose: StandaloneReaderPurpose,
1009    ) -> Result<Connection, SqliteError> {
1010        let path = self.read_connection_path()?;
1011
1012        #[cfg(any(unix, windows))]
1013        if let Some(identity_path) = self.identity_path.as_deref() {
1014            self.verify_opened_file_identity(identity_path)?;
1015        }
1016
1017        let conn = claimed_file_identity::open_connection(
1018            &self.config,
1019            path,
1020            OpenFlags::SQLITE_OPEN_READ_ONLY
1021                | OpenFlags::SQLITE_OPEN_NO_MUTEX
1022                | OpenFlags::SQLITE_OPEN_URI,
1023            self.identity_path.as_deref(),
1024        )?;
1025        #[cfg(any(unix, windows))]
1026        if let Some(identity_path) = self.identity_path.as_deref() {
1027            self.verify_connection_file_identity(&conn, identity_path)?;
1028        }
1029        self.verify_opened_database_id(&conn)?;
1030        configure_reader_connection(&conn, &self.config)?;
1031        conn.pragma_update(None, "synchronous", "NORMAL")?;
1032        self.reader_acquisition_counters
1033            .record_standalone_open(purpose);
1034        #[cfg(any(test, feature = "test-support"))]
1035        crate::statement_observer::install(&conn, &self.statement_observer)?;
1036        Ok(conn)
1037    }
1038
1039    pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1040        if self.max_readers == 0 {
1041            return;
1042        }
1043
1044        if !conn.past_limit(&self.config, Instant::now())
1045            && reset_reader_connection(&conn.conn, dirty, &self.config)
1046            && reader_connection_is_healthy(&conn.conn)
1047        {
1048            self.enqueue_reader_slot(conn);
1049            return;
1050        }
1051
1052        close_connection_quietly(conn.conn.into_inner());
1053        self.replace_discarded_reader_slot();
1054    }
1055
1056    /// Push a connection back onto the physical reader queue, discarding it
1057    /// (rather than growing the queue past its configured capacity) if the
1058    /// queue is already full.
1059    fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1060        if let Err(conn) = self.readers.push(conn) {
1061            eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1062            close_connection_quietly(conn.conn.into_inner());
1063        }
1064    }
1065
1066    /// Open a fresh connection to refill one physical reader slot after its
1067    /// previous occupant was closed and discarded — either disqualified on
1068    /// an ordinary return ([`Self::return_reader`]) or abandoned by a
1069    /// non-reusable checkout ([`ReaderGuard`]'s `Drop`). Both call sites
1070    /// share this so a failed replacement is recorded and logged identically
1071    /// either way, instead of one path silently shrinking the pool.
1072    pub(super) fn replace_discarded_reader_slot(&self) {
1073        self.reader_acquisition_counters
1074            .reader_discards
1075            .fetch_add(1, Ordering::Relaxed);
1076        match self.open_pooled_reader() {
1077            Ok(conn) => self.enqueue_reader_slot(conn),
1078            Err(error) => {
1079                self.reader_acquisition_counters
1080                    .record_reader_replacement_open_failure();
1081                tracing::warn!(target: "khive_db::pool",
1082                    %error,
1083                    "sqlite-pool: reader replacement connection failed to open; the physical \
1084                     pool permanently shrinks by one slot below max_readers"
1085                );
1086            }
1087        }
1088    }
1089}
1090
1091#[cfg(test)]
1092mod checkpoint_presence_tests {
1093    use super::*;
1094
1095    #[test]
1096    fn checkpoint_owner_presence_is_conservative_during_claim() {
1097        let pool = ConnectionPool::new(PoolConfig {
1098            path: None,
1099            ..PoolConfig::default()
1100        })
1101        .unwrap();
1102        assert!(!pool.checkpoint_owner_present());
1103        assert!(pool.checkpoint_ownership.begin_claim());
1104        assert!(pool.checkpoint_owner_present());
1105        pool.checkpoint_ownership.finish_claim(false);
1106        assert!(!pool.checkpoint_owner_present());
1107        pool.claim_checkpoint_ownership().unwrap();
1108        assert!(pool.checkpoint_owner_present());
1109    }
1110}