adityamukho · Apr 4, 2026 · Apr 4, 2026 · Apr 4, 2026 · Apr 4, 2026 · Apr 4, 2026
@@ -19,7 +19,7 @@
 
 mod helpers;
 
-use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main};
 use minigraf::OpenOptions;
 
 // ── Task 3: insert/ ───────────────────────────────────────────────────────────

@@ -538,6 +538,46 @@ impl Minigraf {
         Ok(())
     }
 
+    /// Parse and plan a query once; bind slots (`$name`) are left unresolved.
+    ///
+    /// Returns a [`crate::query::datalog::prepared::PreparedQuery`] that can be executed
+    /// many times with different bind values via
+    /// [`crate::query::datalog::prepared::PreparedQuery::execute`].
+    ///
+    /// # Errors
+    /// - Parse failure.
+    /// - A bind slot appears in an attribute position (rejected at prepare time).
+    /// - The command is not a `(query ...)` — `transact`, `retract`, and `rule`
+    ///   are not preparable.
+    pub fn prepare(
+        &self,
+        query_str: &str,
+    ) -> Result<crate::query::datalog::prepared::PreparedQuery> {
+        use crate::query::datalog::prepared::prepare_query;
+
+        let cmd = parse_datalog_command(query_str).map_err(|e| anyhow::anyhow!("{}", e))?;
+
+        let query = match cmd {
+            DatalogCommand::Query(q) => q,
+            DatalogCommand::Transact(_) => {
+                anyhow::bail!("only (query ...) commands can be prepared; got transact")
+            }
+            DatalogCommand::Retract(_) => {
+                anyhow::bail!("only (query ...) commands can be prepared; got retract")
+            }
+            DatalogCommand::Rule(_) => {
+                anyhow::bail!("only (query ...) commands can be prepared; got rule")
+            }
+        };
+
+        prepare_query(
+            query,
+            self.inner.fact_storage.clone(),
+            self.inner.rules.clone(),
+            self.inner.functions.clone(),
+        )
+    }
+
     /// Returns a clone of the underlying `FactStorage` for use by the REPL.
     ///
     /// Cloning is cheap — `FactStorage` is `Arc`-backed.

