release: prepare v0.5.6 (#142)

- Document all remaining public API items (container v2 types, GPU
  backends and feature-disabled stubs, Avx512Info, occupancy ray
  casters) for 100% rustdoc item coverage
- Update README What's New section for v0.5.6
- Roll CHANGELOG [Unreleased] into [0.5.6] - 2026-06-10
- Bump version to 0.5.6

Co-authored-by: FunKite <FunKite@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: FunKite

CHANGELOG.md

@@ -7,7 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.6] - 2026-06-10
+
 ### Added
+- Documentation for all remaining public API items — the container v2 format types (`HeaderV2`, `TocEntry`, `Footer`, `ContainerWriterV2`), GPU backend constructors and availability checks (including feature-disabled stubs), `Avx512Info` feature-detection fields and methods, and GPU-accelerated occupancy ray casters — bringing rustdoc item coverage to 100%.
 - New high-level `BccGrid` facade (`grid` module, re-exported at the crate root): convert physical points to cells (`cell_at`/`center_of`), query `neighbors`, `k_ring`, `k_shell`, and `distance`, and run A* pathfinding (`astar`, `astar_where` with a traversability predicate, `astar_with_limit`) on modern `Route64` IDs without handling parity, tiers, or coordinate ranges manually.
 - New `examples/quickstart.rs` demonstrating the modern API (`BccGrid`, `Index64`, `Route64`).
 - The README's Rust code blocks now compile as doctests (`#[doc = include_str!]` harness in `lib.rs`), so documentation examples can no longer drift from the implementation.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "octaindex3d"
-version = "0.5.5"
+version = "0.5.6"
 edition = "2021"
 rust-version = "1.77"
 authors = ["Michael A. McLarney"]

Cargo.toml

@@ -17,7 +17,7 @@
 
 ## Table of Contents
 
