Skip to main content

khive_db/pool/
write_units.rs

1use super::*;
2
3#[cfg(test)]
4pub(super) type SpaceProbe = dyn Fn(&Path) -> std::io::Result<u64> + Send + Sync;
5
6#[cfg(test)]
7thread_local! {
8    pub(super) static STARTUP_SPACE_PROBE: std::cell::RefCell<Option<(u64, Arc<SpaceProbe>)>> =
9        const { std::cell::RefCell::new(None) };
10}
11
12/// The SQLite write reserve is sampled at each operation admission. SQLite
13/// does not expose the size of an arbitrary upcoming transaction, so the
14/// reserve is a warning boundary, not a guarantee that a single very large
15/// transaction cannot consume more than the remaining headroom.
16pub(crate) struct WriteAdmission {
17    database_path: Option<PathBuf>,
18    volume: Option<PathBuf>,
19    expected_volume: Option<VolumeIdentity>,
20    volume_lock_dir: Option<PathBuf>,
21    floor_bytes: u64,
22    guard_deadline: Duration,
23    /// Set once a retired connection could neither roll back nor close: the
24    /// outcome of its transaction is unknown, so every later write is refused.
25    settlement_unknown: AtomicBool,
26    /// Lease waits that ran out `guard_deadline` because another writer held
27    /// the volume. Read through [`WriterAcquisitionSnapshot::lease_timeouts`].
28    lease_timeouts: AtomicU64,
29    #[cfg(test)]
30    space_probe: Mutex<Option<Arc<SpaceProbe>>>,
31    #[cfg(test)]
32    current_volume_override: Mutex<Option<VolumeIdentity>>,
33}
34
35impl WriteAdmission {
36    pub(crate) fn new(
37        database_path: Option<PathBuf>,
38        floor_bytes: u64,
39        guard_deadline_ms: u64,
40        volume_lock_dir: Option<PathBuf>,
41    ) -> Result<Self, SqliteError> {
42        let volume = database_path.clone();
43        let expected_volume = volume.as_deref().map(VolumeIdentity::resolve).transpose()?;
44        #[cfg(test)]
45        let (floor_bytes, space_probe) = STARTUP_SPACE_PROBE.with(|probe| {
46            probe
47                .borrow()
48                .as_ref()
49                .map(|(floor, probe)| (*floor, Some(Arc::clone(probe))))
50                .unwrap_or((floor_bytes, None))
51        });
52        Ok(Self {
53            database_path,
54            volume,
55            expected_volume,
56            volume_lock_dir,
57            floor_bytes,
58            guard_deadline: Duration::from_millis(guard_deadline_ms),
59            settlement_unknown: AtomicBool::new(false),
60            lease_timeouts: AtomicU64::new(0),
61            #[cfg(test)]
62            space_probe: Mutex::new(space_probe),
63            #[cfg(test)]
64            current_volume_override: Mutex::new(None),
65        })
66    }
67
68    /// Build admission for a raw connection with no backend-local override.
69    /// Pooled callers must use their pool's effective policy instead.
70    pub(crate) fn for_canonical_path(database_path: Option<PathBuf>) -> Result<Self, SqliteError> {
71        if database_path.is_none() {
72            return Self::new(None, 0, DEFAULT_DISK_GUARD_DEADLINE_MS, None);
73        }
74        let policy = crate::migrations::MigrationWritePolicy::from_environment()?;
75        Self::for_migration_policy(database_path, &policy)
76    }
77
78    pub(crate) fn for_migration_policy(
79        database_path: Option<PathBuf>,
80        policy: &crate::migrations::MigrationWritePolicy,
81    ) -> Result<Self, SqliteError> {
82        let effective = policy.disk_guard_config();
83        if effective.legacy_environment_present {
84            tracing::warn!(
85                "legacy SQLite reserve setting is deprecated; use KHIVE_SQLITE_DISK_RESERVE_BYTES"
86            );
87        }
88        if effective.reserve_bytes == 0 {
89            tracing::warn!("SQLite disk reserve is zero; logical writes have no floor refusal");
90        }
91        Self::new(
92            database_path,
93            effective.reserve_bytes,
94            effective.guard_deadline_ms,
95            Some(policy.volume_lock_dir().to_path_buf()),
96        )
97    }
98
99    pub(super) fn verify_current_volume(&self) -> Result<(), SqliteError> {
100        let (Some(path), Some(expected)) = (self.volume.as_deref(), self.expected_volume.as_ref())
101        else {
102            return Ok(());
103        };
104        #[cfg(test)]
105        let current = self.current_volume_override.lock().clone();
106        #[cfg(not(test))]
107        let current: Option<VolumeIdentity> = None;
108        let unchanged = match current {
109            Some(identity) => &identity == expected,
110            None => expected.still_identifies(path)?,
111        };
112        if !unchanged {
113            return Err(SqliteError::CapacityUnavailable {
114                phase: CapacityUnavailablePhase::Identity,
115                message: "database volume changed after admission identity was captured"
116                    .to_string(),
117            });
118        }
119        Ok(())
120    }
121
122    /// Settle a retired connection while the caller still holds its lease. A
123    /// terminal failure returns the typed outcome-unknown error for this write
124    /// and poisons this admission, so every later write on the pool, the
125    /// writer task and standalone writers is refused before it starts; the
126    /// caller may then release its lease.
127    pub(crate) fn close_retired_connection(&self, conn: Connection) -> Result<(), SqliteError> {
128        let database_path = self
129            .database_path
130            .as_ref()
131            .map(|path| path.display().to_string())
132            .unwrap_or_else(|| ":memory:".to_string());
133        let volume_key = self
134            .expected_volume
135            .as_ref()
136            .map(VolumeIdentity::diagnostic_key)
137            .unwrap_or_else(|| "in-memory".to_string());
138        let settled = crate::connection_settlement::close_retired_connection(
139            conn,
140            &database_path,
141            &volume_key,
142        );
143        if settled.is_err() {
144            self.settlement_unknown.store(true, Ordering::Release);
145        }
146        settled
147    }
148
149    pub(crate) fn ensure_settled(&self) -> Result<(), SqliteError> {
150        if self.settlement_unknown.load(Ordering::Acquire) {
151            return Err(SqliteError::WriterPoisoned);
152        }
153        Ok(())
154    }
155
156    pub(crate) fn volume_identity(&self) -> Result<Option<VolumeIdentity>, SqliteError> {
157        self.verify_current_volume()?;
158        Ok(self.expected_volume.clone())
159    }
160
161    fn available_space(&self, volume: &Path) -> std::io::Result<u64> {
162        #[cfg(test)]
163        if let Some(probe) = self.space_probe.lock().as_ref() {
164            return probe(volume);
165        }
166        fs4::available_space(volume)
167    }
168
169    pub(crate) fn check(&self) -> Result<(), SqliteError> {
170        self.check_with_headroom(0)
171    }
172
173    pub(crate) fn check_with_headroom(
174        &self,
175        required_headroom_bytes: u64,
176    ) -> Result<(), SqliteError> {
177        let Some(volume) = self.volume.as_deref() else {
178            return Ok(());
179        };
180        self.verify_current_volume()?;
181        let identity =
182            self.expected_volume
183                .as_ref()
184                .ok_or_else(|| SqliteError::CapacityUnavailable {
185                    phase: CapacityUnavailablePhase::Identity,
186                    message: "file-backed admission has no captured volume identity".to_string(),
187                })?;
188        let available = self
189            .available_space(identity.probe_path())
190            .map_err(|error| SqliteError::CapacityUnavailable {
191                phase: CapacityUnavailablePhase::Probe,
192                message: format!(
193                    "cannot sample available space on {}: {error}",
194                    volume.display()
195                ),
196            })?;
197        self.verify_current_volume()?;
198        // SQL does not tell admission how many bytes a generic transaction
199        // will append. VACUUM supplies its known copy-sized estimate here.
200        // A zero reserve removes the floor term only: an operation-specific
201        // headroom is still compared, and with neither term nothing is.
202        // Overflow is a refusal, never a wrapped low threshold.
203        let threshold = self.floor_bytes.checked_add(required_headroom_bytes);
204        if threshold.is_none()
205            || (threshold != Some(0) && available <= threshold.unwrap_or(u64::MAX))
206        {
207            return Err(SqliteError::CapacityFloor {
208                volume: volume.display().to_string(),
209                available_bytes: available,
210                floor_bytes: self.floor_bytes,
211                required_headroom_bytes,
212            });
213        }
214        Ok(())
215    }
216
217    /// Acquire the physical-volume lease before SQLite writer acquisition.
218    /// The caller must retain the returned guard through settlement. A request
219    /// from a thread that already holds this volume's lease fails at once as
220    /// re-entry, naming both call sites, instead of waiting out the deadline.
221    /// `class` names what the lease is for; a [`crate::disk_guard::lease_class_scope`]
222    /// on this thread overrides it.
223    #[track_caller]
224    pub(crate) fn acquire(
225        &self,
226        class: crate::disk_guard::LeaseClass,
227    ) -> Result<Option<VolumeLease>, SqliteError> {
228        self.ensure_settled()?;
229        let Some(identity) = self.expected_volume.as_ref() else {
230            return Ok(None);
231        };
232        self.verify_current_volume()?;
233        #[cfg(test)]
234        if crate::disk_guard::SKIP_VOLUME_LEASE_FOR_MEASUREMENT.load(Ordering::Relaxed) {
235            self.verify_current_volume()?;
236            return Ok(Some(VolumeLease::unheld_for_measurement()));
237        }
238        let mut lease = match identity.acquire(self.guard_deadline, self.volume_lock_dir.as_deref())
239        {
240            Ok(lease) => lease,
241            Err(LeaseRefusal::TimedOut(error)) => {
242                self.record_lease_timeout(&error);
243                return Err(error);
244            }
245            Err(refusal) => return Err(refusal.into()),
246        };
247        self.verify_current_volume()?;
248        lease.classify(crate::disk_guard::effective_class(class));
249        Ok(Some(lease))
250    }
251
252    /// The lease is taken before the pool mutex, so ordinary same-volume
253    /// writer contention ends here rather than at `checkout_timeout`. Count it
254    /// and write a `timeout` row with `phase=lock_contended`, as the pool mutex stage
255    /// does for its own timeouts, so the contention stays visible.
256    fn record_lease_timeout(&self, error: &SqliteError) {
257        self.lease_timeouts.fetch_add(1, Ordering::Relaxed);
258        let db = self
259            .database_path
260            .as_ref()
261            .map(|path| path.display().to_string())
262            .unwrap_or_else(|| "memory".to_string());
263        crate::timeout_sink::emit_lease_timeout(
264            &db,
265            &error.to_string(),
266            self.guard_deadline.as_millis().min(u128::from(u64::MAX)) as u64,
267        );
268    }
269
270    pub(crate) fn lease_timeouts(&self) -> u64 {
271        self.lease_timeouts.load(Ordering::Relaxed)
272    }
273
274    /// Admission for VACUUM: its copy-sized headroom is compared even under a
275    /// zero reserve, and a headroom that cannot be estimated refuses the
276    /// operation instead of admitting it with none.
277    pub(crate) fn check_for_vacuum(&self) -> Result<(), SqliteError> {
278        let headroom = self
279            .database_path
280            .as_deref()
281            .map(crate::vacuum_capacity::estimate_vacuum_headroom)
282            .transpose()?
283            .unwrap_or(0);
284        self.check_with_headroom(headroom)
285    }
286
287    #[cfg(test)]
288    pub(super) fn set_test_space_probe(
289        &self,
290        probe: impl Fn(&Path) -> std::io::Result<u64> + Send + Sync + 'static,
291    ) {
292        *self.space_probe.lock() = Some(Arc::new(probe));
293    }
294
295    #[cfg(test)]
296    pub(crate) fn set_test_current_volume(&self, identity: Option<VolumeIdentity>) {
297        *self.current_volume_override.lock() = identity;
298    }
299
300    #[cfg(test)]
301    pub(crate) fn captured_volume_for_test(&self) -> Option<VolumeIdentity> {
302        self.expected_volume.clone()
303    }
304}
305
306/// A writer connection checked out from the pool.
307/// The Mutex ensures only one writer at a time.
308///
309/// Checkout retains exclusion; each consuming operation samples capacity at
310/// its execution boundary. Raw connection access is not a public capability:
311/// ```compile_fail
312/// use khive_db::ConnectionPool;
313/// fn raw(pool: &ConnectionPool) {
314///     let writer = pool.writer().unwrap();
315///     let _connection = writer.conn();
316/// }
317/// ```
318/// ```compile_fail
319/// use khive_db::ConnectionPool;
320/// fn raw_mut(pool: &ConnectionPool) {
321///     let mut writer = pool.writer().unwrap();
322///     let _connection = writer.conn_mut();
323/// }
324/// ```
325/// ```compile_fail
326/// use khive_db::ConnectionPool;
327/// fn raw_mut(pool: &ConnectionPool) {
328///     let mut writer = pool.writer().unwrap();
329///     let _connection: &mut rusqlite::Connection = &mut *writer;
330/// }
331/// ```
332///
333/// # Terminal settlement
334/// Dropping a retired writer settles its connection before the volume lease is
335/// released. If cleanup cannot restore autocommit and owned SQLite close also
336/// fails, the database path, volume, and errors are emitted to stderr and
337/// tracing, that write reports [`SqliteError::WriterSettlementUnknown`], the
338/// pool is poisoned so every later write is refused with
339/// [`SqliteError::WriterPoisoned`] before it starts, and the lease is then
340/// released.
341pub struct WriterGuard<'pool> {
342    pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
343    /// The origin (ADR-091 backend-scoped attribution) of the pool this
344    /// guard was checked out from, carried so `transaction` can register its
345    /// span with the correct origin without holding a `&ConnectionPool`.
346    pub(super) origin: TxOrigin,
347    pub(super) pool: &'pool ConnectionPool,
348    pub(super) admission: &'pool WriteAdmission,
349    /// Normal writer checkout acquires this before taking the writer mutex.
350    /// Maintenance-only nowait checkout leaves it absent to bypass the floor.
351    pub(super) _volume_lease: Option<VolumeLease>,
352}
353
354/// One synchronous pooled autocommit write or script. Construction samples
355/// capacity under the volume lease, and the owned writer guard retains that
356/// lease until this unit is dropped after SQLite returns to autocommit.
357pub(crate) struct PooledAutocommitWriteUnit<'pool> {
358    writer: WriterGuard<'pool>,
359}
360
361impl PooledAutocommitWriteUnit<'_> {
362    pub(crate) fn conn(&self) -> &ProgressConn {
363        self.writer.conn()
364    }
365
366    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
367        self.writer.conn_mut()
368    }
369
370    pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
371        self.writer.rollback_or_retire(context)
372    }
373}
374
375/// One pooled transaction after lease, BEGIN, and capacity admission. The
376/// owned writer guard rolls back on drop if the caller fails to settle it.
377pub(crate) struct PooledTransactionWriteUnit<'pool> {
378    writer: WriterGuard<'pool>,
379}
380
381impl PooledTransactionWriteUnit<'_> {
382    pub(crate) fn conn(&self) -> &ProgressConn {
383        self.writer.conn()
384    }
385
386    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
387        self.writer.conn_mut()
388    }
389}
390
391/// One standalone write unit on an owned connection. Settlement (autocommit
392/// or successful owned close) precedes release of the volume lease, including
393/// when the operation unwinds or its initial rollback fails.
394pub(crate) struct StandaloneWriteUnit {
395    conn: Option<Connection>,
396    admission: Arc<WriteAdmission>,
397    _volume_lease: Option<VolumeLease>,
398}
399
400impl StandaloneWriteUnit {
401    pub(super) fn new(
402        conn: Connection,
403        admission: Arc<WriteAdmission>,
404        volume_lease: Option<VolumeLease>,
405    ) -> Self {
406        Self {
407            conn: Some(conn),
408            admission,
409            _volume_lease: volume_lease,
410        }
411    }
412
413    pub(crate) fn conn(&self) -> &Connection {
414        self.conn
415            .as_ref()
416            .expect("standalone write unit owns its connection")
417    }
418}
419
420impl Drop for StandaloneWriteUnit {
421    fn drop(&mut self) {
422        let conn = self
423            .conn
424            .take()
425            .expect("standalone write unit retirement owner");
426        if conn.is_autocommit() {
427            drop(conn);
428        } else {
429            // A terminal failure has poisoned the admission; Drop cannot
430            // return it, and the lease is released after this returns.
431            let _ = self.admission.close_retired_connection(conn);
432        }
433    }
434}
435
436/// A zero-wait checkout that can run only the fixed checkpoint recovery
437/// pragmas. The connection remains private: exposing it would let a caller
438/// execute logical writes without disk-reserve admission (ADR-154 §5).
439///
440/// Ordinary SQL is deliberately unavailable through this capability:
441/// ```compile_fail
442/// use khive_db::{ConnectionPool, PoolConfig};
443/// let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
444/// pool.try_checkpoint_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");
445/// ```
446pub struct CheckpointGuard<'pool> {
447    pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
448}
449
450/// SQLite's three-column result from a fixed WAL checkpoint pragma.
451#[derive(Debug, Clone, Copy, PartialEq, Eq)]
452pub struct CheckpointResult {
453    /// Whether SQLite reported a busy checkpoint.
454    pub busy: i64,
455    /// WAL frames observed by SQLite (`-1` when there is no WAL).
456    pub log_frames: i64,
457    /// WAL frames copied back into the database.
458    pub checkpointed_frames: i64,
459}
460
461impl CheckpointGuard<'_> {
462    /// Run a PASSIVE checkpoint without disk-reserve admission.
463    pub fn passive(&self) -> Result<CheckpointResult, SqliteError> {
464        self.guard
465            .query_row("PRAGMA wal_checkpoint(PASSIVE)", [], |row| {
466                Ok(CheckpointResult {
467                    busy: row.get(0)?,
468                    log_frames: row.get(1)?,
469                    checkpointed_frames: row.get(2)?,
470                })
471            })
472            .map_err(Into::into)
473    }
474
475    /// Run a TRUNCATE checkpoint without disk-reserve admission.
476    pub fn truncate(&self) -> Result<CheckpointResult, SqliteError> {
477        self.guard
478            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
479                Ok(CheckpointResult {
480                    busy: row.get(0)?,
481                    log_frames: row.get(1)?,
482                    checkpointed_frames: row.get(2)?,
483                })
484            })
485            .map_err(Into::into)
486    }
487}
488
489/// Process-local monotonic counters for every instrumented writer acquisition
490/// boundary owned by one [`ConnectionPool`].
491///
492/// The aggregate `acquisitions` is the saturating sum of its three explicit
493/// connection classes. Infrastructure-only opens (the diagnostics PASSIVE
494/// probe, the writer task's one-time lifetime connection, and the checkpoint
495/// task's dedicated long-lived connection) are excluded; zero-wait
496/// maintenance probes also remain outside these request-traffic counters.
497#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
498pub struct WriterAcquisitionSnapshot {
499    /// Successful acquisitions across pooled, standalone, and writer-task
500    /// connection classes.
501    pub acquisitions: u64,
502    /// Successful finite-wait pool-mutex writer checkouts.
503    pub pooled_acquisitions: u64,
504    /// Successful per-operation standalone writer connection opens.
505    pub standalone_acquisitions: u64,
506    /// Successful writer-task ownership acquisitions (one per dequeued
507    /// top-level request or successful `BEGIN IMMEDIATE`).
508    pub writer_task_acquisitions: u64,
509    /// Finite-wait pool writer checkouts that exhausted `checkout_timeout`
510    /// waiting for the pool mutex. A file-backed writer reaches that wait only
511    /// after it holds the volume lease; a wait that ends at the lease is
512    /// counted in `lease_timeouts` instead.
513    pub timeouts: u64,
514    /// Writer acquisitions refused because another writer held the volume
515    /// lease past `disk_guard_deadline_ms`, returned as
516    /// `CapacityUnavailable { phase: Lock }`. Every write path takes the lease
517    /// before its connection, so same-volume writer contention is counted
518    /// here, across all of this pool's writer classes.
519    pub lease_timeouts: u64,
520    /// Instrumented direct executions whose final returned error retains SQLite's
521    /// primary DatabaseBusy code, once per operation after its busy handler.
522    /// Excludes LOCKED, checkout/open/admission failures, readers, writer tasks,
523    /// infrastructure probes and uninstrumented raw connection escapes.
524    pub direct_busy_refusals: u64,
525    /// Every writer-task `BEGIN IMMEDIATE` attempt refused busy or locked,
526    /// including refusals a subsequent bounded retry went on to absorb.
527    /// Counted separately from `timeouts` because that counter names the
528    /// pool-mutex checkout stage; folding the two would mislabel the stage.
529    pub writer_task_begin_busy: u64,
530    /// Subset of `writer_task_begin_busy` that a subsequent bounded retry
531    /// absorbed before the request closure ran, so the refusal never
532    /// reached the caller. `writer_task_begin_busy - writer_task_begin_busy_absorbed`
533    /// is the count of refusals a caller actually observed.
534    pub writer_task_begin_busy_absorbed: u64,
535    /// Writer-task `BEGIN IMMEDIATE` attempts that failed for a reason other
536    /// than busy or locked, and so surface as `StorageError::Pool`.
537    pub writer_task_begin_errors: u64,
538    /// Dequeued writer-task requests that reached the writer seam (executed
539    /// or attempted to execute their operation) and terminated in error,
540    /// counted once per request regardless of the specific terminal state.
541    pub writer_task_request_failures: u64,
542    /// Subset of `writer_task_request_failures` whose terminal state was
543    /// `WriterTaskRequestState::SideEffectsUnknown` — the commit or rollback
544    /// outcome could not be established, so the request's side effects on
545    /// the database are unknown.
546    pub writer_task_side_effects_unknown: u64,
547    /// Pooled writer guards released while their connection was still inside
548    /// a transaction, which the guard's drop then rolled back (or, when the
549    /// rollback could not prove autocommit, retired). Every writer path settles
550    /// its transaction before releasing the guard, so a non-zero count is a
551    /// caller that left one open; each drop also writes a `writer_guard_drop`
552    /// row to the timeout sink.
553    pub writer_guard_drop_rollbacks: u64,
554}
555
556/// Atomics backing [`WriterAcquisitionSnapshot`]. The writer task retains an
557/// `Arc` after spawn so its per-request acquisition site can update the same
558/// pool-scoped snapshot without retaining the whole pool.
559#[derive(Debug, Default)]
560pub(crate) struct WriterAcquisitionCounters {
561    pub(super) pooled_acquisitions: AtomicU64,
562    pub(super) standalone_acquisitions: AtomicU64,
563    pub(super) writer_task_acquisitions: AtomicU64,
564    pub(super) pooled_timeouts: AtomicU64,
565    pub(super) direct_busy_refusals: AtomicU64,
566    pub(super) writer_task_begin_busy: AtomicU64,
567    pub(super) writer_task_begin_busy_absorbed: AtomicU64,
568    pub(super) writer_task_begin_errors: AtomicU64,
569    pub(super) writer_task_request_failures: AtomicU64,
570    pub(super) writer_task_side_effects_unknown: AtomicU64,
571    pub(super) writer_guard_drop_rollbacks: AtomicU64,
572}
573
574impl<'pool> WriterGuard<'pool> {
575    /// Bind the lease already owned by this guard to one autocommit write
576    /// unit. The caller must construct the unit immediately before its first
577    /// SQLite write, then keep it through the last call in that unit.
578    pub(crate) fn admit_autocommit(
579        mut self,
580    ) -> Result<PooledAutocommitWriteUnit<'pool>, SqliteError> {
581        if !self.guard.is_autocommit() {
582            self.pool.retire_pooled_writer(&mut self.guard);
583            return Err(SqliteError::InvalidData(
584                "pooled autocommit write began on a connection in a transaction".to_string(),
585            ));
586        }
587        self.ensure_logical_write_checkout(
588            "checkpoint writer checkout cannot admit a logical write",
589        )?;
590        self.admission.check()?;
591        Ok(PooledAutocommitWriteUnit { writer: self })
592    }
593
594    fn ensure_logical_write_checkout(&self, message: &'static str) -> Result<(), SqliteError> {
595        if self._volume_lease.is_none()
596            && self.pool.canonical_path().is_some()
597            && !self.pool.config.read_only
598        {
599            return Err(SqliteError::InvalidData(message.to_string()));
600        }
601        Ok(())
602    }
603
604    /// Borrow inside an already owned internal write boundary.
605    pub(crate) fn conn(&self) -> &ProgressConn {
606        &self.guard
607    }
608
609    /// Borrow for the internal migration owner that retains this guard.
610    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
611        &mut self.guard
612    }
613
614    /// Own one autocommit operation or complete SQL script.
615    ///
616    /// Capacity is checked immediately before the callback. A script must
617    /// finish every transaction it starts; an unfinished one is rolled back
618    /// and refused. The consumed guard retains its lease through settlement,
619    /// including if the callback unwinds.
620    ///
621    /// ```no_run
622    /// use khive_db::{ConnectionPool, SqliteError};
623    /// fn seed(pool: &ConnectionPool) -> Result<(), SqliteError> {
624    ///     pool.writer()?.autocommit(|conn| {
625    ///         conn.execute_batch("CREATE TABLE example(value INTEGER)")?;
626    ///         Ok(())
627    ///     })
628    /// }
629    /// ```
630    /// The callback cannot return a connection borrow:
631    /// ```compile_fail
632    /// use khive_db::ConnectionPool;
633    /// fn escape(pool: &ConnectionPool) {
634    ///     let _connection = pool.writer().unwrap().autocommit(|conn| Ok(conn));
635    /// }
636    /// ```
637    pub fn autocommit<R>(
638        self,
639        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
640    ) -> Result<R, SqliteError> {
641        let mut unit = self.admit_autocommit()?;
642        let result = operation(unit.conn()).map_err(statement_error);
643        if unit.conn().is_autocommit() {
644            return result;
645        }
646        let rollback_proven = unit
647            .writer
648            .rollback_or_retire("autocommit script left its transaction open")
649            .is_ok();
650        settle_open_autocommit_result(
651            result,
652            rollback_proven,
653            "pooled script left a transaction open; rolled back",
654        )
655    }
656
657    /// Run a native SQLite fixture operation through the usual autocommit owner.
658    ///
659    /// Available only to test builds and dependents enabling `test-support`.
660    #[cfg(any(test, feature = "test-support"))]
661    pub fn autocommit_sqlite<R>(
662        self,
663        operation: impl FnOnce(&Connection) -> rusqlite::Result<R>,
664    ) -> Result<R, SqliteError> {
665        self.autocommit(|conn| operation(conn).map_err(Into::into))
666    }
667
668    /// Execute a write transaction.
669    /// Consumes this guard through BEGIN IMMEDIATE, post-BEGIN admission and
670    /// COMMIT/ROLLBACK. The callback must not settle the outer transaction itself.
671    ///
672    /// # Panics
673    ///
674    /// A callback panic propagates to the caller. During unwinding, this guard
675    /// attempts rollback or retirement before releasing its volume lease and
676    /// registered transaction evidence.
677    pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
678    where
679        F: FnOnce(&Connection) -> Result<R, SqliteError>,
680    {
681        let mut tx_handle = None;
682        let mut writer = self;
683        writer.ensure_logical_write_checkout(
684            "checkpoint writer checkout cannot start a logical transaction",
685        )?;
686        writer.begin_admitted_transaction()?;
687        let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
688            Some("writer_guard_tx".to_string()),
689            writer.origin.clone(),
690        ));
691
692        match f(&writer.guard) {
693            Ok(result) => {
694                if let Err(err) = writer.guard.execute_batch("COMMIT") {
695                    if writer.rollback_or_retire("commit failure").is_err() {
696                        return Err(SqliteError::settlement_with_cause(
697                            &err,
698                            khive_storage::error::SqliteWriteStage::Commit,
699                        ));
700                    }
701                    return Err(SqliteError::write(
702                        err,
703                        khive_storage::error::SqliteWriteStage::Commit,
704                    ));
705                }
706                if !writer.guard.is_autocommit() {
707                    writer.pool.retire_pooled_writer(&mut writer.guard);
708                    return Err(SqliteError::WriterSettlementUnknown);
709                }
710                Ok(result)
711            }
712            Err(err) => {
713                if writer
714                    .rollback_or_retire("transaction body failure")
715                    .is_err()
716                {
717                    return Err(SqliteError::settlement_with_cause(
718                        &err,
719                        khive_storage::error::SqliteWriteStage::Statement,
720                    ));
721                }
722                Err(match err {
723                    SqliteError::Rusqlite(error) => {
724                        SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
725                    }
726                    other => other,
727                })
728            }
729        }
730    }
731
732    /// Acquire SQLite's writer slot before sampling logical-write capacity.
733    fn begin_admitted_transaction(&mut self) -> Result<(), SqliteError> {
734        if !self.guard.is_autocommit() {
735            self.pool.retire_pooled_writer(&mut self.guard);
736            return Err(SqliteError::InheritedWriterTransaction);
737        }
738        if let Err(error) = self.guard.execute_batch("BEGIN IMMEDIATE") {
739            if !self.guard.is_autocommit() {
740                self.pool.retire_pooled_writer(&mut self.guard);
741                return Err(SqliteError::settlement_with_cause(
742                    &error,
743                    khive_storage::error::SqliteWriteStage::Begin,
744                ));
745            }
746            return Err(SqliteError::write(
747                error,
748                khive_storage::error::SqliteWriteStage::Begin,
749            ));
750        }
751        if let Err(error) = self.admission.check() {
752            self.rollback_or_retire("capacity admission")?;
753            return Err(error);
754        }
755        Ok(())
756    }
757
758    pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
759        if !crate::connection_settlement::rollback_proves_autocommit(&self.guard) {
760            self.pool.retire_pooled_writer(&mut self.guard);
761            tracing::error!(context, "pooled writer rollback did not prove autocommit");
762            return Err(SqliteError::WriterSettlementUnknown);
763        }
764        Ok(())
765    }
766}
767
768/// See [`ConnectionPool::migration_transactions`].
769pub(crate) struct PooledMigrationTransactions<'pool> {
770    pool: &'pool ConnectionPool,
771}
772
773impl crate::migrations::MigrationTransactions for PooledMigrationTransactions<'_> {
774    fn admitted<T>(
775        &mut self,
776        operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
777    ) -> Result<T, SqliteError> {
778        let mut writer = {
779            let _class =
780                crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
781            self.pool.writer()?
782        };
783        let result = writer.conn_mut().with_mut(operation);
784        if writer.guard.is_autocommit() {
785            return result;
786        }
787        writer.rollback_or_retire("schema migration left its transaction open")?;
788        // Rolled back: an operation that reported success did not commit.
789        result.and(Err(SqliteError::WriterSettlementUnknown))
790    }
791}
792
793impl Drop for WriterGuard<'_> {
794    fn drop(&mut self) {
795        if !self.guard.is_autocommit() {
796            // Last-resort settlement: the writer that opened this transaction
797            // returned without settling it. Its caller has already been
798            // answered, so the outcome is recorded rather than returned.
799            let settlement = self.rollback_or_retire("guard dropped with open transaction");
800            self.pool.record_writer_guard_drop(&settlement);
801        }
802        if self.pool.pooled_writer_retired.load(Ordering::Acquire) {
803            if let Some(replacement) = self.pool.retirement_connection.lock().take() {
804                // The mutex excludes all aliases; settlement precedes lease release.
805                let original = std::mem::replace(&mut *self.guard, replacement);
806                let _ = self
807                    .admission
808                    .close_retired_connection(original.into_inner());
809            }
810        }
811    }
812}
813
814impl ConnectionPool {
815    /// Run one standalone autocommit operation or complete SQL script.
816    ///
817    /// The connection and volume lease remain owned by this call. Capacity
818    /// is checked immediately before the callback. A script may contain
819    /// complete transactions, but returning with a transaction still open
820    /// rolls it back and reports an error. Use [`Self::standalone_transaction`]
821    /// when this API should own BEGIN IMMEDIATE and COMMIT instead.
822    ///
823    /// The callback cannot return a connection borrow:
824    /// ```compile_fail
825    /// use khive_db::ConnectionPool;
826    /// fn escape(pool: &ConnectionPool) {
827    ///     let _connection = pool.standalone_autocommit(|conn| Ok(conn));
828    /// }
829    /// ```
830    #[track_caller]
831    pub fn standalone_autocommit<R>(
832        &self,
833        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
834    ) -> Result<R, SqliteError> {
835        let unit = self.standalone_write_unit()?;
836        self.write_admission.check()?;
837        let result = operation(unit.conn()).map_err(statement_error);
838        if unit.conn().is_autocommit() {
839            return result;
840        }
841        let rollback_proven = crate::connection_settlement::rollback_proves_autocommit(unit.conn());
842        settle_open_autocommit_result(
843            result,
844            rollback_proven,
845            "standalone script left a transaction open; rolled back",
846        )
847    }
848
849    /// Run a standalone BEGIN IMMEDIATE transaction under the volume lease.
850    ///
851    /// Capacity is sampled after BEGIN succeeds and before the callback.
852    /// This call owns COMMIT/ROLLBACK; the callback must not settle the outer
853    /// transaction itself. A panic drops the owned connection before the
854    /// lease can be released.
855    #[track_caller]
856    pub fn standalone_transaction<R>(
857        &self,
858        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
859    ) -> Result<R, SqliteError> {
860        let mut tx_handle = None;
861        let unit = self.standalone_transaction_write_unit()?;
862        let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
863            Some("standalone_transaction".into()),
864            self.origin(),
865        ));
866        match operation(unit.conn()).map_err(statement_error) {
867            Ok(value) => match unit.conn().execute_batch("COMMIT") {
868                Ok(()) if unit.conn().is_autocommit() => Ok(value),
869                Ok(()) => Err(SqliteError::WriterSettlementUnknown),
870                Err(error) => {
871                    if unit.conn().execute_batch("ROLLBACK").is_err()
872                        || !unit.conn().is_autocommit()
873                    {
874                        return Err(SqliteError::settlement_with_cause(
875                            &error,
876                            khive_storage::error::SqliteWriteStage::Commit,
877                        ));
878                    }
879                    Err(SqliteError::write(
880                        error,
881                        khive_storage::error::SqliteWriteStage::Commit,
882                    ))
883                }
884            },
885            Err(error) => {
886                if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
887                    return Err(SqliteError::settlement_with_cause(
888                        &error,
889                        khive_storage::error::SqliteWriteStage::Statement,
890                    ));
891                }
892                Err(error)
893            }
894        }
895    }
896
897    #[track_caller]
898    pub(crate) fn autocommit_write_unit(
899        &self,
900    ) -> Result<PooledAutocommitWriteUnit<'_>, SqliteError> {
901        self.writer()?.admit_autocommit()
902    }
903
904    #[track_caller]
905    pub(crate) fn transaction_write_unit(
906        &self,
907    ) -> Result<super::PooledTransactionWriteUnit<'_>, SqliteError> {
908        let mut writer = self.writer()?;
909        writer.begin_admitted_transaction()?;
910        Ok(PooledTransactionWriteUnit { writer })
911    }
912
913    /// Execute DML on a typed direct transaction, choosing the standalone
914    /// connection required by file-backed async stores or the pooled writer
915    /// used by in-memory stores. The callback cannot begin or commit its own
916    /// outer transaction; this seam owns settlement and the volume lease.
917    #[track_caller]
918    pub(crate) fn execute_direct_transaction<R, F>(
919        &self,
920        capability: StorageCapability,
921        operation: &'static str,
922        f: F,
923    ) -> Result<R, StorageError>
924    where
925        F: FnOnce(&Connection) -> Result<R, StorageError>,
926    {
927        let _tx_handle =
928            khive_storage::tx_registry::register_scoped(Some(operation.to_string()), self.origin());
929        let db_label = crate::timeout_sink::db_label(self);
930        let map_admission_error = |error: SqliteError| {
931            crate::timeout_sink::maybe_emit_sqlite_full(&db_label, &error);
932            let error = error.into_storage_error(capability, operation);
933            self.record_direct_writer_error(&error);
934            error
935        };
936        let result = if self.canonical_path().is_some() {
937            let unit = self
938                .standalone_transaction_write_unit()
939                .map_err(map_admission_error)?;
940            let (result, _) = execute_wrapped_transaction(unit.conn(), operation, f);
941            result
942        } else {
943            let mut unit = self.transaction_write_unit().map_err(map_admission_error)?;
944            let (result, terminal_state) = execute_wrapped_transaction(unit.conn(), operation, f);
945            if terminal_state.is_some() {
946                self.retire_pooled_writer(unit.conn_mut());
947            }
948            result
949        };
950        if let Err(error) = &result {
951            crate::timeout_sink::maybe_emit_sqlite_full(&db_label, error);
952            self.record_direct_writer_error(error);
953        }
954        result
955    }
956
957    /// Run core migrations while preserving owner-before-lease-before-writer
958    /// order for callers that hold a pool but not a backend wrapper.
959    pub fn run_migrations(&self) -> Result<u32, SqliteError> {
960        if self.config.read_only {
961            return Err(SqliteError::InvalidData(
962                "cannot run migrations on a read-only pool".to_string(),
963            ));
964        }
965        let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
966            self.canonical_path().map(Path::to_path_buf),
967        )
968        .map_err(|error| {
969            SqliteError::InvalidData(format!(
970                "failed to acquire database GC owner before schema migration: {error}"
971            ))
972        })?;
973        crate::migrations::run_migrations_with_database_gc_owner(
974            &mut self.migration_transactions(),
975            &owner,
976            &self.write_admission,
977        )
978    }
979
980    /// Migration writes through this pool's writer, checked out in
981    /// lease-then-writer order for each admitted unit and returned once that
982    /// unit has settled.
983    pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
984        PooledMigrationTransactions { pool: self }
985    }
986
987    /// Own one standalone write transaction from lease acquisition through
988    /// settlement. The free-space sample occurs only after BEGIN IMMEDIATE
989    /// has acquired SQLite's writer slot.
990    #[track_caller]
991    pub(crate) fn standalone_transaction_write_unit(
992        &self,
993    ) -> Result<super::StandaloneWriteUnit, SqliteError> {
994        let unit = self.standalone_write_unit()?;
995        self.begin_standalone_transaction(unit)
996    }
997
998    /// The SQL bridge's complete standalone transaction owner. Configure the
999    /// connection before BEGIN, then retain its lease through settlement.
1000    #[track_caller]
1001    pub(crate) fn standalone_sql_bridge_transaction_write_unit(
1002        &self,
1003    ) -> Result<super::StandaloneWriteUnit, StorageError> {
1004        let unit = self
1005            .standalone_write_unit()
1006            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
1007        for (name, value) in [
1008            ("cache_size", sqlite_cache_size_pragma()),
1009            ("mmap_size", sqlite_mmap_size_pragma()),
1010        ] {
1011            unit.conn()
1012                .pragma_update(None, name, value)
1013                .map_err(|error| {
1014                    StorageError::driver(StorageCapability::Sql, "open_writer", error)
1015                })?;
1016        }
1017        self.begin_standalone_transaction(unit)
1018            .map_err(|error| match error {
1019                SqliteError::Write { stage, source } => {
1020                    crate::timeout_sink::maybe_emit_busy(
1021                        &crate::timeout_sink::db_label(self),
1022                        crate::timeout_sink::Site::StandaloneSqlBridge,
1023                        &source,
1024                    );
1025                    crate::error::with_write_stage(
1026                        StorageError::driver(StorageCapability::Sql, "execute", source),
1027                        stage,
1028                    )
1029                }
1030                SqliteError::Rusqlite(source) => {
1031                    crate::timeout_sink::maybe_emit_busy(
1032                        &crate::timeout_sink::db_label(self),
1033                        crate::timeout_sink::Site::StandaloneSqlBridge,
1034                        &source,
1035                    );
1036                    StorageError::driver(StorageCapability::Sql, "execute", source)
1037                }
1038                error => error.into_storage_error(StorageCapability::Sql, "execute"),
1039            })
1040    }
1041
1042    fn begin_standalone_transaction(
1043        &self,
1044        unit: StandaloneWriteUnit,
1045    ) -> Result<StandaloneWriteUnit, SqliteError> {
1046        if let Err(error) = unit.conn().execute_batch("BEGIN IMMEDIATE") {
1047            if !unit.conn().is_autocommit() {
1048                return Err(SqliteError::settlement_with_cause(
1049                    &error,
1050                    khive_storage::error::SqliteWriteStage::Begin,
1051                ));
1052            }
1053            return Err(SqliteError::write(
1054                error,
1055                khive_storage::error::SqliteWriteStage::Begin,
1056            ));
1057        }
1058        if let Err(error) = self.write_admission.check() {
1059            if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
1060                return Err(SqliteError::WriterSettlementUnknown);
1061            }
1062            return Err(error);
1063        }
1064        Ok(unit)
1065    }
1066}
1067
1068fn settle_open_autocommit_result<R>(
1069    result: Result<R, SqliteError>,
1070    rollback_proven: bool,
1071    left_open_message: &'static str,
1072) -> Result<R, SqliteError> {
1073    match (rollback_proven, result) {
1074        (true, result) => result.and(Err(SqliteError::InvalidData(left_open_message.into()))),
1075        (false, Err(error)) => Err(SqliteError::settlement_with_cause(
1076            &error,
1077            khive_storage::error::SqliteWriteStage::Statement,
1078        )),
1079        (false, Ok(_)) => Err(SqliteError::WriterSettlementUnknown),
1080    }
1081}
1082
1083fn statement_error(error: SqliteError) -> SqliteError {
1084    match error {
1085        SqliteError::Rusqlite(error) => {
1086            SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1087        }
1088        other => other,
1089    }
1090}
1091
1092#[cfg(test)]
1093#[path = "standalone_write_tests.rs"]
1094mod standalone_write_tests;
1095
1096#[cfg(test)]
1097#[path = "pooled_write_tests.rs"]
1098mod pooled_write_tests;