fix(ldm): gate behind hash feature + harden insert_absolute preconditions

`encoding::ldm` was compiled unconditionally but depends on
`twox_hash::XxHash64` for the per-window XXH64 (`zstd_ldm.c:315`).
`twox-hash` is an optional dependency behind the `hash` feature,
so `default-features = false` builds (no_std, embedded) failed to
compile. The fix mirrors the gating pattern already used for the
same crate in `streaming_encoder.rs`, `frame_compressor.rs`, and
`decode_buffer.rs`:

* `mod ldm;` declaration is `#[cfg(feature = "hash")]`.
* `BtMatcher::ldm_producer` field and every integration callsite
  (`use ... LdmProducer`, `Some(producer) = self.ldm_producer
  ...`) carry the same gate. Under `default-features = false` the
  field disappears and `prepare_ldm_candidates` reduces to its
  legacy `ldm_sequences.clear()` stub.
* `prepare_ldm_candidates_translates_absolute_positions_to_slice_
  indices` regression also gated.

Verified: `cargo build --lib --no-default-features` clean;
`cargo clippy --lib --tests --no-default-features -- -D warnings`
clean.

Separately, `LdmHashTable::insert_absolute` promoted its two
preconditions from `debug_assert!` to runtime panics so a
contract violation cannot silently corrupt the table in release
builds:

* `abs_pos < position_base` now panics via `checked_sub` +
  `unwrap_or_else` with a diagnostic instead of underflowing the
  subtraction and casting the wraparound to `u32`.
* `rel >= u32::MAX as usize` now panics via `assert!` (was
  `debug_assert!`) — the producer's `ensure_room_for` rebases
  before this point, but if a custom caller bypasses it the
  failure is loud and immediate.
* The `+1` empty-slot bias was moved inside the `u32` arithmetic
  (`(rel as u32) + 1` instead of `(rel + 1) as u32`) so the
  intermediate `usize` add can't overflow on 32-bit targets.

New `insert_absolute_panics_below_position_base` regression
covers the underflow guard with `#[should_panic]`.

README quick-start snippet now passes `&b"hello world"[..]` to
`compress_to_vec` — `b"..."` literal alone is `&[u8; N]` which
does not implement `std::io::Read`, so the doctest failed under
`cargo test --doc` after the earlier doc rewrite landed.

469 lib tests + 11 doctests pass; clippy clean under default
features AND under `--no-default-features`.

Author: polaz

README.md

@@ -17,7 +17,7 @@ structured-zstd = "0.0.20"
 ```rust
 use structured_zstd::encoding::{compress_to_vec, CompressionLevel};
 
-let compressed = compress_to_vec(b"hello world", CompressionLevel::from_level(7));
+let compressed = compress_to_vec(&b"hello world"[..], CompressionLevel::from_level(7));
 ```
 
 For `no_std` builds disable the default features:

zstd/src/encoding/bt/mod.rs

@@ -20,6 +20,7 @@
 use alloc::vec::Vec;
 
 use super::cost_model::{HC_MAX_LIT, HcOptState, HcOptimalCostProfile};
+#[cfg(feature = "hash")]
 use super::ldm::LdmProducer;
 use super::opt::ldm::{HcOptLdmState, HcRawSeq, HcRawSeqStore};
 use super::opt::types::{HcOptimalNode, HcOptimalPlanBuffers, HcOptimalSequence, MatchCandidate};
@@ -70,7 +71,13 @@ pub(crate) struct BtMatcher {
     /// `prepare_ldm_candidates` call for a frame. `None` while LDM
     /// is opt-out (current default) so the table allocation only
     /// happens for callers that opt in. See
-    /// [`super::ldm::LdmProducer`].
+    /// [`super::ldm::LdmProducer`]. Gated behind the `hash`
+    /// feature because the producer's per-window XXH64 hashing
+    /// depends on the optional `twox-hash` dependency; under
+    /// `default-features = false` the field disappears and the
+    /// `prepare_ldm_candidates` body shrinks to the legacy
+    /// `ldm_sequences.clear()` stub.
+    #[cfg(feature = "hash")]
     pub(crate) ldm_producer: Option<LdmProducer>,
 }
 
@@ -123,6 +130,7 @@ impl BtMatcher {
             opt_ml_price_generation: Vec::new(),
             opt_ml_price_stamp: 0,
             ldm_sequences: Vec::new(),
+            #[cfg(feature = "hash")]
             ldm_producer: None,
         }
     }
