refactor: extract CQL into feature/cql (part of #778)

Extract the CQL (Cassandra interface) statement family out of core
internal/mycli into internal/mycli/feature/cql through the Feature seam:
the statement, the #757 fail-closed first-keyword classifier (byte-identical),
the Cassandra type-name formatter, and the lazy adapter session (build-once,
now mutex-guarded, closed via the feature store) all move; core no longer
imports gocql or go-spanner-cassandra (verified via go list -deps; the root
main still does via feature/all). CQL stays NOT detached-compatible.

feature/all registers (cql, bigquery), keeping the merged statement order
LLM, CQL, BIGQUERY - README and docs/system_variables.md are byte-identical.

READONLY coverage preserved or improved: mutating CQL is blocked through the
real dispatch path with the READONLY sentinel; the allowed SELECT and the
mutating DELETE are classification-asserted on DISPATCH-BUILT statements
(review nit), so a HandleGroups regression returning a zero-value statement
fails tests instead of silently blocking CQL SELECT under READONLY. The
allowed path deliberately stops before Execute: spancql.NewCluster panics
when the adapter cannot be built (pre-existing upstream behavior, recorded
as a follow-up candidate).

Reviewed: maintainer APPROVE-WITH-NIT (nit addressed in-review); independent
adversarial review SAFE TO MERGE (classifier/Execute equivalence verified,
one unobservable failure-retry nuance recorded); Gemini INFO. CI green.

Author: apstndb

internal/mycli/client_side_statement_def.go

@@ -1191,10 +1191,11 @@ var clientSideStatementDefs = []*clientSideStatementDef{
 			return &ExitStatement{}, nil
 		},
 	},
-	// The optional statement families (GEMINI/CQL) sit at the end of the table.
-	// BIGQUERY was extracted into internal/mycli/feature/bigquery (#778); the
-	// remaining families follow in PR2/PR3. Feature-contributed defs are appended
-	// after this core table in feature/all.All() order (llm, cql, bigquery).
+	// The optional statement family GEMINI/LLM sits at the end of the table.
+	// BIGQUERY (#778) and CQL (#778) were extracted into internal/mycli/feature/
+	// {bigquery,cql}; GEMINI/LLM follows in PR3. Feature-contributed defs are
+	// appended after this core table in feature/all.All() order (llm, cql,
+	// bigquery).
 	// LLM
 	{
 		Descriptions: []clientSideStatementDescription{
@@ -1209,20 +1210,6 @@ var clientSideStatementDefs = []*clientSideStatementDef{
 			return &GeminiStatement{Text: unquoteString(groups["text"])}, nil
 		},
 	},
-	// Cassandra interface
-	{
-		Descriptions: []clientSideStatementDescription{
-			{
-				Usage:  `Execute CQL`,
-				Syntax: `CQL ...`,
-				Note:   "EARLY EXPERIMENTAL",
-			},
-		},
-		Pattern: regexp.MustCompile(`(?is)^CQL\s+(?P<cql>.+)$`),
-		HandleGroups: func(groups map[string]string) (Statement, error) {
-			return &CQLStatement{CQL: groups["cql"]}, nil
-		},
-	},
 }
 
 // Helper functions for HandleGroups implementations

internal/mycli/cql_readonly_guard_test.go

