@quereus/quereus 3.2.1 → 4.0.0

package/dist/src/parser/parser.js

@@ -1,5 +1,5 @@
 import { createLogger } from '../common/logger.js'; // Import logger
-import { Lexer, TokenType } from './lexer.js';
+import { Lexer, TokenType, CONTEXTUAL_KEYWORDS } from './lexer.js';
 import { ConflictResolution } from '../common/constants.js';
 import { quereusError, QuereusError } from '../common/errors.js';
 import { StatusCode } from '../common/types.js';
@@ -32,8 +32,8 @@ function _createLoc(startToken, endToken) {
 /**
  * IMPORTANT: Any changes to parsed syntax must also be reflected in the corresponding emitters:
  *   - packages/quereus/src/emit/ast-stringify.ts          (AST-to-SQL string conversion)
- *   - packages/quereus/src/schema/catalog.ts              (DDL generation for catalog/hashing)
- *   - packages/quereus-store/src/common/ddl-generator.ts  (DDL generation for persistence)
+ *   - packages/quereus/src/schema/catalog.ts              (CREATE ASSERTION DDL for catalog/hashing)
+ *   - packages/quereus/src/schema/ddl-generator.ts        (canonical DDL generation for persistence)
  * If only the parser is updated, SQL round-trips and persisted schemas will silently lose the new syntax.
  */
 export class Parser {
@@ -168,20 +168,108 @@ export class Parser {
         const endToken = this.previous(); // Last token of the WITH clause
         return { type: 'with', recursive, ctes, options, loc: _createLoc(startToken, endToken) };
     }
+    /**
+     * Parses a relation-producing query expression (`QueryExpr`):
+     * `[WITH …] (SELECT | VALUES | INSERT|UPDATE|DELETE)`.
+     *
+     * `outerWithContext` is an outer WITH already consumed by the caller and
+     * forwarded into inner statements purely for CTE-resolution context (the
+     * planner reads CTE definitions out of `select.withClause`). It is NOT
+     * stored on the returned node — that already happened at the outer site.
+     *
+     * If the body itself leads with `WITH`, that inner WITH is consumed here
+     * and attached to the resulting statement. The two WITH clauses do not
+     * mix: an inner body-level WITH wins.
+     *
+     * `requireReturning` enforces the rule that DML used in non-top-level
+     * relation positions (FROM subquery, scalar / IN / EXISTS subquery,
+     * compound leg, CTE body, view body) must carry a RETURNING clause —
+     * the outer position consumes a relation, not a side-effect.
+     */
+    parseQueryExpr(outerWithContext, requireReturning = false) {
+        // Inner body-level WITH (e.g. `(WITH t AS (…) SELECT … FROM t)`). The
+        // inner WITH is owned by the produced statement; we still pass it down
+        // to the inner builder for the same resolution-context reason and
+        // re-attach explicitly so callers that swap it out (rename rewriter,
+        // declared-schema canonicaliser) see a consistent shape.
+        let innerWith;
+        if (this.check(TokenType.WITH)) {
+            innerWith = this.tryParseWithClause();
+        }
+        const resolutionContext = innerWith ?? outerWithContext;
+        const startToken = this.peek();
+        let stmt;
+        if (this.check(TokenType.LPAREN)) {
+            // A parenthesized query expression `( <query-expr> )` is a valid first
+            // operand (view body / CTE body / FROM-subquery / scalar subquery all
+            // funnel here). Read it, then run the shared left-associative tail so
+            // `(…) union …` chains. Pure grouping (no compound follows) returns the
+            // inner expression unchanged — `(select 1)` ≡ `select 1`.
+            const firstOperand = this.parseCompoundOperand(resolutionContext, requireReturning);
+            stmt = this.checkCompoundOperator()
+                ? this.parseCompoundTail(firstOperand, resolutionContext, startToken)
+                : firstOperand;
+        }
+        else {
+            const kw = startToken.lexeme.toUpperCase();
+            switch (kw) {
+                case 'SELECT':
+                    this.advance();
+                    stmt = this.selectStatement(startToken, resolutionContext);
+                    break;
+                case 'VALUES':
+                    this.advance();
+                    stmt = this.valuesStatementWithOptionalCompound(startToken, resolutionContext);
+                    break;
+                case 'INSERT':
+                    this.advance();
+                    stmt = this.insertStatement(startToken, resolutionContext);
+                    break;
+                case 'UPDATE':
+                    this.advance();
+                    stmt = this.updateStatement(startToken, resolutionContext);
+                    break;
+                case 'DELETE':
+                    this.advance();
+                    stmt = this.deleteStatement(startToken, resolutionContext);
+                    break;
+                default:
+                    throw this.error(startToken, "Expected SELECT, VALUES, INSERT, UPDATE, or DELETE in query expression.");
+            }
+        }
+        if (innerWith) {
+            if (this.statementSupportsWithClause(stmt)) {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                stmt.withClause = innerWith;
+                if (innerWith.loc && stmt.loc) {
+                    stmt.loc.start = innerWith.loc.start;
+                }
+            }
+            else {
+                throw this.error(this.previous(), `WITH clause cannot be used with ${stmt.type} statement.`);
+            }
+        }
+        if (requireReturning && (stmt.type === 'insert' || stmt.type === 'update' || stmt.type === 'delete')) {
+            if (!stmt.returning || stmt.returning.length === 0) {
+                throw this.error(this.previous(), `${stmt.type.toUpperCase()} in a relation position must have a RETURNING clause.`);
+            }
+        }
+        return stmt;
+    }
     /**
      * Parses a single Common Table Expression (CTE).
      * cte_name [(col1, col2, ...)] AS (query)
      */
     commonTableExpression() {
         const startToken = this.peek(); // Peek before consuming name
-        const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'like'], "Expected CTE name.");
+        const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected CTE name.");
         let endToken = this.previous(); // End token initially is the name
         let columns;
         if (this.match(TokenType.LPAREN)) {
             columns = [];
             if (!this.check(TokenType.RPAREN)) {
                 do {
-                    columns.push(this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'like'], "Expected column name in CTE definition."));
+                    columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in CTE definition."));
                 } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after CTE column list.");
@@ -196,29 +284,8 @@ export class Parser {
             materializationHint = 'not_materialized';
         }
         this.consume(TokenType.LPAREN, "Expected '(' before CTE query.");
-        // Parse the CTE query (can be SELECT, VALUES (via SELECT), INSERT, UPDATE, DELETE)
-        const queryStartToken = this.peek();
-        let query;
-        if (this.check(TokenType.SELECT)) {
-            this.advance(); // Consume SELECT token
-            query = this.selectStatement(queryStartToken); // Pass start token
-        }
-        else if (this.check(TokenType.INSERT)) {
-            this.advance(); // Consume INSERT token
-            query = this.insertStatement(queryStartToken);
-        }
-        else if (this.check(TokenType.UPDATE)) {
-            this.advance(); // Consume UPDATE token
-            query = this.updateStatement(queryStartToken);
-        }
-        else if (this.check(TokenType.DELETE)) {
-            this.advance(); // Consume DELETE token
-            query = this.deleteStatement(queryStartToken);
-        }
-        // TODO: Add support for VALUES directly if needed (though VALUES is usually part of SELECT)
-        else {
-            throw this.error(this.peek(), "Expected SELECT, INSERT, UPDATE, or DELETE statement for CTE query.");
-        }
+        // CTE body is any QueryExpr; DML bodies must carry RETURNING.
+        const query = this.parseQueryExpr(undefined, /*requireReturning*/ true);
         endToken = this.consume(TokenType.RPAREN, "Expected ')' after CTE query."); // Capture ')' as end token
         return { type: 'commonTableExpr', name, columns, query, materializationHint, loc: _createLoc(startToken, endToken) };
     }
