@quereus/quereus 0.2.0 → 0.4.0

package/dist/src/parser/parser.js

@@ -34,6 +34,8 @@ export class Parser {
     current = 0;
     // Counter for positional parameters
     parameterPosition = 1;
+    // Track opening parentheses for accurate error locations
+    parenStack = [];
     /**
      * Initialize the parser with tokens from a SQL string
      * @param sql SQL string to parse
@@ -44,6 +46,7 @@ export class Parser {
         this.tokens = lexer.scanTokens();
         this.current = 0;
         this.parameterPosition = 1; // Reset parameter counter
+        this.parenStack = [];
         // Check for errors from lexer
         const errorToken = this.tokens.find(t => t.type === TokenType.ERROR);
         if (errorToken) {
@@ -85,6 +88,16 @@ export class Parser {
                 quereusError(`Parser error: ${e instanceof Error ? e.message : e}`, StatusCode.ERROR, e instanceof Error ? e : undefined);
             }
         }
+        // Report any unterminated parenthesis at EOF with pointer to opening location
+        if (this.parenStack.length > 0) {
+            const openToken = this.parenStack[this.parenStack.length - 1];
+            quereusError(`Unterminated '(' opened at line ${openToken.startLine}, column ${openToken.startColumn}. Expected ')' before end of input.`, StatusCode.ERROR, undefined, {
+                loc: {
+                    start: { line: openToken.startLine, column: openToken.startColumn },
+                    end: { line: this.peek().endLine, column: this.peek().endColumn },
+                },
+            });
+        }
         // If we consumed all tokens and didn't parse any statements (e.g., empty input or only comments/whitespace),
         // return an empty array instead of throwing an error.
         return statements;
@@ -162,7 +175,7 @@ export class Parser {
             if (!this.check(TokenType.RPAREN)) {
                 do {
                     columns.push(this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'like'], "Expected column name in CTE definition."));
-                } while (this.match(TokenType.COMMA));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CTE column list.");
         }
@@ -273,6 +286,22 @@ export class Parser {
                 this.advance();
                 stmt = this.pragmaStatement(startToken, withClause);
                 break;
+            case 'DECLARE':
+                this.advance();
+                stmt = this.declareSchemaStatement(startToken);
+                break;
+            case 'DIFF':
+                this.advance();
+                stmt = this.diffSchemaStatement(startToken);
+                break;
+            case 'APPLY':
+                this.advance();
+                stmt = this.applySchemaStatement(startToken);
+                break;
+            case 'EXPLAIN':
+                this.advance();
+                stmt = this.explainSchemaStatement(startToken);
+                break;
             // --- Add default case ---
             default:
                 // If it wasn't a recognized keyword starting the statement
@@ -280,6 +309,7 @@ export class Parser {
         }
         // Attach WITH clause if present and supported
         if (withClause && this.statementSupportsWithClause(stmt)) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             stmt.withClause = withClause;
             if (withClause.loc && stmt.loc) {
                 stmt.loc.start = withClause.loc.start;
@@ -312,6 +342,17 @@ export class Parser {
             } while (this.match(TokenType.COMMA));
             this.consume(TokenType.RPAREN, "Expected ')' after column list.");
         }
+        // Parse mutation context assignments if present (after column list, before VALUES/SELECT)
+        let contextValues;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('CONTEXT')) {
+                contextValues = this.parseContextAssignments();
+            }
+            else {
+                // Not a WITH CONTEXT clause, backtrack
+                this.current--;
+            }
+        }
         // Parse VALUES clause
         let values;
         let select;
@@ -356,6 +397,7 @@ export class Parser {
             values,
             select,
             returning,
+            contextValues,
             loc: _createLoc(startToken, lastConsumedToken),
         };
     }
@@ -409,7 +451,7 @@ export class Parser {
         }
         // Check for compound set operations (UNION / INTERSECT / EXCEPT) BEFORE ORDER BY/LIMIT
         let compound;
-        if (this.match(TokenType.UNION, TokenType.INTERSECT, TokenType.EXCEPT)) {
+        if (this.match(TokenType.UNION, TokenType.INTERSECT, TokenType.EXCEPT, TokenType.DIFF)) {
             const tok = this.previous();
             let op;
             if (tok.type === TokenType.UNION) {
@@ -423,9 +465,12 @@ export class Parser {
             else if (tok.type === TokenType.INTERSECT) {
                 op = 'intersect';
             }
-            else {
+            else if (tok.type === TokenType.EXCEPT) {
                 op = 'except';
             }
+            else {
+                op = 'diff';
+            }
             let rightSelect;
             // Handle parenthesized subquery after set operation
             if (this.match(TokenType.LPAREN)) {
@@ -574,7 +619,7 @@ export class Parser {
         let schema;
         let name;
         let endToken = startToken;
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like', 'temp', 'temporary'];
         // Check for schema.table pattern
         if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT)) {
             schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
@@ -688,7 +733,7 @@ export class Parser {
             if (!this.check(TokenType.RPAREN)) {
                 do {
                     columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
-                } while (this.match(TokenType.COMMA));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
         }
@@ -754,7 +799,7 @@ export class Parser {
             if (!this.check(TokenType.RPAREN)) {
                 do {
                     columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
-                } while (this.match(TokenType.COMMA));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
         }
@@ -830,6 +875,7 @@ export class Parser {
         endToken = this.consume(TokenType.RPAREN, "Expected ')' after table function arguments.");
         // Parse optional alias (same logic as for standard tables)
         let alias;
+        let columns;
         if (this.match(TokenType.AS)) {
             if (!this.checkIdentifierLike(contextualKeywords)) {
                 throw this.error(this.peek(), "Expected alias after 'AS'.");
@@ -847,11 +893,23 @@ export class Parser {
             alias = aliasToken.lexeme;
             endToken = aliasToken;
         }
+        // Optional column list after alias: alias(col1, col2, ...)
+        if (alias && this.match(TokenType.LPAREN)) {
+            columns = [];
+            const colKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(colKeywords, "Expected column name in alias column list."));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
+            }
+            endToken = this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
+        }
         return {
             type: 'functionSource',
             name,
             args,
             alias,
+            columns,
             loc: _createLoc(startToken, endToken),
         };
     }
@@ -882,6 +940,8 @@ export class Parser {
         }
         // Consume JOIN token
         this.consume(TokenType.JOIN, "Expected 'JOIN'.");
+        // Optional LATERAL before right side
+        const _isLateral = this.match(TokenType.LATERAL);
         // Parse right side of join
         const right = this.tableSource(withClause);
         // Parse join condition
@@ -1331,6 +1391,7 @@ export class Parser {
         // Literals
         if (this.match(TokenType.INTEGER, TokenType.FLOAT, TokenType.STRING, TokenType.NULL, TokenType.TRUE, TokenType.FALSE, TokenType.BLOB)) {
             const token = this.previous();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
             let value;
             let lexeme = undefined;
             if (token.type === TokenType.NULL) {
@@ -1607,7 +1668,19 @@ export class Parser {
         if (this.check(type)) {
             return this.advance();
         }
-        this.error(this.peek(), message);
+        // If a ')' was expected, point back to the matching '('
+        if (type === TokenType.RPAREN && this.parenStack.length > 0) {
+            const openToken = this.parenStack[this.parenStack.length - 1];
+            const got = this.peek();
+            quereusError(`${message} Unterminated '(' opened at line ${openToken.startLine}, column ${openToken.startColumn}. Got '${got.lexeme}'.`, StatusCode.ERROR, undefined, {
+                loc: {
+                    start: { line: openToken.startLine, column: openToken.startColumn },
+                    end: { line: this.peek().endLine, column: this.peek().endColumn },
+                },
+            });
+        }
+        const got = this.peek();
+        this.error(got, `${message} Got '${got.lexeme}'.`);
     }
     check(type) {
         if (this.isAtEnd())
@@ -1622,7 +1695,20 @@ export class Parser {
     advance() {
         if (!this.isAtEnd())
             this.current++;
-        return this.previous();
+        const tok = this.previous();
+        // Maintain parenthesis balance for precise diagnostics
+        if (tok.type === TokenType.LPAREN) {
+            this.parenStack.push(tok);
+        }
+        else if (tok.type === TokenType.RPAREN) {
+            if (this.parenStack.length === 0) {
+                quereusError(`Unmatched ')' at line ${tok.startLine}, column ${tok.startColumn}.`, StatusCode.ERROR, undefined, { loc: { start: { line: tok.startLine, column: tok.startColumn }, end: { line: tok.endLine, column: tok.endColumn } } });
+            }
+            else {
+                this.parenStack.pop();
+            }
+        }
+        return tok;
     }
     isAtEnd() {
         return this.peek().type === TokenType.EOF;
@@ -1634,7 +1720,18 @@ export class Parser {
         return this.tokens[this.current - 1];
     }
     error(token, message) {
-        quereusError(message, StatusCode.ERROR, undefined, {
+        // If we see common starter tokens for a different clause where a separator/comma or keyword was expected,
+        // enhance the message to hint at likely fixes instead of generic parenthesis errors.
+        const nextLex = token.lexeme?.toUpperCase?.() || token.lexeme;
+        const hintParts = [];
+        if (this.peekKeyword('CONSTRAINT') || this.peekKeyword('PRIMARY') || this.peekKeyword('UNIQUE') || this.peekKeyword('CHECK') || this.peekKeyword('FOREIGN')) {
+            hintParts.push("If you're in CREATE TABLE, you might be missing a comma between elements.");
+        }
+        if (nextLex === 'ON' && !this.peekKeyword('JOIN')) {
+            hintParts.push("'ON' must follow a JOIN. Use WHERE for filters in subqueries.");
+        }
+        const fullMessage = hintParts.length > 0 ? `${message} ${hintParts.join(' ')}` : message;
+        quereusError(fullMessage, StatusCode.ERROR, undefined, {
             loc: {
                 start: {
                     line: token.startLine,
@@ -1663,7 +1760,7 @@ export class Parser {
             token === TokenType.HAVING ||
             token === TokenType.ORDER ||
             token === TokenType.LIMIT ||
-            token === TokenType.UNION ||
+            token === TokenType.UNION || token === TokenType.DIFF || token === TokenType.INTERSECT || token === TokenType.EXCEPT ||
             token === TokenType.SEMICOLON ||
             token === TokenType.EOF;
     }
@@ -1671,6 +1768,17 @@ export class Parser {
     /** @internal */
     updateStatement(startToken, _withClause) {
         const table = this.tableIdentifier();
+        // Parse mutation context assignments if present
+        let contextValues;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('CONTEXT')) {
+                contextValues = this.parseContextAssignments();
+            }
+            else {
+                // Not a WITH CONTEXT clause, backtrack
+                this.current--;
+            }
+        }
         this.consume(TokenType.SET, "Expected 'SET' after table name in UPDATE.");
         const assignments = [];
         do {
@@ -1689,12 +1797,23 @@ export class Parser {
             returning = this.columnList();
         }
         const endToken = this.previous();
-        return { type: 'update', table, assignments, where, returning, loc: _createLoc(startToken, endToken) };
+        return { type: 'update', table, assignments, where, returning, contextValues, loc: _createLoc(startToken, endToken) };
     }
     /** @internal */
     deleteStatement(startToken, _withClause) {
         this.matchKeyword('FROM');
         const table = this.tableIdentifier();
+        // Parse mutation context assignments if present
+        let contextValues;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('CONTEXT')) {
+                contextValues = this.parseContextAssignments();
+            }
+            else {
+                // Not a WITH CONTEXT clause, backtrack
+                this.current--;
+            }
+        }
         let where;
         if (this.match(TokenType.WHERE)) {
             where = this.expression();
@@ -1705,7 +1824,7 @@ export class Parser {
             returning = this.columnList();
         }
         const endToken = this.previous();
-        return { type: 'delete', table, where, returning, loc: _createLoc(startToken, endToken) };
+        return { type: 'delete', table, where, returning, contextValues, loc: _createLoc(startToken, endToken) };
     }
     /** @internal */
     valuesStatement(startToken) {
@@ -1738,12 +1857,16 @@ export class Parser {
             this.consumeKeyword('VIEW', "Expected 'VIEW' after CREATE.");
             return this.createViewStatement(startToken, withClause);
         }
+        else if (this.peekKeyword('ASSERTION')) {
+            this.consumeKeyword('ASSERTION', "Expected 'ASSERTION' after CREATE.");
+            return this.createAssertionStatement(startToken, withClause);
+        }
         else if (this.peekKeyword('UNIQUE')) {
             this.consumeKeyword('UNIQUE', "Expected 'UNIQUE' after CREATE.");
             this.consumeKeyword('INDEX', "Expected 'INDEX' after CREATE UNIQUE.");
             return this.createIndexStatement(startToken, true, withClause);
         }
-        throw this.error(this.peek(), "Expected TABLE, [UNIQUE] INDEX, VIEW, or VIRTUAL after CREATE.");
+        throw this.error(this.peek(), "Expected TABLE, [UNIQUE] INDEX, VIEW, ASSERTION, or VIRTUAL after CREATE.");
     }
     /**
      * Parse CREATE TABLE statement
@@ -1773,7 +1896,18 @@ export class Parser {
                 else {
                     columns.push(this.columnDefinition());
                 }
-            } while (this.match(TokenType.COMMA));
+                // Allow trailing comma before ')'
+            } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
+            // If we didn't see a comma and the next token looks like the start of another
+            // column or table constraint, provide a clearer error about a missing comma.
+            if (!this.check(TokenType.RPAREN)) {
+                const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
+                const nextLooksLikeAnotherItem = this.peekKeyword('PRIMARY') || this.peekKeyword('UNIQUE') || this.peekKeyword('CHECK') || this.peekKeyword('FOREIGN') || this.peekKeyword('CONSTRAINT') || this.checkIdentifierLike(contextualKeywords);
+                if (nextLooksLikeAnotherItem) {
+                    const next = this.peek();
+                    throw this.error(next, `Expected ',' between table elements. Did you forget a comma before '${next.lexeme}'?`);
+                }
+            }
             this.consume(TokenType.RPAREN, "Expected ')' after table definition.");
         }
         else if (this.matchKeyword('AS')) {
@@ -1787,15 +1921,27 @@ export class Parser {
         const moduleArgs = {};
         if (this.matchKeyword('USING')) {
             moduleName = this.consumeIdentifier("Expected module name after 'USING'.");
-            if (this.matchKeyword('(')) {
-                while (!this.match(TokenType.RPAREN)) {
-                    const nameValue = this.nameValueItem("module argument");
-                    moduleArgs[nameValue.name] = nameValue.value && nameValue.value.type === 'literal'
-                        ? getSyncLiteral(nameValue.value) : nameValue.name;
-                    if (!this.match(TokenType.COMMA) || this.check(TokenType.RPAREN)) {
-                        throw this.error(this.peek(), "Expected ',' or ')' after module argument.");
-                    }
+            if (this.match(TokenType.LPAREN)) {
+                if (!this.check(TokenType.RPAREN)) {
+                    do {
+                        const nameValue = this.nameValueItem('module argument');
+                        moduleArgs[nameValue.name] = nameValue.value && nameValue.value.type === 'literal'
+                            ? getSyncLiteral(nameValue.value)
+                            : (nameValue.value && nameValue.value.type === 'identifier' ? nameValue.value.name : nameValue.name);
+                    } while (this.match(TokenType.COMMA));
                 }
+                this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
+            }
+        }
+        // Parse mutation context definitions if present
+        let contextDefinitions;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('CONTEXT')) {
+                contextDefinitions = this.parseMutationContextDefinitions();
+            }
+            else {
+                // Not a WITH CONTEXT clause, backtrack
+                this.current--;
             }
         }
         return {
@@ -1807,6 +1953,7 @@ export class Parser {
             isTemporary,
             moduleName,
             moduleArgs,
+            contextDefinitions,
             loc: _createLoc(startToken, this.previous()),
         };
     }
@@ -1872,7 +2019,7 @@ export class Parser {
             if (!this.check(TokenType.RPAREN)) {
                 do {
                     columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in view column list."));
-                } while (this.match(TokenType.COMMA));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             this.consume(TokenType.RPAREN, "Expected ')' after view column list.");
         }
@@ -1889,6 +2036,23 @@ export class Parser {
             loc: _createLoc(startToken, this.previous()),
         };
     }
+    /**
+     * Parse CREATE ASSERTION statement
+     * @returns AST for CREATE ASSERTION
+     */
+    createAssertionStatement(startToken, _withClause) {
+        const name = this.consumeIdentifier("Expected assertion name.");
+        this.consumeKeyword('CHECK', "Expected 'CHECK' after assertion name.");
+        this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
+        const check = this.expression();
+        this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
+        return {
+            type: 'createAssertion',
+            name,
+            check,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
     /**
      * Parse DROP statement
      * @returns AST for DROP statement
@@ -1907,8 +2071,12 @@ export class Parser {
             this.consumeKeyword('INDEX', "Expected INDEX after DROP.");
             objectType = 'index';
         }
+        else if (this.peekKeyword('ASSERTION')) {
+            this.consumeKeyword('ASSERTION', "Expected ASSERTION after DROP.");
+            objectType = 'assertion';
+        }
         else {
-            throw this.error(this.peek(), "Expected TABLE, VIEW, or INDEX after DROP.");
+            throw this.error(this.peek(), "Expected TABLE, VIEW, INDEX, or ASSERTION after DROP.");
         }
         let ifExists = false;
         if (this.matchKeyword('IF')) {
@@ -2046,6 +2214,296 @@ export class Parser {
         const nameValue = this.nameValueItem("pragma");
         return { type: 'pragma', ...nameValue, loc: _createLoc(startToken, this.previous()) };
     }
+    // === Declarative schema parsing ===
+    declareSchemaStatement(startToken) {
+        this.consumeKeyword('SCHEMA', "Expected 'SCHEMA' after DECLARE.");
+        const schemaName = this.consumeIdentifier(['temp', 'temporary'], "Expected schema name after DECLARE.");
+        let version;
+        let using;
+        // Optional: version 'semver'
+        // no-op
+        if (this.matchKeyword('VERSION')) {
+            const tok = this.consume(TokenType.STRING, "Expected version string after VERSION.");
+            version = String(tok.literal);
+        }
+        // Optional: using ( default_vtab_module = 'memory', default_vtab_args = '[]' )
+        if (this.match(TokenType.USING)) {
+            this.consume(TokenType.LPAREN, "Expected '(' after USING.");
+            using = {};
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    const optName = this.consumeIdentifier("Expected option name inside USING().").toLowerCase();
+                    this.consume(TokenType.EQUAL, "Expected '=' after option name in USING().");
+                    if (optName === 'default_vtab_module') {
+                        const t = this.consume(TokenType.STRING, "Expected string for default_vtab_module.");
+                        using.defaultVtabModule = String(t.literal);
+                    }
+                    else if (optName === 'default_vtab_args') {
+                        const t = this.consume(TokenType.STRING, "Expected JSON string for default_vtab_args.");
+                        using.defaultVtabArgs = String(t.literal);
+                    }
+                    else {
+                        // Consume simple literal/identifier for forward compatibility
+                        if (this.check(TokenType.STRING) || this.check(TokenType.INTEGER) || this.check(TokenType.FLOAT) || this.check(TokenType.IDENTIFIER)) {
+                            this.advance();
+                        }
+                    }
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after USING options.");
+        }
+        // Block
+        // Parse declaration block delimited by '{' '}'
+        this.consume(TokenType.LBRACE, "Expected '{' to start schema declaration block.");
+        const items = [];
+        while (!this.check(TokenType.RBRACE)) {
+            if (this.isAtEnd())
+                break;
+            // table ...
+            if (this.peekKeyword('TABLE')) {
+                this.advance();
+                items.push(this.declareTableItem());
+            }
+            else if (this.peekKeyword('INDEX')) {
+                this.advance();
+                items.push(this.declareIndexItem());
+            }
+            else if (this.peekKeyword('VIEW')) {
+                this.advance();
+                items.push(this.declareViewItem());
+            }
+            else if (this.peekKeyword('SEED')) {
+                this.advance();
+                items.push(this.declareSeedItem());
+            }
+            else {
+                // Fallback: ignore unrecognized item (domain, collation, import)
+                const start = this.peek();
+                // consume until semicolon
+                while (!this.isAtEnd() && !this.check(TokenType.SEMICOLON) && !(this.check(TokenType.IDENTIFIER) && this.peek().lexeme === '}')) {
+                    this.advance();
+                }
+                const endTok = this.previous();
+                items.push({ type: 'declareIgnored', kind: 'domain', text: this.sourceSlice(start.startOffset, endTok.endOffset) });
+            }
+            this.match(TokenType.SEMICOLON);
+        }
+        this.consume(TokenType.RBRACE, "Expected '}' to close schema declaration block.");
+        const endTok = this.previous();
+        return { type: 'declareSchema', schemaName, version, using, items, loc: _createLoc(startToken, endTok) };
+    }
+    declareTableItem() {
+        const tableName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], 'Expected table name in declaration.');
+        let moduleName;
+        let moduleArgs;
+        const columns = [];
+        const constraints = [];
+        // Optional USING module
+        if (this.match(TokenType.USING)) {
+            if (this.check(TokenType.IDENTIFIER)) {
+                moduleName = this.advance().lexeme;
+            }
+            if (this.match(TokenType.LPAREN)) {
+                moduleArgs = {};
+                if (!this.check(TokenType.RPAREN)) {
+                    do {
+                        const nv = this.nameValueItem('module argument');
+                        moduleArgs[nv.name] = nv.value && nv.value.type === 'literal' ? getSyncLiteral(nv.value) : (nv.value && nv.value.type === 'identifier' ? nv.value.name : null);
+                    } while (this.match(TokenType.COMMA));
+                }
+                this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
+            }
+        }
+        // Column list can be in parens (...) or braces {...}
+        const useBraces = this.check(TokenType.LBRACE);
+        if (useBraces) {
+            this.consume(TokenType.LBRACE, "Expected '{' before column definitions.");
+        }
+        else {
+            this.consume(TokenType.LPAREN, "Expected '(' or '{' before column definitions.");
+        }
+        if (!this.check(useBraces ? TokenType.RBRACE : TokenType.RPAREN)) {
+            do {
+                // Distinguish table constraint vs column definition by lookahead for '(' or constraint keywords
+                if (this.peekKeyword('CONSTRAINT') || this.peekKeyword('PRIMARY') || this.peekKeyword('UNIQUE') || this.peekKeyword('CHECK') || this.peekKeyword('FOREIGN')) {
+                    constraints.push(this.tableConstraint());
+                }
+                else {
+                    columns.push(this.columnDefinition());
+                }
+            } while (this.match(TokenType.COMMA) && !this.check(useBraces ? TokenType.RBRACE : TokenType.RPAREN));
+        }
+        if (useBraces) {
+            this.consume(TokenType.RBRACE, "Expected '}' after table definition.");
+        }
+        else {
+            this.consume(TokenType.RPAREN, "Expected ')' after table definition.");
+        }
+        // Build the CREATE TABLE AST node for this declared table
+        const tableStmt = {
+            type: 'createTable',
+            table: { type: 'identifier', name: tableName },
+            ifNotExists: false,
+            columns,
+            constraints,
+            isTemporary: false,
+            moduleName,
+            moduleArgs
+        };
+        return { type: 'declaredTable', tableStmt };
+    }
+    declareIndexItem() {
+        const indexName = this.consumeIdentifier('Expected index name.');
+        this.consumeKeyword('ON', "Expected 'ON' after index name.");
+        const tableName = this.consumeIdentifier('Expected table name after ON.');
+        this.consume(TokenType.LPAREN, "Expected '(' before index columns.");
+        const columns = this.indexedColumnList();
+        this.consume(TokenType.RPAREN, "Expected ')' after index columns.");
+        const indexStmt = {
+            type: 'createIndex',
+            index: { type: 'identifier', name: indexName },
+            table: { type: 'identifier', name: tableName },
+            ifNotExists: false,
+            columns,
+            isUnique: false
+        };
+        return { type: 'declaredIndex', indexStmt };
+    }
+    declareViewItem() {
+        const viewName = this.consumeIdentifier('Expected view name.');
+        let columns;
+        if (this.match(TokenType.LPAREN)) {
+            columns = this.identifierList();
+            this.consume(TokenType.RPAREN, "Expected ')' after view columns.");
+        }
+        this.consumeKeyword('AS', "Expected AS before SELECT in view declaration.");
+        const selTok = this.consume(TokenType.SELECT, "Expected SELECT after AS in view declaration.");
+        const select = this.selectStatement(selTok);
+        const viewStmt = {
+            type: 'createView',
+            view: { type: 'identifier', name: viewName },
+            ifNotExists: false,
+            columns,
+            select,
+            isTemporary: false
+        };
+        return { type: 'declaredView', viewStmt };
+    }
+    declareSeedItem() {
+        // seed <table> ( (...), (...) ) or seed <table> values (col, ...) values (...), (...)
+        const tableName = this.consumeIdentifier('Expected table name after SEED.');
+        let columns;
+        const rows = [];
+        // Check for column list syntax: seed table (cols...) values (...)
+        if (this.matchKeyword('VALUES')) {
+            this.consume(TokenType.LPAREN, "Expected '(' before seed column list.");
+            columns = this.identifierList();
+            this.consume(TokenType.RPAREN, "Expected ')' after seed column list.");
+            this.consumeKeyword('VALUES', "Expected VALUES to introduce seed rows.");
+        }
+        // Parse seed rows: ( (...), (...) )
+        this.consume(TokenType.LPAREN, "Expected '(' before seed rows.");
+        do {
+            this.consume(TokenType.LPAREN, "Expected '(' before seed row values.");
+            const rowValues = [];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    const expr = this.expression();
+                    // Evaluate literal expressions to SqlValue
+                    if (expr.type === 'literal') {
+                        rowValues.push(getSyncLiteral(expr));
+                    }
+                    else {
+                        throw this.error(this.peek(), "Seed data must contain only literal values.");
+                    }
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after seed row values.");
+            rows.push(rowValues);
+        } while (this.match(TokenType.COMMA));
+        this.consume(TokenType.RPAREN, "Expected ')' after seed rows.");
+        return { type: 'declaredSeed', tableName, columns, seedData: rows };
+    }
+    diffSchemaStatement(startToken) {
+        this.consumeKeyword('SCHEMA', "Expected SCHEMA after DIFF.");
+        const schemaName = this.consumeIdentifier(['temp', 'temporary'], 'Expected schema name after DIFF SCHEMA.');
+        return { type: 'diffSchema', schemaName, loc: _createLoc(startToken, this.previous()) };
+    }
+    applySchemaStatement(startToken) {
+        this.consumeKeyword('SCHEMA', "Expected SCHEMA after APPLY.");
+        const schemaName = this.consumeIdentifier(['temp', 'temporary'], 'Expected schema name after APPLY SCHEMA.');
+        let toVersion;
+        let withSeed = false;
+        let options;
+        if (this.matchKeyword('TO')) {
+            this.consumeKeyword('VERSION', "Expected VERSION after TO.");
+            const tok = this.consume(TokenType.STRING, "Expected version string after TO VERSION.");
+            toVersion = String(tok.literal);
+        }
+        // Check for WITH SEED
+        if (this.matchKeyword('WITH')) {
+            this.consumeKeyword('SEED', "Expected SEED after WITH.");
+            withSeed = true;
+        }
+        if (this.matchKeyword('OPTIONS')) {
+            this.consume(TokenType.LPAREN, "Expected '(' after OPTIONS.");
+            options = {};
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    const key = this.consumeIdentifier('Expected option key.').toLowerCase();
+                    this.consume(TokenType.EQUAL, "Expected '=' after option key.");
+                    if (key === 'dry_run')
+                        options.dryRun = this.consumeBooleanLiteral();
+                    else if (key === 'validate_only')
+                        options.validateOnly = this.consumeBooleanLiteral();
+                    else if (key === 'allow_destructive')
+                        options.allowDestructive = this.consumeBooleanLiteral();
+                    else if (key === 'rename_policy') {
+                        const vtok = this.consume(TokenType.STRING, "Expected string for rename_policy.");
+                        options.renamePolicy = String(vtok.literal);
+                    }
+                    else {
+                        // consume literal
+                        if (this.check(TokenType.STRING) || this.check(TokenType.INTEGER) || this.check(TokenType.FLOAT) || this.check(TokenType.IDENTIFIER))
+                            this.advance();
+                    }
+                } while (this.match(TokenType.COMMA));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after OPTIONS.");
+        }
+        return { type: 'applySchema', schemaName, toVersion, withSeed, options, loc: _createLoc(startToken, this.previous()) };
+    }
+    explainSchemaStatement(startToken) {
+        this.consumeKeyword('SCHEMA', "Expected SCHEMA after EXPLAIN.");
+        const schemaName = this.consumeIdentifier(['temp', 'temporary'], 'Expected schema name after EXPLAIN SCHEMA.');
+        let version;
+        if (this.matchKeyword('VERSION')) {
+            const tok = this.consume(TokenType.STRING, "Expected version string after VERSION.");
+            version = String(tok.literal);
+        }
+        return { type: 'explainSchema', schemaName, version, loc: _createLoc(startToken, this.previous()) };
+    }
+    consumeBooleanLiteral() {
+        if (this.match(TokenType.TRUE))
+            return true;
+        if (this.match(TokenType.FALSE))
+            return false;
+        if (this.check(TokenType.STRING)) {
+            const t = this.advance();
+            const v = String(t.literal).toLowerCase();
+            return v === 'true' || v === '1';
+        }
+        if (this.check(TokenType.INTEGER)) {
+            const t = this.advance();
+            return Number(t.literal) !== 0;
+        }
+        return false;
+    }
+    sourceSlice(_start, _end) {
+        // Lexer tokens include offsets; this.tokens array belongs to this parser, but we don't have direct source here.
+        // Return an empty string as placeholder; canonicalization is future work.
+        return '';
+    }
     nameValueItem(context) {
         const name = this.consumeIdentifier(`Expected ${context} name.`);
         let value;
@@ -2218,6 +2676,50 @@ export class Parser {
         const constraints = this.columnConstraintList();
         return { name, dataType, constraints };
     }
+    /** @internal Parses mutation context variable definitions: WITH CONTEXT (var type [NULL], ...) */
+    parseMutationContextDefinitions() {
+        this.consume(TokenType.LPAREN, "Expected '(' after WITH CONTEXT.");
+        const contextVars = [];
+        do {
+            const name = this.consumeIdentifier("Expected context variable name.");
+            let dataType;
+            if (this.check(TokenType.IDENTIFIER)) {
+                dataType = this.advance().lexeme;
+                if (this.match(TokenType.LPAREN)) {
+                    dataType += '(';
+                    let parenLevel = 1;
+                    while (parenLevel > 0 && !this.isAtEnd()) {
+                        const token = this.peek();
+                        if (token.type === TokenType.LPAREN)
+                            parenLevel++;
+                        if (token.type === TokenType.RPAREN)
+                            parenLevel--;
+                        if (parenLevel > 0) {
+                            dataType += this.advance().lexeme;
+                        }
+                    }
+                    dataType += ')';
+                    this.consume(TokenType.RPAREN, "Expected ')' after type parameters.");
+                }
+            }
+            // Check for NULL keyword (explicit nullable marker)
+            const notNull = !this.match(TokenType.NULL);
+            contextVars.push({ name, dataType, notNull });
+        } while (this.match(TokenType.COMMA));
+        this.consume(TokenType.RPAREN, "Expected ')' after mutation context definitions.");
+        return contextVars;
+    }
+    /** @internal Parses mutation context assignments: WITH CONTEXT var = expr, ... */
+    parseContextAssignments() {
+        const assignments = [];
+        do {
+            const name = this.consumeIdentifier("Expected context variable name.");
+            this.consume(TokenType.EQUAL, `Expected '=' after context variable '${name}'.`);
+            const value = this.expression();
+            assignments.push({ name, value });
+        } while (this.match(TokenType.COMMA));
+        return assignments;
+    }
     /** @internal Parses column constraints */
     columnConstraintList() {
         const constraints = [];
@@ -2293,7 +2795,14 @@ export class Parser {
             this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
             const expr = this.expression();
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
-            return { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
+            // No DEFERRABLE syntax supported; deferral is auto-detected by the planner
+            return {
+                type: 'check',
+                name,
+                expr,
+                operations,
+                loc: _createLoc(startToken, endToken)
+            };
         }
         else if (this.match(TokenType.DEFAULT)) {
             const expr = this.expression();
@@ -2375,7 +2884,14 @@ export class Parser {
             this.consume(TokenType.LPAREN, "Expected '(' after CHECK.");
             const expr = this.expression();
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CHECK expression.");
-            return { type: 'check', name, expr, operations, loc: _createLoc(startToken, endToken) };
+            // No DEFERRABLE syntax supported; deferral is auto-detected by the planner
+            return {
+                type: 'check',
+                name,
+                expr,
+                operations,
+                loc: _createLoc(startToken, endToken)
+            };
         }
         else if (this.match(TokenType.FOREIGN)) {
             this.consume(TokenType.KEY, "Expected KEY after FOREIGN.");