Module checkpoint 

Periodic WAL checkpoint task. Periodic WAL checkpoint task for the connection pool (ADR-091).

Issues PRAGMA wal_checkpoint(PASSIVE) on every tick — non-blocking, never waits for readers. A rare, separately-gated escalation may additionally run PRAGMA wal_checkpoint(TRUNCATE) once WAL pressure crosses truncate_high_water_pages and truncate_min_interval has elapsed since the last attempt (Plank 2); both run under the single writer checkout checkpoint_once holds for that tick. checkpoint_once uses try_writer_nowait (zero-wait try_lock) so a tick is skipped immediately when the writer mutex is held, rather than blocking — a skipped tick is always preferable to stalling write traffic.

warn_pages / high_water_pages WARNs fire at most once per below→above crossing; a skipped tick leaves crossing state unchanged. An age-based background sweep (Plank 1) additionally checks the oldest span in khive_storage::tx_registry against tx_warn_secs/tx_max_age_secs on every tick (Skipped or Observed) and escalates to warn!/error! on each below→above crossing — visibility only, nothing here force-closes a stale span.

See crates/khive-db/docs/api/checkpoint.md#module-overview-adr-091-planks-012 for full ADR-091 Plank 0/1/2 design rationale (why TRUNCATE is excluded from ordinary ticks, the single-writer-checkout invariant, and why Plank 1 is a sweep rather than the ADR’s originally-described per-statement guard).

Structs

CheckpointConfig

Configuration for the WAL checkpoint background task.

CheckpointSeverityEmission

One severity-ladder emission produced by a single CheckpointSeverityState::observe_wal_pages call.

CheckpointSeverityState

ADR-091 severity ladder state, carried across ticks by the caller alongside TruncateState. Pure state machine: no I/O, no logging — callers turn the returned emissions into tracing calls.

TruncateState

Mutable escalation state carried across ticks by the caller (ADR-091 Plank 2).

TxAgeEmission

One emission produced by a single TxAgeSweepState::observe call.

TxAgeSweepState

ADR-091 Plank 1 background-sweep state, carried across ticks by the caller alongside CheckpointSeverityState and TruncateState. Pure state machine: no I/O, no logging — callers turn the returned emissions into tracing calls, mirroring CheckpointSeverityState’s shape.

Enums

CheckpointSeverityRung

ADR-091 graduated severity rung for sustained WAL pressure.

CheckpointTick

Outcome of a single checkpoint attempt.

TxAgeRung

ADR-091 Plank 1 rung for the open-transaction registry’s background age sweep: independent of the WAL-pressure ladder above, keyed purely off how long the registry’s oldest entry has been open.

Constants

DEFAULT_WARN_SUSTAINED_CYCLES

Default number of consecutive above-warn_pages observed ticks required to escalate from the INFO to the WARN rung of the ADR-091 severity ladder.

Functions

checkpoint_consecutive_skips

Current consecutive-skip run length; 0 once the next tick is observed.

checkpoint_last_skip_wal_pages

WAL page count last known at the time of the most recent skip, if any skip has occurred yet in this process.

checkpoint_once

Issue one checkpoint cycle against the writer connection.

checkpoint_skipped_ticks

Total checkpoint ticks skipped (writer busy) in this process’s lifetime.

last_observed_wal_pages

Last-observed WAL page count, if any checkpoint tick has run yet in this process. Read surface for the daemon-frame metrics snapshot.

run_checkpoint_task

Run the WAL checkpoint background task.

truncate_attempts

Total WAL TRUNCATE attempts made in this process’s lifetime.

truncate_consecutive_failures

Current consecutive TRUNCATE-attempt failure count.