@@ -0,0 +1,102 @@
+// Copyright 2026 apstndb
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package mycli_test
+
+// Dispatch-level READONLY guard regression for the extracted CQL family (#757,
+// re-homed by #778). These live in the external mycli_test package so they can
+// import feature/cql (which imports mycli) without a cycle, and prove the guard
+// fires through the real dispatch path: build the statement from the merged def
+// table exactly as production does, then execute it against a READONLY session.
+
+import (
+	"testing"
+
+	"github.com/apstndb/spanner-mycli/internal/mycli"
+	"github.com/apstndb/spanner-mycli/internal/mycli/feature/cql"
+)
+
+func buildCQL(t *testing.T, cqlText string) mycli.Statement {
+	t.Helper()
+	defs := mycli.MergedStatementDefs(cql.Feature())
+	stmt, err := mycli.BuildStatementWithDefs(defs, "CQL "+cqlText)
+	if err != nil {
+		t.Fatalf("BuildStatementWithDefs(CQL %s) error = %v", cqlText, err)
+	}
+	return stmt
+}
+
+// TestReadOnlyGuardBlocksMutatingCQL verifies that mutating CQL is rejected by
+// Session.ExecuteStatement in READONLY mode before the statement can reach the
+// Cassandra adapter. These statements short-circuit at the guard before
+// CQLStatement.Execute, so no adapter/proxy is built.
+func TestReadOnlyGuardBlocksMutatingCQL(t *testing.T) {
+	t.Parallel()
+
+	for _, tt := range []struct {
+		desc string
+		cql  string
+	}{
+		{desc: "DELETE blocked", cql: "DELETE FROM t WHERE id = 1"},
+		{desc: "INSERT blocked", cql: "INSERT INTO t (id) VALUES (1)"},
+		{desc: "unrecognized keyword blocked", cql: "FROBNICATE t"},
+	} {
+		t.Run(tt.desc, func(t *testing.T) {
+			t.Parallel()
+			session := mycli.NewReadOnlySessionForTest(t)
+			_, err := session.ExecuteStatement(t.Context(), buildCQL(t, tt.cql))
+			if !mycli.IsReadOnlyError(err) {
+				t.Errorf("%s in READONLY mode: got error %v, want READONLY error", tt.desc, err)
+			}
+		})
+	}
+}
+
+// TestReadOnlyGuardAllowsReadOnlyCQL verifies, at the dispatch level, that a
+// read-only CQL SELECT is not classified as a static MutationStatement and that
+// the DISPATCH-BUILT statement's conditional classifier reports non-mutating,
+// so the READONLY guard lets it through. Asserting the classification on the
+// statement produced by the real def table (not one built via the constructor)
+// catches a HandleGroups regression that returns a zero-value CQLStatement:
+// with the fail-closed nil-Classify default, that regression would silently
+// block CQL SELECT in READONLY mode (#782 review nit).
+//
+// Unlike the BigQuery counterpart, this does NOT run the SELECT through
+// Session.ExecuteStatement: a passing SELECT proceeds to CQLStatement.Execute,
+// which builds the Cassandra adapter via spancql.NewCluster. That call panics
+// when the adapter client cannot be constructed (no live Spanner backend in
+// tests), so it cannot "fail later for a non-READONLY reason" the way BigQuery's
+// project-not-configured guard does.
+func TestReadOnlyGuardAllowsReadOnlyCQL(t *testing.T) {
+	t.Parallel()
+
+	stmt := buildCQL(t, "SELECT * FROM t")
+	if _, isMutation := stmt.(mycli.MutationStatement); isMutation {
+		t.Fatal("CQLStatement must not be a static MutationStatement")
+	}
+	conditional, mutating := mycli.ClassifyForTest(stmt)
+	if !conditional {
+		t.Fatal("dispatch-built CQLStatement must be a ConditionallyMutatingStatement")
+	}
+	if mutating {
+		t.Fatal("dispatch-built CQL SELECT classifies as mutating; READONLY mode would wrongly block it (HandleGroups regression?)")
+	}
+
+	// The mutating counterpart, classified on the dispatch-built statement.
+	del := buildCQL(t, "DELETE FROM t WHERE id = 1")
+	conditional, mutating = mycli.ClassifyForTest(del)
+	if !conditional || !mutating {
+		t.Fatalf("dispatch-built CQL DELETE: conditional=%v mutating=%v, want true/true", conditional, mutating)
+	}
+}

internal/mycli/export_test.go

