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#[derive(Clone, Copy)]
307pub(super) enum LogicalWriteOwner {
308    Request,
309    CoreMigration,
310    Schema,
311    AttachmentCutover,
312    Checkpoint,
313}
314
315/// A writer connection checked out from the pool.
316/// The Mutex ensures only one writer at a time.
317///
318/// Checkout retains exclusion; each consuming operation samples capacity at
319/// its execution boundary. Raw connection access is not a public capability:
320/// ```compile_fail
321/// use khive_db::ConnectionPool;
322/// fn raw(pool: &ConnectionPool) {
323///     let writer = pool.writer().unwrap();
324///     let _connection = writer.conn();
325/// }
326/// ```
327/// ```compile_fail
328/// use khive_db::ConnectionPool;
329/// fn raw_mut(pool: &ConnectionPool) {
330///     let mut writer = pool.writer().unwrap();
331///     let _connection = writer.conn_mut();
332/// }
333/// ```
334/// ```compile_fail
335/// use khive_db::ConnectionPool;
336/// fn raw_mut(pool: &ConnectionPool) {
337///     let mut writer = pool.writer().unwrap();
338///     let _connection: &mut rusqlite::Connection = &mut *writer;
339/// }
340/// ```
341///
342/// # Terminal settlement
343/// Dropping a retired writer settles its connection before the volume lease is
344/// released. If cleanup cannot restore autocommit and owned SQLite close also
345/// fails, the database path, volume, and errors are emitted to stderr and
346/// tracing, that write reports [`SqliteError::WriterSettlementUnknown`], the
347/// pool is poisoned so every later write is refused with
348/// [`SqliteError::WriterPoisoned`] before it starts, and the lease is then
349/// released.
350pub struct WriterGuard<'pool> {
351    pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
352    /// The origin (ADR-091 backend-scoped attribution) of the pool this
353    /// guard was checked out from, carried so `transaction` can register its
354    /// span with the correct origin without holding a `&ConnectionPool`.
355    pub(super) origin: TxOrigin,
356    pub(super) pool: &'pool ConnectionPool,
357    pub(super) admission: &'pool WriteAdmission,
358    pub(super) logical_owner: LogicalWriteOwner,
359    /// Normal writer checkout acquires this before taking the writer mutex.
360    /// Maintenance-only nowait checkout leaves it absent to bypass the floor.
361    pub(super) _volume_lease: Option<VolumeLease>,
362}
363
364/// One synchronous pooled autocommit write or script. Construction samples
365/// capacity under the volume lease, and the owned writer guard retains that
366/// lease until this unit is dropped after SQLite returns to autocommit.
367pub(crate) struct PooledAutocommitWriteUnit<'pool> {
368    writer: WriterGuard<'pool>,
369}
370
371impl PooledAutocommitWriteUnit<'_> {
372    pub(crate) fn conn(&self) -> &ProgressConn {
373        self.writer.conn()
374    }
375
376    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
377        self.writer.conn_mut()
378    }
379
380    pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
381        self.writer.rollback_or_retire(context)
382    }
383}
384
385/// One pooled transaction after lease, BEGIN, and capacity admission. The
386/// owned writer guard rolls back on drop if the caller fails to settle it.
387pub(crate) struct PooledTransactionWriteUnit<'pool> {
388    writer: WriterGuard<'pool>,
389}
390
391impl PooledTransactionWriteUnit<'_> {
392    pub(crate) fn conn(&self) -> &ProgressConn {
393        self.writer.conn()
394    }
395
396    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
397        self.writer.conn_mut()
398    }
399}
400
401/// One standalone write unit on an owned connection. Settlement (autocommit
402/// or successful owned close) precedes release of the volume lease, including
403/// when the operation unwinds or its initial rollback fails.
404pub(crate) struct StandaloneWriteUnit {
405    conn: Option<Connection>,
406    admission: Arc<WriteAdmission>,
407    _volume_lease: Option<VolumeLease>,
408}
409
410impl StandaloneWriteUnit {
411    pub(super) fn new(
412        conn: Connection,
413        admission: Arc<WriteAdmission>,
414        volume_lease: Option<VolumeLease>,
415    ) -> Self {
416        Self {
417            conn: Some(conn),
418            admission,
419            _volume_lease: volume_lease,
420        }
421    }
422
423    pub(crate) fn conn(&self) -> &Connection {
424        self.conn
425            .as_ref()
426            .expect("standalone write unit owns its connection")
427    }
428}
429
430impl Drop for StandaloneWriteUnit {
431    fn drop(&mut self) {
432        let conn = self
433            .conn
434            .take()
435            .expect("standalone write unit retirement owner");
436        if conn.is_autocommit() {
437            drop(conn);
438        } else {
439            // A terminal failure has poisoned the admission; Drop cannot
440            // return it, and the lease is released after this returns.
441            let _ = self.admission.close_retired_connection(conn);
442        }
443    }
444}
445
446/// A zero-wait checkout that can run only the fixed checkpoint recovery
447/// pragmas. The connection remains private: exposing it would let a caller
448/// execute logical writes without disk-reserve admission (ADR-154 §5).
449///
450/// Ordinary SQL is deliberately unavailable through this capability:
451/// ```compile_fail
452/// use khive_db::{ConnectionPool, PoolConfig};
453/// let pool = ConnectionPool::new(PoolConfig::default()).unwrap();
454/// pool.try_checkpoint_nowait().unwrap().execute_batch("CREATE TABLE bypass (id INTEGER)");
455/// ```
456pub struct CheckpointGuard<'pool> {
457    pub(super) guard: parking_lot::MutexGuard<'pool, ProgressConn>,
458}
459
460/// SQLite's three-column result from a fixed WAL checkpoint pragma.
461#[derive(Debug, Clone, Copy, PartialEq, Eq)]
462pub struct CheckpointResult {
463    /// Whether SQLite reported a busy checkpoint.
464    pub busy: i64,
465    /// WAL frames observed by SQLite (`-1` when there is no WAL).
466    pub log_frames: i64,
467    /// WAL frames copied back into the database.
468    pub checkpointed_frames: i64,
469}
470
471impl CheckpointGuard<'_> {
472    /// Run a PASSIVE checkpoint without disk-reserve admission.
473    pub fn passive(&self) -> Result<CheckpointResult, SqliteError> {
474        self.guard
475            .query_row("PRAGMA wal_checkpoint(PASSIVE)", [], |row| {
476                Ok(CheckpointResult {
477                    busy: row.get(0)?,
478                    log_frames: row.get(1)?,
479                    checkpointed_frames: row.get(2)?,
480                })
481            })
482            .map_err(Into::into)
483    }
484
485    /// Run a TRUNCATE checkpoint without disk-reserve admission.
486    pub fn truncate(&self) -> Result<CheckpointResult, SqliteError> {
487        self.guard
488            .query_row("PRAGMA wal_checkpoint(TRUNCATE)", [], |row| {
489                Ok(CheckpointResult {
490                    busy: row.get(0)?,
491                    log_frames: row.get(1)?,
492                    checkpointed_frames: row.get(2)?,
493                })
494            })
495            .map_err(Into::into)
496    }
497}
498
499/// Process-local monotonic counters for every instrumented writer acquisition
500/// boundary owned by one [`ConnectionPool`].
501///
502/// The aggregate `acquisitions` is the saturating sum of its three explicit
503/// connection classes. Infrastructure-only opens (the diagnostics PASSIVE
504/// probe, the writer task's one-time lifetime connection, and the checkpoint
505/// task's dedicated long-lived connection) are excluded; zero-wait
506/// maintenance probes also remain outside these request-traffic counters.
507#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
508pub struct WriterAcquisitionSnapshot {
509    /// Successful acquisitions across pooled, standalone, and writer-task
510    /// connection classes.
511    pub acquisitions: u64,
512    /// Successful finite-wait pool-mutex writer checkouts.
513    pub pooled_acquisitions: u64,
514    /// Successful per-operation standalone writer connection opens.
515    pub standalone_acquisitions: u64,
516    /// Successful writer-task ownership acquisitions (one per dequeued
517    /// top-level request or successful `BEGIN IMMEDIATE`).
518    pub writer_task_acquisitions: u64,
519    /// Finite-wait pool writer checkouts that exhausted `checkout_timeout`
520    /// waiting for the pool mutex. A file-backed writer reaches that wait only
521    /// after it holds the volume lease; a wait that ends at the lease is
522    /// counted in `lease_timeouts` instead.
523    pub timeouts: u64,
524    /// Writer acquisitions refused because another writer held the volume
525    /// lease past `disk_guard_deadline_ms`, returned as
526    /// `CapacityUnavailable { phase: Lock }`. Every write path takes the lease
527    /// before its connection, so same-volume writer contention is counted
528    /// here, across all of this pool's writer classes.
529    pub lease_timeouts: u64,
530    /// Instrumented direct executions whose final returned error retains SQLite's
531    /// primary DatabaseBusy code, once per operation after its busy handler.
532    /// Excludes LOCKED, checkout/open/admission failures, readers, writer tasks,
533    /// infrastructure probes and uninstrumented raw connection escapes.
534    pub direct_busy_refusals: u64,
535    /// Every writer-task `BEGIN IMMEDIATE` attempt refused busy or locked,
536    /// including refusals a subsequent bounded retry went on to absorb.
537    /// Counted separately from `timeouts` because that counter names the
538    /// pool-mutex checkout stage; folding the two would mislabel the stage.
539    pub writer_task_begin_busy: u64,
540    /// Subset of `writer_task_begin_busy` that a subsequent bounded retry
541    /// absorbed before the request closure ran, so the refusal never
542    /// reached the caller. `writer_task_begin_busy - writer_task_begin_busy_absorbed`
543    /// is the count of refusals a caller actually observed.
544    pub writer_task_begin_busy_absorbed: u64,
545    /// Writer-task `BEGIN IMMEDIATE` attempts that failed for a reason other
546    /// than busy or locked, and so surface as `StorageError::Pool`.
547    pub writer_task_begin_errors: u64,
548    /// Dequeued writer-task requests that reached the writer seam (executed
549    /// or attempted to execute their operation) and terminated in error,
550    /// counted once per request regardless of the specific terminal state.
551    pub writer_task_request_failures: u64,
552    /// Subset of `writer_task_request_failures` whose terminal state was
553    /// `WriterTaskRequestState::SideEffectsUnknown` — the commit or rollback
554    /// outcome could not be established, so the request's side effects on
555    /// the database are unknown.
556    pub writer_task_side_effects_unknown: u64,
557    /// Pooled writer guards released while their connection was still inside
558    /// a transaction, which the guard's drop then rolled back (or, when the
559    /// rollback could not prove autocommit, retired). Every writer path settles
560    /// its transaction before releasing the guard, so a non-zero count is a
561    /// caller that left one open; each drop also writes a `writer_guard_drop`
562    /// row to the timeout sink.
563    pub writer_guard_drop_rollbacks: u64,
564}
565
566/// Atomics backing [`WriterAcquisitionSnapshot`]. The writer task retains an
567/// `Arc` after spawn so its per-request acquisition site can update the same
568/// pool-scoped snapshot without retaining the whole pool.
569#[derive(Debug, Default)]
570pub(crate) struct WriterAcquisitionCounters {
571    pub(super) pooled_acquisitions: AtomicU64,
572    pub(super) standalone_acquisitions: AtomicU64,
573    pub(super) writer_task_acquisitions: AtomicU64,
574    pub(super) pooled_timeouts: AtomicU64,
575    pub(super) direct_busy_refusals: AtomicU64,
576    pub(super) writer_task_begin_busy: AtomicU64,
577    pub(super) writer_task_begin_busy_absorbed: AtomicU64,
578    pub(super) writer_task_begin_errors: AtomicU64,
579    pub(super) writer_task_request_failures: AtomicU64,
580    pub(super) writer_task_side_effects_unknown: AtomicU64,
581    pub(super) writer_guard_drop_rollbacks: AtomicU64,
582}
583
584impl<'pool> WriterGuard<'pool> {
585    /// Bind the lease already owned by this guard to one autocommit write
586    /// unit. The caller must construct the unit immediately before its first
587    /// SQLite write, then keep it through the last call in that unit.
588    pub(crate) fn admit_autocommit(
589        mut self,
590    ) -> Result<PooledAutocommitWriteUnit<'pool>, SqliteError> {
591        if !self.guard.is_autocommit() {
592            self.pool.retire_pooled_writer(&mut self.guard);
593            return Err(SqliteError::InvalidData(
594                "pooled autocommit write began on a connection in a transaction".to_string(),
595            ));
596        }
597        self.ensure_logical_write_checkout(
598            "checkpoint writer checkout cannot admit a logical write",
599        )?;
600        self.admission.check()?;
601        Ok(PooledAutocommitWriteUnit { writer: self })
602    }
603
604    fn ensure_logical_write_checkout(&self, message: &'static str) -> Result<(), SqliteError> {
605        if matches!(self.logical_owner, LogicalWriteOwner::Checkpoint) {
606            return Err(SqliteError::InvalidData(message.to_string()));
607        }
608        if matches!(self.logical_owner, LogicalWriteOwner::Request) {
609            self.pool.ensure_request_write_route("pooled_write")?;
610        }
611        if self._volume_lease.is_none()
612            && self.pool.canonical_path().is_some()
613            && !self.pool.config.read_only
614        {
615            return Err(SqliteError::InvalidData(message.to_string()));
616        }
617        Ok(())
618    }
619
620    /// Borrow inside an already owned internal write boundary.
621    pub(crate) fn conn(&self) -> &ProgressConn {
622        &self.guard
623    }
624
625    /// Borrow for the internal migration owner that retains this guard.
626    pub(crate) fn conn_mut(&mut self) -> &mut ProgressConn {
627        &mut self.guard
628    }
629
630    /// Own one autocommit operation or complete SQL script.
631    ///
632    /// Capacity is checked immediately before the callback. A script must
633    /// finish every transaction it starts; an unfinished one is rolled back
634    /// and refused. The consumed guard retains its lease through settlement,
635    /// including if the callback unwinds.
636    ///
637    /// ```no_run
638    /// use khive_db::{ConnectionPool, SqliteError};
639    /// fn seed(pool: &ConnectionPool) -> Result<(), SqliteError> {
640    ///     pool.writer()?.autocommit(|conn| {
641    ///         conn.execute_batch("CREATE TABLE example(value INTEGER)")?;
642    ///         Ok(())
643    ///     })
644    /// }
645    /// ```
646    /// The callback cannot return a connection borrow:
647    /// ```compile_fail
648    /// use khive_db::ConnectionPool;
649    /// fn escape(pool: &ConnectionPool) {
650    ///     let _connection = pool.writer().unwrap().autocommit(|conn| Ok(conn));
651    /// }
652    /// ```
653    pub fn autocommit<R>(
654        self,
655        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
656    ) -> Result<R, SqliteError> {
657        let mut unit = self.admit_autocommit()?;
658        let result = operation(unit.conn()).map_err(statement_error);
659        if unit.conn().is_autocommit() {
660            return result;
661        }
662        let rollback_proven = unit
663            .writer
664            .rollback_or_retire("autocommit script left its transaction open")
665            .is_ok();
666        settle_open_autocommit_result(
667            result,
668            rollback_proven,
669            "pooled script left a transaction open; rolled back",
670        )
671    }
672
673    /// Run a native SQLite fixture operation through the usual autocommit owner.
674    ///
675    /// Available only to test builds and dependents enabling `test-support`.
676    #[cfg(any(test, feature = "test-support"))]
677    pub fn autocommit_sqlite<R>(
678        self,
679        operation: impl FnOnce(&Connection) -> rusqlite::Result<R>,
680    ) -> Result<R, SqliteError> {
681        self.autocommit(|conn| operation(conn).map_err(Into::into))
682    }
683
684    /// Execute a write transaction.
685    /// Consumes this guard through BEGIN IMMEDIATE, post-BEGIN admission and
686    /// COMMIT/ROLLBACK. The callback must not settle the outer transaction itself.
687    ///
688    /// # Panics
689    ///
690    /// A callback panic propagates to the caller. During unwinding, this guard
691    /// attempts rollback or retirement before releasing its volume lease and
692    /// registered transaction evidence.
693    pub fn transaction<F, R>(self, f: F) -> Result<R, SqliteError>
694    where
695        F: FnOnce(&Connection) -> Result<R, SqliteError>,
696    {
697        let mut tx_handle = None;
698        let mut writer = self;
699        writer.ensure_logical_write_checkout(
700            "checkpoint writer checkout cannot start a logical transaction",
701        )?;
702        writer.begin_admitted_transaction()?;
703        let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
704            Some("writer_guard_tx".to_string()),
705            writer.origin.clone(),
706        ));
707
708        match f(&writer.guard) {
709            Ok(result) => {
710                if let Err(err) = writer.guard.execute_batch("COMMIT") {
711                    if writer.rollback_or_retire("commit failure").is_err() {
712                        return Err(SqliteError::settlement_with_cause(
713                            &err,
714                            khive_storage::error::SqliteWriteStage::Commit,
715                        ));
716                    }
717                    return Err(SqliteError::write(
718                        err,
719                        khive_storage::error::SqliteWriteStage::Commit,
720                    ));
721                }
722                if !writer.guard.is_autocommit() {
723                    writer.pool.retire_pooled_writer(&mut writer.guard);
724                    return Err(SqliteError::WriterSettlementUnknown);
725                }
726                Ok(result)
727            }
728            Err(err) => {
729                if writer
730                    .rollback_or_retire("transaction body failure")
731                    .is_err()
732                {
733                    return Err(SqliteError::settlement_with_cause(
734                        &err,
735                        khive_storage::error::SqliteWriteStage::Statement,
736                    ));
737                }
738                Err(match err {
739                    SqliteError::Rusqlite(error) => {
740                        SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
741                    }
742                    other => other,
743                })
744            }
745        }
746    }
747
748    /// Acquire SQLite's writer slot before sampling logical-write capacity.
749    fn begin_admitted_transaction(&mut self) -> Result<(), SqliteError> {
750        self.ensure_logical_write_checkout("checkpoint writer cannot begin a logical transaction")?;
751        if !self.guard.is_autocommit() {
752            self.pool.retire_pooled_writer(&mut self.guard);
753            return Err(SqliteError::InheritedWriterTransaction);
754        }
755        if let Err(error) = self.guard.execute_batch("BEGIN IMMEDIATE") {
756            if !self.guard.is_autocommit() {
757                self.pool.retire_pooled_writer(&mut self.guard);
758                return Err(SqliteError::settlement_with_cause(
759                    &error,
760                    khive_storage::error::SqliteWriteStage::Begin,
761                ));
762            }
763            return Err(SqliteError::write(
764                error,
765                khive_storage::error::SqliteWriteStage::Begin,
766            ));
767        }
768        if let Err(error) = self.admission.check() {
769            self.rollback_or_retire("capacity admission")?;
770            return Err(error);
771        }
772        Ok(())
773    }
774
775    pub(crate) fn rollback_or_retire(&mut self, context: &str) -> Result<(), SqliteError> {
776        if !crate::connection_settlement::rollback_proves_autocommit(&self.guard) {
777            self.pool.retire_pooled_writer(&mut self.guard);
778            tracing::error!(context, "pooled writer rollback did not prove autocommit");
779            return Err(SqliteError::WriterSettlementUnknown);
780        }
781        Ok(())
782    }
783}
784
785/// See [`ConnectionPool::migration_transactions`].
786pub(crate) struct PooledMigrationTransactions<'pool> {
787    pool: &'pool ConnectionPool,
788}
789
790impl crate::migrations::MigrationTransactions for PooledMigrationTransactions<'_> {
791    fn admitted<T>(
792        &mut self,
793        operation: impl FnOnce(&mut Connection) -> Result<T, SqliteError>,
794    ) -> Result<T, SqliteError> {
795        let mut writer = {
796            let _class =
797                crate::disk_guard::lease_class_scope(crate::disk_guard::LeaseClass::Migration);
798            self.pool.writer_for_core_migration()?
799        };
800        let result = writer.conn_mut().with_mut(operation);
801        if writer.guard.is_autocommit() {
802            return result;
803        }
804        writer.rollback_or_retire("schema migration left its transaction open")?;
805        // Rolled back: an operation that reported success did not commit.
806        result.and(Err(SqliteError::WriterSettlementUnknown))
807    }
808}
809
810impl Drop for WriterGuard<'_> {
811    fn drop(&mut self) {
812        if !self.guard.is_autocommit() {
813            // Last-resort settlement: the writer that opened this transaction
814            // returned without settling it. Its caller has already been
815            // answered, so the outcome is recorded rather than returned.
816            let settlement = self.rollback_or_retire("guard dropped with open transaction");
817            self.pool.record_writer_guard_drop(&settlement);
818        }
819        if self.pool.pooled_writer_retired.load(Ordering::Acquire) {
820            if let Some(replacement) = self.pool.retirement_connection.lock().take() {
821                // The mutex excludes all aliases; settlement precedes lease release.
822                let original = std::mem::replace(&mut *self.guard, replacement);
823                let _ = self
824                    .admission
825                    .close_retired_connection(original.into_inner());
826            }
827        }
828    }
829}
830
831impl ConnectionPool {
832    pub(crate) fn ensure_request_write_route(
833        &self,
834        operation: &'static str,
835    ) -> Result<(), SqliteError> {
836        if self.config.write_routing_strict {
837            Err(SqliteError::WriterRouteViolation { operation })
838        } else {
839            Ok(())
840        }
841    }
842
843    /// Run one standalone autocommit operation or complete SQL script.
844    ///
845    /// The connection and volume lease remain owned by this call. Capacity
846    /// is checked immediately before the callback. A script may contain
847    /// complete transactions, but returning with a transaction still open
848    /// rolls it back and reports an error. Use [`Self::standalone_transaction`]
849    /// when this API should own BEGIN IMMEDIATE and COMMIT instead.
850    ///
851    /// The callback cannot return a connection borrow:
852    /// ```compile_fail
853    /// use khive_db::ConnectionPool;
854    /// fn escape(pool: &ConnectionPool) {
855    ///     let _connection = pool.standalone_autocommit(|conn| Ok(conn));
856    /// }
857    /// ```
858    #[track_caller]
859    pub fn standalone_autocommit<R>(
860        &self,
861        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
862    ) -> Result<R, SqliteError> {
863        let unit = self.standalone_write_unit()?;
864        self.write_admission.check()?;
865        let result = operation(unit.conn()).map_err(statement_error);
866        if unit.conn().is_autocommit() {
867            return result;
868        }
869        let rollback_proven = crate::connection_settlement::rollback_proves_autocommit(unit.conn());
870        settle_open_autocommit_result(
871            result,
872            rollback_proven,
873            "standalone script left a transaction open; rolled back",
874        )
875    }
876
877    /// Run a standalone BEGIN IMMEDIATE transaction under the volume lease.
878    ///
879    /// Capacity is sampled after BEGIN succeeds and before the callback.
880    /// This call owns COMMIT/ROLLBACK; the callback must not settle the outer
881    /// transaction itself. A panic drops the owned connection before the
882    /// lease can be released.
883    #[track_caller]
884    pub fn standalone_transaction<R>(
885        &self,
886        operation: impl FnOnce(&Connection) -> Result<R, SqliteError>,
887    ) -> Result<R, SqliteError> {
888        let mut tx_handle = None;
889        let unit = self.standalone_transaction_write_unit()?;
890        let _ = tx_handle.insert(khive_storage::tx_registry::register_scoped(
891            Some("standalone_transaction".into()),
892            self.origin(),
893        ));
894        match operation(unit.conn()).map_err(statement_error) {
895            Ok(value) => match unit.conn().execute_batch("COMMIT") {
896                Ok(()) if unit.conn().is_autocommit() => Ok(value),
897                Ok(()) => Err(SqliteError::WriterSettlementUnknown),
898                Err(error) => {
899                    if unit.conn().execute_batch("ROLLBACK").is_err()
900                        || !unit.conn().is_autocommit()
901                    {
902                        return Err(SqliteError::settlement_with_cause(
903                            &error,
904                            khive_storage::error::SqliteWriteStage::Commit,
905                        ));
906                    }
907                    Err(SqliteError::write(
908                        error,
909                        khive_storage::error::SqliteWriteStage::Commit,
910                    ))
911                }
912            },
913            Err(error) => {
914                if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
915                    return Err(SqliteError::settlement_with_cause(
916                        &error,
917                        khive_storage::error::SqliteWriteStage::Statement,
918                    ));
919                }
920                Err(error)
921            }
922        }
923    }
924
925    #[track_caller]
926    pub(crate) fn autocommit_write_unit(
927        &self,
928    ) -> Result<PooledAutocommitWriteUnit<'_>, SqliteError> {
929        self.writer()?.admit_autocommit()
930    }
931
932    #[track_caller]
933    pub(crate) fn transaction_write_unit(
934        &self,
935    ) -> Result<super::PooledTransactionWriteUnit<'_>, SqliteError> {
936        let mut writer = self.writer()?;
937        writer.begin_admitted_transaction()?;
938        Ok(PooledTransactionWriteUnit { writer })
939    }
940
941    /// Execute DML on a typed direct transaction, choosing the standalone
942    /// connection required by file-backed async stores or the pooled writer
943    /// used by in-memory stores. The callback cannot begin or commit its own
944    /// outer transaction; this seam owns settlement and the volume lease.
945    #[track_caller]
946    pub(crate) fn execute_direct_transaction<R, F>(
947        &self,
948        capability: StorageCapability,
949        operation: &'static str,
950        f: F,
951    ) -> Result<R, StorageError>
952    where
953        F: FnOnce(&Connection) -> Result<R, StorageError>,
954    {
955        let _tx_handle =
956            khive_storage::tx_registry::register_scoped(Some(operation.to_string()), self.origin());
957        let db_label = crate::timeout_sink::db_label(self);
958        let map_admission_error = |error: SqliteError| {
959            crate::timeout_sink::maybe_emit_sqlite_full(&db_label, &error);
960            let error = error.into_storage_error(capability, operation);
961            self.record_direct_writer_error(&error);
962            error
963        };
964        let result = if self.canonical_path().is_some() {
965            let unit = self
966                .standalone_transaction_write_unit()
967                .map_err(map_admission_error)?;
968            let (result, _) = execute_wrapped_transaction(unit.conn(), operation, f);
969            result
970        } else {
971            let mut unit = self.transaction_write_unit().map_err(map_admission_error)?;
972            let (result, terminal_state) = execute_wrapped_transaction(unit.conn(), operation, f);
973            if terminal_state.is_some() {
974                self.retire_pooled_writer(unit.conn_mut());
975            }
976            result
977        };
978        if let Err(error) = &result {
979            crate::timeout_sink::maybe_emit_sqlite_full(&db_label, error);
980            self.record_direct_writer_error(error);
981        }
982        result
983    }
984
985    /// Run core migrations while preserving owner-before-lease-before-writer
986    /// order for callers that hold a pool but not a backend wrapper.
987    pub fn run_migrations(&self) -> Result<u32, SqliteError> {
988        if self.config.read_only {
989            return Err(SqliteError::InvalidData(
990                "cannot run migrations on a read-only pool".to_string(),
991            ));
992        }
993        let owner = crate::stores::blob::acquire_database_gc_owner_for_path_blocking(
994            self.canonical_path().map(Path::to_path_buf),
995        )
996        .map_err(|error| {
997            SqliteError::InvalidData(format!(
998                "failed to acquire database GC owner before schema migration: {error}"
999            ))
1000        })?;
1001        crate::migrations::run_migrations_with_database_gc_owner(
1002            &mut self.migration_transactions(),
1003            &owner,
1004            &self.write_admission,
1005        )
1006    }
1007
1008    /// Migration writes through this pool's writer, checked out in
1009    /// lease-then-writer order for each admitted unit and returned once that
1010    /// unit has settled.
1011    pub(crate) fn migration_transactions(&self) -> PooledMigrationTransactions<'_> {
1012        PooledMigrationTransactions { pool: self }
1013    }
1014
1015    /// Own one standalone write transaction from lease acquisition through
1016    /// settlement. The free-space sample occurs only after BEGIN IMMEDIATE
1017    /// has acquired SQLite's writer slot.
1018    #[track_caller]
1019    pub(crate) fn standalone_transaction_write_unit(
1020        &self,
1021    ) -> Result<super::StandaloneWriteUnit, SqliteError> {
1022        let unit = self.standalone_write_unit()?;
1023        self.begin_standalone_transaction(unit)
1024    }
1025
1026    /// The SQL bridge's complete standalone transaction owner. Configure the
1027    /// connection before BEGIN, then retain its lease through settlement.
1028    #[track_caller]
1029    pub(crate) fn standalone_sql_bridge_transaction_write_unit(
1030        &self,
1031    ) -> Result<super::StandaloneWriteUnit, StorageError> {
1032        let unit = self
1033            .standalone_write_unit()
1034            .map_err(|error| error.into_storage_error(StorageCapability::Sql, "open_writer"))?;
1035        for (name, value) in [
1036            ("cache_size", sqlite_cache_size_pragma()),
1037            ("mmap_size", sqlite_mmap_size_pragma()),
1038        ] {
1039            unit.conn()
1040                .pragma_update(None, name, value)
1041                .map_err(|error| {
1042                    StorageError::driver(StorageCapability::Sql, "open_writer", error)
1043                })?;
1044        }
1045        self.begin_standalone_transaction(unit)
1046            .map_err(|error| match error {
1047                SqliteError::Write { stage, source } => {
1048                    crate::timeout_sink::maybe_emit_busy(
1049                        &crate::timeout_sink::db_label(self),
1050                        crate::timeout_sink::Site::StandaloneSqlBridge,
1051                        &source,
1052                    );
1053                    crate::error::with_write_stage(
1054                        StorageError::driver(StorageCapability::Sql, "execute", source),
1055                        stage,
1056                    )
1057                }
1058                SqliteError::Rusqlite(source) => {
1059                    crate::timeout_sink::maybe_emit_busy(
1060                        &crate::timeout_sink::db_label(self),
1061                        crate::timeout_sink::Site::StandaloneSqlBridge,
1062                        &source,
1063                    );
1064                    StorageError::driver(StorageCapability::Sql, "execute", source)
1065                }
1066                error => error.into_storage_error(StorageCapability::Sql, "execute"),
1067            })
1068    }
1069
1070    fn begin_standalone_transaction(
1071        &self,
1072        unit: StandaloneWriteUnit,
1073    ) -> Result<StandaloneWriteUnit, SqliteError> {
1074        if let Err(error) = unit.conn().execute_batch("BEGIN IMMEDIATE") {
1075            if !unit.conn().is_autocommit() {
1076                return Err(SqliteError::settlement_with_cause(
1077                    &error,
1078                    khive_storage::error::SqliteWriteStage::Begin,
1079                ));
1080            }
1081            return Err(SqliteError::write(
1082                error,
1083                khive_storage::error::SqliteWriteStage::Begin,
1084            ));
1085        }
1086        if let Err(error) = self.write_admission.check() {
1087            if unit.conn().execute_batch("ROLLBACK").is_err() || !unit.conn().is_autocommit() {
1088                return Err(SqliteError::WriterSettlementUnknown);
1089            }
1090            return Err(error);
1091        }
1092        Ok(unit)
1093    }
1094}
1095
1096fn settle_open_autocommit_result<R>(
1097    result: Result<R, SqliteError>,
1098    rollback_proven: bool,
1099    left_open_message: &'static str,
1100) -> Result<R, SqliteError> {
1101    match (rollback_proven, result) {
1102        (true, result) => result.and(Err(SqliteError::InvalidData(left_open_message.into()))),
1103        (false, Err(error)) => Err(SqliteError::settlement_with_cause(
1104            &error,
1105            khive_storage::error::SqliteWriteStage::Statement,
1106        )),
1107        (false, Ok(_)) => Err(SqliteError::WriterSettlementUnknown),
1108    }
1109}
1110
1111fn statement_error(error: SqliteError) -> SqliteError {
1112    match error {
1113        SqliteError::Rusqlite(error) => {
1114            SqliteError::write(error, khive_storage::error::SqliteWriteStage::Statement)
1115        }
1116        other => other,
1117    }
1118}
1119
1120#[cfg(test)]
1121#[path = "standalone_write_tests.rs"]
1122mod standalone_write_tests;
1123
1124#[cfg(test)]
1125#[path = "pooled_write_tests.rs"]
1126mod pooled_write_tests;
1127
1128#[cfg(test)]
1129mod routing_authority_tests {
1130    use super::*;
1131
1132    #[test]
1133    fn checkpoint_owner_never_grants_memory_logical_write_authority() {
1134        for strict in [false, true] {
1135            let pool = ConnectionPool::new(PoolConfig {
1136                write_routing_strict: strict,
1137                write_queue_enabled: Some(false),
1138                ..PoolConfig::for_test()
1139            })
1140            .unwrap();
1141            let called = std::cell::Cell::new(false);
1142            let result = pool
1143                .writer_for_checkpoint_operation()
1144                .unwrap()
1145                .autocommit(|_| {
1146                    called.set(true);
1147                    Ok(())
1148                });
1149            assert!(
1150                matches!(result, Err(SqliteError::InvalidData(_))),
1151                "checkpoint authority cannot admit a logical write on a memory pool: {result:?}"
1152            );
1153            assert!(
1154                !called.get(),
1155                "checkpoint refusal must precede the write callback"
1156            );
1157        }
1158    }
1159}