Split index lifecycle into IndexBuilder trait for maintenance operations

Extracts directory bookkeeping and construction methods into a new IndexBuilder trait, separating maintenance operations from scientific computation logic. Migrates relevant methods to the new trait, updates module imports across obikindex, and narrows the crate's public API surface. Adds an end-to-end CLI smoke test to verify multi-index merge workflows.

src/obikindex/src/index/builder.rs

@@ -0,0 +1,93 @@
+//! Index-maintenance operations: preparing an output directory for a new
+//! index, laying out a fresh skeleton, finalizing after construction, and
+//! reading build progress. Not "scientific computation on an index" (kmer
+//! counting, distance, query — those live elsewhere), but genuine
+//! maintenance/bookkeeping around an index's own construction lifecycle —
+//! used by `merge`/`select`/`rebuild`/`reindex` (all in this crate) and by
+//! `obikindexer`'s pipeline algorithms alike.
+//!
+//! Public, and defined here rather than in `obikindexer`, precisely
+//! because it's used by `merge`/`select`/`rebuild`/`reindex` — those live
+//! *inside* `obikindex` itself, so a trait only they could reach would
+//! have to be local to this crate regardless (`obikindexer → obikindex`
+//! is the only direction this dependency ever runs). Distinct from
+//! `obikindexer::extensions::PrivateBuilder`, which stays `pub(crate)`
+//! there and covers a different set of methods — the ones exclusive to
+//! the four-stage build pipeline, never needed by `merge`/`select`/
+//! `rebuild`/`reindex`. See
+//! `DevDocMD/implementation/partition_layer_cache.md`, "(8)"/"(9)".
+
+use std::fs;
+use std::path::Path;
+
+use obisys::Reporter;
+use obisys::Stage;
+
+use crate::index::error::{OKIError, OKIResult};
+use crate::index::kmer_index::KmerIndex;
+use crate::index::meta::IndexMeta;
+use crate::index::state::{IndexState, SENTINEL_INDEXED};
+
+pub trait IndexBuilder: Sized {
+    /// Make `output` ready to receive a newly created index.
+    ///
+    /// If an index already exists there, remove it when `force` is set,
+    /// otherwise fail. A bare directory with no `index.meta` (e.g. one left
+    /// behind by a `DirLock`) is not considered a pre-existing index.
+    fn clear_output_for_create<P: AsRef<Path>>(output: P, force: bool) -> OKIResult<()>;
+
+    /// Lay out a fresh index skeleton at `output`: the root directory,
+    /// `index.meta` (from `meta`), and an empty partition layout.
+    ///
+    /// For construction paths that build partitions from scratch (`select`,
+    /// `rebuild`). `merge` bootstraps by copying a source index instead, so
+    /// it does not use this.
+    fn create_skeleton<P: AsRef<Path>>(output: P, meta: &IndexMeta) -> OKIResult<Self>;
+
+    /// Mark `output` as fully indexed, pack its column matrices, and reopen it.
+    ///
+    /// Shared tail of the `select`/`rebuild` construction paths, once their
+    /// partitions have been written.
+    fn finalize_indexed<P: AsRef<Path>>(output: P, rep: &mut Reporter) -> OKIResult<Self>;
+
+    /// Current construction state, as reported by sentinel files on disk.
+    fn state(&self) -> IndexState;
+}
+
+impl IndexBuilder for KmerIndex {
+    fn clear_output_for_create<P: AsRef<Path>>(output: P, force: bool) -> OKIResult<()> {
+        let output = output.as_ref();
+        if Self::exists(output) {
+            if force {
+                fs::remove_dir_all(output).map_err(OKIError::Io)?;
+            } else {
+                return Err(OKIError::Io(std::io::Error::new(
+                    std::io::ErrorKind::AlreadyExists,
+                    format!("{}: output directory already exists", output.display()),
+                )));
+            }
+        }
+        Ok(())
+    }
+
+    fn create_skeleton<P: AsRef<Path>>(output: P, meta: &IndexMeta) -> OKIResult<Self> {
+        let output = output.as_ref();
+        fs::create_dir_all(output).map_err(OKIError::Io)?;
+        meta.write(output).map_err(OKIError::Io)?;
+        Ok(KmerIndex { root_path: output.to_owned(), meta: meta.clone() })
+    }
+
+    fn finalize_indexed<P: AsRef<Path>>(output: P, rep: &mut Reporter) -> OKIResult<Self> {
+        let output = output.as_ref();
+        fs::File::create(output.join(SENTINEL_INDEXED)).map_err(OKIError::Io)?;
+        let idx = KmerIndex::open(output)?;
+        let t_pack = Stage::start("pack");
+        idx.pack_matrices(false)?;
+        rep.push(t_pack.stop());
+        Ok(idx)
+    }
+
+    fn state(&self) -> IndexState {
+        IndexState::detect(&self.root_path).unwrap_or(IndexState::Empty)
+    }
+}

src/obikindex/src/index/kmer_index.rs

@@ -2,7 +2,7 @@ use std::fs;
 use std::path::{Path, PathBuf};
 
 use crate::layer::meta::PartitionMeta;
-use obisys::{Reporter, Stage, progress_bar};
+use obisys::progress_bar;
 use rayon::prelude::*;
 
 use obikseq::{set_k, set_m};
@@ -10,7 +10,6 @@ use obikseq::{set_k, set_m};
 use crate::index::common::load_meta;
 use crate::index::error::{OKIError, OKIResult};
 use crate::index::meta::{GenomeInfo, IndexConfig, IndexMeta};
