Struct CheckpointConfig 

pub struct CheckpointConfig {
    pub interval: Duration,
    pub warn_pages: u64,
    pub warn_sustained_cycles: u8,
    pub high_water_pages: u64,
    pub truncate_high_water_pages: u64,
    pub truncate_min_interval: Duration,
    pub truncate_busy_timeout: Duration,
    pub tx_warn_secs: Duration,
    pub tx_max_age_secs: Duration,
}

Configuration for the WAL checkpoint background task.

All fields default to conservative production values. Override via the environment variables documented on each field.

Fields

interval: Duration

How often to run a passive checkpoint when there is no active write.

Overridable via KHIVE_CHECKPOINT_INTERVAL_MS (milliseconds). Default: 500 ms.

warn_pages: u64

WAL page count above which a warning is logged.

Overridable via KHIVE_WAL_WARN_PAGES. Default: 2000 pages (~8 MB at 4 KiB page size).

warn_sustained_cycles: u8

Number of consecutive observed ticks with wal_pages >= warn_pages required before the ADR-091 severity ladder escalates from INFO (first crossing) to WARN (sustained pressure). Edge-triggered once per elevation episode — see CheckpointSeverityState.

Overridable via KHIVE_WAL_WARN_SUSTAINED_CYCLES. Default: 3 cycles.

high_water_pages: u64

WAL page count above which a high-pressure WARNING is logged.

The periodic task always runs PASSIVE regardless; this threshold signals that a long-lived reader may be pinning an old WAL snapshot that PASSIVE cannot reclaim. An operator can then schedule a blocking TRUNCATE at a safe moment outside normal write traffic.

Overridable via KHIVE_WAL_HIGH_WATER_PAGES. Default: 6000 pages (~24 MB at 4 KiB page size).

truncate_high_water_pages: u64

WAL page count above which a TRUNCATE escalation attempt is armed (ADR-091 Plank 2).

This is a separate, much higher threshold than high_water_pages: crossing it does not itself attempt TRUNCATE — it only arms the attempt, which additionally requires truncate_min_interval to have elapsed since the last attempt.

Overridable via KHIVE_WAL_TRUNCATE_HIGH_WATER_PAGES. Default: 20000 pages.

truncate_min_interval: Duration

Minimum spacing between TRUNCATE attempts (not successes).

A skipped tick (writer busy, below threshold, or interval not yet elapsed) never advances the “last attempt” clock, so the next tick where the writer is free and the threshold is still crossed is immediately eligible rather than waiting out the full interval again.

Overridable via KHIVE_WAL_TRUNCATE_MIN_INTERVAL_SECS. Default: 300 seconds (5 minutes).

truncate_busy_timeout: Duration

Temporary busy_timeout used only for the duration of a TRUNCATE attempt, restored to the pool’s configured busy timeout immediately after the attempt completes (win or lose).

Overridable via KHIVE_WAL_TRUNCATE_BUSY_MS. Default: 2000 ms.

tx_warn_secs: Duration

ADR-091 Plank 1 soft cap: age past which the oldest entry in the shared open-transaction registry is surfaced at tracing::warn! on every tick (Skipped or Observed), independent of WAL page pressure. See crates/khive-db/docs/api/checkpoint.md for the Plank 1 rationale.

Overridable via KHIVE_TX_WARN_SECS. Default: 30 seconds.

tx_max_age_secs: Duration

ADR-091 Plank 1 hard cap: age past which the same sweep escalates the oldest registry entry to tracing::error!. This is visibility only — nothing here can force-close a stale span; see crates/khive-db/docs/design.md for why.

Overridable via KHIVE_TX_MAX_AGE_SECS. Default: 120 seconds.

Implementations

impl CheckpointConfig

pub fn from_env() -> CheckpointConfig

Build a CheckpointConfig from the environment.

Unset or unparseable variables fall back to the compiled-in defaults.

Trait Implementations

impl Clone for CheckpointConfig

fn clone(&self) -> CheckpointConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CheckpointConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for CheckpointConfig

fn default() -> CheckpointConfig

Returns the “default value” for a type.