-- [What's New in v0.5.5](#whats-new-in-v055)
+- [What's New in v0.5.6](#whats-new-in-v056)
 - [Overview](#overview)
 - [Why BCC Lattice?](#why-bcc-lattice)
 - [Interactive 3D Maze Game](#-interactive-3d-maze-game)
@@ -34,15 +34,17 @@
 - [Contributing](#contributing)
 - [Research and Citation](#research-and-citation)
 
-## What's New in v0.5.5
+## What's New in v0.5.6
 
-This release focuses on security dependency updates, GPU dependency compatibility, and release metadata cleanup.
+This release introduces the high-level `BccGrid` API, corrects several BCC lattice operations, and adds a new survival mode to the interactive maze.
 
-- **Security dependency fix** - Updated `lz4_flex` to 0.13.1 to avoid an upstream unsafe-mode dictionary compression panic for short dictionaries.
-- **GPU dependency refresh** - Updated `cudarc` to 0.19.7 and `wgpu` to 29.0.3, including the replacement for the yanked `wgpu` 29.0.2 release.
-- **Runtime and tooling updates** - Refreshed `rkyv`, `rayon`, `clap`, Cargo lockfile resolution, and GitHub Actions dependency tooling.
-- **Feature build fix** - Restored `--no-default-features` builds by keeping legacy serialization helpers behind the `serde` feature.
-- **Release metadata cleanup** - Promoted the accumulated unreleased dependency notes into the v0.5.5 changelog before publishing to crates.io.
+- **New `BccGrid` facade** - Convert physical points to cells, query `neighbors`, `k_ring`, `k_shell`, and `distance`, and run A* pathfinding on modern `Route64` IDs without handling parity, tiers, or coordinate ranges manually. See the [Quick Start](#quick-start) and `examples/quickstart.rs`.
+- **Lattice correctness fixes** - `physical_to_lattice` now snaps any finite in-range point to the nearest valid BCC point and honors its `resolution` parameter; `get_children` produces the 8 parity-valid children with `get_parent` as its exact inverse; `batch_validate_routes` applies the correct all-same-parity rule.
+- **Legacy API deprecations** - The v0.2-era `CellID`, `path::*`, and `Layer` APIs are deprecated in favor of `BccGrid` and the modern ID types. All remain available for compatibility.
+- **README doctests** - The README's Rust code blocks now compile as doctests, so documentation examples stay in sync with the implementation.
+- **Bloodhound survival mode** - A new mode for `octaindex3d play`: reach the goal before pursuing bloodhounds catch you, with spike traps, scent trails, and progressive level sizing.
+- **Security** - Replaced the unmaintained `serde_cbor` dependency with `ciborium` (RUSTSEC-2021-0127); the `Dataset` CBOR API is unchanged.
+- **Documentation coverage** - Documented the remaining public API items (container v2 format types, GPU backends, AVX-512 feature detection) for complete docs.rs coverage.
 
 See the full [Changelog](CHANGELOG.md) for release history.
 

README.md

@@ -41,13 +41,19 @@ impl Default for StreamConfig {
 /// Container v2 header (32 bytes)
 #[derive(Debug, Clone)]
 pub struct HeaderV2 {
+    /// Container format version (currently 2).
     pub format_version: u8,
+    /// Feature flags; bit 0 indicates per-frame SHA-256 hashes are present.
     pub flags: u8,
+    /// Unique stream identifier, derived from the creation timestamp.
     pub stream_id: u64,
+    /// Byte offset of the first frame (immediately after the 32-byte header).
     pub first_frame_offset: u64,
 }
 
 impl HeaderV2 {
+    /// Creates a header for a new stream, generating a fresh `stream_id`
+    /// and setting the SHA-256 flag if `enable_sha256` is true.
     pub fn new(enable_sha256: bool) -> Self {
         use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
@@ -65,10 +71,12 @@ impl HeaderV2 {
         }
     }
 
+    /// Returns true if frames in this stream carry SHA-256 integrity hashes.
     pub fn has_sha256(&self) -> bool {
         (self.flags & 0x01) != 0
     }
 
+    /// Serializes the header to its fixed 32-byte on-disk representation.
     pub fn to_bytes(&self) -> [u8; 32] {
         let mut bytes = [0u8; 32];
         bytes[0..8].copy_from_slice(MAGIC_V2);
@@ -80,6 +88,9 @@ impl HeaderV2 {
         bytes
     }
 
+    /// Parses a header from its 32-byte on-disk representation.
+    ///
+    /// Returns [`Error::InvalidFormat`] if the magic number does not match.
     pub fn from_bytes(bytes: &[u8; 32]) -> Result<Self> {
         if &bytes[0..8] != MAGIC_V2 {
             return Err(Error::InvalidFormat("Invalid magic number".to_string()));
@@ -105,17 +116,26 @@ impl HeaderV2 {
 /// TOC entry (32 bytes)
 #[derive(Debug, Clone)]
 pub struct TocEntry {
+    /// Byte offset of the frame within the container.
     pub offset: u64,
+    /// Size of the frame payload before compression, in bytes.
     pub uncompressed_len: u32,
+    /// Size of the frame payload after compression, in bytes.
     pub compressed_len: u32,
+    /// Compression codec identifier used for this frame.
     pub codec: u8,
+    /// Graph identifier the frame belongs to.
     pub graph: u8,
+    /// Level-of-detail tag for the frame.
     pub lod: u8,
+    /// Storage tier tag for the frame.
     pub tier: u8,
+    /// Monotonically increasing sequence number of the frame.
     pub seq: u64,
 }
 
 impl TocEntry {
+    /// Serializes the entry to its fixed 32-byte on-disk representation.
     pub fn to_bytes(&self) -> [u8; 32] {
         let mut bytes = [0u8; 32];
         bytes[0..8].copy_from_slice(&self.offset.to_be_bytes());
@@ -129,6 +149,7 @@ impl TocEntry {
         bytes
     }
 
+    /// Parses an entry from its 32-byte on-disk representation.
     pub fn from_bytes(bytes: &[u8; 32]) -> Self {
         Self {
             offset: u64::from_be_bytes(
@@ -162,13 +183,18 @@ impl TocEntry {
 /// Footer (32 bytes)
 #[derive(Debug, Clone)]
 pub struct Footer {
+    /// Byte offset where the table of contents begins.
     pub toc_offset: u64,
+    /// Length of the table of contents, in bytes.
     pub toc_len: u64,
+    /// Number of TOC entries (frames) recorded.
     pub entry_count: u64,
+    /// Copy of the header flags, for recovery without re-reading the header.
     pub flags_copy: u64,
 }
 
 impl Footer {
+    /// Serializes the footer to its fixed 32-byte on-disk representation.
     pub fn to_bytes(&self) -> [u8; 32] {
         let mut bytes = [0u8; 32];
         bytes[0..8].copy_from_slice(&self.toc_offset.to_be_bytes());
@@ -178,6 +204,7 @@ impl Footer {
         bytes
     }
 
+    /// Parses a footer from its 32-byte on-disk representation.
     pub fn from_bytes(bytes: &[u8; 32]) -> Self {
         Self {
             toc_offset: u64::from_be_bytes(
@@ -216,6 +243,9 @@ pub struct ContainerWriterV2<W: Write + Seek> {
 }
 
 impl<W: Write + Seek> ContainerWriterV2<W> {
+    /// Creates a writer over `writer`, immediately writing the stream header.
+    ///
+    /// Frames are LZ4-compressed by default; see [`Self::with_compression`].
     pub fn new(mut writer: W, config: StreamConfig) -> Result<Self> {
         let header = HeaderV2::new(config.enable_sha256);
 
@@ -233,11 +263,16 @@ impl<W: Write + Seek> ContainerWriterV2<W> {
         })
     }
 
+    /// Replaces the default LZ4 codec with a custom [`Compression`] implementation.
     pub fn with_compression(mut self, compression: Box<dyn Compression>) -> Result<Self> {
         self.compression = compression;
         Ok(self)
     }
 
+    /// Appends one frame of data, compressing it and recording a TOC entry.
+    ///
+    /// A checkpoint (TOC + footer) is flushed automatically once the configured
+    /// frame-count or byte thresholds in [`StreamConfig`] are reached.
     pub fn write_frame(&mut self, data: &[u8]) -> Result<()> {
         let uncompressed_len = data.len() as u32;
         let offset = self.writer.stream_position()?;
@@ -331,6 +366,10 @@ impl<W: Write + Seek> ContainerWriterV2<W> {
         Ok(())
     }
 
+    /// Finalizes the container, writing the last checkpoint (TOC + footer).
+    ///
+    /// Must be called for the container to be readable; dropping the writer
+    /// without calling `finish` leaves only data up to the last checkpoint.
     pub fn finish(mut self) -> Result<()> {
         // Write final checkpoint
         if !self.toc_entries.is_empty() {

src/container_v2.rs

@@ -62,7 +62,7 @@ pub mod ros2 {
     pub use super::ros2_bridge::*;
 }
 
-// Re-export GPU types (conditionally)
+/// Re-export GPU-accelerated occupancy types (available with `gpu-metal` or `gpu-cuda`)
 #[cfg(any(feature = "gpu-metal", feature = "gpu-cuda"))]
 pub mod gpu {
     pub use super::occupancy_gpu::*;

src/layers/mod.rs

@@ -125,13 +125,16 @@ mod metal_impl {
     use metal::*;
     use std::sync::Arc;
 
+    /// Ray-casting backend that runs occupancy updates on the GPU via Metal.
     pub struct MetalRayCaster {
         _device: Arc<Device>,
         _command_queue: Arc<CommandQueue>,
         _pipeline: ComputePipelineState,
     }
 
     impl MetalRayCaster {
+        /// Creates a ray caster on the system's default Metal device,
+        /// compiling the occupancy ray-cast compute shader.
         pub fn new() -> Result<Self> {
             let device = Device::system_default()
                 .ok_or_else(|| Error::InvalidFormat("No Metal device found".to_string()))?;
@@ -193,11 +196,13 @@ pub use metal_impl::MetalRayCaster;
 mod cuda_impl {
     use super::*;
 
+    /// Ray-casting backend that runs occupancy updates on NVIDIA GPUs via CUDA.
     pub struct CudaRayCaster {
         // CUDA context and kernels would go here
     }
 
     impl CudaRayCaster {
+        /// Creates a CUDA ray caster.
         pub fn new() -> Result<Self> {
             // Initialize CUDA ray casting kernel
             Ok(Self {})

src/layers/occupancy_gpu.rs

@@ -121,7 +121,7 @@ mod tests {
 
     #[test]
     fn test_version() {
-        assert_eq!(VERSION, "0.5.5");
+        assert_eq!(VERSION, "0.5.6");
     }
 
     #[test]

src/lib.rs

@@ -24,6 +24,7 @@ pub fn has_avx512f() -> bool {
     is_x86_feature_detected!("avx512f")
 }
 
+/// Check if AVX-512F (foundation) is available (always false on non-x86_64)
 #[cfg(not(target_arch = "x86_64"))]
 pub fn has_avx512f() -> bool {
     false
@@ -35,6 +36,7 @@ pub fn has_avx512cd() -> bool {
     is_x86_feature_detected!("avx512cd")
 }
 
+/// Check if AVX-512 with conflict detection is available (always false on non-x86_64)
 #[cfg(not(target_arch = "x86_64"))]
 pub fn has_avx512cd() -> bool {
     false
@@ -141,15 +143,22 @@ pub unsafe fn batch_morton_encode_avx512(coords: &[(u16, u16, u16)]) -> Vec<u64>
 
 /// Get AVX-512 feature availability summary
 pub struct Avx512Info {
-    pub has_f: bool,    // Foundation
-    pub has_cd: bool,   // Conflict Detection
-    pub has_dq: bool,   // Doubleword and Quadword
-    pub has_bw: bool,   // Byte and Word
-    pub has_vl: bool,   // Vector Length Extensions
-    pub has_vnni: bool, // Vector Neural Network Instructions
+    /// Foundation (AVX-512F)
+    pub has_f: bool,
+    /// Conflict Detection (AVX-512CD)
+    pub has_cd: bool,
+    /// Doubleword and Quadword (AVX-512DQ)
+    pub has_dq: bool,
+    /// Byte and Word (AVX-512BW)
+    pub has_bw: bool,
+    /// Vector Length Extensions (AVX-512VL)
+    pub has_vl: bool,
+    /// Vector Neural Network Instructions (AVX-512VNNI)
+    pub has_vnni: bool,
 }
 
 impl Avx512Info {
+    /// Detect which AVX-512 feature sets the current CPU supports
     #[cfg(target_arch = "x86_64")]
     pub fn detect() -> Self {
         Self {
@@ -162,6 +171,7 @@ impl Avx512Info {
         }
     }
 
+    /// Detect AVX-512 feature sets (all false on non-x86_64)
     #[cfg(not(target_arch = "x86_64"))]
     pub fn detect() -> Self {
         Self {
@@ -174,10 +184,12 @@ impl Avx512Info {
         }
     }
 
+    /// Returns true if the AVX-512 foundation instructions are available
     pub fn is_available(&self) -> bool {
         self.has_f
     }
 
+    /// Print a human-readable summary of detected AVX-512 features to stdout
     pub fn print_info(&self) {
         println!("AVX-512 Features:");
         println!("  Foundation (F): {}", self.has_f);

src/performance/avx512.rs

@@ -45,6 +45,7 @@ impl CudaBackend {
     }
 }
 
+/// Stub CUDA backend for Apple platforms, where CUDA is unavailable.
 #[cfg(all(feature = "gpu-cuda", any(target_os = "macos", target_os = "ios")))]
 pub struct CudaBackend;
 
@@ -116,11 +117,13 @@ impl GpuBackend for CudaBackend {
     }
 }
 
+/// Stub CUDA backend used when the `gpu-cuda` feature is not enabled
 #[cfg(not(feature = "gpu-cuda"))]
 pub struct CudaBackend;
 
 #[cfg(not(feature = "gpu-cuda"))]
 impl CudaBackend {
+    /// Always returns an error: the `gpu-cuda` feature is not enabled
     pub fn new() -> Result<Self> {
         Err(Error::InvalidFormat("CUDA feature not enabled".to_string()))
     }
@@ -134,11 +137,13 @@ pub fn is_cuda_available() -> bool {
         .unwrap_or(false)
 }
 
+/// Check if CUDA is available (always false on Apple platforms)
 #[cfg(all(feature = "gpu-cuda", any(target_os = "macos", target_os = "ios")))]
 pub fn is_cuda_available() -> bool {
     false
 }
 
+/// Check if CUDA is available (always false without the `gpu-cuda` feature)
 #[cfg(not(feature = "gpu-cuda"))]
 pub fn is_cuda_available() -> bool {
     false