Tracing zipper

Cargo.toml

@@ -9,7 +9,7 @@ repository = "https://github.com/adam-Vandervorst/pathMap/"
 keywords = ["trie", "MORK", "path", "algebra"]
 categories = ["algorithms", "data-structures", "database-implementations"]
 readme = "README.md"
-exclude = ["target/", "benches/", "pathmap-book/", ".*"]
+exclude = ["target/", "benches/", "pathmap-book/", "tools/", ".*"]
 
 [package.metadata.docs.rs]
 rustc-args = ["-C", "target-feature=+aes,+sse2"]
@@ -19,6 +19,7 @@ name = "pathmap"
 path = "src/lib.rs"
 
 [dependencies]
+bitcode = { version = "0.6.9", optional = true }
 pathmap-derive = { version = "0.3.0", path = "./pathmap-derive" }
 maybe-dangling = "0.1.1"
 span-timing = { version = "0.1.0" }
@@ -41,6 +42,7 @@ default = ["graft_root_vals", "slim_ptrs", "serialization"]
 nightly = ["fast-slice-utils/nightly"] # Uses features in the nightly tool chain for better performance, and the allocator and coroutine APIs
 jemalloc = ["dep:tikv-jemallocator"] # Enables [jemalloc](https://jemalloc.net/) as the default allocator.  This dramatically improves scaling for write-heavy workloads and is generally recommended.  The only reason it is not the default is to avoid interference with the host application allocator.
 zipper_tracking = [] #Exports the zipper_tracking module publicly
+trace_zipper = ["dep:bitcode"] # Records zipper operations for replay and visualization
 all_dense_nodes = [] # Exclusively use the DenseByteNode type, which generally performs worse but is useful for compatibility and perf comparisons.
 arena_compact = ["dep:memmap2"]
 
@@ -151,5 +153,5 @@ name = "act_line_cache"
 required-features = ["arena_compact", "serialization"]
 
 [workspace]
-members = ["pathmap-derive", "examples/sampling", "examples/arena_compact_tests", "differential"]
+members = ["pathmap-derive", "examples/sampling", "examples/arena_compact_tests", "differential", "tools/tracer"]
 resolver = "2"

README.md

@@ -48,6 +48,8 @@ pathmap = "0.3"
 
 - `zipper_tracking`: Exports the `zipper_tracking` module publicly, allowing the host application to use the conflict-checking logic independently of zipper creation.
 
+- `trace_zipper`: Records zipper operations to buffers or files, for debugging or animated replay.
+
 - `viz`: Provide APIs to inspect and visualize pathmap trie structures.  Useful to observe structural sharing.
 
 - `random`: Provides utilities for generating random paths, tries, and zipper movements according to configurable distributions.

src/utils/debug/mod.rs

@@ -3,6 +3,9 @@
 mod diff_zipper;
 pub use diff_zipper::DiffZipper;
 
+#[cfg(feature = "trace_zipper")]
+pub mod zipper_tracing;
+
 mod morphism_debug;
 pub use morphism_debug::CatamorphismDebug;