From 50c1b0ddc559ed149812662dd1fb3212613fec28 Mon Sep 17 00:00:00 2001
From: EnRaiha <15997552+EnRaiha@users.noreply.github.com>
Date: Wed, 16 Sep 2026 13:24:29 +0800
Subject: [PATCH 1/2] fix(sql): track token consumption in the graph DSL

A mistyped clause keyword (`DEPTS` for `DEPTH`) defaulted the clause and
left its value unread, so the statement answered a different question than
it asked, with no error. The clause readers were independent forward scans
that ignored every token between a keyword and its value.

A cursor now claims the tokens each clause consumes, and the dispatcher
refuses the first token no clause claimed, naming it. All statement
variants are covered; `MATCH` statements are untouched.
---
 nodedb-sql/src/ddl_ast/graph_parse/cursor.rs  | 279 ++++++++++++++++++
 nodedb-sql/src/ddl_ast/graph_parse/entry.rs   |  46 ++-
 nodedb-sql/src/ddl_ast/graph_parse/helpers.rs |  76 +----
 nodedb-sql/src/ddl_ast/graph_parse/mod.rs     |   1 +
 .../src/ddl_ast/graph_parse/variants.rs       | 223 +++++++++-----
 nodedb/tests/wire/cases/graph_dsl_handlers.rs |  36 +++
 6 files changed, 508 insertions(+), 153 deletions(-)
 create mode 100644 nodedb-sql/src/ddl_ast/graph_parse/cursor.rs