@@ -58,3 +58,16 @@ func NewSessionWithFeaturesForTest(t *testing.T, features ...Feature) *Session {
 func ListVariablesForTest(s *Session) map[string]string {
 	return s.systemVariables.ListVariables()
 }
+
+// ClassifyForTest reports how the READONLY guard would classify stmt:
+// conditional is true when stmt is a ConditionallyMutatingStatement, and
+// mutating is its runtime classification (false when not conditional). The
+// marker method is unexported, so external dispatch-level tests use this bridge
+// to assert the classification of statements built through the real def table.
+func ClassifyForTest(stmt Statement) (conditional, mutating bool) {
+	cm, ok := stmt.(ConditionallyMutatingStatement)
+	if !ok {
+		return false, false
+	}
+	return true, cm.isConditionallyMutating()
+}

internal/mycli/feature/all/all.go

@@ -20,6 +20,7 @@ package all
 import (
 	"github.com/apstndb/spanner-mycli/internal/mycli"
 	"github.com/apstndb/spanner-mycli/internal/mycli/feature/bigquery"
+	"github.com/apstndb/spanner-mycli/internal/mycli/feature/cql"
 )
 
 // All returns every optional feature in a fixed, documented order: GEMINI/LLM,
@@ -30,16 +31,17 @@ import (
 // Order-contract note (#778 §7): features append AFTER the core table, so
 // extracting a family moves its statement-help row to the end of the merged
 // table in All() order. The final order is fixed as (llm, cql, bigquery) rather
-// than the pre-extraction core order (llm, bigquery, cql). This makes the single
-// BIGQUERY/CQL row swap in the generated statement help land in PR1 (BIGQUERY
-// extraction) alone; PR2 (CQL) and PR3 (LLM) then re-append at the same relative
-// positions and stay byte-identical.
+// than the pre-extraction core order (llm, bigquery, cql). The single
+// BIGQUERY/CQL row swap in the generated statement help landed in PR1 (BIGQUERY
+// extraction) alone; CQL now re-appends at the same relative position (before
+// BIGQUERY) and stays byte-identical.
 //
-// Only BIGQUERY is extracted so far; LLM and CQL still live in core and will be
-// added here (before BIGQUERY, preserving the llm, cql, bigquery order) as they
-// are extracted under internal/mycli/feature/{llm,cql}.
+// BIGQUERY and CQL are extracted; LLM still lives in core and will be added here
+// (before CQL, preserving the llm, cql, bigquery order) when it is extracted
+// under internal/mycli/feature/llm.
 func All() []mycli.Feature {
 	return []mycli.Feature{
+		cql.Feature(),
 		bigquery.Feature(),
 	}
 }

internal/mycli/feature/cql/classifier.go

@@ -0,0 +1,50 @@
+// Copyright 2026 apstndb
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cql
+
+import "strings"
+
+// firstCQLKeyword returns the uppercased first whitespace-delimited token of a
+// CQL statement, or "" if there is none.
+func firstCQLKeyword(cql string) string {
+	fields := strings.Fields(cql)
+	if len(fields) == 0 {
+		return ""
+	}
+	return strings.ToUpper(fields[0])
+}
+
+// cqlStatementMutates reports whether a CQL statement should be treated as
+// mutating for the purpose of the READONLY guard.
+//
+// It classifies by the statement's first keyword and is deliberately
+// fail-closed: only statements whose first keyword is a known read-only verb
+// are allowed under READONLY. Everything else - data mutations
+// (INSERT/UPDATE/DELETE), batches (BATCH), DDL (CREATE/DROP/ALTER/TRUNCATE),
+// permission changes (GRANT/REVOKE), and any unrecognized or empty keyword - is
+// treated as mutating so the guard blocks it. This avoids silently allowing an
+// unknown CQL verb to bypass READONLY.
+//
+// SELECT is the only clearly read-only data verb in the Spanner Cassandra
+// adapter's supported surface. Other Cassandra read verbs (e.g. LIST, DESCRIBE)
+// are not part of that surface, so they are intentionally not allow-listed.
+func cqlStatementMutates(cql string) bool {
+	switch firstCQLKeyword(cql) {
+	case "SELECT":
+		return false
+	default:
+		return true
+	}
+}

internal/mycli/feature/cql/classifier_test.go

@@ -0,0 +1,55 @@
+// Copyright 2026 apstndb
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//	http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cql
+
+import "testing"
+
+// TestCQLStatementMutates exhaustively checks the fail-closed classification of
+// CQL statements: only SELECT is treated as read-only; every other verb
+// (mutations, DDL, permissions) and any unrecognized or empty keyword is
+// treated as mutating. Preserves the #757 coverage moved from the core
+// readonly_guard_test.go (#778).
+func TestCQLStatementMutates(t *testing.T) {
+	t.Parallel()
+
+	for _, tt := range []struct {
+		cql  string
+		want bool
+	}{
+		{cql: "SELECT * FROM t", want: false},
+		{cql: "select * from t", want: false},
+		{cql: "  SELECT * FROM t", want: false},
+		{cql: "INSERT INTO t (id) VALUES (1)", want: true},
+		{cql: "UPDATE t SET c = 1 WHERE id = 1", want: true},
+		{cql: "DELETE FROM t WHERE id = 1", want: true},
+		{cql: "BEGIN BATCH INSERT INTO t (id) VALUES (1) APPLY BATCH", want: true},
+		{cql: "TRUNCATE t", want: true},
+		{cql: "CREATE TABLE t (id int PRIMARY KEY)", want: true},
+		{cql: "DROP TABLE t", want: true},
+		{cql: "ALTER TABLE t ADD c int", want: true},
+		{cql: "GRANT SELECT ON t TO role", want: true},
+		{cql: "REVOKE SELECT ON t FROM role", want: true},
+		{cql: "BOGUS not a real verb", want: true}, // fail-closed on unknown keyword
+		{cql: "", want: true},                      // fail-closed on empty
+		{cql: "   ", want: true},                   // fail-closed on whitespace-only
+	} {
+		t.Run(tt.cql, func(t *testing.T) {
+			t.Parallel()
+			if got := cqlStatementMutates(tt.cql); got != tt.want {
+				t.Errorf("cqlStatementMutates(%q) = %v, want %v", tt.cql, got, tt.want)
+			}
+		})
+	}
+}