docs(kernel): preserve SQL transfer guard explanations

Signed-off-by: Aakash Saravanan <aakash.saravanan@databricks.com>

Author: aakash-saravanan-db

src/databricks/sql/backend/kernel/client.py

@@ -73,30 +73,42 @@
 _KERNEL_MANAGED_HEADERS = frozenset({"authorization", "x-databricks-org-id"})
 
 
+# Leading verbs of SQL volume/staging statements. Detected by the
+# leading token (case-insensitive) so the kernel backend can fail loud
+# on staging ops it can't service — see ``execute_command``.
+_STAGING_VERBS = ("PUT", "GET", "REMOVE")
+
+
 def _strip_leading_sql_comments(sql: str) -> str:
-    """Skip SQL comments so unsupported transfers cannot appear successful."""
+    """Strip leading whitespace and SQL comments (``-- …`` line and
+    ``/* … */`` block, possibly several) from ``sql``, returning the
+    remainder.
+
+    Needed so staging detection sees the real leading verb: a
+    comment-prefixed staging op (``-- upload\\nPUT …`` or
+    ``/* c */ PUT …``, common in ETL scripts) must still be classified
+    as staging, or it would slip past the guard into the silent-no-op
+    bug. Block comments do not nest in Databricks SQL, so a simple
+    scan-to-``*/`` is correct.
+    """
     i = 0
     n = len(sql)
     while i < n:
         if sql[i].isspace():
             i += 1
         elif sql.startswith("--", i):
+            # Line comment: skip to end of line (or string).
             nl = sql.find("\n", i)
             i = n if nl == -1 else nl + 1
         elif sql.startswith("/*", i):
+            # Block comment: skip to closing */ (or end if unterminated).
             close = sql.find("*/", i + 2)
             i = n if close == -1 else close + 2
         else:
             break
     return sql[i:]
 
 
-def _is_staging_statement(operation: str) -> bool:
-    stripped = _strip_leading_sql_comments(operation)
-    verb = stripped.split(None, 1)[0].upper() if stripped.strip() else ""
-    return verb in ("PUT", "GET", "REMOVE")
-
-
 def _is_not_found(exc: BaseException) -> bool:
     """True iff ``exc`` is a kernel ``NotFound`` error (HTTP 404 /
     ``STATEMENT_NOT_FOUND``).
@@ -132,6 +144,21 @@ def _catalog_or_none(value: Optional[str]) -> Optional[str]:
     return value
 
 
+def _is_staging_statement(operation: str) -> bool:
+    """True iff ``operation`` is a volume/staging statement (PUT / GET /
+    REMOVE).
+
+    Strips leading whitespace + SQL comments first (so a comment-
+    prefixed staging op is still caught), then matches the leading token
+    only — so a normal query that merely *contains* the word (e.g.
+    ``SELECT 'GET' AS x``) isn't misflagged.
+    """
+    stripped = _strip_leading_sql_comments(operation)
+    # First whitespace-delimited token, uppercased.
+    verb = stripped.split(None, 1)[0].upper() if stripped.strip() else ""
+    return verb in _STAGING_VERBS
+
+
 def _kernel_session_accepts_kwarg(name: str) -> bool:
     """True iff the installed ``databricks_sql_kernel.Session`` constructor
     declares keyword ``name``.