@@ -146,6 +154,7 @@ impl BtMatcher {
         self.opt_ml_price_generation.clear();
         self.opt_ml_price_stamp = 0;
         self.ldm_sequences.clear();
+        #[cfg(feature = "hash")]
         if let Some(producer) = self.ldm_producer.as_mut() {
             producer.clear();
         }
@@ -359,6 +368,7 @@ impl BtMatcher {
         current_len: usize,
     ) {
         self.ldm_sequences.clear();
+        #[cfg(feature = "hash")]
         if let Some(producer) = self.ldm_producer.as_mut() {
             debug_assert!(current_abs_start >= history_abs_start);
             let block_end_abs = current_abs_start
@@ -372,6 +382,19 @@ impl BtMatcher {
                 &mut self.ldm_sequences,
             );
         }
+        #[cfg(not(feature = "hash"))]
+        {
+            // Under `default-features = false` (no `hash`),
+            // `LdmProducer` is not compiled — `live_history` /
+            // `history_abs_start` / `current_abs_start` /
+            // `current_len` would otherwise be unused.
+            let _ = (
+                live_history,
+                history_abs_start,
+                current_abs_start,
+                current_len,
+            );
+        }
     }
 
     /// Donor parity: `ZSTD_storeSeq` — encode `actual_offset` into the
@@ -700,6 +723,7 @@ mod ldm_helper_tests {
     /// panic on the `history[block_start..block_end]` slice access
     /// inside `generate_into`.
     #[test]
+    #[cfg(feature = "hash")]
     fn prepare_ldm_candidates_translates_absolute_positions_to_slice_indices() {
         use crate::encoding::ldm::{LdmProducer, params::LdmParams};
 

zstd/src/encoding/ldm/table.rs

@@ -271,15 +271,31 @@ impl LdmHashTable {
     /// must call `ensure_room_for` before the first insert that
     /// could exceed the window.
     pub(crate) fn insert_absolute(&mut self, hash_id: u32, abs_pos: usize, checksum: u32) {
-        debug_assert!(abs_pos >= self.position_base);
-        let rel = abs_pos - self.position_base;
-        debug_assert!(
+        // Use runtime panics (rather than `debug_assert!`) for both
+        // preconditions so a contract violation never silently
+        // wraps in release: an unchecked `abs_pos - position_base`
+        // would underflow and the subsequent `as u32` cast would
+        // corrupt the table, hiding the bug far from its source.
+        let rel = abs_pos.checked_sub(self.position_base).unwrap_or_else(|| {
+            panic!(
+                "insert position {abs_pos} is below position_base {}; \
+                 callers must rebase via `ensure_room_for` or clear before \
+                 reaching this state",
+                self.position_base
+            )
+        });
+        assert!(
             rel < u32::MAX as usize,
             "insert position {abs_pos} (rel {rel}) exceeds u32 window; \
              producer must call `ensure_room_for` before insert"
         );
         // +1 bias so 0 stays reserved for the empty-slot sentinel.
-        let stored = (rel + 1) as u32;
+        // The cast happens BEFORE the `+ 1` so the addition runs in
+        // `u32` arithmetic — guarded by the `rel < u32::MAX` assert
+        // above, the `+ 1` cannot overflow, and intermediate `usize`
+        // values stay bounded on 32-bit targets where
+        // `usize == u32`.
+        let stored = (rel as u32) + 1;
         self.insert(
             hash_id,
             LdmEntry {
@@ -575,6 +591,20 @@ mod tests {
         assert_eq!(t.resolve(&t.bucket(2)[0]), Some(trigger_pos));
     }
 
+    /// `insert_absolute` must panic in BOTH debug and release
+    /// builds when called with an `abs_pos` below the current
+    /// `position_base` — silently underflowing the subtraction
+    /// would store a wraparound relative offset and corrupt the
+    /// table far from the bug's source. Regression for PR #139
+    /// round-6 review (Copilot + CodeRabbit, Major).
+    #[test]
+    #[should_panic(expected = "below position_base")]
+    fn insert_absolute_panics_below_position_base() {
+        let mut t = LdmHashTable::new(4, 2);
+        t.reduce(100); // shift position_base to 100
+        t.insert_absolute(0, 50, 0xCAFE); // 50 < 100 → panic
+    }
+
     /// `clear()` must reset `position_base` to 0 so a subsequent
     /// frame can insert at any absolute position (including
     /// values below the previous frame's `position_base`)

zstd/src/encoding/mod.rs

@@ -45,6 +45,15 @@ pub(crate) mod bt;
 pub(crate) mod cost_model;
 pub(crate) mod dfast;
 pub(crate) mod hc;
+// LDM uses `twox_hash::XxHash64` (per-window XXH64 over the
+// `min_match_length` byte slice, donor `zstd_ldm.c:315`). The
+// `twox-hash` dependency is gated behind the `hash` feature so
+// `default-features = false` builds (no_std, embedded) don't pull
+// it in. The `BtMatcher::ldm_producer` field and every callsite
+// in `match_generator.rs` share the same `cfg(feature = "hash")`
+// gate so the codepath stays consistent across feature
+// combinations.
+#[cfg(feature = "hash")]
 pub(crate) mod ldm;
 pub(crate) mod match_table;
 pub(crate) mod opt;