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: 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.write_admission.acquire()?;
687        let conn = self.open_standalone_connection()?;
688        self.writer_acquisition_counters
689            .standalone_acquisitions
690            .fetch_add(1, Ordering::Relaxed);
691        let unit = StandaloneWriteUnit::new(conn, Arc::clone(&self.write_admission), volume_lease);
692        if !unit.conn().is_autocommit() {
693            return Err(SqliteError::WriterSettlementUnknown);
694        }
695        Ok(unit)
696    }
697
698    /// Retain a dedicated recovery connection without granting ordinary SQL.
699    /// This bypasses logical-write admission so a checkpoint can reclaim space.
700    pub fn open_standalone_checkpoint(&self) -> Result<StandaloneCheckpoint<'_>, SqliteError> {
701        Ok(StandaloneCheckpoint::new(
702            self,
703            self.open_checkpoint_file()?,
704        ))
705    }
706
707    pub(crate) fn open_checkpoint_file(&self) -> Result<CheckpointFile, SqliteError> {
708        self.open_standalone_connection().map(CheckpointFile::new)
709    }
710
711    pub(crate) fn spawn_writer_task(
712        &self,
713        capacity: usize,
714    ) -> Result<WriterTaskHandle, SqliteError> {
715        let conn = self.open_standalone_connection()?;
716        crate::writer_task::spawn_with_connection(self, conn, capacity)
717    }
718
719    pub(crate) fn open_sql_bridge_writer(
720        self: Arc<Self>,
721        slot: tokio::sync::OwnedSemaphorePermit,
722    ) -> Result<Box<dyn khive_storage::SqlWriter>, StorageError> {
723        let conn = self
724            .open_standalone_connection()
725            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
726        self.writer_acquisition_counters
727            .standalone_acquisitions
728            .fetch_add(1, Ordering::Relaxed);
729        crate::sql_bridge::build_standalone_writer(self, conn, slot)
730    }
731
732    pub(crate) fn inspect_diagnostic_connection(
733        &self,
734        collect_size_composition: bool,
735    ) -> crate::diagnostics::PoolInspection {
736        crate::diagnostics::inspect_open_connection(
737            self,
738            self.open_standalone_connection(),
739            collect_size_composition,
740        )
741    }
742
743    pub(crate) fn inspect_diagnostic_connection_interruptibly(
744        &self,
745        scope: &crate::read_cancellation::InterruptibleReadScope,
746        collect_size_composition: bool,
747    ) -> Result<crate::diagnostics::PoolInspection, StorageError> {
748        scope.ensure_active()?;
749        crate::diagnostics::inspect_open_connection_interruptibly(
750            self,
751            self.open_standalone_connection(),
752            scope,
753            collect_size_composition,
754        )
755    }
756
757    /// FTS merge INSERTs are logical writes, even when scheduled by the
758    /// checkpoint task. They use an admitted owner, never its recovery file.
759    pub(crate) fn run_fts_maintenance(
760        &self,
761        config: &crate::fts_maintenance::FtsMaintenanceConfig,
762        state: &mut crate::fts_maintenance::FtsMaintenanceState,
763        now: Instant,
764    ) -> Result<Option<crate::fts_maintenance::FtsMaintenanceStep>, String> {
765        if !state.is_due(config, now) {
766            return Ok(None);
767        }
768        let unit = self
769            .standalone_write_unit()
770            .map_err(|error| format!("FTS maintenance admission: {error}"))?;
771        crate::fts_maintenance::run_if_due_with_admission(unit.conn(), config, state, now, || {
772            self.write_admission
773                .check()
774                .map_err(|error| format!("FTS maintenance admission: {error}"))
775        })
776    }
777
778    /// The sole raw standalone opener. Only the complete-consumer factories
779    /// above can call it; no raw connection is returned across that boundary.
780    fn open_standalone_connection(&self) -> Result<Connection, SqliteError> {
781        let path = self.identity_path.as_deref().ok_or_else(|| {
782            SqliteError::InvalidData(
783                "in-memory databases do not support standalone connections".to_string(),
784            )
785        })?;
786
787        if self.config.read_only {
788            return Err(SqliteError::InvalidData(
789                "database is read-only: standalone write connections are not permitted".to_string(),
790            ));
791        }
792
793        // The configured spelling may be a symlink that changed since this
794        // pool opened. Use its pinned target, and refuse replacement of that
795        // target before SQLite can execute the diagnostics PASSIVE checkpoint.
796        #[cfg(any(unix, windows))]
797        self.verify_opened_file_identity(path)?;
798
799        #[cfg(test)]
800        run_identity_open_hook(path, IdentityOpenStage::BeforeStandaloneOpen, None);
801
802        let conn = claimed_file_identity::open_connection(
803            &self.config,
804            path,
805            OpenFlags::SQLITE_OPEN_READ_WRITE
806                | OpenFlags::SQLITE_OPEN_NO_MUTEX
807                | OpenFlags::SQLITE_OPEN_URI,
808            self.identity_path.as_deref(),
809        )?;
810        #[cfg(test)]
811        run_identity_open_hook(path, IdentityOpenStage::AfterStandaloneOpen, Some(&conn));
812        #[cfg(any(unix, windows))]
813        self.verify_connection_file_identity(&conn, path)?;
814        self.verify_opened_database_id(&conn)?;
815        self.configure_standalone_connection(&conn)?;
816        Ok(conn)
817    }
818
819    /// Configure a caller-owned native connection. This does not open or
820    /// return a pool connection, and does not grant write admission.
821    pub(super) fn configure_standalone_connection(
822        &self,
823        conn: &Connection,
824    ) -> Result<(), SqliteError> {
825        #[cfg(feature = "namespace-trigram-proto")]
826        register_namespace_trigram(conn)?;
827        register_writer_clock(conn)?;
828        // Expression indexes over these keys are maintained by every writer
829        // (the write-queue task and per-store standalone writers included), so
830        // each of them needs the same functions the pooled writer registers.
831        register_read_functions(conn)?;
832        conn.busy_timeout(self.config.busy_timeout)?;
833        if self.config.code_map_vfs.is_none() {
834            self.checkpoint_ownership
835                .configure_wal_autocheckpoint(conn)?;
836        }
837        conn.pragma_update(None, "foreign_keys", "ON")?;
838        conn.pragma_update(None, "synchronous", "NORMAL")?;
839
840        let wal_enabled =
841            self.config.wal_mode && current_journal_mode(conn)?.eq_ignore_ascii_case("wal");
842        if wal_enabled {
843            conn.pragma_update(
844                None,
845                "journal_size_limit",
846                self.config.journal_size_limit_bytes,
847            )?;
848        }
849
850        #[cfg(any(test, feature = "test-support"))]
851        crate::statement_observer::install(conn, &self.statement_observer)?;
852        Ok(())
853    }
854
855    #[cfg(any(unix, windows))]
856    pub(super) fn verify_opened_file_identity(&self, path: &Path) -> Result<(), SqliteError> {
857        let Some(expected) = self.opened_file_identity else {
858            return Err(SqliteError::InvalidData(
859                "file-backed pool has no opened database file identity".to_string(),
860            ));
861        };
862        let current = database_file_identity(path).ok();
863        if current != Some(expected) {
864            return Err(SqliteError::InvalidData(
865                "pool database file identity changed since the first open; refusing standalone connection"
866                    .to_string(),
867            ));
868        }
869        Ok(())
870    }
871
872    #[cfg(any(unix, windows))]
873    pub(super) fn verify_connection_file_identity(
874        &self,
875        conn: &Connection,
876        path: &Path,
877    ) -> Result<(), SqliteError> {
878        let opened = opened_sqlite_file_identity(conn, path)?;
879        if self.opened_file_identity != Some(opened) {
880            return Err(SqliteError::InvalidData(
881                "pool database file identity changed since the first open; refusing standalone connection"
882                    .to_string(),
883            ));
884        }
885        Ok(())
886    }
887
888    fn verify_opened_database_id(&self, conn: &Connection) -> Result<(), SqliteError> {
889        // A read-only pool, or a writable pool opened below the space reserve,
890        // may precede installation of the nonce by another process. Without a
891        // nonce to pin, use the existing file identity checks where available.
892        let Some(expected) = self.opened_database_id else {
893            return Ok(());
894        };
895        if self.identity_path.is_some() && read_database_id(conn)? != Some(expected) {
896            return Err(SqliteError::InvalidData(
897                "pool database identity changed since the first open; refusing standalone connection"
898                    .to_string(),
899            ));
900        }
901        Ok(())
902    }
903
904    /// Effective `PRAGMA wal_autocheckpoint` for a writer-capable connection
905    /// opened right now: `0` once a dedicated checkpoint owner has claimed
906    /// the pool, the bounded fallback otherwise.
907    #[cfg(test)]
908    pub(crate) fn effective_wal_autocheckpoint_pages(&self) -> u32 {
909        self.checkpoint_ownership.wal_autocheckpoint_pages()
910    }
911
912    /// Whether a checkpoint owner is claiming or has claimed this pool.
913    /// A host without that owner's join must conservatively refuse teardown.
914    pub fn checkpoint_owner_present(&self) -> bool {
915        self.checkpoint_ownership.state.lock().phase
916            != super::admission::CheckpointOwnership::Unclaimed
917    }
918
919    /// Retain this pool's diagnostic sink completion witness before Drop.
920    /// Explicit close waits until all pools and writer tasks sharing the sink
921    /// have released their ownership; ordinary Drop never stops the sink.
922    pub fn timeout_sink_close_handle(&self) -> Option<super::TimeoutSinkCloseHandle> {
923        self.timeout_sink_registration
924            .as_ref()
925            .map(crate::timeout_sink::Registration::close_handle)
926    }
927
928    pub(crate) fn timeout_sink_writer_lease(&self) -> Option<crate::timeout_sink::WriterLease> {
929        self.timeout_sink_registration
930            .as_ref()
931            .map(crate::timeout_sink::Registration::writer_lease)
932    }
933
934    /// Claim routine WAL-checkpoint ownership for this pool.
935    ///
936    /// Called by the scheduled checkpoint task at startup — the one caller
937    /// that actually replaces SQLite's per-commit autocheckpoint with
938    /// dedicated PASSIVE checkpointing (ADR-091 Amendment 10). The claim
939    /// makes every subsequently opened writer-capable connection set
940    /// `PRAGMA wal_autocheckpoint = 0`, and re-applies that pragma on the
941    /// already-open pooled writer under the writer mutex. A writer task
942    /// spawned before the claim keeps its own long-lived connection;
943    /// [`Self::propagate_checkpoint_claim_to_writer_task`] reaches that one.
944    ///
945    /// Without a claim, writer-capable connections keep the bounded
946    /// `FALLBACK_WAL_AUTOCHECKPOINT_PAGES` threshold, so a writable pool
947    /// in a process that never runs the checkpoint task (embedded runtimes,
948    /// one-shot CLI executions) retains SQLite's own WAL reclamation instead
949    /// of growing its WAL without bound.
950    ///
951    /// Read-only pools record the claim but have no writer-capable
952    /// connections to reconfigure. Writable pools publish the claim only after
953    /// the pooled writer is configured successfully; a failed attempt keeps
954    /// the bounded fallback active and remains retryable.
955    pub fn claim_checkpoint_ownership(&self) -> Result<(), SqliteError> {
956        if !self.checkpoint_ownership.begin_claim() {
957            return Ok(());
958        }
959        let result = (|| {
960            if !self.config.read_only {
961                let writer = self.writer_for_checkpoint_operation()?;
962                writer.conn().pragma_update(None, "wal_autocheckpoint", 0)?;
963            }
964            Ok(())
965        })();
966        self.checkpoint_ownership.finish_claim(result.is_ok());
967        result
968    }
969
970    /// Flip an already-running writer task's long-lived connection to the
971    /// claimed-owner setting.
972    ///
973    /// Connections opened after [`Self::claim_checkpoint_ownership`] inherit
974    /// `wal_autocheckpoint = 0` at open; only a writer task spawned before
975    /// the claim still holds a connection on the bounded fallback. Returns
976    /// `Ok(())` without side effects when the pool's write queue is
977    /// disabled.
978    pub async fn propagate_checkpoint_claim_to_writer_task(&self) -> Result<(), StorageError> {
979        let Some(handle) = self.writer_task_handle()? else {
980            return Ok(());
981        };
982        handle
983            .send_top_level(|conn| {
984                conn.pragma_update(None, "wal_autocheckpoint", 0)
985                    .map_err(|e| StorageError::Pool {
986                        operation: "claim_checkpoint_ownership".into(),
987                        message: e.to_string(),
988                    })
989            })
990            .await
991    }
992
993    /// Open a standalone read-only connection for one enumerated structural
994    /// exception to pooled-reader routing.
995    ///
996    /// There is intentionally no public/generic standalone-reader fallback.
997    /// Ordinary request reads use [`Self::reader`] and surface bounded pool
998    /// exhaustion. Adding a purpose variant or call site is therefore a
999    /// deliberate, scoped architecture change (ADR-165 Slice 2), not a
1000    /// routine extension.
1001    pub(crate) fn open_standalone_reader(
1002        &self,
1003        purpose: StandaloneReaderPurpose,
1004    ) -> Result<Connection, SqliteError> {
1005        let path = self.read_connection_path()?;
1006
1007        #[cfg(any(unix, windows))]
1008        if let Some(identity_path) = self.identity_path.as_deref() {
1009            self.verify_opened_file_identity(identity_path)?;
1010        }
1011
1012        let conn = claimed_file_identity::open_connection(
1013            &self.config,
1014            path,
1015            OpenFlags::SQLITE_OPEN_READ_ONLY
1016                | OpenFlags::SQLITE_OPEN_NO_MUTEX
1017                | OpenFlags::SQLITE_OPEN_URI,
1018            self.identity_path.as_deref(),
1019        )?;
1020        #[cfg(any(unix, windows))]
1021        if let Some(identity_path) = self.identity_path.as_deref() {
1022            self.verify_connection_file_identity(&conn, identity_path)?;
1023        }
1024        self.verify_opened_database_id(&conn)?;
1025        configure_reader_connection(&conn, &self.config)?;
1026        conn.pragma_update(None, "synchronous", "NORMAL")?;
1027        self.reader_acquisition_counters
1028            .record_standalone_open(purpose);
1029        #[cfg(any(test, feature = "test-support"))]
1030        crate::statement_observer::install(&conn, &self.statement_observer)?;
1031        Ok(conn)
1032    }
1033
1034    pub(super) fn return_reader(&self, conn: Box<PooledReader>, dirty: bool) {
1035        if self.max_readers == 0 {
1036            return;
1037        }
1038
1039        if !conn.past_limit(&self.config, Instant::now())
1040            && reset_reader_connection(&conn.conn, dirty, &self.config)
1041            && reader_connection_is_healthy(&conn.conn)
1042        {
1043            self.enqueue_reader_slot(conn);
1044            return;
1045        }
1046
1047        close_connection_quietly(conn.conn);
1048        self.replace_discarded_reader_slot();
1049    }
1050
1051    /// Push a connection back onto the physical reader queue, discarding it
1052    /// (rather than growing the queue past its configured capacity) if the
1053    /// queue is already full.
1054    fn enqueue_reader_slot(&self, conn: Box<PooledReader>) {
1055        if let Err(conn) = self.readers.push(conn) {
1056            eprintln!("[sqlite-pool] reader pool queue full, discarding replacement connection");
1057            close_connection_quietly(conn.conn);
1058        }
1059    }
1060
1061    /// Open a fresh connection to refill one physical reader slot after its
1062    /// previous occupant was closed and discarded — either disqualified on
1063    /// an ordinary return ([`Self::return_reader`]) or abandoned by a
1064    /// non-reusable checkout ([`ReaderGuard`]'s `Drop`). Both call sites
1065    /// share this so a failed replacement is recorded and logged identically
1066    /// either way, instead of one path silently shrinking the pool.
1067    pub(super) fn replace_discarded_reader_slot(&self) {
1068        self.reader_acquisition_counters
1069            .reader_discards
1070            .fetch_add(1, Ordering::Relaxed);
1071        match self.open_pooled_reader() {
1072            Ok(conn) => self.enqueue_reader_slot(conn),
1073            Err(error) => {
1074                self.reader_acquisition_counters
1075                    .record_reader_replacement_open_failure();
1076                tracing::warn!(target: "khive_db::pool",
1077                    %error,
1078                    "sqlite-pool: reader replacement connection failed to open; the physical \
1079                     pool permanently shrinks by one slot below max_readers"
1080                );
1081            }
1082        }
1083    }
1084}
1085
1086#[cfg(test)]
1087mod checkpoint_presence_tests {
1088    use super::*;
1089
1090    #[test]
1091    fn checkpoint_owner_presence_is_conservative_during_claim() {
1092        let pool = ConnectionPool::new(PoolConfig {
1093            path: None,
1094            ..PoolConfig::default()
1095        })
1096        .unwrap();
1097        assert!(!pool.checkpoint_owner_present());
1098        assert!(pool.checkpoint_ownership.begin_claim());
1099        assert!(pool.checkpoint_owner_present());
1100        pool.checkpoint_ownership.finish_claim(false);
1101        assert!(!pool.checkpoint_owner_present());
1102        pool.claim_checkpoint_ownership().unwrap();
1103        assert!(pool.checkpoint_owner_present());
1104    }
1105}