docs: add panic safety documentation for various functions in the matcher module

Author: Foster Guo

matcher_rs/src/process/step.rs

@@ -109,6 +109,16 @@ static TRANSFORM_STEP_CACHE: [OnceLock<TransformStep>; 8] = [
     OnceLock::new(),
 ];
 
+/// Returns the cached [`TransformStep`] for a single-bit [`ProcessType`] flag.
+///
+/// The step is lazily initialized on first access via [`OnceLock`] and reused
+/// for all subsequent calls with the same flag.
+///
+/// # Panics
+///
+/// In debug builds, panics if `process_type_bit` is not a single-bit flag
+/// (i.e., not a power of two) or exceeds the cache size. Callers must iterate
+/// [`ProcessType`] to extract individual bits before calling this function.
 pub(crate) fn get_transform_step(process_type_bit: ProcessType) -> &'static TransformStep {
     debug_assert!(
         process_type_bit.bits().is_power_of_two() || process_type_bit == ProcessType::None,

matcher_rs/src/simple_matcher/engine.rs

@@ -456,6 +456,12 @@ impl CharwiseMatcherExt for CharwiseMatcher {
 ///   full pattern set so that non-ASCII haystacks benefit from character-granularity
 ///   scanning (~1.6–1.9× faster on CJK text vs bytewise).
 ///
+/// # Panics
+///
+/// Panics if the bytewise automaton build thread panics internally. This should
+/// not occur under normal operation — it indicates a bug in the underlying
+/// `daachorse` or `aho-corasick` builder.
+///
 /// # Errors
 ///
 /// Returns [`MatcherError`] if the `daachorse` or `aho-corasick` automaton builders

matcher_rs/src/simple_matcher/pattern.rs

@@ -76,7 +76,7 @@ pub(super) struct PatternEntry {
     pub(super) boundary: u8,
     /// Number of positive (AND) segments in the owning rule.
     ///
-    /// Duplicated from [`RuleHot::and_count`](super::rule::RuleHot::and_count) so that
+    /// Duplicated from the rule's AND-segment count so that
     /// [`RuleSet::process_entry`](super::rule::RuleSet::process_entry) can initialize
     /// per-rule state without loading the `RuleHot` struct (avoiding a cache miss on
     /// the 400KB+ hot array). Fits in the existing struct padding (9→10 bytes, still

matcher_rs/src/simple_matcher/rule.rs

@@ -269,6 +269,12 @@ impl RuleSet {
     /// Init logic is inlined rather than calling `ScanState::init_rule` so that the
     /// `&mut WordState` reference obtained at the start of each arm survives across the
     /// init — eliminating a second `word_states` lookup per call.
+    ///
+    /// # Panics
+    ///
+    /// In debug builds, panics if `entry.rule_idx` is out of bounds for the
+    /// rule arrays. This invariant is guaranteed by construction in
+    /// [`SimpleMatcher::new`](super::SimpleMatcher::new).
     #[inline(always)]
     pub(super) fn process_entry(
         &self,

matcher_rs/src/simple_matcher/search.rs

@@ -198,6 +198,12 @@ impl SimpleMatcher {
     }
 
     /// Unified tree walk that transforms, scans, and evaluates rules in a single pass.
+    ///
+    /// # Panics
+    ///
+    /// Panics if a non-root node in the transform trie lacks a cached
+    /// [`TransformStep`]. This is a construction invariant maintained by
+    /// [`build_process_type_tree`](crate::process::graph::build_process_type_tree).
     #[inline]
     pub(super) fn walk_and_scan<'a>(
         &'a self,

matcher_rs/src/simple_matcher/state.rs

@@ -64,7 +64,7 @@ pub(super) struct WordState {
     pub(super) satisfied_mask: u64,
     /// Remaining AND segments still needed before the rule can fire.
     ///
-    /// Initialized to [`RuleHot::and_count`](super::rule::RuleHot::and_count) and
+    /// Initialized to [`PatternEntry::and_count`](super::pattern::PatternEntry::and_count) and
     /// decremented as segments are satisfied. The rule becomes positive when this
     /// reaches zero.
     pub(super) remaining_and: u16,