Permutations and permutable sequences

AGENTS.md

@@ -10,6 +10,8 @@ Current library families are:
 
 - rank/select support over packed bit sequences;
 - positional and monotone packed integer vectors;
+- owning permutations with rebased consuming merge and permutable sequences with
+  unchanged-value consuming merge;
 - range min-max (RmM) indexes;
 - static range-minimum-query (RMQ) indexes;
 - rooted-tree encodings (LOUDS, balanced parentheses, and DFUDS);
@@ -73,7 +75,14 @@ adds Pixie context; it does not replace the shared guidance.
 
 Public data-structure families use CRTP contracts. The current contracts are
 `IntegerVectorBase`, `MonotoneIntegerVectorBase`, `RankSelectBase`, `RmMBase`,
-`pixie::rmq::RmqBase`, `TreeBase`, `StorageBase`, and `WaveletTreeBase`.
+`pixie::rmq::RmqBase`, `TreeBase`, `StorageBase`, `WaveletTreeBase`,
+`PermutationBase`, and `PermutableSequenceBase`. The latter two keep separate
+contracts in `permutation.h` and `permutable_sequence.h`, with concrete
+`Permutation` and `PermutableSequence` types in `permutations/permutation.h` and
+`permutations/sequence.h`. Their benchmark catalogs are
+`permutations/permutation_implementations.h` and
+`permutations/sequence_implementations.h`, respectively;
+`detail/sequence/` is their unsupported shared engine, not a public family.
 
 1. Define or extend the public contract in `include/pixie/<family>.h`.
    Public facade methods delegate to a clearly named `*_impl()` method on the
@@ -248,8 +257,10 @@ The registered test executables are `bit_algorithms_unittests`,
 `rank_select_unittests`, `rank_select_tests`, `benchmark_tests`, `test_rmm`,
 `tree_tests`, `wavelet_tree_tests`, `storage_tests`,
 `serialization_tests`, `integer_vector_tests`, `excess_positions_tests`,
-`excess_record_lows_tests`, and `rmq_tests`. Run an executable directly only
-when debugging a focused Google Test filter.
+`excess_record_lows_tests`, `rmq_tests`, `permutation_tests`,
+`permutable_sequence_tests`, and `bit_sequence_tests`. The last covers internal
+sequence blocks/tree/kernels and the retained mapped-block experiment. Run an
+executable directly only when debugging a focused Google Test filter.
 
 ### Test Configuration via Environment Variables
 

CMakeLists.txt

@@ -309,7 +309,25 @@ if (PIXIE_TESTS)
                 PRIVATE ${sdsl_lite_SOURCE_DIR}/include)
     endif ()
 
+    add_executable(bit_sequence_tests
+            src/tests/bit_sequence_tests.cpp
+            src/tests/packed_sequence_tests.cpp
+            src/tests/sequence_tree_kernels_tests.cpp)
+    target_link_libraries(bit_sequence_tests
+            pixie::pixie gtest_main)
+    target_compile_definitions(bit_sequence_tests
+            PRIVATE PIXIE_SEQUENCE_TREE_TESTING)
+
+    foreach (family IN ITEMS permutation permutable_sequence)
+        add_executable(${family}_tests src/tests/${family}_tests.cpp)
+        target_link_libraries(${family}_tests PRIVATE pixie::pixie gtest_main)
+        target_compile_definitions(${family}_tests PRIVATE PIXIE_SEQUENCE_TREE_TESTING)
+    endforeach ()
+
     set(PIXIE_TEST_TARGETS
+            permutation_tests
+            permutable_sequence_tests
+            bit_sequence_tests
             bit_algorithms_unittests
             rank_select_unittests
             rank_select_tests
@@ -493,7 +511,22 @@ if (PIXIE_BENCHMARKS)
             benchmark_main
             ${PIXIE_DIAGNOSTICS_LIBS})
 
+    add_executable(bit_sequence_benchmarks
+            src/benchmarks/bit_sequence_benchmarks.cpp
+            src/benchmarks/sequence_controls_benchmarks.cpp
+            src/benchmarks/sequence_tree_kernels_benchmarks.cpp)
+    target_link_libraries(bit_sequence_benchmarks
+            pixie::pixie benchmark benchmark_main)
+
+    foreach (family IN ITEMS permutation permutable_sequence)
+        add_executable(${family}_benchmarks src/benchmarks/${family}_benchmarks.cpp)
+        target_link_libraries(${family}_benchmarks PRIVATE pixie::pixie benchmark benchmark_main)
+    endforeach ()
+
     set(PIXIE_BENCHMARK_TARGETS
+            permutation_benchmarks
+            permutable_sequence_benchmarks
+            bit_sequence_benchmarks
             rank_select_benchmarks
             rmm_benchmarks
             rmm_btree_benchmarks

README.md

@@ -17,6 +17,8 @@
 - **Succinct trees**: static variants of $2$-bit per entry trees, i.e. LOUDS, DFUDS, BP (Based on Euler tour and Ferrada-Navarro style).
 - **Wavelet tree**, i.e. static structure that supposts rank/select on arbitrary finite alphabets, supports building a Huffman archieve with fast extraction of arbitrary segment.
 - Succinct **cartesian tree** and a state of the art solution to static **RMQ** (array is immutable, queries are not known in advance).
+- **Permutations**: identity construction, checked reads, rotations, and consuming rebased merge. Contract: `pixie/permutation.h`; concrete: `pixie/permutations/permutation.h`.
+- **Permutable sequences**: consuming range construction, checked immutable reads, rotations, and unchanged-value merge. Contract: `pixie/permutable_sequence.h`; concrete: `pixie/permutations/sequence.h`.
 
 ---
 

academic/AGENTS.md

@@ -75,6 +75,10 @@ quarto render index.qmd --to pdf
 quarto preview index.qmd
 ```
 
+RevealJS loads SVG figures through `<img>`, where nested external SVG references
+such as `<image href="other.svg">` may disappear even though PNG exporters resolve
+them. Keep presentation SVGs standalone by inlining all required layers.
+
 ## Conventions
 
 ### Paper Template (ACM Format)