@@ -319,6 +319,9 @@ impl FactStorage {
             .filter(|f| match as_of {
                 AsOf::Counter(n) => f.tx_count <= *n,
                 AsOf::Timestamp(t) => f.tx_id <= *t as u64,
+                AsOf::Slot(_) => {
+                    panic!("internal: unsubstituted :as-of bind slot reached get_facts_as_of");
+                }
             })
             .collect();
         Ok(filtered)

@@ -35,3 +35,6 @@ pub use query::{
 
 // Bi-temporal query types (Phase 4+)
 pub use query::datalog::types::{AsOf, ValidAt};
+
+// Prepared statements (Phase 7.8)
+pub use query::datalog::prepared::{BindValue, PreparedQuery};
@@ -217,6 +217,9 @@ impl DatalogExecutor {
                 .filter(|f| f.valid_from <= *t && *t < f.valid_to)
                 .collect(),
             Some(ValidAt::AnyValidTime) => asserted,
+            Some(ValidAt::Slot(_)) => {
+                panic!("internal: unsubstituted :valid-at bind slot reached the executor");
+            }
             None => asserted
                 .into_iter()
                 .filter(|f| f.valid_from <= now && now < f.valid_to)
@@ -239,6 +242,9 @@ impl DatalogExecutor {
         let valid_at_value = match &query.valid_at {
             Some(ValidAt::Timestamp(t)) => Value::Integer(*t),
             Some(ValidAt::AnyValidTime) => Value::Null,
+            Some(ValidAt::Slot(_)) => {
+                panic!("internal: unsubstituted :valid-at bind slot reached the executor");
+            }
             None => Value::Integer(now),
         };
 
@@ -365,6 +371,9 @@ impl DatalogExecutor {
         let valid_at_value = match &query.valid_at {
             Some(ValidAt::Timestamp(t)) => Value::Integer(*t),
             Some(ValidAt::AnyValidTime) => Value::Null,
+            Some(ValidAt::Slot(_)) => {
+                panic!("internal: unsubstituted :valid-at bind slot reached the executor");
+            }
             None => Value::Integer(now),
         };
 
@@ -1085,6 +1094,9 @@ pub(crate) fn evaluate_branch(
     let branch_valid_at_value = match &valid_at {
         Some(ValidAt::Timestamp(t)) => Value::Integer(*t),
         Some(ValidAt::AnyValidTime) => Value::Null,
+        Some(ValidAt::Slot(_)) => {
+            panic!("internal: unsubstituted :valid-at bind slot reached the executor");
+        }
         None => Value::Integer(tx_id_now() as i64),
     };
 
@@ -1432,6 +1444,9 @@ pub(crate) fn eval_expr(
             let r = eval_expr(rhs, binding, registry)?;
             eval_binop(op, l, r)
         }
+        Expr::Slot(_) => {
+            panic!("internal: unsubstituted bind slot reached eval_expr");
+        }
     }
 }
 

@@ -4,6 +4,7 @@ pub mod functions;
 pub mod matcher;
 pub mod optimizer;
 pub mod parser;
+pub mod prepared;
 pub mod rules;
 pub mod stratification;
 pub mod types;

@@ -24,6 +24,7 @@ enum Token {
     Boolean(bool),
     TaggedLiteral(String), // e.g., "#uuid"
     Nil,
+    BindSlot(String), // $identifier — named bind slot for PreparedQuery
 }
 
 /// Tokenize EDN input
@@ -219,6 +220,31 @@ fn tokenize(input: &str) -> Result<Vec<Token>, String> {
                     return Err("Unexpected character: !".to_string());
                 }
             }
+            '$' => {
+                chars.next(); // consume '$'
+                let mut name = String::new();
+                while let Some(&ch) = chars.peek() {
+                    if ch.is_alphanumeric() || ch == '_' || ch == '-' {
+                        if name.len() >= MAX_SYMBOL_LENGTH {
+                            return Err(format!(
+                                "Bind slot name exceeds maximum length of {} bytes",
+                                MAX_SYMBOL_LENGTH
+                            ));
+                        }
+                        name.push(ch);
+                        chars.next();
+                    } else {
+                        break;
+                    }
+                }
+                if name.is_empty() {
+                    return Err(
+                        "Bind slot '$' must be followed by an identifier (e.g. $entity)"
+                            .to_string(),
+                    );
+                }
+                tokens.push(Token::BindSlot(name));
+            }
             _ => {
                 return Err(format!("Unexpected character: {}", ch));
             }
@@ -384,6 +410,13 @@ impl Parser {
                 self.advance();
                 Ok(EdnValue::Nil)
             }
+            Some(Token::BindSlot(_)) => {
+                if let Some(Token::BindSlot(name)) = self.advance() {
+                    Ok(EdnValue::BindSlot(name))
+                } else {
+                    unreachable!()
+                }
+            }
             Some(token) => Err(format!("Unexpected token: {:?}", token)),
             None => Err("Unexpected end of input".to_string()),
         }
@@ -676,6 +709,7 @@ fn parse_query(elements: &[EdnValue]) -> Result<DatalogCommand, String> {
                             let ts = parse_timestamp(s).map_err(|e| e.to_string())?;
                             AsOf::Timestamp(ts)
                         }
+                        EdnValue::BindSlot(name) => AsOf::Slot(name.clone()),
                         other => {
                             return Err(format!(
                                 ":as-of must be an integer (counter) or ISO 8601 string, got {:?}",
@@ -698,6 +732,7 @@ fn parse_query(elements: &[EdnValue]) -> Result<DatalogCommand, String> {
                             ValidAt::Timestamp(ts)
                         }
                         EdnValue::Keyword(k) if k == ":any-valid-time" => ValidAt::AnyValidTime,
+                        EdnValue::BindSlot(name) => ValidAt::Slot(name.clone()),
                         other => {
                             return Err(format!(
                                 ":valid-at must be an ISO 8601 string or :any-valid-time, got {:?}",
@@ -981,6 +1016,7 @@ fn parse_expr_arg(edn: &EdnValue) -> Result<Expr, String> {
         EdnValue::Nil => Ok(Expr::Lit(Value::Null)),
         EdnValue::Keyword(k) => Ok(Expr::Lit(Value::Keyword(k.clone()))),
         EdnValue::List(inner) => parse_expr(inner),
+        EdnValue::BindSlot(name) => Ok(Expr::Slot(name.clone())),
         other => Err(format!("unsupported expression argument: {:?}", other)),
     }
 }
@@ -1492,6 +1528,7 @@ fn expr_vars(expr: &Expr) -> Vec<String> {
             v
         }
         Expr::UnaryOp(_, arg) => expr_vars(arg),
+        Expr::Slot(_) => vec![],
     }
 }
 
@@ -2667,6 +2704,112 @@ mod tests {
             "pseudo-attr in value position should error"
         );
     }
+
+    #[test]
+    fn test_tokenize_bind_slot() {
+        let result = parse_edn("$entity");
+        assert!(
+            matches!(result, Ok(EdnValue::BindSlot(ref s)) if s == "entity"),
+            "expected BindSlot"
+        );
+    }
+
+    #[test]
+    fn test_tokenize_bind_slot_hyphenated() {
+        let result = parse_edn("$min-level");
+        assert!(
+            matches!(result, Ok(EdnValue::BindSlot(ref s)) if s == "min-level"),
+            "expected BindSlot(min-level)"
+        );
+    }
+
+    #[test]
+    fn test_parse_bind_slot_in_entity_position() {
+        let cmd =
+            parse_datalog_command("(query [:find ?name :where [$entity :person/name ?name]])");
+        assert!(cmd.is_ok(), "parse failed");
+        match cmd.unwrap() {
+            DatalogCommand::Query(q) => match &q.where_clauses[0] {
+                WhereClause::Pattern(p) => {
+                    assert!(matches!(&p.entity, EdnValue::BindSlot(s) if s == "entity"));
+                }
+                _ => panic!("expected Pattern"),
+            },
+            _ => panic!("expected Query"),
+        }
+    }
+
+    #[test]
+    fn test_parse_bind_slot_in_value_position() {
+        let cmd = parse_datalog_command("(query [:find ?e :where [?e :person/name $name]])");
+        assert!(cmd.is_ok(), "parse failed");
+        match cmd.unwrap() {
+            DatalogCommand::Query(q) => match &q.where_clauses[0] {
+                WhereClause::Pattern(p) => {
+                    assert!(matches!(&p.value, EdnValue::BindSlot(s) if s == "name"));
+                }
+                _ => panic!("expected Pattern"),
+            },
+            _ => panic!("expected Query"),
+        }
+    }
+
+    #[test]
+    fn test_parse_as_of_slot() {
+        let cmd = parse_datalog_command("(query [:find ?v :as-of $tx :where [?e :score ?v]])");
+        assert!(cmd.is_ok(), "parse failed");
+        match cmd.unwrap() {
+            DatalogCommand::Query(q) => {
+                assert!(matches!(q.as_of, Some(AsOf::Slot(ref s)) if s == "tx"));
+            }
+            _ => panic!("expected Query"),
+        }
+    }
+
+    #[test]
+    fn test_parse_valid_at_slot() {
+        let cmd = parse_datalog_command("(query [:find ?v :valid-at $date :where [?e :score ?v]])");
+        assert!(cmd.is_ok(), "parse failed");
+        match cmd.unwrap() {
+            DatalogCommand::Query(q) => {
+                assert!(matches!(q.valid_at, Some(ValidAt::Slot(ref s)) if s == "date"));
+            }
+            _ => panic!("expected Query"),
+        }
+    }
+
+    #[test]
+    fn test_parse_expr_bind_slot_in_binop() {
+        let cmd = parse_datalog_command(
+            "(query [:any-valid-time :find ?v :where [?e :score ?v] [(>= ?v $threshold)]])",
+        );
+        assert!(cmd.is_ok(), "parse failed");
+        match cmd.unwrap() {
+            DatalogCommand::Query(q) => {
+                let expr_clause = q
+                    .where_clauses
+                    .iter()
+                    .find(|c| matches!(c, WhereClause::Expr { .. }));
+                assert!(expr_clause.is_some(), "no Expr clause found");
+                match expr_clause.unwrap() {
+                    WhereClause::Expr {
+                        expr: Expr::BinOp(_, _, rhs),
+                        ..
+                    } => {
+                        assert!(matches!(rhs.as_ref(), Expr::Slot(s) if s == "threshold"));
+                    }
+                    _other => panic!("expected BinOp Expr clause"),
+                }
+            }
+            _ => panic!("expected Query"),
+        }
+    }
+
+    #[test]
+    fn test_parse_bind_slot_empty_name_is_error() {
+        let result = parse_edn("$");
+        assert!(result.is_err(), "bare '$' should be a parse error");
+    }
 }
 
 #[cfg(test)]