khive_db/checkpoint.rs
1//! Periodic WAL checkpoint task for the connection pool (ADR-091; dedicated
2//! checkpoint connection amendment, see below).
3//!
4//! Issues `PRAGMA wal_checkpoint(PASSIVE)` on every tick — non-blocking, never
5//! waits for readers. A rare, separately-gated escalation may additionally run
6//! `PRAGMA wal_checkpoint(TRUNCATE)` once WAL pressure crosses
7//! `truncate_high_water_pages` and `truncate_min_interval` has elapsed since
8//! the last attempt (Plank 2); both run on the task's own dedicated
9//! standalone connection (`CheckpointConnection`), opened once at task
10//! startup and reused for every tick — `checkpoint_once` never checks out the
11//! pool's writer mutex at all, so a concurrent `pool.writer()` checkout can
12//! never queue behind a checkpoint tick's ADMISSION. That guarantee is
13//! admission-only: PASSIVE takes SQLite's CKPT lock, not the WRITE lock, so
14//! it never blocks writers at the SQLite level either — but TRUNCATE
15//! additionally acquires SQLite's writer lock and can still block a
16//! concurrent write transaction, on any connection, for up to
17//! `truncate_busy_timeout` while it waits on a pinning reader, exactly as
18//! before this connection split.
19//!
20//! If the dedicated connection is unavailable (never opened yet, or dropped
21//! after a prior tick's connection-level pragma failure), the tick reports
22//! `CheckpointTick::Skipped` and the next tick lazily reopens it. A busy or
23//! inconsistent PASSIVE result also skips pressure decisions without replacing
24//! the last valid WAL sample; a busy pool writer does not cause either skip.
25//!
26//! `warn_pages` / `high_water_pages` WARNs fire at most once per below→above
27//! crossing; a skipped tick leaves crossing state unchanged. An age-based
28//! background sweep (Plank 1) additionally checks the oldest span in
29//! `khive_storage::tx_registry` against `tx_warn_secs`/`tx_max_age_secs` on
30//! every tick (Skipped or Observed) and escalates to `warn!`/`error!` on each
31//! below→above crossing — visibility only, nothing here force-closes a stale
32//! span.
33//!
34//! See crates/khive-db/docs/api/checkpoint.md#module-overview-adr-091-planks-012
35//! for full ADR-091 Plank 0/1/2 design rationale (why TRUNCATE is excluded
36//! from ordinary ticks, the dedicated-connection invariant, and why Plank 1
37//! is a sweep rather than the ADR's originally-described per-statement guard).
38//!
39//! The same long-lived standalone connection also owns a separate, five-minute
40//! FTS5 maintenance cadence. One due call gives one index at most 500 pages of
41//! incremental merge work and uses a zero busy timeout, so this best-effort
42//! derived-index maintenance cannot queue behind application writes.
43
44use std::collections::{BTreeMap, HashMap};
45use std::path::{Path, PathBuf};
46use std::sync::atomic::{AtomicU64, Ordering};
47#[cfg(test)]
48use std::sync::Arc;
49use std::sync::{Mutex, OnceLock};
50use std::time::{Duration, Instant};
51
52use crate::pool::ConnectionPool;
53
54mod backfill_queries;
55mod checkpoint_core;
56mod lifecycle;
57mod task_loop;
58mod walpin_attribution;
59mod walpin_sidecar;
60
61use backfill_queries::{
62 crossing_warn, log_backfill_gap, observed_wal_pages, query_routine_checkpoint_observation,
63 query_truncate_observation, query_wal_pages, CheckpointUnavailableReason,
64 RawCheckpointObservation,
65};
66#[cfg(test)]
67use backfill_queries::{
68 query_backfill_gap, query_checkpoint_observation, test_arm_passive_row, test_take_passive_row,
69};
70pub(crate) use checkpoint_core::{checkpoint_once_core, CheckpointCoreOutcome};
71#[cfg(test)]
72use checkpoint_core::{
73 log_truncate_no_progress_warn, maybe_truncate, note_truncate_outcome,
74 truncate_needs_attribution, truncate_report_test_sync,
75};
76use checkpoint_core::{
77 log_tx_registry_oldest_debug, log_tx_registry_oldest_warn, log_tx_registry_snapshot_warn,
78 log_wal_high_water_warn,
79};
80
81pub use checkpoint_core::checkpoint_once;
82pub use lifecycle::{run_session_sweep_task, CheckpointLifecycleOwner, SweepBackend};
83pub use task_loop::run_checkpoint_task;
84
85#[cfg(test)]
86pub(crate) fn truncate_requests_attribution_for_test(
87 pool: &crate::pool::ConnectionPool,
88 conn: &rusqlite::Connection,
89 config: &CheckpointConfig,
90 wal_pages_before: u64,
91 state: &mut TruncateState,
92) -> bool {
93 checkpoint_core::maybe_truncate(pool, conn, config, wal_pages_before, state).is_some()
94}
95
96use lifecycle::{CheckpointConnection, CheckpointLifecycleEmitter, CheckpointPressureEpisode};
97#[cfg(test)]
98use task_loop::{
99 checkpoint_outcome_should_emit, observe_checkpoint_pressure_tick,
100 run_fts_maintenance_off_worker,
101};
102use walpin_attribution::WalpinAttributionRequest;
103#[cfg(unix)]
104use walpin_attribution::{capture_walpin_attribution_request, complete_walpin_attribution};
105#[cfg(all(test, unix))]
106use walpin_attribution::{
107 log_walpin_sidecar_report, walpin_attribution_test_sync, WalpinAttributionFailure,
108 WalpinReportFreshness,
109};
110use walpin_sidecar::{log_tx_age_emission, ReaderCheckoutSweepState, WalpinSidecarState};
111#[cfg(unix)]
112use walpin_sidecar::{
113 now_epoch_secs, run_walpin_housekeeping_if_due, CachedWalpinAttribution, WalpinFullScanPlan,
114 DEFAULT_WALPIN_FULL_SCAN_INTERVAL,
115};
116
117mod off_worker;
118#[cfg(test)]
119mod off_worker_tests;
120
121// ── metrics read-surface (load/perf harness) ─────────────────────────────
122// Read-only process-wide gauges (never reset outside #[cfg(test)]). See
123// crates/khive-db/docs/api/checkpoint.md#metrics-read-surface-loadperf-harness
124
125/// Last-observed WAL page count (the routine PASSIVE row's `log` value, or a
126/// rare post-TRUNCATE observation from `maybe_truncate`).
127/// `u64::MAX` is the "never observed" sentinel — no checkpoint tick has run
128/// yet in this process — distinct from a genuine zero-page WAL.
129static LAST_WAL_PAGES: AtomicU64 = AtomicU64::new(u64::MAX);
130
131/// Count of TRUNCATE attempts (`maybe_truncate`'s pragma actually invoked,
132/// win or lose) across this process's lifetime.
133static TRUNCATE_ATTEMPTS: AtomicU64 = AtomicU64::new(0);
134
135/// Current consecutive-failure count, mirrored from the caller-owned
136/// `TruncateState::consecutive_failures` field into a process-readable
137/// gauge every time `note_truncate_outcome` runs.
138static TRUNCATE_CONSECUTIVE_FAILURES: AtomicU64 = AtomicU64::new(0);
139
140/// Count of checkpoint ticks without a usable WAL frame observation because
141/// the dedicated connection was unavailable or SQLite returned a busy or
142/// inconsistent PASSIVE row.
143/// Never reset outside `#[cfg(test)]`.
144static CHECKPOINT_SKIPPED_TICKS: AtomicU64 = AtomicU64::new(0);
145
146/// Current run-length of consecutive skipped ticks. Reset to 0 the next time
147/// a tick has a valid WAL frame observation, so a
148/// sustained skip streak is visible even between two successful
149/// observations.
150static CHECKPOINT_CONSECUTIVE_SKIPS: AtomicU64 = AtomicU64::new(0);
151
152/// WAL page count as of the most recent *observed* tick, snapshotted at the
153/// moment a skip occurs. `u64::MAX` is the "no skip has recorded a snapshot
154/// yet" sentinel, mirroring `LAST_WAL_PAGES`.
155static CHECKPOINT_LAST_SKIP_WAL_PAGES: AtomicU64 = AtomicU64::new(u64::MAX);
156
157/// Elevated checkpoint observations aggregated in memory instead of written
158/// as one primary-store lifecycle row per tick (#1838).
159static CHECKPOINT_PRESSURE_ELEVATED_TICKS: AtomicU64 = AtomicU64::new(0);
160
161/// Below-to-above `warn_pages` transitions observed by checkpoint tasks.
162static CHECKPOINT_PRESSURE_EPISODES_STARTED: AtomicU64 = AtomicU64::new(0);
163
164/// Above-to-below `warn_pages` transitions observed by checkpoint tasks.
165static CHECKPOINT_PRESSURE_EPISODES_RECOVERED: AtomicU64 = AtomicU64::new(0);
166
167/// Primary-store append calls actually made by checkpoint lifecycle workers.
168static CHECKPOINT_LIFECYCLE_APPEND_ATTEMPTS: AtomicU64 = AtomicU64::new(0);
169
170/// Checkpoint lifecycle append calls that returned a storage error.
171static CHECKPOINT_LIFECYCLE_APPEND_FAILURES: AtomicU64 = AtomicU64::new(0);
172
173/// Lifecycle transitions rejected before append because the bounded handoff
174/// was full, closed, or could not serialize the payload.
175static CHECKPOINT_LIFECYCLE_ENQUEUE_DROPS: AtomicU64 = AtomicU64::new(0);
176
177/// Count of cached-reader explicit read transactions rolled back on reuse
178/// for exceeding `read_tx_max_age` (#1846), across this process's lifetime.
179/// Unlike the Plank 1 sweep above, this is reclamation, not just visibility:
180/// each count here is a WAL snapshot that was actually released rather than
181/// merely logged as stale. See `sql_bridge.rs::execute_standalone_read`.
182static READ_TX_MAX_AGE_EVICTIONS: AtomicU64 = AtomicU64::new(0);
183
184mod run_state;
185
186pub use run_state::{
187 checkpoint_consecutive_skips, checkpoint_last_skip_wal_pages,
188 checkpoint_lifecycle_append_attempts, checkpoint_lifecycle_append_failures,
189 checkpoint_lifecycle_enqueue_drops, checkpoint_pressure_elevated_ticks,
190 checkpoint_pressure_episodes_recovered, checkpoint_pressure_episodes_started,
191 checkpoint_skipped_ticks, checkpoint_timing, last_observed_wal_pages,
192 read_tx_max_age_evictions, routine_wal_observation, truncate_attempts,
193 truncate_consecutive_failures, CheckpointRun, CheckpointTick, CheckpointTiming,
194 RoutineWalObservation,
195};
196
197pub(crate) use run_state::{
198 checkpoint_run_snapshot, note_read_tx_max_age_eviction, record_checkpoint_run_result,
199 CheckpointRunStatus, CheckpointRunTaskGuard,
200};
201
202use run_state::{
203 note_checkpoint_observed, note_checkpoint_pressure_observation, note_checkpoint_skipped,
204 record_checkpoint_timing, record_routine_wal_observation,
205};
206
207#[cfg(test)]
208pub(crate) use run_state::{checkpoint_run_status, reset_checkpoint_metrics_for_tests};
209
210#[cfg(test)]
211use run_state::{
212 advance_checkpoint_run, advance_checkpoint_run_at, checkpoint_db_key,
213 checkpoint_db_key_from_path, checkpoint_runs, checkpoint_timings,
214};
215
216mod config;
217
218pub(crate) use config::tx_age_thresholds_from_env;
219pub use config::{CheckpointConfig, DEFAULT_WARN_SUSTAINED_CYCLES};
220
221mod severity_state;
222
223pub use severity_state::{
224 CheckpointSeverityEmission, CheckpointSeverityRung, CheckpointSeverityState, TruncateState,
225 TxAgeEmission, TxAgeRung, TxAgeSweepState,
226};
227
228/// ADR-091 Amendment 2 Plank A: config for the observe-only per-session
229/// sweep. Sessions never checkpoint — that stays daemon-owned so N session
230/// processes never compete for the writer mutex — this only watches
231/// `tx_registry` (and, Plank B, refreshes this process's walpin heartbeat).
232const DEFAULT_SESSION_SWEEP_INTERVAL: Duration = Duration::from_secs(5);
233
234#[derive(Clone, Debug)]
235pub struct SessionSweepConfig {
236 /// How often a session polls the registry. Coarser than the daemon's
237 /// tick: sessions do not need the daemon's 500ms checkpoint cadence.
238 ///
239 /// Overridable via `KHIVE_SESSION_SWEEP_INTERVAL_MS`. Default: 5000 ms.
240 pub interval: Duration,
241 /// Same semantics and default as [`CheckpointConfig::tx_warn_secs`].
242 pub tx_warn_secs: Duration,
243 /// Same semantics and default as [`CheckpointConfig::tx_max_age_secs`].
244 pub tx_max_age_secs: Duration,
245}
246
247impl Default for SessionSweepConfig {
248 fn default() -> Self {
249 Self {
250 interval: DEFAULT_SESSION_SWEEP_INTERVAL,
251 tx_warn_secs: Duration::from_secs(30),
252 tx_max_age_secs: Duration::from_secs(120),
253 }
254 }
255}
256
257impl SessionSweepConfig {
258 /// Build from the environment. Reuses `KHIVE_TX_WARN_SECS` /
259 /// `KHIVE_TX_MAX_AGE_SECS` (the same knobs the daemon's checkpoint task
260 /// reads) so a session and the daemon agree on the same thresholds.
261 pub fn from_env() -> Self {
262 let mut cfg = Self {
263 interval: session_sweep_interval_from_env(),
264 ..Self::default()
265 };
266 // Shares `tx_age_thresholds_from_env` with `CheckpointConfig::from_env`
267 // (minor, ADR-091 Amendment 2) so a session and the daemon
268 // parse and validate `KHIVE_TX_WARN_SECS`/`KHIVE_TX_MAX_AGE_SECS`
269 // identically from one source, not two hand-copied blocks.
270 (cfg.tx_warn_secs, cfg.tx_max_age_secs) =
271 tx_age_thresholds_from_env(cfg.tx_warn_secs, cfg.tx_max_age_secs);
272
273 cfg
274 }
275}
276
277fn session_sweep_interval_from_env() -> Duration {
278 let millis = crate::env::env_parse_or("KHIVE_SESSION_SWEEP_INTERVAL_MS", 0_u64);
279 if millis > 0 {
280 Duration::from_millis(millis)
281 } else {
282 DEFAULT_SESSION_SWEEP_INTERVAL
283 }
284}
285
286#[cfg(test)]
287#[path = "checkpoint_tests.rs"]
288mod tests;