feat(quandledb/krl): implement KRL parser suite — Lexer, AST, Parser, SqlFrontend + tests

Implements KRL (Knot Resolution Language) v0.1.0 parser per grammar.ebnf,
conforming to standards/testing-and-benchmarking/TESTING-TAXONOMY.adoc.

Components:
  Lexer.jl         — single-pass tokeniser; knot-name tokens (3_1), Unicode ≅,
                     nested block comments, bare-= rejection with helpful error
  Ast.jl           — 40+ concrete node types, all position-annotated;
                     ConfidenceLevel enum matching Idris2 ABI
  Parser.jl        — recursive-descent, 9 expression precedence levels;
                     pipeline error recovery (collect errors at | boundaries);
                     Gauss code validation at parse time (non-empty, no zeros);
                     parse_any SQL/KRL auto-dispatch
  SqlFrontend.jl   — syntactic SQL→KRL translation; each clause maps directly
                     to the corresponding KRL pipeline stage; unsupported SQL
                     (DISTINCT, NULL, INSERT, UPDATE, DELETE) → helpful errors
  test/lexer_test.jl   — unit + property + fuzz seed corpus
  test/parser_test.jl  — unit + property + error-recovery + fuzz seed corpus
  test/sql_test.jl     — SQL clause coverage, ordering, unsupported features,
                         parse_any routing, AST equivalence property

Also fixes _parse_sort_item bug: _advance!() → _advance!(ps).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: hyperpolymath

quandledb/server/krl/Ast.jl

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MPL-2.0
+# (PMPL-1.0-or-later preferred; MPL-2.0 for Julia ecosystem consistency)
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+
+"""
+KRL — Knot Resolution Language parser for QuandleDB.
+
+Implements the parser for KRL v0.1.0 (grammar.ebnf, spec/type-system.md).
+Components:
+  Lexer.jl        — tokeniser (Token, tokenise, KRLLexError)
+  Ast.jl          — AST node types (KRLProgram, KRLQuery, …)
+  Parser.jl       — recursive-descent parser (parse_krl, parse_krl_query)
+  SqlFrontend.jl  — SQL→KRL translation layer (parse_sql)
+
+Entry points (re-exported):
+  parse_krl(src)        — parse KRL source → KRLProgram
+  parse_krl_query(src)  — parse a single pipeline query → KRLQuery
+  parse_sql(src)        — parse SQL SELECT → KRLProgram (translated to KRL AST)
+  parse_any(src)        — auto-detect SQL vs KRL and dispatch
+
+Usage from serve.jl:
+  include("krl/KRL.jl")
+  using .KRL: parse_any, parse_krl_query, KRLParseError
+"""
+module KRL
+
+include("Lexer.jl")
+include("Ast.jl")
+include("Parser.jl")
+include("SqlFrontend.jl")
+
+end # module KRL

quandledb/server/krl/KRL.jl