-use crate::index::state::{IndexState, SENTINEL_INDEXED};
 
 pub struct KmerIndex {
     pub(crate) root_path: PathBuf,
@@ -52,61 +51,6 @@ impl KmerIndex {
         IndexMeta::exists(path.as_ref())
     }
 
-    /// Make `output` ready to receive a newly created index.
-    ///
-    /// If an index already exists there, remove it when `force` is set,
-    /// otherwise fail. A bare directory with no `index.meta` (e.g. one left
-    /// behind by a `DirLock`) is not considered a pre-existing index.
-    pub fn clear_output_for_create<P: AsRef<Path>>(output: P, force: bool) -> OKIResult<()> {
-        let output = output.as_ref();
-        if Self::exists(output) {
-            if force {
-                fs::remove_dir_all(output).map_err(OKIError::Io)?;
-            } else {
-                return Err(OKIError::Io(std::io::Error::new(
-                    std::io::ErrorKind::AlreadyExists,
-                    format!("{}: output directory already exists", output.display()),
-                )));
-            }
-        }
-        Ok(())
-    }
-
-    /// Lay out a fresh index skeleton at `output`: the root directory,
-    /// `index.meta` (from `meta`), and an empty partition layout.
-    ///
-    /// For construction paths that build partitions from scratch (`select`,
-    /// `rebuild`). `merge` bootstraps by copying a source index instead, so
-    /// it does not use this.
-    pub(crate) fn create_skeleton<P: AsRef<Path>>(output: P, meta: &IndexMeta) -> OKIResult<KmerIndex> {
-        let output = output.as_ref();
-        fs::create_dir_all(output).map_err(OKIError::Io)?;
-        meta.write(output).map_err(OKIError::Io)?;
-        Ok(KmerIndex { root_path: output.to_owned(), meta: meta.clone() })
-    }
-
-    /// Mark `output` as fully indexed, pack its column matrices, and reopen it.
-    ///
-    /// Shared tail of the `select`/`rebuild` construction paths, once their
-    /// partitions have been written.
-    pub(crate) fn finalize_indexed<P: AsRef<Path>>(
-        output: P,
-        rep: &mut Reporter,
-    ) -> OKIResult<Self> {
-        let output = output.as_ref();
-        fs::File::create(output.join(SENTINEL_INDEXED)).map_err(OKIError::Io)?;
-        let idx = KmerIndex::open(output)?;
-        let t_pack = Stage::start("pack");
-        idx.pack_matrices(false)?;
-        rep.push(t_pack.stop());
-        Ok(idx)
-    }
-
-    /// Current construction state, as reported by sentinel files on disk.
-    pub fn state(&self) -> IndexState {
-        IndexState::detect(&self.root_path).unwrap_or(IndexState::Empty)
-    }
-
     /// The index's root directory.
     pub fn root_path(&self) -> &Path {
         &self.root_path

src/obikindex/src/index/merge.rs

@@ -3,6 +3,8 @@ use std::fs;
 use std::io;
 use std::path::Path;
 
+use crate::index::builder::IndexBuilder;
+
 use obisys::{Reporter, Stage, progress_bar, spinner};
 use tracing::{debug, info};
 

src/obikindex/src/index/mod.rs

@@ -2,6 +2,7 @@ pub mod error;
 pub mod meta;
 pub mod predicate;
 pub mod state;
+mod builder;
 mod common;
 mod distance;
 mod dump;
@@ -22,6 +23,7 @@ mod select_layer;
 mod stats;
 
 pub use error::{OKIError, OKIResult};
+pub use builder::IndexBuilder;
 pub use common::olm_to_sk;
 pub use graph_pipeline::{materialize_layer, write_graph_as_unitigs};
 pub use distance::{DistanceMetric, DistanceOutput};

src/obikindex/src/index/rebuild.rs

@@ -1,5 +1,6 @@
 use std::path::Path;
 
+use crate::index::builder::IndexBuilder;
 use crate::index::{KmerFilter, MergeMode};
 use obisys::{Reporter, Stage, progress_bar};
 use tracing::info;

src/obikindex/src/index/reindex.rs

@@ -1,3 +1,4 @@
+use crate::index::builder::IndexBuilder;
 use crate::layer::{IndexMode, TypedLayer};
 use obisys::{Reporter, Stage, progress_bar};
 use std::fs;

src/obikindex/src/index/select.rs

@@ -1,5 +1,6 @@
 use std::path::Path;
 
+use crate::index::builder::IndexBuilder;
 use crate::index::OutputCol;
 use obisys::{Reporter, Stage, progress_bar};
 use tracing::info;

src/obikindex/src/lib.rs

@@ -14,9 +14,9 @@ pub mod partition;
 
 pub use index::{
     validate_label, AggOp, DistanceMetric, DistanceOutput, GenomeInfo, GroupFilterParams,
-    GroupQuorumFilter, IndexBitsPerKmer, IndexConfig, IndexMeta, IndexState, KmerDesc, KmerFilter,
-    KmerIndex, MergeMode, MetaPred, OKIError, OKIResult, OutputCol, PartitionRunner, QueryHit,
-    QueryStats, META_FILENAME, SENTINEL_COUNTED, SENTINEL_INDEXED, SENTINEL_SCATTERED,
-    materialize_layer, olm_to_sk, write_graph_as_unitigs, passes_all,
+    GroupQuorumFilter, IndexBitsPerKmer, IndexBuilder, IndexConfig, IndexMeta, IndexState,
+    KmerDesc, KmerFilter, KmerIndex, MergeMode, MetaPred, OKIError, OKIResult, OutputCol,
+    PartitionRunner, QueryHit, QueryStats, META_FILENAME, SENTINEL_COUNTED, SENTINEL_INDEXED,
+    SENTINEL_SCATTERED, materialize_layer, olm_to_sk, write_graph_as_unitigs, passes_all,
 };
 pub use index::{filter, meta};