@@ -235,89 +302,106 @@ export class Parser {
         // --- Check for specific keywords first ---
         const currentKeyword = startToken.lexeme.toUpperCase();
         let stmt;
-        switch (currentKeyword) {
-            case 'SELECT':
-                this.advance();
-                stmt = this.selectStatement(startToken, withClause);
-                break;
-            case 'INSERT':
-                this.advance();
-                stmt = this.insertStatement(startToken, withClause);
-                break;
-            case 'UPDATE':
-                this.advance();
-                stmt = this.updateStatement(startToken, withClause);
-                break;
-            case 'DELETE':
-                this.advance();
-                stmt = this.deleteStatement(startToken, withClause);
-                break;
-            case 'VALUES':
-                this.advance();
-                stmt = this.valuesStatement(startToken);
-                break;
-            case 'CREATE':
-                this.advance();
-                stmt = this.createStatement(startToken, withClause);
-                break;
-            case 'DROP':
-                this.advance();
-                stmt = this.dropStatement(startToken, withClause);
-                break;
-            case 'ALTER':
-                this.advance();
-                stmt = this.alterTableStatement(startToken, withClause);
-                break;
-            case 'BEGIN':
-                this.advance();
-                stmt = this.beginStatement(startToken, withClause);
-                break;
-            case 'COMMIT':
-                this.advance();
-                stmt = this.commitStatement(startToken, withClause);
-                break;
-            case 'ROLLBACK':
-                this.advance();
-                stmt = this.rollbackStatement(startToken, withClause);
-                break;
-            case 'SAVEPOINT':
-                this.advance();
-                stmt = this.savepointStatement(startToken, withClause);
-                break;
-            case 'RELEASE':
-                this.advance();
-                stmt = this.releaseStatement(startToken, withClause);
-                break;
-            // TODO: Replace pragmas with build-in functions
-            case 'PRAGMA':
-                this.advance();
-                stmt = this.pragmaStatement(startToken, withClause);
-                break;
-            case 'ANALYZE':
-                this.advance();
-                stmt = this.analyzeStatement(startToken);
-                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
-                throw this.error(startToken, `Expected statement type (SELECT, INSERT, UPDATE, DELETE, VALUES, CREATE, etc.), got '${startToken.lexeme}'.`);
+        // A leading `(` is a parenthesized query expression at top level
+        // (`(select 1) union (select 2);` — SQLite parity). `parseQueryExpr`
+        // reads the operand and any compound tail; the post-switch WITH-attach
+        // below still folds an outer `with … (select …) union …` in.
+        if (this.check(TokenType.LPAREN)) {
+            stmt = this.parseQueryExpr(withClause);
         }
+        else
+            switch (currentKeyword) {
+                case 'SELECT':
+                    this.advance();
+                    stmt = this.selectStatement(startToken, withClause);
+                    break;
+                case 'INSERT':
+                    this.advance();
+                    stmt = this.insertStatement(startToken, withClause);
+                    break;
+                case 'UPDATE':
+                    this.advance();
+                    stmt = this.updateStatement(startToken, withClause);
+                    break;
+                case 'DELETE':
+                    this.advance();
+                    stmt = this.deleteStatement(startToken, withClause);
+                    break;
+                case 'VALUES':
+                    this.advance();
+                    stmt = this.valuesStatementWithOptionalCompound(startToken, withClause);
+                    break;
+                case 'CREATE':
+                    this.advance();
+                    stmt = this.createStatement(startToken, withClause);
+                    break;
+                case 'REFRESH':
+                    this.advance();
+                    stmt = this.refreshStatement(startToken, withClause);
+                    break;
+                case 'DROP':
+                    this.advance();
+                    stmt = this.dropStatement(startToken, withClause);
+                    break;
+                case 'ALTER':
+                    this.advance();
+                    stmt = this.alterStatement(startToken, withClause);
+                    break;
+                case 'BEGIN':
+                    this.advance();
+                    stmt = this.beginStatement(startToken, withClause);
+                    break;
+                case 'COMMIT':
+                    this.advance();
+                    stmt = this.commitStatement(startToken, withClause);
+                    break;
+                case 'ROLLBACK':
+                    this.advance();
+                    stmt = this.rollbackStatement(startToken, withClause);
+                    break;
+                case 'SAVEPOINT':
+                    this.advance();
+                    stmt = this.savepointStatement(startToken, withClause);
+                    break;
+                case 'RELEASE':
+                    this.advance();
+                    stmt = this.releaseStatement(startToken, withClause);
+                    break;
+                // TODO: Replace pragmas with build-in functions
+                case 'PRAGMA':
+                    this.advance();
+                    stmt = this.pragmaStatement(startToken, withClause);
+                    break;
+                case 'ANALYZE':
+                    this.advance();
+                    stmt = this.analyzeStatement(startToken);
+                    break;
+                case 'DECLARE': {
+                    this.advance();
+                    // `declare lens …` is a sibling statement, not a `declare schema`
+                    // variant: branch on the contextual LENS keyword.
+                    stmt = this.peekKeyword('LENS')
+                        ? this.declareLensStatement(startToken)
+                        : 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
+                    throw this.error(startToken, `Expected statement type (SELECT, INSERT, UPDATE, DELETE, VALUES, CREATE, etc.), got '${startToken.lexeme}'.`);
+            }
         // Attach WITH clause if present and supported
         if (withClause && this.statementSupportsWithClause(stmt)) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -356,62 +440,56 @@ export class Parser {
         this.matchKeyword('INTO'); // Handle missing keyword gracefully
         // Parse the table reference
         const table = this.tableIdentifier();
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
         // Parse column list if provided
         let columns;
         if (this.match(TokenType.LPAREN)) {
             columns = [];
             do {
-                if (!this.checkIdentifierLike(contextualKeywords)) {
+                if (!this.checkIdentifierLike(CONTEXTUAL_KEYWORDS)) {
                     throw this.error(this.peek(), "Expected column name.");
                 }
                 columns.push(this.getIdentifierValue(this.advance()));
             } 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)
-        // Note: Can also appear after VALUES/SELECT via parseTrailingWithClauses
+        // Parse mutation context assignments and/or tags if present (after column
+        // list, before VALUES/SELECT). Either may also appear trailing (after
+        // VALUES/SELECT) via parseTrailingWithClauses.
         let contextValues;
-        if (this.matchKeyword('WITH')) {
+        let tags;
+        while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
                 contextValues = this.parseContextAssignments();
             }
+            else if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT clause, backtrack
+                // Not a WITH CONTEXT / WITH TAGS clause, backtrack
                 this.current--;
+                break;
             }
         }
-        // Parse VALUES clause
-        let values;
-        let select;
-        let lastConsumedToken = this.previous(); // After columns or table id
-        if (this.match(TokenType.VALUES)) {
-            values = [];
-            do {
-                this.consume(TokenType.LPAREN, "Expected '(' before values.");
-                const valueList = [];
-                if (!this.check(TokenType.RPAREN)) { // Check for empty value list
-                    do {
-                        valueList.push(this.expression());
-                    } while (this.match(TokenType.COMMA));
-                }
-                this.consume(TokenType.RPAREN, "Expected ')' after values.");
-                values.push(valueList);
-                lastConsumedToken = this.previous(); // Update after closing paren of value list
-            } while (this.match(TokenType.COMMA));
-        }
-        else if (this.check(TokenType.SELECT)) { // If current token is SELECT
-            // Handle INSERT ... SELECT
-            // Consume the SELECT token, as selectStatement expects to start parsing after it.
-            // selectKeywordToken will be the actual 'SELECT' token object, used for location.
-            const selectKeywordToken = this.advance(); // Consume 'SELECT'
-            // Pass the withClause so the embedded SELECT can (via the planner) resolve CTEs defined for the INSERT.
-            select = this.selectStatement(selectKeywordToken, withClause);
-            lastConsumedToken = this.previous(); // After SELECT statement is parsed
-        }
-        else {
-            throw this.error(this.peek(), "Expected VALUES or SELECT after INSERT.");
+        // Parse the source: VALUES / SELECT / INSERT|UPDATE|DELETE with RETURNING.
+        // The outer INSERT consumes the resulting relation, so DML sources must
+        // carry RETURNING — parseQueryExpr enforces that when requireReturning
+        // is true. Pure VALUES / SELECT are passed through unchanged.
+        const sourceStartKeyword = this.peek().lexeme.toUpperCase();
+        let source;
+        switch (sourceStartKeyword) {
+            case 'VALUES':
+            case 'SELECT':
+                source = this.parseQueryExpr(withClause, /*requireReturning*/ false);
+                break;
+            case 'INSERT':
+            case 'UPDATE':
+            case 'DELETE':
+                source = this.parseQueryExpr(withClause, /*requireReturning*/ true);
+                break;
+            default:
+                throw this.error(this.peek(), "Expected VALUES, SELECT, or DML (with RETURNING) after INSERT.");
         }
+        let lastConsumedToken = this.previous(); // After source statement is parsed
         // Parse UPSERT clauses (ON CONFLICT DO ...) - can have multiple
         let upsertClauses;
         while (this.match(TokenType.ON)) {
@@ -438,6 +516,13 @@ export class Parser {
             }
             contextValues = trailingClauses.contextValues;
         }
+        if (trailingClauses.tags) {
+            if (tags) {
+                throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+            }
+            tags = trailingClauses.tags;
+            lastConsumedToken = this.previous(); // After tags
+        }
         const schemaPath = trailingClauses.schemaPath;
         if (schemaPath) {
             lastConsumedToken = this.previous(); // After schema path
@@ -452,13 +537,13 @@ export class Parser {
             type: 'insert',
             table,
             columns,
-            values,
-            select,
+            source,
             onConflict,
             upsertClauses,
             returning,
             contextValues,
             schemaPath,
+            tags,
             loc: _createLoc(startToken, lastConsumedToken),
         };
     }
@@ -524,29 +609,19 @@ export class Parser {
      */
     selectStatement(startToken, withClause, isCompoundSubquery = false) {
         const start = startToken ?? this.previous(); // Use provided or the keyword token
-        let lastConsumedToken = start; // Initialize lastConsumed
         const distinct = this.matchKeyword('DISTINCT');
-        if (distinct)
-            lastConsumedToken = this.previous();
         const all = !distinct && this.matchKeyword('ALL');
-        if (all)
-            lastConsumedToken = this.previous();
         // Parse column list
         const columns = this.columnList();
-        if (columns.length > 0)
-            lastConsumedToken = this.previous(); // Update after last column element
         // Parse FROM clause if present
         let from;
         if (this.match(TokenType.FROM)) {
             from = this.tableSourceList(withClause);
-            if (from.length > 0)
-                lastConsumedToken = this.previous(); // After last source/join
         }
         // Parse WHERE clause if present
         let where;
         if (this.match(TokenType.WHERE)) {
             where = this.expression();
-            lastConsumedToken = this.previous(); // After where expression
         }
         // Parse GROUP BY clause if present
         let groupBy;
@@ -555,69 +630,180 @@ export class Parser {
             do {
                 groupBy.push(this.expression());
             } while (this.match(TokenType.COMMA));
-            lastConsumedToken = this.previous(); // After last group by expression
         }
         // Parse HAVING clause if present
         let having;
         if (this.match(TokenType.HAVING)) {
             having = this.expression();
-            lastConsumedToken = this.previous(); // After having expression
         }
-        // Parse WITH SCHEMA clause if present (must come before ORDER BY/LIMIT)
+        // Parse WITH SCHEMA clause if present (must come before compound / ORDER BY / LIMIT
+        // and is suppressed in compound-subquery position).
         let schemaPath;
         if (!isCompoundSubquery) {
             schemaPath = this.parseSchemaPath();
-            if (schemaPath) {
-                lastConsumedToken = this.previous(); // After schema path
-            }
-        }
-        // Check for compound set operations (UNION / INTERSECT / EXCEPT) BEFORE ORDER BY/LIMIT
-        let compound;
-        if (this.match(TokenType.UNION, TokenType.INTERSECT, TokenType.EXCEPT, TokenType.DIFF)) {
-            const tok = this.previous();
-            let op;
-            if (tok.type === TokenType.UNION) {
-                if (this.match(TokenType.ALL)) {
-                    op = 'unionAll';
-                }
-                else {
-                    op = 'union';
-                }
-            }
-            else if (tok.type === TokenType.INTERSECT) {
-                op = 'intersect';
-            }
-            else if (tok.type === TokenType.EXCEPT) {
-                op = 'except';
-            }
-            else {
-                op = 'diff';
-            }
-            let rightSelect;
-            // Handle parenthesized subquery after set operation
-            if (this.match(TokenType.LPAREN)) {
-                const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in parenthesized set operation.");
-                rightSelect = this.selectStatement(selectToken, withClause, true); // Pass true to indicate compound subquery
-                this.consume(TokenType.RPAREN, "Expected ')' after parenthesized set operation.");
-            }
-            else {
-                // Handle direct SELECT statement
-                const selectStartToken = this.peek();
-                if (this.match(TokenType.SELECT)) {
-                    rightSelect = this.selectStatement(selectStartToken, withClause, true); // Pass true to indicate compound subquery
-                }
-                else {
-                    throw this.error(this.peek(), "Expected 'SELECT' or '(' after set operation keyword.");
-                }
-            }
-            lastConsumedToken = this.previous();
-            compound = { op, select: rightSelect };
         }
-        // Parse ORDER BY clause if present (applies to final result after compound operations)
-        // Skip if this is a compound subquery as ORDER BY belongs to the outer compound
-        let orderBy;
-        if (!isCompoundSubquery && this.match(TokenType.ORDER) && this.consume(TokenType.BY, "Expected 'BY' after 'ORDER'.")) {
-            orderBy = [];
+        const sel = {
+            type: 'select',
+            columns,
+            from,
+            where,
+            groupBy,
+            having,
+            distinct,
+            all,
+            schemaPath,
+            loc: _createLoc(start, this.previous()),
+        };
+        // Compound set operations (UNION / INTERSECT / EXCEPT / DIFF) bind BEFORE
+        // ORDER BY / LIMIT — delegate to the shared left-associative tail parser.
+        const result = this.parseCompoundTail(sel, withClause, start);
+        // ORDER BY / LIMIT / OFFSET apply to the final compound result; suppressed
+        // for a compound subquery (they bind to the outer compound).
+        this.parseTrailingOrderLimit(result, isCompoundSubquery);
+        // Trailing `with defaults (col = expr, …)` — binds to the whole compound,
+        // after limit/offset and before any DDL-level `with tags`. Suppressed on a
+        // compound leg (it belongs to the outer compound, like trailing ORDER BY).
+        if (!isCompoundSubquery) {
+            const defaults = this.parseDefaultsClause();
+            if (defaults)
+                result.defaults = defaults;
+        }
+        result.loc = _createLoc(start, this.previous());
+        return result;
+    }
+    /** True when the next token is a compound set-operation keyword. */
+    checkCompoundOperator() {
+        return this.check(TokenType.UNION)
+            || this.check(TokenType.INTERSECT)
+            || this.check(TokenType.EXCEPT)
+            || this.check(TokenType.DIFF);
+    }
+    /**
+     * Decode a compound set-operation operator the caller has just consumed
+     * (via `match`), plus the optional `<setop> exists <branch> as <name>`
+     * membership-column clause(s) that sit between the operator keyword and the
+     * right leg. One-token lookahead (`exists` followed by `left`/`right`, never
+     * `(`) distinguishes the membership clause from the `exists (<subquery>)`
+     * predicate, which never legally begins a compound leg.
+     */
+    parseCompoundOperator() {
+        const tok = this.previous();
+        let op;
+        if (tok.type === TokenType.UNION) {
+            op = this.match(TokenType.ALL) ? 'unionAll' : 'union';
+        }
+        else if (tok.type === TokenType.INTERSECT) {
+            op = 'intersect';
+        }
+        else if (tok.type === TokenType.EXCEPT) {
+            op = 'except';
+        }
+        else {
+            op = 'diff';
+        }
+        const existence = this.setOpMembershipClauses(op);
+        return existence ? { op, existence } : { op };
+    }
+    /**
+     * Reads a single `query-term` operand of a set operation: either a
+     * parenthesized query expression `( <query-expr> )` (full recursion — WITH,
+     * nested compound, and the inner's OWN trailing ORDER BY / LIMIT all bind
+     * inside the parens) or a bare keyword-led operand (SELECT / VALUES / DML).
+     *
+     * Bare SELECT / VALUES legs parse with `isCompoundSubquery=true` so a
+     * trailing ORDER BY / LIMIT binds to the OUTER compound, and a bare SELECT
+     * leg greedily consumes the remaining unparenthesized chain (preserving the
+     * historical right-leaning shape). `requireReturning` is propagated so a
+     * DML operand without RETURNING in a leg position is rejected.
+     */
+    parseCompoundOperand(withClause, requireReturning) {
+        if (this.check(TokenType.LPAREN)) {
+            this.advance();
+            const inner = this.parseQueryExpr(withClause, requireReturning);
+            this.consume(TokenType.RPAREN, "Expected ')' after parenthesized query expression.");
+            return inner;
+        }
+        const start = this.peek();
+        if (this.check(TokenType.SELECT)) {
+            this.advance();
+            return this.selectStatement(start, withClause, /*isCompoundSubquery*/ true);
+        }
+        if (this.check(TokenType.VALUES)) {
+            this.advance();
+            return this.valuesStatementWithOptionalCompound(start, withClause, /*isCompoundSubquery*/ true);
+        }
+        if (this.check(TokenType.WITH) || this.check(TokenType.INSERT) || this.check(TokenType.UPDATE) || this.check(TokenType.DELETE)) {
+            return this.parseQueryExpr(undefined, requireReturning);
+        }
+        throw this.error(this.peek(), "Expected SELECT, VALUES, a DML statement, or '(' to begin a query operand.");
+    }
+    /**
+     * Wraps an arbitrary query expression as `select * from (<inner>) as
+     * <synthetic alias>` so the SELECT-level `compound` / ORDER BY / LIMIT slots
+     * apply to it. Generalized from the VALUES-compound wrapper; the synthetic
+     * alias is collision-proof per the inner's start offset (nested wraps live in
+     * distinct subquery scopes, so identical aliases never collide).
+     */
+    wrapAsSubquerySelect(inner, startToken) {
+        const syntheticAlias = `values_${startToken.startOffset}`;
+        return {
+            type: 'select',
+            columns: [{ type: 'all' }],
+            from: [{
+                    type: 'subquerySource',
+                    subquery: inner,
+                    alias: syntheticAlias,
+                    loc: inner.loc,
+                }],
+            loc: inner.loc,
+        };
+    }
+    /**
+     * Left-associative tail parser shared by every compound site. Consumes a
+     * chain of `compound-op [membership] query-term` after an already-parsed
+     * left operand and returns the resulting SELECT.
+     *
+     * A parenthesized operand iterates the loop (left-associative), wrapping the
+     * accumulator whenever it cannot host the new compound — either it is not a
+     * plain SELECT (e.g. a parenthesized VALUES/DML/compound operand) or its
+     * `compound` slot is already taken. The first BARE keyword operand greedily
+     * consumes the rest of the chain itself (its own `selectStatement` /
+     * `valuesStatementWithOptionalCompound` recursion), so an unparenthesized
+     * chain keeps today's right-leaning shape byte-for-byte. The user's explicit
+     * parentheses are the only escape hatch into left-grouping.
+     */
+    parseCompoundTail(left, withClause, startToken) {
+        let acc = left;
+        while (this.match(TokenType.UNION, TokenType.INTERSECT, TokenType.EXCEPT, TokenType.DIFF)) {
+            const { op, existence } = this.parseCompoundOperator();
+            const parenthesized = this.check(TokenType.LPAREN);
+            const right = this.parseCompoundOperand(withClause, /*requireReturning*/ true);
+            if (acc.type !== 'select' || acc.compound) {
+                acc = this.wrapAsSubquerySelect(acc, startToken);
+            }
+            acc.compound = existence ? { op, select: right, existence } : { op, select: right };
+            if (!parenthesized)
+                break; // a bare operand already consumed the remaining chain
+        }
+        // `left` is a SelectStmt at every call site that may take zero iterations
+        // (selectStatement / continueSelectAfterFrom); the parenthesized entry only
+        // delegates here once a compound operator follows, and any iteration leaves
+        // `acc` a SELECT — so the result is always a SelectStmt.
+        return acc;
+    }
+    /**
+     * Parses the trailing ORDER BY / LIMIT / OFFSET clauses that apply to the
+     * final result of a (possibly compound) SELECT, mutating `sel` in place.
+     * Suppressed entirely when `isCompoundSubquery` is set — those clauses then
+     * bind to the enclosing compound, not this leg. Shared by `selectStatement`
+     * and `continueSelectAfterFrom`.
+     */
+    parseTrailingOrderLimit(sel, isCompoundSubquery) {
+        if (isCompoundSubquery)
+            return;
+        // ORDER BY applies to the final result after compound operations.
+        if (this.match(TokenType.ORDER) && this.consume(TokenType.BY, "Expected 'BY' after 'ORDER'.")) {
+            sel.orderBy = [];
             do {
                 const expr = this.expression();
                 const direction = this.match(TokenType.DESC) ? 'desc' :
@@ -639,64 +825,42 @@ export class Parser {
                 if (nulls) {
                     orderClause.nulls = nulls;
                 }
-                orderBy.push(orderClause);
+                sel.orderBy.push(orderClause);
             } while (this.match(TokenType.COMMA));
-            lastConsumedToken = this.previous(); // After last order by clause
-        }
-        // Parse LIMIT clause if present (applies to final result after compound operations)
-        // Skip if this is a compound subquery as LIMIT belongs to the outer compound
-        let limit;
-        let offset;
-        if (!isCompoundSubquery && this.match(TokenType.LIMIT)) {
-            limit = this.expression();
-            lastConsumedToken = this.previous(); // After limit expression
+        }
+        // LIMIT applies to the final result after compound operations.
+        if (this.match(TokenType.LIMIT)) {
+            sel.limit = this.expression();
             // LIMIT x OFFSET y syntax
             if (this.match(TokenType.OFFSET)) {
-                offset = this.expression();
-                lastConsumedToken = this.previous(); // After offset expression
+                sel.offset = this.expression();
             }
             // LIMIT x, y syntax (x is offset, y is limit)
             else if (this.match(TokenType.COMMA)) {
-                offset = limit;
-                limit = this.expression();
-                lastConsumedToken = this.previous(); // After second limit expression
+                sel.offset = sel.limit;
+                sel.limit = this.expression();
             }
         }
-        return {
-            type: 'select',
-            columns,
-            from,
-            where,
-            groupBy,
-            having,
-            orderBy,
-            limit,
-            offset,
-            distinct,
-            all,
-            compound,
-            schemaPath,
-            loc: _createLoc(start, lastConsumedToken),
-        };
     }
     /**
      * Parse a comma-separated list of result columns for SELECT
      */
     columnList() {
         const columns = [];
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
         do {
             // Handle wildcard: * or table.*
             if (this.match(TokenType.ASTERISK)) {
                 columns.push({ type: 'all' });
+                this.rejectInverseClauseOnStar();
             }
             // Handle table.* syntax
-            else if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT) &&
+            else if (this.checkIdentifierLike(CONTEXTUAL_KEYWORDS) && this.checkNext(1, TokenType.DOT) &&
                 this.checkNext(2, TokenType.ASTERISK)) {
-                const table = this.consumeIdentifier(contextualKeywords, "Expected table name before '.*'.");
+                const table = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected table name before '.*'.");
                 this.advance(); // consume DOT
                 this.advance(); // consume ASTERISK
                 columns.push({ type: 'all', table });
+                this.rejectInverseClauseOnStar();
             }
             // Handle regular column expression
             else {
@@ -704,7 +868,7 @@ export class Parser {
                 let alias;
                 // Handle AS alias or just alias
                 if (this.match(TokenType.AS)) {
-                    if (this.checkIdentifierLike(contextualKeywords) || this.check(TokenType.STRING)) {
+                    if (this.checkIdentifierLike(CONTEXTUAL_KEYWORDS) || this.check(TokenType.STRING)) {
                         const aliasToken = this.advance();
                         // For STRING tokens, use literal; for identifiers, use getIdentifierValue
                         alias = aliasToken.type === TokenType.STRING
@@ -724,7 +888,10 @@ export class Parser {
                     const aliasToken = this.advance();
                     alias = this.getIdentifierValue(aliasToken);
                 }
-                columns.push({ type: 'column', expr, alias });
+                // Optional trailing `with inverse (col = expr, …)` — authored
+                // write-back expressions (docs/view-updateability.md § Authored inverses)
+                const inverse = this.parseInverseClause();
+                columns.push({ type: 'column', expr, alias, inverse });
             }
         } while (this.match(TokenType.COMMA));
         return columns;
@@ -737,7 +904,7 @@ export class Parser {
         let schema;
         let name;
         let endToken = startToken;
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like', 'temp', 'temporary'];
+        const contextualKeywords = [...CONTEXTUAL_KEYWORDS, 'temp', 'temporary'];
         // Check for schema.table pattern
         if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT)) {
             schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
@@ -780,23 +947,15 @@ export class Parser {
      */
     tableSource(withClause) {
         const startToken = this.peek();
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
-        // Check for subquery: ( SELECT ... or ( VALUES ... or ( WITH ... or ( INSERT/UPDATE/DELETE ...
-        if (this.check(TokenType.LPAREN)) {
-            // Look ahead to see if this is a subquery
-            const lookahead = this.current + 1;
-            if (lookahead < this.tokens.length) {
-                const nextTokenType = this.tokens[lookahead].type;
-                if (nextTokenType === TokenType.SELECT || nextTokenType === TokenType.VALUES || nextTokenType === TokenType.WITH) {
-                    return this.subquerySource(startToken, withClause);
-                }
-                else if (nextTokenType === TokenType.INSERT || nextTokenType === TokenType.UPDATE || nextTokenType === TokenType.DELETE) {
-                    return this.mutatingSubquerySource(startToken, withClause);
-                }
-            }
+        // Subquery: any QueryExpr in parens. Decision is made on the token
+        // immediately after `(`; all relation-producing forms (SELECT, VALUES,
+        // WITH …, INSERT|UPDATE|DELETE w/ RETURNING) flow through the same
+        // subquerySource path.
+        if (this.startsParenSubquery()) {
+            return this.subquerySource(startToken, withClause);
         }
         // Check for function call syntax: IDENTIFIER (
-        if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.LPAREN)) {
+        if (this.checkIdentifierLike(CONTEXTUAL_KEYWORDS) && this.checkNext(1, TokenType.LPAREN)) {
             return this.functionSource(startToken);
         }
         // Otherwise, assume it's a standard table source
@@ -804,31 +963,22 @@ export class Parser {
             return this.standardTableSource(startToken);
         }
     }
-    /** Parses a subquery source: (SELECT ...) AS alias */
-    subquerySource(startToken, withClause) {
+    /**
+     * Parses a subquery source: `(<QueryExpr>) [AS alias [(cols)]]`.
+     *
+     * Accepts any relation-producing form (SELECT, VALUES, WITH …, or
+     * INSERT/UPDATE/DELETE with RETURNING). The DML branch is enforced to
+     * carry RETURNING because the outer FROM-clause position consumes a
+     * relation, not a side-effect.
+     *
+     * `requireAlias` mandates an explicit user-written alias rather than synthesizing
+     * a default — set for an inline-subquery DML *write target* (`update (select …) as
+     * v set …`), whose `alias` is user-meaningful (the `where`/`set` reference it). A
+     * FROM-clause subquery leaves it false and keeps the generated-alias fallback.
+     */
+    subquerySource(startToken, withClause, requireAlias = false) {
         this.consume(TokenType.LPAREN, "Expected '(' before subquery.");
-        let subquery;
-        if (this.check(TokenType.WITH)) {
-            // (WITH ... SELECT ...) — the WITH attaches to the inner SELECT.
-            const innerWith = this.tryParseWithClause();
-            const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' after WITH in subquery.");
-            const sel = this.selectStatement(selectToken, innerWith);
-            sel.withClause = innerWith;
-            subquery = sel;
-        }
-        else if (this.check(TokenType.SELECT)) {
-            // Consume the SELECT token and pass it as startToken to selectStatement
-            const selectToken = this.advance();
-            subquery = this.selectStatement(selectToken, withClause);
-        }
-        else if (this.check(TokenType.VALUES)) {
-            // Handle VALUES subquery
-            const valuesToken = this.advance();
-            subquery = this.valuesStatement(valuesToken);
-        }
-        else {
-            throw this.error(this.peek(), "Expected 'SELECT', 'VALUES', or 'WITH' in subquery.");
-        }
+        const subquery = this.parseQueryExpr(withClause, /*requireReturning*/ true);
         this.consume(TokenType.RPAREN, "Expected ')' after subquery.");
         // Parse optional alias for subquery
         let alias;
@@ -846,17 +996,24 @@ export class Parser {
             !this.isEndOfClause()) {
             alias = this.getIdentifierValue(this.advance());
         }
+        else if (requireAlias) {
+            // A subquery write target's alias is mandatory and user-meaningful — never a
+            // generated default (the `where`/`set` reference it). Reject the bare form.
+            throw this.error(this.peek(), "a subquery UPDATE/DELETE write target requires an alias, e.g. (select …) as v");
+        }
         else {
-            // Generate a default alias if none provided
-            alias = `subquery_${startToken.startOffset}`;
+            // Generate a default alias if none provided. Keep separate prefixes
+            // for read-only vs mutating bodies so generated aliases stay
+            // distinguishable when surfacing in diagnostics.
+            const isMutating = subquery.type === 'insert' || subquery.type === 'update' || subquery.type === 'delete';
+            alias = `${isMutating ? 'mutating_subquery' : 'subquery'}_${startToken.startOffset}`;
         }
         // Parse optional column list after alias: AS alias(col1, col2, ...)
         if (this.match(TokenType.LPAREN)) {
             columns = [];
-            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
             if (!this.check(TokenType.RPAREN)) {
                 do {
-                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
+                    columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in alias column list."));
                 } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
@@ -870,80 +1027,49 @@ export class Parser {
             loc: _createLoc(startToken, endToken),
         };
     }
-    /** Parses a mutating subquery source: (INSERT/UPDATE/DELETE ... RETURNING ...) AS alias */
-    mutatingSubquerySource(startToken, withClause) {
-        this.consume(TokenType.LPAREN, "Expected '(' before mutating subquery.");
-        let stmt;
-        if (this.check(TokenType.INSERT)) {
-            const insertToken = this.advance();
-            stmt = this.insertStatement(insertToken, withClause);
-        }
-        else if (this.check(TokenType.UPDATE)) {
-            const updateToken = this.advance();
-            stmt = this.updateStatement(updateToken, withClause);
-        }
-        else if (this.check(TokenType.DELETE)) {
-            const deleteToken = this.advance();
-            stmt = this.deleteStatement(deleteToken, withClause);
-        }
-        else {
-            throw this.error(this.peek(), "Expected 'INSERT', 'UPDATE', or 'DELETE' in mutating subquery.");
-        }
-        // Validate that the statement has a RETURNING clause
-        if (!stmt.returning || stmt.returning.length === 0) {
-            throw this.error(this.previous(), "Mutating subqueries must have a RETURNING clause to be used as table sources.");
-        }
-        this.consume(TokenType.RPAREN, "Expected ')' after mutating subquery.");
-        // Parse optional alias for mutating subquery
-        let alias;
-        let columns;
-        if (this.match(TokenType.AS)) {
-            if (!this.checkIdentifierLike([])) {
-                throw this.error(this.peek(), "Expected alias after 'AS'.");
-            }
-            alias = this.getIdentifierValue(this.advance());
-        }
-        else if (this.checkIdentifierLike([]) &&
-            !this.checkNext(1, TokenType.DOT) &&
-            !this.checkNext(1, TokenType.COMMA) &&
-            !this.isJoinToken() &&
-            !this.isEndOfClause()) {
-            alias = this.getIdentifierValue(this.advance());
-        }
-        else {
-            // Generate a default alias if none provided
-            alias = `mutating_subquery_${startToken.startOffset}`;
-        }
-        // Parse optional column list after alias: AS alias(col1, col2, ...)
-        if (this.match(TokenType.LPAREN)) {
-            columns = [];
-            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
-            if (!this.check(TokenType.RPAREN)) {
-                do {
-                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in alias column list."));
-                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
-            }
-            this.consume(TokenType.RPAREN, "Expected ')' after alias column list.");
-        }
-        const endToken = this.previous();
-        return {
-            type: 'mutatingSubquerySource',
-            stmt,
-            alias,
-            columns,
-            loc: _createLoc(startToken, endToken),
-        };
+    /**
+     * Detect and parse a leading inline-subquery DML write target — `(<query>) as v` —
+     * for `update`/`delete`, or `undefined` when the next tokens are not a `(` followed
+     * by a relation-producing keyword (the SAME lookahead {@link tableSource} uses for a
+     * FROM subquery). The alias is mandatory (`requireAlias`); the body re-uses the
+     * shared {@link subquerySource} production, so it requires RETURNING on a DML body
+     * (rejected as a write target downstream) and parses the `as v` / `v(a,b)` alias.
+     */
+    subqueryDmlTarget(withClause) {
+        if (!this.startsParenSubquery())
+            return undefined;
+        return this.subquerySource(this.peek(), withClause, /*requireAlias*/ true);
+    }
+    /**
+     * True when the cursor is at `(` followed by a relation-producing keyword
+     * (`SELECT` / `VALUES` / `WITH` / a DML keyword) — i.e. the start of a
+     * parenthesized subquery source. Shared by the FROM-clause {@link tableSource}
+     * and the inline-subquery DML target {@link subqueryDmlTarget} so the lookahead
+     * set stays defined once.
+     */
+    startsParenSubquery() {
+        if (!this.check(TokenType.LPAREN))
+            return false;
+        const lookahead = this.current + 1;
+        if (lookahead >= this.tokens.length)
+            return false;
+        const nextTokenType = this.tokens[lookahead].type;
+        return (nextTokenType === TokenType.SELECT
+            || nextTokenType === TokenType.VALUES
+            || nextTokenType === TokenType.WITH
+            || nextTokenType === TokenType.INSERT
+            || nextTokenType === TokenType.UPDATE
+            || nextTokenType === TokenType.DELETE);
     }
     /** Parses a standard table source (schema.table or table) */
     standardTableSource(startToken) {
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
         // Parse table name (potentially schema-qualified)
         const table = this.tableIdentifier();
         let endToken = this.previous(); // Initialize endToken after parsing table identifier
         // Parse optional alias
         let alias;
         if (this.match(TokenType.AS)) {
-            if (!this.checkIdentifierLike(contextualKeywords)) {
+            if (!this.checkIdentifierLike(CONTEXTUAL_KEYWORDS)) {
                 throw this.error(this.peek(), "Expected alias after 'AS'.");
             }
             const aliasToken = this.advance();
@@ -968,7 +1094,6 @@ export class Parser {
     }
     /** Parses a table-valued function source: name(arg1, ...) [AS alias] */
     functionSource(startToken) {
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
         const name = this.tableIdentifier(); // name has its own loc
         let endToken = this.previous(); // Initialize endToken after parsing function identifier
         this.consume(TokenType.LPAREN, "Expected '(' after table function name.");
@@ -999,7 +1124,7 @@ export class Parser {
         let alias;
         let columns;
         if (this.match(TokenType.AS)) {
-            if (!this.checkIdentifierLike(contextualKeywords)) {
+            if (!this.checkIdentifierLike(CONTEXTUAL_KEYWORDS)) {
                 throw this.error(this.peek(), "Expected alias after 'AS'.");
             }
             const aliasToken = this.advance();
@@ -1018,10 +1143,9 @@ export class Parser {
         // 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."));
+                    columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "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.");
@@ -1077,15 +1201,22 @@ export class Parser {
         else if (this.match(TokenType.USING)) {
             this.consume(TokenType.LPAREN, "Expected '(' after 'USING'.");
             columns = [];
-            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
             do {
-                columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name."));
+                columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name."));
             } while (this.match(TokenType.COMMA));
             endToken = this.consume(TokenType.RPAREN, "Expected ')' after columns.");
         }
         else if (joinType !== 'cross') {
             throw this.error(this.peek(), "Expected 'ON' or 'USING' after JOIN.");
         }
+        // Optional `exists [left|right] as <name>` existence column clause(s), after a
+        // complete ON/USING predicate. One-token lookahead after `exists` (an `as` or
+        // side token, never `(`) distinguishes this from the `exists (<subquery>)`
+        // predicate; the comma form is recognised only when followed by another
+        // `exists`, so a genuine new FROM source comma is left for `tableSourceList`.
+        const existence = this.joinExistenceClauses(joinType);
+        if (existence)
+            endToken = this.previous();
         return {
             type: 'join',
             joinType,
@@ -1094,9 +1225,99 @@ export class Parser {
             condition,
             columns,
             isLateral: isLateral || undefined,
+            existence,
             loc: _createLoc(joinStartToken, endToken),
         };
     }
+    /**
+     * Parse the optional comma-separated `exists [left|right] as <name>` clauses
+     * trailing a join. Returns `undefined` when none are present. Resolves and
+     * validates the side against the join type (default = the unique non-preserved
+     * side; explicit side required for `full`; `inner`/`cross` rejected — no
+     * null-extension means the flag would be a meaningless constant `true`).
+     */
+    joinExistenceClauses(joinType) {
+        // `exists` here must be followed by `as` or a side token, never `(` (which
+        // would be the `exists (<subquery>)` predicate). Bail before consuming if the
+        // lookahead does not match the clause shape.
+        const atExistenceClause = () => this.check(TokenType.EXISTS) &&
+            (this.checkNext(1, TokenType.AS) || this.checkNext(1, TokenType.LEFT) || this.checkNext(1, TokenType.RIGHT));
+        if (!atExistenceClause())
+            return undefined;
+        const result = [];
+        do {
+            this.consume(TokenType.EXISTS, "Expected 'exists'.");
+            let explicitSide;
+            if (this.match(TokenType.LEFT))
+                explicitSide = 'left';
+            else if (this.match(TokenType.RIGHT))
+                explicitSide = 'right';
+            this.consume(TokenType.AS, "Expected 'as' after 'exists' join existence clause.");
+            const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected name after 'exists ... as'.");
+            result.push({ side: this.resolveExistenceSide(joinType, explicitSide), name });
+            // Continue only on `, exists ...`; a plain comma starts a new FROM source.
+        } while (this.check(TokenType.COMMA) && this.checkNext(1, TokenType.EXISTS) && this.advance());
+        return result;
+    }
+    /**
+     * Resolve and validate the side of an `exists [<side>] as` join existence
+     * clause. The flag must reference a null-extendable (non-preserved) side.
+     */
+    resolveExistenceSide(joinType, explicitSide) {
+        // Non-preserved (null-extendable) sides per join type.
+        const nonPreserved = joinType === 'left' ? ['right']
+            : joinType === 'right' ? ['left']
+                : joinType === 'full' ? ['left', 'right']
+                    : []; // inner / cross: neither side null-extends
+        if (nonPreserved.length === 0) {
+            throw this.error(this.previous(), `'exists ... as' is not valid on an ${joinType.toUpperCase()} join (no side is null-extended, so the flag would be a constant true)`);
+        }
+        if (explicitSide) {
+            if (!nonPreserved.includes(explicitSide)) {
+                throw this.error(this.previous(), `'exists ${explicitSide} as' references the preserved side of a ${joinType.toUpperCase()} join; only the non-preserved side (${nonPreserved.join('/')}) has a meaningful match flag`);
+            }
+            return explicitSide;
+        }
+        if (nonPreserved.length > 1) {
+            throw this.error(this.previous(), `'exists as' is ambiguous on a ${joinType.toUpperCase()} join — specify 'exists left as' or 'exists right as'`);
+        }
+        return nonPreserved[0];
+    }
+    /**
+     * Parse the optional comma-separated `exists <branch> as <name>` membership
+     * clauses that sit between a set-operation keyword and its right leg. Returns
+     * `undefined` when none are present. The `branch` is mandatory (`left` = the leg
+     * already parsed before the operator, `right` = the operand that follows) — there
+     * is no elided form, so `exists` here is ALWAYS followed by `left`/`right`, never
+     * `(`; that one-token lookahead distinguishes the clause from the
+     * `exists (<subquery>)` predicate. Rejected on `diff` (symmetric difference
+     * desugars to two `except`s, so membership is ambiguous).
+     */
+    setOpMembershipClauses(op) {
+        const atMembershipClause = () => this.check(TokenType.EXISTS) &&
+            (this.checkNext(1, TokenType.LEFT) || this.checkNext(1, TokenType.RIGHT));
+        if (!atMembershipClause())
+            return undefined;
+        if (op === 'diff') {
+            throw this.error(this.peek(), "'exists <branch> as' membership columns are not valid on DIFF — symmetric difference desugars to two EXCEPTs, so branch membership is ambiguous");
+        }
+        const result = [];
+        do {
+            this.consume(TokenType.EXISTS, "Expected 'exists'.");
+            let branch;
+            if (this.match(TokenType.LEFT))
+                branch = 'left';
+            else if (this.match(TokenType.RIGHT))
+                branch = 'right';
+            else
+                throw this.error(this.peek(), "Expected 'left' or 'right' after 'exists' in a set-operation membership clause.");
+            this.consume(TokenType.AS, "Expected 'as' after 'exists <branch>' membership clause.");
+            const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected name after 'exists <branch> as'.");
+            result.push({ branch, name });
+            // Continue only on `, exists ...`; a plain comma starts the next leg / clause boundary.
+        } while (this.check(TokenType.COMMA) && this.checkNext(1, TokenType.EXISTS) && this.advance());
+        return result;
+    }
     /**
      * Parse a left-associative chain of binary operators.
      * Captures the start token before parsing the first operand, avoiding O(n) token lookups.
@@ -1146,12 +1367,16 @@ export class Parser {
             const right = this.notExpression();
             return { type: 'unary', operator: 'NOT', expr: right, loc: _createLoc(operatorToken, this.previous()) };
         }
-        return this.isNull();
+        return this.isPredicate();
     }
     /**
-     * Parse IS NULL / IS NOT NULL expressions
+     * Parse the postfix IS predicates, each a unary postfix operator on the
+     * operand: `IS [NOT] NULL`, `IS [NOT] TRUE`, `IS [NOT] FALSE`. A general
+     * `IS <expr>` (anything other than NULL/TRUE/FALSE) is unsupported — we
+     * backtrack the consumed `IS [NOT]` so the caller surfaces the same error
+     * as before.
      */
-    isNull() {
+    isPredicate() {
         const startToken = this.peek();
         const expr = this.equality();
         if (this.match(TokenType.IS)) {
@@ -1160,7 +1385,15 @@ export class Parser {
                 const operator = isNot ? 'IS NOT NULL' : 'IS NULL';
                 return { type: 'unary', operator, expr, loc: _createLoc(startToken, this.previous()) };
             }
-            // IS [NOT] not followed by NULL — backtrack
+            if (this.match(TokenType.TRUE)) {
+                const operator = isNot ? 'IS NOT TRUE' : 'IS TRUE';
+                return { type: 'unary', operator, expr, loc: _createLoc(startToken, this.previous()) };
+            }
+            if (this.match(TokenType.FALSE)) {
+                const operator = isNot ? 'IS NOT FALSE' : 'IS FALSE';
+                return { type: 'unary', operator, expr, loc: _createLoc(startToken, this.previous()) };
+            }
+            // IS [NOT] not followed by NULL/TRUE/FALSE — backtrack the IS [NOT].
             if (isNot)
                 this.current--;
             this.current--;
@@ -1193,10 +1426,9 @@ export class Parser {
                 if (this.match(TokenType.IN)) {
                     // NOT IN
                     this.consume(TokenType.LPAREN, "Expected '(' after NOT IN.");
-                    if (this.check(TokenType.SELECT)) {
-                        // NOT IN subquery: expr NOT IN (SELECT ...)
-                        const selectToken = this.advance(); // Consume SELECT
-                        const subquery = this.selectStatement(selectToken);
+                    if (this.checkSubqueryStart()) {
+                        // NOT IN subquery: expr NOT IN (<QueryExpr>)
+                        const subquery = this.parseQueryExpr(undefined, /*requireReturning*/ true);
                         const endToken = this.consume(TokenType.RPAREN, "Expected ')' after NOT IN subquery.");
                         // Create an IN expression with subquery, then wrap in NOT
                         const inExpr = {
@@ -1306,13 +1538,12 @@ export class Parser {
                 };
             }
             else if (operatorToken.type === TokenType.IN) {
-                // Parse IN expression: expr IN (value1, value2, ...) or expr IN (subquery)
+                // Parse IN expression: expr IN (value1, value2, ...) or expr IN (<QueryExpr>)
                 this.consume(TokenType.LPAREN, "Expected '(' after IN.");
                 // Check if this is a subquery or value list
-                if (this.check(TokenType.SELECT)) {
-                    // IN subquery: expr IN (SELECT ...)
-                    const selectToken = this.advance(); // Consume SELECT
-                    const subquery = this.selectStatement(selectToken);
+                if (this.checkSubqueryStart()) {
+                    // IN subquery: expr IN (<QueryExpr>)
+                    const subquery = this.parseQueryExpr(undefined, /*requireReturning*/ true);
                     const endToken = this.consume(TokenType.RPAREN, "Expected ')' after IN subquery.");
                     // Create an IN expression with subquery
                     expr = {
@@ -1410,7 +1641,9 @@ export class Parser {
         const expr = this.jsonPath();
         if (this.matchKeyword('COLLATE')) {
             const collationToken = this.consume(TokenType.IDENTIFIER, "Expected collation name after COLLATE.");
-            return { type: 'collate', expr, collation: collationToken.lexeme, loc: _createLoc(startToken, collationToken) };
+            // getIdentifierValue strips the quotes from a quoted collation name (e.g.
+            // `collate "select"`); using the raw lexeme would embed them in the value.
+            return { type: 'collate', expr, collation: this.getIdentifierValue(collationToken), loc: _createLoc(startToken, collationToken) };
         }
         return expr;
     }
@@ -1493,12 +1726,11 @@ export class Parser {
             const endToken = this.consume(TokenType.RPAREN, "Expected ')' after CAST expression type.");
             return { type: 'cast', expr, targetType, loc: _createLoc(castToken, endToken) };
         }
-        // EXISTS expression: EXISTS(SELECT ...)
+        // EXISTS expression: EXISTS(<QueryExpr>)
         if (this.match(TokenType.EXISTS)) {
             const existsToken = this.previous();
             this.consume(TokenType.LPAREN, "Expected '(' after EXISTS.");
-            const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in EXISTS subquery.");
-            const subquery = this.selectStatement(selectToken);
+            const subquery = this.parseQueryExpr(undefined, /*requireReturning*/ true);
             const endToken = this.consume(TokenType.RPAREN, "Expected ')' after EXISTS subquery.");
             return {
                 type: 'exists',
@@ -1558,8 +1790,8 @@ export class Parser {
             return { type: 'parameter', name: nameToken.lexeme, loc: _createLoc(startToken, nameToken) };
         }
         // Function call (with optional window function support)
-        if (this.checkIdentifierLike(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like', 'replace']) && this.checkNext(1, TokenType.LPAREN)) {
-            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like', 'replace'], "Expected function name.");
+        if (this.checkIdentifierLike([...CONTEXTUAL_KEYWORDS, 'replace']) && this.checkNext(1, TokenType.LPAREN)) {
+            const name = this.consumeIdentifier([...CONTEXTUAL_KEYWORDS, 'replace'], "Expected function name.");
             this.consume(TokenType.LPAREN, "Expected '(' after function name.");
             const args = [];
             let distinct = false;
@@ -1609,16 +1841,15 @@ export class Parser {
             return funcExpr;
         }
         // Column/identifier expressions
-        const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
-        if (this.checkIdentifierLike(contextualKeywords)) {
+        if (this.checkIdentifierLike(CONTEXTUAL_KEYWORDS)) {
             // Schema.table.column
-            if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, contextualKeywords) &&
-                this.checkNext(3, TokenType.DOT) && this.checkIdentifierLikeAt(4, contextualKeywords)) {
-                const schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
+            if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, CONTEXTUAL_KEYWORDS) &&
+                this.checkNext(3, TokenType.DOT) && this.checkIdentifierLikeAt(4, CONTEXTUAL_KEYWORDS)) {
+                const schema = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected schema name.");
                 this.advance(); // Consume DOT
-                const table = this.consumeIdentifier(contextualKeywords, "Expected table name.");
+                const table = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected table name.");
                 this.advance(); // Consume DOT
-                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name.");
                 const nameToken = this.previous();
                 return {
                     type: 'column',
@@ -1629,10 +1860,10 @@ export class Parser {
                 };
             }
             // table.column
-            else if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, contextualKeywords)) {
-                const table = this.consumeIdentifier(contextualKeywords, "Expected table name.");
+            else if (this.checkNext(1, TokenType.DOT) && this.checkIdentifierLikeAt(2, CONTEXTUAL_KEYWORDS)) {
+                const table = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected table name.");
                 this.advance(); // Consume DOT
-                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name.");
                 const nameToken = this.previous();
                 return {
                     type: 'column',
@@ -1643,7 +1874,7 @@ export class Parser {
             }
             // just column
             else {
-                const name = this.consumeIdentifier(contextualKeywords, "Expected column name.");
+                const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name.");
                 const nameToken = this.previous();
                 return {
                     type: 'column',
@@ -1652,12 +1883,12 @@ export class Parser {
                 };
             }
         }
-        // Parenthesized expression or scalar subquery
+        // Parenthesized expression or scalar / row subquery.
+        // A leading SELECT/VALUES/WITH/INSERT/UPDATE/DELETE here disambiguates
+        // to a subquery; anything else is a parenthesized scalar expression.
         if (this.match(TokenType.LPAREN)) {
-            // Look ahead to see if this is a scalar subquery (SELECT ...)
-            if (this.check(TokenType.SELECT)) {
-                const selectToken = this.consume(TokenType.SELECT, "Expected 'SELECT' in subquery.");
-                const subquery = this.selectStatement(selectToken);
+            if (this.checkSubqueryStart()) {
+                const subquery = this.parseQueryExpr(undefined, /*requireReturning*/ true);
                 this.consume(TokenType.RPAREN, "Expected ')' after subquery.");
                 return {
                     type: 'subquery',
@@ -1810,6 +2041,23 @@ export class Parser {
             return false;
         return this.tokens[this.current + n].type === type;
     }
+    /**
+     * Non-consuming lookahead for a trailing `with defaults` clause — `WITH`
+     * followed by the contextual `DEFAULTS` keyword (an IDENTIFIER lexeme, since
+     * DEFAULTS is not reserved). Used by the VALUES trailing-clause path to decide
+     * whether to wrap `VALUES …` as `SELECT * FROM (VALUES …)` so the select spine's
+     * {@link parseDefaultsClause} can consume the clause — exactly how a trailing
+     * ORDER BY / LIMIT on VALUES already wraps. A trailing `WITH TAGS` (DDL-level)
+     * never matches, so it stays with the outer DDL parser.
+     */
+    checkWithDefaults() {
+        if (!this.check(TokenType.WITH))
+            return false;
+        const next = this.tokens[this.current + 1];
+        return next !== undefined
+            && next.type === TokenType.IDENTIFIER
+            && next.lexeme.toUpperCase() === 'DEFAULTS';
+    }
     advance() {
         if (!this.isAtEnd())
             this.current++;
@@ -1870,6 +2118,19 @@ export class Parser {
             this.check(TokenType.FULL) ||
             this.check(TokenType.CROSS);
     }
+    /**
+     * True when the current token starts a `QueryExpr` (SELECT, VALUES, WITH,
+     * INSERT, UPDATE, DELETE). Used by callers that have already consumed an
+     * `(` to decide between a subquery and a parenthesized scalar expression.
+     */
+    checkSubqueryStart() {
+        return this.check(TokenType.SELECT)
+            || this.check(TokenType.VALUES)
+            || this.check(TokenType.WITH)
+            || this.check(TokenType.INSERT)
+            || this.check(TokenType.UPDATE)
+            || this.check(TokenType.DELETE);
+    }
     isEndOfClause() {
         const token = this.peek().type;
         return token === TokenType.FROM ||
@@ -1884,23 +2145,36 @@ export class Parser {
     }
     // --- Statement Parsing Stubs ---
     /** @internal */
-    updateStatement(startToken, _withClause) {
-        const table = this.tableIdentifier();
-        // Parse mutation context assignments if present (can also appear after WHERE)
+    updateStatement(startToken, withClause) {
+        // Inline subquery target: `update (select …) as v set …`. When present, the
+        // alias is the target's correlation name; mirror it into a synthetic placeholder
+        // `table` (= the alias) so generic `stmt.table.name` reads stay total, and carry
+        // it on `alias`. Otherwise fall through to the ordinary named/CTE target.
+        const targetSource = this.subqueryDmlTarget(withClause);
+        const table = targetSource
+            ? { type: 'identifier', name: targetSource.alias, loc: targetSource.loc }
+            : this.tableIdentifier();
+        // Parse mutation context assignments and/or tags if present (either may also
+        // appear trailing, after WHERE, via parseTrailingWithClauses).
         let contextValues;
-        if (this.matchKeyword('WITH')) {
+        let tags;
+        while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
                 contextValues = this.parseContextAssignments();
             }
+            else if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT clause, backtrack
+                // Not a WITH CONTEXT / WITH TAGS clause, backtrack
                 this.current--;
+                break;
             }
         }
         this.consume(TokenType.SET, "Expected 'SET' after table name in UPDATE.");
         const assignments = [];
         do {
-            const column = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name in SET clause.");
+            const column = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in SET clause.");
             this.consume(TokenType.EQUAL, "Expected '=' after column name in SET clause.");
             const value = this.expression();
             assignments.push({ column, value });
@@ -1917,6 +2191,12 @@ export class Parser {
             }
             contextValues = trailingClauses.contextValues;
         }
+        if (trailingClauses.tags) {
+            if (tags) {
+                throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+            }
+            tags = trailingClauses.tags;
+        }
         const schemaPath = trailingClauses.schemaPath;
         // Parse RETURNING clause if present
         let returning;
@@ -1924,21 +2204,33 @@ export class Parser {
             returning = this.columnList();
         }
         const endToken = this.previous();
-        return { type: 'update', table, assignments, where, returning, contextValues, schemaPath, loc: _createLoc(startToken, endToken) };
+        return { type: 'update', table, targetSource, alias: targetSource?.alias, assignments, where, returning, contextValues, schemaPath, tags, loc: _createLoc(startToken, endToken) };
     }
     /** @internal */
-    deleteStatement(startToken, _withClause) {
+    deleteStatement(startToken, withClause) {
+        // `delete` consumes an optional leading `FROM`; the inline-subquery target check
+        // runs AFTER it so `delete from (select …) as v` works (and `delete (select …) as
+        // v` too, matching the optional-FROM behavior). See updateStatement.
         this.matchKeyword('FROM');
-        const table = this.tableIdentifier();
-        // Parse mutation context assignments if present (can also appear after WHERE)
+        const targetSource = this.subqueryDmlTarget(withClause);
+        const table = targetSource
+            ? { type: 'identifier', name: targetSource.alias, loc: targetSource.loc }
+            : this.tableIdentifier();
+        // Parse mutation context assignments and/or tags if present (either may also
+        // appear trailing, after WHERE, via parseTrailingWithClauses).
         let contextValues;
-        if (this.matchKeyword('WITH')) {
+        let tags;
+        while (this.matchKeyword('WITH')) {
             if (this.matchKeyword('CONTEXT')) {
                 contextValues = this.parseContextAssignments();
             }
+            else if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
             else {
-                // Not a WITH CONTEXT clause, backtrack
+                // Not a WITH CONTEXT / WITH TAGS clause, backtrack
                 this.current--;
+                break;
             }
         }
         let where;
@@ -1953,6 +2245,12 @@ export class Parser {
             }
             contextValues = trailingClauses.contextValues;
         }
+        if (trailingClauses.tags) {
+            if (tags) {
+                throw this.error(this.previous(), "Duplicate WITH TAGS clause");
+            }
+            tags = trailingClauses.tags;
+        }
         const schemaPath = trailingClauses.schemaPath;
         // Parse RETURNING clause if present
         let returning;
@@ -1960,7 +2258,7 @@ export class Parser {
             returning = this.columnList();
         }
         const endToken = this.previous();
-        return { type: 'delete', table, where, returning, contextValues, schemaPath, loc: _createLoc(startToken, endToken) };
+        return { type: 'delete', table, targetSource, alias: targetSource?.alias, where, returning, contextValues, schemaPath, tags, loc: _createLoc(startToken, endToken) };
     }
     /** @internal */
     valuesStatement(startToken) {
@@ -1979,23 +2277,85 @@ export class Parser {
         const endToken = this.previous();
         return { type: 'values', values, loc: _createLoc(startToken, endToken) };
     }
+    /**
+     * Parses VALUES at a position that also accepts trailing compound
+     * (UNION / INTERSECT / EXCEPT / DIFF) and — outside compound-leg
+     * position — trailing ORDER BY / LIMIT / OFFSET. Used at the top-level
+     * statement dispatch, inside `parseQueryExpr`, and as a compound right
+     * leg so that chains like `VALUES (1) UNION VALUES (2) UNION VALUES (3)`
+     * and `VALUES (1) ORDER BY 1 LIMIT 2` parse uniformly.
+     *
+     * Implementation note: the AST `compound` / `orderBy` / `limit` fields
+     * live on `SelectStmt`, not on `ValuesStmt`. When any of those clauses
+     * follow VALUES we synthesize a `SELECT * FROM (VALUES …)` wrapper so the
+     * existing SELECT machinery applies. The wrapper is structurally
+     * indistinguishable from what a user-written `SELECT * FROM (VALUES …)`
+     * would produce.
+     *
+     * `isCompoundSubquery` suppresses ORDER BY / LIMIT consumption — those
+     * belong to the outer compound when VALUES appears as a right leg.
+     */
+    valuesStatementWithOptionalCompound(startToken, withClause, isCompoundSubquery = false) {
+        const values = this.valuesStatement(startToken);
+        const hasCompound = this.checkCompoundOperator();
+        // A trailing `with defaults (…)` wraps just like ORDER BY / LIMIT so the
+        // select spine consumes it — a VALUES-bodied view's defaults are inert
+        // (the view is non-updateable), but the clause must still parse + store.
+        const hasTrailing = !isCompoundSubquery && (this.check(TokenType.ORDER) || this.check(TokenType.LIMIT) || this.checkWithDefaults());
+        if (!hasCompound && !hasTrailing) {
+            return values;
+        }
+        // Wrap as `SELECT * FROM (<values>) AS <synthetic alias>` and continue
+        // parsing as a SELECT so the trailing clauses fold in naturally.
+        const wrapped = this.wrapAsSubquerySelect(values, startToken);
+        return this.continueSelectAfterFrom(wrapped, withClause, startToken, isCompoundSubquery);
+    }
+    /**
+     * Picks up an in-progress SELECT after its FROM clause is already populated
+     * and parses any remaining trailing clauses by delegating to the shared
+     * compound-tail / ORDER-LIMIT parsers. Used by
+     * `valuesStatementWithOptionalCompound` to graft a compound chain and
+     * trailing clauses onto a synthesized SELECT-from-VALUES wrapper. The
+     * synthesized wrapper never carries its own WHERE / GROUP BY / HAVING — bare
+     * VALUES at top level does not accept those clauses, so they fall through as
+     * a statement-boundary parse error rather than being silently absorbed.
+     *
+     * `startToken` seeds the synthetic alias of any further subquery wrapper the
+     * tail parser mints; `isCompoundSubquery` suppresses ORDER BY / LIMIT
+     * consumption — those belong to the outer compound when this wrapper is a
+     * right leg.
+     */
+    continueSelectAfterFrom(sel, withClause, startToken, isCompoundSubquery = false) {
+        // Compound chain (left-associative tail) binds before ORDER BY / LIMIT.
+        const result = this.parseCompoundTail(sel, withClause, startToken);
+        this.parseTrailingOrderLimit(result, isCompoundSubquery);
+        // Trailing `with defaults (…)` binds to the whole compound (see selectStatement).
+        if (!isCompoundSubquery) {
+            const defaults = this.parseDefaultsClause();
+            if (defaults)
+                result.defaults = defaults;
+        }
+        return result;
+    }
     /** @internal */
     createStatement(startToken, withClause) {
-        let isTemporary = false;
+        // TEMP/TEMPORARY is not a Quereus concept — the schema is already transient
+        // and temp placement was never wired. Reject it rather than silently ignore.
         if (this.peekKeyword('TEMP') || this.peekKeyword('TEMPORARY')) {
-            isTemporary = true;
-            this.advance();
+            throw this.error(this.peek(), "TEMP/TEMPORARY is not supported.");
         }
         if (this.peekKeyword('TABLE')) {
             this.consumeKeyword('TABLE', "Expected 'TABLE' after CREATE.");
-            return this.createTableStatement(startToken, isTemporary, withClause);
+            return this.createTableStatement(startToken, withClause);
         }
         else if (this.peekKeyword('VIEW')) {
             this.consumeKeyword('VIEW', "Expected 'VIEW' after CREATE.");
-            return this.createViewStatement(startToken, isTemporary, withClause);
+            return this.createViewStatement(startToken, withClause);
         }
-        else if (isTemporary) {
-            throw this.error(this.peek(), "Expected TABLE or VIEW after CREATE TEMP/TEMPORARY.");
+        else if (this.peekKeyword('MATERIALIZED')) {
+            this.consumeKeyword('MATERIALIZED', "Expected 'MATERIALIZED' after CREATE.");
+            this.consumeKeyword('VIEW', "Expected 'VIEW' after CREATE MATERIALIZED.");
+            return this.createMaterializedViewStatement(startToken, withClause);
         }
         else if (this.peekKeyword('INDEX')) {
             this.consumeKeyword('INDEX', "Expected 'INDEX' after CREATE.");
@@ -2010,13 +2370,13 @@ export class Parser {
             this.consumeKeyword('INDEX', "Expected 'INDEX' after CREATE UNIQUE.");
             return this.createIndexStatement(startToken, true, withClause);
         }
-        throw this.error(this.peek(), "Expected TABLE, [UNIQUE] INDEX, VIEW, ASSERTION, or VIRTUAL after CREATE.");
+        throw this.error(this.peek(), "Expected TABLE, [UNIQUE] INDEX, VIEW, MATERIALIZED VIEW, ASSERTION, or VIRTUAL after CREATE.");
     }
     /**
      * Parse CREATE TABLE statement
      * @returns AST for CREATE TABLE
      */
-    createTableStatement(startToken, isTemporary, _withClause) {
+    createTableStatement(startToken, _withClause) {
         let ifNotExists = false;
         if (this.matchKeyword('IF')) {
             this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
@@ -2040,8 +2400,7 @@ export class Parser {
             // 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);
+                const nextLooksLikeAnotherItem = this.peekKeyword('PRIMARY') || this.peekKeyword('UNIQUE') || this.peekKeyword('CHECK') || this.peekKeyword('FOREIGN') || this.peekKeyword('CONSTRAINT') || this.checkIdentifierLike(CONTEXTUAL_KEYWORDS);
                 if (nextLooksLikeAnotherItem) {
                     const next = this.peek();
                     throw this.error(next, `Expected ',' between table elements. Did you forget a comma before '${next.lexeme}'?`);
@@ -2085,6 +2444,11 @@ export class Parser {
                 this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
             }
         }
+        // Optional `maintained as <body … with defaults (…)>` clause — the declared-shape
+        // maintained-table form. `maintained` is contextual (an IDENTIFIER lexeme match), and
+        // this position (after the column list / USING clause, before the WITH clauses) is
+        // unambiguous, so no look-ahead guard is needed.
+        const maintained = this.parseMaintainedClause();
         // Parse trailing WITH clauses (CONTEXT, TAGS) in any order
         let contextDefinitions;
         let tags;
@@ -2113,14 +2477,57 @@ export class Parser {
             ifNotExists,
             columns,
             constraints,
-            isTemporary,
             moduleName,
             moduleArgs,
             contextDefinitions,
             tags,
+            maintained,
             loc: _createLoc(startToken, this.previous()),
         };
     }
+    /**
+     * Parse the optional `maintained as <query-expr>` clause of a CREATE TABLE (or
+     * a `declare schema` table item) — the declared-shape maintained-table form.
+     * Any omitted-insert defaults ride inside the body select's trailing
+     * `with defaults (…)` clause. Returns undefined when the clause is absent.
+     */
+    parseMaintainedClause() {
+        if (!this.matchKeyword('MAINTAINED'))
+            return undefined;
+        // Optional explicit output-column rename list before AS — the lossless
+        // table-form encoding of the MV-sugar `(a, b)` renames. Absent ⇒ implicit
+        // (the body follows its source shape on reopen). The required AS that
+        // follows keeps this unambiguous against a parenthesized body.
+        const columns = this.parseMaintainedColumnList();
+        this.consumeKeyword('AS', "Expected 'AS' after MAINTAINED.");
+        // Body is any QueryExpr — bare SELECT / VALUES / WITH … SELECT all qualify.
+        // DML bodies parse here but the planner rejects them. A trailing
+        // `with defaults (…)` is consumed by the select spine into `select.defaults`.
+        const select = this.parseQueryExpr(undefined, /*requireReturning*/ true);
+        return { columns, select };
+    }
+    /**
+     * Parse the optional parenthesized output-column rename list that may precede the
+     * `AS` of a maintained-table form — shared by `create table … maintained (cols) as`
+     * and `alter table … set maintained (cols) as`. Returns undefined when absent
+     * (the implicit form). An empty `()` is rejected: it could not round-trip
+     * (`maintainedClauseToString` drops an empty list) and the clause's absence is
+     * already the implicit signal, so require at least one column.
+     */
+    parseMaintainedColumnList() {
+        if (!this.check(TokenType.LPAREN))
+            return undefined;
+        this.consume(TokenType.LPAREN, "Expected '(' to start maintained column list.");
+        if (this.check(TokenType.RPAREN)) {
+            throw this.error(this.peek(), "Expected at least one column name in the maintained column list.");
+        }
+        const columns = [];
+        do {
+            columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in maintained column list."));
+        } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
+        this.consume(TokenType.RPAREN, "Expected ')' after maintained column list.");
+        return columns;
+    }
     /**
      * Parse CREATE INDEX statement
      * @param isUnique Flag indicating if UNIQUE keyword was already parsed
@@ -2173,7 +2580,7 @@ export class Parser {
      * Parse CREATE VIEW statement
      * @returns AST for CREATE VIEW
      */
-    createViewStatement(startToken, isTemporary, withClause) {
+    createViewStatement(startToken, withClause) {
         let ifNotExists = false;
         if (this.matchKeyword('IF')) {
             this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
@@ -2185,29 +2592,20 @@ export class Parser {
         if (this.check(TokenType.LPAREN)) {
             this.consume(TokenType.LPAREN, "Expected '(' to start view column list.");
             columns = [];
-            const contextualKeywords = ['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'];
             if (!this.check(TokenType.RPAREN)) {
                 do {
-                    columns.push(this.consumeIdentifier(contextualKeywords, "Expected column name in view column list."));
+                    columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in view column list."));
                 } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
             }
             this.consume(TokenType.RPAREN, "Expected ')' after view column list.");
         }
-        this.consumeKeyword('AS', "Expected 'AS' before SELECT statement for CREATE VIEW.");
-        // CREATE VIEW body may optionally start with a WITH (CTE) clause; the WITH attaches to
-        // the inner SELECT, not to the CREATE VIEW itself.
-        let innerWith;
-        if (this.check(TokenType.WITH)) {
-            innerWith = this.tryParseWithClause();
-        }
-        const selectStartToken = this.consume(TokenType.SELECT, "Expected 'SELECT' after 'AS' in CREATE VIEW.");
-        const select = this.selectStatement(selectStartToken, innerWith ?? withClause);
-        if (innerWith) {
-            select.withClause = innerWith;
-            if (innerWith.loc && select.loc) {
-                select.loc.start = innerWith.loc.start;
-            }
-        }
+        this.consumeKeyword('AS', "Expected 'AS' before view body in CREATE VIEW.");
+        // CREATE VIEW body is any QueryExpr — bare SELECT / VALUES / WITH …
+        // SELECT all qualify. DML bodies parse here but the planner rejects
+        // them (mutating views are out of scope for this milestone).
+        const select = this.parseQueryExpr(withClause, /*requireReturning*/ true);
+        // A trailing `with defaults (…)` rides inside the select body
+        // (`select.defaults`); only the DDL-level WITH TAGS is parsed here.
         // Parse optional WITH TAGS
         let tags;
         if (this.matchKeyword('WITH')) {
@@ -2224,11 +2622,195 @@ export class Parser {
             ifNotExists,
             columns,
             select,
-            isTemporary,
             tags,
             loc: _createLoc(startToken, this.previous()),
         };
     }
+    /**
+     * Parse the optional trailing `with defaults ( col = expr , … )` clause of a
+     * core select — per-column omitted-insert defaults for view write-through.
+     * Modeled byte-for-byte on {@link parseInverseClause}: commits only once
+     * DEFAULTS follows WITH, so a statement-trailing `with tags` / `with schema` /
+     * `with context` stays with the outer parser (the rewound token is WITH, which
+     * never touches the parenStack — so the bare cursor rewind is safe). Returns
+     * undefined when the clause is absent. An empty assignment list is a parse error.
+     */
+    parseDefaultsClause() {
+        if (!this.check(TokenType.WITH))
+            return undefined;
+        this.advance();
+        if (!this.peekKeyword('DEFAULTS')) {
+            // Not our clause — back up the WITH and stop. Bare cursor rewind is safe
+            // only because the rewound token is WITH: advance() has one non-cursor
+            // side effect (LPAREN/RPAREN parenStack maintenance), which WITH never hits.
+            this.current--;
+            return undefined;
+        }
+        this.advance();
+        this.consume(TokenType.LPAREN, "Expected '(' after WITH DEFAULTS.");
+        const defaults = [];
+        const seen = new Set();
+        do {
+            const columnToken = this.peek();
+            const column = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in WITH DEFAULTS.");
+            if (seen.has(column.toLowerCase())) {
+                throw this.error(columnToken, `Duplicate column '${column}' in WITH DEFAULTS.`);
+            }
+            seen.add(column.toLowerCase());
+            this.consume(TokenType.EQUAL, `Expected '=' after WITH DEFAULTS column '${column}'.`);
+            const expr = this.expression();
+            defaults.push({ column, expr });
+        } while (this.match(TokenType.COMMA));
+        this.consume(TokenType.RPAREN, "Expected ')' after WITH DEFAULTS list.");
+        return defaults;
+    }
+    /**
+     * Parse the optional `with inverse ( col = expr , … )` clause trailing an
+     * expression result column — authored write-back expressions for view
+     * write-through (inert metadata until the write path consumes it; validation
+     * is build-time). Returns undefined when the clause is absent. `inverse` is
+     * contextual: commits only once INVERSE follows WITH, so a statement-trailing
+     * `with schema` / `with context` / `with tags` after the column list stays
+     * with the outer parser. An empty assignment list is a parse error.
+     */
+    parseInverseClause() {
+        if (!this.check(TokenType.WITH))
+            return undefined;
+        this.advance();
+        if (!this.peekKeyword('INVERSE')) {
+            // Not our clause — back up the WITH and stop. Bare cursor rewind is safe
+            // only because the rewound token is WITH: advance() has one non-cursor
+            // side effect (LPAREN/RPAREN parenStack maintenance), which WITH never hits.
+            this.current--;
+            return undefined;
+        }
+        this.advance();
+        this.consume(TokenType.LPAREN, "Expected '(' after WITH INVERSE.");
+        const assignments = [];
+        const seen = new Set();
+        do {
+            const columnToken = this.peek();
+            const column = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in WITH INVERSE.");
+            if (seen.has(column.toLowerCase())) {
+                throw this.error(columnToken, `Duplicate column '${column}' in WITH INVERSE.`);
+            }
+            seen.add(column.toLowerCase());
+            this.consume(TokenType.EQUAL, `Expected '=' after WITH INVERSE column '${column}'.`);
+            const expr = this.expression();
+            assignments.push({ column, expr });
+        } while (this.match(TokenType.COMMA));
+        this.consume(TokenType.RPAREN, "Expected ')' after WITH INVERSE list.");
+        return assignments;
+    }
+    /**
+     * A `*` / `t.*` result column cannot carry WITH INVERSE (it names no single
+     * expression to invert). Name the clause in the diagnostic rather than letting
+     * the leftover WITH garble into a downstream CTE/clause error. A trailing
+     * `with schema` / `with tags` is untouched — parseInverseClause commits only
+     * on WITH followed by INVERSE.
+     */
+    rejectInverseClauseOnStar() {
+        const withToken = this.peek();
+        if (this.parseInverseClause()) {
+            throw this.error(withToken, "WITH INVERSE cannot apply to a '*' result column.");
+        }
+    }
+    /**
+     * Parse CREATE MATERIALIZED VIEW statement.
+     *
+     * Syntax: `create materialized view <name> [(cols)] [using <module>(args)] as <query-expr> [with tags ...]`.
+     * The optional `using` clause is parsed before `as` to stay unambiguous with the query body;
+     * v1 restricts the backing module to `memory` at build time (the AST keeps the slot forward-compatible).
+     */
+    createMaterializedViewStatement(startToken, withClause) {
+        let ifNotExists = false;
+        if (this.matchKeyword('IF')) {
+            this.consumeKeyword('NOT', "Expected 'NOT' after 'IF'.");
+            this.consumeKeyword('EXISTS', "Expected 'EXISTS' after 'IF NOT'.");
+            ifNotExists = true;
+        }
+        const view = this.tableIdentifier();
+        let columns;
+        if (this.check(TokenType.LPAREN)) {
+            this.consume(TokenType.LPAREN, "Expected '(' to start view column list.");
+            columns = [];
+            if (!this.check(TokenType.RPAREN)) {
+                do {
+                    columns.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in view column list."));
+                } while (this.match(TokenType.COMMA) && !this.check(TokenType.RPAREN));
+            }
+            this.consume(TokenType.RPAREN, "Expected ')' after view column list.");
+        }
+        // Optional backing-module clause (`using mem(...)`) before the body.
+        let moduleName;
+        const moduleArgs = {};
+        if (this.matchKeyword('USING')) {
+            moduleName = this.consumeIdentifier("Expected module name after 'USING'.");
+            if (this.match(TokenType.LPAREN)) {
+                let positionalIndex = 0;
+                if (!this.check(TokenType.RPAREN)) {
+                    do {
+                        if (this.check(TokenType.STRING) || this.check(TokenType.INTEGER) || this.check(TokenType.FLOAT)) {
+                            const token = this.advance();
+                            moduleArgs[String(positionalIndex++)] = token.literal;
+                        }
+                        else if (this.check(TokenType.IDENTIFIER)) {
+                            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);
+                        }
+                        else {
+                            throw this.error(this.peek(), "Expected module argument (string, number, or name=value pair).");
+                        }
+                    } while (this.match(TokenType.COMMA));
+                }
+                this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
+            }
+        }
+        this.consumeKeyword('AS', "Expected 'AS' before view body in CREATE MATERIALIZED VIEW.");
+        // Body is any QueryExpr — bare SELECT / VALUES / WITH … SELECT all qualify.
+        // DML bodies parse here but the planner rejects them.
+        const select = this.parseQueryExpr(withClause, /*requireReturning*/ true);
+        // A trailing `with defaults (…)` rides inside the select body
+        // (`select.defaults`); only the DDL-level WITH TAGS is parsed here.
+        // Parse the trailing `with tags (...)` metadata clause.
+        let tags;
+        while (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--; // Not a clause we own — back up the WITH and stop.
+                break;
+            }
+        }
+        return {
+            type: 'createMaterializedView',
+            view,
+            ifNotExists,
+            columns,
+            select,
+            moduleName,
+            moduleArgs: moduleName && Object.keys(moduleArgs).length > 0 ? moduleArgs : undefined,
+            tags,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
+    /**
+     * Parse REFRESH MATERIALIZED VIEW statement.
+     * Syntax: `refresh materialized view <name>`.
+     */
+    refreshStatement(startToken, _withClause) {
+        this.consumeKeyword('MATERIALIZED', "Expected 'MATERIALIZED' after REFRESH.");
+        this.consumeKeyword('VIEW', "Expected 'VIEW' after REFRESH MATERIALIZED.");
+        const name = this.tableIdentifier();
+        return {
+            type: 'refreshMaterializedView',
+            name,
+            loc: _createLoc(startToken, this.previous()),
+        };
+    }
     /**
      * Parse CREATE ASSERTION statement
      * @returns AST for CREATE ASSERTION
@@ -2256,6 +2838,11 @@ export class Parser {
             this.consumeKeyword('TABLE', "Expected TABLE after DROP.");
             objectType = 'table';
         }
+        else if (this.peekKeyword('MATERIALIZED')) {
+            this.consumeKeyword('MATERIALIZED', "Expected MATERIALIZED after DROP.");
+            this.consumeKeyword('VIEW', "Expected VIEW after DROP MATERIALIZED.");
+            objectType = 'materializedView';
+        }
         else if (this.peekKeyword('VIEW')) {
             this.consumeKeyword('VIEW', "Expected VIEW after DROP.");
             objectType = 'view';
@@ -2269,7 +2856,7 @@ export class Parser {
             objectType = 'assertion';
         }
         else {
-            throw this.error(this.peek(), "Expected TABLE, VIEW, INDEX, or ASSERTION after DROP.");
+            throw this.error(this.peek(), "Expected TABLE, VIEW, MATERIALIZED VIEW, INDEX, or ASSERTION after DROP.");
         }
         let ifExists = false;
         if (this.matchKeyword('IF')) {
@@ -2285,6 +2872,74 @@ export class Parser {
             loc: _createLoc(startToken, this.previous()),
         };
     }
+    /**
+     * Top-level ALTER dispatch. `ALTER` has already been consumed. Branches on the
+     * object keyword: TABLE → the full ALTER TABLE grammar; VIEW / MATERIALIZED VIEW
+     * / INDEX → the v1 `SET TAGS`-only metadata grammar. MATERIALIZED is checked
+     * before VIEW so `MATERIALIZED VIEW` is not mis-parsed as a plain view.
+     */
+    alterStatement(startToken, withClause) {
+        if (this.peekKeyword('TABLE')) {
+            return this.alterTableStatement(startToken, withClause);
+        }
+        if (this.peekKeyword('MATERIALIZED')) {
+            return this.alterMaterializedViewStatement(startToken);
+        }
+        if (this.peekKeyword('VIEW')) {
+            return this.alterViewStatement(startToken);
+        }
+        if (this.peekKeyword('INDEX')) {
+            return this.alterIndexStatement(startToken);
+        }
+        throw this.error(this.peek(), "Expected 'TABLE', 'VIEW', 'MATERIALIZED VIEW', or 'INDEX' after ALTER.");
+    }
+    /**
+     * Parse the trailing `{SET|ADD|DROP} TAGS (...)` of an ALTER VIEW /
+     * MATERIALIZED VIEW / INDEX statement (object name already consumed):
+     *   SET TAGS  → whole-set replace (empty list clears),
+     *   ADD TAGS  → per-key merge (empty list is a no-op),
+     *   DROP TAGS → per-key delete (atomic; empty list is a no-op).
+     * No `(` look-ahead guard is needed (unlike the ALTER TABLE table level):
+     * after `ALTER VIEW <name>` the only legal grammar is a tag op, so the
+     * leading keyword is unambiguous.
+     */
+    parseObjectTagsAction() {
+        if (this.matchKeyword('SET')) {
+            this.consumeKeyword('TAGS', "Expected 'TAGS' after SET.");
+            return { type: 'setTags', mode: 'replace', tags: this.parseTags() };
+        }
+        if (this.matchKeyword('ADD')) {
+            this.consumeKeyword('TAGS', "Expected 'TAGS' after ADD.");
+            return { type: 'setTags', mode: 'merge', tags: this.parseTags() };
+        }
+        if (this.matchKeyword('DROP')) {
+            this.consumeKeyword('TAGS', "Expected 'TAGS' after DROP.");
+            return { type: 'dropTags', keys: this.parseTagKeys() };
+        }
+        throw this.error(this.peek(), "Expected SET, ADD, or DROP TAGS after object name.");
+    }
+    /** Parse `ALTER VIEW <name> {SET|ADD|DROP} TAGS (...)`. */
+    alterViewStatement(startToken) {
+        this.consumeKeyword('VIEW', "Expected 'VIEW' after ALTER.");
+        const name = this.tableIdentifier();
+        const action = this.parseObjectTagsAction();
+        return { type: 'alterView', name, action, loc: _createLoc(startToken, this.previous()) };
+    }
+    /** Parse `ALTER MATERIALIZED VIEW <name> {SET|ADD|DROP} TAGS (...)`. */
+    alterMaterializedViewStatement(startToken) {
+        this.consumeKeyword('MATERIALIZED', "Expected 'MATERIALIZED' after ALTER.");
+        this.consumeKeyword('VIEW', "Expected 'VIEW' after MATERIALIZED.");
+        const name = this.tableIdentifier();
+        const action = this.parseObjectTagsAction();
+        return { type: 'alterMaterializedView', name, action, loc: _createLoc(startToken, this.previous()) };
+    }
+    /** Parse `ALTER INDEX <name> {SET|ADD|DROP} TAGS (...)`. */
+    alterIndexStatement(startToken) {
+        this.consumeKeyword('INDEX', "Expected 'INDEX' after ALTER.");
+        const name = this.tableIdentifier();
+        const action = this.parseObjectTagsAction();
+        return { type: 'alterIndex', name, action, loc: _createLoc(startToken, this.previous()) };
+    }
     /**
      * Parse ALTER TABLE statement
      * @returns AST for ALTER TABLE statement
@@ -2296,21 +2951,44 @@ export class Parser {
         if (this.peekKeyword('RENAME')) {
             this.consumeKeyword('RENAME', "Expected RENAME.");
             if (this.matchKeyword('COLUMN')) {
-                const oldName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected old column name after RENAME COLUMN.");
+                const oldName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected old column name after RENAME COLUMN.");
                 this.consumeKeyword('TO', "Expected 'TO' after old column name.");
-                const newName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected new column name after TO.");
+                const newName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected new column name after TO.");
                 action = { type: 'renameColumn', oldName, newName };
             }
+            else if (this.matchKeyword('CONSTRAINT')) {
+                // RENAME CONSTRAINT <old> TO <new> — name-level rename of a named
+                // table-level constraint (CHECK / UNIQUE / FOREIGN KEY).
+                const oldName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected old constraint name after RENAME CONSTRAINT.");
+                this.consumeKeyword('TO', "Expected 'TO' after old constraint name.");
+                const newName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected new constraint name after TO.");
+                action = { type: 'renameConstraint', oldName, newName };
+            }
             else {
                 this.consumeKeyword('TO', "Expected 'TO' after RENAME.");
-                const newName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected new table name after RENAME TO.");
+                const newName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected new table name after RENAME TO.");
                 action = { type: 'renameTable', newName };
             }
         }
         else if (this.peekKeyword('ADD')) {
             this.consumeKeyword('ADD', "Expected ADD.");
-            if (this.peekKeyword('CONSTRAINT')) {
-                // ADD CONSTRAINT ... - let tableConstraint parse everything including CONSTRAINT keyword
+            if (this.peekKeyword('TAGS') && this.checkNext(1, TokenType.LPAREN)) {
+                // ADD TAGS (...) — per-key merge of table tags. Gated on TAGS being
+                // immediately followed by '(' so a column literally named `tags`
+                // (e.g. `ADD tags integer` / `ADD COLUMN tags ...`) still parses as
+                // ADD COLUMN. `TAGS` is a contextual keyword (a plain identifier), so
+                // without the '(' guard it would shadow such columns.
+                this.consumeKeyword('TAGS', "Expected 'TAGS'.");
+                const tags = this.parseTags();
+                action = { type: 'setTags', target: { kind: 'table' }, mode: 'merge', tags };
+            }
+            else if (this.peekKeyword('CONSTRAINT')
+                || this.check(TokenType.UNIQUE)
+                || this.check(TokenType.FOREIGN)
+                || this.check(TokenType.CHECK)) {
+                // ADD CONSTRAINT <name> <body>, or the unnamed table-constraint forms
+                // ADD UNIQUE (...) / ADD FOREIGN KEY (...) / ADD CHECK (...).
+                // tableConstraint() consumes the optional CONSTRAINT <name> prefix.
                 const constraint = this.tableConstraint();
                 action = { type: 'addConstraint', constraint };
             }
@@ -2323,9 +3001,52 @@ export class Parser {
         }
         else if (this.peekKeyword('DROP')) {
             this.consumeKeyword('DROP', "Expected DROP.");
-            this.matchKeyword('COLUMN');
-            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name after DROP COLUMN.");
-            action = { type: 'dropColumn', name };
+            if (this.peekKeyword('TAGS') && this.checkNext(1, TokenType.LPAREN)) {
+                // DROP TAGS (...) — per-key delete of table tags. Same '(' guard as
+                // ADD TAGS so `DROP COLUMN tags` / `DROP tags` (a column named `tags`)
+                // still parse as DROP COLUMN.
+                this.consumeKeyword('TAGS', "Expected 'TAGS'.");
+                action = { type: 'dropTags', target: { kind: 'table' }, keys: this.parseTagKeys() };
+            }
+            else if (this.peekKeyword('MAINTAINED')) {
+                // DROP MAINTAINED — detach the table's derivation. The verb wins over a
+                // column literally named `maintained`; use DROP COLUMN maintained for that.
+                this.consumeKeyword('MAINTAINED', "Expected 'MAINTAINED'.");
+                action = { type: 'dropMaintained' };
+            }
+            else if (this.matchKeyword('CONSTRAINT')) {
+                // DROP CONSTRAINT <name> — drop a named table-level constraint
+                // (CHECK / UNIQUE / FOREIGN KEY).
+                const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected constraint name after DROP CONSTRAINT.");
+                action = { type: 'dropConstraint', name };
+            }
+            else {
+                this.matchKeyword('COLUMN');
+                const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name after DROP COLUMN.");
+                action = { type: 'dropColumn', name };
+            }
+        }
+        else if (this.peekKeyword('SET')) {
+            this.consumeKeyword('SET', "Expected SET.");
+            if (this.matchKeyword('MAINTAINED')) {
+                // SET MAINTAINED [(cols)] AS <body> — attach / re-attach a derivation.
+                // No `using` clause: the module is the table's identity. The optional
+                // `(cols)` is the explicit output-column rename list (the differ's
+                // lossless encoding of an MV-sugar `(a, c)` rename): present ⇒ positional
+                // rename + recorded explicit; absent ⇒ implicit (the body's natural
+                // names). The required AS keeps it unambiguous. A trailing
+                // `with defaults (…)` rides inside the body (`select.defaults`).
+                const columns = this.parseMaintainedColumnList();
+                this.consumeKeyword('AS', "Expected 'AS' after SET MAINTAINED.");
+                const select = this.parseQueryExpr(undefined, /*requireReturning*/ true);
+                action = { type: 'setMaintained', columns, select };
+            }
+            else {
+                // Table-level `SET TAGS (...)` — whole-set tag replacement on the table.
+                this.consumeKeyword('TAGS', "Expected 'TAGS' or 'MAINTAINED' after SET.");
+                const tags = this.parseTags();
+                action = { type: 'setTags', target: { kind: 'table' }, mode: 'replace', tags };
+            }
         }
         else if (this.peekKeyword('ALTER')) {
             this.consumeKeyword('ALTER', "Expected ALTER.");
@@ -2333,14 +3054,37 @@ export class Parser {
                 this.consumeKeyword('COLUMN', "Expected COLUMN.");
                 action = this.alterColumnAction();
             }
+            else if (this.peekKeyword('CONSTRAINT')) {
+                // ALTER CONSTRAINT <name> {SET|ADD|DROP} TAGS (...) — tag mutation on a
+                // named table-level constraint (only named constraints are addressable):
+                //   SET TAGS  → whole-set replace, ADD TAGS → per-key merge,
+                //   DROP TAGS → per-key delete.
+                this.consumeKeyword('CONSTRAINT', "Expected CONSTRAINT.");
+                const constraintName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected constraint name after ALTER CONSTRAINT.");
+                if (this.matchKeyword('SET')) {
+                    this.consumeKeyword('TAGS', "Expected 'TAGS' after SET.");
+                    action = { type: 'setTags', target: { kind: 'constraint', constraintName }, mode: 'replace', tags: this.parseTags() };
+                }
+                else if (this.matchKeyword('ADD')) {
+                    this.consumeKeyword('TAGS', "Expected 'TAGS' after ADD.");
+                    action = { type: 'setTags', target: { kind: 'constraint', constraintName }, mode: 'merge', tags: this.parseTags() };
+                }
+                else if (this.matchKeyword('DROP')) {
+                    this.consumeKeyword('TAGS', "Expected 'TAGS' after DROP.");
+                    action = { type: 'dropTags', target: { kind: 'constraint', constraintName }, keys: this.parseTagKeys() };
+                }
+                else {
+                    throw this.error(this.peek(), `Expected SET, ADD, or DROP after ALTER CONSTRAINT ${constraintName}.`);
+                }
+            }
             else {
-                this.consumeKeyword('PRIMARY', "Expected 'PRIMARY' or 'COLUMN' after ALTER.");
+                this.consumeKeyword('PRIMARY', "Expected 'PRIMARY', 'COLUMN', or 'CONSTRAINT' after ALTER.");
                 this.consumeKeyword('KEY', "Expected 'KEY' after PRIMARY.");
                 this.consume(TokenType.LPAREN, "Expected '(' after PRIMARY KEY.");
                 const columns = [];
                 if (!this.check(TokenType.RPAREN)) {
                     do {
-                        const colName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name in PRIMARY KEY definition.");
+                        const colName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name in PRIMARY KEY definition.");
                         let direction;
                         if (this.matchKeyword('ASC')) {
                             direction = 'asc';
@@ -2371,7 +3115,7 @@ export class Parser {
      * Caller has already consumed ALTER COLUMN.
      */
     alterColumnAction() {
-        const columnName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name after ALTER COLUMN.");
+        const columnName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name after ALTER COLUMN.");
         if (this.matchKeyword('SET')) {
             if (this.matchKeyword('NOT')) {
                 this.consumeKeyword('NULL', "Expected 'NULL' after SET NOT.");
@@ -2386,7 +3130,29 @@ export class Parser {
                 const expr = this.expression();
                 return { type: 'alterColumn', columnName, setDefault: expr };
             }
-            throw this.error(this.peek(), "Expected NOT NULL, DATA TYPE, or DEFAULT after SET.");
+            if (this.match(TokenType.COLLATE)) {
+                // ALTER COLUMN <name> SET COLLATE <name> — change the column's collation,
+                // re-sorting / re-validating any PK / UNIQUE / index that orders by it.
+                if (!this.check(TokenType.IDENTIFIER)) {
+                    throw this.error(this.peek(), "Expected collation name after SET COLLATE.");
+                }
+                const collation = this.getIdentifierValue(this.advance());
+                return { type: 'alterColumn', columnName, setCollation: collation };
+            }
+            if (this.matchKeyword('TAGS')) {
+                // ALTER COLUMN <name> SET TAGS (...) — whole-set tag replacement on the column.
+                const tags = this.parseTags();
+                return { type: 'setTags', target: { kind: 'column', columnName }, mode: 'replace', tags };
+            }
+            throw this.error(this.peek(), "Expected NOT NULL, DATA TYPE, DEFAULT, COLLATE, or TAGS after SET.");
+        }
+        if (this.matchKeyword('ADD')) {
+            // ALTER COLUMN <name> ADD TAGS (...) — per-key merge on the column. TAGS is
+            // unambiguous here (the grammar after ALTER COLUMN <name> ADD is fixed), so
+            // no '(' look-ahead guard is needed as it is at the table level.
+            this.consumeKeyword('TAGS', "Expected 'TAGS' after ADD.");
+            const tags = this.parseTags();
+            return { type: 'setTags', target: { kind: 'column', columnName }, mode: 'merge', tags };
         }
         if (this.matchKeyword('DROP')) {
             if (this.matchKeyword('NOT')) {
@@ -2396,9 +3162,13 @@ export class Parser {
             if (this.matchKeyword('DEFAULT')) {
                 return { type: 'alterColumn', columnName, setDefault: null };
             }
-            throw this.error(this.peek(), "Expected NOT NULL or DEFAULT after DROP.");
+            if (this.matchKeyword('TAGS')) {
+                // ALTER COLUMN <name> DROP TAGS (...) — per-key delete on the column.
+                return { type: 'dropTags', target: { kind: 'column', columnName }, keys: this.parseTagKeys() };
+            }
+            throw this.error(this.peek(), "Expected NOT NULL, DEFAULT, or TAGS after DROP.");
         }
-        throw this.error(this.peek(), "Expected SET or DROP after ALTER COLUMN name.");
+        throw this.error(this.peek(), "Expected SET, ADD, or DROP after ALTER COLUMN name.");
     }
     /**
      * Parse a data-type name as used in column definitions. Supports optional
@@ -2486,16 +3256,20 @@ export class Parser {
         return { type: 'pragma', ...nameValue, loc: _createLoc(startToken, this.previous()) };
     }
     /**
-     * Parse ANALYZE statement: ANALYZE [schema.]table | ANALYZE
+     * Parse ANALYZE statement: ANALYZE [schema.]table | ANALYZE schema.* | ANALYZE
      */
     analyzeStatement(startToken) {
         // ANALYZE with no arguments → analyze all tables
         if (this.isAtEnd() || this.check(TokenType.SEMICOLON)) {
             return { type: 'analyze', loc: _createLoc(startToken, this.previous()) };
         }
-        // Parse optional schema.table or just table
+        // Parse optional schema.table, schema.* (all tables in schema), or just table
         const name1 = this.consumeIdentifier([], "Expected table name after ANALYZE.");
         if (this.match(TokenType.DOT)) {
+            // ANALYZE schema.* → analyze every table in the schema (schema-only shape)
+            if (this.match(TokenType.ASTERISK)) {
+                return { type: 'analyze', schemaName: name1, loc: _createLoc(startToken, this.previous()) };
+            }
             const name2 = this.consumeIdentifier([], "Expected table name after schema qualifier.");
             return { type: 'analyze', schemaName: name1, tableName: name2, loc: _createLoc(startToken, this.previous()) };
         }
@@ -2503,6 +3277,8 @@ export class Parser {
     }
     // === Declarative schema parsing ===
     declareSchemaStatement(startToken) {
+        // Optional contextual keyword: `declare logical schema X { ... }`.
+        const isLogical = this.matchKeyword('LOGICAL');
         this.consumeKeyword('SCHEMA', "Expected 'SCHEMA' after DECLARE.");
         const schemaName = this.consumeIdentifier(['temp', 'temporary'], "Expected schema name after DECLARE.");
         let version;
@@ -2560,6 +3336,11 @@ export class Parser {
                 this.consumeKeyword('INDEX', "Expected 'INDEX' after 'UNIQUE'.");
                 items.push(this.declareIndexItem(true));
             }
+            else if (this.peekKeyword('MATERIALIZED')) {
+                this.advance();
+                this.consumeKeyword('VIEW', "Expected 'VIEW' after 'MATERIALIZED'.");
+                items.push(this.declareMaterializedViewItem());
+            }
             else if (this.peekKeyword('VIEW')) {
                 this.advance();
                 items.push(this.declareViewItem());
@@ -2586,10 +3367,52 @@ export class Parser {
         }
         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) };
+        return { type: 'declareSchema', schemaName, version, using, items, ...(isLogical ? { isLogical: true } : {}), loc: _createLoc(startToken, endTok) };
+    }
+    /**
+     * Parses `declare lens for <X> over <Y> { ( view <T> as <select> ;? )* }`.
+     * The DECLARE token is already consumed by {@link statement}. `lens` and `for`
+     * are contextual keywords (matched via peekKeyword's IDENTIFIER fallback);
+     * `over` is the existing window-function keyword.
+     */
+    declareLensStatement(startToken) {
+        this.consumeKeyword('LENS', "Expected 'LENS' after DECLARE.");
+        this.consumeKeyword('FOR', "Expected 'FOR' after DECLARE LENS.");
+        const logicalSchema = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected logical schema name after 'FOR'.");
+        this.consumeKeyword('OVER', "Expected 'OVER' after the logical schema name.");
+        const basisSchema = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected basis schema name after 'OVER'.");
+        this.consume(TokenType.LBRACE, "Expected '{' to start the lens declaration block.");
+        const overrides = [];
+        while (!this.check(TokenType.RBRACE)) {
+            if (this.isAtEnd())
+                break;
+            this.consumeKeyword('VIEW', "Expected 'view' to begin a lens override.");
+            const table = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected the logical table name after 'view'.");
+            this.consumeKeyword('AS', "Expected 'AS' after the logical table name.");
+            const body = this.parseQueryExpr();
+            if (body.type !== 'select') {
+                throw this.error(this.previous(), `A lens override body must be a SELECT; got '${body.type}'.`);
+            }
+            // A compound set-operation parses as a single `select` node carrying a
+            // `compound` (or legacy `union`) pointer; the override merger composes
+            // only the top leg, so reject the shape rather than silently mis-map.
+            if (body.compound || body.union) {
+                throw this.error(this.previous(), `A lens override body must be a single SELECT; compound set-operations (union/intersect/except) are not supported in v1 lens overrides.`);
+            }
+            overrides.push({ table, select: body });
+            this.match(TokenType.SEMICOLON);
+        }
+        this.consume(TokenType.RBRACE, "Expected '}' to close the lens declaration block.");
+        return {
+            type: 'declareLens',
+            logicalSchema,
+            basisSchema,
+            overrides,
+            loc: _createLoc(startToken, this.previous()),
+        };
     }
     declareTableItem() {
-        const tableName = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], 'Expected table name in declaration.');
+        const tableName = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, 'Expected table name in declaration.');
         let moduleName;
         let moduleArgs;
         const columns = [];
@@ -2648,6 +3471,10 @@ export class Parser {
         else {
             this.consume(TokenType.RPAREN, "Expected ')' after table definition.");
         }
+        // Optional `maintained as <body … with defaults (…)>` — the declared-shape
+        // maintained-table form, carried through the CreateTableStmt reuse. (Differ
+        // transition handling is a follow-up; the clause parses and round-trips.)
+        const maintained = this.parseMaintainedClause();
         // Parse trailing WITH clauses (CONTEXT, TAGS) in any order
         let contextDefinitions;
         let tags;
@@ -2676,11 +3503,11 @@ export class Parser {
             ifNotExists: false,
             columns,
             constraints,
-            isTemporary: false,
             moduleName,
             moduleArgs,
             contextDefinitions,
-            tags
+            tags,
+            maintained
         };
         return { type: 'declaredTable', tableStmt };
     }
@@ -2691,6 +3518,11 @@ export class Parser {
         this.consume(TokenType.LPAREN, "Expected '(' before index columns.");
         const columns = this.indexedColumnList();
         this.consume(TokenType.RPAREN, "Expected ')' after index columns.");
+        // Parse optional WHERE <predicate> (partial index), before WITH TAGS
+        let where;
+        if (this.matchKeyword('WHERE')) {
+            where = this.expression();
+        }
         // Parse optional WITH TAGS
         let tags;
         if (this.matchKeyword('WITH')) {
@@ -2707,6 +3539,7 @@ export class Parser {
             table: { type: 'identifier', name: tableName },
             ifNotExists: false,
             columns,
+            where,
             isUnique,
             tags
         };
@@ -2719,9 +3552,10 @@ export class Parser {
             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);
+        this.consumeKeyword('AS', "Expected AS before view body in view declaration.");
+        const select = this.parseQueryExpr(undefined, /*requireReturning*/ true);
+        // A trailing `with defaults (…)` rides inside the select body
+        // (`select.defaults`); only the DDL-level WITH TAGS is parsed here.
         // Parse optional WITH TAGS
         let tags;
         if (this.matchKeyword('WITH')) {
@@ -2738,11 +3572,71 @@ export class Parser {
             ifNotExists: false,
             columns,
             select,
-            isTemporary: false,
             tags
         };
         return { type: 'declaredView', viewStmt };
     }
+    declareMaterializedViewItem() {
+        const viewName = this.consumeIdentifier('Expected materialized view name.');
+        let columns;
+        if (this.match(TokenType.LPAREN)) {
+            columns = this.identifierList();
+            this.consume(TokenType.RPAREN, "Expected ')' after materialized view columns.");
+        }
+        // Optional backing-module clause (`using mem(...)`) before the body — same
+        // shape as the top-level CREATE MATERIALIZED VIEW form.
+        let moduleName;
+        const moduleArgs = {};
+        if (this.matchKeyword('USING')) {
+            moduleName = this.consumeIdentifier("Expected module name after 'USING'.");
+            if (this.match(TokenType.LPAREN)) {
+                let positionalIndex = 0;
+                if (!this.check(TokenType.RPAREN)) {
+                    do {
+                        if (this.check(TokenType.STRING) || this.check(TokenType.INTEGER) || this.check(TokenType.FLOAT)) {
+                            const token = this.advance();
+                            moduleArgs[String(positionalIndex++)] = token.literal;
+                        }
+                        else if (this.check(TokenType.IDENTIFIER)) {
+                            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);
+                        }
+                        else {
+                            throw this.error(this.peek(), "Expected module argument (string, number, or name=value pair).");
+                        }
+                    } while (this.match(TokenType.COMMA));
+                }
+                this.consume(TokenType.RPAREN, "Expected ')' after module arguments.");
+            }
+        }
+        this.consumeKeyword('AS', "Expected AS before view body in materialized view declaration.");
+        const select = this.parseQueryExpr(undefined, /*requireReturning*/ true);
+        // A trailing `with defaults (…)` rides inside the select body
+        // (`select.defaults`); only the DDL-level WITH TAGS is parsed here.
+        // Parse optional WITH TAGS
+        let tags;
+        if (this.matchKeyword('WITH')) {
+            if (this.matchKeyword('TAGS')) {
+                tags = this.parseTags();
+            }
+            else {
+                this.current--;
+            }
+        }
+        const viewStmt = {
+            type: 'createMaterializedView',
+            view: { type: 'identifier', name: viewName },
+            ifNotExists: false,
+            columns,
+            select,
+            moduleName,
+            moduleArgs: moduleName && Object.keys(moduleArgs).length > 0 ? moduleArgs : undefined,
+            tags
+        };
+        return { type: 'declaredMaterializedView', viewStmt };
+    }
     declareSeedItem() {
         // seed <table> ( (...), (...) ) or seed <table> values (col, ...) values (...), (...)
         const tableName = this.consumeIdentifier('Expected table name after SEED.');
@@ -3027,7 +3921,7 @@ export class Parser {
     // --- Stubs for required helpers (implement fully for CREATE TABLE) ---
     /** @internal Parses a column definition */
     columnDefinition() {
-        const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected column name.");
+        const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected column name.");
         let dataType;
         if (this.check(TokenType.IDENTIFIER)) {
             dataType = this.advance().lexeme;
@@ -3184,6 +4078,22 @@ export class Parser {
         this.consume(TokenType.RPAREN, "Expected ')' after tag list.");
         return tags;
     }
+    /**
+     * @internal Parses a bare comma-list of tag keys — `(key [, key ...])` with no
+     * `= value`, used by the DROP TAGS form. Mirrors {@link parseTags} but yields
+     * just the keys. An empty list `()` yields `[]`.
+     */
+    parseTagKeys() {
+        this.consume(TokenType.LPAREN, "Expected '(' after TAGS.");
+        const keys = [];
+        if (!this.check(TokenType.RPAREN)) {
+            do {
+                keys.push(this.consumeIdentifier("Expected tag key identifier."));
+            } while (this.match(TokenType.COMMA));
+        }
+        this.consume(TokenType.RPAREN, "Expected ')' after tag key list.");
+        return keys;
+    }
     /** @internal Parses a tag value: string, number, TRUE, FALSE, or NULL */
     parseTagValue() {
         if (this.match(TokenType.STRING)) {
@@ -3418,7 +4328,19 @@ export class Parser {
         if (this.check(TokenType.REFERENCES)) {
             this.advance();
         }
-        const table = this.consumeIdentifier("Expected foreign table name.");
+        // Optional `schema.` qualifier on the parent table (cross-schema FK),
+        // mirroring tableIdentifier() so a schema named `temp` parses.
+        const contextualKeywords = [...CONTEXTUAL_KEYWORDS, 'temp', 'temporary'];
+        let schema;
+        let table;
+        if (this.checkIdentifierLike(contextualKeywords) && this.checkNext(1, TokenType.DOT)) {
+            schema = this.consumeIdentifier(contextualKeywords, "Expected schema name.");
+            this.advance(); // Consume DOT
+            table = this.consumeIdentifier(contextualKeywords, "Expected foreign table name after schema.");
+        }
+        else {
+            table = this.consumeIdentifier(contextualKeywords, "Expected foreign table name.");
+        }
         let columns;
         if (this.match(TokenType.LPAREN)) {
             columns = this.identifierList();
@@ -3473,7 +4395,7 @@ export class Parser {
                 break;
             }
         }
-        return { table, columns, onDelete, onUpdate, deferrable, initiallyDeferred };
+        return { table, schema, columns, onDelete, onUpdate, deferrable, initiallyDeferred };
     }
     /** @internal Parses the ON CONFLICT clause */
     parseConflictClause() {
@@ -3518,7 +4440,7 @@ export class Parser {
     identifierList() {
         const identifiers = [];
         do {
-            identifiers.push(this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected identifier in list."));
+            identifiers.push(this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected identifier in list."));
         } while (this.match(TokenType.COMMA));
         return identifiers;
     }
@@ -3526,7 +4448,7 @@ export class Parser {
     identifierListWithDirection() {
         const identifiers = [];
         do {
-            const name = this.consumeIdentifier(['key', 'action', 'set', 'default', 'check', 'unique', 'references', 'on', 'cascade', 'restrict', 'like'], "Expected identifier in list.");
+            const name = this.consumeIdentifier(CONTEXTUAL_KEYWORDS, "Expected identifier in list.");
             const direction = this.match(TokenType.ASC) ? 'asc' : this.match(TokenType.DESC) ? 'desc' : undefined;
             identifiers.push({ name, direction });
         } while (this.match(TokenType.COMMA));