@@ -0,0 +1,353 @@
+# SPDX-License-Identifier: MPL-2.0
+# (PMPL-1.0-or-later preferred; MPL-2.0 for Julia ecosystem consistency)
+# Copyright (c) 2026 Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+
+"""
+KRL Lexer — tokenises a KRL (Knot Resolution Language) source string.
+
+Follows grammar.ebnf v0.1.0 exactly. All 50+ keywords are recognised.
+
+Token kinds (Symbol tags):
+  Literals:   :integer   — `123`
+              :float     — `1.5`
+              :string    — `"hello"`
+              :bool      — `true` / `false`
+              :knot_name — `3_1`, `10_139` (digit `_` digit form)
+  Names:      :keyword   — reserved word
+              :identifier — user name or invariant name
+  Operators:  :eq          (`==`)
+              :neq         (`!=`)
+              :lt          (`<`)
+              :lte         (`<=`)
+              :gt          (`>`)
+              :gte         (`>=`)
+              :plus        (`+`)
+              :minus       (`-`)
+              :star        (`*`)
+              :slash       (`/`)
+              :percent     (`%`)
+              :pipe        (`|`)
+              :arrow       (`->`)
+              :fat_arrow   (`=>`)
+              :tilde_arrow (`~>`)
+              :iso         (`≅` or `~=` — normalised to one token kind)
+              :null_coalesce (`??`)
+              :dot         (`.`)
+              :colon       (`:`)
+              :comma       (`,`)
+              :semi        (`;`)
+  Delimiters: :lparen, :rparen, :lbracket, :rbracket, :lbrace, :rbrace
+  Special:    :eof
+
+Innovations vs KRLAdapter.jl:
+  - `:knot_name` token: `3_1`, `5_2`, `10_139` (digit-underscore-digit) emitted
+    as a dedicated token, not split into integer + identifier.
+  - Float literals: `1.5`, `3.14`.
+  - Block comments `{- ... -}` with nesting depth tracking (depth > 1 is an
+    innovation allowing nested comment-out blocks).
+  - Unicode operator `≅` normalised to `:iso` (same as ASCII `~=`).
+  - All 50 KRL keywords, including compound forms (`find_equivalent`, `group_by`).
+"""
+
+export Token, TokenKind, tokenise, KRLLexError
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Token kind
+# ─────────────────────────────────────────────────────────────────────────────
+
+const TokenKind = Symbol
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Reserved words (must stay in sync with grammar.ebnf keyword list)
+# ─────────────────────────────────────────────────────────────────────────────
+
+const KRL_KEYWORDS = Set([
+    # pipeline stages
+    "from", "filter", "sort", "take", "skip", "return",
+    "group_by", "aggregate",
+    # equivalence / path queries
+    "find_equivalent", "find_path", "match", "via",
+    # logical / comparison
+    "and", "or", "not", "in",
+    # specifiers
+    "as", "with", "let", "where",
+    # provenance
+    "provenance",
+    # confidence levels
+    "confidence", "exact", "necessary", "sufficient", "heuristic",
+    # sort direction
+    "asc", "desc",
+    # aggregate functions (also plain identifiers in function-call position)
+    "count", "min", "max", "avg", "sum",
+    # collections
+    "knots", "diagrams", "invariants",
+    # path methods
+    "reidemeister", "isotopy",
+    # return items
+    "equivalences", "equivalence_class", "proof",
+    # rule / axiom
+    "rule", "define", "axiom", "forall",
+    # boolean literals (also handled in literal branch, keyword tag wins)
+    "true", "false",
+    # option absent
+    "none",
+    # type names (doubled as keywords so the parser can recognise them)
+    "Int", "Float", "String", "Bool",
+    "Knot", "Diagram", "Polynomial", "GaussCode", "Quandle",
+    "Equivalence", "Option", "List", "Set", "Map", "ResultSet", "Provenance",
+])
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Token
+# ─────────────────────────────────────────────────────────────────────────────
+
+"""
+    Token
+
+A single lexical unit produced by `tokenise`.
+
+Fields:
+- `kind::TokenKind` — symbolic tag (see Lexer.jl header)
+- `value::String`   — raw text of the token (empty for `:eof`)
+- `line::Int`       — 1-based source line of first character
+- `col::Int`        — 1-based column of first character
+"""
+struct Token
+    kind::TokenKind
+    value::String
+    line::Int
+    col::Int
+end
+
+Base.show(io::IO, t::Token) =
+    print(io, "Token($(t.kind), $(repr(t.value)), L$(t.line):C$(t.col))")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Lex error
+# ─────────────────────────────────────────────────────────────────────────────
+
+"""
+    KRLLexError(msg, line, col)
+
+Thrown by `tokenise` on unexpected characters, unterminated strings, or
+unterminated block comments.
+"""
+struct KRLLexError <: Exception
+    msg::String
+    line::Int
+    col::Int
+end
+
+Base.showerror(io::IO, e::KRLLexError) =
+    print(io, "KRLLexError at L$(e.line):C$(e.col): $(e.msg)")
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Tokeniser
+# ─────────────────────────────────────────────────────────────────────────────
+
+"""
+    tokenise(src::String) -> Vector{Token}
+
+Scan `src` and return all tokens. The last element is always `Token(:eof, "", …)`.
+
+Throws `KRLLexError` on unrecognised characters, unterminated string literals,
+or unterminated block comments.
+"""
+function tokenise(src::String)::Vector{Token}
+    tokens = Token[]
+    chars  = collect(src)   # Unicode-aware char array
+    n      = length(chars)
+    i      = 1
+    line   = 1
+    col    = 1
+
+    # Inline helpers ─────────────────────────────────────────────────────────
+
+    @inline function advance!()
+        c = chars[i]; i += 1
+        if c == '\n'; line += 1; col = 1; else; col += 1; end
+        c
+    end
+
+    @inline peek()  = i     <= n ? chars[i]     : '\0'
+    @inline peek2() = i + 1 <= n ? chars[i + 1] : '\0'
+
+    @inline function emit(kind, val, sl, sc)
+        push!(tokens, Token(kind, val, sl, sc))
+    end
+
+    # Main scan loop ─────────────────────────────────────────────────────────
+
+    while i <= n
+        sl = line; sc = col   # start line/col of this token
+        c = advance!()
+
+        # ── whitespace ───────────────────────────────────────────────────────
+        if c == ' ' || c == '\t' || c == '\r' || c == '\n'
+            continue
+        end
+
+        # ── line comment: -- to EOL ──────────────────────────────────────────
+        if c == '-' && peek() == '-'
+            advance!()
+            while i <= n && chars[i] != '\n'; advance!(); end
+            continue
+        end
+
+        # ── block comment: {- ... -} with nesting ────────────────────────────
+        if c == '{' && peek() == '-'
+            advance!()          # consume '-'
+            depth = 1
+            while depth > 0
+                i > n && throw(KRLLexError("unterminated block comment", sl, sc))
+                ch = advance!()
+                if ch == '{' && peek() == '-'; advance!(); depth += 1
+                elseif ch == '-' && peek() == '}'; advance!(); depth -= 1
+                end
+            end
+            continue
+        end
+
+        # ── string literals ──────────────────────────────────────────────────
+        if c == '"'
+            buf = Char[]
+            while true
+                i > n && throw(KRLLexError("unterminated string literal", sl, sc))
+                ch = advance!()
+                if ch == '"'; break
+                elseif ch == '\\'
+                    i > n && throw(KRLLexError("unterminated escape sequence", sl, sc))
+                    esc = advance!()
+                    push!(buf, esc == 'n' ? '\n' :
+                               esc == 't' ? '\t' :
+                               esc == 'r' ? '\r' : esc)
+                else
+                    push!(buf, ch)
+                end
+            end
+            emit(:string, String(buf), sl, sc)
+            continue
+        end
+
+        # ── numeric literals: integer, float, or knot_name ───────────────────
+        #   knot_name pattern: digit+ '_' digit+   (e.g. 3_1, 10_139)
+        #   float pattern:     digit+ '.' digit+
+        #   integer pattern:   digit+
+        if isdigit(c)
+            buf = [c]
+            while i <= n && isdigit(peek()); push!(buf, advance!()); end
+            if peek() == '_' && i + 1 <= n && isdigit(peek2())
+                push!(buf, advance!())   # consume '_'
+                while i <= n && isdigit(peek()); push!(buf, advance!()); end
+                emit(:knot_name, String(buf), sl, sc)
+            elseif peek() == '.' && i + 1 <= n && isdigit(peek2())
+                push!(buf, advance!())   # consume '.'
+                while i <= n && isdigit(peek()); push!(buf, advance!()); end
+                emit(:float, String(buf), sl, sc)
+            else
+                emit(:integer, String(buf), sl, sc)
+            end
+            continue
+        end
+
+        # ── identifiers and keywords ─────────────────────────────────────────
+        #   Identifiers may contain letters, digits, underscores, hyphens.
+        #   Compound keywords like `find_equivalent` and `group_by` are matched
+        #   as single identifiers and then classified via KRL_KEYWORDS.
+        if isletter(c) || c == '_'
+            buf = [c]
+            while i <= n && (isletter(peek()) || isdigit(peek()) || peek() == '_' || peek() == '-')
+                push!(buf, advance!())
+            end
+            word = String(buf)
+            kind = word in KRL_KEYWORDS ? :keyword : :identifier
+            emit(kind, word, sl, sc)
+            continue
+        end
+
+        # ── Unicode operator: ≅ (propositional equivalence) ──────────────────
+        if c == '≅'
+            emit(:iso, "≅", sl, sc)
+            continue
+        end
+
+        # ── two-character and single-character operators ──────────────────────
+
+        if c == '='
+            if peek() == '='
+                advance!(); emit(:eq, "==", sl, sc)
+            else
+                throw(KRLLexError("bare `=` is not a KRL operator; did you mean `==`?", sl, sc))
+            end
+            continue
+        end
+
+        if c == '!'
+            peek() == '=' || throw(KRLLexError("expected `!=`, got bare `!`", sl, sc))
+            advance!(); emit(:neq, "!=", sl, sc)
+            continue
+        end
+
+        if c == '<'
+            if peek() == '='; advance!(); emit(:lte, "<=", sl, sc)
+            else; emit(:lt, "<", sl, sc); end
+            continue
+        end
+
+        if c == '>'
+            if peek() == '='; advance!(); emit(:gte, ">=", sl, sc)
+            else; emit(:gt, ">", sl, sc); end
+            continue
+        end
+
+        if c == '-'
+            if peek() == '>'; advance!(); emit(:arrow, "->", sl, sc)
+            else; emit(:minus, "-", sl, sc); end
+            continue
+        end
+
+        if c == '='
+            if peek() == '>'; advance!(); emit(:fat_arrow, "=>", sl, sc)
+            else; emit(:eq, "=", sl, sc); end
+            continue
+        end
+
+        if c == '~'
+            if peek() == '>'; advance!(); emit(:tilde_arrow, "~>", sl, sc)
+            elseif peek() == '='; advance!(); emit(:iso, "~=", sl, sc)
+            else; throw(KRLLexError("expected `~>` or `~=`, got bare `~`", sl, sc)); end
+            continue
+        end
+
+        if c == '?'
+            peek() == '?' || throw(KRLLexError("expected `??`, got bare `?`", sl, sc))
+            advance!(); emit(:null_coalesce, "??", sl, sc)
+            continue
+        end
+
+        # single-char operators
+        if c == '+';  emit(:plus,     "+", sl, sc); continue; end
+        if c == '*';  emit(:star,     "*", sl, sc); continue; end
+        if c == '/';  emit(:slash,    "/", sl, sc); continue; end
+        if c == '%';  emit(:percent,  "%", sl, sc); continue; end
+        if c == '|';  emit(:pipe,     "|", sl, sc); continue; end
+        if c == '.';  emit(:dot,      ".", sl, sc); continue; end
+        if c == ':';  emit(:colon,    ":", sl, sc); continue; end
+        if c == ',';  emit(:comma,    ",", sl, sc); continue; end
+        if c == ';';  emit(:semi,     ";", sl, sc); continue; end
+        if c == '(';  emit(:lparen,   "(", sl, sc); continue; end
+        if c == ')';  emit(:rparen,   ")", sl, sc); continue; end
+        if c == '[';  emit(:lbracket, "[", sl, sc); continue; end
+        if c == ']';  emit(:rbracket, "]", sl, sc); continue; end
+        if c == '}';  emit(:rbrace,   "}", sl, sc); continue; end
+
+        # '{' is a block-comment start only if followed by '-' (handled above).
+        # Otherwise it opens a record literal.
+        if c == '{';  emit(:lbrace,   "{", sl, sc); continue; end
+
+        throw(KRLLexError("unexpected character $(repr(c))", sl, sc))
+    end
+
+    emit(:eof, "", line, col)
+    tokens
+end