fix: preserve persistence health across page splits

Cargo.toml

@@ -3,7 +3,7 @@ members = ["codegen", "examples", "performance_measurement", "performance_measur
 
 [package]
 name = "worktable"
-version = "1.0.0-beta.8"
+version = "1.0.0-beta.9"
 edition = "2024"
 authors = ["Handy-caT"]
 license = "MIT"
@@ -66,7 +66,7 @@ tracing = "0.1"
 url = { version = "2", optional = true }
 uuid = { version = "1.24.0", features = ["v4", "v7"] }
 walkdir = { version = "2", optional = true }
-worktable_codegen = { path = "codegen", version = "=1.0.0-beta.8" }
+worktable_codegen = { path = "codegen", version = "=1.0.0-beta.9" }
 
 [dev-dependencies]
 chrono = "0.4.43"

codegen/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "worktable_codegen"
-version = "1.0.0-beta.8"
+version = "1.0.0-beta.9"
 edition = "2024"
 license = "MIT"
 description = "Proc-macro companion crate for worktable: the worktable! macro and its derives."

codegen/src/persist_table/generator/space_file/worktable_impls.rs

@@ -10,6 +10,7 @@ impl Generator {
         let space_info_fn = self.gen_worktable_space_info_fn();
         let persisted_pk_fn = self.gen_worktable_persisted_primary_key_fn();
         let wait_for_ops_fn = self.gen_worktable_wait_for_ops_fn();
+        let persistence_monitor_fn = self.gen_worktable_persistence_monitor_fn();
         let close_fn = self.gen_worktable_close_fn();
         let persisted_data_file_size_fn = self.gen_persisted_data_file_size_fn();
 
@@ -18,6 +19,7 @@ impl Generator {
                 #space_info_fn
                 #persisted_pk_fn
                 #wait_for_ops_fn
+                #persistence_monitor_fn
                 #close_fn
                 #persisted_data_file_size_fn
             }
@@ -55,6 +57,20 @@ impl Generator {
         }
     }
 
+    fn gen_worktable_persistence_monitor_fn(&self) -> TokenStream {
+        if self.attributes.read_only {
+            quote! {}
+        } else {
+            quote! {
+                /// Returns a cloneable terminal-state monitor that does not
+                /// borrow the table and can therefore observe `close()`.
+                pub fn persistence_monitor(&self) -> PersistenceMonitor {
+                    self.1.monitor()
+                }
+            }
+        }
+    }
+
     fn gen_worktable_close_fn(&self) -> TokenStream {
         if self.attributes.read_only {
             quote! {

codegen/src/persist_table/mod.rs

@@ -78,6 +78,10 @@ mod tests {
             output.contains("fn into_worktable_with_mode"),
             "read_only should generate explicit recovery-mode conversion"
         );
+        assert!(
+            !output.contains("persistence_monitor"),
+            "read_only should not expose monitoring for a worker it does not have"
+        );
         assert!(output.contains("LoadMode :: Strict"));
     }
 
@@ -107,6 +111,7 @@ mod tests {
             output.contains("async fn into_worktable_with_mode"),
             "normal should generate explicit recovery-mode conversion"
         );
+        assert!(output.contains("fn persistence_monitor"));
         assert!(output.contains("LoadMode :: Strict"));
     }
 

src/lib.rs

@@ -36,11 +36,12 @@ pub mod prelude {
     pub use crate::persistence::{
         AcknowledgeOperation, ArtPersistenceKey, DeleteOperation, DiskConfig, DiskPersistenceEngine,
         IndexTableOfContents, InsertOperation, LoadMode, Operation, OperationId, PersistedWorkTable, PersistenceConfig,
-        PersistenceEngine, PersistenceError, PersistenceIndexCorruption, PersistenceLoadError, PersistenceResult,
-        PersistenceState, PersistenceTask, ReadOnlyPersistenceEngine, SpaceArcticIndex, SpaceCongeeIndex, SpaceData,
-        SpaceDataOps, SpaceIndex, SpaceIndexOps, SpaceIndexUnsized, SpaceLogicalIndex, SpaceLogicalIndexUnsized,
-        SpaceSecondaryIndexOps, UpdateOperation, load_persisted_state, map_index_pages_to_toc_and_general,
-        map_unsized_index_pages_to_toc_and_general, reconstruct_multi_index_nodes, validate_events,
+        PersistenceEngine, PersistenceError, PersistenceIndexCorruption, PersistenceLoadError, PersistenceMonitor,
+        PersistenceResult, PersistenceState, PersistenceTask, ReadOnlyPersistenceEngine, SpaceArcticIndex,
+        SpaceCongeeIndex, SpaceData, SpaceDataOps, SpaceIndex, SpaceIndexOps, SpaceIndexUnsized, SpaceLogicalIndex,
+        SpaceLogicalIndexUnsized, SpaceSecondaryIndexOps, UpdateOperation, load_persisted_state,
+        map_index_pages_to_toc_and_general, map_unsized_index_pages_to_toc_and_general, reconstruct_multi_index_nodes,
+        validate_events,
     };
     pub use crate::primary_key::{PrimaryKeyGenerator, PrimaryKeyGeneratorState, TablePrimaryKey};
     pub use crate::table::select::{Order, QueryParams, SelectQueryBuilder, SelectQueryExecutor};

src/persistence/mod.rs

@@ -20,7 +20,7 @@ pub use space::{
     SpaceIndexOps, SpaceIndexUnsized, SpaceLogicalIndex, SpaceLogicalIndexUnsized, SpaceSecondaryIndexOps,
     map_index_pages_to_toc_and_general, map_unsized_index_pages_to_toc_and_general, reconstruct_multi_index_nodes,
 };
-pub use task::PersistenceTask;
+pub use task::{PersistenceMonitor, PersistenceTask};
 
 mod engine;
 mod error;

src/persistence/space/index/table_of_contents.rs

@@ -113,15 +113,30 @@ where
     pub fn update_key(&mut self, old_key: &T, new_key: T)
     where
         T: Clone + Debug,
+    {
+        assert!(
+            self.try_update_key(old_key, new_key),
+            "Page with key {old_key:?} not found"
+        );
+    }
+
+    /// Updates a page identity without panicking when the old identity is
+    /// absent. Batch replay uses this checked form because an absent key is a
+    /// persistence invariant failure that must surface through `Result`.
+    pub fn try_update_key(&mut self, old_key: &T, new_key: T) -> bool
+    where
+        T: Clone,
     {
         let page = self.get_current_page_mut();
         if page.inner.update_key(old_key, new_key.clone()).is_none() {
             for page in self.pages.iter_mut() {
                 if page.inner.update_key(old_key, new_key.clone()).is_some() {
-                    return;
+                    return true;
                 }
             }
-            panic!("Page with key {old_key:?} not found");
+            false
+        } else {
+            true
         }
     }
 
@@ -229,6 +244,16 @@ mod tests {
         );
     }
 
+    #[test]
+    fn checked_update_reports_a_missing_identity_without_mutating_the_toc() {
+        let mut toc = IndexTableOfContents::<u8, 128>::new(0.into(), Arc::new(AtomicU32::new(1)));
+        toc.insert(7, 2.into());
+
+        assert!(!toc.try_update_key(&8, 9));
+        assert_eq!(toc.get(&7), Some(2.into()));
+        assert_eq!(toc.get(&9), None);
+    }
+
     #[test]
     fn insert_more_than_one_page() {
         let mut toc = IndexTableOfContents::<u8, 20>::new(0.into(), Arc::new(AtomicU32::new(0)));