refactor(scheduler): clarify pattern tag naming

Author: Eikix

coprocessor/fhevm-engine/scheduler/src/dfg/pattern/encoding.rs

@@ -12,11 +12,11 @@ use crate::dfg::types::DFGTaskInput;
 use crate::dfg::{DFGOp, OpEdge};
 use fhevm_engine_common::common::FheOperation;
 
-/// Encoding version byte (self-describing, decodable).
-pub(super) const ENCODING_VERSION: u8 = 0x01;
+/// Tag byte for the inline, self-describing pattern encoding.
+pub(super) const INLINE_PATTERN_TAG: u8 = 0x01;
 
-/// Hash version byte (Keccak-256 truncated, not decodable).
-pub(super) const HASH_VERSION: u8 = 0x02;
+/// Tag byte for the hashed pattern encoding (Keccak-256 truncated, not decodable).
+pub(super) const HASHED_PATTERN_TAG: u8 = 0x02;
 
 /// Number of bytes to keep from the Keccak-256 digest.
 const HASH_DIGEST_LEN: usize = 20;
@@ -48,14 +48,14 @@ pub fn pattern_to_base64url(bytes: &[u8]) -> String {
 
 /// Decode a binary pattern encoding into a [`PatternDescription`].
 ///
-/// Returns `None` if the encoding is malformed (wrong version, truncated, etc.)
-/// or if the pattern is a hashed v2 form (hashes are not decodable).
+/// Returns `None` if the encoding is malformed (wrong tag, truncated, etc.)
+/// or if the pattern is a hashed form (hashes are not decodable).
 pub fn decode_pattern(bytes: &[u8]) -> Option<PatternDescription> {
     if bytes.len() < 2 {
         return None;
     }
-    // Only v1 encodings are decodable; hashed (v2) and unknown versions are not.
-    if bytes[0] != ENCODING_VERSION {
+    // Only inline encodings are decodable; hashed and unknown tags are not.
+    if bytes[0] != INLINE_PATTERN_TAG {
         return None;
     }
     let node_count = bytes[1] as usize;
@@ -116,9 +116,9 @@ pub fn decode_pattern(bytes: &[u8]) -> Option<PatternDescription> {
 // Two-tier finalization (encoding vs hash)
 // ---------------------------------------------------------------------------
 
-/// Returns `true` if the pattern bytes represent a hashed (v2) pattern.
+/// Returns `true` if the pattern bytes represent a hashed pattern.
 pub fn is_hashed_pattern(bytes: &[u8]) -> bool {
-    !bytes.is_empty() && bytes[0] == HASH_VERSION
+    !bytes.is_empty() && bytes[0] == HASHED_PATTERN_TAG
 }
 
 /// Hash threshold read once from `FHEVM_PATTERN_HASH_THRESHOLD` env var,
@@ -130,11 +130,11 @@ pub(super) static PATTERN_HASH_THRESHOLD: LazyLock<usize> = LazyLock::new(|| {
         .unwrap_or(DEFAULT_PATTERN_HASH_THRESHOLD)
 });
 
-/// If the v1 encoding has `node_count ≤ threshold`, return it as-is.
-/// Otherwise hash it into a compact 23-byte v2 form and log the full
+/// If the inline encoding has `node_count ≤ threshold`, return it as-is.
+/// Otherwise hash it into a compact 23-byte form and log the full
 /// encoding once (per unique hash) for operator linkability.
 pub(super) fn finalize_pattern(encoding: Vec<u8>, threshold: usize) -> Vec<u8> {
-    debug_assert!(encoding.len() >= 2 && encoding[0] == ENCODING_VERSION);
+    debug_assert!(encoding.len() >= 2 && encoding[0] == INLINE_PATTERN_TAG);
     let node_count = encoding[1] as usize;
 
     if node_count <= threshold {
@@ -144,12 +144,12 @@ pub(super) fn finalize_pattern(encoding: Vec<u8>, threshold: usize) -> Vec<u8> {
     build_hash_pattern(&encoding, node_count, true)
 }
 
-/// Build a 23-byte v2 hashed pattern from arbitrary encoding bytes.
+/// Build a 23-byte hashed pattern from arbitrary encoding bytes.
 ///
 /// ## Hashed pattern binary layout
 ///
 /// ```text
-/// Byte 0:     0x02 (HASH_VERSION)
+/// Byte 0:     0x02 (HASHED_PATTERN_TAG)
 /// Bytes 1-2:  node_count as u16 big-endian
 /// Bytes 3-22: first 20 bytes of Keccak-256(encoding)
 /// Total: 23 bytes
@@ -162,7 +162,7 @@ pub(super) fn build_hash_pattern(
     let digest = Keccak256::digest(encoding);
 
     let mut buf = Vec::with_capacity(1 + 2 + HASH_DIGEST_LEN);
-    buf.push(HASH_VERSION);
+    buf.push(HASHED_PATTERN_TAG);
     let node_count_u16 = u16::try_from(node_count).unwrap_or(u16::MAX);
     buf.extend_from_slice(&node_count_u16.to_be_bytes());
     buf.extend_from_slice(&digest[..HASH_DIGEST_LEN]);
@@ -220,10 +220,10 @@ pub(super) fn compute_subgraph_layout(
     Some((local_topo, topo_pos))
 }
 
-/// Maximum number of nodes that a v1 encoding can represent (node_count is u8).
+/// Maximum number of nodes that an inline encoding can represent (node_count is u8).
 const V1_MAX_NODES: usize = 255;
 
-/// Maximum number of inputs per node that a v1 encoding can represent
+/// Maximum number of inputs per node that an inline encoding can represent
 /// (3-bit field in the flags byte).
 const V1_MAX_INPUTS_PER_NODE: usize = 7;
 
@@ -243,14 +243,14 @@ const V1_MAX_INTERNAL_REF: usize = 127;
 /// nodes, allowed nodes from other groups, DB handles) are treated as external
 /// (byte 0x00).
 ///
-/// Returns `None` if the group exceeds the v1 encoding limits (\>255 nodes,
+/// Returns `None` if the group exceeds the inline encoding limits (\>255 nodes,
 /// \>7 inputs per node, or \>127 internal-ref position). Callers can fall back
 /// to wide-format hashing so oversized groups are still attributable via hash.
 ///
-/// ## Binary layout (version 1)
+/// ## Inline binary layout
 ///
 /// ```text
-/// Byte 0:  0x01 (version)
+/// Byte 0:  0x01 (inline pattern tag)
 /// Byte 1:  node_count (u8, max 255)
 ///
 /// Per node in canonical topological order:
@@ -276,11 +276,11 @@ pub(super) fn encode_subgraph(
         return None;
     }
 
-    // Pre-allocate: version(1) + count(1) + per-node ~4 bytes average
+    // Pre-allocate: tag(1) + count(1) + per-node ~4 bytes average
     let mut buf: Vec<u8> = Vec::with_capacity(2 + node_count * 4);
 
     // Header
-    buf.push(ENCODING_VERSION);
+    buf.push(INLINE_PATTERN_TAG);
     buf.push(node_count as u8);
 
     // Nodes
@@ -326,7 +326,7 @@ pub(super) fn encode_subgraph(
     Some(buf)
 }
 
-/// Wide-format encoding used only as hash input when a group exceeds v1 limits.
+/// Wide-format encoding used only as hash input when a group exceeds inline encoding limits.
 ///
 /// This is intentionally not emitted as a pattern attribute directly: only the
 /// resulting hash is used.

coprocessor/fhevm-engine/scheduler/src/dfg/pattern/grouping.rs

@@ -226,9 +226,10 @@ pub fn compute_logical_pattern_ids(
 
     // Encode each group and assign pattern_ids.
     //
-    // Try compact v1 first. If it succeeds and is above threshold, we hash and
-    // log full encoding once. If v1 fails (group too large), hash wide encoding
-    // without logging the full payload.
+    // Try the compact inline encoding first. If it succeeds and is above the
+    // threshold, we hash and log the full encoding once. If inline encoding
+    // fails (group too large), hash the wide encoding without logging the full
+    // payload.
     let threshold = *PATTERN_HASH_THRESHOLD;
     let mut result: HashMap<usize, Vec<u8>> = HashMap::new();
     for group in groups.values() {

coprocessor/fhevm-engine/scheduler/src/dfg/pattern/mod.rs

@@ -28,7 +28,7 @@ pub use grouping::{compute_logical_pattern_ids, compute_transaction_pattern_id};
 pub use types::{PatternDescription, PatternInput, PatternNode};
 
 #[cfg(test)]
-use encoding::{ENCODING_VERSION, HASH_VERSION};
+use encoding::{HASHED_PATTERN_TAG, INLINE_PATTERN_TAG};
 
 #[cfg(test)]
 mod tests;

coprocessor/fhevm-engine/scheduler/src/dfg/pattern/tests.rs

@@ -6,7 +6,7 @@ use std::collections::HashMap;
 use base64::{engine::general_purpose::URL_SAFE_NO_PAD, Engine};
 
 use super::{
-    decode_pattern, is_hashed_pattern, pattern_to_base64url, ENCODING_VERSION, HASH_VERSION,
+    decode_pattern, is_hashed_pattern, pattern_to_base64url, HASHED_PATTERN_TAG, INLINE_PATTERN_TAG,
 };
 
 /// Build a pre-partition graph + produced_handles from `Vec<DFGOp>` and call
@@ -56,22 +56,22 @@ fn collect_op_pattern_ids(component: &super::super::ComponentNode) -> Vec<Vec<u8
         .collect()
 }
 
-/// Assert that a pattern_id is a valid pattern — either a v1 encoding
-/// (decodable) or a v2 hash (23 bytes, starts with HASH_VERSION).
+/// Assert that a pattern_id is a valid pattern — either an inline encoding
+/// (decodable) or a hashed encoding (23 bytes, starts with `HASHED_PATTERN_TAG`).
 fn assert_valid_pattern(bytes: &[u8]) {
     assert!(!bytes.is_empty(), "pattern_id should not be empty");
     match bytes[0] {
-        ENCODING_VERSION => {
-            let desc = decode_pattern(bytes).expect("v1 pattern_id should be decodable");
+        INLINE_PATTERN_TAG => {
+            let desc = decode_pattern(bytes).expect("inline pattern_id should be decodable");
             assert!(
                 !desc.nodes.is_empty(),
                 "decoded pattern should have at least one node"
             );
         }
-        HASH_VERSION => {
+        HASHED_PATTERN_TAG => {
             assert_eq!(bytes.len(), 23, "hashed pattern should be exactly 23 bytes");
         }
-        other => panic!("unexpected pattern version byte: 0x{other:02x}"),
+        other => panic!("unexpected pattern tag byte: 0x{other:02x}"),
     }
 }
 
@@ -1110,7 +1110,7 @@ fn oversize_group_hashes_for_transaction_pattern() {
 
     let tx_id = vec![0xFFu8; 32];
     let (components, _) = build_component_nodes(ops2, &tx_id).unwrap();
-    // >255 nodes: v1 encoding fails, wide encoding is hashed.
+    // >255 nodes: inline encoding fails, wide encoding is hashed.
     let tx_pat = &components[0].transaction_pattern_id;
     assert!(
         is_hashed_pattern(tx_pat),
@@ -1167,22 +1167,22 @@ fn build_chain(n: usize, prefix: u8) -> Vec<DFGOp> {
 
 #[test]
 fn pattern_below_threshold_is_encoding() {
-    // A group with ≤ DEFAULT_PATTERN_HASH_THRESHOLD nodes stays v1.
+    // A group with ≤ DEFAULT_PATTERN_HASH_THRESHOLD nodes stays inline.
     let ops = build_chain(10, 0xA0);
     let ids = compute_logical_ids(ops);
     assert!(!ids.is_empty());
     let pattern = ids.values().next().unwrap();
     assert_eq!(
-        pattern[0], ENCODING_VERSION,
-        "small group should produce v1 encoding"
+        pattern[0], INLINE_PATTERN_TAG,
+        "small group should produce inline encoding"
     );
     assert!(
         decode_pattern(pattern).is_some(),
-        "v1 encoding should be decodable"
+        "inline encoding should be decodable"
     );
     assert!(
         !is_hashed_pattern(pattern),
-        "v1 encoding should not be identified as hashed"
+        "inline encoding should not be identified as hashed"
     );
 }
 
@@ -1195,8 +1195,8 @@ fn pattern_above_threshold_is_hashed() {
     assert!(!ids.is_empty());
     let pattern = ids.values().next().unwrap();
     assert_eq!(
-        pattern[0], HASH_VERSION,
-        "large group should produce v2 hashed pattern"
+        pattern[0], HASHED_PATTERN_TAG,
+        "large group should produce hashed pattern"
     );
     assert_eq!(
         pattern.len(),
@@ -1208,7 +1208,7 @@ fn pattern_above_threshold_is_hashed() {
     assert_eq!(node_count, 30, "hashed pattern should encode node_count=30");
     assert!(
         is_hashed_pattern(pattern),
-        "v2 pattern should be identified as hashed"
+        "hashed pattern should be identified as hashed"
     );
     assert!(
         decode_pattern(pattern).is_none(),