feat(nodedb-types): add bitemporal audit-retention config types

Add `BitemporalRetention` (per-collection policy: engine tag, audit
retain duration, enforcement mode) and `BitemporalTuning` (operator-
tunable tick interval for the enforcement loop) to `nodedb-types`.

Expose both through `config::retention` and `config::tuning::bitemporal`
sub-modules, and wire `TuningConfig::bitemporal_retention_tick()` so the
Event Plane can read the cadence without depending on the full config
hierarchy.

Author: farhan-syah

nodedb-types/src/config/mod.rs

@@ -1,3 +1,5 @@
+pub mod retention;
 pub mod tuning;
 
+pub use retention::{BitemporalRetention, RetentionValidationError};
 pub use tuning::TuningConfig;

nodedb-types/src/config/retention.rs

@@ -0,0 +1,136 @@
+//! Cross-engine bitemporal retention configuration.
+//!
+//! Bitemporal collections split "retention" along two independent axes:
+//!
+//! - `data_retain_ms` — how long the *current* logical row stays queryable
+//!   in live reads (the "as of now" view). Superseded by normal
+//!   engine-specific retention when the collection is not bitemporal.
+//! - `audit_retain_ms` — how long *superseded versions* of a row are
+//!   preserved for historical / audit-time queries (the "as of then" view).
+//!
+//! The minimum audit retention is a floor enforced by policy — some
+//! deployments (regulated, GDPR-on-paper, SOC2) require audit history to
+//! survive beyond the default so operators can't silently configure it
+//! below the compliance floor.
+//!
+//! Lives in `nodedb-types` because multiple engines (Columnar, Array,
+//! EdgeStore, DocumentStrict) compose it into their engine-specific
+//! config. Engine code consults the two axes separately: data purge
+//! deletes the live row when `data_retain_ms` elapses; audit purge
+//! deletes superseded versions when `audit_retain_ms` elapses.
+
+use serde::{Deserialize, Serialize};
+
+/// Error validating a [`BitemporalRetention`].
+#[derive(Debug, thiserror::Error)]
+#[error("bitemporal retention: {field} — {reason}")]
+pub struct RetentionValidationError {
+    pub field: String,
+    pub reason: String,
+}
+
+/// Per-collection bitemporal retention policy.
+///
+/// Two independent axes: data (live rows) and audit (superseded
+/// versions). Zero on either axis means "retain forever".
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub struct BitemporalRetention {
+    /// Retention for currently-live rows (versions where
+    /// `_ts_valid_until == MAX`). `0` = retain forever.
+    pub data_retain_ms: u64,
+
+    /// Retention for superseded versions (versions where
+    /// `_ts_valid_until < MAX`). `0` = retain forever.
+    pub audit_retain_ms: u64,
+
+    /// Policy floor for `audit_retain_ms`. Operators cannot configure
+    /// `audit_retain_ms` below this value. `0` = no floor.
+    pub minimum_audit_retain_ms: u64,
+}
+
+impl BitemporalRetention {
+    /// Retain everything forever. Sensible conservative default for
+    /// bitemporal collections where operator intent is unstated.
+    pub const fn retain_forever() -> Self {
+        Self {
+            data_retain_ms: 0,
+            audit_retain_ms: 0,
+            minimum_audit_retain_ms: 0,
+        }
+    }
+
+    /// Validate axis consistency and policy floor.
+    pub fn validate(&self) -> Result<(), RetentionValidationError> {
+        if self.minimum_audit_retain_ms > 0
+            && self.audit_retain_ms > 0
+            && self.audit_retain_ms < self.minimum_audit_retain_ms
+        {
+            return Err(RetentionValidationError {
+                field: "audit_retain_ms".into(),
+                reason: format!(
+                    "{} is below minimum_audit_retain_ms ({})",
+                    self.audit_retain_ms, self.minimum_audit_retain_ms
+                ),
+            });
+        }
+        Ok(())
+    }
+}
+
+impl Default for BitemporalRetention {
+    fn default() -> Self {
+        Self::retain_forever()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn retain_forever_validates() {
+        assert!(BitemporalRetention::retain_forever().validate().is_ok());
+    }
+
+    #[test]
+    fn audit_below_floor_rejected() {
+        let r = BitemporalRetention {
+            data_retain_ms: 0,
+            audit_retain_ms: 60_000,
+            minimum_audit_retain_ms: 120_000,
+        };
+        let err = r.validate().expect_err("must reject");
+        assert_eq!(err.field, "audit_retain_ms");
+    }
+
+    #[test]
+    fn audit_at_or_above_floor_ok() {
+        let r = BitemporalRetention {
+            data_retain_ms: 0,
+            audit_retain_ms: 120_000,
+            minimum_audit_retain_ms: 120_000,
+        };
+        assert!(r.validate().is_ok());
+    }
+
+    #[test]
+    fn zero_audit_ignores_floor() {
+        // audit_retain_ms == 0 means "retain forever" — floor does not apply.
+        let r = BitemporalRetention {
+            data_retain_ms: 0,
+            audit_retain_ms: 0,
+            minimum_audit_retain_ms: 120_000,
+        };
+        assert!(r.validate().is_ok());
+    }
+
+    #[test]
+    fn data_and_audit_are_independent() {
+        let r = BitemporalRetention {
+            data_retain_ms: 30_000,
+            audit_retain_ms: 300_000,
+            minimum_audit_retain_ms: 0,
+        };
+        assert!(r.validate().is_ok());
+    }
+}

nodedb-types/src/config/tuning/bitemporal.rs

@@ -0,0 +1,62 @@
+//! Bitemporal audit-retention scheduler tuning.
+//!
+//! Controls the cadence of the background enforcement loop that dispatches
+//! `MetaOp::TemporalPurge*` for collections registered with a bitemporal
+//! audit-retain window.
+
+use std::time::Duration;
+
+use serde::{Deserialize, Serialize};
+
+fn default_tick_interval_secs() -> u64 {
+    // One hour mirrors the timeseries retention loop default. Purge is
+    // always idempotent, so a rare tick is fine for bounded audit
+    // history; operators running tighter retention windows can lower
+    // this to match their SLA.
+    3_600
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BitemporalTuning {
+    /// How often the bitemporal audit-retention enforcement loop
+    /// ticks. Each tick iterates the full registry; a tick finds
+    /// nothing to do when the registry is empty or every entry's
+    /// `audit_retain_ms` is zero (retain forever), so tightening this
+    /// is cheap.
+    #[serde(default = "default_tick_interval_secs")]
+    pub tick_interval_secs: u64,
+}
+
+impl BitemporalTuning {
+    pub fn tick_interval(&self) -> Duration {
+        Duration::from_secs(self.tick_interval_secs)
+    }
+}
+
+impl Default for BitemporalTuning {
+    fn default() -> Self {
+        Self {
+            tick_interval_secs: default_tick_interval_secs(),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_one_hour() {
+        assert_eq!(BitemporalTuning::default().tick_interval_secs, 3600);
+        assert_eq!(
+            BitemporalTuning::default().tick_interval(),
+            Duration::from_secs(3600)
+        );
+    }
+
+    #[test]
+    fn override_via_toml() {
+        let t: BitemporalTuning = toml::from_str("tick_interval_secs = 60").unwrap();
+        assert_eq!(t.tick_interval_secs, 60);
+    }
+}

nodedb-types/src/config/tuning/mod.rs

@@ -1,10 +1,12 @@
+mod bitemporal;
 mod data_plane;
 mod engines;
 mod memory;
 mod network;
 mod scheduler;
 mod shutdown;
 
+pub use bitemporal::BitemporalTuning;
 pub use data_plane::{DataPlaneTuning, QueryTuning};
 pub use engines::{
     DEFAULT_MAX_DEPTH, DEFAULT_MAX_VISITED, GraphTuning, KvTuning, SparseTuning, TimeseriesToning,
@@ -51,6 +53,17 @@ pub struct TuningConfig {
     pub scheduler: SchedulerTuning,
     #[serde(default)]
     pub shutdown: ShutdownTuning,
+    #[serde(default)]
+    pub bitemporal: BitemporalTuning,
+}
+
+impl TuningConfig {
+    /// Tick interval for the bitemporal audit-retention enforcement loop.
+    /// Returns `None` when the operator wants the loop default; returns
+    /// `Some(d)` when `[tuning.bitemporal] tick_interval_secs` is set.
+    pub fn bitemporal_retention_tick(&self) -> Option<std::time::Duration> {
+        Some(self.bitemporal.tick_interval())
+    }
 }
 
 #[cfg(test)]