From f21b94c007517f8a0e234a81654ecb7e9643ee7e Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Mon, 29 Jun 2026 08:41:05 -0600
Subject: [PATCH 01/43] begin gbfs integration

---
 rust/Cargo.toml                          |  1 +
 rust/bambam-gbfs/Cargo.toml              |  1 +
 rust/bambam-gbfs/src/app/download/run.rs | 20 ++++++++++++++++++--
 rust/bambam-gbfs/src/app/gbfs_cli.rs     | 15 +++++++++------
 4 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index e7113a6a..59fbbb95 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -36,6 +36,7 @@ downloader = { version = "0.2.8" }
 env_logger = "0.11.8"
 flate2 = "1.0"
 futures = { version = "0.3.31", features = ["executor"] }
+gbfs_types = "0.1.4"
 geo = { version = "0.33.1", features = ["use-serde"] }
 geo-buffer = "0.2.0"
 geo-traits = "0.3.0"
diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index 09039bd1..8c32500c 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -9,6 +9,7 @@ description = "GBFS Extensions for The Behavior and Advanced Mobility Big Access
 chrono = { workspace = true }
 clap = { workspace = true }
 env_logger = { workspace = true }
+gbfs_types = { workspace = true }
 geo = { workspace = true }
 humantime = { workspace = true }
 kdam = { workspace = true }
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 8f569e00..ececdd61 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -6,16 +6,32 @@ use chrono::TimeDelta;
 /// to files to be consumed by BAMBAM.
 ///
 /// # Arguments
-/// * url - URL to the GBFS dataset
+/// * url - URL to the GBFS dataset's system-information file
 /// * out_dir - output directory to write the processed GBFS data
 /// * dur - how long to poll the GBFS API
 ///
 /// # Result
 /// If successful, returns nothing, otherwise an error
-pub fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Result<(), String> {
+pub async fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Result<(), String> {
     let dur_secs = dur.as_seconds_f64();
     log::debug!(
         "run_gbfs_download with url={url}, out_dir={out_dir:?}, duration (seconds)={dur_secs}"
     );
+    let client = reqwest::Client::new();
+    let response = client
+        .get(url)
+        .header("User-Agent", "rust-reqwest")
+        .send()
+        .await?;
+
+    if response.status().is_success() {
+        let system_information: SystemInformationFile = response.json().await?;
+        println!("systemInformation version: {}", system_information.version);
+        println!(
+            "systemInformation data: {}",
+            system_information.data.system_id
+        );
+    }
+
     todo!("download + post-processing logic")
 }
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index 1cf0a2e2..9be3f445 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -33,17 +33,20 @@ pub enum GbfsOperation {
 }
 
 impl GbfsOperation {
-    pub fn run(&self) -> Result<(), String> {
+    pub async fn run(&self) -> Result<(), String> {
         match self {
             GbfsOperation::Download {
                 gbfs_url,
                 output_directory,
                 collect_duration,
-            } => crate::app::download::run_gbfs_download(
-                gbfs_url,
-                Path::new(output_directory),
-                collect_duration,
-            ),
+            } => {
+                crate::app::download::run_gbfs_download(
+                    gbfs_url,
+                    Path::new(output_directory),
+                    collect_duration,
+                )
+                .await
+            }
         }
     }
 }

From f72e037f9a41326fd41f3b15b9e531ae129f0fda Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 13:24:28 -0600
Subject: [PATCH 02/43] resolve gbfs_types import + ignore pyo3 feature

---
 rust/Cargo.toml             | 3 ++-
 rust/bambam-gbfs/Cargo.toml | 1 +
 rust/bambam-py/Cargo.toml   | 2 +-
 3 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index 5023e364..b322d6e0 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -36,7 +36,7 @@ downloader = { version = "0.2.8" }
 env_logger = "0.11.8"
 flate2 = "1.0"
 futures = { version = "0.3.31", features = ["executor"] }
-gbfs_types = "0.1.4"
+gbfs_types = { version = "0.1.4", default-features = false, features = ["reqwest_blocking"]}
 geo = { version = "0.33.1", features = ["use-serde"] }
 geo-buffer = "0.2.0"
 geo-traits = "0.3.0"
@@ -59,6 +59,7 @@ ordered-float = { version = "5.1.0", features = ["serde"] }
 osmio = "0.14.0"
 osmpbf = "0.3.4"
 parquet = { version = "=58.0.0", features = ["snap", "async", "object_store"] }
+pyo3 = { version = "0.29.0", features = ["extension-module", "serde"] }
 rand = "0.10.0"
 rayon = "1.10.0"
 regex = { version = "1.11.1" }
diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index 8c32500c..b794f3bd 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -19,3 +19,4 @@ routee-compass-core = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_with = { workspace = true }
+tokio = { workspace = true }
\ No newline at end of file
diff --git a/rust/bambam-py/Cargo.toml b/rust/bambam-py/Cargo.toml
index d849f589..6d00bd4e 100644
--- a/rust/bambam-py/Cargo.toml
+++ b/rust/bambam-py/Cargo.toml
@@ -14,7 +14,7 @@ inventory = { workspace = true }
 
 itertools = { workspace = true }
 
-pyo3 = { version = "0.29.0", features = ["extension-module", "serde"] }
+pyo3 = { workspace = true }
 routee-compass = { workspace = true, default-features = false }
 routee-compass-core = { workspace = true }
 routee-compass-macros = { workspace = true }

From 1b0c27f7e15bd81e8d3c3adbba803cd42cefc7d8 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 13:24:44 -0600
Subject: [PATCH 03/43] wire in tokio runtime + fix error channel

---
 rust/bambam-gbfs/src/app/download/run.rs | 10 +++++++---
 rust/bambam-gbfs/src/main.rs             |  6 ++++--
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index ececdd61..1895c507 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -1,6 +1,7 @@
 use std::path::Path;
 
 use chrono::TimeDelta;
+use gbfs_types::v3_0::files::SystemInformationFile;
 
 /// downloads GBFS data for some duration. aggregates the resulting rows and writes them
 /// to files to be consumed by BAMBAM.
@@ -22,10 +23,13 @@ pub async fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Re
         .get(url)
         .header("User-Agent", "rust-reqwest")
         .send()
-        .await?;
+        .await
+        .map_err(|e| format!("failed to connect to GBFS URL: {e}"))?;
 
     if response.status().is_success() {
-        let system_information: SystemInformationFile = response.json().await?;
+        let system_information: SystemInformationFile = response.json().await.map_err(|e| {
+            format!("failed to deserialize system information file from HTTP response: {e}")
+        })?;
         println!("systemInformation version: {}", system_information.version);
         println!(
             "systemInformation data: {}",
@@ -33,5 +37,5 @@ pub async fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Re
         );
     }
 
-    todo!("download + post-processing logic")
+    Ok(())
 }
diff --git a/rust/bambam-gbfs/src/main.rs b/rust/bambam-gbfs/src/main.rs
index acf2772f..e163c893 100644
--- a/rust/bambam-gbfs/src/main.rs
+++ b/rust/bambam-gbfs/src/main.rs
@@ -1,10 +1,12 @@
 use bambam_gbfs::app::GbfsCliArguments;
 use clap::Parser;
 
-fn main() {
+#[tokio::main]
+async fn main() {
     env_logger::init();
     let args = GbfsCliArguments::parse();
-    match args.op.run() {
+
+    match args.op.run().await {
         Ok(_) => log::info!("finished."),
         Err(e) => {
             log::error!("failed running bambam_gbfs: {e}");

From 50fe4d6726231e829c034400fce87438523f5422 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 15:27:11 -0600
Subject: [PATCH 04/43] CLI GBFS app retrieves geofence + system info from GBFS
 URL

---
 .../src/app/download/entry_point.rs           | 22 ++++++
 .../src/app/download/gbfs_version.rs          | 37 ++++++++++
 rust/bambam-gbfs/src/app/download/mod.rs      |  6 ++
 rust/bambam-gbfs/src/app/download/ops.rs      | 27 ++++++++
 rust/bambam-gbfs/src/app/download/run.rs      | 37 +++++-----
 rust/bambam-gbfs/src/app/download/v3_ops.rs   | 67 +++++++++++++++++++
 rust/bambam-gbfs/src/app/gbfs_cli.rs          | 20 +++++-
 7 files changed, 197 insertions(+), 19 deletions(-)
 create mode 100644 rust/bambam-gbfs/src/app/download/entry_point.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/gbfs_version.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/ops.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/v3_ops.rs

diff --git a/rust/bambam-gbfs/src/app/download/entry_point.rs b/rust/bambam-gbfs/src/app/download/entry_point.rs
new file mode 100644
index 00000000..c762e788
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/entry_point.rs
@@ -0,0 +1,22 @@
+use clap::ValueEnum;
+use serde::{Deserialize, Serialize};
+
+/// target of an initial HTTP call to a GBFS archive.
+/// for an explanation, see <https://gbfs.org/get-started/#2-transform-your-data-into-gbfs-structure>.
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, ValueEnum, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum EntryPoint {
+    /// manifest.json file
+    Manifest,
+    /// gbfs.json file for a specific GBFS version.
+    Gbfs,
+}
+
+impl std::fmt::Display for EntryPoint {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            EntryPoint::Manifest => write!(f, "manifest"),
+            EntryPoint::Gbfs => write!(f, "gbfs"),
+        }
+    }
+}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_version.rs b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
new file mode 100644
index 00000000..5957ef27
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
@@ -0,0 +1,37 @@
+use std::str::FromStr;
+
+use clap::ValueEnum;
+use serde::{Deserialize, Serialize};
+
+/// GBFS version of the targeted archive. only supported versions are included.
+#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum GbfsVersion {
+    #[serde(rename = "v3.0")]
+    V3_0,
+}
+
+impl GbfsVersion {
+    pub const ALL: [&'static str; 1] = ["v3.0"];
+}
+
+impl std::fmt::Display for GbfsVersion {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            GbfsVersion::V3_0 => write!(f, "v3.0"),
+        }
+    }
+}
+
+impl FromStr for GbfsVersion {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s {
+            "v3.0" => Ok(Self::V3_0),
+            _ => Err(format!(
+                "unknown version '{s}', must be one of [{}]",
+                Self::ALL.join(", ")
+            )),
+        }
+    }
+}
diff --git a/rust/bambam-gbfs/src/app/download/mod.rs b/rust/bambam-gbfs/src/app/download/mod.rs
index ffd60131..4e3a9977 100644
--- a/rust/bambam-gbfs/src/app/download/mod.rs
+++ b/rust/bambam-gbfs/src/app/download/mod.rs
@@ -1,3 +1,9 @@
+mod entry_point;
+mod gbfs_version;
 mod run;
 
 pub use run::run_gbfs_download;
+pub mod ops;
+pub use entry_point::EntryPoint;
+pub use gbfs_version::GbfsVersion;
+pub mod v3_ops;
diff --git a/rust/bambam-gbfs/src/app/download/ops.rs b/rust/bambam-gbfs/src/app/download/ops.rs
new file mode 100644
index 00000000..f26b76db
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/ops.rs
@@ -0,0 +1,27 @@
+use reqwest::{Client, IntoUrl};
+use serde::de::DeserializeOwned;
+
+use crate::app::download::{EntryPoint, GbfsVersion};
+
+/// helper function for running a client HTTP GET call to retrieve a JSON object.
+pub async fn retrieve_file<'a, 'b, T: DeserializeOwned, U: IntoUrl>(
+    client: &'b Client,
+    url: U,
+) -> Result<T, String> {
+    let response = client
+        .get(url)
+        .header("User-Agent", "rust-reqwest")
+        .send()
+        .await
+        .map_err(|e| format!("failed to connect to GBFS URL: {e}"))?;
+    let status = response.status();
+    if status.is_success() {
+        let t: T = response.json().await.map_err(|e| {
+            let type_name = std::any::type_name::<T>();
+            format!("failed to deserialize {type_name} file from HTTP response: {e}")
+        })?;
+        Ok(t)
+    } else {
+        Err(format!("client response is {status}"))
+    }
+}
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 1895c507..5e966bf5 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -1,7 +1,8 @@
 use std::path::Path;
 
 use chrono::TimeDelta;
-use gbfs_types::v3_0::files::SystemInformationFile;
+
+use crate::app::download::{EntryPoint, GbfsVersion, v3_ops};
 
 /// downloads GBFS data for some duration. aggregates the resulting rows and writes them
 /// to files to be consumed by BAMBAM.
@@ -13,28 +14,30 @@ use gbfs_types::v3_0::files::SystemInformationFile;
 ///
 /// # Result
 /// If successful, returns nothing, otherwise an error