diff --git a/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs b/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs
new file mode 100644
index 000000000..3b6bcb775
--- /dev/null
+++ b/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs
@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//! Consume-tracking cursor over a graph DSL token list.
+//!
+//! The module's parse is seek-based: a clause reader finds its keyword
+//! wherever it appears and ignores every token between. That is fine while
+//! every token belongs to some clause. It is wrong the moment a token belongs
+//! to none: `GRAPH TRAVERSE FROM 1 DEPTS 3 IN g` finds no `DEPTH`, defaults
+//! the depth, and leaves `DEPTS 3` unread — the statement answers a different
+//! question than it asked, with no error.
+//!
+//! The cursor records which tokens each clause consumed. After the statement
+//! is built, [`Cursor::finish`] refuses the first token no clause claimed.
+//! A typo is then a parse error that names the token, and a new clause cannot
+//! be added without deciding what it consumes.
+
+use super::tokenizer::Tok;
+use crate::error::SqlError;
+
+/// A token list plus the set of tokens a clause has claimed.
+pub(super) struct Cursor<'a> {
+    toks: Vec<Tok<'a>>,
+    used: Vec<bool>,
+}
+
+impl<'a> Cursor<'a> {
+    /// Build a cursor over `toks`. The first `prefix_len` tokens are the
+    /// command words (`GRAPH TRAVERSE`), which the dispatcher matched and no
+    /// clause will claim.
+    pub(super) fn new(toks: Vec<Tok<'a>>, prefix_len: usize) -> Self {
+        let mut used = vec![false; toks.len()];
+        for slot in used.iter_mut().take(prefix_len.min(toks.len())) {
+            *slot = true;
+        }
+        Self { toks, used }
+    }
+
+    fn is_keyword(tok: &Tok<'_>, keyword: &str) -> bool {
+        matches!(tok, Tok::Word(w) if w.eq_ignore_ascii_case(keyword))
+    }
+
+    /// Position of `keyword`, claiming it. A keyword already claimed by an
+    /// earlier clause still matches: `IN` in one statement is one clause, but
+    /// the seek-based readers may be called in any order.
+    fn find(&mut self, keyword: &str) -> Option<usize> {
+        let pos = self
+            .toks
+            .iter()
+            .position(|tok| Self::is_keyword(tok, keyword))?;
+        self.used[pos] = true;
+        Some(pos)
+    }
+
+    /// Claim the value token at `pos` when it is a word or a quoted literal.
+    /// An object literal is claimed by the callers that accept one.
+    fn claim_text(&mut self, pos: usize) -> Option<String> {
+        let value = match self.toks.get(pos)? {
+            Tok::Quoted(s) => s.clone().into_owned(),
+            Tok::Word(w) => (*w).to_string(),
+            Tok::Object(_) => return None,
+        };
+        self.used[pos] = true;
+        Some(value)
+    }
+
+    /// The word or quoted literal after `keyword`.
+    pub(super) fn quoted_after(&mut self, keyword: &str) -> Option<String> {
+        let pos = self.find(keyword)?;
+        self.claim_text(pos + 1)
+    }
+
+    /// Every consecutive word or quoted literal after `keyword`, up to the
+    /// first token that is neither. Used by `AS <label> [, <label>…]`.
+    pub(super) fn quoted_list_after(&mut self, keyword: &str) -> Vec<String> {
+        let Some(pos) = self.find(keyword) else {
+            return Vec::new();
+        };
+        let mut out = Vec::new();
+        let mut at = pos + 1;
+        while let Some(value) = self.claim_text(at) {
+            out.push(value);
+            at += 1;
+        }
+        out
+    }
+
+    /// The brace-balanced object literal after `keyword`.
+    pub(super) fn object_after(&mut self, keyword: &str) -> Option<String> {
+        let pos = self.find(keyword)?;
+        match self.toks.get(pos + 1)? {
+            Tok::Object(s) => {
+                self.used[pos + 1] = true;
+                Some((*s).to_string())
+            }
+            _ => None,
+        }
+    }
+
+    /// The bare word after `keyword`.
+    pub(super) fn word_after(&mut self, keyword: &str) -> Option<String> {
+        let pos = self.find(keyword)?;
+        match self.toks.get(pos + 1)? {
+            Tok::Word(w) => {
+                self.used[pos + 1] = true;
+                Some((*w).to_string())
+            }
+            _ => None,
+        }
+    }
+
+    /// The unsigned integer after `keyword`.
+    pub(super) fn usize_after(&mut self, keyword: &str) -> Option<usize> {
+        self.word_after(keyword)?.parse().ok()
+    }
+
+    /// The float after `keyword`.
+    pub(super) fn float_after(&mut self, keyword: &str) -> Option<f64> {
+        self.word_after(keyword)?.parse().ok()
+    }
+
+    /// The next `count` float words after `keyword`.
+    pub(super) fn floats_after<const N: usize>(&mut self, keyword: &str) -> Option<[f64; N]> {
+        let pos = self.find(keyword)?;
+        let mut out = [0.0f64; N];
+        for (offset, slot) in out.iter_mut().enumerate() {
+            let value = match self.toks.get(pos + 1 + offset)? {
+                Tok::Word(w) => w.parse::<f64>().ok()?,
+                _ => return None,
+            };
+            self.used[pos + 1 + offset] = true;
+            *slot = value;
+        }
+        Some(out)
+    }
+
+    /// Read a `DIRECTION` clause.
+    ///
+    /// An omitted clause defaults to `out`. A value outside the vocabulary is
+    /// refused by name — defaulting it would answer a question the caller did
+    /// not ask, and `DIRECTION INBOUND` is indistinguishable from `DIRECTION
+    /// BANANA` once both have become `out`.
+    pub(super) fn direction_after(
+        &mut self,
+        keyword: &str,
+    ) -> Result<super::super::statement::GraphDirection, SqlError> {
+        use super::super::statement::GraphDirection;
+        let Some(word) = self.word_after(keyword) else {
+            return Ok(GraphDirection::Out);
+        };
+        match word.to_ascii_uppercase().as_str() {
+            "IN" => Ok(GraphDirection::In),
+            "OUT" => Ok(GraphDirection::Out),
+            "BOTH" => Ok(GraphDirection::Both),
+            _ => Err(SqlError::Parse {
+                detail: format!("{keyword} must be one of in, out, both — found '{word}'"),
+            }),
+        }
+    }
+
+    /// An optional numeric clause, refusing a value that is present but not a
+    /// number. `Ok(None)` means the clause was omitted, so the caller applies
+    /// its own default; it never means "the value was unreadable".
+    pub(super) fn usize_after_checked(&mut self, keyword: &str) -> Result<Option<usize>, SqlError> {
+        let Some(word) = self.word_after(keyword) else {
+            return Ok(None);
+        };
+        word.parse().map(Some).map_err(|_| SqlError::Parse {
+            detail: format!("{keyword} must be a non-negative integer — found '{word}'"),
+        })
+    }
+
+    /// The `PROPERTIES {…}` / `PROPERTIES 'literal'` clause.
+    pub(super) fn extract_properties(&mut self) -> super::super::statement::GraphProperties {
+        use super::super::statement::GraphProperties;
+        let Some(pos) = self.find("PROPERTIES") else {
+            return GraphProperties::None;
+        };
+        match self.toks.get(pos + 1) {
+            Some(Tok::Object(obj_str)) => {
+                self.used[pos + 1] = true;
+                GraphProperties::Object((*obj_str).to_string())
+            }
+            Some(Tok::Quoted(s)) => {
+                self.used[pos + 1] = true;
+                GraphProperties::Quoted(s.clone().into_owned())
+            }
+            _ => GraphProperties::None,
+        }
+    }
+
+    /// The token slice, for readers that validate their own span (fusion
+    /// parameters read the bracket payload from the raw statement text).
+    pub(super) fn tokens(&self) -> &[Tok<'a>] {
+        &self.toks
+    }
+
+    /// Claim every remaining token.
+    ///
+    /// For a statement whose parameters a dedicated extractor validated
+    /// (`GRAPH RAG FUSION`), where this cursor's clause readers do not see the
+    /// bracket payload the extractor reads from the raw text.
+    pub(super) fn consume_rest(&mut self) {
+        for slot in self.used.iter_mut() {
+            *slot = true;
+        }
+    }
+
+    /// Refuse the first token no clause claimed.
+    pub(super) fn finish(self, statement: &str) -> Result<(), SqlError> {
+        for (tok, used) in self.toks.iter().zip(self.used.iter()) {
+            if *used {
+                continue;
+            }
+            let text = match tok {
+                Tok::Word(w) => (*w).to_string(),
+                Tok::Quoted(s) => s.to_string(),
+                Tok::Object(_) => "{…}".to_string(),
+            };
+            return Err(SqlError::Parse {
+                detail: format!("{statement}: unexpected token '{text}'"),
+            });
+        }
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ddl_ast::graph_parse::tokenizer::tokenize;
+
+    #[test]
+    fn a_mistyped_keyword_is_left_unclaimed() {
+        let toks = tokenize("GRAPH TRAVERSE FROM 1 DEPTS 3 IN g");
+        let mut cursor = Cursor::new(toks, 2);
+        assert_eq!(cursor.quoted_after("FROM").as_deref(), Some("1"));
+        assert_eq!(cursor.quoted_after("IN").as_deref(), Some("g"));
+        assert!(cursor.usize_after_checked("DEPTH").unwrap().is_none());
+        let err = cursor.finish("GRAPH TRAVERSE").unwrap_err();
+        assert!(
+            err.to_string().contains("DEPTS"),
+            "the error must name the unclaimed token: {err}"
+        );
+    }
+
+    #[test]
+    fn a_consumed_clause_leaves_nothing_unclaimed() {
+        let toks = tokenize("GRAPH TRAVERSE FROM 1 DEPTH 3 IN g DIRECTION both");
+        let mut cursor = Cursor::new(toks, 2);
+        assert_eq!(cursor.quoted_after("FROM").as_deref(), Some("1"));
+        assert_eq!(cursor.usize_after_checked("DEPTH").unwrap(), Some(3));
+        assert_eq!(cursor.quoted_after("IN").as_deref(), Some("g"));
+        let _ = cursor.direction_after("DIRECTION").unwrap();
+        cursor
+            .finish("GRAPH TRAVERSE")
+            .expect("every token claimed");
+    }
+
+    #[test]
+    fn a_stray_quoted_literal_is_refused() {
+        let toks = tokenize("GRAPH PATH FROM 'a' TO 'b' 'stray'");
+        let mut cursor = Cursor::new(toks, 2);
+        assert_eq!(cursor.quoted_after("FROM").as_deref(), Some("a"));
+        assert_eq!(cursor.quoted_after("TO").as_deref(), Some("b"));
+        let err = cursor.finish("GRAPH PATH").unwrap_err();
+        assert!(err.to_string().contains("stray"), "{err}");
+    }
+
+    #[test]
+    fn a_float_pair_is_claimed_together() {
+        let toks = tokenize("GRAPH RAG FUSION ON g RRF_K (60.0, 35.0)");
+        let mut cursor = Cursor::new(toks, 3);
+        assert_eq!(cursor.word_after("ON").as_deref(), Some("g"));
+        assert_eq!(cursor.floats_after::<2>("RRF_K"), Some([60.0, 35.0]));
+        cursor
+            .finish("GRAPH RAG FUSION")
+            .expect("every token claimed");
+    }
+}
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/entry.rs b/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
index 1976639ac..cc138dd02 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
@@ -3,7 +3,11 @@
 //! Graph DSL entry point.
 
 use super::super::statement::{GraphStmt, NodedbStatement};
-use super::{tokenizer, variants};
+use super::{
+    cursor::Cursor,
+    tokenizer::{self, Tok},
+    variants,
+};
 use crate::error::SqlError;
 
 /// Parse a graph DSL statement.
@@ -31,23 +35,29 @@ pub fn try_parse(sql: &str) -> Option<Result<NodedbStatement, SqlError>> {
     let toks = tokenizer::tokenize(trimmed);
 
     let parsed = if upper.starts_with("GRAPH INSERT EDGE ") {
-        variants::parse_insert_edge(&toks)
+        run(toks, 3, "GRAPH INSERT EDGE", variants::parse_insert_edge)
     } else if upper.starts_with("GRAPH DELETE EDGE ") {
-        variants::parse_delete_edge(&toks)
+        run(toks, 3, "GRAPH DELETE EDGE", variants::parse_delete_edge)
     } else if upper.starts_with("GRAPH LABEL ") {
-        variants::parse_set_labels(&toks, false)
+        run(toks, 2, "GRAPH LABEL", |cursor| {
+            variants::parse_set_labels(cursor, false)
+        })
     } else if upper.starts_with("GRAPH UNLABEL ") {
-        variants::parse_set_labels(&toks, true)
+        run(toks, 2, "GRAPH UNLABEL", |cursor| {
+            variants::parse_set_labels(cursor, true)
+        })
     } else if upper.starts_with("GRAPH TRAVERSE ") {
-        variants::parse_traverse(&toks)
+        run(toks, 2, "GRAPH TRAVERSE", variants::parse_traverse)
     } else if upper.starts_with("GRAPH NEIGHBORS ") {
-        variants::parse_neighbors(&toks)
+        run(toks, 2, "GRAPH NEIGHBORS", variants::parse_neighbors)
     } else if upper.starts_with("GRAPH PATH ") {
-        variants::parse_path(&toks)
+        run(toks, 2, "GRAPH PATH", variants::parse_path)
     } else if upper.starts_with("GRAPH ALGO ") {
-        variants::parse_algo(&toks)
+        run(toks, 2, "GRAPH ALGO", variants::parse_algo)
     } else if upper.starts_with("GRAPH RAG FUSION ") {
-        variants::parse_rag_fusion(&toks, trimmed)
+        run(toks, 3, "GRAPH RAG FUSION", |cursor| {
+            variants::parse_rag_fusion(cursor, trimmed)
+        })
     } else {
         // Starts with `GRAPH ` but names no known command. Still graph DSL,
         // so report it here rather than letting the SQL parser guess.
@@ -59,6 +69,22 @@ pub fn try_parse(sql: &str) -> Option<Result<NodedbStatement, SqlError>> {
     Some(parsed)
 }
 
+/// Run one variant with a consume-tracking cursor, then refuse any token the
+/// statement left unclaimed.
+///
+/// `prefix_len` counts the command words the dispatcher matched
+/// (`GRAPH TRAVERSE` is two, `GRAPH INSERT EDGE` is three); no clause claims
+/// them.
+fn run<'a>(
+    toks: Vec<Tok<'a>>,
+    prefix_len: usize,
+    statement: &str,
+    parse: impl FnOnce(&mut Cursor<'a>) -> Result<NodedbStatement, SqlError>,
+) -> Result<NodedbStatement, SqlError> {
+    let mut cursor = Cursor::new(toks, prefix_len);
+    parse(&mut cursor).and_then(|stmt| cursor.finish(statement).map(|()| stmt))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs b/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
index c109438f3..7a9f0db59 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
@@ -1,9 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 
-use super::{
-    super::statement::{GraphDirection, GraphProperties},
-    tokenizer::Tok,
-};
+use super::tokenizer::Tok;
 use crate::error::SqlError;
 
 pub(super) fn find_keyword(toks: &[Tok<'_>], keyword: &str) -> Option<usize> {
@@ -20,31 +17,10 @@ pub(super) fn quoted_after(toks: &[Tok<'_>], keyword: &str) -> Option<String> {
     }
 }
 
-pub(super) fn quoted_list_after(toks: &[Tok<'_>], keyword: &str) -> Vec<String> {
-    let Some(pos) = find_keyword(toks, keyword) else {
-        return Vec::new();
-    };
-    toks[pos + 1..]
-        .iter()
-        .map_while(|t| match t {
-            Tok::Quoted(s) => Some(s.clone().into_owned()),
-            _ => None,
-        })
-        .collect()
-}
-
 /// Extract a brace-balanced object literal (`{…}`, braces included) that
 /// immediately follows `keyword`. Used for `PERSONALIZATION {…}` in
 /// `GRAPH ALGO`. Returns `None` when the keyword is absent or is not followed
 /// by an object token.
-pub(super) fn object_after(toks: &[Tok<'_>], keyword: &str) -> Option<String> {
-    let pos = find_keyword(toks, keyword)?;
-    match toks.get(pos + 1)? {
-        Tok::Object(s) => Some((*s).to_string()),
-        _ => None,
-    }
-}
-
 pub(super) fn word_after(toks: &[Tok<'_>], keyword: &str) -> Option<String> {
     let pos = find_keyword(toks, keyword)?;
     if let Tok::Word(w) = toks.get(pos + 1)? {
@@ -58,10 +34,6 @@ pub(super) fn usize_after(toks: &[Tok<'_>], keyword: &str) -> Option<usize> {
     word_after(toks, keyword)?.parse().ok()
 }
 
-pub(super) fn float_after(toks: &[Tok<'_>], keyword: &str) -> Option<f64> {
-    word_after(toks, keyword)?.parse().ok()
-}
-
 /// Extract the two consecutive float tokens that follow `keyword`.
 ///
 /// The tokenizer strips `(` and `)`, so `RRF_K (60.0, 35.0)` becomes the
@@ -102,41 +74,6 @@ pub(super) fn float_triple_after(toks: &[Tok<'_>], keyword: &str) -> Option<(f64
     Some((k1, k2, k3))
 }
 
-/// Read a `DIRECTION` clause.
-///
-/// An omitted clause defaults to `out`. A value outside the vocabulary is
-/// refused by name — defaulting it would answer a question the caller did
-/// not ask, and `DIRECTION INBOUND` is indistinguishable from `DIRECTION
-/// BANANA` once both have become `out`.
-pub(super) fn direction_after(toks: &[Tok<'_>]) -> Result<GraphDirection, SqlError> {
-    let Some(word) = word_after(toks, "DIRECTION") else {
-        return Ok(GraphDirection::Out);
-    };
-    match word.to_ascii_uppercase().as_str() {
-        "IN" => Ok(GraphDirection::In),
-        "OUT" => Ok(GraphDirection::Out),
-        "BOTH" => Ok(GraphDirection::Both),
-        _ => Err(SqlError::Parse {
-            detail: format!("DIRECTION must be one of in, out, both — found '{word}'"),
-        }),
-    }
-}
-
-/// Read an optional numeric clause, refusing a value that is present but
-/// not a number. `Ok(None)` means the clause was omitted, so the caller
-/// applies its own default; it never means "the value was unreadable".
-pub(super) fn usize_after_checked(
-    toks: &[Tok<'_>],
-    keyword: &str,
-) -> Result<Option<usize>, SqlError> {
-    let Some(word) = word_after(toks, keyword) else {
-        return Ok(None);
-    };
-    word.parse().map(Some).map_err(|_| SqlError::Parse {
-        detail: format!("{keyword} must be a non-negative integer — found '{word}'"),
-    })
-}
-
 /// A required clause was absent.
 pub(super) fn missing_clause(statement: &str, clause: &str) -> SqlError {
     SqlError::Parse {
@@ -144,17 +81,6 @@ pub(super) fn missing_clause(statement: &str, clause: &str) -> SqlError {
     }
 }
 
-pub(super) fn extract_properties(toks: &[Tok<'_>]) -> GraphProperties {
-    let Some(pos) = find_keyword(toks, "PROPERTIES") else {
-        return GraphProperties::None;
-    };
-    match toks.get(pos + 1) {
-        Some(Tok::Object(obj_str)) => GraphProperties::Object((*obj_str).to_string()),
-        Some(Tok::Quoted(s)) => GraphProperties::Quoted(s.clone().into_owned()),
-        _ => GraphProperties::None,
-    }
-}
-
 /// Extract `ARRAY[f1, f2, …]` that appears after `keyword` in raw SQL.
 ///
 /// Used for `QUERY ARRAY[…]` in `GRAPH RAG FUSION` where the vector payload
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/mod.rs b/nodedb-sql/src/ddl_ast/graph_parse/mod.rs
index aab9f0408..fbc404dc0 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/mod.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/mod.rs
@@ -20,6 +20,7 @@
 //! vocabulary, means no statement reaches the boundary at all. Both are
 //! reported as a parse error naming what is wrong.
 
+mod cursor;
 mod entry;
 pub mod fusion_params;
 mod helpers;
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/variants.rs b/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
index 6939e724b..917128bf8 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
@@ -7,26 +7,35 @@
 //! here, so "this clause is missing" must not be reported the same way as
 //! "this was never a graph statement" — the second sends the input to the
 //! general SQL parser, which can only say `GRAPH` is not SQL.
+//!
+//! Each parser reads its clauses through [`Cursor`], which claims the tokens
+//! it consumes; the dispatcher refuses any token left unclaimed. A mistyped
+//! keyword is then a parse error naming the token, not a silently defaulted
+//! clause.
 
 use super::{
     super::statement::{GraphStmt, NodedbStatement},
+    cursor::Cursor,
     fusion_params::{FusionParams, RAG_FUSION_KEYWORDS},
-    helpers::{
-        direction_after, extract_properties, missing_clause, quoted_after, quoted_list_after,
-        usize_after, usize_after_checked, word_after,
-    },
-    tokenizer::Tok,
+    helpers::missing_clause,
 };
 use crate::error::SqlError;
 
-pub(super) fn parse_insert_edge(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_insert_edge(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH INSERT EDGE";
-    let collection =
-        quoted_after(toks, "IN").ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
-    let src = quoted_after(toks, "FROM").ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
-    let dst = quoted_after(toks, "TO").ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
-    let label = quoted_after(toks, "TYPE").ok_or_else(|| missing_clause(STMT, "TYPE <label>"))?;
-    let properties = extract_properties(toks);
+    let collection = cursor
+        .quoted_after("IN")
+        .ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
+    let src = cursor
+        .quoted_after("FROM")
+        .ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
+    let dst = cursor
+        .quoted_after("TO")
+        .ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
+    let label = cursor
+        .quoted_after("TYPE")
+        .ok_or_else(|| missing_clause(STMT, "TYPE <label>"))?;
+    let properties = cursor.extract_properties();
     Ok(NodedbStatement::Graph(GraphStmt::GraphInsertEdge {
         collection,
         src,
@@ -36,13 +45,20 @@ pub(super) fn parse_insert_edge(toks: &[Tok<'_>]) -> Result<NodedbStatement, Sql
     }))
 }
 
-pub(super) fn parse_delete_edge(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_delete_edge(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH DELETE EDGE";
-    let collection =
-        quoted_after(toks, "IN").ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
-    let src = quoted_after(toks, "FROM").ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
-    let dst = quoted_after(toks, "TO").ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
-    let label = quoted_after(toks, "TYPE").ok_or_else(|| missing_clause(STMT, "TYPE <label>"))?;
+    let collection = cursor
+        .quoted_after("IN")
+        .ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
+    let src = cursor
+        .quoted_after("FROM")
+        .ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
+    let dst = cursor
+        .quoted_after("TO")
+        .ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
+    let label = cursor
+        .quoted_after("TYPE")
+        .ok_or_else(|| missing_clause(STMT, "TYPE <label>"))?;
     Ok(NodedbStatement::Graph(GraphStmt::GraphDeleteEdge {
         collection,
         src,
@@ -52,13 +68,14 @@ pub(super) fn parse_delete_edge(toks: &[Tok<'_>]) -> Result<NodedbStatement, Sql
 }
 
 pub(super) fn parse_set_labels(
-    toks: &[Tok<'_>],
+    cursor: &mut Cursor<'_>,
     remove: bool,
 ) -> Result<NodedbStatement, SqlError> {
     let keyword = if remove { "UNLABEL" } else { "LABEL" };
-    let node_id = quoted_after(toks, keyword)
+    let node_id = cursor
+        .quoted_after(keyword)
         .ok_or_else(|| missing_clause(&format!("GRAPH {keyword}"), "<node>"))?;
-    let labels = quoted_list_after(toks, "AS");
+    let labels = cursor.quoted_list_after("AS");
     Ok(NodedbStatement::Graph(GraphStmt::GraphSetLabels {
         node_id,
         labels,
@@ -66,14 +83,17 @@ pub(super) fn parse_set_labels(
     }))
 }
 
-pub(super) fn parse_traverse(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_traverse(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH TRAVERSE";
-    let collection =
-        quoted_after(toks, "IN").ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
-    let start = quoted_after(toks, "FROM").ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
-    let depth = usize_after_checked(toks, "DEPTH")?.unwrap_or(2);
-    let edge_label = quoted_after(toks, "LABEL");
-    let direction = direction_after(toks)?;
+    let collection = cursor
+        .quoted_after("IN")
+        .ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
+    let start = cursor
+        .quoted_after("FROM")
+        .ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
+    let depth = cursor.usize_after_checked("DEPTH")?.unwrap_or(2);
+    let edge_label = cursor.quoted_after("LABEL");
+    let direction = cursor.direction_after("DIRECTION")?;
     Ok(NodedbStatement::Graph(GraphStmt::GraphTraverse {
         collection,
         start,
@@ -83,13 +103,16 @@ pub(super) fn parse_traverse(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlErr
     }))
 }
 
-pub(super) fn parse_neighbors(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_neighbors(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH NEIGHBORS";
-    let collection =
-        quoted_after(toks, "IN").ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
-    let node = quoted_after(toks, "OF").ok_or_else(|| missing_clause(STMT, "OF <node>"))?;
-    let edge_label = quoted_after(toks, "LABEL");
-    let direction = direction_after(toks)?;
+    let collection = cursor
+        .quoted_after("IN")
+        .ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
+    let node = cursor
+        .quoted_after("OF")
+        .ok_or_else(|| missing_clause(STMT, "OF <node>"))?;
+    let edge_label = cursor.quoted_after("LABEL");
+    let direction = cursor.direction_after("DIRECTION")?;
     Ok(NodedbStatement::Graph(GraphStmt::GraphNeighbors {
         collection,
         node,
@@ -98,14 +121,19 @@ pub(super) fn parse_neighbors(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlEr
     }))
 }
 
-pub(super) fn parse_path(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_path(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH PATH";
-    let collection =
-        quoted_after(toks, "IN").ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
-    let src = quoted_after(toks, "FROM").ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
-    let dst = quoted_after(toks, "TO").ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
-    let max_depth = usize_after_checked(toks, "MAX_DEPTH")?.unwrap_or(10);
-    let edge_label = quoted_after(toks, "LABEL");
+    let collection = cursor
+        .quoted_after("IN")
+        .ok_or_else(|| missing_clause(STMT, "IN <collection>"))?;
+    let src = cursor
+        .quoted_after("FROM")
+        .ok_or_else(|| missing_clause(STMT, "FROM <node>"))?;
+    let dst = cursor
+        .quoted_after("TO")
+        .ok_or_else(|| missing_clause(STMT, "TO <node>"))?;
+    let max_depth = cursor.usize_after_checked("MAX_DEPTH")?.unwrap_or(10);
+    let edge_label = cursor.quoted_after("LABEL");
     Ok(NodedbStatement::Graph(GraphStmt::GraphPath {
         collection,
         src,
@@ -115,24 +143,23 @@ pub(super) fn parse_path(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError>
     }))
 }
 
-pub(super) fn parse_algo(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError> {
+pub(super) fn parse_algo(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     const STMT: &str = "GRAPH ALGO";
-    let algorithm = super::helpers::find_keyword(toks, "ALGO")
-        .and_then(|i| match toks.get(i + 1)? {
-            Tok::Word(w) => Some(w.to_ascii_uppercase()),
-            _ => None,
-        })
+    let algorithm = cursor
+        .word_after("ALGO")
+        .map(|word| word.to_ascii_uppercase())
         .ok_or_else(|| missing_clause(STMT, "ALGO <algorithm>"))?;
 
     // Accept either a bare word (`ON users`) or a quoted literal (`ON 'users'`)
     // so clients can escape collection names safely.
-    let collection_raw =
-        quoted_after(toks, "ON").ok_or_else(|| missing_clause(STMT, "ON <collection>"))?;
+    let collection_raw = cursor
+        .quoted_after("ON")
+        .ok_or_else(|| missing_clause(STMT, "ON <collection>"))?;
 
     // Reject the `ON (subquery)` form: the tokenizer strips `(` and `)`, so
-    // `ON (SELECT …)` becomes `[ON, SELECT, …]` and `quoted_after("ON")`
-    // returns `"SELECT"`, which would be stored as the collection name and
-    // then ignored — producing tenant-wide results.
+    // `ON (SELECT …)` becomes `[ON, SELECT, …]` and the reader returns
+    // `"SELECT"`, which would be stored as the collection name and then
+    // ignored — producing tenant-wide results.
     const SUBQUERY_KEYWORDS: &[&str] = &["SELECT", "WITH", "VALUES", "TABLE"];
     if SUBQUERY_KEYWORDS
         .iter()
@@ -147,30 +174,90 @@ pub(super) fn parse_algo(toks: &[Tok<'_>]) -> Result<NodedbStatement, SqlError>
     Ok(NodedbStatement::Graph(GraphStmt::GraphAlgo {
         algorithm,
         collection,
-        edge_label: quoted_after(toks, "EDGE_LABEL"),
-        damping: super::helpers::float_after(toks, "DAMPING"),
-        tolerance: super::helpers::float_after(toks, "TOLERANCE"),
-        resolution: super::helpers::float_after(toks, "RESOLUTION"),
-        max_iterations: usize_after(toks, "ITERATIONS"),
-        sample_size: usize_after(toks, "SAMPLE"),
-        source_node: quoted_after(toks, "FROM").or_else(|| quoted_after(toks, "SOURCE")),
-        direction: word_after(toks, "DIRECTION"),
-        mode: word_after(toks, "MODE"),
-        personalization: super::helpers::object_after(toks, "PERSONALIZATION"),
+        edge_label: cursor.quoted_after("EDGE_LABEL"),
+        damping: cursor.float_after("DAMPING"),
+        tolerance: cursor.float_after("TOLERANCE"),
+        resolution: cursor.float_after("RESOLUTION"),
+        max_iterations: cursor.usize_after("ITERATIONS"),
+        sample_size: cursor.usize_after("SAMPLE"),
+        source_node: cursor
+            .quoted_after("FROM")
+            .or_else(|| cursor.quoted_after("SOURCE")),
+        direction: cursor.word_after("DIRECTION"),
+        mode: cursor.word_after("MODE"),
+        personalization: cursor.object_after("PERSONALIZATION"),
     }))
 }
 
 /// Parse `GRAPH RAG FUSION ON <collection> QUERY ARRAY[…] [options…]`.
 ///
-/// All fusion parameters are delegated to [`FusionParams::extract`] so
-/// every fusion SQL surface shares one typed, quote-aware extractor.
-pub(super) fn parse_rag_fusion(toks: &[Tok<'_>], sql: &str) -> Result<NodedbStatement, SqlError> {
-    let collection = word_after(toks, "ON")
-        .or_else(|| quoted_after(toks, "ON"))
+/// All fusion parameters are delegated to [`FusionParams::extract`] so every
+/// fusion SQL surface shares one typed, quote-aware extractor. That extractor
+/// reads the bracket payload from the raw text, so it claims no tokens here —
+/// the variant claims the rest, and the extractor's own validation is what
+/// refuses a malformed option.
+pub(super) fn parse_rag_fusion(
+    cursor: &mut Cursor<'_>,
+    sql: &str,
+) -> Result<NodedbStatement, SqlError> {
+    let collection = cursor
+        .word_after("ON")
+        .or_else(|| cursor.quoted_after("ON"))
         .ok_or_else(|| missing_clause("GRAPH RAG FUSION", "ON <collection>"))?;
-    let params = FusionParams::extract(toks, sql, &RAG_FUSION_KEYWORDS);
+    let params = FusionParams::extract(cursor.tokens(), sql, &RAG_FUSION_KEYWORDS);
+    cursor.consume_rest();
     Ok(NodedbStatement::Graph(GraphStmt::GraphRagFusion {
         collection,
         params,
     }))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ddl_ast::graph_parse::cursor::Cursor;
+    use crate::ddl_ast::graph_parse::tokenizer;
+
+    fn parse(sql: &str, prefix_len: usize, statement: &str) -> Result<NodedbStatement, SqlError> {
+        let mut cursor = Cursor::new(tokenizer::tokenize(sql), prefix_len);
+        let parsed = match statement {
+            "GRAPH TRAVERSE" => parse_traverse(&mut cursor),
+            "GRAPH PATH" => parse_path(&mut cursor),
+            other => panic!("unhandled test statement {other}"),
+        };
+        parsed.and_then(|stmt| cursor.finish(statement).map(|()| stmt))
+    }
+
+    #[test]
+    fn a_mistyped_keyword_fails_the_statement() {
+        let err = parse("GRAPH TRAVERSE FROM 1 DEPTS 3 IN g", 2, "GRAPH TRAVERSE")
+            .expect_err("DEPTS is not a clause");
+        assert!(err.to_string().contains("DEPTS"), "{err}");
+    }
+
+    #[test]
+    fn a_valid_statement_still_parses() {
+        let stmt = parse(
+            "GRAPH TRAVERSE FROM 1 DEPTH 3 IN g DIRECTION both",
+            2,
+            "GRAPH TRAVERSE",
+        )
+        .expect("every token belongs to a clause");
+        let NodedbStatement::Graph(GraphStmt::GraphTraverse { depth, .. }) = stmt else {
+            panic!("expected a traverse statement");
+        };
+        assert_eq!(depth, 3);
+    }
+
+    #[test]
+    fn a_stray_literal_fails_the_statement() {
+        // The statement needs its required IN clause: without it the parser
+        // correctly refuses for the missing clause before it ever reaches the
+        // stray token. With IN present, the unclaimed trailing literal is what
+        // the cursor's finish step must name.
+        let err = parse("GRAPH PATH IN g FROM 'a' TO 'b' 'stray'", 2, "GRAPH PATH")
+            .expect_err("the stray literal belongs to no clause");
+        assert!(err.to_string().contains("stray"), "{err}");
+        assert!(err.to_string().contains("unexpected token"), "{err}");
+    }
+}
diff --git a/nodedb/tests/wire/cases/graph_dsl_handlers.rs b/nodedb/tests/wire/cases/graph_dsl_handlers.rs
index 47041f072..69c1952c7 100644
--- a/nodedb/tests/wire/cases/graph_dsl_handlers.rs
+++ b/nodedb/tests/wire/cases/graph_dsl_handlers.rs
@@ -448,3 +448,39 @@ async fn graph_traverse_node_id_containing_keyword_substring() {
         "traversal must reach 'b'; substring 'DEPTH' in src id must not be parsed as DEPTH keyword; got: {blob}"
     );
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn graph_traverse_rejects_a_mistyped_clause_keyword() {
+    let server = TestServer::start().await;
+    server.exec("CREATE COLLECTION mistyped").await.unwrap();
+    server
+        .exec("GRAPH INSERT EDGE IN 'mistyped' FROM '1' TO '2' TYPE 'l'")
+        .await
+        .unwrap();
+
+    // `DEPTS` is not a clause. Seeking for DEPTH, finding none, and defaulting
+    // the depth left `DEPTS 3` unread: the statement answered a different
+    // question than it asked, and reported success.
+    server
+        .expect_error(
+            "GRAPH TRAVERSE IN 'mistyped' FROM '1' DEPTS 3 LABEL 'l'",
+            "42601",
+        )
+        .await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn graph_path_rejects_a_stray_literal() {
+    let server = TestServer::start().await;
+    server.exec("CREATE COLLECTION strays").await.unwrap();
+    server
+        .exec("GRAPH INSERT EDGE IN 'strays' FROM 'a' TO 'b' TYPE 'l'")
+        .await
+        .unwrap();
+
+    // The trailing literal belongs to no clause. Ignoring it accepted a
+    // statement whose text does not mean what it parses to.
+    server
+        .expect_error("GRAPH PATH IN 'strays' FROM 'a' TO 'b' 'stray'", "42601")
+        .await;
+}

From ddf5394be2531ba08379f76a2d7093ec1fbb8cb2 Mon Sep 17 00:00:00 2001
From: EnRaiha <15997552+EnRaiha@users.noreply.github.com>
Date: Wed, 16 Sep 2026 21:25:57 +0800
Subject: [PATCH 2/2] fix(sql): read fusion options through a claim-tracking
 cursor

Fusion parameters were read from a raw token slice and the variant then
claimed every remaining token, so a mistyped option keyword ran the
statement with a default and no error. The shared extractor now reads
through the cursor: each keyword and value is claimed, the ARRAY[...]
payload is claimed element by element, and a token no clause owns is
refused by name. A present-but-unreadable value is an error, never a
default.

- drop the raw-text readers; the ARRAY payload and the RRF_K count come
  from the same token stream
- the BM25 field's ON is read after the BM25 anchor: ON also introduces
  the collection, and the first match is not the field's
- the wrapped SEARCH ... USING FUSION(...) surface validates with the
  same extractor and refuses unclaimed tokens
---
 nodedb-sql/src/ddl_ast/graph_parse/cursor.rs  | 119 ++++++++++----
 nodedb-sql/src/ddl_ast/graph_parse/entry.rs   |  26 +++-
 .../src/ddl_ast/graph_parse/fusion_params.rs  | 145 ++++++++++++------
 nodedb-sql/src/ddl_ast/graph_parse/helpers.rs |  99 +-----------
 .../src/ddl_ast/graph_parse/variants.rs       |  16 +-
 .../shared/ddl/neutral/dsl/search_fusion.rs   |   8 +-
 nodedb/tests/wire/cases/graph_rag_fusion.rs   |  42 ++++-
 7 files changed, 269 insertions(+), 186 deletions(-)

diff --git a/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs b/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs
index 3b6bcb775..4a1302b16 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/cursor.rs
@@ -69,6 +69,22 @@ impl<'a> Cursor<'a> {
         self.claim_text(pos + 1)
     }
 
+    /// The word or quoted literal after `keyword`, searching only at or after
+    /// the first `anchor` token. Used where one keyword introduces two clauses,
+    /// as `ON` does for `ON <collection>` and `BM25 <text> ON <field>`.
+    pub(super) fn quoted_after_from(&mut self, anchor: &str, keyword: &str) -> Option<String> {
+        let anchor_pos = self
+            .toks
+            .iter()
+            .position(|tok| Self::is_keyword(tok, anchor))?;
+        let offset = self.toks[anchor_pos..]
+            .iter()
+            .position(|tok| Self::is_keyword(tok, keyword))?;
+        let pos = anchor_pos + offset;
+        self.used[pos] = true;
+        self.claim_text(pos + 1)
+    }
+
     /// Every consecutive word or quoted literal after `keyword`, up to the
     /// first token that is neither. Used by `AS <label> [, <label>…]`.
     pub(super) fn quoted_list_after(&mut self, keyword: &str) -> Vec<String> {
@@ -119,18 +135,68 @@ impl<'a> Cursor<'a> {
     }
 
     /// The next `count` float words after `keyword`.
-    pub(super) fn floats_after<const N: usize>(&mut self, keyword: &str) -> Option<[f64; N]> {
-        let pos = self.find(keyword)?;
-        let mut out = [0.0f64; N];
-        for (offset, slot) in out.iter_mut().enumerate() {
-            let value = match self.toks.get(pos + 1 + offset)? {
-                Tok::Word(w) => w.parse::<f64>().ok()?,
-                _ => return None,
+    pub(super) fn floats_after_max(
+        &mut self,
+        keyword: &str,
+        max: usize,
+    ) -> Result<Option<Vec<f64>>, SqlError> {
+        let Some(pos) = self.find(keyword) else {
+            return Ok(None);
+        };
+        let mut out = Vec::new();
+        let mut at = pos + 1;
+        while out.len() < max {
+            match self.toks.get(at) {
+                Some(Tok::Word(w)) => match w.parse::<f64>() {
+                    Ok(value) => {
+                        self.used[at] = true;
+                        out.push(value);
+                        at += 1;
+                    }
+                    Err(_) => break,
+                },
+                _ => break,
+            }
+        }
+        if out.is_empty() {
+            let found = match self.toks.get(pos + 1) {
+                Some(Tok::Word(w)) => (*w).to_string(),
+                Some(Tok::Quoted(s)) => format!("'{s}'"),
+                Some(Tok::Object(_)) => "{…}".to_string(),
+                None => "nothing".to_string(),
             };
-            self.used[pos + 1 + offset] = true;
-            *slot = value;
+            return Err(SqlError::Parse {
+                detail: format!("{keyword} expects numbers — found {found}"),
+            });
+        }
+        Ok(Some(out))
+    }
+
+    /// The `ARRAY[f1, f2, …]` payload after `anchor`, claiming the anchor, the
+    /// `ARRAY` word, and every numeric element. The tokenizer drops the
+    /// brackets, so the element run ends at the first non-numeric token (the
+    /// next clause keyword).
+    pub(super) fn floats_array_after(&mut self, anchor: &str) -> Option<Vec<f64>> {
+        let pos = self.find(anchor)?;
+        let mut at = pos + 1;
+        if let Some(Tok::Word(w)) = self.toks.get(at)
+            && w.eq_ignore_ascii_case("ARRAY")
+        {
+            self.used[at] = true;
+            at += 1;
         }
-        Some(out)
+        let mut out = Vec::new();
+        while let Some(Tok::Word(w)) = self.toks.get(at) {
+            match w.parse::<f64>() {
+                Ok(value) => {
+                    self.used[at] = true;
+                    out.push(value);
+                    at += 1;
+                }
+                Err(_) => break,
+            }
+        }
+        if out.is_empty() { None } else { Some(out) }
     }
 
     /// Read a `DIRECTION` clause.
@@ -188,23 +254,6 @@ impl<'a> Cursor<'a> {
         }
     }
 
-    /// The token slice, for readers that validate their own span (fusion
-    /// parameters read the bracket payload from the raw statement text).
-    pub(super) fn tokens(&self) -> &[Tok<'a>] {
-        &self.toks
-    }
-
-    /// Claim every remaining token.
-    ///
-    /// For a statement whose parameters a dedicated extractor validated
-    /// (`GRAPH RAG FUSION`), where this cursor's clause readers do not see the
-    /// bracket payload the extractor reads from the raw text.
-    pub(super) fn consume_rest(&mut self) {
-        for slot in self.used.iter_mut() {
-            *slot = true;
-        }
-    }
-
     /// Refuse the first token no clause claimed.
     pub(super) fn finish(self, statement: &str) -> Result<(), SqlError> {
         for (tok, used) in self.toks.iter().zip(self.used.iter()) {
@@ -271,9 +320,23 @@ mod tests {
         let toks = tokenize("GRAPH RAG FUSION ON g RRF_K (60.0, 35.0)");
         let mut cursor = Cursor::new(toks, 3);
         assert_eq!(cursor.word_after("ON").as_deref(), Some("g"));
-        assert_eq!(cursor.floats_after::<2>("RRF_K"), Some([60.0, 35.0]));
+        assert_eq!(
+            cursor.floats_after_max("RRF_K", 3).unwrap(),
+            Some(vec![60.0, 35.0])
+        );
         cursor
             .finish("GRAPH RAG FUSION")
             .expect("every token claimed");
     }
+
+    #[test]
+    fn a_mistyped_float_value_is_refused() {
+        let toks = tokenize("GRAPH RAG FUSION ON g RRF_K (fast)");
+        let mut cursor = Cursor::new(toks, 3);
+        let err = cursor.floats_after_max("RRF_K", 3).unwrap_err();
+        assert!(
+            err.to_string().contains("RRF_K"),
+            "the error must name the clause: {err}"
+        );
+    }
 }
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/entry.rs b/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
index cc138dd02..c4831c6df 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/entry.rs
@@ -55,9 +55,7 @@ pub fn try_parse(sql: &str) -> Option<Result<NodedbStatement, SqlError>> {
     } else if upper.starts_with("GRAPH ALGO ") {
         run(toks, 2, "GRAPH ALGO", variants::parse_algo)
     } else if upper.starts_with("GRAPH RAG FUSION ") {
-        run(toks, 3, "GRAPH RAG FUSION", |cursor| {
-            variants::parse_rag_fusion(cursor, trimmed)
-        })
+        run(toks, 3, "GRAPH RAG FUSION", variants::parse_rag_fusion)
     } else {
         // Starts with `GRAPH ` but names no known command. Still graph DSL,
         // so report it here rather than letting the SQL parser guess.
@@ -382,6 +380,28 @@ mod tests {
         }
     }
 
+    /// `ON` introduces both the fusion collection and the BM25 field. The field
+    /// read must anchor on `BM25`, or the collection name is captured as the
+    /// field and the real `ON` is left unclaimed.
+    #[test]
+    fn parse_rag_fusion_three_source_reads_the_bm25_field() {
+        let stmt = parsed(
+            "GRAPH RAG FUSION ON ents \
+             QUERY ARRAY[0.1] \
+             VECTOR_TOP_K 5 \
+             BM25 'attention' ON 'body' \
+             RRF_K (60.0, 35.0, 50.0)",
+        );
+        match stmt {
+            NodedbStatement::Graph(GraphStmt::GraphRagFusion { params, .. }) => {
+                assert_eq!(params.bm25_query.as_deref(), Some("attention"));
+                assert_eq!(params.bm25_field.as_deref(), Some("body"));
+                assert_eq!(params.rrf_k_triple, Some((60.0, 35.0, 50.0)));
+            }
+            other => panic!("expected GraphRagFusion, got {other:?}"),
+        }
+    }
+
     #[test]
     fn parse_rag_fusion_missing_collection_names_the_clause() {
         let error = try_parse("GRAPH RAG FUSION QUERY ARRAY[0.1] VECTOR_TOP_K 5")
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/fusion_params.rs b/nodedb-sql/src/ddl_ast/graph_parse/fusion_params.rs
index f2f237675..3dbe891c1 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/fusion_params.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/fusion_params.rs
@@ -15,10 +15,9 @@
 //! parsing did.
 
 use super::super::statement::GraphDirection;
-use super::helpers::{
-    array_floats_after, float_pair_after, float_triple_after, quoted_after, usize_after, word_after,
-};
+use super::cursor::Cursor;
 use super::tokenizer::{Tok, tokenize};
+use crate::error::SqlError;
 
 /// Keyword aliases for the shared fusion parameters.
 ///
@@ -108,64 +107,88 @@ pub struct FusionParams {
 }
 
 impl FusionParams {
-    pub(super) fn extract(toks: &[Tok<'_>], sql: &str, kw: &FusionKeywords) -> Self {
-        let direction = match word_after(toks, kw.direction)
-            .as_deref()
-            .map(str::to_ascii_uppercase)
-            .as_deref()
-        {
-            Some("IN") => Some(GraphDirection::In),
-            Some("BOTH") => Some(GraphDirection::Both),
-            Some("OUT") => Some(GraphDirection::Out),
-            _ => None,
+    /// Read every fusion parameter through the cursor, so each keyword and value
+    /// is claimed and a token no clause owns is left for `Cursor::finish` to
+    /// refuse. A clause that is present but unreadable is an error, never a
+    /// silent default.
+    pub(super) fn extract(cursor: &mut Cursor<'_>, kw: &FusionKeywords) -> Result<Self, SqlError> {
+        let direction = match cursor.word_after(kw.direction) {
+            None => None,
+            Some(word) => match word.to_ascii_uppercase().as_str() {
+                "IN" => Some(GraphDirection::In),
+                "BOTH" => Some(GraphDirection::Both),
+                "OUT" => Some(GraphDirection::Out),
+                _ => {
+                    return Err(SqlError::Parse {
+                        detail: format!(
+                            "{} must be one of in, out, both — found '{word}'",
+                            kw.direction
+                        ),
+                    });
+                }
+            },
         };
 
-        // Try to parse a three-value RRF_K triple first; fall back to the
-        // two-value pair. This way `RRF_K (60.0, 35.0, 50.0)` populates
-        // `rrf_k_triple` and leaves `rrf_k` as None, while the legacy
-        // `RRF_K (60.0, 35.0)` continues to populate only `rrf_k`.
-        let rrf_k_triple = float_triple_after(toks, kw.rrf_k);
-        let rrf_k = if rrf_k_triple.is_some() {
-            None
-        } else {
-            float_pair_after(toks, kw.rrf_k)
+        // Three values form the RRF_K triple; two form the legacy pair. Any
+        // other count is a typo, not a default.
+        let rrf = cursor.floats_after_max(kw.rrf_k, 3)?;
+        let (rrf_k, rrf_k_triple) = match rrf.as_deref() {
+            None => (None, None),
+            Some([a, b]) => (Some((*a, *b)), None),
+            Some([a, b, c]) => (None, Some((*a, *b, *c))),
+            Some(other) => {
+                return Err(SqlError::Parse {
+                    detail: format!(
+                        "{} expects two or three numbers — found {}",
+                        kw.rrf_k,
+                        other.len()
+                    ),
+                });
+            }
         };
 
-        // BM25 text leg — only parsed when the keyword is non-empty.
+        // BM25 text leg — only parsed when the keyword is non-empty. The field
+        // keyword (`ON`) is read after the BM25 anchor: `ON` also introduces
+        // the fusion collection, and the first match is not the field's.
         let (bm25_query, bm25_field) = if !kw.bm25_query.is_empty() {
             (
-                quoted_after(toks, kw.bm25_query),
-                quoted_after(toks, kw.bm25_field),
+                cursor.quoted_after(kw.bm25_query),
+                cursor.quoted_after_from(kw.bm25_query, kw.bm25_field),
             )
         } else {
             (None, None)
         };
 
-        Self {
-            query_vector: array_floats_after(sql, kw.query_anchor),
-            vector_top_k: usize_after(toks, kw.vector_top_k),
-            expansion_depth: usize_after(toks, kw.expansion_depth),
-            edge_label: quoted_after(toks, kw.edge_label),
-            final_top_k: usize_after(toks, kw.final_top_k),
+        let query_vector = cursor
+            .floats_array_after(kw.query_anchor)
+            .map(|floats| floats.into_iter().map(|f| f as f32).collect());
+
+        Ok(Self {
+            query_vector,
+            vector_top_k: cursor.usize_after_checked(kw.vector_top_k)?,
+            expansion_depth: cursor.usize_after_checked(kw.expansion_depth)?,
+            edge_label: cursor.quoted_after(kw.edge_label),
+            final_top_k: cursor.usize_after_checked(kw.final_top_k)?,
             rrf_k,
             rrf_k_triple,
-            vector_field: quoted_after(toks, kw.vector_field),
+            vector_field: cursor.quoted_after(kw.vector_field),
             direction,
-            max_visited: usize_after(toks, kw.max_visited),
+            max_visited: cursor.usize_after_checked(kw.max_visited)?,
             bm25_query,
             bm25_field,
-        }
+        })
     }
 }
 
 /// Parse `SEARCH <collection> USING FUSION(...)` into its collection name
-/// and a typed [`FusionParams`]. Returns `None` when the SQL does not
-/// match the expected shape.
+/// and a typed [`FusionParams`]. Returns `Ok(None)` when the SQL does not
+/// match the expected shape; a matched shape whose options are unreadable is
+/// an error, never a silent default.
 ///
 /// Body extraction uses the same quote- and bracket-aware tokenizer as
 /// the `GRAPH RAG FUSION` path, so a keyword-shaped string literal (e.g.
 /// a label value `'TOP'`) cannot shadow a real parameter keyword.
-pub fn parse_search_using_fusion(sql: &str) -> Option<(String, FusionParams)> {
+pub fn parse_search_using_fusion(sql: &str) -> Result<Option<(String, FusionParams)>, SqlError> {
     let toks = tokenize(sql);
     let collection = match toks.as_slice() {
         [Tok::Word(s), Tok::Word(c), Tok::Word(u), Tok::Word(f), ..]
@@ -175,12 +198,12 @@ pub fn parse_search_using_fusion(sql: &str) -> Option<(String, FusionParams)> {
         {
             (*c).to_string()
         }
-        _ => return None,
+        _ => return Ok(None),
     };
-    Some((
-        collection,
-        FusionParams::extract(&toks, sql, &SEARCH_FUSION_KEYWORDS),
-    ))
+    let mut cursor = Cursor::new(toks, 4);
+    let params = FusionParams::extract(&mut cursor, &SEARCH_FUSION_KEYWORDS)?;
+    cursor.finish("SEARCH ... USING FUSION")?;
+    Ok(Some((collection, params)))
 }
 
 #[cfg(test)]
@@ -193,6 +216,7 @@ mod tests {
             "SEARCH mycol USING FUSION(ARRAY[0.1, 0.2] VECTOR_TOP_K 5 DEPTH 2 \
              LABEL 'related' TOP 10 RRF_K (60.0, 35.0))",
         )
+        .unwrap()
         .unwrap();
         assert_eq!(col, "mycol");
         assert_eq!(p.query_vector.as_deref().map(<[f32]>::len), Some(2));
@@ -211,6 +235,7 @@ mod tests {
              VECTOR_TOP_K 50 BM25 'transformer attention' ON 'body' \
              DEPTH 2 LABEL 'related_to' TOP 10 RRF_K (60.0, 35.0, 50.0))",
         )
+        .unwrap()
         .unwrap();
         assert_eq!(col, "entities");
         assert_eq!(p.rrf_k, None);
@@ -229,6 +254,7 @@ mod tests {
         // quoted strings whole, so `TOP 10` is the real parameter.
         let (_, p) =
             parse_search_using_fusion("SEARCH c USING FUSION(ARRAY[0.5] LABEL 'TOP_SECRET' TOP 7)")
+                .unwrap()
                 .unwrap();
         assert_eq!(p.edge_label.as_deref(), Some("TOP_SECRET"));
         assert_eq!(p.final_top_k, Some(7));
@@ -236,7 +262,38 @@ mod tests {
 
     #[test]
     fn search_fusion_rejects_wrong_prefix() {
-        assert!(parse_search_using_fusion("INSERT INTO x VALUES (1)").is_none());
-        assert!(parse_search_using_fusion("SEARCH x USING VECTOR(ARRAY[1.0])").is_none());
+        assert!(
+            parse_search_using_fusion("INSERT INTO x VALUES (1)")
+                .unwrap()
+                .is_none()
+        );
+        assert!(
+            parse_search_using_fusion("SEARCH x USING VECTOR(ARRAY[1.0])")
+                .unwrap()
+                .is_none()
+        );
+    }
+
+    /// A mistyped option keyword belongs to no clause; the cursor refuses it by
+    /// name instead of running the statement with a default.
+    #[test]
+    fn search_fusion_refuses_a_mistyped_option_keyword() {
+        let err = parse_search_using_fusion("SEARCH c USING FUSION(ARRAY[0.5] VECTOR_TOPK 5)")
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("VECTOR_TOPK"),
+            "the error must name the unclaimed token: {err}"
+        );
+    }
+
+    /// A value the clause cannot read is an error, never a silent default.
+    #[test]
+    fn search_fusion_refuses_an_unreadable_option_value() {
+        let err = parse_search_using_fusion("SEARCH c USING FUSION(ARRAY[0.5] VECTOR_TOP_K abc)")
+            .unwrap_err();
+        assert!(
+            err.to_string().contains("VECTOR_TOP_K"),
+            "the error must name the clause: {err}"
+        );
     }
 }
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs b/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
index 7a9f0db59..32cd682f0 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/helpers.rs
@@ -1,78 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 
-use super::tokenizer::Tok;
-use crate::error::SqlError;
-
-pub(super) fn find_keyword(toks: &[Tok<'_>], keyword: &str) -> Option<usize> {
-    toks.iter()
-        .position(|t| matches!(t, Tok::Word(w) if w.eq_ignore_ascii_case(keyword)))
-}
-
-pub(super) fn quoted_after(toks: &[Tok<'_>], keyword: &str) -> Option<String> {
-    let pos = find_keyword(toks, keyword)?;
-    match toks.get(pos + 1)? {
-        Tok::Quoted(s) => Some(s.clone().into_owned()),
-        Tok::Word(w) => Some((*w).to_string()),
-        Tok::Object(_) => None,
-    }
-}
-
-/// Extract a brace-balanced object literal (`{…}`, braces included) that
-/// immediately follows `keyword`. Used for `PERSONALIZATION {…}` in
-/// `GRAPH ALGO`. Returns `None` when the keyword is absent or is not followed
-/// by an object token.
-pub(super) fn word_after(toks: &[Tok<'_>], keyword: &str) -> Option<String> {
-    let pos = find_keyword(toks, keyword)?;
-    if let Tok::Word(w) = toks.get(pos + 1)? {
-        Some((*w).to_string())
-    } else {
-        None
-    }
-}
+//! Shared helpers for the graph DSL parsers.
 
-pub(super) fn usize_after(toks: &[Tok<'_>], keyword: &str) -> Option<usize> {
-    word_after(toks, keyword)?.parse().ok()
-}
-
-/// Extract the two consecutive float tokens that follow `keyword`.
-///
-/// The tokenizer strips `(` and `)`, so `RRF_K (60.0, 35.0)` becomes the
-/// token sequence `[Word("RRF_K"), Word("60.0"), Word("35.0")]`. This helper
-/// reads both values without requiring the caller to know about that stripping.
-pub(super) fn float_pair_after(toks: &[Tok<'_>], keyword: &str) -> Option<(f64, f64)> {
-    let pos = find_keyword(toks, keyword)?;
-    let k1 = match toks.get(pos + 1)? {
-        Tok::Word(w) => w.parse::<f64>().ok()?,
-        _ => return None,
-    };
-    let k2 = match toks.get(pos + 2)? {
-        Tok::Word(w) => w.parse::<f64>().ok()?,
-        _ => return None,
-    };
-    Some((k1, k2))
-}
-
-/// Extract three consecutive float tokens that follow `keyword`.
-///
-/// The tokenizer strips `(` and `)`, so `RRF_K (60.0, 35.0, 50.0)` becomes
-/// `[Word("RRF_K"), Word("60.0"), Word("35.0"), Word("50.0")]`. Returns `None`
-/// if fewer than three float tokens follow the keyword.
-pub(super) fn float_triple_after(toks: &[Tok<'_>], keyword: &str) -> Option<(f64, f64, f64)> {
-    let pos = find_keyword(toks, keyword)?;
-    let k1 = match toks.get(pos + 1)? {
-        Tok::Word(w) => w.parse::<f64>().ok()?,
-        _ => return None,
-    };
-    let k2 = match toks.get(pos + 2)? {
-        Tok::Word(w) => w.parse::<f64>().ok()?,
-        _ => return None,
-    };
-    let k3 = match toks.get(pos + 3)? {
-        Tok::Word(w) => w.parse::<f64>().ok()?,
-        _ => return None,
-    };
-    Some((k1, k2, k3))
-}
+use crate::error::SqlError;
 
 /// A required clause was absent.
 pub(super) fn missing_clause(statement: &str, clause: &str) -> SqlError {
@@ -80,28 +10,3 @@ pub(super) fn missing_clause(statement: &str, clause: &str) -> SqlError {
         detail: format!("{statement} requires {clause}"),
     }
 }
-
-/// Extract `ARRAY[f1, f2, …]` that appears after `keyword` in raw SQL.
-///
-/// Used for `QUERY ARRAY[…]` in `GRAPH RAG FUSION` where the vector payload
-/// cannot be tokenized as keyword-value pairs. Searches for the first `[`
-/// after the keyword and collects comma-separated f32 values up to `]`.
-pub(super) fn array_floats_after(sql: &str, keyword: &str) -> Option<Vec<f32>> {
-    let upper = sql.to_ascii_uppercase();
-    let kw_pos = upper.find(keyword)?;
-    let after_kw = &sql[kw_pos + keyword.len()..];
-    let bracket_start = after_kw.find('[').map(|i| i + 1)?;
-    let bracket_end = after_kw[bracket_start..]
-        .find(']')
-        .map(|i| i + bracket_start)?;
-    let content = &after_kw[bracket_start..bracket_end];
-    let floats: Vec<f32> = content
-        .split(',')
-        .filter_map(|s| s.trim().parse::<f32>().ok())
-        .collect();
-    if floats.is_empty() {
-        None
-    } else {
-        Some(floats)
-    }
-}
diff --git a/nodedb-sql/src/ddl_ast/graph_parse/variants.rs b/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
index 917128bf8..6acc2aa54 100644
--- a/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
+++ b/nodedb-sql/src/ddl_ast/graph_parse/variants.rs
@@ -192,20 +192,16 @@ pub(super) fn parse_algo(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, Sql
 /// Parse `GRAPH RAG FUSION ON <collection> QUERY ARRAY[…] [options…]`.
 ///
 /// All fusion parameters are delegated to [`FusionParams::extract`] so every
-/// fusion SQL surface shares one typed, quote-aware extractor. That extractor
-/// reads the bracket payload from the raw text, so it claims no tokens here —
-/// the variant claims the rest, and the extractor's own validation is what
-/// refuses a malformed option.
-pub(super) fn parse_rag_fusion(
-    cursor: &mut Cursor<'_>,
-    sql: &str,
-) -> Result<NodedbStatement, SqlError> {
+/// fusion SQL surface shares one typed, quote-aware extractor. The extractor
+/// reads its options through the cursor, so every keyword and value is claimed
+/// here and a token no clause owns is left for the dispatcher's `finish` to
+/// refuse by name.
+pub(super) fn parse_rag_fusion(cursor: &mut Cursor<'_>) -> Result<NodedbStatement, SqlError> {
     let collection = cursor
         .word_after("ON")
         .or_else(|| cursor.quoted_after("ON"))
         .ok_or_else(|| missing_clause("GRAPH RAG FUSION", "ON <collection>"))?;
-    let params = FusionParams::extract(cursor.tokens(), sql, &RAG_FUSION_KEYWORDS);
-    cursor.consume_rest();
+    let params = FusionParams::extract(cursor, &RAG_FUSION_KEYWORDS)?;
     Ok(NodedbStatement::Graph(GraphStmt::GraphRagFusion {
         collection,
         params,
diff --git a/nodedb/src/control/server/shared/ddl/neutral/dsl/search_fusion.rs b/nodedb/src/control/server/shared/ddl/neutral/dsl/search_fusion.rs
index 334767513..843cf73f2 100644
--- a/nodedb/src/control/server/shared/ddl/neutral/dsl/search_fusion.rs
+++ b/nodedb/src/control/server/shared/ddl/neutral/dsl/search_fusion.rs
@@ -25,7 +25,13 @@ pub async fn search_fusion(
     database_id: DatabaseId,
     sql: &str,
 ) -> Result<Vec<DdlResult>, DdlError> {
-    let (collection, params) = parse_search_using_fusion(sql).ok_or_else(|| {
+    let parsed = parse_search_using_fusion(sql).map_err(|e| {
+        ddl_err(
+            "42601",
+            format!("SEARCH <collection> USING FUSION(...): {e}"),
+        )
+    })?;
+    let (collection, params) = parsed.ok_or_else(|| {
         ddl_err(
             "42601",
             "syntax: SEARCH <collection> USING FUSION(ARRAY[...] ...)",
diff --git a/nodedb/tests/wire/cases/graph_rag_fusion.rs b/nodedb/tests/wire/cases/graph_rag_fusion.rs
index cc25a4309..071de2c20 100644
--- a/nodedb/tests/wire/cases/graph_rag_fusion.rs
+++ b/nodedb/tests/wire/cases/graph_rag_fusion.rs
@@ -56,9 +56,9 @@ async fn graph_rag_fusion_rrf_k_pair_is_accepted() {
     server.exec("CREATE COLLECTION ragf_rrfk").await.unwrap();
 
     // The tokenizer strips `(` and `)`, collapsing `RRF_K (60.0, 35.0)` to
-    // three consecutive tokens. Without a dedicated `float_pair_after` helper
-    // the second value (graph_k = 35.0) is silently dropped and the default
-    // (10.0) used. The statement must not error on the pair syntax.
+    // three consecutive tokens. A reader that stops at the first value drops
+    // the second (graph_k = 35.0) and the default applies. The statement must
+    // not error on the pair syntax.
     let result = server
         .query_text(
             "GRAPH RAG FUSION ON ragf_rrfk \
@@ -431,3 +431,39 @@ async fn vector_and_text_hits_on_one_row_fuse_into_a_single_entry() {
          more than one means the legs keyed the same row differently: {blob}"
     );
 }
+
+// ── Mistyped fusion options are refused, never defaulted ─────────────────────
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn graph_rag_fusion_rejects_a_mistyped_option_keyword() {
+    let server = TestServer::start().await;
+    server.exec("CREATE COLLECTION ragf_typo").await.unwrap();
+
+    // `VECTOR_TOPK` is not a clause. Seeking `VECTOR_TOP_K`, finding none, and
+    // defaulting the cap left `VECTOR_TOPK 5` unread: the statement ran with a
+    // cap the text did not ask for, and reported success.
+    server
+        .expect_error(
+            "GRAPH RAG FUSION ON ragf_typo QUERY ARRAY[0.1, 0.2] VECTOR_TOPK 5",
+            "VECTOR_TOPK",
+        )
+        .await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn graph_rag_fusion_rejects_an_unreadable_option_value() {
+    let server = TestServer::start().await;
+    server
+        .exec("CREATE COLLECTION ragf_bad_value")
+        .await
+        .unwrap();
+
+    // The clause is present but its value is not a number: a silent default
+    // would answer a different question than the text asks.
+    server
+        .expect_error(
+            "GRAPH RAG FUSION ON ragf_bad_value QUERY ARRAY[0.1, 0.2] VECTOR_TOP_K five",
+            "VECTOR_TOP_K",
+        )
+        .await;
+}