diff --git a/include/dwarfs/filesystem_extractor.h b/include/dwarfs/filesystem_extractor.h
index a5f2a01b..83046d79 100644
--- a/include/dwarfs/filesystem_extractor.h
+++ b/include/dwarfs/filesystem_extractor.h
@@ -30,11 +30,16 @@
 
 namespace dwarfs {
 
-class filesystem_v2;
 class library_dependencies;
 class logger;
 class os_access;
 
+namespace reader {
+
+class filesystem_v2;
+
+}
+
 struct filesystem_extractor_options {
   size_t max_queued_bytes{4096};
   bool continue_on_error{false};
@@ -62,9 +67,9 @@ class filesystem_extractor {
 
   void close() { return impl_->close(); }
 
-  bool
-  extract(filesystem_v2 const& fs, filesystem_extractor_options const& opts =
-                                       filesystem_extractor_options()) {
+  bool extract(reader::filesystem_v2 const& fs,
+               filesystem_extractor_options const& opts =
+                   filesystem_extractor_options()) {
     return impl_->extract(fs, opts);
   }
 
@@ -77,7 +82,7 @@ class filesystem_extractor {
     virtual void open_stream(std::ostream& os, std::string const& format) = 0;
     virtual void open_disk(std::filesystem::path const& output) = 0;
     virtual void close() = 0;
-    virtual bool extract(filesystem_v2 const& fs,
+    virtual bool extract(reader::filesystem_v2 const& fs,
                          filesystem_extractor_options const& opts) = 0;
   };
 
diff --git a/include/dwarfs/reader/block_range.h b/include/dwarfs/reader/block_range.h
index 9a41b5da..aacfee50 100644
--- a/include/dwarfs/reader/block_range.h
+++ b/include/dwarfs/reader/block_range.h
@@ -25,7 +25,7 @@
 #include <memory>
 #include <span>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 namespace internal {
 
@@ -50,4 +50,4 @@ class block_range {
   std::shared_ptr<internal::cached_block const> block_;
 };
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/include/dwarfs/reader/filesystem_v2.h b/include/dwarfs/reader/filesystem_v2.h
index d7ad8ff7..f6bb0889 100644
--- a/include/dwarfs/reader/filesystem_v2.h
+++ b/include/dwarfs/reader/filesystem_v2.h
@@ -43,7 +43,6 @@
 
 namespace dwarfs {
 
-struct iovec_read_buf;
 struct vfs_stat;
 
 class category_resolver;
@@ -55,6 +54,10 @@ class os_access;
 class performance_monitor;
 class writer_progress;
 
+namespace reader {
+
+struct iovec_read_buf;
+
 class filesystem_v2 {
  public:
   filesystem_v2() = default;
@@ -394,4 +397,5 @@ class filesystem_v2 {
   std::unique_ptr<impl> impl_;
 };
 
+} // namespace reader
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/block_cache.h b/include/dwarfs/reader/internal/block_cache.h
index 35fa91c0..a737f347 100644
--- a/include/dwarfs/reader/internal/block_cache.h
+++ b/include/dwarfs/reader/internal/block_cache.h
@@ -45,6 +45,10 @@ namespace internal {
 
 class fs_section;
 
+}
+
+namespace reader::internal {
+
 class block_cache {
  public:
   block_cache(logger& lgr, os_access const& os, std::shared_ptr<mmif> mm,
@@ -53,7 +57,9 @@ class block_cache {
 
   size_t block_count() const { return impl_->block_count(); }
 
-  void insert(fs_section const& section) { impl_->insert(section); }
+  void insert(dwarfs::internal::fs_section const& section) {
+    impl_->insert(section);
+  }
 
   void set_block_size(size_t size) { impl_->set_block_size(size); }
 
@@ -73,7 +79,7 @@ class block_cache {
     virtual ~impl() = default;
 
     virtual size_t block_count() const = 0;
-    virtual void insert(fs_section const& section) = 0;
+    virtual void insert(dwarfs::internal::fs_section const& section) = 0;
     virtual void set_block_size(size_t size) = 0;
     virtual void set_num_workers(size_t num) = 0;
     virtual void set_tidy_config(cache_tidy_config const& cfg) = 0;
@@ -85,5 +91,5 @@ class block_cache {
   std::unique_ptr<impl> impl_;
 };
 
-} // namespace internal
+} // namespace reader::internal
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/cached_block.h b/include/dwarfs/reader/internal/cached_block.h
index 1ffa1f6c..91fcb14a 100644
--- a/include/dwarfs/reader/internal/cached_block.h
+++ b/include/dwarfs/reader/internal/cached_block.h
@@ -35,11 +35,15 @@ namespace internal {
 
 class fs_section;
 
+}
+
+namespace reader::internal {
+
 class cached_block {
  public:
   static std::unique_ptr<cached_block>
-  create(logger& lgr, fs_section const& b, std::shared_ptr<mmif> mm,
-         bool release, bool disable_integrity_check);
+  create(logger& lgr, dwarfs::internal::fs_section const& b,
+         std::shared_ptr<mmif> mm, bool release, bool disable_integrity_check);
 
   virtual ~cached_block() = default;
 
@@ -53,6 +57,6 @@ class cached_block {
   virtual bool any_pages_swapped_out(std::vector<uint8_t>& tmp) const = 0;
 };
 
-} // namespace internal
+} // namespace reader::internal
 
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/filesystem_parser.h b/include/dwarfs/reader/internal/filesystem_parser.h
index 9c4791a6..8ab06a59 100644
--- a/include/dwarfs/reader/internal/filesystem_parser.h
+++ b/include/dwarfs/reader/internal/filesystem_parser.h
@@ -36,7 +36,7 @@ namespace dwarfs {
 
 class mmif;
 
-namespace internal {
+namespace reader::internal {
 
 class filesystem_parser {
  private:
@@ -48,7 +48,7 @@ class filesystem_parser {
   explicit filesystem_parser(std::shared_ptr<mmif> mm,
                              file_off_t image_offset = 0);
 
-  std::optional<fs_section> next_section();
+  std::optional<dwarfs::internal::fs_section> next_section();
 
   std::optional<std::span<uint8_t const>> header() const;
 
@@ -77,6 +77,6 @@ class filesystem_parser {
   std::vector<uint64_t> index_;
 };
 
-} // namespace internal
+} // namespace reader::internal
 
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/inode_reader_v2.h b/include/dwarfs/reader/internal/inode_reader_v2.h
index 85a39b4f..5454a707 100644
--- a/include/dwarfs/reader/internal/inode_reader_v2.h
+++ b/include/dwarfs/reader/internal/inode_reader_v2.h
@@ -42,7 +42,7 @@ struct inode_reader_options;
 struct iovec_read_buf;
 class performance_monitor;
 
-namespace internal {
+namespace reader::internal {
 
 class inode_reader_v2 {
  public:
@@ -116,5 +116,5 @@ class inode_reader_v2 {
   std::unique_ptr<impl> impl_;
 };
 
-} // namespace internal
+} // namespace reader::internal
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/metadata_types.h b/include/dwarfs/reader/internal/metadata_types.h
index 3ee6268f..c1b3904f 100644
--- a/include/dwarfs/reader/internal/metadata_types.h
+++ b/include/dwarfs/reader/internal/metadata_types.h
@@ -42,7 +42,7 @@ namespace dwarfs {
 
 class logger;
 
-namespace internal {
+namespace reader::internal {
 
 template <typename T>
 class metadata_;
@@ -62,7 +62,7 @@ class global_metadata {
   uint32_t first_dir_entry(uint32_t ino) const;
   uint32_t parent_dir_entry(uint32_t ino) const;
 
-  string_table const& names() const { return names_; }
+  dwarfs::internal::string_table const& names() const { return names_; }
 
   std::vector<thrift::metadata::directory> const& directories() const {
     return directories_storage_;
@@ -72,7 +72,7 @@ class global_metadata {
   Meta const& meta_;
   std::vector<thrift::metadata::directory> const directories_storage_;
   thrift::metadata::directory const* const directories_;
-  string_table const names_;
+  dwarfs::internal::string_table const names_;
 };
 
 class inode_view_impl
@@ -240,6 +240,6 @@ class chunk_range {
   uint32_t end_{0};
 };
 
-} // namespace internal
+} // namespace reader::internal
 
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/metadata_v2.h b/include/dwarfs/reader/internal/metadata_v2.h
index bec8aff9..9635149e 100644
--- a/include/dwarfs/reader/internal/metadata_v2.h
+++ b/include/dwarfs/reader/internal/metadata_v2.h
@@ -54,7 +54,7 @@ namespace thrift::metadata {
 class metadata;
 }
 
-namespace internal {
+namespace reader::internal {
 
 class metadata_v2 {
  public:
@@ -245,5 +245,5 @@ class metadata_v2 {
   std::unique_ptr<impl> impl_;
 };
 
-} // namespace internal
+} // namespace reader::internal
 } // namespace dwarfs
diff --git a/include/dwarfs/reader/internal/offset_cache.h b/include/dwarfs/reader/internal/offset_cache.h
index 8b60efd9..4a9987ca 100644
--- a/include/dwarfs/reader/internal/offset_cache.h
+++ b/include/dwarfs/reader/internal/offset_cache.h
@@ -33,7 +33,7 @@
 
 #include <dwarfs/small_vector.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
 
 template <typename InodeT, typename FileOffsetT, typename ChunkIndexT,
           size_t ChunkIndexInterval, size_t UpdaterMaxInlineOffsets>
@@ -204,4 +204,4 @@ class basic_offset_cache {
   std::mutex mutable mx_;
 };
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/include/dwarfs/reader/iovec_read_buf.h b/include/dwarfs/reader/iovec_read_buf.h
index 1a2d14c7..17817773 100644
--- a/include/dwarfs/reader/iovec_read_buf.h
+++ b/include/dwarfs/reader/iovec_read_buf.h
@@ -28,7 +28,7 @@
 #include <dwarfs/reader/block_range.h>
 #include <dwarfs/small_vector.h>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 #ifdef _WIN32
 struct dwarfs_iovec {
@@ -52,4 +52,4 @@ struct iovec_read_buf {
   small_vector<block_range, inline_storage> ranges;
 };
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/include/dwarfs/reader/metadata_types.h b/include/dwarfs/reader/metadata_types.h
index 27aaaa21..ad4c9ad8 100644
--- a/include/dwarfs/reader/metadata_types.h
+++ b/include/dwarfs/reader/metadata_types.h
@@ -32,7 +32,7 @@
 #include <dwarfs/file_stat.h>
 #include <dwarfs/file_type.h>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 namespace internal {
 
@@ -133,4 +133,4 @@ class directory_view {
   internal::global_metadata const* g_;
 };
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/src/dwarfs/filesystem_extractor.cpp b/src/dwarfs/filesystem_extractor.cpp
index 9c45f1b4..161134c7 100644
--- a/src/dwarfs/filesystem_extractor.cpp
+++ b/src/dwarfs/filesystem_extractor.cpp
@@ -176,7 +176,7 @@ class filesystem_extractor_ final : public filesystem_extractor::impl {
     closefd(pipefd_[0]);
   }
 
-  bool extract(filesystem_v2 const& fs,
+  bool extract(reader::filesystem_v2 const& fs,
                filesystem_extractor_options const& opts) override;
 
  private:
@@ -234,7 +234,7 @@ class filesystem_extractor_ final : public filesystem_extractor::impl {
 
 template <typename LoggerPolicy>
 bool filesystem_extractor_<LoggerPolicy>::extract(
-    filesystem_v2 const& fs, filesystem_extractor_options const& opts) {
+    reader::filesystem_v2 const& fs, filesystem_extractor_options const& opts) {
   DWARFS_CHECK(a_, "filesystem not opened");
 
   auto lr = ::archive_entry_linkresolver_new();
@@ -264,7 +264,7 @@ bool filesystem_extractor_<LoggerPolicy>::extract(
   uint64_t const bytes_total{vfs.blocks};
 
   auto do_archive = [&](::archive_entry* ae,
-                        inode_view entry) { // TODO: inode vs. entry
+                        reader::inode_view entry) { // TODO: inode vs. entry
     if (auto size = ::archive_entry_size(ae);
         entry.is_regular_file() && size > 0) {
       auto fd = fs.open(entry);
diff --git a/src/dwarfs/reader/block_range.cpp b/src/dwarfs/reader/block_range.cpp
index 8fe40398..5ee8c808 100644
--- a/src/dwarfs/reader/block_range.cpp
+++ b/src/dwarfs/reader/block_range.cpp
@@ -26,7 +26,7 @@
 
 #include <dwarfs/reader/internal/cached_block.h>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 block_range::block_range(uint8_t const* data, size_t offset, size_t size)
     : span_{data + offset, size} {
@@ -49,4 +49,4 @@ block_range::block_range(std::shared_ptr<internal::cached_block const> block,
   }
 }
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/src/dwarfs/reader/filesystem_v2.cpp b/src/dwarfs/reader/filesystem_v2.cpp
index fd71e003..3176a29d 100644
--- a/src/dwarfs/reader/filesystem_v2.cpp
+++ b/src/dwarfs/reader/filesystem_v2.cpp
@@ -57,10 +57,12 @@
 #include <dwarfs/reader/internal/inode_reader_v2.h>
 #include <dwarfs/reader/internal/metadata_v2.h>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 namespace internal {
 
+using namespace dwarfs::internal;
+
 namespace {
 
 void check_section_logger(logger& lgr, fs_section const& section) {
@@ -1228,4 +1230,4 @@ filesystem_v2::header(std::shared_ptr<mmif> mm, file_off_t image_offset) {
   return internal::filesystem_parser(mm, image_offset).header();
 }
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/src/dwarfs/reader/internal/block_cache.cpp b/src/dwarfs/reader/internal/block_cache.cpp
index d35d2e6c..b6617b70 100644
--- a/src/dwarfs/reader/internal/block_cache.cpp
+++ b/src/dwarfs/reader/internal/block_cache.cpp
@@ -53,7 +53,9 @@
 #include <dwarfs/reader/internal/block_cache.h>
 #include <dwarfs/reader/internal/cached_block.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
+
+using namespace dwarfs::internal;
 
 namespace {
 
@@ -147,7 +149,7 @@ class block_request {
 
   size_t end() const { return end_; }
 
-  void fulfill(std::shared_ptr<internal::cached_block const> block) {
+  void fulfill(std::shared_ptr<cached_block const> block) {
     promise_.set_value(block_range(std::move(block), begin_, end_ - begin_));
   }
 
@@ -161,8 +163,7 @@ class block_request {
 
 class block_request_set {
  public:
-  block_request_set(std::shared_ptr<internal::cached_block> block,
-                    size_t block_no)
+  block_request_set(std::shared_ptr<cached_block> block, size_t block_no)
       : range_end_(0)
       , block_(std::move(block))
       , block_no_(block_no) {}
@@ -198,14 +199,14 @@ class block_request_set {
 
   bool empty() const { return queue_.empty(); }
 
-  std::shared_ptr<internal::cached_block> block() const { return block_; }
+  std::shared_ptr<cached_block> block() const { return block_; }
 
   size_t block_no() const { return block_no_; }
 
  private:
   std::vector<block_request> queue_;
   size_t range_end_;
-  std::shared_ptr<internal::cached_block> block_;
+  std::shared_ptr<cached_block> block_;
   const size_t block_no_;
 };
 
@@ -230,11 +231,11 @@ class block_cache_ final : public block_cache::impl {
       , os_{os}
       , options_(options) {
     if (options.init_workers) {
-      wg_ = internal::worker_group(lgr, os_, "blkcache",
-                                   std::max(options.num_workers > 0
-                                                ? options.num_workers
-                                                : hardware_concurrency(),
-                                            static_cast<size_t>(1)));
+      wg_ = worker_group(lgr, os_, "blkcache",
+                         std::max(options.num_workers > 0
+                                      ? options.num_workers
+                                      : hardware_concurrency(),
+                                  static_cast<size_t>(1)));
     }
   }
 
@@ -329,8 +330,7 @@ class block_cache_ final : public block_cache::impl {
     cache_.~lru_type();
     new (&cache_) lru_type(max_blocks);
     cache_.setPruneHook(
-        [this](size_t block_no,
-               std::shared_ptr<internal::cached_block>&& block) {
+        [this](size_t block_no, std::shared_ptr<cached_block>&& block) {
           LOG_DEBUG << "evicting block " << block_no
                     << " from cache, decompression ratio = "
                     << double(block->range_end()) /
@@ -347,7 +347,7 @@ class block_cache_ final : public block_cache::impl {
       wg_.stop();
     }
 
-    wg_ = internal::worker_group(LOG_GET_LOGGER, os_, "blkcache", num);
+    wg_ = worker_group(LOG_GET_LOGGER, os_, "blkcache", num);
   }
 
   void set_tidy_config(cache_tidy_config const& cfg) override {
@@ -555,10 +555,9 @@ class block_cache_ final : public block_cache::impl {
   void create_cached_block(size_t block_no, std::promise<block_range>&& promise,
                            size_t offset, size_t range_end) const {
     try {
-      std::shared_ptr<internal::cached_block> block =
-          internal::cached_block::create(
-              LOG_GET_LOGGER, DWARFS_NOTHROW(block_.at(block_no)), mm_,
-              options_.mm_release, options_.disable_block_integrity_check);
+      std::shared_ptr<cached_block> block = cached_block::create(
+          LOG_GET_LOGGER, DWARFS_NOTHROW(block_.at(block_no)), mm_,
+          options_.mm_release, options_.disable_block_integrity_check);
       blocks_created_.fetch_add(1, std::memory_order_relaxed);
 
       // Make a new set for the block
@@ -586,7 +585,7 @@ class block_cache_ final : public block_cache::impl {
     tidy_thread_.join();
   }
 
-  void update_block_stats(internal::cached_block const& cb) {
+  void update_block_stats(cached_block const& cb) {
     if (cb.range_end() < cb.uncompressed_size()) {
       partially_decompressed_.fetch_add(1, std::memory_order_relaxed);
     }
@@ -729,16 +728,16 @@ class block_cache_ final : public block_cache::impl {
           std::cv_status::timeout) {
         switch (tidy_config_.strategy) {
         case cache_tidy_strategy::EXPIRY_TIME:
-          remove_block_if([tp = std::chrono::steady_clock::now() -
-                                tidy_config_.expiry_time](
-                              internal::cached_block const& blk) {
-            return blk.last_used_before(tp);
-          });
+          remove_block_if(
+              [tp = std::chrono::steady_clock::now() -
+                    tidy_config_.expiry_time](cached_block const& blk) {
+                return blk.last_used_before(tp);
+              });
           break;
 
         case cache_tidy_strategy::BLOCK_SWAPPED_OUT: {
           std::vector<uint8_t> tmp;
-          remove_block_if([&tmp](internal::cached_block const& blk) {
+          remove_block_if([&tmp](cached_block const& blk) {
             return blk.any_pages_swapped_out(tmp);
           });
         } break;
@@ -751,7 +750,7 @@ class block_cache_ final : public block_cache::impl {
   }
 
   using lru_type =
-      folly::EvictingCacheMap<size_t, std::shared_ptr<internal::cached_block>>;
+      folly::EvictingCacheMap<size_t, std::shared_ptr<cached_block>>;
 
   mutable std::mutex mx_;
   mutable lru_type cache_;
@@ -783,7 +782,7 @@ class block_cache_ final : public block_cache::impl {
   mutable folly::Histogram<size_t> active_set_size_{1, 0, 1024};
 
   mutable std::shared_mutex mx_wg_;
-  mutable internal::worker_group wg_;
+  mutable worker_group wg_;
   std::vector<fs_section> block_;
   std::shared_ptr<mmif> mm_;
   LOG_PROXY_DECL(LoggerPolicy);
@@ -806,4 +805,4 @@ block_cache::block_cache(logger& lgr, os_access const& os,
     : impl_(make_unique_logging_object<impl, block_cache_, logger_policies>(
           lgr, os, std::move(mm), options, std::move(perfmon))) {}
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/internal/cached_block.cpp b/src/dwarfs/reader/internal/cached_block.cpp
index d87e0844..d68d424c 100644
--- a/src/dwarfs/reader/internal/cached_block.cpp
+++ b/src/dwarfs/reader/internal/cached_block.cpp
@@ -33,7 +33,9 @@
 #include <dwarfs/internal/fs_section.h>
 #include <dwarfs/reader/internal/cached_block.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
+
+using namespace dwarfs::internal;
 
 namespace {
 
@@ -140,4 +142,4 @@ cached_block::create(logger& lgr, fs_section const& b, std::shared_ptr<mmif> mm,
       lgr, b, std::move(mm), release, disable_integrity_check);
 }
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/internal/filesystem_parser.cpp b/src/dwarfs/reader/internal/filesystem_parser.cpp
index 111332ae..5a59f5c3 100644
--- a/src/dwarfs/reader/internal/filesystem_parser.cpp
+++ b/src/dwarfs/reader/internal/filesystem_parser.cpp
@@ -31,7 +31,9 @@
 
 #include <dwarfs/reader/internal/filesystem_parser.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
+
+using namespace dwarfs::internal;
 
 file_off_t
 filesystem_parser::find_image_offset(mmif& mm, file_off_t image_offset) {
@@ -208,4 +210,4 @@ void filesystem_parser::find_index() {
   }
 }
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/internal/inode_reader_v2.cpp b/src/dwarfs/reader/internal/inode_reader_v2.cpp
index 0efa7990..baa13e73 100644
--- a/src/dwarfs/reader/internal/inode_reader_v2.cpp
+++ b/src/dwarfs/reader/internal/inode_reader_v2.cpp
@@ -44,7 +44,7 @@
 #include <dwarfs/reader/internal/inode_reader_v2.h>
 #include <dwarfs/reader/internal/offset_cache.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
 
 namespace {
 
@@ -459,4 +459,4 @@ inode_reader_v2::inode_reader_v2(
                                        logger_policies>(
           lgr, std::move(bc), opts, std::move(perfmon))) {}
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/internal/metadata_types.cpp b/src/dwarfs/reader/internal/metadata_types.cpp
index 9e42a3df..31e59ce2 100644
--- a/src/dwarfs/reader/internal/metadata_types.cpp
+++ b/src/dwarfs/reader/internal/metadata_types.cpp
@@ -35,7 +35,9 @@
 
 #include <dwarfs/gen-cpp2/metadata_types_custom_protocol.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
+
+using namespace dwarfs::internal;
 
 namespace {
 
@@ -750,4 +752,4 @@ void dir_entry_view_impl::append_to(std::filesystem::path& p) const {
   }
 }
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/internal/metadata_v2.cpp b/src/dwarfs/reader/internal/metadata_v2.cpp
index 1a8daf1e..f1581357 100644
--- a/src/dwarfs/reader/internal/metadata_v2.cpp
+++ b/src/dwarfs/reader/internal/metadata_v2.cpp
@@ -63,8 +63,9 @@
 
 #include <thrift/lib/thrift/gen-cpp2/frozen_types_custom_protocol.h>
 
-namespace dwarfs::internal {
+namespace dwarfs::reader::internal {
 
+using namespace dwarfs::internal;
 namespace fs = std::filesystem;
 
 namespace {
@@ -1870,4 +1871,4 @@ metadata_v2::metadata_v2(logger& lgr, std::span<uint8_t const> schema,
           lgr, schema, data, options, inode_offset, force_consistency_check,
           std::move(perfmon))) {}
 
-} // namespace dwarfs::internal
+} // namespace dwarfs::reader::internal
diff --git a/src/dwarfs/reader/metadata_types.cpp b/src/dwarfs/reader/metadata_types.cpp
index e5c11604..2bc1e7ed 100644
--- a/src/dwarfs/reader/metadata_types.cpp
+++ b/src/dwarfs/reader/metadata_types.cpp
@@ -34,7 +34,7 @@
 
 #include <dwarfs/reader/internal/metadata_types.h>
 
-namespace dwarfs {
+namespace dwarfs::reader {
 
 inode_view::mode_type inode_view::mode() const { return iv_->mode(); }
 
@@ -121,4 +121,4 @@ uint32_t directory_view::parent_inode() const {
   return ent;
 }
 
-} // namespace dwarfs
+} // namespace dwarfs::reader
diff --git a/src/dwarfs_main.cpp b/src/dwarfs_main.cpp
index 7ad05d51..ed026a93 100644
--- a/src/dwarfs_main.cpp
+++ b/src/dwarfs_main.cpp
@@ -202,7 +202,7 @@ struct dwarfs_userdata {
   std::filesystem::path progname;
   options opts;
   stream_logger lgr;
-  filesystem_v2 fs;
+  reader::filesystem_v2 fs;
   iolayer const& iol;
   std::shared_ptr<performance_monitor> perfmon;
   PERFMON_EXT_PROXY_DECL
@@ -514,7 +514,7 @@ int op_readlink_common(LogProxy& log_, dwarfs_userdata& userdata,
   return checked_call(log_, [&] {
     if (auto entry = find()) {
       std::error_code ec;
-      auto link = userdata.fs.readlink(*entry, readlink_mode::unix, ec);
+      auto link = userdata.fs.readlink(*entry, reader::readlink_mode::unix, ec);
       if (!ec) {
         *str = link;
       }
@@ -662,7 +662,7 @@ void op_read(fuse_req_t req, fuse_ino_t ino, size_t size, file_off_t off,
     }
 
     std::error_code ec;
-    iovec_read_buf buf;
+    reader::iovec_read_buf buf;
     auto num = userdata.fs.readv(ino, buf, size, off, ec);
 
     LOG_DEBUG << "readv(" << ino << ", " << size << ", " << off << ") -> "
@@ -707,7 +707,7 @@ class readdir_lowlevel_policy {
     buf_.resize(size);
   }
 
-  auto find(filesystem_v2& fs) const { return fs.find(ino_); }
+  auto find(reader::filesystem_v2& fs) const { return fs.find(ino_); }
 
   bool keep_going() const { return written_ < buf_.size(); }
 
@@ -742,7 +742,7 @@ class readdir_policy {
       , buf_{buf}
       , filler_{filler} {}
 
-  auto find(filesystem_v2& fs) const { return fs.find(path_); }
+  auto find(reader::filesystem_v2& fs) const { return fs.find(path_); }
 
   bool keep_going() const { return true; }
 
@@ -761,7 +761,7 @@ class readdir_policy {
 #endif
 
 template <typename Policy, typename OnInode>
-int op_readdir_common(filesystem_v2& fs, Policy& policy, file_off_t off,
+int op_readdir_common(reader::filesystem_v2& fs, Policy& policy, file_off_t off,
                       OnInode&& on_inode) {
   auto dirent = policy.find(fs);
 
@@ -822,7 +822,7 @@ void op_readdir(fuse_req_t req, fuse_ino_t ino, size_t size, file_off_t off,
 
   checked_reply_err(log_, req, [&] {
     readdir_lowlevel_policy policy{req, ino, size};
-    return op_readdir_common(userdata.fs, policy, off, [](inode_view) {});
+    return op_readdir_common(userdata.fs, policy, off, [](auto) {});
   });
 }
 #else
@@ -838,7 +838,7 @@ int op_readdir(char const* path, void* buf, fuse_fill_dir_t filler,
 
   return -checked_call(log_, [&] {
     readdir_policy policy{path, buf, filler};
-    return op_readdir_common(userdata.fs, policy, off, [&](inode_view e) {
+    return op_readdir_common(userdata.fs, policy, off, [&](auto e) {
       PERFMON_SET_CONTEXT(e.inode_num())
     });
   });
@@ -1462,8 +1462,8 @@ void load_filesystem(dwarfs_userdata& userdata) {
 
   LOG_DEBUG << "attempting to load filesystem from " << fsimage;
 
-  userdata.fs = filesystem_v2(userdata.lgr, *userdata.iol.os, fsimage, fsopts,
-                              userdata.perfmon);
+  userdata.fs = reader::filesystem_v2(userdata.lgr, *userdata.iol.os, fsimage,
+                                      fsopts, userdata.perfmon);
 
   ti << "file system initialized";
 }
diff --git a/src/dwarfsck_main.cpp b/src/dwarfsck_main.cpp
index d1dabcdf..16b38f14 100644
--- a/src/dwarfsck_main.cpp
+++ b/src/dwarfsck_main.cpp
@@ -57,7 +57,8 @@ namespace po = boost::program_options;
 
 namespace {
 
-void do_list_files(filesystem_v2& fs, iolayer const& iol, bool verbose) {
+void do_list_files(reader::filesystem_v2& fs, iolayer const& iol,
+                   bool verbose) {
   auto max_width = [](auto const& vec) {
     auto max = std::max_element(vec.begin(), vec.end());
     return std::to_string(*max).size();
@@ -102,7 +103,7 @@ void do_list_files(filesystem_v2& fs, iolayer const& iol, bool verbose) {
   });
 }
 
-void do_checksum(logger& lgr, filesystem_v2& fs, iolayer const& iol,
+void do_checksum(logger& lgr, reader::filesystem_v2& fs, iolayer const& iol,
                  std::string const& algo, size_t num_workers) {
   LOG_PROXY(debug_logger_policy, lgr);
 
@@ -292,7 +293,7 @@ int dwarfsck_main(int argc, sys_char** argv, iolayer const& iol) {
     std::shared_ptr<mmif> mm = iol.os->map_file(input_path);
 
     if (print_header) {
-      if (auto hdr = filesystem_v2::header(mm, fsopts.image_offset)) {
+      if (auto hdr = reader::filesystem_v2::header(mm, fsopts.image_offset)) {
         ensure_binary_mode(iol.out);
         iol.out.write(reinterpret_cast<char const*>(hdr->data()), hdr->size());
         if (iol.out.bad() || iol.out.fail()) {
@@ -304,7 +305,7 @@ int dwarfsck_main(int argc, sys_char** argv, iolayer const& iol) {
         return 2;
       }
     } else {
-      filesystem_v2 fs(lgr, *iol.os, mm, fsopts);
+      reader::filesystem_v2 fs(lgr, *iol.os, mm, fsopts);
 
       if (!export_metadata.empty()) {
         std::error_code ec;
diff --git a/src/dwarfsextract_main.cpp b/src/dwarfsextract_main.cpp
index 8c1830f5..f5b8bc11 100644
--- a/src/dwarfsextract_main.cpp
+++ b/src/dwarfsextract_main.cpp
@@ -164,7 +164,7 @@ int dwarfsextract_main(int argc, sys_char** argv, iolayer const& iol) {
     std::shared_ptr<performance_monitor> perfmon = performance_monitor::create(
         perfmon_enabled, iol.file, perfmon_trace_file);
 
-    filesystem_v2 fs(lgr, *iol.os, fs_image, fsopts, perfmon);
+    reader::filesystem_v2 fs(lgr, *iol.os, fs_image, fsopts, perfmon);
     filesystem_extractor fsx(lgr, *iol.os);
 
     if (format.empty()) {
diff --git a/src/mkdwarfs_main.cpp b/src/mkdwarfs_main.cpp
index d348b805..f8f66429 100644
--- a/src/mkdwarfs_main.cpp
+++ b/src/mkdwarfs_main.cpp
@@ -1159,7 +1159,7 @@ int mkdwarfs_main(int argc, sys_char** argv, iolayer const& iol) {
     }
   }
 
-  std::optional<filesystem_v2> input_filesystem;
+  std::optional<reader::filesystem_v2> input_filesystem;
   std::shared_ptr<category_resolver> cat_resolver;
 
   if (recompress) {
diff --git a/test/badfs_test.cpp b/test/badfs_test.cpp
index 03e02a13..cb4d44b7 100644
--- a/test/badfs_test.cpp
+++ b/test/badfs_test.cpp
@@ -62,9 +62,9 @@ TEST_P(bad_fs, test) {
   int nerror = 0;
 
   try {
-    nerror = filesystem_v2::identify(lgr, os, std::make_shared<mmap>(filename),
-                                     oss, 9, 1, true,
-                                     filesystem_options::IMAGE_OFFSET_AUTO);
+    nerror = reader::filesystem_v2::identify(
+        lgr, os, std::make_shared<mmap>(filename), oss, 9, 1, true,
+        filesystem_options::IMAGE_OFFSET_AUTO);
   } catch (std::exception const&) {
     nerror = 1;
   }
diff --git a/test/block_cache_test.cpp b/test/block_cache_test.cpp
index b6540210..574dddcd 100644
--- a/test/block_cache_test.cpp
+++ b/test/block_cache_test.cpp
@@ -48,7 +48,7 @@ using namespace dwarfs;
 
 namespace {
 
-class mock_cached_block : public internal::cached_block {
+class mock_cached_block : public reader::internal::cached_block {
  public:
   mock_cached_block() = default;
   mock_cached_block(std::span<uint8_t const> span)
@@ -79,19 +79,19 @@ TEST(block_range, uncompressed) {
   std::iota(data.begin(), data.end(), 0);
 
   {
-    block_range range{data.data(), 0, data.size()};
+    reader::block_range range{data.data(), 0, data.size()};
     EXPECT_EQ(range.data(), data.data());
     EXPECT_EQ(range.size(), 100);
     EXPECT_TRUE(std::equal(range.begin(), range.end(), data.begin()));
   }
 
   {
-    block_range range{data.data(), 10, 20};
+    reader::block_range range{data.data(), 10, 20};
     EXPECT_EQ(range.size(), 20);
     EXPECT_TRUE(std::equal(range.begin(), range.end(), data.begin() + 10));
   }
 
-  EXPECT_THAT([] { block_range range(nullptr, 0, 0); },
+  EXPECT_THAT([] { reader::block_range range(nullptr, 0, 0); },
               ::testing::ThrowsMessage<dwarfs::runtime_error>(
                   ::testing::HasSubstr("block_range: block data is null")));
 }
@@ -102,7 +102,7 @@ TEST(block_range, compressed) {
 
   {
     auto block = std::make_shared<mock_cached_block>(data);
-    block_range range{block, 0, data.size()};
+    reader::block_range range{block, 0, data.size()};
     EXPECT_EQ(range.data(), data.data());
     EXPECT_EQ(range.size(), 100);
     EXPECT_TRUE(std::equal(range.begin(), range.end(), data.begin()));
@@ -110,7 +110,7 @@ TEST(block_range, compressed) {
 
   {
     auto block = std::make_shared<mock_cached_block>(data);
-    block_range range{block, 10, 20};
+    reader::block_range range{block, 10, 20};
     EXPECT_EQ(range.size(), 20);
     EXPECT_TRUE(std::equal(range.begin(), range.end(), data.begin() + 10));
   }
@@ -118,7 +118,7 @@ TEST(block_range, compressed) {
   EXPECT_THAT(
       [] {
         auto block = std::make_shared<mock_cached_block>();
-        block_range range(block, 0, 0);
+        reader::block_range range(block, 0, 0);
       },
       ::testing::ThrowsMessage<dwarfs::runtime_error>(
           ::testing::HasSubstr("block_range: block data is null")));
@@ -126,7 +126,7 @@ TEST(block_range, compressed) {
   EXPECT_THAT(
       [&] {
         auto block = std::make_shared<mock_cached_block>(data);
-        block_range range(block, 100, 1);
+        reader::block_range range(block, 100, 1);
       },
       ::testing::ThrowsMessage<dwarfs::runtime_error>(
           ::testing::HasSubstr("block_range: size out of range (101 > 100)")));
@@ -183,7 +183,7 @@ TEST_P(options_test, cache_stress) {
   filesystem_options opts{
       .block_cache = cache_opts,
   };
-  filesystem_v2 fs(lgr, *os, mm, opts);
+  reader::filesystem_v2 fs(lgr, *os, mm, opts);
 
   EXPECT_NO_THROW(
       fs.set_cache_tidy_config({.strategy = cache_tidy_strategy::NONE}));
@@ -210,14 +210,14 @@ TEST_P(options_test, cache_stress) {
       .expiry_time = std::chrono::milliseconds(2),
   });
 
-  std::vector<inode_view> inodes;
+  std::vector<reader::inode_view> inodes;
 
   fs.walk([&](auto e) { inodes.push_back(e.inode()); });
 
   std::uniform_int_distribution<size_t> inode_dist(0, inodes.size() - 1);
 
   struct read_request {
-    inode_view inode;
+    reader::inode_view inode;
     size_t offset;
     size_t size;
   };
diff --git a/test/compat_test.cpp b/test/compat_test.cpp
index 3cd5365c..fb391019 100644
--- a/test/compat_test.cpp
+++ b/test/compat_test.cpp
@@ -812,7 +812,7 @@ file_stat make_stat(posix_file_type::value type, file_stat::perms_type perms,
   return st;
 }
 
-void check_compat(logger& lgr, filesystem_v2 const& fs,
+void check_compat(logger& lgr, reader::filesystem_v2 const& fs,
                   std::string const& version) {
   bool has_devices = not(version == "0.2.0" or version == "0.2.3");
   bool has_ac_time = version == "0.2.0" or version == "0.2.3";
@@ -862,7 +862,7 @@ void check_compat(logger& lgr, filesystem_v2 const& fs,
 
   entry = fs.find("/foo/bad");
   ASSERT_TRUE(entry);
-  auto link = fs.readlink(*entry, readlink_mode::raw);
+  auto link = fs.readlink(*entry, reader::readlink_mode::raw);
   EXPECT_EQ(link, "../foo");
 
   entry = fs.find(0, "foo");
@@ -949,11 +949,12 @@ void check_compat(logger& lgr, filesystem_v2 const& fs,
     foo.set_size(foo.size() - 1);
   }
 
-  for (auto mp : {&filesystem_v2::walk, &filesystem_v2::walk_data_order}) {
+  for (auto mp : {&reader::filesystem_v2::walk,
+                  &reader::filesystem_v2::walk_data_order}) {
     std::map<std::string, file_stat> entries;
     std::vector<int> inodes;
 
-    (fs.*mp)([&](dir_entry_view e) {
+    (fs.*mp)([&](auto e) {
       auto stbuf = fs.getattr(e.inode());
       inodes.push_back(stbuf.ino());
       EXPECT_TRUE(entries.emplace(e.unix_path(), stbuf).second);
@@ -1033,7 +1034,8 @@ void check_compat(logger& lgr, filesystem_v2 const& fs,
 
 class compat_metadata : public testing::TestWithParam<std::string> {};
 
-void check_dynamic(std::string const& version, filesystem_v2 const& fs) {
+void check_dynamic(std::string const& version,
+                   reader::filesystem_v2 const& fs) {
   auto meta = fs.metadata_as_json();
   nlohmann::json ref;
   if (version == "0.2.0" or version == "0.2.3") {
@@ -1049,7 +1051,7 @@ TEST_P(compat_metadata, backwards_compat) {
   auto filename = std::string(TEST_DATA_DIR "/compat-v") + version + ".dwarfs";
   test::test_logger lgr;
   test::os_access_mock os;
-  filesystem_v2 fs(lgr, os, std::make_shared<mmap>(filename));
+  reader::filesystem_v2 fs(lgr, os, std::make_shared<mmap>(filename));
   check_dynamic(version, fs);
 }
 
@@ -1071,7 +1073,7 @@ TEST_P(compat_filesystem, backwards_compat) {
   opts.metadata.check_consistency = true;
 
   {
-    filesystem_v2 fs(lgr, os, std::make_shared<mmap>(filename), opts);
+    reader::filesystem_v2 fs(lgr, os, std::make_shared<mmap>(filename), opts);
     check_compat(lgr, fs, version);
   }
 
@@ -1081,15 +1083,15 @@ TEST_P(compat_filesystem, backwards_compat) {
   ASSERT_TRUE(folly::readFile(filename.c_str(), fsdata));
 
   for (auto const& hdr : headers) {
-    filesystem_v2 fs(lgr, os, std::make_shared<test::mmap_mock>(hdr + fsdata),
-                     opts);
+    reader::filesystem_v2 fs(
+        lgr, os, std::make_shared<test::mmap_mock>(hdr + fsdata), opts);
     check_compat(lgr, fs, version);
   }
 
   if (version != "0.2.0" and version != "0.2.3") {
     for (auto const& hdr : headers_v2) {
-      filesystem_v2 fs(lgr, os, std::make_shared<test::mmap_mock>(hdr + fsdata),
-                       opts);
+      reader::filesystem_v2 fs(
+          lgr, os, std::make_shared<test::mmap_mock>(hdr + fsdata), opts);
       check_compat(lgr, fs, version);
     }
   }
@@ -1121,7 +1123,7 @@ TEST_P(rewrite, filesystem_rewrite) {
   auto rewrite_fs = [&](auto& fsw, auto const& mm) {
     filesystem_options fsopts;
     fsopts.image_offset = filesystem_options::IMAGE_OFFSET_AUTO;
-    filesystem_v2 fs(lgr, os, mm, fsopts);
+    reader::filesystem_v2 fs(lgr, os, mm, fsopts);
     filesystem_block_category_resolver resolver(fs.get_all_block_categories());
     fs.rewrite(prog, fsw, resolver, opts);
   };
@@ -1131,16 +1133,16 @@ TEST_P(rewrite, filesystem_rewrite) {
                                                  bc, bc);
     fsw.add_default_compressor(bc);
     auto mm = std::make_shared<mmap>(filename);
-    EXPECT_NO_THROW(filesystem_v2::identify(lgr, os, mm, idss));
-    EXPECT_FALSE(filesystem_v2::header(mm));
+    EXPECT_NO_THROW(reader::filesystem_v2::identify(lgr, os, mm, idss));
+    EXPECT_FALSE(reader::filesystem_v2::header(mm));
     rewrite_fs(fsw, mm);
   }
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten.str());
-    EXPECT_NO_THROW(filesystem_v2::identify(lgr, os, mm, idss));
-    EXPECT_FALSE(filesystem_v2::header(mm));
-    filesystem_v2 fs(lgr, os, mm);
+    EXPECT_NO_THROW(reader::filesystem_v2::identify(lgr, os, mm, idss));
+    EXPECT_FALSE(reader::filesystem_v2::header(mm));
+    reader::filesystem_v2 fs(lgr, os, mm);
     check_dynamic(version, fs);
   }
 
@@ -1158,16 +1160,16 @@ TEST_P(rewrite, filesystem_rewrite) {
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten.str());
-    EXPECT_NO_THROW(filesystem_v2::identify(
+    EXPECT_NO_THROW(reader::filesystem_v2::identify(
         lgr, os, mm, idss, 0, 1, false, filesystem_options::IMAGE_OFFSET_AUTO));
-    auto hdr = filesystem_v2::header(mm);
+    auto hdr = reader::filesystem_v2::header(mm);
     ASSERT_TRUE(hdr) << folly::hexDump(rewritten.str().data(),
                                        rewritten.str().size());
     EXPECT_EQ(format_sh, std::string(reinterpret_cast<char const*>(hdr->data()),
                                      hdr->size()));
     filesystem_options fsopts;
     fsopts.image_offset = filesystem_options::IMAGE_OFFSET_AUTO;
-    filesystem_v2 fs(lgr, os, mm, fsopts);
+    reader::filesystem_v2 fs(lgr, os, mm, fsopts);
     check_dynamic(version, fs);
   }
 
@@ -1184,7 +1186,7 @@ TEST_P(rewrite, filesystem_rewrite) {
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten2.str());
-    auto hdr = filesystem_v2::header(mm);
+    auto hdr = reader::filesystem_v2::header(mm);
     ASSERT_TRUE(hdr) << folly::hexDump(rewritten2.str().data(),
                                        rewritten2.str().size());
     EXPECT_EQ("D", std::string(reinterpret_cast<char const*>(hdr->data()),
@@ -1202,7 +1204,7 @@ TEST_P(rewrite, filesystem_rewrite) {
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten3.str());
-    auto hdr = filesystem_v2::header(mm);
+    auto hdr = reader::filesystem_v2::header(mm);
     ASSERT_TRUE(hdr) << folly::hexDump(rewritten3.str().data(),
                                        rewritten3.str().size());
     EXPECT_EQ("D", std::string(reinterpret_cast<char const*>(hdr->data()),
@@ -1222,10 +1224,10 @@ TEST_P(rewrite, filesystem_rewrite) {
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten4.str());
-    EXPECT_NO_THROW(filesystem_v2::identify(lgr, os, mm, idss));
-    EXPECT_FALSE(filesystem_v2::header(mm))
+    EXPECT_NO_THROW(reader::filesystem_v2::identify(lgr, os, mm, idss));
+    EXPECT_FALSE(reader::filesystem_v2::header(mm))
         << folly::hexDump(rewritten4.str().data(), rewritten4.str().size());
-    filesystem_v2 fs(lgr, os, mm);
+    reader::filesystem_v2 fs(lgr, os, mm);
     check_dynamic(version, fs);
   }
 
@@ -1242,10 +1244,10 @@ TEST_P(rewrite, filesystem_rewrite) {
 
   {
     auto mm = std::make_shared<test::mmap_mock>(rewritten5.str());
-    EXPECT_NO_THROW(filesystem_v2::identify(lgr, os, mm, idss));
-    EXPECT_FALSE(filesystem_v2::header(mm))
+    EXPECT_NO_THROW(reader::filesystem_v2::identify(lgr, os, mm, idss));
+    EXPECT_FALSE(reader::filesystem_v2::header(mm))
         << folly::hexDump(rewritten5.str().data(), rewritten5.str().size());
-    filesystem_v2 fs(lgr, os, mm);
+    reader::filesystem_v2 fs(lgr, os, mm);
     check_dynamic(version, fs);
   }
 }
@@ -1262,7 +1264,7 @@ TEST_P(set_uidgid_test, read_legacy_image) {
 
   test::test_logger lgr;
   test::os_access_mock os;
-  filesystem_v2 fs(lgr, os, std::make_shared<mmap>(image));
+  reader::filesystem_v2 fs(lgr, os, std::make_shared<mmap>(image));
 
   ASSERT_EQ(0, fs.check(filesystem_check_level::FULL));
 
diff --git a/test/dwarfs_benchmark.cpp b/test/dwarfs_benchmark.cpp
index b87ffce7..90e8bc6a 100644
--- a/test/dwarfs_benchmark.cpp
+++ b/test/dwarfs_benchmark.cpp
@@ -192,7 +192,7 @@ void dwarfs_initialize(::benchmark::State& state) {
   opts.metadata.enable_nlink = true;
 
   for (auto _ : state) {
-    auto fs = filesystem_v2(lgr, os, mm, opts);
+    auto fs = reader::filesystem_v2(lgr, os, mm, opts);
     ::benchmark::DoNotOptimize(fs);
   }
 }
@@ -207,7 +207,7 @@ class filesystem : public ::benchmark::Fixture {
     filesystem_options opts;
     opts.block_cache.max_bytes = 1 << 20;
     opts.metadata.enable_nlink = true;
-    fs = std::make_unique<filesystem_v2>(lgr, os, mm, opts);
+    fs = std::make_unique<reader::filesystem_v2>(lgr, os, mm, opts);
     entries.reserve(NUM_ENTRIES);
     for (int i = 0; entries.size() < NUM_ENTRIES; ++i) {
       if (auto e = fs->find(i)) {
@@ -252,7 +252,7 @@ class filesystem : public ::benchmark::Fixture {
     auto i = fs->open(*iv);
 
     for (auto _ : state) {
-      iovec_read_buf buf;
+      reader::iovec_read_buf buf;
       auto r = fs->readv(i, buf);
       ::benchmark::DoNotOptimize(r);
     }
@@ -275,7 +275,7 @@ class filesystem : public ::benchmark::Fixture {
   void getattr_bench(::benchmark::State& state, getattr_options const& opts,
                      std::array<std::string_view, N> const& paths) {
     int i = 0;
-    std::vector<inode_view> ent;
+    std::vector<reader::inode_view> ent;
     ent.reserve(paths.size());
     for (auto const& p : paths) {
       ent.emplace_back(*fs->find(p.data()));
@@ -293,8 +293,8 @@ class filesystem : public ::benchmark::Fixture {
     getattr_bench(state, {}, paths);
   }
 
-  std::unique_ptr<filesystem_v2> fs;
-  std::vector<inode_view> entries;
+  std::unique_ptr<reader::filesystem_v2> fs;
+  std::vector<reader::inode_view> entries;
 
  private:
   test::test_logger lgr;
diff --git a/test/dwarfs_test.cpp b/test/dwarfs_test.cpp
index be25e169..88dfcb16 100644
--- a/test/dwarfs_test.cpp
+++ b/test/dwarfs_test.cpp
@@ -242,7 +242,7 @@ void basic_end_to_end_test(std::string const& compressor,
   opts.metadata.check_consistency = true;
   opts.inode_reader.readahead = readahead;
 
-  filesystem_v2 fs(lgr, *input, mm, opts);
+  reader::filesystem_v2 fs(lgr, *input, mm, opts);
 
   // fs.dump(std::cerr, 9);
 
@@ -471,11 +471,12 @@ void basic_end_to_end_test(std::string const& compressor,
   EXPECT_EQ(set_uid ? EACCES : 0, ec.value());
   EXPECT_EQ(set_uid, !fs.access(*entry, R_OK, 1337, 0));
 
-  for (auto mp : {&filesystem_v2::walk, &filesystem_v2::walk_data_order}) {
+  for (auto mp : {&reader::filesystem_v2::walk,
+                  &reader::filesystem_v2::walk_data_order}) {
     std::map<std::string, file_stat> entries;
     std::vector<int> inodes;
 
-    (fs.*mp)([&](dir_entry_view e) {
+    (fs.*mp)([&](reader::dir_entry_view e) {
       auto stbuf = fs.getattr(e.inode());
       inodes.push_back(stbuf.ino());
       auto path = e.path();
@@ -679,7 +680,7 @@ TEST_P(packing_test, regression_empty_fs) {
   opts.block_cache.max_bytes = 1 << 20;
   opts.metadata.check_consistency = true;
 
-  filesystem_v2 fs(lgr, *input, mm, opts);
+  reader::filesystem_v2 fs(lgr, *input, mm, opts);
 
   vfs_stat vfsbuf;
   fs.statvfs(&vfsbuf);
@@ -689,7 +690,7 @@ TEST_P(packing_test, regression_empty_fs) {
 
   size_t num = 0;
 
-  fs.walk([&](dir_entry_view e) {
+  fs.walk([&](reader::dir_entry_view e) {
     ++num;
     auto stbuf = fs.getattr(e.inode());
     EXPECT_TRUE(stbuf.is_directory());
@@ -752,7 +753,7 @@ TEST(segmenter, regression_block_boundary) {
 
     auto mm = std::make_shared<test::mmap_mock>(fsdata);
 
-    filesystem_v2 fs(lgr, *input, mm, opts);
+    reader::filesystem_v2 fs(lgr, *input, mm, opts);
 
     vfs_stat vfsbuf;
     fs.statvfs(&vfsbuf);
@@ -806,7 +807,7 @@ TEST_P(compression_regression, github45) {
   auto mm = std::make_shared<test::mmap_mock>(fsdata);
 
   std::stringstream idss;
-  filesystem_v2::identify(lgr, *input, mm, idss, 3);
+  reader::filesystem_v2::identify(lgr, *input, mm, idss, 3);
 
   std::string line;
   std::regex const re("^SECTION num=\\d+, type=BLOCK, compression=(\\w+).*");
@@ -825,7 +826,7 @@ TEST_P(compression_regression, github45) {
   }
   EXPECT_EQ(1, compressions.count("NONE"));
 
-  filesystem_v2 fs(lgr, *input, mm, opts);
+  reader::filesystem_v2 fs(lgr, *input, mm, opts);
 
   vfs_stat vfsbuf;
   fs.statvfs(&vfsbuf);
@@ -1014,11 +1015,11 @@ TEST_P(filter_test, filesystem) {
   opts.metadata.enable_nlink = true;
   opts.metadata.check_consistency = true;
 
-  filesystem_v2 fs(lgr, *input, mm, opts);
+  reader::filesystem_v2 fs(lgr, *input, mm, opts);
 
   std::unordered_set<std::string> got;
 
-  fs.walk([&got](dir_entry_view e) { got.emplace(e.unix_path()); });
+  fs.walk([&got](reader::dir_entry_view e) { got.emplace(e.unix_path()); });
 
   EXPECT_EQ(spec.expected_files(), got);
 }
@@ -1093,11 +1094,11 @@ TEST(file_scanner, input_list) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm);
+  reader::filesystem_v2 fs(lgr, *input, mm);
 
   std::unordered_set<std::string> got;
 
-  fs.walk([&got](dir_entry_view e) { got.emplace(e.unix_path()); });
+  fs.walk([&got](reader::dir_entry_view e) { got.emplace(e.unix_path()); });
 
   std::unordered_set<std::string> expected{
       "",
@@ -1124,7 +1125,7 @@ TEST(filesystem, uid_gid_32bit) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm);
+  reader::filesystem_v2 fs(lgr, *input, mm);
 
   auto iv16 = fs.find("/foo16.txt");
   auto iv32 = fs.find("/foo32.txt");
@@ -1158,7 +1159,7 @@ TEST(filesystem, uid_gid_count) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm);
+  reader::filesystem_v2 fs(lgr, *input, mm);
 
   auto iv00000 = fs.find("/foo00000.txt");
   auto iv50000 = fs.find("/foo50000.txt");
@@ -1235,9 +1236,9 @@ TEST(section_index_regression, github183) {
 
   auto mm = std::make_shared<test::mmap_mock>(fsimage2);
 
-  filesystem_v2 fs;
+  reader::filesystem_v2 fs;
 
-  ASSERT_NO_THROW(fs = filesystem_v2(lgr, *input, mm));
+  ASSERT_NO_THROW(fs = reader::filesystem_v2(lgr, *input, mm));
   EXPECT_NO_THROW(fs.walk([](auto) {}));
 
   auto entry = fs.find("/foo.pl");
@@ -1259,7 +1260,7 @@ TEST(section_index_regression, github183) {
   EXPECT_EQ(ec.value(), EIO);
 
   std::stringstream idss;
-  EXPECT_THROW(filesystem_v2::identify(lgr, *input, mm, idss, 3),
+  EXPECT_THROW(reader::filesystem_v2::identify(lgr, *input, mm, idss, 3),
                dwarfs::runtime_error);
 }
 
@@ -1269,7 +1270,7 @@ TEST(filesystem, find_by_path) {
   auto fsimage = build_dwarfs(lgr, input, "null");
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm);
+  reader::filesystem_v2 fs(lgr, *input, mm);
 
   std::vector<std::string> paths;
   fs.walk([&](auto e) { paths.emplace_back(e.unix_path()); });
@@ -1301,7 +1302,8 @@ TEST(file_scanner, file_start_hash) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm, {.metadata = {.enable_nlink = true}});
+  reader::filesystem_v2 fs(lgr, *input, mm,
+                           {.metadata = {.enable_nlink = true}});
 
   auto link1 = fs.find("/hardlink1");
   auto link2 = fs.find("/hardlink2");
@@ -1333,7 +1335,7 @@ TEST(filesystem, root_access_github204) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm);
+  reader::filesystem_v2 fs(lgr, *input, mm);
 
   auto other = fs.find("/other");
   auto group = fs.find("/group");
@@ -1497,7 +1499,8 @@ TEST(filesystem, read) {
 
   auto mm = std::make_shared<test::mmap_mock>(std::move(fsimage));
 
-  filesystem_v2 fs(lgr, *input, mm, {.inode_reader = {.readahead = 64}});
+  reader::filesystem_v2 fs(lgr, *input, mm,
+                           {.inode_reader = {.readahead = 64}});
 
   auto iv = fs.find("/random");
   EXPECT_TRUE(iv);
@@ -1507,10 +1510,10 @@ TEST(filesystem, read) {
 
   std::error_code ec;
   std::vector<char> tmp(contents.size());
-  iovec_read_buf iov;
+  reader::iovec_read_buf iov;
   std::string_view cview(contents);
 
-  auto iov_to_str = [](iovec_read_buf const& iov) {
+  auto iov_to_str = [](reader::iovec_read_buf const& iov) {
     std::string result;
     for (auto const& i : iov.buf) {
       result.append(reinterpret_cast<char const*>(i.iov_base), i.iov_len);
@@ -1518,7 +1521,7 @@ TEST(filesystem, read) {
     return result;
   };
 
-  auto fut_to_str = [](std::vector<std::future<block_range>>&& futs) {
+  auto fut_to_str = [](std::vector<std::future<reader::block_range>>&& futs) {
     std::string result;
     for (auto& f : futs) {
       auto br = f.get();
diff --git a/test/filesystem_test.cpp b/test/filesystem_test.cpp
index 396ecb56..12674e82 100644
--- a/test/filesystem_test.cpp
+++ b/test/filesystem_test.cpp
@@ -51,7 +51,7 @@ TEST(filesystem, metadata_symlink_win) {
   test::os_access_mock os;
 
   auto mm = std::make_shared<mmap>(test_dir / "winlink.dwarfs");
-  filesystem_v2 fs(lgr, os, mm);
+  reader::filesystem_v2 fs(lgr, os, mm);
 
   auto i1 = fs.find("link.txt");
   auto i2 = fs.find("dir/link.txt");
@@ -80,22 +80,22 @@ TEST(filesystem, metadata_symlink_win) {
   }
 
   {
-    auto buffer = fs.readlink(*i1, readlink_mode::raw);
+    auto buffer = fs.readlink(*i1, reader::readlink_mode::raw);
     EXPECT_EQ("subdir\\test.txt", buffer);
-    buffer = fs.readlink(*i2, readlink_mode::raw);
+    buffer = fs.readlink(*i2, reader::readlink_mode::raw);
     EXPECT_EQ("..\\subdir\\test.txt", buffer);
   }
 
   {
-    auto buffer = fs.readlink(*i1, readlink_mode::unix);
+    auto buffer = fs.readlink(*i1, reader::readlink_mode::unix);
     EXPECT_EQ("subdir/test.txt", buffer);
-    buffer = fs.readlink(*i2, readlink_mode::unix);
+    buffer = fs.readlink(*i2, reader::readlink_mode::unix);
     EXPECT_EQ("../subdir/test.txt", buffer);
   }
 
   {
     std::error_code ec;
-    auto r = fs.readlink(*i1, readlink_mode::unix, ec);
+    auto r = fs.readlink(*i1, reader::readlink_mode::unix, ec);
     EXPECT_FALSE(ec);
     EXPECT_EQ("subdir/test.txt", r);
   }
@@ -109,7 +109,7 @@ TEST(filesystem, metadata_symlink_win) {
 
   // also test throwing interface
   {
-    auto r = fs.readlink(*i1, readlink_mode::unix);
+    auto r = fs.readlink(*i1, reader::readlink_mode::unix);
     EXPECT_EQ("subdir/test.txt", r);
   }
 
@@ -124,7 +124,7 @@ TEST(filesystem, metadata_symlink_unix) {
   test::os_access_mock os;
 
   auto mm = std::make_shared<mmap>(test_dir / "unixlink.dwarfs");
-  filesystem_v2 fs(lgr, os, mm);
+  reader::filesystem_v2 fs(lgr, os, mm);
 
   auto i1 = fs.find("link.txt");
   auto i2 = fs.find("dir/link.txt");
@@ -153,22 +153,22 @@ TEST(filesystem, metadata_symlink_unix) {
   }
 
   {
-    auto buffer = fs.readlink(*i1, readlink_mode::raw);
+    auto buffer = fs.readlink(*i1, reader::readlink_mode::raw);
     EXPECT_EQ("subdir/test.txt", buffer);
-    buffer = fs.readlink(*i2, readlink_mode::raw);
+    buffer = fs.readlink(*i2, reader::readlink_mode::raw);
     EXPECT_EQ("../subdir/test.txt", buffer);
   }
 
   {
-    auto buffer = fs.readlink(*i1, readlink_mode::unix);
+    auto buffer = fs.readlink(*i1, reader::readlink_mode::unix);
     EXPECT_EQ("subdir/test.txt", buffer);
-    buffer = fs.readlink(*i2, readlink_mode::unix);
+    buffer = fs.readlink(*i2, reader::readlink_mode::unix);
     EXPECT_EQ("../subdir/test.txt", buffer);
   }
 
   {
     std::error_code ec;
-    auto r = fs.readlink(*i1, readlink_mode::unix, ec);
+    auto r = fs.readlink(*i1, reader::readlink_mode::unix, ec);
     EXPECT_FALSE(ec);
     EXPECT_EQ("subdir/test.txt", r);
   }
@@ -221,7 +221,7 @@ TEST(filesystem, find_image_offset) {
       [&](std::string data,
           filesystem_options const& opt = {
               .image_offset = filesystem_options::IMAGE_OFFSET_AUTO}) {
-        return filesystem_v2(
+        return reader::filesystem_v2(
             lgr, os, std::make_shared<test::mmap_mock>(std::move(data)), opt);
       };
 
diff --git a/test/tool_main_test.cpp b/test/tool_main_test.cpp
index e48cd54a..fc61f043 100644
--- a/test/tool_main_test.cpp
+++ b/test/tool_main_test.cpp
@@ -283,17 +283,19 @@ class mkdwarfs_tester : public tester_common {
     }
   }
 
-  filesystem_v2 fs_from_data(std::string data,
-                             filesystem_options const& opt = default_fs_opts) {
+  reader::filesystem_v2
+  fs_from_data(std::string data,
+               filesystem_options const& opt = default_fs_opts) {
     if (!lgr) {
       lgr = std::make_unique<test::test_logger>();
     }
     auto mm = std::make_shared<test::mmap_mock>(std::move(data));
-    return filesystem_v2(*lgr, *os, mm, opt);
+    return reader::filesystem_v2(*lgr, *os, mm, opt);
   }
 
-  filesystem_v2 fs_from_file(std::string path,
-                             filesystem_options const& opt = default_fs_opts) {
+  reader::filesystem_v2
+  fs_from_file(std::string path,
+               filesystem_options const& opt = default_fs_opts) {
     auto fsimage = fa->get_file(path);
     if (!fsimage) {
       throw std::runtime_error("file not found: " + path);
@@ -301,7 +303,7 @@ class mkdwarfs_tester : public tester_common {
     return fs_from_data(std::move(fsimage.value()), opt);
   }
 
-  filesystem_v2
+  reader::filesystem_v2
   fs_from_stdout(filesystem_options const& opt = default_fs_opts) {
     return fs_from_data(out(), opt);
   }
@@ -365,7 +367,7 @@ class dwarfsextract_tester : public tester_common {
   }
 };
 
-std::tuple<std::optional<filesystem_v2>, mkdwarfs_tester>
+std::tuple<std::optional<reader::filesystem_v2>, mkdwarfs_tester>
 build_with_args(std::vector<std::string> opt_args = {}) {
   std::string const image_file = "test.dwarfs";
   mkdwarfs_tester t;
@@ -377,7 +379,7 @@ build_with_args(std::vector<std::string> opt_args = {}) {
   return {t.fs_from_file(image_file), std::move(t)};
 }
 
-std::set<uint64_t> get_all_fs_times(filesystem_v2 const& fs) {
+std::set<uint64_t> get_all_fs_times(reader::filesystem_v2 const& fs) {
   std::set<uint64_t> times;
   fs.walk([&](auto const& e) {
     auto st = fs.getattr(e.inode());
@@ -388,7 +390,7 @@ std::set<uint64_t> get_all_fs_times(filesystem_v2 const& fs) {
   return times;
 }
 
-std::set<uint64_t> get_all_fs_uids(filesystem_v2 const& fs) {
+std::set<uint64_t> get_all_fs_uids(reader::filesystem_v2 const& fs) {
   std::set<uint64_t> uids;
   fs.walk([&](auto const& e) {
     auto st = fs.getattr(e.inode());
@@ -397,7 +399,7 @@ std::set<uint64_t> get_all_fs_uids(filesystem_v2 const& fs) {
   return uids;
 }
 
-std::set<uint64_t> get_all_fs_gids(filesystem_v2 const& fs) {
+std::set<uint64_t> get_all_fs_gids(reader::filesystem_v2 const& fs) {
   std::set<uint64_t> gids;
   fs.walk([&](auto const& e) {
     auto st = fs.getattr(e.inode());
@@ -880,7 +882,7 @@ TEST(mkdwarfs_test, metadata_path) {
   ASSERT_EQ(0, t.run("-l3 -i / -o -"));
   auto fs = t.fs_from_stdout();
 
-  std::map<size_t, dir_entry_view> entries;
+  std::map<size_t, reader::dir_entry_view> entries;
   fs.walk([&](auto e) {
     auto stat = fs.getattr(e.inode());
     if (stat.is_regular_file()) {
@@ -1989,8 +1991,8 @@ TEST(dwarfsck_test, check_fail) {
       test::test_logger lgr;
       test::os_access_mock os;
       auto make_fs = [&] {
-        return filesystem_v2{lgr, os,
-                             std::make_shared<test::mmap_mock>(corrupt_image)};
+        return reader::filesystem_v2{
+            lgr, os, std::make_shared<test::mmap_mock>(corrupt_image)};
       };
       if (is_metadata_section) {
         EXPECT_THAT([&] { make_fs(); },
@@ -2276,7 +2278,7 @@ TEST(mkdwarfs_test, max_similarity_size) {
     return t;
   };
 
-  auto get_sizes_in_offset_order = [](filesystem_v2 const& fs) {
+  auto get_sizes_in_offset_order = [](reader::filesystem_v2 const& fs) {
     std::vector<std::pair<size_t, size_t>> tmp;
 
     for (auto size : sizes) {
@@ -2447,7 +2449,7 @@ TEST(mkdwarfs_test, filesystem_read_error) {
                 ::testing::Throws<std::system_error>());
   }
   {
-    iovec_read_buf buf;
+    reader::iovec_read_buf buf;
     std::error_code ec;
     auto num = fs.readv(iv->inode_num(), buf, 42, ec);
     EXPECT_EQ(0, num);
diff --git a/test/utils_test.cpp b/test/utils_test.cpp
index 959f0864..9b7ce709 100644
--- a/test/utils_test.cpp
+++ b/test/utils_test.cpp
@@ -192,7 +192,7 @@ TEST(utils, shorten_path_utf8) {
 namespace {
 
 using cache_type =
-    internal::basic_offset_cache<uint32_t, uint32_t, uint32_t, 4, 4>;
+    reader::internal::basic_offset_cache<uint32_t, uint32_t, uint32_t, 4, 4>;
 constexpr std::array<cache_type::file_offset_type, 32> const test_chunks{
     3, 15, 13, 1,  11, 6,  9,  15, 1,  16, 1,  13, 11, 16, 10, 14,
     4, 14, 4,  16, 8,  12, 16, 2,  16, 10, 15, 15, 2,  15, 5,  8,