-pub async fn run_gbfs_download(url: &str, out_dir: &Path, dur: &TimeDelta) -> Result<(), String> {
+pub async fn run_gbfs_download(
+    url: &str,
+    out_dir: &Path,
+    dur: &TimeDelta,
+    entry_point: EntryPoint,
+    version: GbfsVersion,
+) -> Result<(), String> {
     let dur_secs = dur.as_seconds_f64();
     log::debug!(
         "run_gbfs_download with url={url}, out_dir={out_dir:?}, duration (seconds)={dur_secs}"
     );
     let client = reqwest::Client::new();
-    let response = client
-        .get(url)
-        .header("User-Agent", "rust-reqwest")
-        .send()
-        .await
-        .map_err(|e| format!("failed to connect to GBFS URL: {e}"))?;
 
-    if response.status().is_success() {
-        let system_information: SystemInformationFile = response.json().await.map_err(|e| {
-            format!("failed to deserialize system information file from HTTP response: {e}")
-        })?;
-        println!("systemInformation version: {}", system_information.version);
-        println!(
-            "systemInformation data: {}",
-            system_information.data.system_id
-        );
+    let result = match (version, entry_point) {
+        (GbfsVersion::V3_0, EntryPoint::Manifest) => {
+            v3_ops::run_v3_0_manifest(&client, url).await?
+        }
+        (GbfsVersion::V3_0, EntryPoint::Gbfs) => {
+            v3_ops::run_v3_0_gbfs(&client, url).await.map(|g| vec![g])?
+        }
+    };
+
+    for row in result.into_iter() {
+        println!("{}", serde_json::to_string_pretty(&row).unwrap_or_default());
     }
 
     Ok(())
diff --git a/rust/bambam-gbfs/src/app/download/v3_ops.rs b/rust/bambam-gbfs/src/app/download/v3_ops.rs
new file mode 100644
index 00000000..9c039d0f
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/v3_ops.rs
@@ -0,0 +1,67 @@
+use gbfs_types::v3_0::files::{GbfsFile, GeofencingZonesFile, SystemInformationFile};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct GbfsV3Import {
+    /// contains the system-level metadata including opening hours.
+    pub info: SystemInformationFile,
+    /// contains the zonal geometries, global, and zone-specific traversal rules for this system.
+    pub geofence: GeofencingZonesFile,
+}
+
+/// runs retrieval from a manifest file. allows mutli-system downloads.
+pub async fn run_v3_0_manifest(
+    client: &reqwest::Client,
+    url: &str,
+) -> Result<Vec<GbfsV3Import>, String> {
+    let manifest: gbfs_types::v3_0::files::ManifestFile =
+        super::ops::retrieve_file(&client, url).await?;
+
+    // find v3 datasets for each system in this manifest and run the inner retrieval function
+    let mut results = vec![];
+    for system in manifest.data.datasets.iter() {
+        let system_id = system.system_id.clone();
+        let v_search = system.versions.iter().find(|v| v.version == "3.0");
+        match v_search {
+            Some(v3) => {
+                let gbfs_url = v3.url.value.clone();
+                let result = run_v3_0_gbfs(client, &gbfs_url).await?;
+                results.push(result);
+            }
+            None => return Err(format!("in system {system_id} no v3.0 was found.")),
+        }
+    }
+
+    Ok(results)
+}
+
+/// runs retrieval at the gbfs.json level, retrieving from a single system.
+pub async fn run_v3_0_gbfs(client: &reqwest::Client, url: &str) -> Result<GbfsV3Import, String> {
+    let gbfs: GbfsFile = super::ops::retrieve_file(&client, url).await?;
+
+    let geofencing_zones_url = gbfs
+        .data
+        .get_geofencing_zones_url()
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let geofence: GeofencingZonesFile =
+        super::ops::retrieve_file(&client, &geofencing_zones_url.value)
+            .await
+            .map_err(|e| {
+                format!(
+                    "while attempting HTTP GET '{}': {e}",
+                    geofencing_zones_url.value
+                )
+            })?;
+
+    let system_info_url = gbfs
+        .data
+        .get_system_information_url()
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let info: SystemInformationFile = super::ops::retrieve_file(&client, &system_info_url.value)
+        .await
+        .map_err(|e| format!("while attempting HTTP GET '{}': {e}", system_info_url.value))?;
+
+    let result = GbfsV3Import { info, geofence };
+
+    Ok(result)
+}
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index 9be3f445..c36ac7d8 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -1,9 +1,11 @@
-use std::path::Path;
+use std::{path::Path, str::FromStr};
 
 use chrono::TimeDelta;
 use clap::{Parser, Subcommand};
 use serde::{Deserialize, Serialize};
 
+use crate::app::download::{EntryPoint, GbfsVersion};
+
 /// command line tool providing GBFS processing scripts
 #[derive(Parser)]
 #[command(author, version, about, long_about = None)]
@@ -26,9 +28,15 @@ pub enum GbfsOperation {
         #[arg(short, long, default_value_t = String::from("."))]
         output_directory: String,
         /// duration to collect data rows. provide in human-readable time values
-        /// 2m, 30s, 2h, 2days...
+        /// 2m, 30s, 2h, 2days... applies to wait time modeling capability.
         #[arg(short, long, value_parser = parse_duration, default_value = "10m")]
         collect_duration: TimeDelta,
+        /// target of the initial HTTP call.
+        #[arg(long, default_value_t = EntryPoint::Gbfs)]
+        entry_point: EntryPoint,
+        /// GBFS version number to download.
+        #[arg(long, default_value_t = GbfsVersion::V3_0, value_parser = parse_version)]
+        version: GbfsVersion,
     },
 }
 
@@ -39,11 +47,15 @@ impl GbfsOperation {
                 gbfs_url,
                 output_directory,
                 collect_duration,
+                entry_point,
+                version,
             } => {
                 crate::app::download::run_gbfs_download(
                     gbfs_url,
                     Path::new(output_directory),
                     collect_duration,
+                    *entry_point,
+                    *version,
                 )
                 .await
             }
@@ -56,3 +68,7 @@ fn parse_duration(s: &str) -> Result<chrono::TimeDelta, String> {
         humantime::parse_duration(s).map_err(|e| format!("Invalid duration: {e}"))?;
     chrono::TimeDelta::from_std(std_duration).map_err(|e| format!("TimeDelta out of range: {e}"))
 }
+
+fn parse_version(s: &str) -> Result<GbfsVersion, String> {
+    GbfsVersion::from_str(s)
+}

From 059ac76c87e4dcb20da3ec86006bebd6d15133cf Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 15:29:37 -0600
Subject: [PATCH 05/43] cargo sort

---
 rust/Cargo.toml             | 2 +-
 rust/bambam-gbfs/Cargo.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index b322d6e0..1995de92 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -36,7 +36,7 @@ downloader = { version = "0.2.8" }
 env_logger = "0.11.8"
 flate2 = "1.0"
 futures = { version = "0.3.31", features = ["executor"] }
-gbfs_types = { version = "0.1.4", default-features = false, features = ["reqwest_blocking"]}
+gbfs_types = { version = "0.1.4", default-features = false, features = ["reqwest_blocking"] }
 geo = { version = "0.33.1", features = ["use-serde"] }
 geo-buffer = "0.2.0"
 geo-traits = "0.3.0"
diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index b794f3bd..f4f7fd1e 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -19,4 +19,4 @@ routee-compass-core = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }
 serde_with = { workspace = true }
-tokio = { workspace = true }
\ No newline at end of file
+tokio = { workspace = true }

From 40d90a7b1823476ebe9733efc24fcdc6e260a01a Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 15:29:47 -0600
Subject: [PATCH 06/43] clippy

---
 rust/bambam-gbfs/src/app/download/gbfs_version.rs         | 1 -
 rust/bambam-gbfs/src/app/download/ops.rs                  | 1 -
 rust/bambam-gbfs/src/app/download/v3_ops.rs               | 8 ++++----
 rust/bambam-osm/src/app/network/wci/bulk_compute_wci.rs   | 2 +-
 rust/bambam-osm/src/model/osm/graph/compass_writer.rs     | 2 +-
 .../src/model/traversal/time_delay/time_delay_record.rs   | 6 +++---
 6 files changed, 9 insertions(+), 11 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/gbfs_version.rs b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
index 5957ef27..8a93b2a3 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_version.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
@@ -1,6 +1,5 @@
 use std::str::FromStr;
 
-use clap::ValueEnum;
 use serde::{Deserialize, Serialize};
 
 /// GBFS version of the targeted archive. only supported versions are included.
diff --git a/rust/bambam-gbfs/src/app/download/ops.rs b/rust/bambam-gbfs/src/app/download/ops.rs
index f26b76db..07e247e9 100644
--- a/rust/bambam-gbfs/src/app/download/ops.rs
+++ b/rust/bambam-gbfs/src/app/download/ops.rs
@@ -1,7 +1,6 @@
 use reqwest::{Client, IntoUrl};
 use serde::de::DeserializeOwned;
 
-use crate::app::download::{EntryPoint, GbfsVersion};
 
 /// helper function for running a client HTTP GET call to retrieve a JSON object.
 pub async fn retrieve_file<'a, 'b, T: DeserializeOwned, U: IntoUrl>(
diff --git a/rust/bambam-gbfs/src/app/download/v3_ops.rs b/rust/bambam-gbfs/src/app/download/v3_ops.rs
index 9c039d0f..9e2c5681 100644
--- a/rust/bambam-gbfs/src/app/download/v3_ops.rs
+++ b/rust/bambam-gbfs/src/app/download/v3_ops.rs
@@ -15,7 +15,7 @@ pub async fn run_v3_0_manifest(
     url: &str,
 ) -> Result<Vec<GbfsV3Import>, String> {
     let manifest: gbfs_types::v3_0::files::ManifestFile =
-        super::ops::retrieve_file(&client, url).await?;
+        super::ops::retrieve_file(client, url).await?;
 
     // find v3 datasets for each system in this manifest and run the inner retrieval function
     let mut results = vec![];
@@ -37,14 +37,14 @@ pub async fn run_v3_0_manifest(
 
 /// runs retrieval at the gbfs.json level, retrieving from a single system.
 pub async fn run_v3_0_gbfs(client: &reqwest::Client, url: &str) -> Result<GbfsV3Import, String> {
-    let gbfs: GbfsFile = super::ops::retrieve_file(&client, url).await?;
+    let gbfs: GbfsFile = super::ops::retrieve_file(client, url).await?;
 
     let geofencing_zones_url = gbfs
         .data
         .get_geofencing_zones_url()
         .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
     let geofence: GeofencingZonesFile =
-        super::ops::retrieve_file(&client, &geofencing_zones_url.value)
+        super::ops::retrieve_file(client, &geofencing_zones_url.value)
             .await
             .map_err(|e| {
                 format!(
@@ -57,7 +57,7 @@ pub async fn run_v3_0_gbfs(client: &reqwest::Client, url: &str) -> Result<GbfsV3
         .data
         .get_system_information_url()
         .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
-    let info: SystemInformationFile = super::ops::retrieve_file(&client, &system_info_url.value)
+    let info: SystemInformationFile = super::ops::retrieve_file(client, &system_info_url.value)
         .await
         .map_err(|e| format!("while attempting HTTP GET '{}': {e}", system_info_url.value))?;
 
diff --git a/rust/bambam-osm/src/app/network/wci/bulk_compute_wci.rs b/rust/bambam-osm/src/app/network/wci/bulk_compute_wci.rs
index 007aa0b0..b185439d 100644
--- a/rust/bambam-osm/src/app/network/wci/bulk_compute_wci.rs
+++ b/rust/bambam-osm/src/app/network/wci/bulk_compute_wci.rs
@@ -41,7 +41,7 @@ pub fn bulk_compute_wci(
 
     let bar: Arc<Mutex<Bar>> = Arc::new(Mutex::new(
         BarBuilder::default()
-            .desc(format!("Computing WCI scores for the road network"))
+            .desc("Computing WCI scores for the road network".to_string())
             .total(way_rtree_entries.len())
             .build()?,
     ));
diff --git a/rust/bambam-osm/src/model/osm/graph/compass_writer.rs b/rust/bambam-osm/src/model/osm/graph/compass_writer.rs
index 994114ff..e10566cb 100644
--- a/rust/bambam-osm/src/model/osm/graph/compass_writer.rs
+++ b/rust/bambam-osm/src/model/osm/graph/compass_writer.rs
@@ -39,7 +39,7 @@ impl CompassWriter for OsmGraphVectorized {
             let dirname = output_directory.as_os_str().to_string_lossy();
             return Err(OsmError::InternalError(format!(
                 "unable to create directory {}",
-                &dirname
+                dirname
             )));
         }
 
diff --git a/rust/bambam/src/model/traversal/time_delay/time_delay_record.rs b/rust/bambam/src/model/traversal/time_delay/time_delay_record.rs
index edc7adef..2023dac0 100644
--- a/rust/bambam/src/model/traversal/time_delay/time_delay_record.rs
+++ b/rust/bambam/src/model/traversal/time_delay/time_delay_record.rs
@@ -59,7 +59,7 @@ impl<'de> de::Deserialize<'de> for TimeDelayRecord {
                                     .map_err(|e| {
                                         de::Error::custom(format!(
                                             "unable to parse WKT geometry '{}': {}",
-                                            &value, e
+                                            value, e
                                         ))
                                     })?;
                                 let row_geometry: Geometry<f32> = match geo_f64 {
@@ -78,7 +78,7 @@ impl<'de> de::Deserialize<'de> for TimeDelayRecord {
                                     _ => {
                                         return Err(de::Error::custom(format!(
                                             "expected Polygon or MultiPolygon geometry, found unexpected type in '{}'",
-                                            &value
+                                            value
                                         )));
                                     }
                                 };
@@ -89,7 +89,7 @@ impl<'de> de::Deserialize<'de> for TimeDelayRecord {
                                     serde_json::from_str::<Time>(value).map_err(|e| {
                                         de::Error::custom(format!(
                                             "unable to parse time value '{}': {}",
-                                            &value, e
+                                            value, e
                                         ))
                                     })?;
                                 time_option = Some(row_time);

From 561b25bdff03108d27cb989c8213ed09f502818b Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 19:44:57 -0600
Subject: [PATCH 07/43] fmt

---
 rust/bambam-gbfs/src/app/download/ops.rs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/app/download/ops.rs b/rust/bambam-gbfs/src/app/download/ops.rs
index 07e247e9..5c5fc6cd 100644
--- a/rust/bambam-gbfs/src/app/download/ops.rs
+++ b/rust/bambam-gbfs/src/app/download/ops.rs
@@ -1,7 +1,6 @@
 use reqwest::{Client, IntoUrl};
 use serde::de::DeserializeOwned;
 
-
 /// helper function for running a client HTTP GET call to retrieve a JSON object.
 pub async fn retrieve_file<'a, 'b, T: DeserializeOwned, U: IntoUrl>(
     client: &'b Client,

From 9d093b3ca8a6123d8053ab9543388fe09ec39b48 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 15 Jul 2026 19:45:46 -0600
Subject: [PATCH 08/43] remove unused lifetime

---
 rust/bambam-gbfs/src/app/download/ops.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/ops.rs b/rust/bambam-gbfs/src/app/download/ops.rs
index 5c5fc6cd..7d4028f9 100644
--- a/rust/bambam-gbfs/src/app/download/ops.rs
+++ b/rust/bambam-gbfs/src/app/download/ops.rs
@@ -2,8 +2,8 @@ use reqwest::{Client, IntoUrl};
 use serde::de::DeserializeOwned;
 
 /// helper function for running a client HTTP GET call to retrieve a JSON object.
-pub async fn retrieve_file<'a, 'b, T: DeserializeOwned, U: IntoUrl>(
-    client: &'b Client,
+pub async fn retrieve_file<T: DeserializeOwned, U: IntoUrl>(
+    client: &Client,
     url: U,
 ) -> Result<T, String> {
     let response = client

From fe0496bf67a0d15deea3ba07c9c2b54ce30d873d Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Tue, 21 Jul 2026 17:09:12 -0600
Subject: [PATCH 09/43] checkpoint: GBFS import supporting 2.3 + 3.0 versions
 and building out interop between gbfs_types and bambam

---
 rust/Cargo.toml                               |   2 +-
 rust/bambam-gbfs/Cargo.toml                   |   4 +
 .../src/app/download/download_metadata.rs     |  29 ++++
 .../src/app/download/feature_rules.rs         |  77 +++++++++
 .../src/app/download/gbfs_record.rs           |  87 ++++++++++
 .../bambam-gbfs/src/app/download/gbfs_v2_3.rs |  67 ++++++++
 .../app/download/{v3_ops.rs => gbfs_v3.rs}    |   0
 rust/bambam-gbfs/src/app/download/mod.rs      |  11 +-
 rust/bambam-gbfs/src/app/download/ops.rs      |  26 +++
 rust/bambam-gbfs/src/app/download/run.rs      | 149 +++++++++++++++++-
 rust/bambam-gbfs/src/app/gbfs_cli.rs          |  33 +++-
 rust/bambam-gbfs/src/model/gbfs/mod.rs        |   1 +
 rust/bambam-gbfs/src/model/gbfs/record.rs     |   7 +
 rust/bambam-gbfs/src/model/mod.rs             |   1 +
 14 files changed, 483 insertions(+), 11 deletions(-)
 create mode 100644 rust/bambam-gbfs/src/app/download/download_metadata.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/feature_rules.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/gbfs_record.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
 rename rust/bambam-gbfs/src/app/download/{v3_ops.rs => gbfs_v3.rs} (100%)
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/mod.rs
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/record.rs

diff --git a/rust/Cargo.toml b/rust/Cargo.toml
index 1995de92..fe87f5df 100644
--- a/rust/Cargo.toml
+++ b/rust/Cargo.toml
@@ -36,7 +36,7 @@ downloader = { version = "0.2.8" }
 env_logger = "0.11.8"
 flate2 = "1.0"
 futures = { version = "0.3.31", features = ["executor"] }
-gbfs_types = { version = "0.1.4", default-features = false, features = ["reqwest_blocking"] }
+gbfs_types = { version = "0.1.6", default-features = false, features = ["reqwest_blocking"] }
 geo = { version = "0.33.1", features = ["use-serde"] }
 geo-buffer = "0.2.0"
 geo-traits = "0.3.0"
diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index f4f7fd1e..20564399 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -8,12 +8,16 @@ description = "GBFS Extensions for The Behavior and Advanced Mobility Big Access
 [dependencies]
 chrono = { workspace = true }
 clap = { workspace = true }
+csv = { workspace = true }
 env_logger = { workspace = true }
+futures = { workspace = true }
 gbfs_types = { workspace = true }
 geo = { workspace = true }
+geozero = { workspace = true }
 humantime = { workspace = true }
 kdam = { workspace = true }
 log = { workspace = true }
+rayon = { workspace = true }
 reqwest = { workspace = true }
 routee-compass-core = { workspace = true }
 serde = { workspace = true }
diff --git a/rust/bambam-gbfs/src/app/download/download_metadata.rs b/rust/bambam-gbfs/src/app/download/download_metadata.rs
new file mode 100644
index 00000000..f9213a2f
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/download_metadata.rs
@@ -0,0 +1,29 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+
+#[derive(Deserialize, Clone, Debug)]
+pub enum UnversionedGbfsVersion {
+    #[serde(rename = "2.3")]
+    V2_3,
+    #[serde(rename = "3.0")]
+    V3_0,
+}
+
+impl Serialize for UnversionedGbfsVersion {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        match self {
+            UnversionedGbfsVersion::V2_3 => serializer.serialize_str("2.3"),
+            UnversionedGbfsVersion::V3_0 => serializer.serialize_str("3.0"),
+        }
+    }
+}
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct UnversionedGbfsMetadata {
+    pub last_updated: Value,
+    pub ttl: Value,
+    pub version: UnversionedGbfsVersion,
+}
diff --git a/rust/bambam-gbfs/src/app/download/feature_rules.rs b/rust/bambam-gbfs/src/app/download/feature_rules.rs
new file mode 100644
index 00000000..7da0b855
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/feature_rules.rs
@@ -0,0 +1,77 @@
+use serde::{Deserialize, Serialize};
+
+pub type VehicleTypeId = String;
+
+/// geofencing rules object
+pub struct FeatureRules {
+    /// Array of IDs of vehicle types for which any restrictions SHOULD be applied.
+    /// If vehicle type IDs are not specified, then restrictions apply to all vehicle types.
+    pub vehicle_type_ids: Option<Vec<VehicleTypeId>>,
+    /// Is the ride allowed to start in this zone?
+    pub ride_start_allowed: bool,
+    /// Is the ride allowed to end in this zone?
+    pub ride_end_allowed: bool,
+    /// Is the ride allowed to travel through this zone?
+    pub ride_through_allowed: bool,
+    /// What is the maximum speed allowed, in kilometers per hour?
+    ///
+    /// If there is no maximum speed to observe, this can be omitted.
+    pub maximum_speed_kph: Option<i32>,
+    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
+    pub station_parking: Option<bool>,
+}
+
+#[serde_with::skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+/// Vehicle that is currently deployed in the field
+pub struct VehicleType {
+    /// Unique identifier of a vehicle type.
+    pub vehicle_type_id: VehicleTypeId,
+    /// The vehicle's general form factor.
+    pub form_factor: Option<String>,
+    /// The number of riders (driver included) the vehicle can legally accommodate.
+    pub rider_capacity: Option<u8>,
+    /// Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
+    pub cargo_volume_capacity: Option<i32>,
+    /// The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms.
+    pub cargo_load_capacity: Option<f64>,
+    /// The primary propulsion type of the vehicle.
+    pub propulsion_type: Option<String>,
+    // /// Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones.
+    // pub eco_labels: Option<Vec<EcoLabel>>,
+    /// This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example, a full battery or full tank of gas).
+    pub max_range_meters: Option<f64>,
+    /// The public name of this vehicle type.
+    pub name: Option<Vec<String>>,
+    /// Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently.
+    pub vehicle_accessories: Option<Vec<String>>,
+    // /// Maximum quantity of CO2, in grams, emitted per kilometer, according to the [WLTP](https://en.wikipedia.org/wiki/Worldwide_Harmonised_Light_Vehicles_Test_Procedure).
+    // pub g_CO2_km: Option<i64>,
+    /// URL to an image that would assist the user in identifying the vehicle (for example, an image of the vehicle or a logo).
+    pub vehicle_image: Option<String>,
+    /// The name of the vehicle manufacturer.
+    pub make: Option<Vec<String>>,
+    /// The name of the vehicle model.
+    pub model: Option<Vec<String>>,
+    /// The color of the vehicle.
+    pub color: Option<String>,
+    /// Customer-readable description of the vehicle type outlining special features or how-tos.
+    pub description: Option<Vec<String>>,
+    /// Number of wheels this vehicle type has.
+    pub wheel_count: Option<u8>,
+    /// The maximum speed in kilometers per hour this vehicle is permitted to reach in accordance with local permit and regulations.
+    pub max_permitted_speed: Option<u8>,
+    /// The rated power of the motor for this vehicle type in watts.
+    pub rated_power: Option<u32>,
+    /// Maximum time in minutes that a vehicle can be reserved before a rental begins.
+    /// If default_reserve_time is set to 0, the vehicle type cannot be reserved.
+    pub default_reserve_time: Option<u32>,
+    /// The conditions for returning the vehicle at the end of the rental.
+    pub return_constraint: Option<String>,
+    // pub vehicle_assets: Option<VehicleAsset>,
+    // /// A plan_id, as defined in system_pricing_plans.json, that identifies a default pricing plan for this vehicle to be used by trip planning applications for purposes of calculating the cost of a single trip using this vehicle type.
+    // /// This default pricing plan is superseded by `pricing_plan_id` when `pricing_plan_id` is defined in `vehicle_status.json`.
+    // pub default_pricing_plan_id: Option<PricingPlanID>,
+    // /// All pricing plan IDs that are applied to this vehicle type.
+    // pub pricing_plan_ids: Option<Vec<PricingPlanID>>,
+}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_record.rs b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
new file mode 100644
index 00000000..45d1f765
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
@@ -0,0 +1,87 @@
+use geo::Geometry;
+use geozero::{ToGeo, geojson::GeoJson};
+use serde::Serialize;
+
+use crate::app::download::FeatureRules;
+
+pub enum GbfsRecord {
+    V3_0(super::GbfsV3Import),
+    V2_3(super::GbfsV2_3Import),
+}
+
+impl Serialize for GbfsRecord {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        match self {
+            GbfsRecord::V3_0(record) => record.serialize(serializer),
+            GbfsRecord::V2_3(record) => record.serialize(serializer),
+        }
+    }
+}
+
+impl GbfsRecord {
+    pub fn no_geofence(&self) -> bool {
+        match self {
+            GbfsRecord::V3_0(record) => record.geofence.data.geofencing_zones.features.is_empty(),
+            GbfsRecord::V2_3(record) => record.geofence.data.geofencing_zones.features.is_empty(),
+        }
+    }
+
+    pub fn system_id(&self) -> String {
+        match self {
+            GbfsRecord::V3_0(record) => record.info.data.system_id.clone(),
+            GbfsRecord::V2_3(record) => record.info.data.system_id.clone(),
+        }
+    }
+
+    pub fn n_features(&self) -> usize {
+        match self {
+            GbfsRecord::V3_0(record) => record.geofence.data.geofencing_zones.features.len(),
+            GbfsRecord::V2_3(record) => record.geofence.data.geofencing_zones.features.len(),
+        }
+    }
+
+    /// gets the geometry from a feature
+    pub fn get_feature_geometry(&self, idx: usize) -> Result<Geometry, String> {
+        match self {
+            GbfsRecord::V3_0(record) => {
+                let f = record
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let geom_str = serde_json::to_string(f)
+                    .map_err(|e| format!("failure deserializing feature: {e}"))?;
+                let geojson = GeoJson(&geom_str);
+                let geometry = geojson
+                    .to_geo()
+                    .map_err(|e| format!("unable to read GeoJSON as MultiPolygon: {e}"))?;
+                Ok(geometry)
+            }
+            GbfsRecord::V2_3(record) => {
+                let f = record
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let geom_str = serde_json::to_string(f)
+                    .map_err(|e| format!("failure deserializing feature: {e}"))?;
+                let geojson = GeoJson(&geom_str);
+                let geometry = geojson
+                    .to_geo()
+                    .map_err(|e| format!("unable to read GeoJSON as MultiPolygon: {e}"))?;
+                Ok(geometry)
+            }
+        }
+    }
+
+    pub fn get_feature_rules(&self) -> Result<FeatureRules, String> {
+        todo!()
+    }
+}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs b/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
new file mode 100644
index 00000000..acc85dda
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
@@ -0,0 +1,67 @@
+use gbfs_types::v2_3::files::{GbfsFile, GeofencingZonesFile, SystemInformationFile};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct GbfsV2_3Import {
+    /// contains the system-level metadata including opening hours.
+    pub info: SystemInformationFile,
+    /// contains the zonal geometries, global, and zone-specific traversal rules for this system.
+    pub geofence: GeofencingZonesFile,
+}
+
+/// runs retrieval from a manifest file. allows mutli-system downloads.
+pub async fn run_v2_3_manifest(
+    client: &reqwest::Client,
+    url: &str,
+) -> Result<Vec<GbfsV2_3Import>, String> {
+    let manifest: gbfs_types::v3_0::files::ManifestFile =
+        super::ops::retrieve_file(client, url).await?;
+
+    // find v3 datasets for each system in this manifest and run the inner retrieval function
+    let mut results = vec![];
+    for system in manifest.data.datasets.iter() {
+        let system_id = system.system_id.clone();
+        let v_search = system.versions.iter().find(|v| v.version == "3.0");
+        match v_search {
+            Some(v3) => {
+                let gbfs_url = v3.url.value.clone();
+                let result = run_v2_3_gbfs(client, &gbfs_url).await?;
+                results.push(result);
+            }
+            None => return Err(format!("in system {system_id} no v3.0 was found.")),
+        }
+    }
+
+    Ok(results)
+}
+
+/// runs retrieval at the gbfs.json level, retrieving from a single system.
+pub async fn run_v2_3_gbfs(client: &reqwest::Client, url: &str) -> Result<GbfsV2_3Import, String> {
+    let gbfs: GbfsFile = super::ops::retrieve_file(client, url).await?;
+
+    let geofencing_zones_url = gbfs
+        .data
+        .get_geofencing_zones_url("en")
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let geofence: GeofencingZonesFile =
+        super::ops::retrieve_file(client, &geofencing_zones_url.value)
+            .await
+            .map_err(|e| {
+                format!(
+                    "while attempting HTTP GET '{}': {e}",
+                    geofencing_zones_url.value
+                )
+            })?;
+
+    let system_info_url = gbfs
+        .data
+        .get_system_information_url("en")
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let info: SystemInformationFile = super::ops::retrieve_file(client, &system_info_url.value)
+        .await
+        .map_err(|e| format!("while attempting HTTP GET '{}': {e}", system_info_url.value))?;
+
+    let result = GbfsV2_3Import { info, geofence };
+
+    Ok(result)
+}
diff --git a/rust/bambam-gbfs/src/app/download/v3_ops.rs b/rust/bambam-gbfs/src/app/download/gbfs_v3.rs
similarity index 100%
rename from rust/bambam-gbfs/src/app/download/v3_ops.rs
rename to rust/bambam-gbfs/src/app/download/gbfs_v3.rs
diff --git a/rust/bambam-gbfs/src/app/download/mod.rs b/rust/bambam-gbfs/src/app/download/mod.rs
index 4e3a9977..06dd7fb1 100644
--- a/rust/bambam-gbfs/src/app/download/mod.rs
+++ b/rust/bambam-gbfs/src/app/download/mod.rs
@@ -1,9 +1,16 @@
 mod entry_point;
+mod feature_rules;
+mod gbfs_record;
+mod gbfs_v2_3;
+mod gbfs_v3;
 mod gbfs_version;
 mod run;
 
-pub use run::run_gbfs_download;
+pub use run::{run_gbfs_batch_download, run_gbfs_download_old};
+pub mod download_metadata;
 pub mod ops;
 pub use entry_point::EntryPoint;
+pub use feature_rules::FeatureRules;
+pub use gbfs_v2_3::GbfsV2_3Import;
+pub use gbfs_v3::GbfsV3Import;
 pub use gbfs_version::GbfsVersion;
-pub mod v3_ops;
diff --git a/rust/bambam-gbfs/src/app/download/ops.rs b/rust/bambam-gbfs/src/app/download/ops.rs
index 7d4028f9..d7d54535 100644
--- a/rust/bambam-gbfs/src/app/download/ops.rs
+++ b/rust/bambam-gbfs/src/app/download/ops.rs
@@ -23,3 +23,29 @@ pub async fn retrieve_file<T: DeserializeOwned, U: IntoUrl>(
         Err(format!("client response is {status}"))
     }
 }
+
+/// reads URLs from a CSV file at some column name into a vector.
+pub fn gather_feeds(csv_file: &str, url_column: &str) -> Result<Vec<String>, String> {
+    let mut reader = csv::ReaderBuilder::default()
+        .has_headers(true)
+        .from_path(csv_file)
+        .map_err(|e| format!("failed to open CSV '{csv_file}': {e}"))?;
+    let headers = reader
+        .headers()
+        .map_err(|e| format!("file '{csv_file}' failed to read headers: {e}"))?;
+    let (col_idx, _) = headers
+        .iter()
+        .enumerate()
+        .find(|(_, name)| *name == url_column)
+        .ok_or_else(|| format!("column '{url_column}' not found"))?;
+
+    let mut urls = vec![];
+    for (idx, row_result) in reader.into_records().enumerate() {
+        let row = row_result.map_err(|e| format!("failed to read CSV row {idx}: {e}"))?;
+        let url = row
+            .get(col_idx)
+            .ok_or_else(|| format!("CSV row {idx} missing col {col_idx}"))?;
+        urls.push(url.to_string());
+    }
+    Ok(urls)
+}
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 5e966bf5..ea02173b 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -1,8 +1,16 @@
-use std::path::Path;
+use std::{
+    path::Path,
+    sync::{Arc, Mutex},
+};
 
 use chrono::TimeDelta;
+use kdam::{Bar, BarBuilder, BarExt};
+use tokio::{
+    sync::Semaphore,
+    time::{Duration, Instant},
+};
 
-use crate::app::download::{EntryPoint, GbfsVersion, v3_ops};
+use crate::app::download::{EntryPoint, GbfsVersion, gbfs_record::GbfsRecord, gbfs_v2_3, gbfs_v3};
 
 /// downloads GBFS data for some duration. aggregates the resulting rows and writes them
 /// to files to be consumed by BAMBAM.
@@ -14,7 +22,7 @@ use crate::app::download::{EntryPoint, GbfsVersion, v3_ops};
 ///
 /// # Result
 /// If successful, returns nothing, otherwise an error
-pub async fn run_gbfs_download(
+pub async fn run_gbfs_download_old(
     url: &str,
     out_dir: &Path,
     dur: &TimeDelta,
@@ -29,11 +37,11 @@ pub async fn run_gbfs_download(
 
     let result = match (version, entry_point) {
         (GbfsVersion::V3_0, EntryPoint::Manifest) => {
-            v3_ops::run_v3_0_manifest(&client, url).await?
-        }
-        (GbfsVersion::V3_0, EntryPoint::Gbfs) => {
-            v3_ops::run_v3_0_gbfs(&client, url).await.map(|g| vec![g])?
+            gbfs_v3::run_v3_0_manifest(&client, url).await?
         }
+        (GbfsVersion::V3_0, EntryPoint::Gbfs) => gbfs_v3::run_v3_0_gbfs(&client, url)
+            .await
+            .map(|g| vec![g])?,
     };
 
     for row in result.into_iter() {
@@ -42,3 +50,130 @@ pub async fn run_gbfs_download(
 
     Ok(())
 }
+
+/// designed to download from a GBFS system list file such as
+/// <https://github.com/MobilityData/gbfs/blob/master/systems.csv>.
+pub async fn run_gbfs_batch_download(
+    urls: &[String],
+    entry_point: EntryPoint,
+    out_dir: &Path,
+) -> Result<(), String> {
+    // Keep defaults conservative to avoid API throttling; allow overrides via env vars.
+    let max_concurrency = std::env::var("BAMBAM_GBFS_MAX_CONCURRENCY")
+        .ok()
+        .and_then(|v| v.parse::<usize>().ok())
+        .filter(|&v| v > 0)
+        .unwrap_or(4);
+    let request_spacing_secs = std::env::var("BAMBAM_GBFS_REQUEST_SPACING_SECS")
+        .ok()
+        .and_then(|v| v.parse::<u64>().ok())
+        .unwrap_or(2);
+
+    let bar: Arc<Mutex<Bar>> = Arc::new(Mutex::new(
+        BarBuilder::default()
+            .total(urls.len())
+            .desc("gbfs urls")
+            .build()
+            .map_err(|e| format!("error building progress bar: {e}"))?,
+    ));
+    let client = Arc::new(reqwest::Client::new());
+    let semaphore = Arc::new(Semaphore::new(max_concurrency));
+    let mut next_start_at = Instant::now();
+    let spacing = Duration::from_secs(request_spacing_secs);
+
+    log::info!(
+        "starting calls to download archives via {entry_point} entry point (max_concurrency={max_concurrency}, request_spacing_secs={request_spacing_secs})"
+    );
+    let mut set = tokio::task::JoinSet::new();
+    for url in urls.into_iter() {
+        let client = client.clone();
+        let semaphore = semaphore.clone();
+        let url = url.to_string();
+        let inner_bar = bar.clone();
+        let start_delay = next_start_at.saturating_duration_since(Instant::now());
+        next_start_at += spacing;
+
+        set.spawn(async move {
+            if !start_delay.is_zero() {
+                tokio::time::sleep(start_delay).await;
+            }
+
+            let _permit = semaphore
+                .acquire_owned()
+                .await
+                .map_err(|e| format!("failed to acquire concurrency permit: {e}"))?;
+
+            run_gbfs_download(client, url, entry_point, inner_bar).await
+        });
+    }
+
+    let mut results = vec![];
+    let mut errors: Vec<String> = vec![];
+    while let Some(res) = set.join_next().await {
+        match res {
+            Ok(Err(e)) => errors.push(e),
+            Err(e) => errors.push(format!("error on tokio join of task: {e}")),
+            Ok(Ok(r)) => results.extend(r.into_iter()),
+        }
+    }
+
+    for result in results.into_iter() {
+        let no_features = result.no_geofence();
+        if !no_features {
+            let filename = result.system_id();
+            let filepath = out_dir.join(&filename);
+
+            std::fs::write(
+                filepath,
+                serde_json::to_string_pretty(&result).unwrap_or_default(),
+            )
+            .map_err(|e| format!("failure while writing to '{filename}': {e}"))?;
+        }
+    }
+
+    if !errors.is_empty() {
+        for err in errors.iter() {
+            log::error!("{err}")
+        }
+        log::error!("{} calls failed", errors.len());
+    }
+
+    Ok(())
+}
+
+async fn run_gbfs_download(
+    client: Arc<reqwest::Client>,
+    url: String,
+    entry_point: EntryPoint,
+    bar: Arc<Mutex<Bar>>,
+) -> Result<Vec<GbfsRecord>, String> {
+    let unversioned: super::download_metadata::UnversionedGbfsMetadata =
+        super::ops::retrieve_file(&client, &url).await?;
+
+    let result: Vec<GbfsRecord> = match unversioned.version {
+        super::download_metadata::UnversionedGbfsVersion::V2_3 => {
+            let result = match entry_point {
+                EntryPoint::Manifest => gbfs_v2_3::run_v2_3_manifest(&client, &url).await?,
+                EntryPoint::Gbfs => gbfs_v2_3::run_v2_3_gbfs(&client, &url)
+                    .await
+                    .map(|g| vec![g])?,
+            };
+            result.into_iter().map(|r| GbfsRecord::V2_3(r)).collect()
+        }
+        super::download_metadata::UnversionedGbfsVersion::V3_0 => {
+            let result = match entry_point {
+                EntryPoint::Manifest => gbfs_v3::run_v3_0_manifest(&client, &url).await?,
+                EntryPoint::Gbfs => gbfs_v3::run_v3_0_gbfs(&client, &url)
+                    .await
+                    .map(|g| vec![g])?,
+            };
+            result.into_iter().map(|r| GbfsRecord::V3_0(r)).collect()
+        }
+    };
+
+    if let Ok(mut bar) = bar.lock() {
+        let _ = bar.update(1);
+    }
+
+    Ok(result)
+}
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index c36ac7d8..c5b453ee 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -38,6 +38,22 @@ pub enum GbfsOperation {
         #[arg(long, default_value_t = GbfsVersion::V3_0, value_parser = parse_version)]
         version: GbfsVersion,
     },
+    /// downloads GBFS archives from a CSV. ignores archives missing geofence data. writes
+    /// each dataset JSON 3.0 object to a file in the out directory.
+    DownloadWithGeofences {
+        /// a file like <https://github.com/MobilityData/gbfs/blob/master/systems.csv>
+        #[arg(long)]
+        csv_file: String,
+        /// column name for CSV column containing URLs
+        #[arg(long)]
+        csv_column: String,
+        /// whether we are targeting a manifest.json file or gbfs.json file.
+        #[arg(long)]
+        entry_point: EntryPoint,
+        /// output directory path.
+        #[arg(short, long, default_value_t = String::from("."))]
+        output_directory: String,
+    },
 }
 
 impl GbfsOperation {
@@ -50,7 +66,7 @@ impl GbfsOperation {
                 entry_point,
                 version,
             } => {
-                crate::app::download::run_gbfs_download(
+                crate::app::download::run_gbfs_download_old(
                     gbfs_url,
                     Path::new(output_directory),
                     collect_duration,
@@ -59,6 +75,21 @@ impl GbfsOperation {
                 )
                 .await
             }
+            GbfsOperation::DownloadWithGeofences {
+                csv_file,
+                csv_column,
+                entry_point,
+                output_directory,
+            } => {
+                let urls = crate::app::download::ops::gather_feeds(csv_file, csv_column)?;
+                log::info!("found {} urls", urls.len());
+                crate::app::download::run_gbfs_batch_download(
+                    &urls,
+                    *entry_point,
+                    Path::new(output_directory),
+                )
+                .await
+            }
         }
     }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/mod.rs b/rust/bambam-gbfs/src/model/gbfs/mod.rs
new file mode 100644
index 00000000..1f46c735
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/mod.rs
@@ -0,0 +1 @@
+mod record;
diff --git a/rust/bambam-gbfs/src/model/gbfs/record.rs b/rust/bambam-gbfs/src/model/gbfs/record.rs
new file mode 100644
index 00000000..3b840b6a
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/record.rs
@@ -0,0 +1,7 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct GbfsImportRecord {
+    fq_id: String,
+    system_id: String,
+}
diff --git a/rust/bambam-gbfs/src/model/mod.rs b/rust/bambam-gbfs/src/model/mod.rs
index e0a9a6f6..83c5ffd0 100644
--- a/rust/bambam-gbfs/src/model/mod.rs
+++ b/rust/bambam-gbfs/src/model/mod.rs
@@ -1,2 +1,3 @@
 pub mod constraint;
+pub mod gbfs;
 pub mod traversal;

From 46c66d8b9fd6ee4a60ea043acacbf107da4f7339 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Fri, 24 Jul 2026 14:40:32 -0600
Subject: [PATCH 10/43] data importer CLIs

---
 rust/bambam-gbfs/Cargo.toml                   |   2 +
 .../src/app/download/download_metadata.rs     |   3 +
 .../src/app/download/feature_rules.rs         |  77 ------
 .../src/app/download/gbfs_record.rs           | 179 +++++++++++++-
 .../bambam-gbfs/src/app/download/gbfs_v2_2.rs | 172 +++++++++++++
 .../app/download/{gbfs_v3.rs => gbfs_v3_0.rs} |   0
 .../src/app/download/gbfs_version.rs          |  16 +-
 rust/bambam-gbfs/src/app/download/mod.rs      |  13 +-
 rust/bambam-gbfs/src/app/download/run.rs      | 141 +++++++++--
 .../src/app/download/zone_constraints.rs      | 233 ++++++++++++++++++
 rust/bambam-gbfs/src/app/gbfs_cli.rs          |  41 ++-
 rust/bambam-gbfs/src/model/gbfs/mod.rs        |   3 +
 rust/bambam-gbfs/src/model/gbfs/ops.rs        |  15 ++
 rust/bambam-gbfs/src/model/gbfs/record.rs     |  54 +++-
 14 files changed, 833 insertions(+), 116 deletions(-)
 delete mode 100644 rust/bambam-gbfs/src/app/download/feature_rules.rs
 create mode 100644 rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
 rename rust/bambam-gbfs/src/app/download/{gbfs_v3.rs => gbfs_v3_0.rs} (100%)
 create mode 100644 rust/bambam-gbfs/src/app/download/zone_constraints.rs
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/ops.rs

diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index 20564399..aa18f49a 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -10,11 +10,13 @@ chrono = { workspace = true }
 clap = { workspace = true }
 csv = { workspace = true }
 env_logger = { workspace = true }
+flate2 = { workspace = true }
 futures = { workspace = true }
 gbfs_types = { workspace = true }
 geo = { workspace = true }
 geozero = { workspace = true }
 humantime = { workspace = true }
+itertools = { workspace = true }
 kdam = { workspace = true }
 log = { workspace = true }
 rayon = { workspace = true }
diff --git a/rust/bambam-gbfs/src/app/download/download_metadata.rs b/rust/bambam-gbfs/src/app/download/download_metadata.rs
index f9213a2f..de6f87b3 100644
--- a/rust/bambam-gbfs/src/app/download/download_metadata.rs
+++ b/rust/bambam-gbfs/src/app/download/download_metadata.rs
@@ -3,6 +3,8 @@ use serde_json::Value;
 
 #[derive(Deserialize, Clone, Debug)]
 pub enum UnversionedGbfsVersion {
+    #[serde(rename = "2.2")]
+    V2_2,
     #[serde(rename = "2.3")]
     V2_3,
     #[serde(rename = "3.0")]
@@ -15,6 +17,7 @@ impl Serialize for UnversionedGbfsVersion {
         S: serde::Serializer,
     {
         match self {
+            UnversionedGbfsVersion::V2_2 => serializer.serialize_str("2.2"),
             UnversionedGbfsVersion::V2_3 => serializer.serialize_str("2.3"),
             UnversionedGbfsVersion::V3_0 => serializer.serialize_str("3.0"),
         }
diff --git a/rust/bambam-gbfs/src/app/download/feature_rules.rs b/rust/bambam-gbfs/src/app/download/feature_rules.rs
deleted file mode 100644
index 7da0b855..00000000
--- a/rust/bambam-gbfs/src/app/download/feature_rules.rs
+++ /dev/null
@@ -1,77 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-pub type VehicleTypeId = String;
-
-/// geofencing rules object
-pub struct FeatureRules {
-    /// Array of IDs of vehicle types for which any restrictions SHOULD be applied.
-    /// If vehicle type IDs are not specified, then restrictions apply to all vehicle types.
-    pub vehicle_type_ids: Option<Vec<VehicleTypeId>>,
-    /// Is the ride allowed to start in this zone?
-    pub ride_start_allowed: bool,
-    /// Is the ride allowed to end in this zone?
-    pub ride_end_allowed: bool,
-    /// Is the ride allowed to travel through this zone?
-    pub ride_through_allowed: bool,
-    /// What is the maximum speed allowed, in kilometers per hour?
-    ///
-    /// If there is no maximum speed to observe, this can be omitted.
-    pub maximum_speed_kph: Option<i32>,
-    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
-    pub station_parking: Option<bool>,
-}
-
-#[serde_with::skip_serializing_none]
-#[derive(Serialize, Deserialize, Debug, Clone)]
-/// Vehicle that is currently deployed in the field
-pub struct VehicleType {
-    /// Unique identifier of a vehicle type.
-    pub vehicle_type_id: VehicleTypeId,
-    /// The vehicle's general form factor.
-    pub form_factor: Option<String>,
-    /// The number of riders (driver included) the vehicle can legally accommodate.
-    pub rider_capacity: Option<u8>,
-    /// Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
-    pub cargo_volume_capacity: Option<i32>,
-    /// The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms.
-    pub cargo_load_capacity: Option<f64>,
-    /// The primary propulsion type of the vehicle.
-    pub propulsion_type: Option<String>,
-    // /// Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones.
-    // pub eco_labels: Option<Vec<EcoLabel>>,
-    /// This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example, a full battery or full tank of gas).
-    pub max_range_meters: Option<f64>,
-    /// The public name of this vehicle type.
-    pub name: Option<Vec<String>>,
-    /// Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently.
-    pub vehicle_accessories: Option<Vec<String>>,
-    // /// Maximum quantity of CO2, in grams, emitted per kilometer, according to the [WLTP](https://en.wikipedia.org/wiki/Worldwide_Harmonised_Light_Vehicles_Test_Procedure).
-    // pub g_CO2_km: Option<i64>,
-    /// URL to an image that would assist the user in identifying the vehicle (for example, an image of the vehicle or a logo).
-    pub vehicle_image: Option<String>,
-    /// The name of the vehicle manufacturer.
-    pub make: Option<Vec<String>>,
-    /// The name of the vehicle model.
-    pub model: Option<Vec<String>>,
-    /// The color of the vehicle.
-    pub color: Option<String>,
-    /// Customer-readable description of the vehicle type outlining special features or how-tos.
-    pub description: Option<Vec<String>>,
-    /// Number of wheels this vehicle type has.
-    pub wheel_count: Option<u8>,
-    /// The maximum speed in kilometers per hour this vehicle is permitted to reach in accordance with local permit and regulations.
-    pub max_permitted_speed: Option<u8>,
-    /// The rated power of the motor for this vehicle type in watts.
-    pub rated_power: Option<u32>,
-    /// Maximum time in minutes that a vehicle can be reserved before a rental begins.
-    /// If default_reserve_time is set to 0, the vehicle type cannot be reserved.
-    pub default_reserve_time: Option<u32>,
-    /// The conditions for returning the vehicle at the end of the rental.
-    pub return_constraint: Option<String>,
-    // pub vehicle_assets: Option<VehicleAsset>,
-    // /// A plan_id, as defined in system_pricing_plans.json, that identifies a default pricing plan for this vehicle to be used by trip planning applications for purposes of calculating the cost of a single trip using this vehicle type.
-    // /// This default pricing plan is superseded by `pricing_plan_id` when `pricing_plan_id` is defined in `vehicle_status.json`.
-    // pub default_pricing_plan_id: Option<PricingPlanID>,
-    // /// All pricing plan IDs that are applied to this vehicle type.
-    // pub pricing_plan_ids: Option<Vec<PricingPlanID>>,
-}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_record.rs b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
index 45d1f765..2269f7fb 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_record.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
@@ -1,12 +1,17 @@
 use geo::Geometry;
 use geozero::{ToGeo, geojson::GeoJson};
+use itertools::Itertools;
 use serde::Serialize;
 
-use crate::app::download::FeatureRules;
+use crate::{
+    app::download::{GbfsVersion, ZoneConstraints},
+    model::gbfs::GbfsZoneRecord,
+};
 
 pub enum GbfsRecord {
     V3_0(super::GbfsV3Import),
     V2_3(super::GbfsV2_3Import),
+    V2_2(super::GbfsV2_2Import),
 }
 
 impl Serialize for GbfsRecord {
@@ -17,15 +22,39 @@ impl Serialize for GbfsRecord {
         match self {
             GbfsRecord::V3_0(record) => record.serialize(serializer),
             GbfsRecord::V2_3(record) => record.serialize(serializer),
+            GbfsRecord::V2_2(record) => record.serialize(serializer),
         }
     }
 }
 
 impl GbfsRecord {
+    /// downloads a dataset from a URL for a given GBFS version.
+    pub async fn download_from_gbfs_endpoint(
+        client: &reqwest::Client,
+        url: &str,
+        version: GbfsVersion,
+    ) -> Result<Self, String> {
+        match version {
+            GbfsVersion::V3_0 => {
+                let gbfs = super::gbfs_v3_0::run_v3_0_gbfs(client, url).await?;
+                Ok(Self::V3_0(gbfs))
+            }
+            GbfsVersion::V2_3 => {
+                let gbfs = super::gbfs_v2_3::run_v2_3_gbfs(client, url).await?;
+                Ok(Self::V2_3(gbfs))
+            }
+            GbfsVersion::V2_2 => {
+                let gbfs = super::gbfs_v2_2::run_v2_2_gbfs(client, url).await?;
+                Ok(Self::V2_2(gbfs))
+            }
+        }
+    }
+
     pub fn no_geofence(&self) -> bool {
         match self {
             GbfsRecord::V3_0(record) => record.geofence.data.geofencing_zones.features.is_empty(),
             GbfsRecord::V2_3(record) => record.geofence.data.geofencing_zones.features.is_empty(),
+            GbfsRecord::V2_2(record) => record.geofence.data.geofencing_zones.features.is_empty(),
         }
     }
 
@@ -33,6 +62,7 @@ impl GbfsRecord {
         match self {
             GbfsRecord::V3_0(record) => record.info.data.system_id.clone(),
             GbfsRecord::V2_3(record) => record.info.data.system_id.clone(),
+            GbfsRecord::V2_2(record) => record.info.data.system_id.clone(),
         }
     }
 
@@ -40,10 +70,11 @@ impl GbfsRecord {
         match self {
             GbfsRecord::V3_0(record) => record.geofence.data.geofencing_zones.features.len(),
             GbfsRecord::V2_3(record) => record.geofence.data.geofencing_zones.features.len(),
+            GbfsRecord::V2_2(record) => record.geofence.data.geofencing_zones.features.len(),
         }
     }
 
-    /// gets the geometry from a feature
+    /// gets the geometry for a feature.
     pub fn get_feature_geometry(&self, idx: usize) -> Result<Geometry, String> {
         match self {
             GbfsRecord::V3_0(record) => {
@@ -78,10 +109,150 @@ impl GbfsRecord {
                     .map_err(|e| format!("unable to read GeoJSON as MultiPolygon: {e}"))?;
                 Ok(geometry)
             }
+            GbfsRecord::V2_2(record) => {
+                let f = record
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let geom_str = serde_json::to_string(f)
+                    .map_err(|e| format!("failure deserializing feature: {e}"))?;
+                let geojson = GeoJson(&geom_str);
+                let geometry = geojson
+                    .to_geo()
+                    .map_err(|e| format!("unable to read GeoJSON as MultiPolygon: {e}"))?;
+                Ok(geometry)
+            }
         }
     }
 
-    pub fn get_feature_rules(&self) -> Result<FeatureRules, String> {
-        todo!()
+    /// converts a feature in the GBFS dataset into a [GbfsZoneRecord].
+    pub fn get_feature_zone_record(&self, idx: usize) -> Result<GbfsZoneRecord, String> {
+        match self {
+            GbfsRecord::V3_0(gbfs) => {
+                let system_id = gbfs.info.data.system_id.clone();
+                let global_constraints =
+                    ZoneConstraints::from_v3_0(gbfs.geofence.data.global_rules.as_ref());
+                let feature = gbfs
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let found_constraints: Vec<ZoneConstraints> =
+                    match feature.properties.rules.as_ref() {
+                        Some(rs) => rs
+                            .iter()
+                            .filter(|r| r.vehicle_type_ids.is_none())
+                            .map(|r| r.into())
+                            .collect_vec(),
+                        None => vec![],
+                    };
+                let start = feature.properties.start.clone();
+                let end = feature.properties.end.clone();
+                // merge global and feature-specific constraints
+                let zone_constraints = ZoneConstraints::merge_constraints(
+                    &global_constraints,
+                    &found_constraints,
+                    None,
+                )
+                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                Ok(GbfsZoneRecord::new(
+                    system_id,
+                    idx,
+                    start,
+                    end,
+                    zone_constraints,
+                ))
+            }
+            GbfsRecord::V2_3(gbfs) => {
+                let system_id = gbfs.info.data.system_id.clone();
+                let global_constraints = vec![];
+                let feature = gbfs
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let found_constraints: Vec<ZoneConstraints> =
+                    match feature.properties.rules.as_ref() {
+                        Some(rs) => rs
+                            .iter()
+                            .filter(|r| r.vehicle_type_id.is_none())
+                            .map(|r| r.into())
+                            .collect_vec(),
+                        None => vec![],
+                    };
+                let start = process_optional_ts_to_string(feature.properties.start)?;
+                let end = process_optional_ts_to_string(feature.properties.end)?;
+                // merge global and feature-specific constraints
+                let zone_constraints = ZoneConstraints::merge_constraints(
+                    &global_constraints,
+                    &found_constraints,
+                    None,
+                )
+                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                Ok(GbfsZoneRecord::new(
+                    system_id,
+                    idx,
+                    start,
+                    end,
+                    zone_constraints,
+                ))
+            }
+            GbfsRecord::V2_2(gbfs) => {
+                let system_id = gbfs.info.data.system_id.clone();
+                let global_constraints = vec![];
+                let feature = gbfs
+                    .geofence
+                    .data
+                    .geofencing_zones
+                    .features
+                    .get(idx)
+                    .ok_or_else(|| format!("feature index {idx} not found"))?;
+                let found_constraints: Vec<ZoneConstraints> =
+                    match feature.properties.rules.as_ref() {
+                        Some(rs) => rs
+                            .iter()
+                            .filter(|r| r.vehicle_type_id.is_none())
+                            .map(|r| r.into())
+                            .collect_vec(),
+                        None => vec![],
+                    };
+                let start = process_optional_ts_to_string(feature.properties.start)?;
+                let end = process_optional_ts_to_string(feature.properties.end)?;
+                // merge global and feature-specific constraints
+                let zone_constraints = ZoneConstraints::merge_constraints(
+                    &global_constraints,
+                    &found_constraints,
+                    None,
+                )
+                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                Ok(GbfsZoneRecord::new(
+                    system_id,
+                    idx,
+                    start,
+                    end,
+                    zone_constraints,
+                ))
+            }
+        }
+    }
+}
+
+fn process_optional_ts_to_string(s: Option<i64>) -> Result<Option<String>, String> {
+    match s {
+        None => Ok(None),
+        Some(ts) => timestamp_from_int(ts).map(Some),
     }
 }
+
+fn timestamp_from_int(t: i64) -> Result<String, String> {
+    chrono::DateTime::from_timestamp(t, 0)
+        .ok_or_else(|| format!("could not parse timestamp '{t}'"))
+        .map(|ts| ts.to_rfc3339())
+}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs b/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
new file mode 100644
index 00000000..662dd8ca
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
@@ -0,0 +1,172 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct GbfsV2_2Import {
+    /// contains the system-level metadata including opening hours.
+    pub info: types::SystemInformationFile,
+    /// contains the zonal geometries, global, and zone-specific traversal rules for this system.
+    pub geofence: types::GeofencingZonesFile,
+}
+
+/// runs retrieval at the gbfs.json level, retrieving from a single system.
+pub async fn run_v2_2_gbfs(client: &reqwest::Client, url: &str) -> Result<GbfsV2_2Import, String> {
+    let gbfs: types::GbfsFile = super::ops::retrieve_file(client, url)
+        .await
+        .map_err(|e| format!("while downloading gbfs.json file, {e}"))?;
+
+    let geofencing_zones_url = gbfs
+        .get_geofencing_zones_url("en")
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let geofence: types::GeofencingZonesFile =
+        super::ops::retrieve_file(client, &geofencing_zones_url)
+            .await
+            .map_err(|e| format!("while attempting HTTP GET '{}': {e}", geofencing_zones_url))?;
+
+    let system_info_url = gbfs
+        .get_system_information_url("en")
+        .ok_or_else(|| format!("feed at {url} does not include geofencing_zones"))?;
+    let info: types::SystemInformationFile = super::ops::retrieve_file(client, &system_info_url)
+        .await
+        .map_err(|e| format!("while attempting HTTP GET '{}': {e}", system_info_url))?;
+
+    let result = GbfsV2_2Import { info, geofence };
+
+    Ok(result)
+}
+
+pub mod types {
+    //! GBFS 2.2 is not implemented in gbfs_types but it is used by Lime.
+    use std::collections::HashMap;
+
+    use serde::{Deserialize, Serialize};
+
+    pub type GbfsFile = GbfsMetadata<Feeds>;
+    pub type SystemInformationFile = GbfsMetadata<SystemInformation>;
+    pub type GeofencingZonesFile = GbfsMetadata<GeofencingZones>;
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GbfsMetadata<T> {
+        /// Indicates the last time data in the feed was updated. This timestamp represents the publisher's knowledge of the current state of the system at this point in time.
+        pub last_updated: Timestamp,
+        /// Number of seconds before the data in the feed will be updated again (0 if the data should always be refreshed).
+        pub ttl: u32,
+        /// GBFS version number to which the feed conforms, according to the versioning framework.
+        pub version: String,
+        /// Response data.
+        pub data: T,
+    }
+
+    pub type Feeds = HashMap<Language, GbfsLanguageFeeds>;
+
+    impl GbfsMetadata<Feeds> {
+        pub fn get_geofencing_zones_url(&self, language: &str) -> Option<Url> {
+            self.get_file_url(language, "geofencing_zones")
+        }
+
+        pub fn get_system_information_url(&self, language: &str) -> Option<Url> {
+            self.get_file_url(language, "system_information")
+        }
+
+        fn get_file_url(&self, language: &str, feed_type: &str) -> Option<Url> {
+            self.data.get(language).and_then(|feed| {
+                feed.feeds.iter().find_map(|f| {
+                    if f.name == feed_type {
+                        Some(f.url.clone())
+                    } else {
+                        None
+                    }
+                })
+            })
+        }
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GbfsLanguageFeeds {
+        pub feeds: Vec<GbfsDataFeed>,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GbfsDataFeed {
+        /// Key identifying the type of feed this is. The key MUST be the base file name defined in the spec for the corresponding feed type
+        pub name: FeedType,
+        /// URL for the feed. Note that the actual feed endpoints (urls) may not be defined in the `file_name.json` format.
+        /// For example, a valid feed endpoint could end with `station_info` instead of `station_information.json`.
+        pub url: Url,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct SystemInformation {
+        /// Identifier for this vehicle share system. This should be globally unique (even between different systems).
+        pub system_id: String,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GeofencingZones {
+        pub geofencing_zones: GeofenceCollection,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GeofenceCollection {
+        pub r#type: String,
+        pub features: Vec<GeofenceFeature>,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GeofenceFeature {
+        pub r#type: String,
+        pub geometry: GeofenceGeometry,
+        pub properties: GeofenceProperties,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    #[serde(tag = "type")]
+    pub enum GeofenceGeometry {
+        #[serde(rename = "MultiPolygon")]
+        MultiPolygon(Vec<Vec<Vec<Vec<f64>>>>),
+        #[serde(rename = "Polygon")]
+        Polygon(Vec<Vec<Vec<Vec<f64>>>>),
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GeofenceProperties {
+        /// Start time of the geofencing zone. If the geofencing zone is always active, this can be omitted.
+        pub start: Option<Timestamp>,
+        /// End time of the geofencing zone. If the geofencing zone is always active, this can be omitted.
+        pub end: Option<Timestamp>,
+        /// Array that contains one object per rule.
+        pub rules: Option<Vec<GeofenceRules>>,
+    }
+
+    #[derive(Serialize, Deserialize, Debug, Clone)]
+    pub struct GeofenceRules {
+        pub vehicle_type_id: Option<Vec<String>>,
+        pub ride_allowed: bool,
+        pub ride_through_allowed: bool,
+        pub maximum_speed_kph: Option<i32>,
+    }
+
+    pub type Timestamp = i64;
+
+    /// A fully qualified URL that includes `http://` or `https://`. Any special characters in the URL MUST be correctly escaped. See the following <https://www.w3.org/Addressing/URL/4_URI_Recommentations.html> for a description of how to create fully qualified URL values.
+    pub type Url = String; // url::URL;
+
+    /// An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to <https://www.rfc-editor.org/rfc/bcp/bcp47.txt> and <https://www.w3.org/International/articles/language-tags/>. Examples: `en` for English, `en-US`
+    pub type Language = String;
+
+    /// Type of a GBFS feed.
+    /// Current values are :
+    /// - `gbfs` for [GbfsFile],
+    /// - `gbfs_versions` for [GbfsVersionsFile],
+    /// - `system_information` for [SystemInformationFile],
+    /// - `vehicle_types` for [VehicleTypesFile],
+    /// - `station_information` for [StationInformationFile],
+    /// - `station_status` for [StationStatusFile],
+    /// - `free_bike_status` for [FreeBikeStatusFile],
+    /// - `system_hours` for [SystemHoursFile],
+    /// - `system_calendar` for [SystemCalendarFile],
+    /// - `system_regions` for [SystemRegionsFile],
+    /// - `system_pricing_plans` for [SystemPricingPlansFile],
+    /// - `system_alerts` for [SystemAlertsFile],
+    /// - `geofencing_zones` for [GeofencingZonesFile]
+    pub type FeedType = String;
+}
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_v3.rs b/rust/bambam-gbfs/src/app/download/gbfs_v3_0.rs
similarity index 100%
rename from rust/bambam-gbfs/src/app/download/gbfs_v3.rs
rename to rust/bambam-gbfs/src/app/download/gbfs_v3_0.rs
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_version.rs b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
index 8a93b2a3..acd1beae 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_version.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_version.rs
@@ -5,18 +5,24 @@ use serde::{Deserialize, Serialize};
 /// GBFS version of the targeted archive. only supported versions are included.
 #[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum GbfsVersion {
-    #[serde(rename = "v3.0")]
+    #[serde(rename = "3.0")]
     V3_0,
+    #[serde(rename = "2.3")]
+    V2_3,
+    #[serde(rename = "2.2")]
+    V2_2,
 }
 
 impl GbfsVersion {
-    pub const ALL: [&'static str; 1] = ["v3.0"];
+    pub const ALL: [&'static str; 3] = ["3.0", "2.3", "2.2"];
 }
 
 impl std::fmt::Display for GbfsVersion {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
-            GbfsVersion::V3_0 => write!(f, "v3.0"),
+            GbfsVersion::V3_0 => write!(f, "3.0"),
+            GbfsVersion::V2_3 => write!(f, "2.3"),
+            GbfsVersion::V2_2 => write!(f, "2.2"),
         }
     }
 }
@@ -26,7 +32,9 @@ impl FromStr for GbfsVersion {
 
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         match s {
-            "v3.0" => Ok(Self::V3_0),
+            "3.0" => Ok(Self::V3_0),
+            "2.3" => Ok(Self::V2_3),
+            "2.2" => Ok(Self::V2_2),
             _ => Err(format!(
                 "unknown version '{s}', must be one of [{}]",
                 Self::ALL.join(", ")
diff --git a/rust/bambam-gbfs/src/app/download/mod.rs b/rust/bambam-gbfs/src/app/download/mod.rs
index 06dd7fb1..a2e8c8f4 100644
--- a/rust/bambam-gbfs/src/app/download/mod.rs
+++ b/rust/bambam-gbfs/src/app/download/mod.rs
@@ -1,16 +1,17 @@
 mod entry_point;
-mod feature_rules;
 mod gbfs_record;
+mod gbfs_v2_2;
 mod gbfs_v2_3;
-mod gbfs_v3;
+mod gbfs_v3_0;
 mod gbfs_version;
-mod run;
+mod zone_constraints;
 
-pub use run::{run_gbfs_batch_download, run_gbfs_download_old};
 pub mod download_metadata;
 pub mod ops;
+pub mod run;
 pub use entry_point::EntryPoint;
-pub use feature_rules::FeatureRules;
+pub use gbfs_v2_2::GbfsV2_2Import;
 pub use gbfs_v2_3::GbfsV2_3Import;
-pub use gbfs_v3::GbfsV3Import;
+pub use gbfs_v3_0::GbfsV3Import;
 pub use gbfs_version::GbfsVersion;
+pub use zone_constraints::ZoneConstraints;
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index ea02173b..3bca7724 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -1,16 +1,84 @@
 use std::{
+    fs::File,
     path::Path,
     sync::{Arc, Mutex},
 };
 
 use chrono::TimeDelta;
+use csv::QuoteStyle;
+use flate2::{Compression, write::GzEncoder};
+use geozero::ToWkt;
 use kdam::{Bar, BarBuilder, BarExt};
 use tokio::{
     sync::Semaphore,
     time::{Duration, Instant},
 };
 
-use crate::app::download::{EntryPoint, GbfsVersion, gbfs_record::GbfsRecord, gbfs_v2_3, gbfs_v3};
+use crate::app::download::{
+    EntryPoint, GbfsVersion, gbfs_record::GbfsRecord, gbfs_v2_2, gbfs_v2_3, gbfs_v3_0,
+};
+
+const GEOMETRIES_FILENAME: &str = "edges-gbfs-geofences-enumerated.txt.gz";
+const RECORDS_FILENAME: &str = "edges-gbfs-records.csv.gz";
+
+pub async fn gbfs_download_import(
+    url: &str,
+    out_dir: &Path,
+    version: GbfsVersion,
+    overwrite: bool,
+) -> Result<(), String> {
+    log::info!("run_gbfs_download with url={url}, out_dir={out_dir:?}, version={version}");
+
+    // download GBFS dataset
+    let client = reqwest::Client::new();
+    let gbfs = GbfsRecord::download_from_gbfs_endpoint(&client, url, version).await?;
+
+    // process into BAMBAM-GBFS edge list format
+    let mut geometries = vec![];
+    let mut zone_records = vec![];
+    for i in 0..gbfs.n_features() {
+        let geometry = gbfs.get_feature_geometry(i)?;
+        let record = gbfs.get_feature_zone_record(i)?;
+        geometries.push(geometry);
+        zone_records.push(record);
+    }
+
+    // write outputs
+    std::fs::create_dir_all(out_dir)
+        .map_err(|e| format!("failure creating output directory location: {e}"))?;
+    let mut geom_writer = create_writer(
+        out_dir,
+        GEOMETRIES_FILENAME,
+        false,
+        QuoteStyle::Never,
+        overwrite,
+    )?;
+    let mut record_writer = create_writer(
+        out_dir,
+        RECORDS_FILENAME,
+        true,
+        QuoteStyle::Necessary,
+        overwrite,
+    )?;
+
+    for (idx, geom) in geometries.into_iter().enumerate() {
+        let wkt_string = geom
+            .to_wkt()
+            .map_err(|e| format!("failure converting geometry {idx} into WKT: {e}"))?;
+
+        geom_writer
+            .serialize(&wkt_string)
+            .map_err(|e| format!("failure writing geometry {idx} to file: {e}"))?
+    }
+
+    for (idx, record) in zone_records.into_iter().enumerate() {
+        record_writer
+            .serialize(&record)
+            .map_err(|e| format!("failure writing geometry {idx} to file: {e}"))?
+    }
+
+    Ok(())
+}
 
 /// downloads GBFS data for some duration. aggregates the resulting rows and writes them
 /// to files to be consumed by BAMBAM.
@@ -22,7 +90,7 @@ use crate::app::download::{EntryPoint, GbfsVersion, gbfs_record::GbfsRecord, gbf
 ///
 /// # Result
 /// If successful, returns nothing, otherwise an error
-pub async fn run_gbfs_download_old(
+pub async fn gbfs_download_old(
     url: &str,
     out_dir: &Path,
     dur: &TimeDelta,
@@ -37,11 +105,12 @@ pub async fn run_gbfs_download_old(
 
     let result = match (version, entry_point) {
         (GbfsVersion::V3_0, EntryPoint::Manifest) => {
-            gbfs_v3::run_v3_0_manifest(&client, url).await?
+            gbfs_v3_0::run_v3_0_manifest(&client, url).await?
         }
-        (GbfsVersion::V3_0, EntryPoint::Gbfs) => gbfs_v3::run_v3_0_gbfs(&client, url)
+        (GbfsVersion::V3_0, EntryPoint::Gbfs) => gbfs_v3_0::run_v3_0_gbfs(&client, url)
             .await
             .map(|g| vec![g])?,
+        _ => return Err("version not supported".to_string()),
     };
 
     for row in result.into_iter() {
@@ -53,21 +122,15 @@ pub async fn run_gbfs_download_old(
 
 /// designed to download from a GBFS system list file such as
 /// <https://github.com/MobilityData/gbfs/blob/master/systems.csv>.
-pub async fn run_gbfs_batch_download(
+pub async fn gbfs_batch_metadata_download(
     urls: &[String],
     entry_point: EntryPoint,
     out_dir: &Path,
+    parallelism: Option<usize>,
+    delay_ms: Option<u64>,
 ) -> Result<(), String> {
-    // Keep defaults conservative to avoid API throttling; allow overrides via env vars.
-    let max_concurrency = std::env::var("BAMBAM_GBFS_MAX_CONCURRENCY")
-        .ok()
-        .and_then(|v| v.parse::<usize>().ok())
-        .filter(|&v| v > 0)
-        .unwrap_or(4);
-    let request_spacing_secs = std::env::var("BAMBAM_GBFS_REQUEST_SPACING_SECS")
-        .ok()
-        .and_then(|v| v.parse::<u64>().ok())
-        .unwrap_or(2);
+    let par = parallelism.unwrap_or(1);
+    let del = delay_ms.unwrap_or_default();
 
     let bar: Arc<Mutex<Bar>> = Arc::new(Mutex::new(
         BarBuilder::default()
@@ -77,12 +140,12 @@ pub async fn run_gbfs_batch_download(
             .map_err(|e| format!("error building progress bar: {e}"))?,
     ));
     let client = Arc::new(reqwest::Client::new());
-    let semaphore = Arc::new(Semaphore::new(max_concurrency));
+    let semaphore = Arc::new(Semaphore::new(par));
     let mut next_start_at = Instant::now();
-    let spacing = Duration::from_secs(request_spacing_secs);
+    let spacing = Duration::from_millis(del);
 
     log::info!(
-        "starting calls to download archives via {entry_point} entry point (max_concurrency={max_concurrency}, request_spacing_secs={request_spacing_secs})"
+        "starting calls to download archives via {entry_point} entry point (parallelism={par}, delay={del})"
     );
     let mut set = tokio::task::JoinSet::new();
     for url in urls.into_iter() {
@@ -151,6 +214,17 @@ async fn run_gbfs_download(
         super::ops::retrieve_file(&client, &url).await?;
 
     let result: Vec<GbfsRecord> = match unversioned.version {
+        super::download_metadata::UnversionedGbfsVersion::V2_2 => {
+            let result = match entry_point {
+                EntryPoint::Manifest => {
+                    return Err("manifest entry point not supported for version 2.2".to_string());
+                }
+                EntryPoint::Gbfs => gbfs_v2_2::run_v2_2_gbfs(&client, &url)
+                    .await
+                    .map(|g| vec![g])?,
+            };
+            result.into_iter().map(|r| GbfsRecord::V2_2(r)).collect()
+        }
         super::download_metadata::UnversionedGbfsVersion::V2_3 => {
             let result = match entry_point {
                 EntryPoint::Manifest => gbfs_v2_3::run_v2_3_manifest(&client, &url).await?,
@@ -162,8 +236,8 @@ async fn run_gbfs_download(
         }
         super::download_metadata::UnversionedGbfsVersion::V3_0 => {
             let result = match entry_point {
-                EntryPoint::Manifest => gbfs_v3::run_v3_0_manifest(&client, &url).await?,
-                EntryPoint::Gbfs => gbfs_v3::run_v3_0_gbfs(&client, &url)
+                EntryPoint::Manifest => gbfs_v3_0::run_v3_0_manifest(&client, &url).await?,
+                EntryPoint::Gbfs => gbfs_v3_0::run_v3_0_gbfs(&client, &url)
                     .await
                     .map(|g| vec![g])?,
             };
@@ -177,3 +251,30 @@ async fn run_gbfs_download(
 
     Ok(result)
 }
+
+/// helper function to build a filewriter for writing either .csv.gz or
+/// .txt.gz files for compass datasets while respecting the user's overwrite
+/// preferences and properly formatting WKT outputs.
+fn create_writer(
+    directory: &Path,
+    filename: &str,
+    has_headers: bool,
+    quote_style: QuoteStyle,
+    overwrite: bool,
+) -> Result<csv::Writer<GzEncoder<File>>, String> {
+    let filepath = directory.join(filename);
+    if filepath.exists() && !overwrite {
+        return Err(format!(
+            "user chose overwrite=false but file {} exists",
+            filepath.to_string_lossy()
+        ));
+    }
+    let file = File::create(&filepath)
+        .map_err(|e| format!("failure creating file {}: {e}", filepath.to_string_lossy()))?;
+    let buffer = GzEncoder::new(file, Compression::default());
+    let writer = csv::WriterBuilder::new()
+        .has_headers(has_headers)
+        .quote_style(quote_style)
+        .from_writer(buffer);
+    Ok(writer)
+}
diff --git a/rust/bambam-gbfs/src/app/download/zone_constraints.rs b/rust/bambam-gbfs/src/app/download/zone_constraints.rs
new file mode 100644
index 00000000..578c8dcf
--- /dev/null
+++ b/rust/bambam-gbfs/src/app/download/zone_constraints.rs
@@ -0,0 +1,233 @@
+use itertools::Itertools;
+use serde::{Deserialize, Serialize};
+
+pub type VehicleTypeId = String;
+
+/// geofencing_zones "rules" object that contains logical rules.
+#[derive(Default, Clone, Debug)]
+pub struct ZoneConstraints {
+    /// Is the ride allowed to start in this zone?
+    pub ride_start_allowed: Option<bool>,
+    /// Is the ride allowed to end in this zone?
+    pub ride_end_allowed: Option<bool>,
+    /// Is the ride allowed to travel through this zone?
+    pub ride_through_allowed: Option<bool>,
+    /// What is the maximum speed allowed, in kilometers per hour?
+    pub maximum_speed_kph: Option<i32>,
+    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
+    pub station_parking: Option<bool>,
+    /// Array of IDs of vehicle types for which any restrictions SHOULD be applied.
+    /// If vehicle type IDs are not specified, then restrictions apply to all vehicle types.
+    pub vehicle_type_ids: Option<Vec<VehicleTypeId>>,
+}
+
+impl ZoneConstraints {
+    /// default behavior if no Rules are encountered for a feature.
+    pub fn allow_all() -> Self {
+        Self {
+            ride_start_allowed: Some(true),
+            ride_end_allowed: Some(true),
+            ride_through_allowed: Some(true),
+            maximum_speed_kph: Some(i32::MAX),
+            station_parking: Some(true),
+            vehicle_type_ids: None,
+        }
+    }
+
+    /// converts v2_3 Rules into ZoneConstraints for either a zone or for a global ruleset.
+    pub fn from_v2_3(
+        rules: Option<&Vec<gbfs_types::v2_3::files::geofencing_zones::Rule>>,
+    ) -> Vec<ZoneConstraints> {
+        match rules {
+            Some(rs) => rs.iter().map(|r| r.into()).collect_vec(),
+            None => vec![],
+        }
+    }
+
+    /// converts v3_0 Rules into ZoneConstraints for either a zone or for a global ruleset.
+    pub fn from_v3_0(
+        rules: Option<&Vec<gbfs_types::v3_0::files::geofencing_zones::Rule>>,
+    ) -> Vec<ZoneConstraints> {
+        match rules {
+            Some(rs) => rs.iter().map(|r| r.into()).collect_vec(),
+            None => vec![],
+        }
+    }
+
+    /// from a list of constraints, merge according to the rules of precedence found at
+    /// <https://github.com/MobilityData/gbfs/blob/master/gbfs.md#geofencing-rule-precedence>.
+    ///
+    /// here, we ensure that:
+    ///   - When multiple rules in the same array apply to a particular vehicle type, per the
+    /// semantics of the vehicle_type_ids field, then the earlier rule (in order of the JSON file)
+    /// takes precedence for that vehicle type.
+    ///   - When a polygon and the global_rules field define rules that apply to a particular
+    /// vehicle type, then the rules from the polygon take precedence for that vehicle type
+    /// in the area of the polygon.
+    pub fn merge_constraints(
+        global_constraints: &[ZoneConstraints],
+        constraints: &[ZoneConstraints],
+        for_vehicle_type: Option<&VehicleTypeId>,
+    ) -> Option<ZoneConstraints> {
+        let iter: Box<dyn Iterator<Item = &ZoneConstraints>> =
+            match (global_constraints, constraints) {
+                ([], []) => return None,
+                (glob, []) => Box::new(glob.iter()),
+                ([], zone) => Box::new(zone.iter()),
+                (glob, zone) => Box::new(zone.iter().chain(glob.iter())),
+            };
+
+        let mut accumulator = Self::default();
+        for c in iter {
+            if matches_accumulator(c, for_vehicle_type) {
+                accumulator.append(c);
+            }
+        }
+        Some(accumulator)
+    }
+
+    /// appends the values of another set of constraints onto this one.
+    ///
+    /// per documentation:
+    ///
+    /// > When multiple rules in the same array apply to a particular vehicle type,
+    /// > per the semantics of the vehicle_type_ids field, then the earlier rule
+    /// > (in order of the JSON file) takes precedence for that vehicle type.
+    ///
+    /// see <https://github.com/MobilityData/gbfs/blob/master/gbfs.md#geofencing-rule-precedence>
+    fn append(&mut self, other: &ZoneConstraints) {
+        self.maximum_speed_kph =
+            merge_no_overwrite(self.maximum_speed_kph, other.maximum_speed_kph);
+        self.ride_start_allowed =
+            merge_no_overwrite(self.ride_start_allowed, other.ride_start_allowed);
+        self.ride_end_allowed = merge_no_overwrite(self.ride_end_allowed, other.ride_end_allowed);
+        self.ride_through_allowed =
+            merge_no_overwrite(self.ride_through_allowed, other.ride_through_allowed);
+        self.station_parking = merge_no_overwrite(self.station_parking, other.station_parking);
+    }
+}
+
+/// the subset of VehicleType related to route planning. ignored fields are commented out.
+/// taken from gbfs_types::v3_0::files::vehicle_types.
+#[allow(unused)]
+#[serde_with::skip_serializing_none]
+#[derive(Serialize, Deserialize, Debug, Clone)]
+pub struct VehicleTypeConstraints {
+    /// Unique identifier of a vehicle type.
+    pub vehicle_type_id: VehicleTypeId,
+    // /// The vehicle's general form factor.
+    // pub form_factor: Option<String>,
+    // /// The number of riders (driver included) the vehicle can legally accommodate.
+    // pub rider_capacity: Option<u8>,
+    // /// Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
+    // pub cargo_volume_capacity: Option<i32>,
+    // /// The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms.
+    // pub cargo_load_capacity: Option<f64>,
+    // /// The primary propulsion type of the vehicle.
+    // pub propulsion_type: Option<String>,
+    // // /// Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones.
+    // // pub eco_labels: Option<Vec<EcoLabel>>,
+    // /// This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example, a full battery or full tank of gas).
+    pub max_range_meters: Option<f64>,
+    /// The public name of this vehicle type.
+    pub name: Option<Vec<String>>,
+    // /// Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently.
+    // pub vehicle_accessories: Option<Vec<String>>,
+    // // /// Maximum quantity of CO2, in grams, emitted per kilometer, according to the [WLTP](https://en.wikipedia.org/wiki/Worldwide_Harmonised_Light_Vehicles_Test_Procedure).
+    // // pub g_CO2_km: Option<i64>,
+    // /// URL to an image that would assist the user in identifying the vehicle (for example, an image of the vehicle or a logo).
+    // pub vehicle_image: Option<String>,
+    // /// The name of the vehicle manufacturer.
+    // pub make: Option<Vec<String>>,
+    // /// The name of the vehicle model.
+    // pub model: Option<Vec<String>>,
+    // /// The color of the vehicle.
+    // pub color: Option<String>,
+    // /// Customer-readable description of the vehicle type outlining special features or how-tos.
+    // pub description: Option<Vec<String>>,
+    // /// Number of wheels this vehicle type has.
+    // pub wheel_count: Option<u8>,
+    /// The maximum speed in kilometers per hour this vehicle is permitted to reach in accordance with local permit and regulations.
+    pub max_permitted_speed: Option<u8>,
+    // /// The rated power of the motor for this vehicle type in watts.
+    // pub rated_power: Option<u32>,
+    // /// Maximum time in minutes that a vehicle can be reserved before a rental begins.
+    // /// If default_reserve_time is set to 0, the vehicle type cannot be reserved.
+    // pub default_reserve_time: Option<u32>,
+    // /// The conditions for returning the vehicle at the end of the rental.
+    // pub return_constraint: Option<String>,
+    // pub vehicle_assets: Option<VehicleAsset>,
+    // /// A plan_id, as defined in system_pricing_plans.json, that identifies a default pricing plan for this vehicle to be used by trip planning applications for purposes of calculating the cost of a single trip using this vehicle type.
+    // /// This default pricing plan is superseded by `pricing_plan_id` when `pricing_plan_id` is defined in `vehicle_status.json`.
+    // pub default_pricing_plan_id: Option<PricingPlanID>,
+    // /// All pricing plan IDs that are applied to this vehicle type.
+    // pub pricing_plan_ids: Option<Vec<PricingPlanID>>,
+}
+
+impl From<&gbfs_types::v2_3::files::geofencing_zones::Rule> for ZoneConstraints {
+    fn from(value: &gbfs_types::v2_3::files::geofencing_zones::Rule) -> Self {
+        Self {
+            vehicle_type_ids: value.vehicle_type_id.clone(),
+            ride_start_allowed: Some(value.ride_allowed),
+            ride_end_allowed: Some(value.ride_allowed),
+            ride_through_allowed: Some(value.ride_through_allowed),
+            maximum_speed_kph: value.maximum_speed_kph,
+            station_parking: value.station_parking,
+        }
+    }
+}
+
+impl From<&gbfs_types::v3_0::files::geofencing_zones::Rule> for ZoneConstraints {
+    fn from(value: &gbfs_types::v3_0::files::geofencing_zones::Rule) -> Self {
+        Self {
+            vehicle_type_ids: value.vehicle_type_ids.clone(),
+            ride_start_allowed: Some(value.ride_start_allowed),
+            ride_end_allowed: Some(value.ride_end_allowed),
+            ride_through_allowed: Some(value.ride_through_allowed),
+            maximum_speed_kph: value.maximum_speed_kph,
+            station_parking: value.station_parking,
+        }
+    }
+}
+
+impl From<&super::gbfs_v2_2::types::GeofenceRules> for ZoneConstraints {
+    fn from(value: &super::gbfs_v2_2::types::GeofenceRules) -> Self {
+        Self {
+            vehicle_type_ids: value.vehicle_type_id.clone(),
+            ride_start_allowed: Some(value.ride_allowed),
+            ride_end_allowed: Some(value.ride_allowed),
+            ride_through_allowed: Some(value.ride_through_allowed),
+            maximum_speed_kph: value.maximum_speed_kph,
+            station_parking: None,
+        }
+    }
+}
+
+/// helper for testing if the accumulator's vehicle type argument matches the constraint set.
+fn matches_accumulator(
+    constraint: &ZoneConstraints,
+    for_vehicle_type: Option<&VehicleTypeId>,
+) -> bool {
+    match (for_vehicle_type, &constraint.vehicle_type_ids) {
+        (None, None) => true,
+        (None, Some(_)) => false,
+        (Some(_), None) => false,
+        (Some(acc_type), Some(c_types)) => c_types.contains(acc_type),
+    }
+}
+
+/// per documentation:
+///
+/// > When multiple rules in the same array apply to a particular vehicle type,
+/// > per the semantics of the vehicle_type_ids field, then the earlier rule
+/// > (in order of the JSON file) takes precedence for that vehicle type.
+///
+/// see <https://github.com/MobilityData/gbfs/blob/master/gbfs.md#geofencing-rule-precedence>s
+fn merge_no_overwrite<T>(lhs: Option<T>, rhs: Option<T>) -> Option<T> {
+    match (lhs, rhs) {
+        (None, None) => None,
+        (None, Some(r)) => Some(r),
+        (Some(l), None) => Some(l),
+        (Some(l), Some(_)) => Some(l),
+    }
+}
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index c5b453ee..3d0bb000 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -53,6 +53,25 @@ pub enum GbfsOperation {
         /// output directory path.
         #[arg(short, long, default_value_t = String::from("."))]
         output_directory: String,
+        #[arg(long, default_value = None)]
+        parallelism: Option<usize>,
+        #[arg(long, default_value = None)]
+        delay: Option<u64>,
+    },
+    /// downloads a GBFS archive from its .gbfs endpoint.
+    DownloadAndImport {
+        /// a GBFS API URL
+        #[arg(long)]
+        gbfs_url: String,
+        /// output directory path.
+        #[arg(long)]
+        output_directory: String,
+        /// GBFS version number to download.
+        #[arg(long)]
+        version: GbfsVersion,
+        /// whether to overwrite the files if they already exist.
+        #[arg(long)]
+        overwrite: bool,
     },
 }
 
@@ -66,7 +85,7 @@ impl GbfsOperation {
                 entry_point,
                 version,
             } => {
-                crate::app::download::run_gbfs_download_old(
+                crate::app::download::run::gbfs_download_old(
                     gbfs_url,
                     Path::new(output_directory),
                     collect_duration,
@@ -80,13 +99,31 @@ impl GbfsOperation {
                 csv_column,
                 entry_point,
                 output_directory,
+                parallelism,
+                delay,
             } => {
                 let urls = crate::app::download::ops::gather_feeds(csv_file, csv_column)?;
                 log::info!("found {} urls", urls.len());
-                crate::app::download::run_gbfs_batch_download(
+                crate::app::download::run::gbfs_batch_metadata_download(
                     &urls,
                     *entry_point,
                     Path::new(output_directory),
+                    parallelism.clone(),
+                    delay.clone(),
+                )
+                .await
+            }
+            GbfsOperation::DownloadAndImport {
+                gbfs_url,
+                output_directory,
+                version,
+                overwrite,
+            } => {
+                crate::app::download::run::gbfs_download_import(
+                    gbfs_url,
+                    Path::new(output_directory),
+                    *version,
+                    *overwrite,
                 )
                 .await
             }
diff --git a/rust/bambam-gbfs/src/model/gbfs/mod.rs b/rust/bambam-gbfs/src/model/gbfs/mod.rs
index 1f46c735..ca5bf25b 100644
--- a/rust/bambam-gbfs/src/model/gbfs/mod.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/mod.rs
@@ -1 +1,4 @@
 mod record;
+
+pub use record::GbfsZoneRecord;
+pub mod ops;
diff --git a/rust/bambam-gbfs/src/model/gbfs/ops.rs b/rust/bambam-gbfs/src/model/gbfs/ops.rs
new file mode 100644
index 00000000..e51bfd92
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/ops.rs
@@ -0,0 +1,15 @@
+/// builds a globally-unique identifier for a zone. based on the fact that
+/// system_ids are defined as globally unique. as documented at
+/// <https://github.com/MobilityData/gbfs/blob/master/gbfs.md#system_informationjson>:
+///
+/// > [system_id] is a globally unique identifier for the vehicle share system. Each distinct system
+/// > or geographic area in which vehicles are operated MUST have its own unique system_id. It
+/// > is up to the publisher of the feed to guarantee uniqueness and MUST be checked against
+/// > existing system_id fields in systems.csv to ensure this. This value is intended to remain
+/// > the same over the life of the system.
+/// >
+/// > System IDs SHOULD be recognizable as belonging to a particular system as opposed to random
+/// > strings - for example, bcycle_austin or biketown_pdx.
+pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: usize) -> String {
+    format!("{system_id}#{zone_feature_index}")
+}
diff --git a/rust/bambam-gbfs/src/model/gbfs/record.rs b/rust/bambam-gbfs/src/model/gbfs/record.rs
index 3b840b6a..2fa71268 100644
--- a/rust/bambam-gbfs/src/model/gbfs/record.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/record.rs
@@ -1,7 +1,55 @@
 use serde::{Deserialize, Serialize};
 
+use crate::{app::download::ZoneConstraints, model::gbfs::ops};
+
+/// a composite of SystemInformation and GeofencingZone attributes along with a
+/// globally-unique identifier for this zone. the geometry is stored elsewhere.
 #[derive(Serialize, Deserialize, Clone, Debug)]
-pub struct GbfsImportRecord {
-    fq_id: String,
-    system_id: String,
+pub struct GbfsZoneRecord {
+    /// a globally-unique zone identifier that combines the system id and zone index
+    pub fq_id: String,
+    /// GBFS SystemInformation.system_id value.
+    pub system_id: String,
+    /// index of the geojson feature associated with this zone
+    pub feature_index: usize,
+    /// optional start time for using this zone
+    pub start: Option<String>,
+    /// optional end time for using this zone
+    pub end: Option<String>,
+    /// Is the ride allowed to start in this zone?
+    pub ride_start_allowed: bool,
+    /// Is the ride allowed to end in this zone?
+    pub ride_end_allowed: bool,
+    /// Is the ride allowed to travel through this zone?
+    pub ride_through_allowed: bool,
+    /// What is the maximum speed allowed, in kilometers per hour?
+    pub maximum_speed_kph: Option<i32>,
+    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
+    pub station_parking: bool,
+}
+
+impl GbfsZoneRecord {
+    /// create a record for a zone, including its identifiers and its constraint set.
+    /// if a given boolean constraint is found to be None, apply a permissive rule.
+    pub fn new(
+        system_id: String,
+        feature_index: usize,
+        start: Option<String>,
+        end: Option<String>,
+        zone_constraints: ZoneConstraints,
+    ) -> Self {
+        let fq_id = ops::fully_qualified_zone_id(&system_id, feature_index);
+        Self {
+            fq_id,
+            system_id,
+            feature_index,
+            start,
+            end,
+            ride_start_allowed: zone_constraints.ride_start_allowed.unwrap_or(true),
+            ride_end_allowed: zone_constraints.ride_end_allowed.unwrap_or(true),
+            ride_through_allowed: zone_constraints.ride_through_allowed.unwrap_or(true),
+            maximum_speed_kph: zone_constraints.maximum_speed_kph,
+            station_parking: zone_constraints.station_parking.unwrap_or(true),
+        }
+    }
 }

From 24dfa31fe04bb1f799e93f59073efd07683b5d9d Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Fri, 24 Jul 2026 14:40:44 -0600
Subject: [PATCH 11/43] clippy

---
 rust/bambam-gbfs/src/app/download/gbfs_record.rs |  6 +++---
 rust/bambam-gbfs/src/app/download/run.rs         | 10 +++++-----
 rust/bambam-gbfs/src/app/gbfs_cli.rs             |  4 ++--
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/gbfs_record.rs b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
index 2269f7fb..0376e32f 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_record.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
@@ -159,7 +159,7 @@ impl GbfsRecord {
                     &found_constraints,
                     None,
                 )
-                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                .unwrap_or_else(ZoneConstraints::allow_all);
                 Ok(GbfsZoneRecord::new(
                     system_id,
                     idx,
@@ -195,7 +195,7 @@ impl GbfsRecord {
                     &found_constraints,
                     None,
                 )
-                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                .unwrap_or_else(ZoneConstraints::allow_all);
                 Ok(GbfsZoneRecord::new(
                     system_id,
                     idx,
@@ -231,7 +231,7 @@ impl GbfsRecord {
                     &found_constraints,
                     None,
                 )
-                .unwrap_or_else(|| ZoneConstraints::allow_all());
+                .unwrap_or_else(ZoneConstraints::allow_all);
                 Ok(GbfsZoneRecord::new(
                     system_id,
                     idx,
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 3bca7724..63d0ff0a 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -148,7 +148,7 @@ pub async fn gbfs_batch_metadata_download(
         "starting calls to download archives via {entry_point} entry point (parallelism={par}, delay={del})"
     );
     let mut set = tokio::task::JoinSet::new();
-    for url in urls.into_iter() {
+    for url in urls.iter() {
         let client = client.clone();
         let semaphore = semaphore.clone();
         let url = url.to_string();
@@ -176,7 +176,7 @@ pub async fn gbfs_batch_metadata_download(
         match res {
             Ok(Err(e)) => errors.push(e),
             Err(e) => errors.push(format!("error on tokio join of task: {e}")),
-            Ok(Ok(r)) => results.extend(r.into_iter()),
+            Ok(Ok(r)) => results.extend(r),
         }
     }
 
@@ -223,7 +223,7 @@ async fn run_gbfs_download(
                     .await
                     .map(|g| vec![g])?,
             };
-            result.into_iter().map(|r| GbfsRecord::V2_2(r)).collect()
+            result.into_iter().map(GbfsRecord::V2_2).collect()
         }
         super::download_metadata::UnversionedGbfsVersion::V2_3 => {
             let result = match entry_point {
@@ -232,7 +232,7 @@ async fn run_gbfs_download(
                     .await
                     .map(|g| vec![g])?,
             };
-            result.into_iter().map(|r| GbfsRecord::V2_3(r)).collect()
+            result.into_iter().map(GbfsRecord::V2_3).collect()
         }
         super::download_metadata::UnversionedGbfsVersion::V3_0 => {
             let result = match entry_point {
@@ -241,7 +241,7 @@ async fn run_gbfs_download(
                     .await
                     .map(|g| vec![g])?,
             };
-            result.into_iter().map(|r| GbfsRecord::V3_0(r)).collect()
+            result.into_iter().map(GbfsRecord::V3_0).collect()
         }
     };
 
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index 3d0bb000..a1eac193 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -108,8 +108,8 @@ impl GbfsOperation {
                     &urls,
                     *entry_point,
                     Path::new(output_directory),
-                    parallelism.clone(),
-                    delay.clone(),
+                    *parallelism,
+                    *delay,
                 )
                 .await
             }

From e66618edd71b7f00f503ed423ef77b95b9f720ac Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Fri, 24 Jul 2026 14:58:12 -0600
Subject: [PATCH 12/43] scaffold models for GBFS

---
 .../src/model/constraint/boarding/builder.rs  | 24 ------
 .../src/model/constraint/boarding/config.rs   |  5 --
 .../src/model/constraint/boarding/engine.rs   | 75 -------------------
 .../src/model/constraint/boarding/mod.rs      | 11 ---
 .../src/model/constraint/boarding/model.rs    | 38 ----------
 .../src/model/constraint/boarding/service.rs  | 30 --------
 .../constraint/gbfs_constraint/builder.rs     | 27 +++++++
 .../constraint/gbfs_constraint/config.rs      |  4 +
 .../constraint/gbfs_constraint/engine.rs      | 15 ++++
 .../model/constraint/gbfs_constraint/mod.rs   | 19 +++++
 .../model/constraint/gbfs_constraint/model.rs | 38 ++++++++++
 .../constraint/gbfs_constraint/params.rs      |  4 +
 .../constraint/gbfs_constraint/service.rs     | 35 +++++++++
 .../src/model/constraint/geofence/builder.rs  | 24 ------
 .../src/model/constraint/geofence/config.rs   |  5 --
 .../src/model/constraint/geofence/engine.rs   | 75 -------------------
 .../src/model/constraint/geofence/mod.rs      | 11 ---
 .../src/model/constraint/geofence/model.rs    | 39 ----------
 .../src/model/constraint/geofence/service.rs  | 30 --------
 rust/bambam-gbfs/src/model/constraint/mod.rs  |  3 +-
 .../src/model/traversal/boarding/builder.rs   | 23 ------
 .../src/model/traversal/boarding/config.rs    |  8 --
 .../src/model/traversal/boarding/mod.rs       |  9 ---
 .../src/model/traversal/boarding/service.rs   | 28 -------
 .../model/traversal/gbfs_traversal/builder.rs | 27 +++++++
 .../model/traversal/gbfs_traversal/config.rs  |  4 +
 .../model/traversal/gbfs_traversal/engine.rs  | 15 ++++
 .../src/model/traversal/gbfs_traversal/mod.rs | 13 ++++
 .../{boarding => gbfs_traversal}/model.rs     | 35 ++++++---
 .../model/traversal/gbfs_traversal/params.rs  |  4 +
 .../model/traversal/gbfs_traversal/service.rs | 33 ++++++++
 rust/bambam-gbfs/src/model/traversal/mod.rs   |  2 +-
 rust/bambam/src/model/builders.rs             | 19 +----
 33 files changed, 268 insertions(+), 464 deletions(-)
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/builder.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/config.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/engine.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/mod.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/model.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/boarding/service.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/mod.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
 create mode 100644 rust/bambam-gbfs/src/model/constraint/gbfs_constraint/service.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/builder.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/config.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/engine.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/mod.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/model.rs
 delete mode 100644 rust/bambam-gbfs/src/model/constraint/geofence/service.rs
 delete mode 100644 rust/bambam-gbfs/src/model/traversal/boarding/builder.rs
 delete mode 100644 rust/bambam-gbfs/src/model/traversal/boarding/config.rs
 delete mode 100644 rust/bambam-gbfs/src/model/traversal/boarding/mod.rs
 delete mode 100644 rust/bambam-gbfs/src/model/traversal/boarding/service.rs
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/builder.rs
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/mod.rs
 rename rust/bambam-gbfs/src/model/traversal/{boarding => gbfs_traversal}/model.rs (60%)
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
 create mode 100644 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/service.rs

diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/builder.rs b/rust/bambam-gbfs/src/model/constraint/boarding/builder.rs
deleted file mode 100644
index 86f5fb1f..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/builder.rs
+++ /dev/null
@@ -1,24 +0,0 @@
-use std::sync::Arc;
-
-use routee_compass_core::model::constraint::{
-    ConstraintModelBuilder, ConstraintModelError, ConstraintModelService,
-};
-use routee_compass_core::util::geo::PolygonalRTree;
-
-use super::{BoardingConstraintConfig, BoardingConstraintEngine, BoardingConstraintService};
-
-pub struct BoardingConstraintBuilder {}
-
-impl ConstraintModelBuilder for BoardingConstraintBuilder {
-    fn build(
-        &self,
-        parameters: &serde_json::Value,
-    ) -> Result<Arc<dyn ConstraintModelService>, ConstraintModelError> {
-        let config: BoardingConstraintConfig = serde_json::from_value(parameters.clone())
-            .map_err(|e| ConstraintModelError::BuildError(e.to_string()))?;
-        let rtree = PolygonalRTree::new(vec![]).map_err(ConstraintModelError::BuildError)?;
-        let engine = BoardingConstraintEngine::new(config, rtree);
-        let service = BoardingConstraintService::new(engine);
-        Ok(Arc::new(service))
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/config.rs b/rust/bambam-gbfs/src/model/constraint/boarding/config.rs
deleted file mode 100644
index f10851ef..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/config.rs
+++ /dev/null
@@ -1,5 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-#[derive(Serialize, Deserialize, Clone, Debug)]
-#[serde(rename_all = "snake_case")]
-pub struct BoardingConstraintConfig {}
diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/engine.rs b/rust/bambam-gbfs/src/model/constraint/boarding/engine.rs
deleted file mode 100644
index 10621e5f..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/engine.rs
+++ /dev/null
@@ -1,75 +0,0 @@
-use routee_compass_core::{
-    model::{constraint::ConstraintModelError, network::Vertex},
-    util::geo::PolygonalRTree,
-};
-
-use super::BoardingConstraintConfig;
-
-// whatever the type of BoardingId should be
-type BoardingId = String;
-
-pub struct BoardingConstraintEngine {
-    pub config: BoardingConstraintConfig,
-    pub rtree: PolygonalRTree<f32, BoardingId>,
-}
-
-impl BoardingConstraintEngine {
-    pub fn new(
-        config: BoardingConstraintConfig,
-        rtree: PolygonalRTree<f32, BoardingId>,
-    ) -> BoardingConstraintEngine {
-        BoardingConstraintEngine { config, rtree }
-    }
-
-    pub fn in_geofence(
-        &self,
-        vertex: &Vertex,
-        geofence_id: &str,
-    ) -> Result<bool, ConstraintModelError> {
-        let pt = geo::Geometry::Point(geo::Point::new(vertex.x(), vertex.y()));
-        let mut iter = self.rtree.intersection(&pt).map_err(|e| {
-            ConstraintModelError::ConstraintModelError(format!(
-                "failure checking geofence for {:?}: {e}",
-                vertex.coordinate.x_y()
-            ))
-        })?;
-        match iter.next() {
-            Some(boundary) => {
-                let result = boundary.data == geofence_id;
-                Ok(result)
-            }
-            _ => Ok(false),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use routee_compass_core::{model::network::Vertex, util::geo::PolygonalRTree};
-
-    use crate::model::constraint::boarding::BoardingConstraintConfig;
-
-    use super::BoardingConstraintEngine;
-
-    #[test]
-    fn test_in_geofence() {
-        let config = BoardingConstraintConfig {};
-        let polygon = geo::Geometry::Polygon(geo::Polygon::new(
-            geo::line_string![
-                (0.0, 0.0).into(),
-                (1.0, 0.0).into(),
-                (1.0, 1.0).into(),
-                (0.0, 1.0).into(),
-                (0.0, 0.0).into()
-            ],
-            vec![],
-        ));
-        let rtree = PolygonalRTree::new(vec![(polygon, "zone 1".to_string())])
-            .expect("test invariant failed: could not build Rtree");
-        let engine = BoardingConstraintEngine::new(config, rtree);
-        let vertex = Vertex::new(0, 0.5, 0.5);
-        let result = engine.in_geofence(&vertex, "zone 1");
-        assert!(result.is_ok());
-        assert!(result.unwrap());
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/mod.rs b/rust/bambam-gbfs/src/model/constraint/boarding/mod.rs
deleted file mode 100644
index 4dc7b8bb..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/mod.rs
+++ /dev/null
@@ -1,11 +0,0 @@
-mod builder;
-mod config;
-mod engine;
-mod model;
-mod service;
-
-pub use builder::BoardingConstraintBuilder;
-pub use config::BoardingConstraintConfig;
-pub use engine::BoardingConstraintEngine;
-pub use model::BoardingConstraintModel;
-pub use service::BoardingConstraintService;
diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/model.rs b/rust/bambam-gbfs/src/model/constraint/boarding/model.rs
deleted file mode 100644
index cc393505..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/model.rs
+++ /dev/null
@@ -1,38 +0,0 @@
-use std::sync::Arc;
-
-use routee_compass_core::model::{
-    constraint::ConstraintModel,
-    state::{StateModel, StateVariable},
-    traversal::EdgeFrontierContext,
-};
-
-use super::BoardingConstraintEngine;
-
-pub struct BoardingConstraintModel {
-    pub engine: Arc<BoardingConstraintEngine>,
-}
-
-/// restricts where GBFS boarding can occur by zone
-impl BoardingConstraintModel {
-    pub fn new(engine: Arc<BoardingConstraintEngine>) -> BoardingConstraintModel {
-        BoardingConstraintModel { engine }
-    }
-}
-
-impl ConstraintModel for BoardingConstraintModel {
-    fn valid_frontier(
-        &self,
-        _ctx: &EdgeFrontierContext,
-        _state: &[StateVariable],
-        _state_model: &StateModel,
-    ) -> Result<bool, routee_compass_core::model::constraint::ConstraintModelError> {
-        todo!()
-    }
-
-    fn valid_edge(
-        &self,
-        _edge: &routee_compass_core::model::network::Edge,
-    ) -> Result<bool, routee_compass_core::model::constraint::ConstraintModelError> {
-        todo!()
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/boarding/service.rs b/rust/bambam-gbfs/src/model/constraint/boarding/service.rs
deleted file mode 100644
index 6622eb8d..00000000
--- a/rust/bambam-gbfs/src/model/constraint/boarding/service.rs
+++ /dev/null
@@ -1,30 +0,0 @@
-use std::sync::Arc;
-
-use super::{BoardingConstraintEngine, BoardingConstraintModel};
-
-use routee_compass_core::model::{
-    constraint::{ConstraintModel, ConstraintModelError, ConstraintModelService},
-    state::StateModel,
-};
-
-pub struct BoardingConstraintService {
-    pub engine: Arc<BoardingConstraintEngine>,
-}
-
-impl BoardingConstraintService {
-    pub fn new(engine: BoardingConstraintEngine) -> BoardingConstraintService {
-        BoardingConstraintService {
-            engine: Arc::new(engine),
-        }
-    }
-}
-
-impl ConstraintModelService for BoardingConstraintService {
-    fn build(
-        &self,
-        _query: &serde_json::Value,
-        _state_model: Arc<StateModel>,
-    ) -> Result<Arc<dyn ConstraintModel>, ConstraintModelError> {
-        Ok(Arc::new(BoardingConstraintModel::new(self.engine.clone())))
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
new file mode 100644
index 00000000..a513d80b
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
@@ -0,0 +1,27 @@
+use std::sync::Arc;
+
+use super::{GbfsConstraintConfig, GbfsConstraintEngine, GbfsConstraintService};
+
+use routee_compass_core::model::constraint::{
+    ConstraintModelBuilder, ConstraintModelError, ConstraintModelService,
+};
+
+pub struct GbfsConstraintBuilder {}
+
+impl ConstraintModelBuilder for GbfsConstraintBuilder {
+    fn build(
+        &self,
+        value: &serde_json::Value,
+    ) -> Result<Arc<dyn ConstraintModelService>, ConstraintModelError> {
+        let config: GbfsConstraintConfig = serde_json::from_value(value.clone()).map_err(|e| {
+            let msg = format!("failure reading config for GbfsConstraint builder: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
+        let engine = GbfsConstraintEngine::try_from(config).map_err(|e| {
+            let msg = format!("failure building engine from config for GbfsConstraint builder: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
+        let service = GbfsConstraintService::new(engine);
+        Ok(Arc::new(service))
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
new file mode 100644
index 00000000..a658b04d
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
@@ -0,0 +1,4 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug)]
+pub struct GbfsConstraintConfig {}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
new file mode 100644
index 00000000..ea54f823
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -0,0 +1,15 @@
+use super::GbfsConstraintConfig;
+
+use routee_compass_core::model::constraint::ConstraintModelError;
+
+pub struct GbfsConstraintEngine {
+    config: GbfsConstraintConfig,
+}
+
+impl TryFrom<GbfsConstraintConfig> for GbfsConstraintEngine {
+    type Error = ConstraintModelError;
+
+    fn try_from(config: GbfsConstraintConfig) -> Result<Self, Self::Error> {
+        Ok(Self { config })
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/mod.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/mod.rs
new file mode 100644
index 00000000..1e278038
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/mod.rs
@@ -0,0 +1,19 @@
+//! GbfsConstraint Constraint Model
+//!
+//! A stubbed version of a constraint model module that compiles. Used in codegen.
+//! If code changes in Compass lead to compiler errors in this module, the changes
+//! should get updated.
+
+mod builder;
+mod config;
+mod engine;
+mod model;
+mod params;
+mod service;
+
+pub use builder::GbfsConstraintBuilder;
+pub use config::GbfsConstraintConfig;
+pub use engine::GbfsConstraintEngine;
+pub use model::GbfsConstraintModel;
+pub use params::GbfsConstraintParams;
+pub use service::GbfsConstraintService;
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
new file mode 100644
index 00000000..3cbed806
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
@@ -0,0 +1,38 @@
+use std::sync::Arc;
+
+use super::{GbfsConstraintEngine, GbfsConstraintParams};
+
+use routee_compass_core::model::{
+    constraint::{ConstraintModel, ConstraintModelError},
+    network::Edge,
+    state::{StateModel, StateVariable},
+    traversal::EdgeFrontierContext,
+};
+
+pub struct GbfsConstraintModel {
+    pub engine: Arc<GbfsConstraintEngine>,
+    pub params: GbfsConstraintParams,
+}
+
+impl GbfsConstraintModel {
+    pub fn new(engine: Arc<GbfsConstraintEngine>, params: GbfsConstraintParams) -> Self {
+        // modify this and the struct definition if additional pre-processing
+        // is required during model instantiation from query parameters.
+        Self { engine, params }
+    }
+}
+
+impl ConstraintModel for GbfsConstraintModel {
+    fn valid_frontier(
+        &self,
+        _ctx: &EdgeFrontierContext,
+        _state: &[StateVariable],
+        _state_model: &StateModel,
+    ) -> Result<bool, ConstraintModelError> {
+        todo!()
+    }
+
+    fn valid_edge(&self, _edge: &Edge) -> Result<bool, ConstraintModelError> {
+        todo!()
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
new file mode 100644
index 00000000..a055d9a4
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
@@ -0,0 +1,4 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug)]
+pub struct GbfsConstraintParams {}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/service.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/service.rs
new file mode 100644
index 00000000..dad63a13
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/service.rs
@@ -0,0 +1,35 @@
+use std::sync::Arc;
+
+use super::{GbfsConstraintEngine, GbfsConstraintModel, GbfsConstraintParams};
+
+use routee_compass_core::model::{
+    constraint::{ConstraintModel, ConstraintModelError, ConstraintModelService},
+    state::StateModel,
+};
+
+pub struct GbfsConstraintService {
+    engine: Arc<GbfsConstraintEngine>,
+}
+
+impl GbfsConstraintService {
+    pub fn new(engine: GbfsConstraintEngine) -> Self {
+        Self {
+            engine: Arc::new(engine),
+        }
+    }
+}
+
+impl ConstraintModelService for GbfsConstraintService {
+    fn build(
+        &self,
+        query: &serde_json::Value,
+        #[allow(unused)] state_model: Arc<StateModel>,
+    ) -> Result<Arc<dyn ConstraintModel>, ConstraintModelError> {
+        let params: GbfsConstraintParams = serde_json::from_value(query.clone()).map_err(|e| {
+            let msg = format!("failure reading params for GbfsConstraint service: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
+        let model = GbfsConstraintModel::new(self.engine.clone(), params);
+        Ok(Arc::new(model))
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/builder.rs b/rust/bambam-gbfs/src/model/constraint/geofence/builder.rs
deleted file mode 100644
index cab1db33..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/builder.rs
+++ /dev/null
@@ -1,24 +0,0 @@
-use std::sync::Arc;
-
-use crate::model::constraint::geofence::GeofenceConstraintEngine;
-
-use super::{GeofenceConstraintConfig, GeofenceConstraintService};
-use routee_compass_core::model::constraint::{
-    ConstraintModelBuilder, ConstraintModelError, ConstraintModelService,
-};
-use routee_compass_core::util::geo::PolygonalRTree;
-pub struct GeofenceConstraintBuilder {}
-
-impl ConstraintModelBuilder for GeofenceConstraintBuilder {
-    fn build(
-        &self,
-        parameters: &serde_json::Value,
-    ) -> Result<Arc<dyn ConstraintModelService>, ConstraintModelError> {
-        let config: GeofenceConstraintConfig = serde_json::from_value(parameters.clone())
-            .map_err(|e| ConstraintModelError::BuildError(e.to_string()))?;
-        let rtree = PolygonalRTree::new(vec![]).map_err(ConstraintModelError::BuildError)?;
-        let engine = GeofenceConstraintEngine::new(config, rtree);
-        let service = GeofenceConstraintService::new(engine);
-        Ok(Arc::new(service))
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/config.rs b/rust/bambam-gbfs/src/model/constraint/geofence/config.rs
deleted file mode 100644
index d15558b6..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/config.rs
+++ /dev/null
@@ -1,5 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-#[derive(Serialize, Deserialize, Clone, Debug)]
-#[serde(rename_all = "snake_case")]
-pub struct GeofenceConstraintConfig {}
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/engine.rs b/rust/bambam-gbfs/src/model/constraint/geofence/engine.rs
deleted file mode 100644
index 1db7f901..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/engine.rs
+++ /dev/null
@@ -1,75 +0,0 @@
-use routee_compass_core::{
-    model::{constraint::ConstraintModelError, network::Vertex},
-    util::geo::PolygonalRTree,
-};
-
-use crate::model::constraint::geofence::GeofenceConstraintConfig;
-
-// whatever the type of GeofenceId should be
-type GeofenceId = String;
-
-pub struct GeofenceConstraintEngine {
-    pub config: GeofenceConstraintConfig,
-    pub rtree: PolygonalRTree<f32, GeofenceId>,
-}
-
-impl GeofenceConstraintEngine {
-    pub fn new(
-        config: GeofenceConstraintConfig,
-        rtree: PolygonalRTree<f32, GeofenceId>,
-    ) -> GeofenceConstraintEngine {
-        GeofenceConstraintEngine { config, rtree }
-    }
-
-    pub fn in_geofence(
-        &self,
-        vertex: &Vertex,
-        geofence_id: &str,
-    ) -> Result<bool, ConstraintModelError> {
-        let pt = geo::Geometry::Point(geo::Point::new(vertex.x(), vertex.y()));
-        let mut iter = self.rtree.intersection(&pt).map_err(|e| {
-            ConstraintModelError::ConstraintModelError(format!(
-                "failure checking geofence for {:?}: {e}",
-                vertex.coordinate.x_y()
-            ))
-        })?;
-        match iter.next() {
-            Some(boundary) => {
-                let result = boundary.data == geofence_id;
-                Ok(result)
-            }
-            _ => Ok(false),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use routee_compass_core::{model::network::Vertex, util::geo::PolygonalRTree};
-
-    use crate::model::constraint::geofence::GeofenceConstraintConfig;
-
-    use super::GeofenceConstraintEngine;
-
-    #[test]
-    fn test_in_geofence() {
-        let config = GeofenceConstraintConfig {};
-        let polygon = geo::Geometry::Polygon(geo::Polygon::new(
-            geo::line_string![
-                (0.0, 0.0).into(),
-                (1.0, 0.0).into(),
-                (1.0, 1.0).into(),
-                (0.0, 1.0).into(),
-                (0.0, 0.0).into()
-            ],
-            vec![],
-        ));
-        let rtree = PolygonalRTree::new(vec![(polygon, "zone 1".to_string())])
-            .expect("test invariant failed: could not build Rtree");
-        let engine = GeofenceConstraintEngine::new(config, rtree);
-        let vertex = Vertex::new(0, 0.5, 0.5);
-        let result = engine.in_geofence(&vertex, "zone 1");
-        assert!(result.is_ok());
-        assert!(result.unwrap());
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/mod.rs b/rust/bambam-gbfs/src/model/constraint/geofence/mod.rs
deleted file mode 100644
index 190edd4a..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/mod.rs
+++ /dev/null
@@ -1,11 +0,0 @@
-mod builder;
-mod config;
-mod engine;
-mod model;
-mod service;
-
-pub use builder::GeofenceConstraintBuilder;
-pub use config::GeofenceConstraintConfig;
-pub use engine::GeofenceConstraintEngine;
-pub use model::GeofenceConstraintModel;
-pub use service::GeofenceConstraintService;
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/model.rs b/rust/bambam-gbfs/src/model/constraint/geofence/model.rs
deleted file mode 100644
index 92227a76..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/model.rs
+++ /dev/null
@@ -1,39 +0,0 @@
-use std::sync::Arc;
-
-use routee_compass_core::model::{
-    constraint::ConstraintModel,
-    state::{StateModel, StateVariable},
-    traversal::EdgeFrontierContext,
-};
-
-use crate::model::constraint::geofence::GeofenceConstraintEngine;
-
-/// looks up a geofence by agency id to test whether an edge traversal
-/// does not exit the region supported by this GBFS travel mode.
-pub struct GeofenceConstraintModel {
-    pub engine: Arc<GeofenceConstraintEngine>,
-}
-
-impl GeofenceConstraintModel {
-    pub fn new(engine: Arc<GeofenceConstraintEngine>) -> GeofenceConstraintModel {
-        GeofenceConstraintModel { engine }
-    }
-}
-
-impl ConstraintModel for GeofenceConstraintModel {
-    fn valid_frontier(
-        &self,
-        _ctx: &EdgeFrontierContext,
-        _state: &[StateVariable],
-        _state_model: &StateModel,
-    ) -> Result<bool, routee_compass_core::model::constraint::ConstraintModelError> {
-        todo!()
-    }
-
-    fn valid_edge(
-        &self,
-        _edge: &routee_compass_core::model::network::Edge,
-    ) -> Result<bool, routee_compass_core::model::constraint::ConstraintModelError> {
-        todo!()
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/geofence/service.rs b/rust/bambam-gbfs/src/model/constraint/geofence/service.rs
deleted file mode 100644
index 4fe607d2..00000000
--- a/rust/bambam-gbfs/src/model/constraint/geofence/service.rs
+++ /dev/null
@@ -1,30 +0,0 @@
-use std::sync::Arc;
-
-use crate::model::constraint::geofence::{GeofenceConstraintEngine, GeofenceConstraintModel};
-
-use routee_compass_core::model::{
-    constraint::{ConstraintModel, ConstraintModelError, ConstraintModelService},
-    state::StateModel,
-};
-
-pub struct GeofenceConstraintService {
-    pub engine: Arc<GeofenceConstraintEngine>,
-}
-
-impl GeofenceConstraintService {
-    pub fn new(engine: GeofenceConstraintEngine) -> GeofenceConstraintService {
-        GeofenceConstraintService {
-            engine: Arc::new(engine),
-        }
-    }
-}
-
-impl ConstraintModelService for GeofenceConstraintService {
-    fn build(
-        &self,
-        _query: &serde_json::Value,
-        _state_model: Arc<StateModel>,
-    ) -> Result<Arc<dyn ConstraintModel>, ConstraintModelError> {
-        Ok(Arc::new(GeofenceConstraintModel::new(self.engine.clone())))
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/constraint/mod.rs b/rust/bambam-gbfs/src/model/constraint/mod.rs
index a4435e23..db64a87c 100644
--- a/rust/bambam-gbfs/src/model/constraint/mod.rs
+++ b/rust/bambam-gbfs/src/model/constraint/mod.rs
@@ -1,2 +1 @@
-pub mod boarding;
-pub mod geofence;
+pub mod gbfs_constraint;
diff --git a/rust/bambam-gbfs/src/model/traversal/boarding/builder.rs b/rust/bambam-gbfs/src/model/traversal/boarding/builder.rs
deleted file mode 100644
index 00d745e1..00000000
--- a/rust/bambam-gbfs/src/model/traversal/boarding/builder.rs
+++ /dev/null
@@ -1,23 +0,0 @@
-use std::sync::Arc;
-
-use routee_compass_core::model::traversal::{
-    TraversalModelBuilder, TraversalModelError, TraversalModelService,
-};
-
-use super::{BoardingTraversalConfig, BoardingTraversalService};
-
-pub struct BoardingTraversalBuilder {}
-
-impl TraversalModelBuilder for BoardingTraversalBuilder {
-    fn build(
-        &self,
-        parameters: &serde_json::Value,
-    ) -> Result<Arc<dyn TraversalModelService>, TraversalModelError> {
-        let config: BoardingTraversalConfig = serde_json::from_value(parameters.clone())
-            .map_err(|e| TraversalModelError::BuildError(e.to_string()))?;
-        // this is where you will read GBFS files and store the data as fields
-        // on the GBFS traversal service.
-        let service = BoardingTraversalService::new(config);
-        Ok(Arc::new(service))
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/traversal/boarding/config.rs b/rust/bambam-gbfs/src/model/traversal/boarding/config.rs
deleted file mode 100644
index 9cf0c0b4..00000000
--- a/rust/bambam-gbfs/src/model/traversal/boarding/config.rs
+++ /dev/null
@@ -1,8 +0,0 @@
-use serde::{Deserialize, Serialize};
-
-/// this is where you will add the expected configuration fields required for
-/// creating a GBFS service such as `gbfs_input_file: String` and any other
-/// requirements for setting up GBFS for search.
-#[derive(Serialize, Deserialize, Clone, Debug)]
-#[serde(rename_all = "snake_case")]
-pub struct BoardingTraversalConfig {}
diff --git a/rust/bambam-gbfs/src/model/traversal/boarding/mod.rs b/rust/bambam-gbfs/src/model/traversal/boarding/mod.rs
deleted file mode 100644
index 1f6bc6aa..00000000
--- a/rust/bambam-gbfs/src/model/traversal/boarding/mod.rs
+++ /dev/null
@@ -1,9 +0,0 @@
-mod builder;
-mod config;
-mod model;
-mod service;
-
-pub use builder::BoardingTraversalBuilder;
-pub use config::BoardingTraversalConfig;
-pub use model::BoardingTraversalModel;
-pub use service::BoardingTraversalService;
diff --git a/rust/bambam-gbfs/src/model/traversal/boarding/service.rs b/rust/bambam-gbfs/src/model/traversal/boarding/service.rs
deleted file mode 100644
index dfde5858..00000000
--- a/rust/bambam-gbfs/src/model/traversal/boarding/service.rs
+++ /dev/null
@@ -1,28 +0,0 @@
-use std::sync::Arc;
-
-use routee_compass_core::model::traversal::{
-    TraversalModel, TraversalModelError, TraversalModelService,
-};
-
-use super::BoardingTraversalConfig;
-
-pub struct BoardingTraversalService {
-    pub config: BoardingTraversalConfig,
-}
-
-impl BoardingTraversalService {
-    pub fn new(config: BoardingTraversalConfig) -> BoardingTraversalService {
-        BoardingTraversalService { config }
-    }
-}
-
-impl TraversalModelService for BoardingTraversalService {
-    fn build(
-        &self,
-        _query: &serde_json::Value,
-    ) -> Result<Arc<dyn TraversalModel>, TraversalModelError> {
-        // if there's anything that can change between the execution of each search,
-        // we should attempt to pull it from the query here.
-        todo!()
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/builder.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/builder.rs
new file mode 100644
index 00000000..add48801
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/builder.rs
@@ -0,0 +1,27 @@
+use std::sync::Arc;
+
+use super::{GbfsTraversalConfig, GbfsTraversalEngine, GbfsTraversalService};
+
+use routee_compass_core::model::traversal::{
+    TraversalModelBuilder, TraversalModelError, TraversalModelService,
+};
+
+pub struct GbfsTraversalBuilder {}
+
+impl TraversalModelBuilder for GbfsTraversalBuilder {
+    fn build(
+        &self,
+        value: &serde_json::Value,
+    ) -> Result<Arc<dyn TraversalModelService>, TraversalModelError> {
+        let config: GbfsTraversalConfig = serde_json::from_value(value.clone()).map_err(|e| {
+            let msg = format!("failure reading config for GbfsTraversal builder: {e}");
+            TraversalModelError::BuildError(msg)
+        })?;
+        let engine = GbfsTraversalEngine::try_from(config).map_err(|e| {
+            let msg = format!("failure building engine from config for GbfsTraversal builder: {e}");
+            TraversalModelError::BuildError(msg)
+        })?;
+        let service = GbfsTraversalService::new(engine);
+        Ok(Arc::new(service))
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
new file mode 100644
index 00000000..a7dbf110
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
@@ -0,0 +1,4 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug)]
+pub struct GbfsTraversalConfig {}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
new file mode 100644
index 00000000..eae50bd5
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -0,0 +1,15 @@
+use super::GbfsTraversalConfig;
+
+use routee_compass_core::model::traversal::TraversalModelError;
+
+pub struct GbfsTraversalEngine {
+    config: GbfsTraversalConfig,
+}
+
+impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
+    type Error = TraversalModelError;
+
+    fn try_from(config: GbfsTraversalConfig) -> Result<Self, Self::Error> {
+        Ok(Self { config })
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/mod.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/mod.rs
new file mode 100644
index 00000000..ad94cf12
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/mod.rs
@@ -0,0 +1,13 @@
+mod builder;
+mod config;
+mod engine;
+mod model;
+mod params;
+mod service;
+
+pub use builder::GbfsTraversalBuilder;
+pub use config::GbfsTraversalConfig;
+pub use engine::GbfsTraversalEngine;
+pub use model::GbfsTraversalModel;
+pub use params::GbfsTraversalParams;
+pub use service::GbfsTraversalService;
diff --git a/rust/bambam-gbfs/src/model/traversal/boarding/model.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
similarity index 60%
rename from rust/bambam-gbfs/src/model/traversal/boarding/model.rs
rename to rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
index 84ad565a..a633c314 100644
--- a/rust/bambam-gbfs/src/model/traversal/boarding/model.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
@@ -1,3 +1,7 @@
+use std::sync::Arc;
+
+use super::{GbfsTraversalEngine, GbfsTraversalParams};
+
 use routee_compass_core::{
     algorithm::search::SearchTree,
     model::{
@@ -7,12 +11,22 @@ use routee_compass_core::{
     },
 };
 
-/// applies wait times when boarding a micromobility vehicle.
-pub struct BoardingTraversalModel {}
+pub struct GbfsTraversalModel {
+    pub engine: Arc<GbfsTraversalEngine>,
+    pub params: GbfsTraversalParams,
+}
 
-impl TraversalModel for BoardingTraversalModel {
+impl GbfsTraversalModel {
+    pub fn new(engine: Arc<GbfsTraversalEngine>, params: GbfsTraversalParams) -> Self {
+        // modify this and the struct definition if additional pre-processing
+        // is required during model instantiation from query parameters.
+        Self { engine, params }
+    }
+}
+
+impl TraversalModel for GbfsTraversalModel {
     fn name(&self) -> String {
-        "BoardingTraversalModel".to_string()
+        "GbfsTraversalModel".to_string()
     }
 
     fn input_features(&self) -> Vec<InputFeature> {
@@ -23,21 +37,20 @@ impl TraversalModel for BoardingTraversalModel {
         todo!()
     }
 
-    fn estimate_traversal(
+    fn traverse_edge(
         &self,
-        _od: (&Vertex, &Vertex),
+        _ctx: &EdgeFrontierContext,
         _state: &mut Vec<StateVariable>,
-        _tree: &SearchTree,
         _state_model: &StateModel,
     ) -> Result<(), TraversalModelError> {
-        // this can be skipped if we aren't trying to use A*.
-        Ok(())
+        todo!()
     }
 
-    fn traverse_edge(
+    fn estimate_traversal(
         &self,
-        _ctx: &EdgeFrontierContext,
+        _od: (&Vertex, &Vertex),
         _state: &mut Vec<StateVariable>,
+        _tree: &SearchTree,
         _state_model: &StateModel,
     ) -> Result<(), TraversalModelError> {
         todo!()
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
new file mode 100644
index 00000000..5c6fc60c
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
@@ -0,0 +1,4 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug)]
+pub struct GbfsTraversalParams {}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/service.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/service.rs
new file mode 100644
index 00000000..a2b4f050
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/service.rs
@@ -0,0 +1,33 @@
+use std::sync::Arc;
+
+use super::{GbfsTraversalEngine, GbfsTraversalModel, GbfsTraversalParams};
+
+use routee_compass_core::model::traversal::{
+    TraversalModel, TraversalModelError, TraversalModelService,
+};
+
+pub struct GbfsTraversalService {
+    engine: Arc<GbfsTraversalEngine>,
+}
+
+impl GbfsTraversalService {
+    pub fn new(engine: GbfsTraversalEngine) -> Self {
+        Self {
+            engine: Arc::new(engine),
+        }
+    }
+}
+
+impl TraversalModelService for GbfsTraversalService {
+    fn build(
+        &self,
+        query: &serde_json::Value,
+    ) -> Result<Arc<dyn TraversalModel>, TraversalModelError> {
+        let params: GbfsTraversalParams = serde_json::from_value(query.clone()).map_err(|e| {
+            let msg = format!("failure reading params for GbfsTraversal service: {e}");
+            TraversalModelError::BuildError(msg)
+        })?;
+        let model = GbfsTraversalModel::new(self.engine.clone(), params);
+        Ok(Arc::new(model))
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/mod.rs b/rust/bambam-gbfs/src/model/traversal/mod.rs
index dd807c51..55b32aa1 100644
--- a/rust/bambam-gbfs/src/model/traversal/mod.rs
+++ b/rust/bambam-gbfs/src/model/traversal/mod.rs
@@ -1 +1 @@
-pub mod boarding;
+pub mod gbfs_traversal;
diff --git a/rust/bambam/src/model/builders.rs b/rust/bambam/src/model/builders.rs
index 35e5d15d..7b2a7485 100644
--- a/rust/bambam/src/model/builders.rs
+++ b/rust/bambam/src/model/builders.rs
@@ -11,9 +11,8 @@ use crate::model::output_plugin::isochrone::isochrone_output_plugin_builder::Iso
 use crate::model::output_plugin::opportunity::OpportunityOutputPluginBuilder;
 use crate::model::traversal::multimodal::MultimodalTraversalBuilder;
 use crate::model::traversal::switch::switch_traversal_builder::SwitchTraversalBuilder;
-use bambam_gbfs::model::constraint::boarding::BoardingConstraintBuilder;
-use bambam_gbfs::model::constraint::geofence::GeofenceConstraintBuilder;
-use bambam_gbfs::model::traversal::boarding::BoardingTraversalBuilder;
+use bambam_gbfs::model::constraint::gbfs_constraint::GbfsConstraintBuilder;
+use bambam_gbfs::model::traversal::gbfs_traversal::GbfsTraversalBuilder;
 use bambam_gtfs::model::traversal::transit::TransitTraversalBuilder;
 use bambam_gtfs_flex::model::constraint::GtfsFlexDepartureFrontierBuilder;
 use bambam_gtfs_flex::model::traversal::flex::GtfsFlexBuilder;
@@ -41,18 +40,8 @@ pub const BUILDER_REGISTRATION: BuilderRegistration = BuilderRegistration(|build
     );
 
     builders.add_traversal_model(String::from("transit"), Rc::new(TransitTraversalBuilder {}));
-    builders.add_constraint_model(
-        "gbfs_geofence".to_string(),
-        Rc::new(GeofenceConstraintBuilder {}),
-    );
-    builders.add_constraint_model(
-        "gbfs_boarding".to_string(),
-        Rc::new(BoardingConstraintBuilder {}),
-    );
-    builders.add_traversal_model(
-        "gbfs_boarding".to_string(),
-        Rc::new(BoardingTraversalBuilder {}),
-    );
+    builders.add_constraint_model("gbfs".to_string(), Rc::new(GbfsConstraintBuilder {}));
+    builders.add_traversal_model("gbfs".to_string(), Rc::new(GbfsTraversalBuilder {}));
 
     builders.add_traversal_model("gtfs-flex".to_string(), Rc::new(GtfsFlexBuilder {}));
 

From 3a7d440685bc709a5ef4f74721aeecc1d1b3dc7e Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Fri, 24 Jul 2026 14:58:17 -0600
Subject: [PATCH 13/43] fmt

---
 .../src/model/constraint/gbfs_constraint/builder.rs            | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
index a513d80b..15f66a15 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/builder.rs
@@ -18,7 +18,8 @@ impl ConstraintModelBuilder for GbfsConstraintBuilder {
             ConstraintModelError::BuildError(msg)
         })?;
         let engine = GbfsConstraintEngine::try_from(config).map_err(|e| {
-            let msg = format!("failure building engine from config for GbfsConstraint builder: {e}");
+            let msg =
+                format!("failure building engine from config for GbfsConstraint builder: {e}");
             ConstraintModelError::BuildError(msg)
         })?;
         let service = GbfsConstraintService::new(engine);

From 9fddb0cef24fe262c4eba00ddece7c3ed5035ebb Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Tue, 28 Jul 2026 17:21:28 -0600
Subject: [PATCH 14/43] GBFS spatiotemporal lookup + rules aggregation

---
 rust/bambam-gbfs/Cargo.toml                   |   2 +
 .../src/app/download/gbfs_record.rs           |  24 +--
 .../constraint/gbfs_constraint/config.rs      |  12 +-
 .../constraint/gbfs_constraint/engine.rs      |  38 +++-
 rust/bambam-gbfs/src/model/gbfs/lookup.rs     | 167 ++++++++++++++++++
 rust/bambam-gbfs/src/model/gbfs/mod.rs        |   4 +
 rust/bambam-gbfs/src/model/gbfs/ops.rs        |   7 +-
 rust/bambam-gbfs/src/model/gbfs/record.rs     |  30 +++-
 rust/bambam-gbfs/src/model/gbfs/rules.rs      |  69 ++++++++
 9 files changed, 320 insertions(+), 33 deletions(-)
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/lookup.rs
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/rules.rs

diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index aa18f49a..60da1a89 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -6,6 +6,7 @@ license = "BSD-3-Clause"
 description = "GBFS Extensions for The Behavior and Advanced Mobility Big Access Model"
 
 [dependencies]
+bambam-core = { workspace = true }
 chrono = { workspace = true }
 clap = { workspace = true }
 csv = { workspace = true }
@@ -26,3 +27,4 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 serde_with = { workspace = true }
 tokio = { workspace = true }
+uom = { workspace = true }
\ No newline at end of file
diff --git a/rust/bambam-gbfs/src/app/download/gbfs_record.rs b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
index 0376e32f..44b14e6c 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_record.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
@@ -160,13 +160,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                Ok(GbfsZoneRecord::new(
-                    system_id,
-                    idx,
-                    start,
-                    end,
-                    zone_constraints,
-                ))
+                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
             }
             GbfsRecord::V2_3(gbfs) => {
                 let system_id = gbfs.info.data.system_id.clone();
@@ -196,13 +190,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                Ok(GbfsZoneRecord::new(
-                    system_id,
-                    idx,
-                    start,
-                    end,
-                    zone_constraints,
-                ))
+                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
             }
             GbfsRecord::V2_2(gbfs) => {
                 let system_id = gbfs.info.data.system_id.clone();
@@ -232,13 +220,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                Ok(GbfsZoneRecord::new(
-                    system_id,
-                    idx,
-                    start,
-                    end,
-                    zone_constraints,
-                ))
+                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
             }
         }
     }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
index a658b04d..9b4bce74 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
@@ -1,4 +1,14 @@
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Clone, Debug)]
-pub struct GbfsConstraintConfig {}
+pub struct GbfsConstraintConfig {
+    /// output of bambam-gbfs CLI import process, contains a record of the
+    /// identifier, optional start/end times for service, and traversal ruleset
+    /// for default vehicles (trips without a VehicleTripId).
+    ///
+    /// see [crate::model::gbfs::GbfsZoneRecord]
+    pub zones_input_file: String,
+    /// output of bambam-gbfs CLI import process, contains zonal geometries
+    /// with matching indices to the zones input file.
+    pub geometries_input_file: String,
+}
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index ea54f823..f72adfe3 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -1,15 +1,49 @@
+use crate::model::gbfs::{GbfsLookupModel, GbfsZoneRecord};
+
 use super::GbfsConstraintConfig;
 
-use routee_compass_core::model::constraint::ConstraintModelError;
+use chrono::{DateTime, Utc};
+use routee_compass_core::model::{
+    constraint::ConstraintModelError,
+    network::Vertex,
+    state::{StateModel, StateVariable},
+};
 
 pub struct GbfsConstraintEngine {
     config: GbfsConstraintConfig,
+    lookup: GbfsLookupModel,
+}
+
+impl GbfsConstraintEngine {
+    /// tests:
+    ///   - are we NOT in a zone? FALSE
+    ///   - does that zone support `ride_through_allowed`? TRUE
+    ///   - otherwise FALSE
+    fn check_valid(
+        &self,
+        vertex: &Vertex,
+        state: &[StateVariable],
+        state_model: &StateModel,
+        start_time: DateTime<Utc>,
+    ) -> Result<bool, String> {
+        let zone = self
+            .lookup
+            .get_zone_rules(vertex, state, state_model, start_time)?;
+        match zone {
+            None => Ok(false), // no zones intersect, this is not a valid place to GBFS
+            Some(z) => Ok(z.ride_through_allowed),
+        }
+    }
 }
 
 impl TryFrom<GbfsConstraintConfig> for GbfsConstraintEngine {
     type Error = ConstraintModelError;
 
     fn try_from(config: GbfsConstraintConfig) -> Result<Self, Self::Error> {
-        Ok(Self { config })
+        let lookup = GbfsLookupModel::try_from(&config).map_err(|e| {
+            let msg = format!("failure building GBFS lookup model: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
+        Ok(Self { config, lookup })
     }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
new file mode 100644
index 00000000..dfa37d96
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -0,0 +1,167 @@
+use crate::model::{
+    constraint::gbfs_constraint::GbfsConstraintConfig,
+    gbfs::{GbfsZoneRecord, ZoneRules},
+};
+
+use bambam_core::{model::state::fieldname, util::geo_utils};
+use chrono::{DateTime, TimeDelta, Utc};
+use geo::Geometry;
+use geozero::{ToGeo, wkt::Wkt};
+use itertools::Itertools;
+use kdam::BarBuilder;
+use routee_compass_core::{
+    model::{
+        network::Vertex,
+        state::{StateModel, StateVariable},
+    },
+    util::{fs::read_utils, geo::PolygonalRTree},
+};
+
+pub struct GbfsLookupModel {
+    rtree: PolygonalRTree<f32, GbfsZoneRecord>,
+    global: Option<GbfsZoneRecord>,
+}
+
+impl TryFrom<&GbfsConstraintConfig> for GbfsLookupModel {
+    type Error = String;
+
+    fn try_from(config: &GbfsConstraintConfig) -> Result<Self, Self::Error> {
+        let (global, zonal_records) = read_records(&config.zones_input_file)?;
+        let geometries = read_geometries(&config.geometries_input_file)?;
+
+        // check sizes match
+        if zonal_records.len() != geometries.len() {
+            let msg = format!(
+                "file {} has {} records (besides global record), but file {} has {} geometries; sizes must match.",
+                config.zones_input_file,
+                zonal_records.len(),
+                config.geometries_input_file,
+                geometries.len()
+            );
+            return Err(msg);
+        }
+
+        let rows = geometries
+            .into_iter()
+            .zip(zonal_records.into_iter())
+            .collect_vec();
+        let rtree = PolygonalRTree::new(rows)
+            .map_err(|e| format!("failure building spatial index: {e}"))?;
+        Ok(Self { rtree, global })
+    }
+}
+
+impl GbfsLookupModel {
+    /// uses the destination vertex of the current edge traversal to find any intersecting
+    /// zones. filters out zonal rules that do not match our trip datetime. combines all
+    /// zone record rules in order to produce a single value result.
+    pub fn get_zone_rules(
+        &self,
+        vertex: &Vertex,
+        state: &[StateVariable],
+        state_model: &StateModel,
+        start_time: DateTime<Utc>,
+    ) -> Result<Option<ZoneRules>, String> {
+        let query = geo::Geometry::Point(geo::Point(vertex.coordinate.0));
+        let time = get_trip_datetime(state, state_model, start_time)?;
+        let intersection = self.spatiotemporal_intersection(&query, time)?;
+        let rules = ZoneRules::from_records(self.global.as_ref(), intersection);
+        Ok(rules)
+    }
+
+    /// inner function that finds all zone matches that intersect a spatiotemporal query.
+    fn spatiotemporal_intersection<'a>(
+        &'a self,
+        spatial_query: &'a Geometry<f32>,
+        time: DateTime<Utc>,
+    ) -> Result<Box<dyn Iterator<Item = &'a GbfsZoneRecord> + 'a>, String> {
+        let matches = self
+            .rtree
+            .intersection(&spatial_query)
+            .map_err(|e| format!("failure running GBFS zone lookup: {e}"))?
+            .filter_map(move |z| {
+                if within_time_range(time, &z.data) {
+                    Some(&z.data)
+                } else {
+                    None
+                }
+            });
+
+        Ok(Box::new(matches))
+    }
+}
+
+/// reads the records and builds a ZoneGraph from them. holds aside the global record
+fn read_records(
+    zone_record_input_file: &str,
+) -> Result<(Option<GbfsZoneRecord>, Vec<GbfsZoneRecord>), String> {
+    let bb = BarBuilder::default().desc("reading zone records");
+    let zone_records: Box<[GbfsZoneRecord]> =
+        read_utils::from_csv(&zone_record_input_file, true, Some(bb), None)
+            .map_err(|e| format!("failure reading zone records: {e}"))?;
+    let (mut globals, zonals): (Vec<GbfsZoneRecord>, Vec<GbfsZoneRecord>) = zone_records
+        .into_iter()
+        .partition(|r| r.feature_index.is_none());
+    let globals_n = globals.len();
+    if globals_n > 1 {
+        return Err(format!(
+            "expected exactly one global record in file '{zone_record_input_file}', found {globals_n}"
+        ));
+    }
+    let global = globals.pop();
+    Ok((global, zonals))
+}
+
+/// reads zonal geometries and ZoneIds from a CSV geometry collection.
+fn read_geometries(geometry_input_file: &str) -> Result<Vec<Geometry<f32>>, String> {
+    let bb = BarBuilder::default().desc("reading zone geometries");
+    let record_strings: Box<[String]> =
+        read_utils::from_csv(&geometry_input_file, true, Some(bb), None)
+            .map_err(|e| format!("failure reading zone geometries: {e}"))?;
+    let rtree_data = record_strings
+        .iter()
+        .enumerate()
+        .map(|(idx, geom_str)| {
+            let geometry = Wkt(geom_str)
+                .to_geo()
+                .map_err(|e| format!("failure reading WKT geometry {idx}: {e}"))?;
+            let geom_f32 = geo_utils::try_convert_f32(&geometry).map_err(|e| {
+                format!(
+                    "failure converting geometry to 32-bit FP representation for index {idx}: {e}",
+                )
+            })?;
+            Ok(geom_f32)
+        })
+        .collect::<Result<Vec<_>, String>>()?;
+
+    Ok(rtree_data)
+}
+
+/// composes a starting datetime value with the trip time on the provided state producing the
+/// current
+fn get_trip_datetime(
+    state: &[StateVariable],
+    state_model: &StateModel,
+    start_time: DateTime<Utc>,
+) -> Result<DateTime<Utc>, String> {
+    let time = state_model
+        .get_time(state, fieldname::TRIP_TIME)
+        .map_err(|e| format!("failure reading {} from state: {e}", fieldname::TRIP_TIME))?;
+    let nanos = time.get::<uom::si::time::nanosecond>() as i64;
+    let timedelta = TimeDelta::nanoseconds(nanos);
+    start_time.checked_add_signed(timedelta).ok_or_else(|| {
+        format!(
+            "adding {nanos} ns to {} is out-of-range",
+            start_time.to_rfc3339()
+        )
+    })
+}
+
+/// times are documented with "If the geofencing zone is always active, this can be omitted."
+/// in this way, we optimistically choose `true` when only one of [start,end] are present.
+fn within_time_range(time: DateTime<Utc>, record: &GbfsZoneRecord) -> bool {
+    match (record.start, record.end) {
+        (Some(s), Some(e)) => s <= time && time < e,
+        _ => true,
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/gbfs/mod.rs b/rust/bambam-gbfs/src/model/gbfs/mod.rs
index ca5bf25b..0fcd2b4a 100644
--- a/rust/bambam-gbfs/src/model/gbfs/mod.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/mod.rs
@@ -1,4 +1,8 @@
+mod lookup;
 mod record;
+mod rules;
 
 pub use record::GbfsZoneRecord;
 pub mod ops;
+pub use lookup::GbfsLookupModel;
+pub use rules::ZoneRules;
diff --git a/rust/bambam-gbfs/src/model/gbfs/ops.rs b/rust/bambam-gbfs/src/model/gbfs/ops.rs
index e51bfd92..14793c8b 100644
--- a/rust/bambam-gbfs/src/model/gbfs/ops.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/ops.rs
@@ -10,6 +10,9 @@
 /// >
 /// > System IDs SHOULD be recognizable as belonging to a particular system as opposed to random
 /// > strings - for example, bcycle_austin or biketown_pdx.
-pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: usize) -> String {
-    format!("{system_id}#{zone_feature_index}")
+pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: Option<usize>) -> String {
+    match zone_feature_index {
+        Some(index) => format!("{system_id}#{index}"),
+        None => system_id.to_string(),
+    }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/record.rs b/rust/bambam-gbfs/src/model/gbfs/record.rs
index 2fa71268..1430995f 100644
--- a/rust/bambam-gbfs/src/model/gbfs/record.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/record.rs
@@ -1,3 +1,4 @@
+use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
 use crate::{app::download::ZoneConstraints, model::gbfs::ops};
@@ -10,12 +11,13 @@ pub struct GbfsZoneRecord {
     pub fq_id: String,
     /// GBFS SystemInformation.system_id value.
     pub system_id: String,
-    /// index of the geojson feature associated with this zone
-    pub feature_index: usize,
+    /// index of the geojson feature associated with this zone. if not provided,
+    /// this record is the global zone record.
+    pub feature_index: Option<usize>,
     /// optional start time for using this zone
-    pub start: Option<String>,
+    pub start: Option<DateTime<Utc>>,
     /// optional end time for using this zone
-    pub end: Option<String>,
+    pub end: Option<DateTime<Utc>>,
     /// Is the ride allowed to start in this zone?
     pub ride_start_allowed: bool,
     /// Is the ride allowed to end in this zone?
@@ -33,13 +35,15 @@ impl GbfsZoneRecord {
     /// if a given boolean constraint is found to be None, apply a permissive rule.
     pub fn new(
         system_id: String,
-        feature_index: usize,
+        feature_index: Option<usize>,
         start: Option<String>,
         end: Option<String>,
         zone_constraints: ZoneConstraints,
-    ) -> Self {
+    ) -> Result<Self, String> {
         let fq_id = ops::fully_qualified_zone_id(&system_id, feature_index);
-        Self {
+        let start = to_datetime(start)?;
+        let end = to_datetime(end)?;
+        let result = Self {
             fq_id,
             system_id,
             feature_index,
@@ -50,6 +54,18 @@ impl GbfsZoneRecord {
             ride_through_allowed: zone_constraints.ride_through_allowed.unwrap_or(true),
             maximum_speed_kph: zone_constraints.maximum_speed_kph,
             station_parking: zone_constraints.station_parking.unwrap_or(true),
+        };
+        Ok(result)
+    }
+}
+
+fn to_datetime(value: Option<String>) -> Result<Option<DateTime<Utc>>, String> {
+    match value {
+        None => Ok(None),
+        Some(dt_string) => {
+            let dt = DateTime::parse_from_rfc3339(&dt_string)
+                .map_err(|e| format!("unable to parse date {dt_string}: {e}"))?;
+            Ok(Some(dt.to_utc()))
         }
     }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/rules.rs b/rust/bambam-gbfs/src/model/gbfs/rules.rs
new file mode 100644
index 00000000..15293de3
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/rules.rs
@@ -0,0 +1,69 @@
+use crate::model::gbfs::GbfsZoneRecord;
+
+/// aggregated record to represent the rules at a given time/place for use of GBFS.
+/// built from the GBFS `geofencing_rules` for all zones that intersect with the
+/// current destination of the graph search, flattened according to the rules of
+/// precedence: <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
+pub struct ZoneRules {
+    /// Is the ride allowed to start in this zone?
+    pub ride_start_allowed: bool,
+    /// Is the ride allowed to end in this zone?
+    pub ride_end_allowed: bool,
+    /// Is the ride allowed to travel through this zone?
+    pub ride_through_allowed: bool,
+    /// What is the maximum speed allowed, in kilometers per hour?
+    pub maximum_speed_kph: Option<i32>,
+    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
+    pub station_parking: bool,
+}
+
+impl ZoneRules {
+    /// combines global and feature zone record "rules" as described in
+    /// <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
+    ///
+    /// note: GbfsZoneRecords have already been "flattened" into concrete
+    /// boolean values by injecting the implicit default value "true" where
+    /// a field is omitted from the source rule.
+    pub fn from_records<'a, 'b>(
+        global: Option<&'a GbfsZoneRecord>,
+        intersection: Box<dyn Iterator<Item = &'b GbfsZoneRecord> + 'b>,
+    ) -> Option<ZoneRules> {
+        let mut ride_start_allowed = global.map(|g| g.ride_start_allowed);
+        let mut ride_end_allowed = global.map(|g| g.ride_end_allowed);
+        let mut ride_through_allowed = global.map(|g| g.ride_through_allowed);
+        let mut maximum_speed_kph = global.and_then(|g| g.maximum_speed_kph);
+        let mut station_parking = global.map(|g| g.station_parking);
+
+        // Sort records by feature index so that the earliest overlapping polygon takes precedence.
+        let mut records: Vec<&GbfsZoneRecord> = intersection.collect();
+        records.sort_by_key(|r| r.feature_index.unwrap_or(usize::MAX));
+
+        // Iterate records from lowest index to highest, applying values and keeping the highest-precedence (lowest index).
+        for record in records {
+            // Apply lowest index record values if an earlier record hasn't set it since we want highest precedence
+            if ride_start_allowed.is_none() {
+                ride_start_allowed = Some(record.ride_start_allowed);
+            }
+            if ride_end_allowed.is_none() {
+                ride_end_allowed = Some(record.ride_end_allowed);
+            }
+            if ride_through_allowed.is_none() {
+                ride_through_allowed = Some(record.ride_through_allowed);
+            }
+            if maximum_speed_kph.is_none() {
+                maximum_speed_kph = record.maximum_speed_kph;
+            }
+            if station_parking.is_none() {
+                station_parking = Some(record.station_parking);
+            }
+        }
+
+        Some(ZoneRules {
+            ride_start_allowed: ride_start_allowed.unwrap_or(true),
+            ride_end_allowed: ride_end_allowed.unwrap_or(true),
+            ride_through_allowed: ride_through_allowed.unwrap_or(true),
+            maximum_speed_kph,
+            station_parking: station_parking.unwrap_or(true),
+        })
+    }
+}

From 0a75394007c35508d50b963909bfa5791d745b3d Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Tue, 28 Jul 2026 17:21:59 -0600
Subject: [PATCH 15/43] cargo sort

---
 rust/bambam-gbfs/Cargo.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/bambam-gbfs/Cargo.toml b/rust/bambam-gbfs/Cargo.toml
index 60da1a89..a7747b5b 100644
--- a/rust/bambam-gbfs/Cargo.toml
+++ b/rust/bambam-gbfs/Cargo.toml
@@ -27,4 +27,4 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 serde_with = { workspace = true }
 tokio = { workspace = true }
-uom = { workspace = true }
\ No newline at end of file
+uom = { workspace = true }

From b2c400da9a9f9e5cd03dda8c2dea7c492dcd8328 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Tue, 28 Jul 2026 17:22:09 -0600
Subject: [PATCH 16/43] clippy

---
 .../src/model/constraint/gbfs_constraint/engine.rs            | 2 +-
 rust/bambam-gbfs/src/model/gbfs/lookup.rs                     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index f72adfe3..3e91236a 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -1,4 +1,4 @@
-use crate::model::gbfs::{GbfsLookupModel, GbfsZoneRecord};
+use crate::model::gbfs::GbfsLookupModel;
 
 use super::GbfsConstraintConfig;
 
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index dfa37d96..d3538816 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -43,7 +43,7 @@ impl TryFrom<&GbfsConstraintConfig> for GbfsLookupModel {
 
         let rows = geometries
             .into_iter()
-            .zip(zonal_records.into_iter())
+            .zip(zonal_records)
             .collect_vec();
         let rtree = PolygonalRTree::new(rows)
             .map_err(|e| format!("failure building spatial index: {e}"))?;
@@ -77,7 +77,7 @@ impl GbfsLookupModel {
     ) -> Result<Box<dyn Iterator<Item = &'a GbfsZoneRecord> + 'a>, String> {
         let matches = self
             .rtree
-            .intersection(&spatial_query)
+            .intersection(spatial_query)
             .map_err(|e| format!("failure running GBFS zone lookup: {e}"))?
             .filter_map(move |z| {
                 if within_time_range(time, &z.data) {

From dd3c053d52045653e56355332f7131cfe3a62a90 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 29 Jul 2026 15:10:49 -0600
Subject: [PATCH 17/43] stub out boarding check + build out features +
 accessors

---
 .../constraint/gbfs_constraint/engine.rs      |  4 +
 rust/bambam-gbfs/src/model/feature.rs         | 93 +++++++++++++++++++
 rust/bambam-gbfs/src/model/mod.rs             |  1 +
 3 files changed, 98 insertions(+)
 create mode 100644 rust/bambam-gbfs/src/model/feature.rs

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index 3e91236a..a14b793d 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -17,6 +17,8 @@ pub struct GbfsConstraintEngine {
 impl GbfsConstraintEngine {
     /// tests:
     ///   - are we NOT in a zone? FALSE
+    ///   - have we boarded?
+    ///     - if FALSE, also check if `ride_start_allowed`
     ///   - does that zone support `ride_through_allowed`? TRUE
     ///   - otherwise FALSE
     fn check_valid(
@@ -26,6 +28,8 @@ impl GbfsConstraintEngine {
         state_model: &StateModel,
         start_time: DateTime<Utc>,
     ) -> Result<bool, String> {
+        todo!("check if boarded");
+
         let zone = self
             .lookup
             .get_zone_rules(vertex, state, state_model, start_time)?;
diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
new file mode 100644
index 00000000..a561a6d7
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -0,0 +1,93 @@
+pub mod fieldname {
+    /// the name of the agency providing the GBFS vehicle.
+    /// if this value is set, the trip has boarded the service.
+    pub const GBFS_AGENCY_ID: &str = "gbfs_agency_id";
+
+    /// true if the trip has a [GBFS_AGENCY_ID] and if the current
+    /// edge has a GBFS zone where `ride_end_allowed` is true.
+    pub const GBFS_DESTINATION: &str = "gbfs_destination";
+}
+
+pub mod variable {
+    //! the configuration for state variables in GTFS-Flex routing
+
+    use routee_compass_core::model::state::{CustomVariableConfig, StateVariableConfig};
+
+    /// stores a zone id in a state variable
+    pub fn gbfs_agency_id() -> StateVariableConfig {
+        StateVariableConfig::Custom {
+            custom_type: "Option<GbfsAgencyId>".to_string(),
+            value: empty(),
+            accumulator: true,
+        }
+    }
+
+    pub fn gbfs_destination() -> StateVariableConfig {
+        StateVariableConfig::Custom {
+            custom_type: "Bool".to_string(),
+            value: CustomVariableConfig::Boolean { initial: false },
+            accumulator: false,
+        }
+    }
+
+    /// empty value is "-1" for categoricals mapped to real numbers
+    pub fn empty() -> CustomVariableConfig {
+        CustomVariableConfig::SignedInteger { initial: -1 }
+    }
+}
+
+pub mod state {
+    use super::fieldname;
+    use bambam_core::model::state::CategoricalStateMapping;
+    use routee_compass_core::model::state::{StateModel, StateModelError, StateVariable};
+
+    /// label value representing un-assigned agency_ids
+    const NO_AGENCY_ID: i64 = -1;
+
+    /// assigns the given agency_id to the state vector.
+    fn set_agency_id(
+        state: &mut [StateVariable],
+        state_model: &StateModel,
+        agency_id: &str,
+        mapping: &CategoricalStateMapping,
+    ) -> Result<(), StateModelError> {
+        let value = mapping.get_label(agency_id).ok_or_else(|| {
+            StateModelError::RuntimeError(format!("agency_id {agency_id} missing from mapping"))
+        })?;
+        state_model.set_custom_i64(state, fieldname::GBFS_AGENCY_ID, value)
+    }
+
+    /// gets the stored agency_id from the state variable, if it exists.
+    fn get_agency_id<'a, 'b>(
+        state: &'a [StateVariable],
+        state_model: &'a StateModel,
+        mapping: &'b CategoricalStateMapping,
+    ) -> Result<Option<&'b String>, StateModelError> {
+        let agency_label = state_model.get_custom_i64(state, fieldname::GBFS_AGENCY_ID)?;
+        let agency_id = mapping.get_categorical(agency_label)?;
+        Ok(agency_id)
+    }
+
+    /// confirms that there is a stored agency_id and that it matches the provided one.
+    fn verify_agency_id(
+        agency_id: &str,
+        state: &[StateVariable],
+        state_model: &StateModel,
+        mapping: &CategoricalStateMapping,
+    ) -> Result<bool, StateModelError> {
+        let stored_agency = get_agency_id(state, state_model, mapping)?;
+        match stored_agency {
+            Some(a) if a == agency_id => Ok(true),
+            _ => Ok(false),
+        }
+    }
+
+    /// confirms that the search has boarded a GBFS agency (that GBFS_AGENCY_ID is set).
+    fn is_boarded(
+        state: &[StateVariable],
+        state_model: &StateModel,
+    ) -> Result<bool, StateModelError> {
+        let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_AGENCY_ID)?;
+        Ok(agency_id != -1)
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/mod.rs b/rust/bambam-gbfs/src/model/mod.rs
index 83c5ffd0..aec35c60 100644
--- a/rust/bambam-gbfs/src/model/mod.rs
+++ b/rust/bambam-gbfs/src/model/mod.rs
@@ -1,3 +1,4 @@
 pub mod constraint;
+pub mod feature;
 pub mod gbfs;
 pub mod traversal;

From 7b9ab43798d5f8f7adf6bdfadf5ea8bcb25d25a4 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 29 Jul 2026 15:10:54 -0600
Subject: [PATCH 18/43] fmt

---
 rust/bambam-gbfs/src/model/gbfs/lookup.rs | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index d3538816..9d39a958 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -41,10 +41,7 @@ impl TryFrom<&GbfsConstraintConfig> for GbfsLookupModel {
             return Err(msg);
         }
 
-        let rows = geometries
-            .into_iter()
-            .zip(zonal_records)
-            .collect_vec();
+        let rows = geometries.into_iter().zip(zonal_records).collect_vec();
         let rtree = PolygonalRTree::new(rows)
             .map_err(|e| format!("failure building spatial index: {e}"))?;
         Ok(Self { rtree, global })

From 671266b22c354813564a9d4313380a1b35d50777 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 30 Jul 2026 11:48:04 -0600
Subject: [PATCH 19/43] GBFS constraint implemented

---
 .../src/app/download/gbfs_record.rs           |   6 +-
 rust/bambam-gbfs/src/app/download/run.rs      |  13 ++-
 .../constraint/gbfs_constraint/config.rs      |   2 +
 .../constraint/gbfs_constraint/engine.rs      |  57 ++++++---
 .../model/constraint/gbfs_constraint/model.rs |  15 ++-
 .../constraint/gbfs_constraint/params.rs      |   6 +-
 rust/bambam-gbfs/src/model/feature.rs         |  20 ++--
 rust/bambam-gbfs/src/model/gbfs/lookup.rs     | 110 ++++++++----------
 .../src/model/gbfs/lookup_config.rs           |  14 +++
 rust/bambam-gbfs/src/model/gbfs/mod.rs        |   6 +-
 rust/bambam-gbfs/src/model/gbfs/ops.rs        |   7 +-
 rust/bambam-gbfs/src/model/gbfs/record.rs     |   4 +-
 rust/bambam-gbfs/src/model/gbfs/rules.rs      |  69 -----------
 rust/bambam-gbfs/src/model/gbfs/state.rs      |  80 +++++++++++++
 .../model/traversal/gbfs_traversal/config.rs  |  14 ++-
 .../model/traversal/gbfs_traversal/engine.rs  |  62 +++++++++-
 16 files changed, 308 insertions(+), 177 deletions(-)
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/lookup_config.rs
 delete mode 100644 rust/bambam-gbfs/src/model/gbfs/rules.rs
 create mode 100644 rust/bambam-gbfs/src/model/gbfs/state.rs

diff --git a/rust/bambam-gbfs/src/app/download/gbfs_record.rs b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
index 44b14e6c..0eefed2d 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_record.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_record.rs
@@ -160,7 +160,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
+                GbfsZoneRecord::new(system_id, idx, start, end, zone_constraints)
             }
             GbfsRecord::V2_3(gbfs) => {
                 let system_id = gbfs.info.data.system_id.clone();
@@ -190,7 +190,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
+                GbfsZoneRecord::new(system_id, idx, start, end, zone_constraints)
             }
             GbfsRecord::V2_2(gbfs) => {
                 let system_id = gbfs.info.data.system_id.clone();
@@ -220,7 +220,7 @@ impl GbfsRecord {
                     None,
                 )
                 .unwrap_or_else(ZoneConstraints::allow_all);
-                GbfsZoneRecord::new(system_id, Some(idx), start, end, zone_constraints)
+                GbfsZoneRecord::new(system_id, idx, start, end, zone_constraints)
             }
         }
     }
diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 63d0ff0a..aaeef68c 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -20,6 +20,7 @@ use crate::app::download::{
 
 const GEOMETRIES_FILENAME: &str = "edges-gbfs-geofences-enumerated.txt.gz";
 const RECORDS_FILENAME: &str = "edges-gbfs-records.csv.gz";
+const IDS_FILENAME: &str = "edges-zone-ids.txt.gz";
 
 pub async fn gbfs_download_import(
     url: &str,
@@ -36,11 +37,14 @@ pub async fn gbfs_download_import(
     // process into BAMBAM-GBFS edge list format
     let mut geometries = vec![];
     let mut zone_records = vec![];
+    let mut ids = vec![];
     for i in 0..gbfs.n_features() {
         let geometry = gbfs.get_feature_geometry(i)?;
         let record = gbfs.get_feature_zone_record(i)?;
+        let id = record.fq_id.clone();
         geometries.push(geometry);
         zone_records.push(record);
+        ids.push(id);
     }
 
     // write outputs
@@ -60,6 +64,7 @@ pub async fn gbfs_download_import(
         QuoteStyle::Necessary,
         overwrite,
     )?;
+    let mut id_writer = create_writer(out_dir, IDS_FILENAME, false, QuoteStyle::Never, overwrite)?;
 
     for (idx, geom) in geometries.into_iter().enumerate() {
         let wkt_string = geom
@@ -74,7 +79,13 @@ pub async fn gbfs_download_import(
     for (idx, record) in zone_records.into_iter().enumerate() {
         record_writer
             .serialize(&record)
-            .map_err(|e| format!("failure writing geometry {idx} to file: {e}"))?
+            .map_err(|e| format!("failure writing record {idx} to file: {e}"))?
+    }
+
+    for (idx, id) in ids.into_iter().enumerate() {
+        id_writer
+            .serialize(&id)
+            .map_err(|e| format!("failure writing {idx}th id {id} to file: {e}"))?
     }
 
     Ok(())
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
index 9b4bce74..f25b989e 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
@@ -11,4 +11,6 @@ pub struct GbfsConstraintConfig {
     /// output of bambam-gbfs CLI import process, contains zonal geometries
     /// with matching indices to the zones input file.
     pub geometries_input_file: String,
+    /// fully-qualified identifiers for each record with matching index to zone + geometry files.
+    pub zone_ids_input_file: String,
 }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index a14b793d..eef2d441 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -1,7 +1,10 @@
-use crate::model::gbfs::GbfsLookupModel;
+use std::path::Path;
+
+use crate::model::{feature, gbfs::GbfsLookupModel};
 
 use super::GbfsConstraintConfig;
 
+use bambam_core::model::state::CategoricalStateMapping;
 use chrono::{DateTime, Utc};
 use routee_compass_core::model::{
     constraint::ConstraintModelError,
@@ -10,8 +13,8 @@ use routee_compass_core::model::{
 };
 
 pub struct GbfsConstraintEngine {
-    config: GbfsConstraintConfig,
     lookup: GbfsLookupModel,
+    mapping: CategoricalStateMapping,
 }
 
 impl GbfsConstraintEngine {
@@ -21,21 +24,35 @@ impl GbfsConstraintEngine {
     ///     - if FALSE, also check if `ride_start_allowed`
     ///   - does that zone support `ride_through_allowed`? TRUE
     ///   - otherwise FALSE
-    fn check_valid(
+    pub fn check_valid(
         &self,
         vertex: &Vertex,
         state: &[StateVariable],
         state_model: &StateModel,
         start_time: DateTime<Utc>,
-    ) -> Result<bool, String> {
-        todo!("check if boarded");
-
-        let zone = self
+    ) -> Result<bool, ConstraintModelError> {
+        let service_opt = feature::state::get_service_id(state, state_model, &self.mapping)
+            .map_err(|e| {
+                let msg = format!("failure inspecting service id of search state: {e}");
+                ConstraintModelError::ConstraintModelError(msg)
+            })?;
+        let zones = self
             .lookup
-            .get_zone_rules(vertex, state, state_model, start_time)?;
-        match zone {
-            None => Ok(false), // no zones intersect, this is not a valid place to GBFS
-            Some(z) => Ok(z.ride_through_allowed),
+            .get_zone_rules(vertex, state, state_model, start_time, service_opt)
+            .map_err(|e| {
+                let msg = format!("failure running GBFS rule lookup: {e}");
+                ConstraintModelError::ConstraintModelError(msg)
+            })?;
+
+        let not_in_a_zone = zones.len() == 0;
+        let through_allowed = zones.iter().any(|z| z.ride_through_allowed);
+        let no_depart_allowed =
+            service_opt.is_none() && !zones.iter().any(|z| z.ride_start_allowed);
+
+        if not_in_a_zone || no_depart_allowed {
+            Ok(false)
+        } else {
+            Ok(through_allowed)
         }
     }
 }
@@ -44,10 +61,20 @@ impl TryFrom<GbfsConstraintConfig> for GbfsConstraintEngine {
     type Error = ConstraintModelError;
 
     fn try_from(config: GbfsConstraintConfig) -> Result<Self, Self::Error> {
-        let lookup = GbfsLookupModel::try_from(&config).map_err(|e| {
-            let msg = format!("failure building GBFS lookup model: {e}");
-            ConstraintModelError::BuildError(msg)
+        let lookup = GbfsLookupModel::new(&config.zones_input_file, &config.geometries_input_file)
+            .map_err(|e| {
+                let msg = format!("failure building GBFS lookup model: {e}");
+                ConstraintModelError::BuildError(msg)
+            })?;
+        let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
+            &config.zone_ids_input_file,
+        ))
+        .map_err(|e| {
+            ConstraintModelError::BuildError(format!(
+                "failure while building categorical mapping from {}: {e}",
+                config.zone_ids_input_file
+            ))
         })?;
-        Ok(Self { config, lookup })
+        Ok(Self { lookup, mapping })
     }
 }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
index 3cbed806..37477e6e 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/model.rs
@@ -25,14 +25,19 @@ impl GbfsConstraintModel {
 impl ConstraintModel for GbfsConstraintModel {
     fn valid_frontier(
         &self,
-        _ctx: &EdgeFrontierContext,
-        _state: &[StateVariable],
-        _state_model: &StateModel,
+        ctx: &EdgeFrontierContext,
+        state: &[StateVariable],
+        state_model: &StateModel,
     ) -> Result<bool, ConstraintModelError> {
-        todo!()
+        self.engine
+            .check_valid(ctx.dst, state, state_model, self.params.start_time)
+            .map_err(|e| {
+                let msg = format!("failure running GBFS constraint model: {e}");
+                ConstraintModelError::ConstraintModelError(msg)
+            })
     }
 
     fn valid_edge(&self, _edge: &Edge) -> Result<bool, ConstraintModelError> {
-        todo!()
+        Ok(true)
     }
 }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
index a055d9a4..781c82ac 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/params.rs
@@ -1,4 +1,8 @@
+use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Clone, Debug)]
-pub struct GbfsConstraintParams {}
+pub struct GbfsConstraintParams {
+    /// time the trip starts
+    pub start_time: DateTime<Utc>,
+}
diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index a561a6d7..2a59bc70 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -1,7 +1,7 @@
 pub mod fieldname {
     /// the name of the agency providing the GBFS vehicle.
     /// if this value is set, the trip has boarded the service.
-    pub const GBFS_AGENCY_ID: &str = "gbfs_agency_id";
+    pub const GBFS_SERVICE_ID: &str = "gbfs_service_id";
 
     /// true if the trip has a [GBFS_AGENCY_ID] and if the current
     /// edge has a GBFS zone where `ride_end_allowed` is true.
@@ -14,7 +14,7 @@ pub mod variable {
     use routee_compass_core::model::state::{CustomVariableConfig, StateVariableConfig};
 
     /// stores a zone id in a state variable
-    pub fn gbfs_agency_id() -> StateVariableConfig {
+    pub fn gbfs_service_id() -> StateVariableConfig {
         StateVariableConfig::Custom {
             custom_type: "Option<GbfsAgencyId>".to_string(),
             value: empty(),
@@ -45,7 +45,7 @@ pub mod state {
     const NO_AGENCY_ID: i64 = -1;
 
     /// assigns the given agency_id to the state vector.
-    fn set_agency_id(
+    pub fn set_service_id(
         state: &mut [StateVariable],
         state_model: &StateModel,
         agency_id: &str,
@@ -54,28 +54,28 @@ pub mod state {
         let value = mapping.get_label(agency_id).ok_or_else(|| {
             StateModelError::RuntimeError(format!("agency_id {agency_id} missing from mapping"))
         })?;
-        state_model.set_custom_i64(state, fieldname::GBFS_AGENCY_ID, value)
+        state_model.set_custom_i64(state, fieldname::GBFS_SERVICE_ID, value)
     }
 
     /// gets the stored agency_id from the state variable, if it exists.
-    fn get_agency_id<'a, 'b>(
+    pub fn get_service_id<'a, 'b>(
         state: &'a [StateVariable],
         state_model: &'a StateModel,
         mapping: &'b CategoricalStateMapping,
     ) -> Result<Option<&'b String>, StateModelError> {
-        let agency_label = state_model.get_custom_i64(state, fieldname::GBFS_AGENCY_ID)?;
+        let agency_label = state_model.get_custom_i64(state, fieldname::GBFS_SERVICE_ID)?;
         let agency_id = mapping.get_categorical(agency_label)?;
         Ok(agency_id)
     }
 
     /// confirms that there is a stored agency_id and that it matches the provided one.
-    fn verify_agency_id(
+    pub fn verify_service_id(
         agency_id: &str,
         state: &[StateVariable],
         state_model: &StateModel,
         mapping: &CategoricalStateMapping,
     ) -> Result<bool, StateModelError> {
-        let stored_agency = get_agency_id(state, state_model, mapping)?;
+        let stored_agency = get_service_id(state, state_model, mapping)?;
         match stored_agency {
             Some(a) if a == agency_id => Ok(true),
             _ => Ok(false),
@@ -83,11 +83,11 @@ pub mod state {
     }
 
     /// confirms that the search has boarded a GBFS agency (that GBFS_AGENCY_ID is set).
-    fn is_boarded(
+    pub fn is_boarded(
         state: &[StateVariable],
         state_model: &StateModel,
     ) -> Result<bool, StateModelError> {
-        let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_AGENCY_ID)?;
+        let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_SERVICE_ID)?;
         Ok(agency_id != -1)
     }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index 9d39a958..ee68877b 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -1,7 +1,4 @@
-use crate::model::{
-    constraint::gbfs_constraint::GbfsConstraintConfig,
-    gbfs::{GbfsZoneRecord, ZoneRules},
-};
+use crate::model::gbfs::{GbfsZoneRecord, ZoneState};
 
 use bambam_core::{model::state::fieldname, util::geo_utils};
 use chrono::{DateTime, TimeDelta, Utc};
@@ -19,23 +16,20 @@ use routee_compass_core::{
 
 pub struct GbfsLookupModel {
     rtree: PolygonalRTree<f32, GbfsZoneRecord>,
-    global: Option<GbfsZoneRecord>,
 }
 
-impl TryFrom<&GbfsConstraintConfig> for GbfsLookupModel {
-    type Error = String;
-
-    fn try_from(config: &GbfsConstraintConfig) -> Result<Self, Self::Error> {
-        let (global, zonal_records) = read_records(&config.zones_input_file)?;
-        let geometries = read_geometries(&config.geometries_input_file)?;
+impl GbfsLookupModel {
+    pub fn new(zones_input_file: &str, geometries_input_file: &str) -> Result<Self, String> {
+        let zonal_records = read_records(&zones_input_file)?;
+        let geometries = read_geometries(&geometries_input_file)?;
 
         // check sizes match
         if zonal_records.len() != geometries.len() {
             let msg = format!(
                 "file {} has {} records (besides global record), but file {} has {} geometries; sizes must match.",
-                config.zones_input_file,
+                zones_input_file,
                 zonal_records.len(),
-                config.geometries_input_file,
+                geometries_input_file,
                 geometries.len()
             );
             return Err(msg);
@@ -44,69 +38,76 @@ impl TryFrom<&GbfsConstraintConfig> for GbfsLookupModel {
         let rows = geometries.into_iter().zip(zonal_records).collect_vec();
         let rtree = PolygonalRTree::new(rows)
             .map_err(|e| format!("failure building spatial index: {e}"))?;
-        Ok(Self { rtree, global })
+        Ok(Self { rtree })
     }
-}
 
-impl GbfsLookupModel {
     /// uses the destination vertex of the current edge traversal to find any intersecting
-    /// zones. filters out zonal rules that do not match our trip datetime. combines all
+    /// zones. filters out zonal rules that do not match our trip datetime. if we are boarded on a GBFS
+    /// provider we further filter to only zones with a matching ServiceId. combines all
     /// zone record rules in order to produce a single value result.
-    pub fn get_zone_rules(
-        &self,
-        vertex: &Vertex,
-        state: &[StateVariable],
-        state_model: &StateModel,
+    pub fn get_zone_rules<'a, 'b>(
+        &'a self,
+        vertex: &'b Vertex,
+        state: &'b [StateVariable],
+        state_model: &'b StateModel,
         start_time: DateTime<Utc>,
-    ) -> Result<Option<ZoneRules>, String> {
+        service_id: Option<&'b String>,
+    ) -> Result<Vec<ZoneState>, String> {
         let query = geo::Geometry::Point(geo::Point(vertex.coordinate.0));
         let time = get_trip_datetime(state, state_model, start_time)?;
-        let intersection = self.spatiotemporal_intersection(&query, time)?;
-        let rules = ZoneRules::from_records(self.global.as_ref(), intersection);
+        let intersection = self.spatiotemporal_intersection(&query, time, service_id)?;
+        let rules = ZoneState::collect_zones(intersection);
         Ok(rules)
     }
 
     /// inner function that finds all zone matches that intersect a spatiotemporal query.
-    fn spatiotemporal_intersection<'a>(
+    fn spatiotemporal_intersection<'a, 'b: 'a>(
         &'a self,
-        spatial_query: &'a Geometry<f32>,
+        spatial_query: &'b Geometry<f32>,
         time: DateTime<Utc>,
-    ) -> Result<Box<dyn Iterator<Item = &'a GbfsZoneRecord> + 'a>, String> {
+        system_id: Option<&'b String>,
+    ) -> Result<Vec<&'a GbfsZoneRecord>, String> {
         let matches = self
             .rtree
             .intersection(spatial_query)
             .map_err(|e| format!("failure running GBFS zone lookup: {e}"))?
-            .filter_map(move |z| {
-                if within_time_range(time, &z.data) {
-                    Some(&z.data)
-                } else {
-                    None
-                }
-            });
+            .filter_map(move |z| zone_matches_search(&z.data, time, system_id));
 
-        Ok(Box::new(matches))
+        Ok(matches.collect_vec())
+    }
+}
+
+/// times are documented with "If the geofencing zone is always active, this can be omitted."
+/// in this way, we optimistically choose `true` when only one of [start,end] are present.
+///
+/// if we are currently boarded, we only accept zone records with a matching system id.
+fn zone_matches_search<'a, 'b>(
+    record: &'a GbfsZoneRecord,
+    time: DateTime<Utc>,
+    system_id: Option<&'b String>,
+) -> Option<&'a GbfsZoneRecord> {
+    let service_ok = match system_id {
+        Some(id) => id == &record.system_id,
+        None => true,
+    };
+    let time_ok = match (record.start, record.end) {
+        (Some(s), Some(e)) => s <= time && time < e,
+        _ => true,
+    };
+    if service_ok && time_ok {
+        Some(record)
+    } else {
+        None
     }
 }
 
 /// reads the records and builds a ZoneGraph from them. holds aside the global record
-fn read_records(
-    zone_record_input_file: &str,
-) -> Result<(Option<GbfsZoneRecord>, Vec<GbfsZoneRecord>), String> {
+fn read_records(zone_record_input_file: &str) -> Result<Vec<GbfsZoneRecord>, String> {
     let bb = BarBuilder::default().desc("reading zone records");
     let zone_records: Box<[GbfsZoneRecord]> =
         read_utils::from_csv(&zone_record_input_file, true, Some(bb), None)
             .map_err(|e| format!("failure reading zone records: {e}"))?;
-    let (mut globals, zonals): (Vec<GbfsZoneRecord>, Vec<GbfsZoneRecord>) = zone_records
-        .into_iter()
-        .partition(|r| r.feature_index.is_none());
-    let globals_n = globals.len();
-    if globals_n > 1 {
-        return Err(format!(
-            "expected exactly one global record in file '{zone_record_input_file}', found {globals_n}"
-        ));
-    }
-    let global = globals.pop();
-    Ok((global, zonals))
+    Ok(zone_records.to_vec())
 }
 
 /// reads zonal geometries and ZoneIds from a CSV geometry collection.
@@ -153,12 +154,3 @@ fn get_trip_datetime(
         )
     })
 }
-
-/// times are documented with "If the geofencing zone is always active, this can be omitted."
-/// in this way, we optimistically choose `true` when only one of [start,end] are present.
-fn within_time_range(time: DateTime<Utc>, record: &GbfsZoneRecord) -> bool {
-    match (record.start, record.end) {
-        (Some(s), Some(e)) => s <= time && time < e,
-        _ => true,
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup_config.rs b/rust/bambam-gbfs/src/model/gbfs/lookup_config.rs
new file mode 100644
index 00000000..70bb96b0
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup_config.rs
@@ -0,0 +1,14 @@
+use serde::{Deserialize, Serialize};
+
+#[derive(Deserialize, Serialize, Clone, Debug)]
+pub struct GbfsLookupConfig {
+    /// output of bambam-gbfs CLI import process, contains a record of the
+    /// identifier, optional start/end times for service, and traversal ruleset
+    /// for default vehicles (trips without a VehicleTripId).
+    ///
+    /// see [crate::model::gbfs::GbfsZoneRecord]
+    pub zones_input_file: String,
+    /// output of bambam-gbfs CLI import process, contains zonal geometries
+    /// with matching indices to the zones input file.
+    pub geometries_input_file: String,
+}
diff --git a/rust/bambam-gbfs/src/model/gbfs/mod.rs b/rust/bambam-gbfs/src/model/gbfs/mod.rs
index 0fcd2b4a..421cb5e1 100644
--- a/rust/bambam-gbfs/src/model/gbfs/mod.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/mod.rs
@@ -1,8 +1,10 @@
 mod lookup;
+mod lookup_config;
 mod record;
-mod rules;
+mod state;
 
 pub use record::GbfsZoneRecord;
 pub mod ops;
 pub use lookup::GbfsLookupModel;
-pub use rules::ZoneRules;
+pub use lookup_config::GbfsLookupConfig;
+pub use state::ZoneState;
diff --git a/rust/bambam-gbfs/src/model/gbfs/ops.rs b/rust/bambam-gbfs/src/model/gbfs/ops.rs
index 14793c8b..e51bfd92 100644
--- a/rust/bambam-gbfs/src/model/gbfs/ops.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/ops.rs
@@ -10,9 +10,6 @@
 /// >
 /// > System IDs SHOULD be recognizable as belonging to a particular system as opposed to random
 /// > strings - for example, bcycle_austin or biketown_pdx.
-pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: Option<usize>) -> String {
-    match zone_feature_index {
-        Some(index) => format!("{system_id}#{index}"),
-        None => system_id.to_string(),
-    }
+pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: usize) -> String {
+    format!("{system_id}#{zone_feature_index}")
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/record.rs b/rust/bambam-gbfs/src/model/gbfs/record.rs
index 1430995f..7928ab93 100644
--- a/rust/bambam-gbfs/src/model/gbfs/record.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/record.rs
@@ -13,7 +13,7 @@ pub struct GbfsZoneRecord {
     pub system_id: String,
     /// index of the geojson feature associated with this zone. if not provided,
     /// this record is the global zone record.
-    pub feature_index: Option<usize>,
+    pub feature_index: usize,
     /// optional start time for using this zone
     pub start: Option<DateTime<Utc>>,
     /// optional end time for using this zone
@@ -35,7 +35,7 @@ impl GbfsZoneRecord {
     /// if a given boolean constraint is found to be None, apply a permissive rule.
     pub fn new(
         system_id: String,
-        feature_index: Option<usize>,
+        feature_index: usize,
         start: Option<String>,
         end: Option<String>,
         zone_constraints: ZoneConstraints,
diff --git a/rust/bambam-gbfs/src/model/gbfs/rules.rs b/rust/bambam-gbfs/src/model/gbfs/rules.rs
deleted file mode 100644
index 15293de3..00000000
--- a/rust/bambam-gbfs/src/model/gbfs/rules.rs
+++ /dev/null
@@ -1,69 +0,0 @@
-use crate::model::gbfs::GbfsZoneRecord;
-
-/// aggregated record to represent the rules at a given time/place for use of GBFS.
-/// built from the GBFS `geofencing_rules` for all zones that intersect with the
-/// current destination of the graph search, flattened according to the rules of
-/// precedence: <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
-pub struct ZoneRules {
-    /// Is the ride allowed to start in this zone?
-    pub ride_start_allowed: bool,
-    /// Is the ride allowed to end in this zone?
-    pub ride_end_allowed: bool,
-    /// Is the ride allowed to travel through this zone?
-    pub ride_through_allowed: bool,
-    /// What is the maximum speed allowed, in kilometers per hour?
-    pub maximum_speed_kph: Option<i32>,
-    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
-    pub station_parking: bool,
-}
-
-impl ZoneRules {
-    /// combines global and feature zone record "rules" as described in
-    /// <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
-    ///
-    /// note: GbfsZoneRecords have already been "flattened" into concrete
-    /// boolean values by injecting the implicit default value "true" where
-    /// a field is omitted from the source rule.
-    pub fn from_records<'a, 'b>(
-        global: Option<&'a GbfsZoneRecord>,
-        intersection: Box<dyn Iterator<Item = &'b GbfsZoneRecord> + 'b>,
-    ) -> Option<ZoneRules> {
-        let mut ride_start_allowed = global.map(|g| g.ride_start_allowed);
-        let mut ride_end_allowed = global.map(|g| g.ride_end_allowed);
-        let mut ride_through_allowed = global.map(|g| g.ride_through_allowed);
-        let mut maximum_speed_kph = global.and_then(|g| g.maximum_speed_kph);
-        let mut station_parking = global.map(|g| g.station_parking);
-
-        // Sort records by feature index so that the earliest overlapping polygon takes precedence.
-        let mut records: Vec<&GbfsZoneRecord> = intersection.collect();
-        records.sort_by_key(|r| r.feature_index.unwrap_or(usize::MAX));
-
-        // Iterate records from lowest index to highest, applying values and keeping the highest-precedence (lowest index).
-        for record in records {
-            // Apply lowest index record values if an earlier record hasn't set it since we want highest precedence
-            if ride_start_allowed.is_none() {
-                ride_start_allowed = Some(record.ride_start_allowed);
-            }
-            if ride_end_allowed.is_none() {
-                ride_end_allowed = Some(record.ride_end_allowed);
-            }
-            if ride_through_allowed.is_none() {
-                ride_through_allowed = Some(record.ride_through_allowed);
-            }
-            if maximum_speed_kph.is_none() {
-                maximum_speed_kph = record.maximum_speed_kph;
-            }
-            if station_parking.is_none() {
-                station_parking = Some(record.station_parking);
-            }
-        }
-
-        Some(ZoneRules {
-            ride_start_allowed: ride_start_allowed.unwrap_or(true),
-            ride_end_allowed: ride_end_allowed.unwrap_or(true),
-            ride_through_allowed: ride_through_allowed.unwrap_or(true),
-            maximum_speed_kph,
-            station_parking: station_parking.unwrap_or(true),
-        })
-    }
-}
diff --git a/rust/bambam-gbfs/src/model/gbfs/state.rs b/rust/bambam-gbfs/src/model/gbfs/state.rs
new file mode 100644
index 00000000..83c62ad1
--- /dev/null
+++ b/rust/bambam-gbfs/src/model/gbfs/state.rs
@@ -0,0 +1,80 @@
+use std::collections::HashMap;
+
+use crate::model::gbfs::GbfsZoneRecord;
+
+/// aggregated record to represent the rules at a given time/place for use of GBFS.
+/// built from the GBFS `geofencing_rules` for all zones that intersect with the
+/// current destination of the graph search, flattened according to the rules of
+/// precedence: <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
+pub struct ZoneState {
+    /// agency associated with this zone.
+    pub system_id: String,
+    /// Is the ride allowed to start in this zone?
+    pub ride_start_allowed: bool,
+    /// Is the ride allowed to end in this zone?
+    pub ride_end_allowed: bool,
+    /// Is the ride allowed to travel through this zone?
+    pub ride_through_allowed: bool,
+    /// What is the maximum speed allowed, in kilometers per hour?
+    pub maximum_speed_kph: Option<i32>,
+    /// Can vehicles only be parked at stations defined in [station_information] within this geofence zone?
+    pub station_parking: bool,
+}
+
+impl ZoneState {
+    pub fn new(record: &GbfsZoneRecord) -> Self {
+        Self {
+            system_id: record.system_id.clone(),
+            ride_start_allowed: record.ride_start_allowed,
+            ride_end_allowed: record.ride_end_allowed,
+            ride_through_allowed: record.ride_through_allowed,
+            maximum_speed_kph: record.maximum_speed_kph,
+            station_parking: record.station_parking,
+        }
+    }
+
+    // only overwrite values if they are the default when appending a lower-tier record, in accordance
+    // with the rules of precedence: <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
+    pub fn append(&mut self, record: &GbfsZoneRecord) {
+        // Apply lowest index record values if an earlier record hasn't set it since we want highest precedence
+        if self.ride_start_allowed {
+            self.ride_start_allowed = record.ride_start_allowed;
+        }
+        if self.ride_end_allowed {
+            self.ride_end_allowed = record.ride_end_allowed;
+        }
+        if self.ride_through_allowed {
+            self.ride_through_allowed = record.ride_through_allowed;
+        }
+        if self.maximum_speed_kph.is_none() {
+            self.maximum_speed_kph = record.maximum_speed_kph;
+        }
+        if self.station_parking {
+            self.station_parking = record.station_parking;
+        }
+    }
+
+    /// combines global and feature zone record "rules" as described in
+    /// <https://gbfs.org/documentation/reference/#geofencing-rule-precedence>.
+    ///
+    /// note: GbfsZoneRecords have already been "flattened" into concrete
+    /// boolean values by injecting the implicit default value "true" where
+    /// a field is omitted from the source rule.
+    pub fn collect_zones(intersection: Vec<&GbfsZoneRecord>) -> Vec<ZoneState> {
+        let mut result: HashMap<&String, Self> = HashMap::new();
+
+        // Sort records by feature index so that the earliest overlapping polygon takes precedence.
+        let mut records: Vec<&GbfsZoneRecord> = intersection.clone();
+        records.sort_by_key(|r| r.feature_index);
+
+        // Iterate records from lowest index to highest, applying values and keeping the highest-precedence (lowest index).
+        for record in records {
+            result
+                .entry(&record.system_id)
+                .and_modify(|zone| zone.append(record))
+                .or_insert(Self::new(record));
+        }
+
+        result.into_values().collect()
+    }
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
index a7dbf110..42d903e4 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
@@ -1,4 +1,16 @@
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Clone, Debug)]
-pub struct GbfsTraversalConfig {}
+pub struct GbfsTraversalConfig {
+    /// output of bambam-gbfs CLI import process, contains a record of the
+    /// identifier, optional start/end times for service, and traversal ruleset
+    /// for default vehicles (trips without a VehicleTripId).
+    ///
+    /// see [crate::model::gbfs::GbfsZoneRecord]
+    pub zones_input_file: String,
+    /// output of bambam-gbfs CLI import process, contains zonal geometries
+    /// with matching indices to the zones input file.
+    pub geometries_input_file: String,
+    /// fully-qualified identifiers for each record with matching index to zone + geometry files.
+    pub zone_ids_input_file: String,
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index eae50bd5..2b5c8e94 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -1,15 +1,69 @@
+use std::path::Path;
+
+use crate::model::{feature, gbfs::GbfsLookupModel};
+
 use super::GbfsTraversalConfig;
 
-use routee_compass_core::model::traversal::TraversalModelError;
+use bambam_core::model::state::CategoricalStateMapping;
+use chrono::{DateTime, Utc};
+use routee_compass_core::model::{
+    constraint::ConstraintModelError,
+    network::Vertex,
+    state::{StateModel, StateVariable},
+    traversal::TraversalModelError,
+};
 
 pub struct GbfsTraversalEngine {
-    config: GbfsTraversalConfig,
+    lookup: GbfsLookupModel,
+    mapping: CategoricalStateMapping,
+}
+
+impl GbfsTraversalEngine {
+    pub fn traverse(
+        &self,
+        vertex: &Vertex,
+        state: &[StateVariable],
+        state_model: &StateModel,
+        start_time: DateTime<Utc>,
+    ) -> Result<(), TraversalModelError> {
+        todo!("1) what is the sequence of ops here? doc them; 2) write logic")
+        // let service_opt = feature::state::get_service_id(state, state_model, &self.mapping)
+        //     .map_err(|e| format!("failure inspecting service id of search state: {e}"))?;
+        // let zones =
+        //     self.lookup
+        //         .get_zone_rules(vertex, state, state_model, start_time, service_opt)?;
+
+        // let not_in_a_zone = zones.len() == 0;
+        // let through_allowed = zones.iter().any(|z| z.ride_through_allowed);
+        // let no_depart_allowed =
+        //     service_opt.is_none() && !zones.iter().any(|z| z.ride_start_allowed);
+
+        // if not_in_a_zone || no_depart_allowed {
+        //     Ok(false)
+        // } else {
+        //     Ok(through_allowed)
+        // }
+    }
 }
 
 impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
-    type Error = TraversalModelError;
+    type Error = ConstraintModelError;
 
     fn try_from(config: GbfsTraversalConfig) -> Result<Self, Self::Error> {
-        Ok(Self { config })
+        let lookup = GbfsLookupModel::new(&config.zones_input_file, &config.geometries_input_file)
+            .map_err(|e| {
+                let msg = format!("failure building GBFS lookup model: {e}");
+                ConstraintModelError::BuildError(msg)
+            })?;
+        let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
+            &config.zone_ids_input_file,
+        ))
+        .map_err(|e| {
+            ConstraintModelError::BuildError(format!(
+                "failure while building categorical mapping from {}: {e}",
+                config.zone_ids_input_file
+            ))
+        })?;
+        Ok(Self { lookup, mapping })
     }
 }

From 6b042cef72dfd44e36c50d99a847eb6a0c942b63 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 30 Jul 2026 11:48:12 -0600
Subject: [PATCH 20/43] clippy

---
 .../src/model/constraint/gbfs_constraint/engine.rs   |  2 +-
 rust/bambam-gbfs/src/model/gbfs/lookup.rs            | 12 ++++++------
 .../src/model/traversal/gbfs_traversal/engine.rs     | 10 +++++-----
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index eef2d441..227c9214 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -44,7 +44,7 @@ impl GbfsConstraintEngine {
                 ConstraintModelError::ConstraintModelError(msg)
             })?;
 
-        let not_in_a_zone = zones.len() == 0;
+        let not_in_a_zone = zones.is_empty();
         let through_allowed = zones.iter().any(|z| z.ride_through_allowed);
         let no_depart_allowed =
             service_opt.is_none() && !zones.iter().any(|z| z.ride_start_allowed);
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index ee68877b..645bab0d 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -20,8 +20,8 @@ pub struct GbfsLookupModel {
 
 impl GbfsLookupModel {
     pub fn new(zones_input_file: &str, geometries_input_file: &str) -> Result<Self, String> {
-        let zonal_records = read_records(&zones_input_file)?;
-        let geometries = read_geometries(&geometries_input_file)?;
+        let zonal_records = read_records(zones_input_file)?;
+        let geometries = read_geometries(geometries_input_file)?;
 
         // check sizes match
         if zonal_records.len() != geometries.len() {
@@ -45,8 +45,8 @@ impl GbfsLookupModel {
     /// zones. filters out zonal rules that do not match our trip datetime. if we are boarded on a GBFS
     /// provider we further filter to only zones with a matching ServiceId. combines all
     /// zone record rules in order to produce a single value result.
-    pub fn get_zone_rules<'a, 'b>(
-        &'a self,
+    pub fn get_zone_rules<'b>(
+        &self,
         vertex: &'b Vertex,
         state: &'b [StateVariable],
         state_model: &'b StateModel,
@@ -81,10 +81,10 @@ impl GbfsLookupModel {
 /// in this way, we optimistically choose `true` when only one of [start,end] are present.
 ///
 /// if we are currently boarded, we only accept zone records with a matching system id.
-fn zone_matches_search<'a, 'b>(
+fn zone_matches_search<'a>(
     record: &'a GbfsZoneRecord,
     time: DateTime<Utc>,
-    system_id: Option<&'b String>,
+    system_id: Option<&String>,
 ) -> Option<&'a GbfsZoneRecord> {
     let service_ok = match system_id {
         Some(id) => id == &record.system_id,
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 2b5c8e94..7a02fc97 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -1,6 +1,6 @@
 use std::path::Path;
 
-use crate::model::{feature, gbfs::GbfsLookupModel};
+use crate::model::gbfs::GbfsLookupModel;
 
 use super::GbfsTraversalConfig;
 
@@ -21,10 +21,10 @@ pub struct GbfsTraversalEngine {
 impl GbfsTraversalEngine {
     pub fn traverse(
         &self,
-        vertex: &Vertex,
-        state: &[StateVariable],
-        state_model: &StateModel,
-        start_time: DateTime<Utc>,
+        _vertex: &Vertex,
+        _state: &[StateVariable],
+        _state_model: &StateModel,
+        _start_time: DateTime<Utc>,
     ) -> Result<(), TraversalModelError> {
         todo!("1) what is the sequence of ops here? doc them; 2) write logic")
         // let service_opt = feature::state::get_service_id(state, state_model, &self.mapping)

From deb079c33bd6a5eca657a2380bd6fdd2188069e3 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Wed, 12 Aug 2026 15:18:25 -0600
Subject: [PATCH 21/43] traversal model for GBFS

---
 .../constraint/gbfs_constraint/engine.rs      |   4 +-
 rust/bambam-gbfs/src/model/feature.rs         |  30 +++-
 rust/bambam-gbfs/src/model/gbfs/lookup.rs     |   2 +-
 rust/bambam-gbfs/src/model/gbfs/state.rs      |  11 ++
 .../model/traversal/gbfs_traversal/config.rs  |   9 ++
 .../model/traversal/gbfs_traversal/engine.rs  | 146 +++++++++++++++---
 .../model/traversal/gbfs_traversal/model.rs   |   2 +
 7 files changed, 171 insertions(+), 33 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index 227c9214..a9917071 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -31,14 +31,14 @@ impl GbfsConstraintEngine {
         state_model: &StateModel,
         start_time: DateTime<Utc>,
     ) -> Result<bool, ConstraintModelError> {
-        let service_opt = feature::state::get_service_id(state, state_model, &self.mapping)
+        let service_opt = feature::state::get_system_id(state, state_model, &self.mapping)
             .map_err(|e| {
                 let msg = format!("failure inspecting service id of search state: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
             })?;
         let zones = self
             .lookup
-            .get_zone_rules(vertex, state, state_model, start_time, service_opt)
+            .matching_zones(vertex, state, state_model, start_time, service_opt)
             .map_err(|e| {
                 let msg = format!("failure running GBFS rule lookup: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index 2a59bc70..8c7b2a72 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -1,7 +1,7 @@
 pub mod fieldname {
     /// the name of the agency providing the GBFS vehicle.
     /// if this value is set, the trip has boarded the service.
-    pub const GBFS_SERVICE_ID: &str = "gbfs_service_id";
+    pub const GBFS_SERVICE_ID: &str = "gbfs_system_id";
 
     /// true if the trip has a [GBFS_AGENCY_ID] and if the current
     /// edge has a GBFS zone where `ride_end_allowed` is true.
@@ -14,7 +14,7 @@ pub mod variable {
     use routee_compass_core::model::state::{CustomVariableConfig, StateVariableConfig};
 
     /// stores a zone id in a state variable
-    pub fn gbfs_service_id() -> StateVariableConfig {
+    pub fn gbfs_system_id() -> StateVariableConfig {
         StateVariableConfig::Custom {
             custom_type: "Option<GbfsAgencyId>".to_string(),
             value: empty(),
@@ -45,7 +45,7 @@ pub mod state {
     const NO_AGENCY_ID: i64 = -1;
 
     /// assigns the given agency_id to the state vector.
-    pub fn set_service_id(
+    pub fn set_system_id(
         state: &mut [StateVariable],
         state_model: &StateModel,
         agency_id: &str,
@@ -58,7 +58,7 @@ pub mod state {
     }
 
     /// gets the stored agency_id from the state variable, if it exists.
-    pub fn get_service_id<'a, 'b>(
+    pub fn get_system_id<'a, 'b>(
         state: &'a [StateVariable],
         state_model: &'a StateModel,
         mapping: &'b CategoricalStateMapping,
@@ -69,13 +69,13 @@ pub mod state {
     }
 
     /// confirms that there is a stored agency_id and that it matches the provided one.
-    pub fn verify_service_id(
+    pub fn verify_system_id(
         agency_id: &str,
         state: &[StateVariable],
         state_model: &StateModel,
         mapping: &CategoricalStateMapping,
     ) -> Result<bool, StateModelError> {
-        let stored_agency = get_service_id(state, state_model, mapping)?;
+        let stored_agency = get_system_id(state, state_model, mapping)?;
         match stored_agency {
             Some(a) if a == agency_id => Ok(true),
             _ => Ok(false),
@@ -88,6 +88,22 @@ pub mod state {
         state_model: &StateModel,
     ) -> Result<bool, StateModelError> {
         let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_SERVICE_ID)?;
-        Ok(agency_id != -1)
+        Ok(agency_id != NO_AGENCY_ID)
+    }
+
+    /// affirms that the trip location associated with this state vector is a valid trip destination.
+    pub fn set_valid_destination(
+        state: &mut [StateVariable],
+        state_model: &StateModel,
+    ) -> Result<(), StateModelError> {
+        state_model.set_custom_bool(state, fieldname::GBFS_DESTINATION, &true)
+    }
+
+    /// is the trip location associated with this state vector is a valid trip destination?
+    pub fn get_valid_destination(
+        state: &[StateVariable],
+        state_model: &StateModel,
+    ) -> Result<bool, StateModelError> {
+        state_model.get_custom_bool(state, fieldname::GBFS_DESTINATION)
     }
 }
diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index 645bab0d..7cd8e8f2 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -45,7 +45,7 @@ impl GbfsLookupModel {
     /// zones. filters out zonal rules that do not match our trip datetime. if we are boarded on a GBFS
     /// provider we further filter to only zones with a matching ServiceId. combines all
     /// zone record rules in order to produce a single value result.
-    pub fn get_zone_rules<'b>(
+    pub fn matching_zones<'b>(
         &self,
         vertex: &'b Vertex,
         state: &'b [StateVariable],
diff --git a/rust/bambam-gbfs/src/model/gbfs/state.rs b/rust/bambam-gbfs/src/model/gbfs/state.rs
index 83c62ad1..bd706926 100644
--- a/rust/bambam-gbfs/src/model/gbfs/state.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/state.rs
@@ -60,6 +60,8 @@ impl ZoneState {
     /// note: GbfsZoneRecords have already been "flattened" into concrete
     /// boolean values by injecting the implicit default value "true" where
     /// a field is omitted from the source rule.
+    ///
+    /// returns at most one zone per system_id.
     pub fn collect_zones(intersection: Vec<&GbfsZoneRecord>) -> Vec<ZoneState> {
         let mut result: HashMap<&String, Self> = HashMap::new();
 
@@ -77,4 +79,13 @@ impl ZoneState {
 
         result.into_values().collect()
     }
+
+    /// used by sorting combinators so that the first value has the highest speed permissiveness
+    /// and the lexicagraphically-first system id.
+    pub fn ascending_sort_key(&self) -> (i32, String) {
+        (
+            -self.maximum_speed_kph.unwrap_or(i32::MAX),
+            self.system_id.clone(),
+        )
+    }
 }
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
index 42d903e4..3538202a 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
@@ -1,3 +1,4 @@
+use routee_compass_core::model::unit::SpeedUnit;
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Clone, Debug)]
@@ -13,4 +14,12 @@ pub struct GbfsTraversalConfig {
     pub geometries_input_file: String,
     /// fully-qualified identifiers for each record with matching index to zone + geometry files.
     pub zone_ids_input_file: String,
+    /// speed to use for GBFS trips. can be limited by zone-specific max speeds.
+    pub default_speed: DefaultSpeed,
+}
+
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct DefaultSpeed {
+    pub speed: f64,
+    pub speed_unit: SpeedUnit,
 }
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 7a02fc97..7da9f969 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -1,11 +1,15 @@
 use std::path::Path;
 
-use crate::model::gbfs::GbfsLookupModel;
+use crate::model::{
+    feature,
+    gbfs::{GbfsLookupModel, ZoneState},
+};
 
 use super::GbfsTraversalConfig;
 
 use bambam_core::model::state::CategoricalStateMapping;
 use chrono::{DateTime, Utc};
+use itertools::Itertools;
 use routee_compass_core::model::{
     constraint::ConstraintModelError,
     network::Vertex,
@@ -16,33 +20,44 @@ use routee_compass_core::model::{
 pub struct GbfsTraversalEngine {
     lookup: GbfsLookupModel,
     mapping: CategoricalStateMapping,
+    default_speed: uom::si::f64::Velocity,
 }
 
 impl GbfsTraversalEngine {
     pub fn traverse(
         &self,
-        _vertex: &Vertex,
-        _state: &[StateVariable],
-        _state_model: &StateModel,
-        _start_time: DateTime<Utc>,
+        vertex: &Vertex,
+        state: &mut [StateVariable],
+        state_model: &StateModel,
+        start_time: DateTime<Utc>,
     ) -> Result<(), TraversalModelError> {
-        todo!("1) what is the sequence of ops here? doc them; 2) write logic")
-        // let service_opt = feature::state::get_service_id(state, state_model, &self.mapping)
-        //     .map_err(|e| format!("failure inspecting service id of search state: {e}"))?;
-        // let zones =
-        //     self.lookup
-        //         .get_zone_rules(vertex, state, state_model, start_time, service_opt)?;
-
-        // let not_in_a_zone = zones.len() == 0;
-        // let through_allowed = zones.iter().any(|z| z.ride_through_allowed);
-        // let no_depart_allowed =
-        //     service_opt.is_none() && !zones.iter().any(|z| z.ride_start_allowed);
-
-        // if not_in_a_zone || no_depart_allowed {
-        //     Ok(false)
-        // } else {
-        //     Ok(through_allowed)
-        // }
+        // are we currently boarded with a system_id?
+        let service_opt = feature::state::get_system_id(state, state_model, &self.mapping)
+            .map_err(|e| {
+                let msg = format!("failure inspecting gbfs service id of search state: {e}");
+                TraversalModelError::TraversalModelFailure(msg)
+            })?;
+
+        // find intersecting zones. if we are already boarded, only accept zones with our existing system_id.
+        let zones = self
+            .lookup
+            .matching_zones(vertex, state, state_model, start_time, service_opt)
+            .map_err(|e| {
+                let vertex_id = vertex.vertex_id;
+                let service_msg = match service_opt {
+                    Some(id) => format!("for trip boarded on service '{id}'"),
+                    None => "for unboarded trip".to_string(),
+                };
+                let msg = format!(
+                    "failure getting gbfs zone rules for vertex {vertex_id} {service_msg}: {e}"
+                );
+                TraversalModelError::TraversalModelFailure(msg)
+            })?;
+
+        match service_opt {
+            Some(_) => process_boarded(&zones, self.default_speed, state, state_model),
+            None => process_unboarded(zones, self.default_speed, state, state_model, &self.mapping),
+        }
     }
 }
 
@@ -55,6 +70,7 @@ impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
                 let msg = format!("failure building GBFS lookup model: {e}");
                 ConstraintModelError::BuildError(msg)
             })?;
+
         let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
             &config.zone_ids_input_file,
         ))
@@ -64,6 +80,90 @@ impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
                 config.zone_ids_input_file
             ))
         })?;
-        Ok(Self { lookup, mapping })
+
+        let default_speed = config
+            .default_speed
+            .speed_unit
+            .to_uom(config.default_speed.speed);
+        Ok(Self {
+            lookup,
+            mapping,
+            default_speed,
+        })
+    }
+}
+
+/// traversal is associated with a trip that has already boarded GBFS. here we must
+//   1. determine if this location is a valid destination, and set if true (ride_end_allowed)
+//   2. write edge_speed (either from config value or overriding value from record)
+//   3. (todo) if station_parking -> confirm we are at a station location
+fn process_boarded(
+    zones: &[ZoneState],
+    default_speed: uom::si::f64::Velocity,
+    state: &mut [StateVariable],
+    state_model: &StateModel,
+) -> Result<(), TraversalModelError> {
+    use uom::si::{f64::Velocity, velocity::kilometer_per_hour};
+    let zone = match zones {
+        [zone] => zone,
+        _ => {
+            let n_zones = zones.len();
+            let msg = format!(
+                "expected a boarded GBFS trip would match exactly one zone state, found {n_zones}."
+            );
+            return Err(TraversalModelError::TraversalModelFailure(msg));
+        }
+    };
+
+    // 1. is this a valid destination?
+    if zone.ride_end_allowed {
+        feature::state::set_valid_destination(state, state_model)?;
+    }
+    // 2. set the speed, limiting if max speed is present
+    let speed_value: Velocity = match zone.maximum_speed_kph {
+        Some(max) => {
+            let max_vel = Velocity::new::<kilometer_per_hour>(max.into());
+            max_vel.min(default_speed)
+        }
+        None => default_speed,
+    };
+    state_model.set_speed(state, "edge_speed", &speed_value)?;
+
+    Ok(())
+}
+
+/// traversal is associated with a trip that has not yet boarded GBFS. here we must
+///   1. pick the best-quality system from the intersecting zones
+///     - ride_start_allowed is true
+///     - best speed
+///     - sort ids lexicagraphically
+///   2. board with that system_id
+///   3. process boarded
+fn process_unboarded(
+    zones: Vec<ZoneState>,
+    default_speed: uom::si::f64::Velocity,
+    state: &mut [StateVariable],
+    state_model: &StateModel,
+    mapping: &CategoricalStateMapping,
+) -> Result<(), TraversalModelError> {
+    let n_zones = zones.len();
+
+    let best_zone = zones
+        .into_iter()
+        .filter(|z| z.ride_start_allowed)
+        .sorted_by_cached_key(|z| z.ascending_sort_key())
+        .next();
+
+    match best_zone {
+        Some(best) => {
+            feature::state::set_system_id(state, state_model, &best.system_id, mapping)?;
+            process_boarded(&[best], default_speed, state, state_model)
+        }
+        None => {
+            let msg = format!(
+                "found {n_zones} zones but none are ride_start_allowed; should have been caught by constraint model!",
+            );
+            Err(TraversalModelError::InternalError(msg))
+        }
     }
 }
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
index a633c314..dc9c87db 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
@@ -34,6 +34,8 @@ impl TraversalModel for GbfsTraversalModel {
     }
 
     fn output_features(&self) -> Vec<(String, StateVariableConfig)> {
+        // 1. valid destination
+        // 2. max_speed + edge_speed
         todo!()
     }
 

From 9b5c75263d0fe7a6ae7250a4cffd631f0f8188b3 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 08:25:39 -0600
Subject: [PATCH 22/43] add doc comment

---
 rust/bambam-gbfs/src/model/gbfs/state.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/model/gbfs/state.rs b/rust/bambam-gbfs/src/model/gbfs/state.rs
index bd706926..65efff71 100644
--- a/rust/bambam-gbfs/src/model/gbfs/state.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/state.rs
@@ -81,7 +81,9 @@ impl ZoneState {
     }
 
     /// used by sorting combinators so that the first value has the highest speed permissiveness
-    /// and the lexicagraphically-first system id.
+    /// and, as a tie-breaker, the lexicagraphically-first system id.
+    ///
+    /// maximum_speed_kph values of None are treated as MAX values.
     pub fn ascending_sort_key(&self) -> (i32, String) {
         (
             -self.maximum_speed_kph.unwrap_or(i32::MAX),

From 1398055a7ea81d2ab90d86fe6916619539ff6be8 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 09:48:49 -0600
Subject: [PATCH 23/43] wire in gbfs model/engine

---
 .../constraint/gbfs_constraint/config.rs      |  4 +-
 .../constraint/gbfs_constraint/engine.rs      | 13 +++---
 rust/bambam-gbfs/src/model/feature.rs         |  8 ++--
 .../model/traversal/gbfs_traversal/config.rs  |  4 +-
 .../model/traversal/gbfs_traversal/engine.rs  | 16 +++++---
 .../model/traversal/gbfs_traversal/model.rs   | 40 ++++++++++++++-----
 .../model/traversal/gbfs_traversal/params.rs  |  6 ++-
 7 files changed, 62 insertions(+), 29 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
index f25b989e..1e134931 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
@@ -7,10 +7,10 @@ pub struct GbfsConstraintConfig {
     /// for default vehicles (trips without a VehicleTripId).
     ///
     /// see [crate::model::gbfs::GbfsZoneRecord]
-    pub zones_input_file: String,
+    pub zone_record_input_file: String,
     /// output of bambam-gbfs CLI import process, contains zonal geometries
     /// with matching indices to the zones input file.
-    pub geometries_input_file: String,
+    pub zone_geometry_input_file: String,
     /// fully-qualified identifiers for each record with matching index to zone + geometry files.
     pub zone_ids_input_file: String,
 }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index a9917071..dadfe6bb 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -61,11 +61,14 @@ impl TryFrom<GbfsConstraintConfig> for GbfsConstraintEngine {
     type Error = ConstraintModelError;
 
     fn try_from(config: GbfsConstraintConfig) -> Result<Self, Self::Error> {
-        let lookup = GbfsLookupModel::new(&config.zones_input_file, &config.geometries_input_file)
-            .map_err(|e| {
-                let msg = format!("failure building GBFS lookup model: {e}");
-                ConstraintModelError::BuildError(msg)
-            })?;
+        let lookup = GbfsLookupModel::new(
+            &config.zone_record_input_file,
+            &config.zone_geometry_input_file,
+        )
+        .map_err(|e| {
+            let msg = format!("failure building GBFS lookup model: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
         let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
             &config.zone_ids_input_file,
         ))
diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index 8c7b2a72..21fef951 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -1,7 +1,7 @@
 pub mod fieldname {
     /// the name of the agency providing the GBFS vehicle.
     /// if this value is set, the trip has boarded the service.
-    pub const GBFS_SERVICE_ID: &str = "gbfs_system_id";
+    pub const GBFS_SYSTEM_ID: &str = "gbfs_system_id";
 
     /// true if the trip has a [GBFS_AGENCY_ID] and if the current
     /// edge has a GBFS zone where `ride_end_allowed` is true.
@@ -54,7 +54,7 @@ pub mod state {
         let value = mapping.get_label(agency_id).ok_or_else(|| {
             StateModelError::RuntimeError(format!("agency_id {agency_id} missing from mapping"))
         })?;
-        state_model.set_custom_i64(state, fieldname::GBFS_SERVICE_ID, value)
+        state_model.set_custom_i64(state, fieldname::GBFS_SYSTEM_ID, value)
     }
 
     /// gets the stored agency_id from the state variable, if it exists.
@@ -63,7 +63,7 @@ pub mod state {
         state_model: &'a StateModel,
         mapping: &'b CategoricalStateMapping,
     ) -> Result<Option<&'b String>, StateModelError> {
-        let agency_label = state_model.get_custom_i64(state, fieldname::GBFS_SERVICE_ID)?;
+        let agency_label = state_model.get_custom_i64(state, fieldname::GBFS_SYSTEM_ID)?;
         let agency_id = mapping.get_categorical(agency_label)?;
         Ok(agency_id)
     }
@@ -87,7 +87,7 @@ pub mod state {
         state: &[StateVariable],
         state_model: &StateModel,
     ) -> Result<bool, StateModelError> {
-        let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_SERVICE_ID)?;
+        let agency_id = state_model.get_custom_i64(state, fieldname::GBFS_SYSTEM_ID)?;
         Ok(agency_id != NO_AGENCY_ID)
     }
 
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
index 3538202a..46c0cd88 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
@@ -8,10 +8,10 @@ pub struct GbfsTraversalConfig {
     /// for default vehicles (trips without a VehicleTripId).
     ///
     /// see [crate::model::gbfs::GbfsZoneRecord]
-    pub zones_input_file: String,
+    pub zone_record_input_file: String,
     /// output of bambam-gbfs CLI import process, contains zonal geometries
     /// with matching indices to the zones input file.
-    pub geometries_input_file: String,
+    pub zone_geometry_input_file: String,
     /// fully-qualified identifiers for each record with matching index to zone + geometry files.
     pub zone_ids_input_file: String,
     /// speed to use for GBFS trips. can be limited by zone-specific max speeds.
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 7da9f969..269d7627 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -20,10 +20,11 @@ use routee_compass_core::model::{
 pub struct GbfsTraversalEngine {
     lookup: GbfsLookupModel,
     mapping: CategoricalStateMapping,
-    default_speed: uom::si::f64::Velocity,
+    pub default_speed: uom::si::f64::Velocity,
 }
 
 impl GbfsTraversalEngine {
+    /// runs the traversal logic for the GBFS traversal model at an iteration of graph search.
     pub fn traverse(
         &self,
         vertex: &Vertex,
@@ -65,11 +66,14 @@ impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
     type Error = ConstraintModelError;
 
     fn try_from(config: GbfsTraversalConfig) -> Result<Self, Self::Error> {
-        let lookup = GbfsLookupModel::new(&config.zones_input_file, &config.geometries_input_file)
-            .map_err(|e| {
-                let msg = format!("failure building GBFS lookup model: {e}");
-                ConstraintModelError::BuildError(msg)
-            })?;
+        let lookup = GbfsLookupModel::new(
+            &config.zone_record_input_file,
+            &config.zone_geometry_input_file,
+        )
+        .map_err(|e| {
+            let msg = format!("failure building GBFS lookup model: {e}");
+            ConstraintModelError::BuildError(msg)
+        })?;
 
         let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
             &config.zone_ids_input_file,
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
index dc9c87db..c50b7a40 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/model.rs
@@ -1,5 +1,7 @@
 use std::sync::Arc;
 
+use crate::model::feature;
+
 use super::{GbfsTraversalEngine, GbfsTraversalParams};
 
 use routee_compass_core::{
@@ -10,6 +12,7 @@ use routee_compass_core::{
         traversal::{EdgeFrontierContext, TraversalModel, TraversalModelError},
     },
 };
+use uom::si::f64::Velocity;
 
 pub struct GbfsTraversalModel {
     pub engine: Arc<GbfsTraversalEngine>,
@@ -30,31 +33,50 @@ impl TraversalModel for GbfsTraversalModel {
     }
 
     fn input_features(&self) -> Vec<InputFeature> {
-        todo!()
+        vec![]
     }
 
     fn output_features(&self) -> Vec<(String, StateVariableConfig)> {
         // 1. valid destination
         // 2. max_speed + edge_speed
-        todo!()
+        vec![
+            (
+                feature::fieldname::GBFS_DESTINATION.to_string(),
+                feature::variable::gbfs_destination(),
+            ),
+            (
+                feature::fieldname::GBFS_SYSTEM_ID.to_string(),
+                feature::variable::gbfs_system_id(),
+            ),
+            (
+                "edge_speed".to_string(),
+                StateVariableConfig::Speed {
+                    initial: Velocity::new::<uom::si::velocity::kilometer_per_hour>(0.0),
+                    accumulator: false,
+                    output_unit: None,
+                },
+            ),
+        ]
     }
 
     fn traverse_edge(
         &self,
-        _ctx: &EdgeFrontierContext,
-        _state: &mut Vec<StateVariable>,
-        _state_model: &StateModel,
+        ctx: &EdgeFrontierContext,
+        state: &mut Vec<StateVariable>,
+        state_model: &StateModel,
     ) -> Result<(), TraversalModelError> {
-        todo!()
+        self.engine
+            .traverse(ctx.dst, state, state_model, self.params.start_time)
     }
 
     fn estimate_traversal(
         &self,
         _od: (&Vertex, &Vertex),
-        _state: &mut Vec<StateVariable>,
+        state: &mut Vec<StateVariable>,
         _tree: &SearchTree,
-        _state_model: &StateModel,
+        state_model: &StateModel,
     ) -> Result<(), TraversalModelError> {
-        todo!()
+        state_model.set_speed(state, "edge_speed", &self.engine.default_speed)?;
+        Ok(())
     }
 }
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
index 5c6fc60c..8c78c9fb 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/params.rs
@@ -1,4 +1,8 @@
+use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};
 
 #[derive(Deserialize, Serialize, Clone, Debug)]
-pub struct GbfsTraversalParams {}
+pub struct GbfsTraversalParams {
+    /// datetime we start this trip.
+    pub start_time: DateTime<Utc>,
+}

From 0b57d5d1a545f58d293836e8bfc6857014d653af Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 10:58:38 -0600
Subject: [PATCH 24/43] rename agency_id to system_id

---
 rust/bambam-gbfs/src/model/feature.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index 21fef951..c17b77c4 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -48,11 +48,11 @@ pub mod state {
     pub fn set_system_id(
         state: &mut [StateVariable],
         state_model: &StateModel,
-        agency_id: &str,
+        system_id: &str,
         mapping: &CategoricalStateMapping,
     ) -> Result<(), StateModelError> {
-        let value = mapping.get_label(agency_id).ok_or_else(|| {
-            StateModelError::RuntimeError(format!("agency_id {agency_id} missing from mapping"))
+        let value = mapping.get_label(system_id).ok_or_else(|| {
+            StateModelError::RuntimeError(format!("system_id {system_id} missing from mapping"))
         })?;
         state_model.set_custom_i64(state, fieldname::GBFS_SYSTEM_ID, value)
     }

From 8b2a1546d859c263ad8512d9f98d3fd308969077 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 10:58:45 -0600
Subject: [PATCH 25/43] clearer error message

---
 .../input_plugin/population/population_source_config.rs      | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/rust/bambam/src/model/input_plugin/population/population_source_config.rs b/rust/bambam/src/model/input_plugin/population/population_source_config.rs
index f22f9640..6a3acda1 100644
--- a/rust/bambam/src/model/input_plugin/population/population_source_config.rs
+++ b/rust/bambam/src/model/input_plugin/population/population_source_config.rs
@@ -20,7 +20,10 @@ pub enum PopulationSourceConfig {
 }
 
 fn env_census_api_token() -> Result<String, String> {
-    std::env::var("CENSUS_API_TOKEN").map_err(|e| format!("ACS token required, {e}"))
+    std::env::var("CENSUS_API_TOKEN").map_err(|_| {
+        "ACS requires token for access. please set via 'CENSUS_API_TOKEN' environment variable"
+            .to_string()
+    })
 }
 
 impl PopulationSourceConfig {

From de1902fadec38e25866e90bc98c11763f6b8d7ec Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 10:58:54 -0600
Subject: [PATCH 26/43] geometry file is not CSV

---
 rust/bambam-gbfs/src/model/gbfs/lookup.rs | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/gbfs/lookup.rs b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
index 7cd8e8f2..b0e5d5df 100644
--- a/rust/bambam-gbfs/src/model/gbfs/lookup.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/lookup.rs
@@ -11,7 +11,10 @@ use routee_compass_core::{
         network::Vertex,
         state::{StateModel, StateVariable},
     },
-    util::{fs::read_utils, geo::PolygonalRTree},
+    util::{
+        fs::{read_decoders, read_utils},
+        geo::PolygonalRTree,
+    },
 };
 
 pub struct GbfsLookupModel {
@@ -113,9 +116,9 @@ fn read_records(zone_record_input_file: &str) -> Result<Vec<GbfsZoneRecord>, Str
 /// reads zonal geometries and ZoneIds from a CSV geometry collection.
 fn read_geometries(geometry_input_file: &str) -> Result<Vec<Geometry<f32>>, String> {
     let bb = BarBuilder::default().desc("reading zone geometries");
-    let record_strings: Box<[String]> =
-        read_utils::from_csv(&geometry_input_file, true, Some(bb), None)
-            .map_err(|e| format!("failure reading zone geometries: {e}"))?;
+    let record_strings =
+        read_utils::read_raw_file(geometry_input_file, read_decoders::string, Some(bb), None)
+            .map_err(|e| format!("failure reading file '{geometry_input_file}': {e}"))?;
     let rtree_data = record_strings
         .iter()
         .enumerate()

From 852704241409370804b2788325532e75992519e2 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:05:54 -0600
Subject: [PATCH 27/43] test/traverse edges using current time, not start time

---
 .../constraint/gbfs_constraint/engine.rs      | 11 ++++--
 rust/bambam-gbfs/src/model/gbfs/ops.rs        | 34 +++++++++++++++++++
 .../model/traversal/gbfs_traversal/engine.rs  | 14 +++++---
 3 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index dadfe6bb..4b2683f7 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -1,6 +1,9 @@
 use std::path::Path;
 
-use crate::model::{feature, gbfs::GbfsLookupModel};
+use crate::model::{
+    feature,
+    gbfs::{GbfsLookupModel, ops},
+};
 
 use super::GbfsConstraintConfig;
 
@@ -36,9 +39,13 @@ impl GbfsConstraintEngine {
                 let msg = format!("failure inspecting service id of search state: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
             })?;
+        let current_time = ops::current_datetime(start_time, state, state_model).map_err(|e| {
+            let msg: String = format!("failure running GBFS constraint model: {e}");
+            ConstraintModelError::ConstraintModelError(msg)
+        })?;
         let zones = self
             .lookup
-            .matching_zones(vertex, state, state_model, start_time, service_opt)
+            .matching_zones(vertex, state, state_model, current_time, service_opt)
             .map_err(|e| {
                 let msg = format!("failure running GBFS rule lookup: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
diff --git a/rust/bambam-gbfs/src/model/gbfs/ops.rs b/rust/bambam-gbfs/src/model/gbfs/ops.rs
index e51bfd92..a29bc081 100644
--- a/rust/bambam-gbfs/src/model/gbfs/ops.rs
+++ b/rust/bambam-gbfs/src/model/gbfs/ops.rs
@@ -1,3 +1,10 @@
+use chrono::{DateTime, TimeDelta, Utc};
+use routee_compass_core::model::{
+    state::{StateModel, StateVariable},
+    traversal::default::fieldname,
+};
+use uom::si::f64::Time;
+
 /// builds a globally-unique identifier for a zone. based on the fact that
 /// system_ids are defined as globally unique. as documented at
 /// <https://github.com/MobilityData/gbfs/blob/master/gbfs.md#system_informationjson>:
@@ -13,3 +20,30 @@
 pub fn fully_qualified_zone_id(system_id: &str, zone_feature_index: usize) -> String {
     format!("{system_id}#{zone_feature_index}")
 }
+
+/// helper function to calculate the current datetime based on the start time and trip_time values.
+pub fn current_datetime(
+    start_time: DateTime<Utc>,
+    state: &[StateVariable],
+    state_model: &StateModel,
+) -> Result<DateTime<Utc>, String> {
+    let time: Time = state_model
+        .get_time(state, fieldname::TRIP_TIME)
+        .map_err(|e| {
+            format!(
+                "failure getting '{}' from state vector: {e}",
+                fieldname::TRIP_TIME
+            )
+        })?;
+    let time_i64 = time.get::<uom::si::time::second>() as i64;
+    start_time
+        .checked_add_signed(TimeDelta::seconds(time_i64))
+        .ok_or_else(|| {
+            let msg = format!(
+                "adding {} seconds to {} was out of bounds",
+                time_i64,
+                start_time.to_rfc3339()
+            );
+            msg
+        })
+}
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 269d7627..bcb4b09f 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -2,20 +2,21 @@ use std::path::Path;
 
 use crate::model::{
     feature,
-    gbfs::{GbfsLookupModel, ZoneState},
+    gbfs::{GbfsLookupModel, ZoneState, ops},
 };
 
 use super::GbfsTraversalConfig;
 
 use bambam_core::model::state::CategoricalStateMapping;
-use chrono::{DateTime, Utc};
+use chrono::{DateTime, TimeDelta, Utc};
 use itertools::Itertools;
 use routee_compass_core::model::{
     constraint::ConstraintModelError,
     network::Vertex,
     state::{StateModel, StateVariable},
-    traversal::TraversalModelError,
+    traversal::{TraversalModelError, default::fieldname},
 };
+use uom::si::f64::Time;
 
 pub struct GbfsTraversalEngine {
     lookup: GbfsLookupModel,
@@ -39,10 +40,15 @@ impl GbfsTraversalEngine {
                 TraversalModelError::TraversalModelFailure(msg)
             })?;
 
+        let current_time = ops::current_datetime(start_time, state, state_model).map_err(|e| {
+            let msg = format!("during GBFS traversal, {e}");
+            TraversalModelError::TraversalModelFailure(msg)
+        })?;
+
         // find intersecting zones. if we are already boarded, only accept zones with our existing system_id.
         let zones = self
             .lookup
-            .matching_zones(vertex, state, state_model, start_time, service_opt)
+            .matching_zones(vertex, state, state_model, current_time, service_opt)
             .map_err(|e| {
                 let vertex_id = vertex.vertex_id;
                 let service_msg = match service_opt {

From d25fd7e9d26388b533a823e78d305792faa42108 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:06:03 -0600
Subject: [PATCH 28/43] clippy

---
 .../bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index bcb4b09f..6bc28b61 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -8,15 +8,14 @@ use crate::model::{
 use super::GbfsTraversalConfig;
 
 use bambam_core::model::state::CategoricalStateMapping;
-use chrono::{DateTime, TimeDelta, Utc};
+use chrono::{DateTime, Utc};
 use itertools::Itertools;
 use routee_compass_core::model::{
     constraint::ConstraintModelError,
     network::Vertex,
     state::{StateModel, StateVariable},
-    traversal::{TraversalModelError, default::fieldname},
+    traversal::TraversalModelError,
 };
-use uom::si::f64::Time;
 
 pub struct GbfsTraversalEngine {
     lookup: GbfsLookupModel,

From 2c20de6a9b11b73b4991f9ba82b6b82320aaeb4a Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:22:32 -0600
Subject: [PATCH 29/43] record system ids, not fully-qualified ids

---
 rust/bambam-gbfs/src/app/download/run.rs | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index aaeef68c..dd2a4df0 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -1,4 +1,5 @@
 use std::{
+    collections::HashSet,
     fs::File,
     path::Path,
     sync::{Arc, Mutex},
@@ -8,6 +9,7 @@ use chrono::TimeDelta;
 use csv::QuoteStyle;
 use flate2::{Compression, write::GzEncoder};
 use geozero::ToWkt;
+use itertools::Itertools;
 use kdam::{Bar, BarBuilder, BarExt};
 use tokio::{
     sync::Semaphore,
@@ -20,7 +22,7 @@ use crate::app::download::{
 
 const GEOMETRIES_FILENAME: &str = "edges-gbfs-geofences-enumerated.txt.gz";
 const RECORDS_FILENAME: &str = "edges-gbfs-records.csv.gz";
-const IDS_FILENAME: &str = "edges-zone-ids.txt.gz";
+const SYSTEM_IDS_FILENAME: &str = "edges-system-ids.txt.gz";
 
 pub async fn gbfs_download_import(
     url: &str,
@@ -37,14 +39,14 @@ pub async fn gbfs_download_import(
     // process into BAMBAM-GBFS edge list format
     let mut geometries = vec![];
     let mut zone_records = vec![];
-    let mut ids = vec![];
+    let mut ids = HashSet::new();
     for i in 0..gbfs.n_features() {
         let geometry = gbfs.get_feature_geometry(i)?;
         let record = gbfs.get_feature_zone_record(i)?;
-        let id = record.fq_id.clone();
+        let system_id = record.system_id.clone();
         geometries.push(geometry);
         zone_records.push(record);
-        ids.push(id);
+        ids.insert(system_id);
     }
 
     // write outputs
@@ -64,7 +66,13 @@ pub async fn gbfs_download_import(
         QuoteStyle::Necessary,
         overwrite,
     )?;
-    let mut id_writer = create_writer(out_dir, IDS_FILENAME, false, QuoteStyle::Never, overwrite)?;
+    let mut id_writer = create_writer(
+        out_dir,
+        SYSTEM_IDS_FILENAME,
+        false,
+        QuoteStyle::Never,
+        overwrite,
+    )?;
 
     for (idx, geom) in geometries.into_iter().enumerate() {
         let wkt_string = geom
@@ -82,7 +90,7 @@ pub async fn gbfs_download_import(
             .map_err(|e| format!("failure writing record {idx} to file: {e}"))?
     }
 
-    for (idx, id) in ids.into_iter().enumerate() {
+    for (idx, id) in ids.into_iter().sorted().enumerate() {
         id_writer
             .serialize(&id)
             .map_err(|e| format!("failure writing {idx}th id {id} to file: {e}"))?

From 377c8ef564aa30bfd38a8cc21aa37c1451c24bc3 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:28:36 -0600
Subject: [PATCH 30/43] rename to system_ids_input_file

---
 .../src/model/constraint/gbfs_constraint/config.rs            | 4 ++--
 .../src/model/constraint/gbfs_constraint/engine.rs            | 4 ++--
 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs | 4 ++--
 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
index 1e134931..e6c2596a 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/config.rs
@@ -11,6 +11,6 @@ pub struct GbfsConstraintConfig {
     /// output of bambam-gbfs CLI import process, contains zonal geometries
     /// with matching indices to the zones input file.
     pub zone_geometry_input_file: String,
-    /// fully-qualified identifiers for each record with matching index to zone + geometry files.
-    pub zone_ids_input_file: String,
+    /// system identifiers for all records. these are sorted lexicagraphically.
+    pub system_ids_input_file: String,
 }
diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index 4b2683f7..68f945a8 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -77,12 +77,12 @@ impl TryFrom<GbfsConstraintConfig> for GbfsConstraintEngine {
             ConstraintModelError::BuildError(msg)
         })?;
         let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
-            &config.zone_ids_input_file,
+            &config.system_ids_input_file,
         ))
         .map_err(|e| {
             ConstraintModelError::BuildError(format!(
                 "failure while building categorical mapping from {}: {e}",
-                config.zone_ids_input_file
+                config.system_ids_input_file
             ))
         })?;
         Ok(Self { lookup, mapping })
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
index 46c0cd88..856de3be 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/config.rs
@@ -12,8 +12,8 @@ pub struct GbfsTraversalConfig {
     /// output of bambam-gbfs CLI import process, contains zonal geometries
     /// with matching indices to the zones input file.
     pub zone_geometry_input_file: String,
-    /// fully-qualified identifiers for each record with matching index to zone + geometry files.
-    pub zone_ids_input_file: String,
+    /// system identifiers for all records. these are sorted lexicagraphically.
+    pub system_ids_input_file: String,
     /// speed to use for GBFS trips. can be limited by zone-specific max speeds.
     pub default_speed: DefaultSpeed,
 }
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 6bc28b61..cf131584 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -81,12 +81,12 @@ impl TryFrom<GbfsTraversalConfig> for GbfsTraversalEngine {
         })?;
 
         let mapping = CategoricalStateMapping::from_enumerated_category_file(Path::new(
-            &config.zone_ids_input_file,
+            &config.system_ids_input_file,
         ))
         .map_err(|e| {
             ConstraintModelError::BuildError(format!(
                 "failure while building categorical mapping from {}: {e}",
-                config.zone_ids_input_file
+                config.system_ids_input_file
             ))
         })?;
 

From 336f9955c46a602cb4f36a776a3fd87cf199d4a4 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:51:20 -0600
Subject: [PATCH 31/43] remove duplicate time delta injection

---
 .../src/model/constraint/gbfs_constraint/engine.rs    | 11 ++---------
 .../src/model/traversal/gbfs_traversal/engine.rs      |  9 ++-------
 2 files changed, 4 insertions(+), 16 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index 68f945a8..4ff62a02 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -1,9 +1,6 @@
 use std::path::Path;
 
-use crate::model::{
-    feature,
-    gbfs::{GbfsLookupModel, ops},
-};
+use crate::model::{feature, gbfs::GbfsLookupModel};
 
 use super::GbfsConstraintConfig;
 
@@ -39,13 +36,9 @@ impl GbfsConstraintEngine {
                 let msg = format!("failure inspecting service id of search state: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
             })?;
-        let current_time = ops::current_datetime(start_time, state, state_model).map_err(|e| {
-            let msg: String = format!("failure running GBFS constraint model: {e}");
-            ConstraintModelError::ConstraintModelError(msg)
-        })?;
         let zones = self
             .lookup
-            .matching_zones(vertex, state, state_model, current_time, service_opt)
+            .matching_zones(vertex, state, state_model, start_time, service_opt)
             .map_err(|e| {
                 let msg = format!("failure running GBFS rule lookup: {e}");
                 ConstraintModelError::ConstraintModelError(msg)
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index cf131584..440160ef 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -2,7 +2,7 @@ use std::path::Path;
 
 use crate::model::{
     feature,
-    gbfs::{GbfsLookupModel, ZoneState, ops},
+    gbfs::{GbfsLookupModel, ZoneState},
 };
 
 use super::GbfsTraversalConfig;
@@ -39,15 +39,10 @@ impl GbfsTraversalEngine {
                 TraversalModelError::TraversalModelFailure(msg)
             })?;
 
-        let current_time = ops::current_datetime(start_time, state, state_model).map_err(|e| {
-            let msg = format!("during GBFS traversal, {e}");
-            TraversalModelError::TraversalModelFailure(msg)
-        })?;
-
         // find intersecting zones. if we are already boarded, only accept zones with our existing system_id.
         let zones = self
             .lookup
-            .matching_zones(vertex, state, state_model, current_time, service_opt)
+            .matching_zones(vertex, state, state_model, start_time, service_opt)
             .map_err(|e| {
                 let vertex_id = vertex.vertex_id;
                 let service_msg = match service_opt {

From 5c7cf1f8b40129a6ea518146e0121747046fe7da Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:54:36 -0600
Subject: [PATCH 32/43] ensure a zone exists where both predicates are true

---
 .../src/model/constraint/gbfs_constraint/engine.rs  | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
index 4ff62a02..560d25c4 100644
--- a/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
+++ b/rust/bambam-gbfs/src/model/constraint/gbfs_constraint/engine.rs
@@ -44,16 +44,11 @@ impl GbfsConstraintEngine {
                 ConstraintModelError::ConstraintModelError(msg)
             })?;
 
-        let not_in_a_zone = zones.is_empty();
-        let through_allowed = zones.iter().any(|z| z.ride_through_allowed);
-        let no_depart_allowed =
-            service_opt.is_none() && !zones.iter().any(|z| z.ride_start_allowed);
+        let valid = zones
+            .iter()
+            .any(|z| z.ride_through_allowed && (service_opt.is_some() || z.ride_start_allowed));
 
-        if not_in_a_zone || no_depart_allowed {
-            Ok(false)
-        } else {
-            Ok(through_allowed)
-        }
+        Ok(valid)
     }
 }
 

From e40ca437566fe3b4d913c03899dc5d5a83cbd0ff Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robfitzgerald@gmail.com>
Date: Thu, 13 Aug 2026 12:56:10 -0600
Subject: [PATCH 33/43] assert ride start AND through are supported for
 departure

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 440160ef..8e391c1e 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -154,7 +154,7 @@ fn process_unboarded(
 
     let best_zone = zones
         .into_iter()
-        .filter(|z| z.ride_start_allowed)
+        .filter(|z| z.ride_start_allowed && z.ride_through_allowed)
         .sorted_by_cached_key(|z| z.ascending_sort_key())
         .next();
 

From 6cf23ccc8f948009d4bd4a2d19019c4b15f33f6f Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 12:59:10 -0600
Subject: [PATCH 34/43] fix name

---
 rust/bambam-gbfs/src/model/feature.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index c17b77c4..ee9cb2b4 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -16,7 +16,7 @@ pub mod variable {
     /// stores a zone id in a state variable
     pub fn gbfs_system_id() -> StateVariableConfig {
         StateVariableConfig::Custom {
-            custom_type: "Option<GbfsAgencyId>".to_string(),
+            custom_type: "Option<GbfsSystemId>".to_string(),
             value: empty(),
             accumulator: true,
         }

From bb26af6aed6a23d1be3e7b929d50c6ff3da590ec Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robfitzgerald@gmail.com>
Date: Thu, 13 Aug 2026 13:00:07 -0600
Subject: [PATCH 35/43] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs b/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
index 662dd8ca..6f28d0dc 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_v2_2.rs
@@ -119,12 +119,12 @@ pub mod types {
     }
 
     #[derive(Serialize, Deserialize, Debug, Clone)]
-    #[serde(tag = "type")]
+    #[serde(tag = "type", content = "coordinates")]
     pub enum GeofenceGeometry {
         #[serde(rename = "MultiPolygon")]
         MultiPolygon(Vec<Vec<Vec<Vec<f64>>>>),
         #[serde(rename = "Polygon")]
-        Polygon(Vec<Vec<Vec<Vec<f64>>>>),
+        Polygon(Vec<Vec<Vec<f64>>>),
     }
 
     #[derive(Serialize, Deserialize, Debug, Clone)]

From 0667c363b61097bd1bed7769eb90c122f32f1423 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robfitzgerald@gmail.com>
Date: Thu, 13 Aug 2026 13:00:51 -0600
Subject: [PATCH 36/43] prevent CLI parallelism argument of 0

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 rust/bambam-gbfs/src/app/download/run.rs | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index dd2a4df0..8e058eda 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -149,6 +149,9 @@ pub async fn gbfs_batch_metadata_download(
     delay_ms: Option<u64>,
 ) -> Result<(), String> {
     let par = parallelism.unwrap_or(1);
+    if par == 0 {
+        return Err("parallelism must be greater than zero".to_string());
+    }
     let del = delay_ms.unwrap_or_default();
 
     let bar: Arc<Mutex<Bar>> = Arc::new(Mutex::new(

From 1d37ba13515e267129f2b3c3cd734622ccefdce4 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robfitzgerald@gmail.com>
Date: Thu, 13 Aug 2026 13:01:24 -0600
Subject: [PATCH 37/43] typo of GBFS versions

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs b/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
index acc85dda..9f157cf6 100644
--- a/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
+++ b/rust/bambam-gbfs/src/app/download/gbfs_v2_3.rs
@@ -21,14 +21,14 @@ pub async fn run_v2_3_manifest(
     let mut results = vec![];
     for system in manifest.data.datasets.iter() {
         let system_id = system.system_id.clone();
-        let v_search = system.versions.iter().find(|v| v.version == "3.0");
+        let v_search = system.versions.iter().find(|v| v.version == "2.3");
         match v_search {
-            Some(v3) => {
-                let gbfs_url = v3.url.value.clone();
+            Some(v2_3) => {
+                let gbfs_url = v2_3.url.value.clone();
                 let result = run_v2_3_gbfs(client, &gbfs_url).await?;
                 results.push(result);
             }
-            None => return Err(format!("in system {system_id} no v3.0 was found.")),
+            None => return Err(format!("in system {system_id} no v2.3 was found.")),
         }
     }
 

From 10ffaeb3b5e8162d8e48fbb99e3710642dd300cf Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 13:49:54 -0600
Subject: [PATCH 38/43] rename CLI, feed batch into compass output writer

---
 rust/bambam-gbfs/src/app/download/run.rs | 215 +++++++++++------------
 rust/bambam-gbfs/src/app/gbfs_cli.rs     |  83 ++++-----
 2 files changed, 135 insertions(+), 163 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 8e058eda..a2ca785a 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -24,7 +24,7 @@ const GEOMETRIES_FILENAME: &str = "edges-gbfs-geofences-enumerated.txt.gz";
 const RECORDS_FILENAME: &str = "edges-gbfs-records.csv.gz";
 const SYSTEM_IDS_FILENAME: &str = "edges-system-ids.txt.gz";
 
-pub async fn gbfs_download_import(
+pub async fn download_one(
     url: &str,
     out_dir: &Path,
     version: GbfsVersion,
@@ -35,125 +35,26 @@ pub async fn gbfs_download_import(
     // download GBFS dataset
     let client = reqwest::Client::new();
     let gbfs = GbfsRecord::download_from_gbfs_endpoint(&client, url, version).await?;
-
-    // process into BAMBAM-GBFS edge list format
-    let mut geometries = vec![];
-    let mut zone_records = vec![];
-    let mut ids = HashSet::new();
-    for i in 0..gbfs.n_features() {
-        let geometry = gbfs.get_feature_geometry(i)?;
-        let record = gbfs.get_feature_zone_record(i)?;
-        let system_id = record.system_id.clone();
-        geometries.push(geometry);
-        zone_records.push(record);
-        ids.insert(system_id);
-    }
-
-    // write outputs
-    std::fs::create_dir_all(out_dir)
-        .map_err(|e| format!("failure creating output directory location: {e}"))?;
-    let mut geom_writer = create_writer(
-        out_dir,
-        GEOMETRIES_FILENAME,
-        false,
-        QuoteStyle::Never,
-        overwrite,
-    )?;
-    let mut record_writer = create_writer(
-        out_dir,
-        RECORDS_FILENAME,
-        true,
-        QuoteStyle::Necessary,
-        overwrite,
-    )?;
-    let mut id_writer = create_writer(
-        out_dir,
-        SYSTEM_IDS_FILENAME,
-        false,
-        QuoteStyle::Never,
-        overwrite,
-    )?;
-
-    for (idx, geom) in geometries.into_iter().enumerate() {
-        let wkt_string = geom
-            .to_wkt()
-            .map_err(|e| format!("failure converting geometry {idx} into WKT: {e}"))?;
-
-        geom_writer
-            .serialize(&wkt_string)
-            .map_err(|e| format!("failure writing geometry {idx} to file: {e}"))?
-    }
-
-    for (idx, record) in zone_records.into_iter().enumerate() {
-        record_writer
-            .serialize(&record)
-            .map_err(|e| format!("failure writing record {idx} to file: {e}"))?
-    }
-
-    for (idx, id) in ids.into_iter().sorted().enumerate() {
-        id_writer
-            .serialize(&id)
-            .map_err(|e| format!("failure writing {idx}th id {id} to file: {e}"))?
-    }
-
-    Ok(())
-}
-
-/// downloads GBFS data for some duration. aggregates the resulting rows and writes them
-/// to files to be consumed by BAMBAM.
-///
-/// # Arguments
-/// * url - URL to the GBFS dataset's system-information file
-/// * out_dir - output directory to write the processed GBFS data
-/// * dur - how long to poll the GBFS API
-///
-/// # Result
-/// If successful, returns nothing, otherwise an error
-pub async fn gbfs_download_old(
-    url: &str,
-    out_dir: &Path,
-    dur: &TimeDelta,
-    entry_point: EntryPoint,
-    version: GbfsVersion,
-) -> Result<(), String> {
-    let dur_secs = dur.as_seconds_f64();
-    log::debug!(
-        "run_gbfs_download with url={url}, out_dir={out_dir:?}, duration (seconds)={dur_secs}"
-    );
-    let client = reqwest::Client::new();
-
-    let result = match (version, entry_point) {
-        (GbfsVersion::V3_0, EntryPoint::Manifest) => {
-            gbfs_v3_0::run_v3_0_manifest(&client, url).await?
-        }
-        (GbfsVersion::V3_0, EntryPoint::Gbfs) => gbfs_v3_0::run_v3_0_gbfs(&client, url)
-            .await
-            .map(|g| vec![g])?,
-        _ => return Err("version not supported".to_string()),
-    };
-
-    for row in result.into_iter() {
-        println!("{}", serde_json::to_string_pretty(&row).unwrap_or_default());
-    }
-
-    Ok(())
+    write_edge_list(&[gbfs], out_dir, overwrite).await
 }
 
 /// designed to download from a GBFS system list file such as
 /// <https://github.com/MobilityData/gbfs/blob/master/systems.csv>.
-pub async fn gbfs_batch_metadata_download(
+pub async fn batch_download(
     urls: &[String],
     entry_point: EntryPoint,
     out_dir: &Path,
     parallelism: Option<usize>,
     delay_ms: Option<u64>,
+    no_compass: bool,
+    no_summary: bool,
+    overwrite: bool,
 ) -> Result<(), String> {
     let par = parallelism.unwrap_or(1);
     if par == 0 {
         return Err("parallelism must be greater than zero".to_string());
     }
     let del = delay_ms.unwrap_or_default();
-
     let bar: Arc<Mutex<Bar>> = Arc::new(Mutex::new(
         BarBuilder::default()
             .total(urls.len())
@@ -202,11 +103,38 @@ pub async fn gbfs_batch_metadata_download(
         }
     }
 
-    for result in results.into_iter() {
+    if !no_summary {
+        write_summaries(&results, out_dir)?;
+    }
+
+    if !no_compass {
+        write_edge_list(&results, out_dir, overwrite).await?;
+    }
+
+    if !errors.is_empty() {
+        for err in errors.iter() {
+            log::error!("{err}")
+        }
+        log::error!("{} calls failed", errors.len());
+    }
+
+    Ok(())
+}
+
+/// writes GbfsArchives as JSON files in a summary/ directory.
+pub fn write_summaries(results: &[GbfsRecord], out_dir: &Path) -> Result<(), String> {
+    let sum_dir = out_dir.join("summary");
+    std::fs::create_dir_all(&sum_dir).map_err(|e| {
+        format!(
+            "failure writing summary directory path '{}': {e}",
+            sum_dir.to_string_lossy()
+        )
+    })?;
+    for result in results.iter() {
         let no_features = result.no_geofence();
         if !no_features {
             let filename = result.system_id();
-            let filepath = out_dir.join(&filename);
+            let filepath = sum_dir.join(&filename);
 
             std::fs::write(
                 filepath,
@@ -215,12 +143,77 @@ pub async fn gbfs_batch_metadata_download(
             .map_err(|e| format!("failure while writing to '{filename}': {e}"))?;
         }
     }
+    Ok(())
+}
 
-    if !errors.is_empty() {
-        for err in errors.iter() {
-            log::error!("{err}")
+/// writes an edge list to an output directory that covers the provided GBFS archives.
+/// fails if overwrite = false and output files are found.
+pub async fn write_edge_list(
+    archives: &[GbfsRecord],
+    out_dir: &Path,
+    overwrite: bool,
+) -> Result<(), String> {
+    // process into BAMBAM-GBFS edge list format
+    let mut geometries = vec![];
+    let mut zone_records = vec![];
+    let mut ids = HashSet::new();
+
+    for gbfs in archives.iter() {
+        for i in 0..gbfs.n_features() {
+            let geometry = gbfs.get_feature_geometry(i)?;
+            let record = gbfs.get_feature_zone_record(i)?;
+            let system_id = record.system_id.clone();
+            geometries.push(geometry);
+            zone_records.push(record);
+            ids.insert(system_id);
         }
-        log::error!("{} calls failed", errors.len());
+    }
+
+    // write outputs
+    std::fs::create_dir_all(out_dir)
+        .map_err(|e| format!("failure creating output directory location: {e}"))?;
+    let mut geom_writer = create_writer(
+        out_dir,
+        GEOMETRIES_FILENAME,
+        false,
+        QuoteStyle::Never,
+        overwrite,
+    )?;
+    let mut record_writer = create_writer(
+        out_dir,
+        RECORDS_FILENAME,
+        true,
+        QuoteStyle::Necessary,
+        overwrite,
+    )?;
+    let mut id_writer = create_writer(
+        out_dir,
+        SYSTEM_IDS_FILENAME,
+        false,
+        QuoteStyle::Never,
+        overwrite,
+    )?;
+
+    for (idx, geom) in geometries.into_iter().enumerate() {
+        let wkt_string = geom
+            .to_wkt()
+            .map_err(|e| format!("failure converting geometry {idx} into WKT: {e}"))?;
+
+        geom_writer
+            .serialize(&wkt_string)
+            .map_err(|e| format!("failure writing geometry {idx} to file: {e}"))?
+    }
+
+    for (idx, record) in zone_records.into_iter().enumerate() {
+        record_writer
+            .serialize(&record)
+            .map_err(|e| format!("failure writing record {idx} to file: {e}"))?
+    }
+
+    for (idx, id) in ids.into_iter().sorted().enumerate() {
+        id_writer
+            .serialize(&id)
+            .map_err(|e| format!("failure writing {idx}th id {id} to file: {e}"))?
     }
 
     Ok(())
diff --git a/rust/bambam-gbfs/src/app/gbfs_cli.rs b/rust/bambam-gbfs/src/app/gbfs_cli.rs
index a1eac193..78b8c6cc 100644
--- a/rust/bambam-gbfs/src/app/gbfs_cli.rs
+++ b/rust/bambam-gbfs/src/app/gbfs_cli.rs
@@ -1,6 +1,5 @@
-use std::{path::Path, str::FromStr};
+use std::path::Path;
 
-use chrono::TimeDelta;
 use clap::{Parser, Subcommand};
 use serde::{Deserialize, Serialize};
 
@@ -18,29 +17,9 @@ pub struct GbfsCliArguments {
 
 #[derive(Debug, Clone, Serialize, Deserialize, Subcommand)]
 pub enum GbfsOperation {
-    /// runs a GBFS download, writing data from some source URL
-    /// to an output directory.
-    Download {
-        /// a GBFS API URL
-        #[arg(short, long)]
-        gbfs_url: String,
-        /// output directory path.
-        #[arg(short, long, default_value_t = String::from("."))]
-        output_directory: String,
-        /// duration to collect data rows. provide in human-readable time values
-        /// 2m, 30s, 2h, 2days... applies to wait time modeling capability.
-        #[arg(short, long, value_parser = parse_duration, default_value = "10m")]
-        collect_duration: TimeDelta,
-        /// target of the initial HTTP call.
-        #[arg(long, default_value_t = EntryPoint::Gbfs)]
-        entry_point: EntryPoint,
-        /// GBFS version number to download.
-        #[arg(long, default_value_t = GbfsVersion::V3_0, value_parser = parse_version)]
-        version: GbfsVersion,
-    },
     /// downloads GBFS archives from a CSV. ignores archives missing geofence data. writes
     /// each dataset JSON 3.0 object to a file in the out directory.
-    DownloadWithGeofences {
+    BatchDownload {
         /// a file like <https://github.com/MobilityData/gbfs/blob/master/systems.csv>
         #[arg(long)]
         csv_file: String,
@@ -55,11 +34,21 @@ pub enum GbfsOperation {
         output_directory: String,
         #[arg(long, default_value = None)]
         parallelism: Option<usize>,
+        /// delay between calls to avoid getting rejected by provider rate limits during scraping.
         #[arg(long, default_value = None)]
         delay: Option<u64>,
+        /// if true, skip the Compass network edge list import
+        #[arg(long)]
+        no_compass: bool,
+        /// if true, skip writing the raw GBFS datasets to JSON files.
+        #[arg(long)]
+        no_summary: bool,
+        /// whether to overwrite the files if they already exist.
+        #[arg(long)]
+        overwrite: bool,
     },
     /// downloads a GBFS archive from its .gbfs endpoint.
-    DownloadAndImport {
+    Download {
         /// a GBFS API URL
         #[arg(long)]
         gbfs_url: String,
@@ -78,48 +67,38 @@ pub enum GbfsOperation {
 impl GbfsOperation {
     pub async fn run(&self) -> Result<(), String> {
         match self {
-            GbfsOperation::Download {
-                gbfs_url,
-                output_directory,
-                collect_duration,
-                entry_point,
-                version,
-            } => {
-                crate::app::download::run::gbfs_download_old(
-                    gbfs_url,
-                    Path::new(output_directory),
-                    collect_duration,
-                    *entry_point,
-                    *version,
-                )
-                .await
-            }
-            GbfsOperation::DownloadWithGeofences {
+            GbfsOperation::BatchDownload {
                 csv_file,
                 csv_column,
                 entry_point,
                 output_directory,
                 parallelism,
                 delay,
+                no_compass,
+                no_summary,
+                overwrite,
             } => {
                 let urls = crate::app::download::ops::gather_feeds(csv_file, csv_column)?;
                 log::info!("found {} urls", urls.len());
-                crate::app::download::run::gbfs_batch_metadata_download(
+                crate::app::download::run::batch_download(
                     &urls,
                     *entry_point,
                     Path::new(output_directory),
                     *parallelism,
                     *delay,
+                    *no_compass,
+                    *no_summary,
+                    *overwrite,
                 )
                 .await
             }
-            GbfsOperation::DownloadAndImport {
+            GbfsOperation::Download {
                 gbfs_url,
                 output_directory,
                 version,
                 overwrite,
             } => {
-                crate::app::download::run::gbfs_download_import(
+                crate::app::download::run::download_one(
                     gbfs_url,
                     Path::new(output_directory),
                     *version,
@@ -131,12 +110,12 @@ impl GbfsOperation {
     }
 }
 
-fn parse_duration(s: &str) -> Result<chrono::TimeDelta, String> {
-    let std_duration =
-        humantime::parse_duration(s).map_err(|e| format!("Invalid duration: {e}"))?;
-    chrono::TimeDelta::from_std(std_duration).map_err(|e| format!("TimeDelta out of range: {e}"))
-}
+// fn parse_duration(s: &str) -> Result<chrono::TimeDelta, String> {
+//     let std_duration =
+//         humantime::parse_duration(s).map_err(|e| format!("Invalid duration: {e}"))?;
+//     chrono::TimeDelta::from_std(std_duration).map_err(|e| format!("TimeDelta out of range: {e}"))
+// }
 
-fn parse_version(s: &str) -> Result<GbfsVersion, String> {
-    GbfsVersion::from_str(s)
-}
+// fn parse_version(s: &str) -> Result<GbfsVersion, String> {
+//     GbfsVersion::from_str(s)
+// }

From 2c816f193db73153517b5fdf475dbc569f4a5b1c Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 13:50:01 -0600
Subject: [PATCH 39/43] clippy

---
 rust/bambam-gbfs/src/app/download/run.rs | 1 -
 1 file changed, 1 deletion(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index a2ca785a..3c021735 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -5,7 +5,6 @@ use std::{
     sync::{Arc, Mutex},
 };
 
-use chrono::TimeDelta;
 use csv::QuoteStyle;
 use flate2::{Compression, write::GzEncoder};
 use geozero::ToWkt;

From 68d03ecb1abca692cbc9f32e17ac41499c5df4ea Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 13:55:44 -0600
Subject: [PATCH 40/43] fix dropped progress bar calls

---
 rust/bambam-gbfs/src/app/download/run.rs | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 3c021735..d20b13f1 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -73,12 +73,16 @@ pub async fn batch_download(
     for url in urls.iter() {
         let client = client.clone();
         let semaphore = semaphore.clone();
-        let url = url.to_string();
+        let url: String = url.to_string();
         let inner_bar = bar.clone();
         let start_delay = next_start_at.saturating_duration_since(Instant::now());
         next_start_at += spacing;
 
         set.spawn(async move {
+            if let Ok(mut bar) = inner_bar.lock() {
+                let _ = bar.update(1);
+            }
+
             if !start_delay.is_zero() {
                 tokio::time::sleep(start_delay).await;
             }
@@ -88,7 +92,7 @@ pub async fn batch_download(
                 .await
                 .map_err(|e| format!("failed to acquire concurrency permit: {e}"))?;
 
-            run_gbfs_download(client, url, entry_point, inner_bar).await
+            run_gbfs_download(client, url, entry_point).await
         });
     }
 
@@ -222,7 +226,6 @@ async fn run_gbfs_download(
     client: Arc<reqwest::Client>,
     url: String,
     entry_point: EntryPoint,
-    bar: Arc<Mutex<Bar>>,
 ) -> Result<Vec<GbfsRecord>, String> {
     let unversioned: super::download_metadata::UnversionedGbfsMetadata =
         super::ops::retrieve_file(&client, &url).await?;
@@ -259,10 +262,6 @@ async fn run_gbfs_download(
         }
     };
 
-    if let Ok(mut bar) = bar.lock() {
-        let _ = bar.update(1);
-    }
-
     Ok(result)
 }
 

From 4c591a212380995db6a1429454e501a19482f9a1 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 14:32:26 -0600
Subject: [PATCH 41/43] include URL on failure

---
 rust/bambam-gbfs/src/app/download/run.rs | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index d20b13f1..804aaf51 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -92,7 +92,9 @@ pub async fn batch_download(
                 .await
                 .map_err(|e| format!("failed to acquire concurrency permit: {e}"))?;
 
-            run_gbfs_download(client, url, entry_point).await
+            run_gbfs_download(client, &url, entry_point)
+                .await
+                .map_err(|e| format!("URL: '{url}' - {e}"))
         });
     }
 
@@ -224,11 +226,11 @@ pub async fn write_edge_list(
 
 async fn run_gbfs_download(
     client: Arc<reqwest::Client>,
-    url: String,
+    url: &String,
     entry_point: EntryPoint,
 ) -> Result<Vec<GbfsRecord>, String> {
     let unversioned: super::download_metadata::UnversionedGbfsMetadata =
-        super::ops::retrieve_file(&client, &url).await?;
+        super::ops::retrieve_file(&client, url).await?;
 
     let result: Vec<GbfsRecord> = match unversioned.version {
         super::download_metadata::UnversionedGbfsVersion::V2_2 => {
@@ -236,7 +238,7 @@ async fn run_gbfs_download(
                 EntryPoint::Manifest => {
                     return Err("manifest entry point not supported for version 2.2".to_string());
                 }
-                EntryPoint::Gbfs => gbfs_v2_2::run_v2_2_gbfs(&client, &url)
+                EntryPoint::Gbfs => gbfs_v2_2::run_v2_2_gbfs(&client, url)
                     .await
                     .map(|g| vec![g])?,
             };
@@ -244,7 +246,7 @@ async fn run_gbfs_download(
         }
         super::download_metadata::UnversionedGbfsVersion::V2_3 => {
             let result = match entry_point {
-                EntryPoint::Manifest => gbfs_v2_3::run_v2_3_manifest(&client, &url).await?,
+                EntryPoint::Manifest => gbfs_v2_3::run_v2_3_manifest(&client, url).await?,
                 EntryPoint::Gbfs => gbfs_v2_3::run_v2_3_gbfs(&client, &url)
                     .await
                     .map(|g| vec![g])?,
@@ -253,7 +255,7 @@ async fn run_gbfs_download(
         }
         super::download_metadata::UnversionedGbfsVersion::V3_0 => {
             let result = match entry_point {
-                EntryPoint::Manifest => gbfs_v3_0::run_v3_0_manifest(&client, &url).await?,
+                EntryPoint::Manifest => gbfs_v3_0::run_v3_0_manifest(&client, url).await?,
                 EntryPoint::Gbfs => gbfs_v3_0::run_v3_0_gbfs(&client, &url)
                     .await
                     .map(|g| vec![g])?,

From ad3c28e3c5a4825fb016c391f2ac9dfc8975f619 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Thu, 13 Aug 2026 14:32:35 -0600
Subject: [PATCH 42/43] clippy

---
 rust/bambam-gbfs/src/app/download/run.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rust/bambam-gbfs/src/app/download/run.rs b/rust/bambam-gbfs/src/app/download/run.rs
index 804aaf51..796ade7e 100644
--- a/rust/bambam-gbfs/src/app/download/run.rs
+++ b/rust/bambam-gbfs/src/app/download/run.rs
@@ -247,7 +247,7 @@ async fn run_gbfs_download(
         super::download_metadata::UnversionedGbfsVersion::V2_3 => {
             let result = match entry_point {
                 EntryPoint::Manifest => gbfs_v2_3::run_v2_3_manifest(&client, url).await?,
-                EntryPoint::Gbfs => gbfs_v2_3::run_v2_3_gbfs(&client, &url)
+                EntryPoint::Gbfs => gbfs_v2_3::run_v2_3_gbfs(&client, url)
                     .await
                     .map(|g| vec![g])?,
             };
@@ -256,7 +256,7 @@ async fn run_gbfs_download(
         super::download_metadata::UnversionedGbfsVersion::V3_0 => {
             let result = match entry_point {
                 EntryPoint::Manifest => gbfs_v3_0::run_v3_0_manifest(&client, url).await?,
-                EntryPoint::Gbfs => gbfs_v3_0::run_v3_0_gbfs(&client, &url)
+                EntryPoint::Gbfs => gbfs_v3_0::run_v3_0_gbfs(&client, url)
                     .await
                     .map(|g| vec![g])?,
             };

From c94a36112cabfefaf8da831db2f4222daee69884 Mon Sep 17 00:00:00 2001
From: Rob Fitzgerald <robert.fitzgerald@nrel.gov>
Date: Tue, 18 Aug 2026 08:13:44 -0600
Subject: [PATCH 43/43] reverse GBFS destination default and flip destination
 logic to "falsify"

---
 rust/bambam-gbfs/src/model/feature.rs                      | 7 ++++---
 .../src/model/traversal/gbfs_traversal/engine.rs           | 7 ++++---
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/rust/bambam-gbfs/src/model/feature.rs b/rust/bambam-gbfs/src/model/feature.rs
index ee9cb2b4..0d5eba58 100644
--- a/rust/bambam-gbfs/src/model/feature.rs
+++ b/rust/bambam-gbfs/src/model/feature.rs
@@ -22,10 +22,11 @@ pub mod variable {
         }
     }
 
+    /// each gbfs destination is assumed to be "true" and conditionally negated by the GBFS traversal model.
     pub fn gbfs_destination() -> StateVariableConfig {
         StateVariableConfig::Custom {
             custom_type: "Bool".to_string(),
-            value: CustomVariableConfig::Boolean { initial: false },
+            value: CustomVariableConfig::Boolean { initial: true },
             accumulator: false,
         }
     }
@@ -92,11 +93,11 @@ pub mod state {
     }
 
     /// affirms that the trip location associated with this state vector is a valid trip destination.
-    pub fn set_valid_destination(
+    pub fn set_invalid_destination(
         state: &mut [StateVariable],
         state_model: &StateModel,
     ) -> Result<(), StateModelError> {
-        state_model.set_custom_bool(state, fieldname::GBFS_DESTINATION, &true)
+        state_model.set_custom_bool(state, fieldname::GBFS_DESTINATION, &false)
     }
 
     /// is the trip location associated with this state vector is a valid trip destination?
diff --git a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
index 8e391c1e..6a7c92f1 100644
--- a/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
+++ b/rust/bambam-gbfs/src/model/traversal/gbfs_traversal/engine.rs
@@ -119,9 +119,10 @@ fn process_boarded(
         }
     };
 
-    // 1. is this a valid destination?
-    if zone.ride_end_allowed {
-        feature::state::set_valid_destination(state, state_model)?;
+    // 1. is this a valid destination? by default, we assume yes, but here
+    // we overwrite as false if `ride_end_allowed` is false.
+    if !zone.ride_end_allowed {
+        feature::state::set_invalid_destination(state, state_model)?;
     }
     // 2. set the speed, limiting if max speed is present
     let speed_value: Velocity = match zone.maximum_speed_kph {