refactor(core): consolidate check_lane_strict into check_lane (#273) (#289)

* refactor(core): consolidate check_lane_strict into check_lane (#273)

Replace check_lane with the stricter validation that also verifies
the site/word is a valid forward source for the bus. Remove
check_lane_strict as a separate function.

Fixes:
- Bus.resolve_forward/resolve_backward now use .get() to avoid
  panicking on mismatched src/dst lengths
- Example arch spec lane encoding updated from 0xC000000000010000
  (word_id=1, old convention) to 0xC000000000000000 (word_id=0,
  correct forward-source convention)
- AOD rectangle tests updated to use valid forward source sites
  across two words instead of destination sites on one word

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(core): update group_rectangle smoke test for stricter check_lane

The .sst test file used sites 5,6 (bus destinations) as forward
sources. Updated to use valid forward sources across two words
to form the same 2x2 rectangle geometry.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix(core): add site_id bounds check for WordBus lanes and clarify docs

- check_lane now validates site_id is in range for WordBus lanes
  (previously only word_id was checked, but site_id is used in
  lane_endpoints to build LocationAddr)
- Clarify archspec.md lane example: word_id encodes the forward
  source for that specific lane, not necessarily word 0 in general

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: weinbe58

crates/bloqade-lanes-bytecode-core/src/arch/mod.rs

@@ -58,7 +58,7 @@ pub(crate) fn example_arch_spec() -> ArchSpec {
         "entangling_zones": [0],
         "measurement_mode_zones": [0],
         "paths": [
-            {"lane": "0xC000000000010000", "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]}
+            {"lane": "0xC000000000000000", "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]}
         ]
     }"#;
     serde_json::from_str(json).unwrap()

crates/bloqade-lanes-bytecode-core/src/arch/query.rs

@@ -111,14 +111,20 @@ impl Bus {
     /// For site buses, this maps source site → destination site.
     /// For word buses, this maps source word → destination word.
     pub fn resolve_forward(&self, src: u32) -> Option<u32> {
-        self.src.iter().position(|&s| s == src).map(|i| self.dst[i])
+        self.src
+            .iter()
+            .position(|&s| s == src)
+            .and_then(|i| self.dst.get(i).copied())
     }
 
     /// Given a destination value, return the source value (backward move).
     /// For site buses, this maps destination site → source site.
     /// For word buses, this maps destination word → source word.
     pub fn resolve_backward(&self, dst: u32) -> Option<u32> {
-        self.dst.iter().position(|&d| d == dst).map(|i| self.src[i])
+        self.dst
+            .iter()
+            .position(|&d| d == dst)
+            .and_then(|i| self.src.get(i).copied())
     }
 }
 
@@ -189,7 +195,7 @@ impl ArchSpec {
 
         // Validate the lane address up front so callers always get None
         // for invalid lanes (e.g. out-of-range word_id or site_id).
-        if !self.check_lane_strict(lane).is_empty() {
+        if !self.check_lane(lane).is_empty() {
             return None;
         }
 
@@ -262,76 +268,53 @@ impl ArchSpec {
         }
     }
 
-    /// Check whether a lane address is valid (bus exists, word/site in range).
+    /// Check whether a lane address is valid.
+    ///
+    /// Validates that the bus exists, word/site are in range, and the
+    /// site/word is a valid forward source for the bus. In the lane address
+    /// convention, `site_id` and `word_id` always encode the forward-direction
+    /// source — the `direction` field only controls which endpoint is src vs
+    /// dst, not which site/word is encoded.
     pub fn check_lane(&self, addr: &LaneAddr) -> Vec<String> {
         let num_words = self.geometry.words.len() as u32;
         let sites_per_word = self.geometry.sites_per_word;
         let mut errors = Vec::new();
 
         match addr.move_type {
             MoveType::SiteBus => {
-                if self.site_bus_by_id(addr.bus_id).is_none() {
-                    errors.push(format!("unknown site_bus id {}", addr.bus_id));
-                }
                 if addr.word_id >= num_words {
                     errors.push(format!("word_id {} out of range", addr.word_id));
                 }
                 if addr.site_id >= sites_per_word {
                     errors.push(format!("site_id {} out of range", addr.site_id));
                 }
+                if let Some(bus) = self.site_bus_by_id(addr.bus_id) {
+                    if errors.is_empty() && bus.resolve_forward(addr.site_id).is_none() {
+                        errors.push(format!(
+                            "site_id {} is not a valid source for site_bus {}",
+                            addr.site_id, addr.bus_id
+                        ));
+                    }
+                } else {
+                    errors.push(format!("unknown site_bus id {}", addr.bus_id));
+                }
             }
             MoveType::WordBus => {
-                if self.word_bus_by_id(addr.bus_id).is_none() {
-                    errors.push(format!("unknown word_bus id {}", addr.bus_id));
-                }
                 if addr.word_id >= num_words {
                     errors.push(format!("word_id {} out of range", addr.word_id));
                 }
-            }
-        }
-        errors
-    }
-
-    /// Strict lane validation: checks everything in [`check_lane`] plus
-    /// verifies that the site/word can be resolved through the bus.
-    ///
-    /// In the lane address convention, `site_id` and `word_id` always refer
-    /// to the forward-direction source. The `direction` field only controls
-    /// which endpoint is src vs dst in the result — it does not change which
-    /// site/word is encoded. Therefore, validation always checks against the
-    /// bus's forward resolution (`bus.src` list).
-    ///
-    /// This is used by [`lane_endpoints`](Self::lane_endpoints) to guarantee
-    /// that returned endpoints are fully valid.
-    pub fn check_lane_strict(&self, addr: &LaneAddr) -> Vec<String> {
-        // Start with the basic checks
-        let mut errors = self.check_lane(addr);
-        if !errors.is_empty() {
-            return errors;
-        }
-
-        // Verify the site/word is a valid forward source for the bus.
-        // The direction field only flips src/dst — it doesn't change
-        // which site/word is encoded in the lane address.
-        match addr.move_type {
-            MoveType::SiteBus => {
-                if let Some(bus) = self.site_bus_by_id(addr.bus_id)
-                    && bus.resolve_forward(addr.site_id).is_none()
-                {
-                    errors.push(format!(
-                        "site_id {} is not a valid source for site_bus {}",
-                        addr.site_id, addr.bus_id
-                    ));
+                if addr.site_id >= sites_per_word {
+                    errors.push(format!("site_id {} out of range", addr.site_id));
                 }
-            }
-            MoveType::WordBus => {
-                if let Some(bus) = self.word_bus_by_id(addr.bus_id)
-                    && bus.resolve_forward(addr.word_id).is_none()
-                {
-                    errors.push(format!(
-                        "word_id {} is not a valid source for word_bus {}",
-                        addr.word_id, addr.bus_id
-                    ));
+                if let Some(bus) = self.word_bus_by_id(addr.bus_id) {
+                    if errors.is_empty() && bus.resolve_forward(addr.word_id).is_none() {
+                        errors.push(format!(
+                            "word_id {} is not a valid source for word_bus {}",
+                            addr.word_id, addr.bus_id
+                        ));
+                    }
+                } else {
+                    errors.push(format!("unknown word_bus id {}", addr.bus_id));
                 }
             }
         }
@@ -850,10 +833,10 @@ mod tests {
         assert!(spec.lane_endpoints(&lane).is_none());
     }
 
-    // ── check_lane_strict tests ──
+    // ── check_lane tests ──
 
     #[test]
-    fn check_lane_strict_valid_forward() {
+    fn check_lane_valid_forward() {
         let spec = example_arch_spec();
         let lane = crate::arch::addr::LaneAddr {
             direction: crate::arch::addr::Direction::Forward,
@@ -862,11 +845,11 @@ mod tests {
             site_id: 0,
             bus_id: 0,
         };
-        assert!(spec.check_lane_strict(&lane).is_empty());
+        assert!(spec.check_lane(&lane).is_empty());
     }
 
     #[test]
-    fn check_lane_strict_valid_backward() {
+    fn check_lane_valid_backward() {
         let spec = example_arch_spec();
         // Backward with forward source site_id=0 should be valid
         let lane = crate::arch::addr::LaneAddr {
@@ -876,11 +859,11 @@ mod tests {
             site_id: 0,
             bus_id: 0,
         };
-        assert!(spec.check_lane_strict(&lane).is_empty());
+        assert!(spec.check_lane(&lane).is_empty());
     }
 
     #[test]
-    fn check_lane_strict_destination_site_rejected() {
+    fn check_lane_destination_site_rejected() {
         let spec = example_arch_spec();
         // Site 5 is a destination, not a forward source
         let lane = crate::arch::addr::LaneAddr {
@@ -890,13 +873,13 @@ mod tests {
             site_id: 5,
             bus_id: 0,
         };
-        let errors = spec.check_lane_strict(&lane);
+        let errors = spec.check_lane(&lane);
         assert!(!errors.is_empty());
         assert!(errors[0].contains("not a valid source"));
     }
 
     #[test]
-    fn check_lane_strict_destination_site_backward_also_rejected() {
+    fn check_lane_destination_site_backward_also_rejected() {
         let spec = example_arch_spec();
         // Site 5 with backward direction — still not a forward source
         let lane = crate::arch::addr::LaneAddr {
@@ -906,13 +889,13 @@ mod tests {
             site_id: 5,
             bus_id: 0,
         };
-        let errors = spec.check_lane_strict(&lane);
+        let errors = spec.check_lane(&lane);
         assert!(!errors.is_empty());
         assert!(errors[0].contains("not a valid source"));
     }
 
     #[test]
-    fn check_lane_strict_invalid_bus() {
+    fn check_lane_invalid_bus() {
         let spec = example_arch_spec();
         let lane = crate::arch::addr::LaneAddr {
             direction: crate::arch::addr::Direction::Forward,
@@ -921,7 +904,7 @@ mod tests {
             site_id: 0,
             bus_id: 99,
         };
-        let errors = spec.check_lane_strict(&lane);
+        let errors = spec.check_lane(&lane);
         assert!(!errors.is_empty());
     }
 }

crates/bloqade-lanes-bytecode-core/src/bytecode/validate.rs

@@ -1073,10 +1073,17 @@ mod tests {
     #[test]
     fn test_lane_group_aod_constraint_rectangle_passes() {
         let arch = lane_group_arch_spec();
-        let lanes: Vec<(u32, u32)> = [0, 1, 5, 6]
-            .iter()
-            .map(|&s| make_lane(Direction::Forward, MoveType::SiteBus, 0, s, 0))
-            .collect();
+        // Use valid forward sources on two words to form a 2x2 rectangle:
+        // Word 0, Site 0: (1.0, 2.5)
+        // Word 0, Site 1: (3.0, 2.5)
+        // Word 1, Site 0: (1.0, 12.5)
+        // Word 1, Site 1: (3.0, 12.5)
+        let lanes: Vec<(u32, u32)> = vec![
+            make_lane(Direction::Forward, MoveType::SiteBus, 0, 0, 0),
+            make_lane(Direction::Forward, MoveType::SiteBus, 0, 1, 0),
+            make_lane(Direction::Forward, MoveType::SiteBus, 1, 0, 0),
+            make_lane(Direction::Forward, MoveType::SiteBus, 1, 1, 0),
+        ];
         let program = Program {
             version: Version::new(1, 0),
             instructions: vec![
@@ -1094,10 +1101,15 @@ mod tests {
     #[test]
     fn test_lane_group_aod_constraint_not_rectangle() {
         let arch = lane_group_arch_spec();
-        let lanes: Vec<(u32, u32)> = [0, 1, 5]
-            .iter()
-            .map(|&s| make_lane(Direction::Forward, MoveType::SiteBus, 0, s, 0))
-            .collect();
+        // 3 corners of a rectangle (missing word 1, site 1) — not a complete rectangle
+        // Word 0, Site 0: (1.0, 2.5)
+        // Word 0, Site 1: (3.0, 2.5)
+        // Word 1, Site 0: (1.0, 12.5)
+        let lanes: Vec<(u32, u32)> = vec![
+            make_lane(Direction::Forward, MoveType::SiteBus, 0, 0, 0),
+            make_lane(Direction::Forward, MoveType::SiteBus, 0, 1, 0),
+            make_lane(Direction::Forward, MoveType::SiteBus, 1, 0, 0),
+        ];
         let program = Program {
             version: Version::new(1, 0),
             instructions: vec![

docs/src/arch/archspec.md

@@ -151,7 +151,7 @@ The lane is identified by its encoded `LaneAddr`, serialized as a hex string. Se
 ```jsonc
 "paths": [
   {
-    "lane": "0xC000000000010000",                        // encoded LaneAddr (hex, 16-digit)
+    "lane": "0xC000000000000000",                        // encoded LaneAddr (hex, 16-digit)
     "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]  // physical trajectory
   }
 ]
@@ -164,7 +164,7 @@ Each `TransportPath` entry has:
 | `lane` | string | Encoded `LaneAddr` as a `"0x..."` hex string. |
 | `waypoints` | [x, y][] | Sequence of physical coordinate waypoints. |
 
-To decode the lane hex string, parse it as a 64-bit unsigned integer. The low 32 bits (data0) contain `[word_id:16][site_id:16]` and the high 32 bits (data1) contain `[dir:1][mt:1][pad:14][bus_id:16]`. For example, `"0xC000000000010000"` decodes to direction=Backward, move_type=WordBus, word=1, site=0, bus=0.
+To decode the lane hex string, parse it as a 64-bit unsigned integer. The low 32 bits (data0) contain `[word_id:16][site_id:16]` and the high 32 bits (data1) contain `[dir:1][mt:1][pad:14][bus_id:16]`. For example, `"0xC000000000000000"` decodes to direction=Backward, move_type=WordBus, word=0, site=0, bus=0. In the lane address convention, `word_id` always encodes the forward-direction source word for that lane; in this specific example the bus mapping is src=[0], dst=[1], so `direction=Backward` means the move goes from word 1 back to word 0.
 
 This field is omitted from the JSON when not needed.
 

examples/programs/valid/group_rectangle.sst

@@ -1,13 +1,17 @@
 .version 1
 ; Move 4 lanes forming a 2x2 rectangle on the grid.
-; Word 0 grid: x=[1,3,5,7,9] y=[2.5,5.0]
-; Sites 0-4 = row 0 (y=2.5), sites 5-9 = row 1 (y=5.0)
-; Sites 0,1,5,6 -> (1,2.5),(3,2.5),(1,5.0),(3,5.0) = 2x2 rectangle
 ; site_bus 0: src=[0,1,2,3,4] dst=[5,6,7,8,9]
+; Word 0: y_start=2.5, Word 1: y_start=12.5
+; Site 0: x=1.0, Site 1: x=3.0
+; (word 0, site 0) = (1.0, 2.5)
+; (word 0, site 1) = (3.0, 2.5)
+; (word 1, site 0) = (1.0, 12.5)
+; (word 1, site 1) = (3.0, 12.5)
+; = 2x2 rectangle using valid forward sources
 
 const_lane 0x0000000000000000   ; fwd, site_bus, word 0, site 0, bus 0
 const_lane 0x0000000000000001   ; fwd, site_bus, word 0, site 1, bus 0
-const_lane 0x0000000000000005   ; fwd, site_bus, word 0, site 5, bus 0
-const_lane 0x0000000000000006   ; fwd, site_bus, word 0, site 6, bus 0
+const_lane 0x0000000000010000   ; fwd, site_bus, word 1, site 0, bus 0
+const_lane 0x0000000000010001   ; fwd, site_bus, word 1, site 1, bus 0
 move 4
 halt

python/bloqade/lanes/bytecode/_native.pyi

@@ -475,7 +475,7 @@ class TransportPath:
         lane (LaneAddress): Lane address identifying the transport lane.
         waypoints (list[tuple[float, float]]): Sequence of ``(x, y)`` coordinate waypoints.
 
-    Note: In JSON, the lane is serialized as a 16-digit hex string (e.g. ``"0xC000000000010000"``).
+    Note: In JSON, the lane is serialized as a 16-digit hex string (e.g. ``"0xC000000000000000"``).
     """
 
     def __init__(

python/tests/bytecode/test_arch_spec.py

@@ -108,7 +108,7 @@
         "measurement_mode_zones": [0],
         "paths": [
             {
-                "lane": "0xC000000000010000",
+                "lane": "0xC000000000000000",
                 "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]],
             }
         ],
@@ -174,7 +174,7 @@ def _build_spec_from_python():
             TransportPath(
                 lane=LaneAddress(
                     MoveType.WORD,
-                    word_id=1,
+                    word_id=0,
                     site_id=0,
                     bus_id=0,
                     direction=Direction.BACKWARD,
@@ -331,11 +331,11 @@ def test_paths(self):
         spec = ArchSpec.from_json(EXAMPLE_JSON)
         assert spec.paths is not None
         assert len(spec.paths) == 1
-        assert spec.paths[0].lane_encoded == 0xC000000000010000
+        assert spec.paths[0].lane_encoded == 0xC000000000000000
         lane = spec.paths[0].lane
         assert lane.direction == Direction.BACKWARD
         assert lane.move_type == MoveType.WORD
-        assert lane.word_id == 1
+        assert lane.word_id == 0
         assert lane.site_id == 0
         assert lane.bus_id == 0
         assert len(spec.paths[0].waypoints) == 3
@@ -522,20 +522,25 @@ def test_consistency_fail_direction(self):
 
     def test_aod_constraint_rectangle_pass(self):
         spec = ArchSpec.from_json(EXAMPLE_JSON)
-        # 2x2 rectangle: sites 0,1,5,6
+        # 2x2 rectangle using valid forward sources on 2 words:
+        # Word 0, Site 0: (1.0, 2.5)   Word 0, Site 1: (3.0, 2.5)
+        # Word 1, Site 0: (1.0, 12.5)  Word 1, Site 1: (3.0, 12.5)
         lanes = [
-            LaneAddress(MoveType.SITE, word_id=0, site_id=s, bus_id=0)
-            for s in [0, 1, 5, 6]
+            LaneAddress(MoveType.SITE, word_id=0, site_id=0, bus_id=0),
+            LaneAddress(MoveType.SITE, word_id=0, site_id=1, bus_id=0),
+            LaneAddress(MoveType.SITE, word_id=1, site_id=0, bus_id=0),
+            LaneAddress(MoveType.SITE, word_id=1, site_id=1, bus_id=0),
         ]
         errors = spec.check_lanes(lanes)
         assert errors == []
 
     def test_aod_constraint_not_rectangle(self):
         spec = ArchSpec.from_json(EXAMPLE_JSON)
-        # L-shape: sites 0,1,5
+        # 3 corners of a rectangle (missing word 1, site 1)
         lanes = [
-            LaneAddress(MoveType.SITE, word_id=0, site_id=s, bus_id=0)
-            for s in [0, 1, 5]
+            LaneAddress(MoveType.SITE, word_id=0, site_id=0, bus_id=0),
+            LaneAddress(MoveType.SITE, word_id=0, site_id=1, bus_id=0),
+            LaneAddress(MoveType.SITE, word_id=1, site_id=0, bus_id=0),
         ]
         errors = spec.check_lanes(lanes)
         assert len(errors) > 0

tests/arch_spec_integration.rs

@@ -33,7 +33,7 @@ const EXAMPLE_JSON: &str = r#"{
     "entangling_zones": [0],
     "measurement_mode_zones": [0],
     "paths": [
-        {"lane": "0xC000000000010000", "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]}
+        {"lane": "0xC000000000000000", "waypoints": [[1.0, 12.5], [1.0, 7.5], [1.0, 2.5]]}
     ]
 }"#;