@ldclabs/kip-lang 0.4.0 → 2.0.0

package/dist/parser.js

@@ -1,5 +1,5 @@
 import { tokenize } from './lexer.js';
-import { TokenType, isTrivia } from './token.js';
+import { TokenType, isTrivia, isIdentifierLike, isAggregate } from './token.js';
 export function parse(source) {
     const allTokens = tokenize(source);
     const parser = new Parser(allTokens, source);
@@ -10,6 +10,7 @@ class Parser {
     pos = 0;
     diagnostics = [];
     source;
+    dialect = 'kql';
     constructor(tokens, source) {
         // Filter out trivia for parsing, but keep comments for attachment later
         this.tokens = tokens.filter((t) => !isTrivia(t.type) || t.type === TokenType.Comment);
@@ -51,1223 +52,2104 @@ class Parser {
     parseStatement() {
         const tok = this.current();
         switch (tok.type) {
+            // KQL
             case TokenType.Find:
                 return this.parseFindStatement();
+            // KML
+            case TokenType.Mutate:
+                return this.parseMutateStatement();
+            case TokenType.Create:
             case TokenType.Upsert:
-                return this.parseUpsertStatement();
+            case TokenType.Ensure:
+            case TokenType.Assert:
             case TokenType.Update:
-                return this.parseUpdateStatement();
+            case TokenType.Retract:
+            case TokenType.Supersede:
+            case TokenType.Correct:
+            case TokenType.Transition:
+            case TokenType.Set:
+            case TokenType.Archive:
+            case TokenType.Tombstone:
+            case TokenType.Purge:
             case TokenType.Merge:
-                return this.parseMergeStatement();
-            case TokenType.Delete:
-                return this.parseDeleteStatement();
+                return this.parseMutationClause();
+            // META
             case TokenType.Describe:
                 return this.parseDescribeStatement();
+            case TokenType.List:
+                return this.parseListStatement();
             case TokenType.Search:
                 return this.parseSearchStatement();
+            case TokenType.Verify:
+                return this.parseVerifyStatement();
+            case TokenType.Validate:
+                return this.parseValidateStatement();
+            case TokenType.Preview:
+                return this.parsePreviewStatement();
+            case TokenType.History:
+                return this.parseHistoryStatement();
+            case TokenType.Changes:
+                return this.parseChangesStatement();
+            case TokenType.Snapshot:
+                return this.parseSnapshotStatement();
             case TokenType.Export:
-                return this.parseExportStatement();
+                return this.parseExportCapsuleStatement();
             default:
-                this.error(`Unexpected token '${tok.value}', expected a statement keyword (FIND, UPSERT, UPDATE, MERGE, DELETE, DESCRIBE, SEARCH, EXPORT)`, tok);
-                this.advance();
+                this.error(`Unexpected token '${tok.value}': expected a KQL, KML or META statement`, tok);
                 return null;
         }
     }
+    /** Every mutation legal at statement level and inside `MUTATE { ... }`. */
+    parseMutationClause() {
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Create:
+                return this.parseCreateStatement();
+            case TokenType.Upsert:
+                return this.parseUpsertConcept();
+            case TokenType.Ensure:
+                return this.parseEnsureProposition();
+            case TokenType.Assert:
+                return this.parseAssertStatement();
+            case TokenType.Update:
+                return this.parseUpdateStatement();
+            case TokenType.Retract:
+                return this.parseRetractAssertion();
+            case TokenType.Supersede:
+                return this.parseSupersedeAssertion();
+            case TokenType.Correct:
+                return this.parseCorrectEvidence();
+            case TokenType.Transition:
+                return this.parseTransitionActivity();
+            case TokenType.Set:
+                return this.parseSetRetention();
+            case TokenType.Archive:
+                return this.parseArchiveStatement();
+            case TokenType.Tombstone:
+                return this.parseTombstoneStatement();
+            case TokenType.Purge:
+                return this.parsePurgeStatement();
+            case TokenType.Merge:
+                return this.parseMergeConcept();
+            default:
+                this.error(`Unexpected token '${tok.value}': expected a KML mutation`, tok);
+                throw new ParseAbort();
+        }
+    }
     // ────────────────────────────────────────────────────────────────────
-    //  FIND
+    //  KQL — FIND
     // ────────────────────────────────────────────────────────────────────
     parseFindStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
+        this.dialect = 'kql';
         this.expect(TokenType.Find);
-        const lparen = this.current();
         this.expect(TokenType.LParen);
         const projections = [];
         if (!this.check(TokenType.RParen)) {
-            projections.push(this.parseExpression());
-            while (this.match(TokenType.Comma)) {
-                projections.push(this.parseExpression());
-            }
+            do {
+                projections.push(this.parseProjectionExpression());
+            } while (this.match(TokenType.Comma));
         }
         if (projections.length === 0) {
-            this.error(`FIND must declare at least one output expression, e.g. FIND(?var)`, lparen);
+            this.error('FIND requires at least one projection', this.current());
         }
         this.expect(TokenType.RParen);
-        let where;
+        this.expectKeywordWithSpace(TokenType.Where);
+        const where = this.parseWhereClause();
+        let asOf;
+        let forTime;
+        let epistemic;
         let orderBy;
         let limit;
         let cursor;
-        if (this.check(TokenType.Where)) {
-            where = this.parseWhereClause();
-        }
-        if (this.check(TokenType.Order)) {
-            orderBy = this.parseOrderBy();
-        }
-        if (this.check(TokenType.Limit)) {
-            limit = this.parseLimitClause();
-        }
-        if (this.check(TokenType.Cursor)) {
-            cursor = this.parseCursorClause();
+        let lastClauseOrder = -1;
+        // The grammar fixes this order. Accepting any order here would let a
+        // command run on this parser that a conformant engine rejects, so each
+        // clause is taken once and out-of-order repeats are reported.
+        for (;;) {
+            const tok = this.current();
+            if (this.check(TokenType.As)) {
+                lastClauseOrder = this.checkClauseOrder(0, lastClauseOrder, 'AS OF', tok);
+                this.rejectRepeat(asOf, 'AS OF', tok);
+                asOf = this.parseAsOfClause();
+            }
+            else if (this.check(TokenType.For)) {
+                lastClauseOrder = this.checkClauseOrder(1, lastClauseOrder, 'FOR TIME', tok);
+                this.rejectRepeat(forTime, 'FOR TIME', tok);
+                forTime = this.parseForTimeClause();
+            }
+            else if (this.check(TokenType.With)) {
+                lastClauseOrder = this.checkClauseOrder(2, lastClauseOrder, 'WITH EPISTEMIC', tok);
+                this.rejectRepeat(epistemic, 'WITH EPISTEMIC', tok);
+                epistemic = this.parseEpistemicClause();
+            }
+            else if (this.check(TokenType.Order)) {
+                lastClauseOrder = this.checkClauseOrder(3, lastClauseOrder, 'ORDER BY', tok);
+                this.rejectRepeat(orderBy, 'ORDER BY', tok);
+                orderBy = this.parseOrderBy();
+            }
+            else if (this.check(TokenType.Limit)) {
+                lastClauseOrder = this.checkClauseOrder(4, lastClauseOrder, 'LIMIT', tok);
+                this.rejectRepeat(limit, 'LIMIT', tok);
+                limit = this.parseLimitClause();
+            }
+            else if (this.check(TokenType.Cursor)) {
+                lastClauseOrder = this.checkClauseOrder(5, lastClauseOrder, 'CURSOR', tok);
+                this.rejectRepeat(cursor, 'CURSOR', tok);
+                cursor = this.parseCursorClause();
+            }
+            else {
+                break;
+            }
         }
         return {
             kind: 'FindStatement',
             projections,
             where,
+            asOf,
+            forTime,
+            epistemic,
             orderBy,
             limit,
             cursor,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    // ────────────────────────────────────────────────────────────────────
-    //  UPSERT
-    // ────────────────────────────────────────────────────────────────────
-    parseUpsertStatement() {
+    /** `projection_expression = aggregate_expression | expression` */
+    parseProjectionExpression() {
+        return this.parseExpression();
+    }
+    parseAsOfClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Upsert);
-        this.expect(TokenType.LBrace);
-        const blocks = [];
-        this.skipComments();
-        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const before = this.pos;
-            this.skipComments();
-            if (this.check(TokenType.Concept)) {
-                blocks.push(this.parseConceptBlock());
-            }
-            else if (this.check(TokenType.Proposition)) {
-                blocks.push(this.parsePropositionBlock());
-            }
-            else if (this.check(TokenType.RBrace)) {
-                break;
-            }
-            else {
-                this.error(`Expected CONCEPT or PROPOSITION inside UPSERT block`, this.current());
-                this.advance();
-            }
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
-                break;
+        const first = this.expect(TokenType.As);
+        this.expectSecondWord(TokenType.Of, first);
+        let basis;
+        if (this.match(TokenType.Seq)) {
+            basis = 'SEQ';
         }
-        this.expect(TokenType.RBrace);
-        let metadata;
-        if (this.check(TokenType.With)) {
-            metadata = this.parseWithMetadata();
+        else if (this.match(TokenType.Tx)) {
+            basis = 'TX';
+        }
+        else if (this.match(TokenType.Time)) {
+            basis = 'TIME';
         }
+        else {
+            this.error(`Expected SEQ, TX or TIME after AS OF but got '${this.current().value}'`, this.current());
+            basis = 'SEQ';
+        }
+        const value = this.parseScalarValue();
         return {
-            kind: 'UpsertStatement',
-            blocks,
-            metadata,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'AsOfClause',
+            basis,
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    parseConceptBlock() {
+    parseForTimeClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Concept);
-        // The handle is optional: a block nothing else refers to needs no name.
-        let handle;
-        if (this.check(TokenType.Variable)) {
-            handle = this.expectVariable();
-        }
-        this.expect(TokenType.LBrace);
-        const matcher = this.parseConceptMatcher();
-        let expectVersion;
-        if (this.check(TokenType.Expect)) {
-            expectVersion = this.parseExpectVersion();
-        }
-        let setAttributes;
-        let setPropositions;
-        let metadata;
-        this.skipComments();
-        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const before = this.pos;
-            this.skipComments();
-            if (this.check(TokenType.Set)) {
-                const setStart = this.currentPos();
-                const setTok = this.advance(); // skip SET
-                if (this.check(TokenType.Attributes)) {
-                    this.expectSecondWord(TokenType.Attributes, setTok);
-                    setAttributes = this.parseSetAttributesBody(setStart);
-                }
-                else if (this.check(TokenType.Propositions)) {
-                    this.expectSecondWord(TokenType.Propositions, setTok);
-                    setPropositions = this.parseSetPropositionsBody(setStart);
-                }
-                else {
-                    this.error(`Expected ATTRIBUTES or PROPOSITIONS after SET`, this.current());
-                    this.advance();
-                }
-            }
-            else if (this.check(TokenType.With)) {
-                metadata = this.parseWithMetadata();
-            }
-            else if (this.check(TokenType.RBrace)) {
-                break;
-            }
-            else {
-                this.skipComments();
-                if (this.check(TokenType.RBrace))
-                    break;
-                this.error(`Unexpected token '${this.current().value}' in CONCEPT block`, this.current());
-                this.advance();
-            }
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
-                break;
-        }
-        this.expect(TokenType.RBrace);
-        // Concept-level WITH METADATA (outside the CONCEPT braces)
-        if (!metadata && this.check(TokenType.With)) {
-            metadata = this.parseWithMetadata();
-        }
+        const first = this.expect(TokenType.For);
+        this.expectSecondWord(TokenType.Time, first);
+        const value = this.parseScalarValue();
         return {
-            kind: 'ConceptBlock',
-            handle,
-            matcher,
-            expectVersion,
-            setAttributes,
-            setPropositions,
-            metadata,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'ForTimeClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    parsePropositionBlock() {
+    parseEpistemicClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Proposition);
-        let handle;
-        if (this.check(TokenType.Variable)) {
-            handle = this.expectVariable();
-        }
-        this.expect(TokenType.LBrace);
-        const proposition = this.parsePropositionPatternBody(undefined);
-        let expectVersion;
-        if (this.check(TokenType.Expect)) {
-            expectVersion = this.parseExpectVersion();
-        }
-        let setAttributes;
-        let metadata;
-        this.skipComments();
-        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const before = this.pos;
-            this.skipComments();
-            if (this.check(TokenType.Set)) {
-                const setStart = this.currentPos();
-                const setTok = this.advance();
-                if (this.check(TokenType.Attributes)) {
-                    this.expectSecondWord(TokenType.Attributes, setTok);
-                    setAttributes = this.parseSetAttributesBody(setStart);
-                }
-                else {
-                    this.error(`Expected ATTRIBUTES after SET in PROPOSITION block`, this.current());
-                    this.advance();
-                }
-            }
-            else if (this.check(TokenType.RBrace)) {
-                break;
-            }
-            else {
-                this.error(`Unexpected token '${this.current().value}' in PROPOSITION block`, this.current());
-                this.advance();
-            }
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
-                break;
-        }
-        this.expect(TokenType.RBrace);
-        if (this.check(TokenType.With)) {
-            metadata = this.parseWithMetadata();
-        }
+        const first = this.expect(TokenType.With);
+        this.expectSecondWord(TokenType.Epistemic, first);
+        const options = this.parseObjectLiteral();
         return {
-            kind: 'PropositionBlock',
-            handle,
-            id: proposition.id,
-            subject: proposition.subject,
-            predicate: proposition.predicate,
-            object: proposition.object,
-            expectVersion,
-            setAttributes,
-            metadata,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'EpistemicClause',
+            options,
+            range: { start, end: this.endPos() }
         };
     }
-    // ────────────────────────────────────────────────────────────────────
-    //  UPDATE
-    // ────────────────────────────────────────────────────────────────────
-    parseUpdateStatement() {
+    parseOrderBy() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Update);
-        const target = this.expectVariable();
-        let setAttributes;
-        let setMetadata;
-        this.skipComments();
-        while (this.check(TokenType.Set) && !this.isAtEnd()) {
-            const before = this.pos;
-            const setStart = this.currentPos();
-            const setTok = this.advance();
-            if (this.check(TokenType.Attributes)) {
-                this.expectSecondWord(TokenType.Attributes, setTok);
-                setAttributes = this.parseSetAttributesBody(setStart);
-            }
-            else if (this.check(TokenType.Metadata)) {
-                this.expectSecondWord(TokenType.Metadata, setTok);
-                setMetadata = this.parseSetMetadataBody(setStart);
-            }
-            else {
-                this.error(`Expected ATTRIBUTES or METADATA after SET in UPDATE statement`, this.current());
-                this.advance();
-            }
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
-                break;
-        }
-        if (!setAttributes && !setMetadata) {
-            this.error(`Expected SET ATTRIBUTES or SET METADATA in UPDATE statement`, this.current());
-        }
-        const where = this.parseWhereClause();
-        let limit;
-        if (this.check(TokenType.Limit)) {
-            limit = this.parseLimitClause();
-        }
+        const first = this.expect(TokenType.Order);
+        this.expectSecondWord(TokenType.By, first);
+        const items = [];
+        do {
+            items.push(this.parseOrderItem());
+        } while (this.match(TokenType.Comma));
         return {
-            kind: 'UpdateStatement',
-            target,
-            setAttributes,
-            setMetadata,
-            where,
-            limit,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'OrderByClause',
+            items,
+            range: { start, end: this.endPos() }
         };
     }
-    // ────────────────────────────────────────────────────────────────────
-    //  MERGE
-    // ────────────────────────────────────────────────────────────────────
-    parseMergeStatement() {
+    parseOrderItem() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        const mergeTok = this.expect(TokenType.Merge);
-        this.expectSecondWord(TokenType.Concept, mergeTok);
-        const source = this.expectVariable();
-        this.expect(TokenType.Into);
-        const target = this.expectVariable();
-        const where = this.parseWhereClause();
+        const expression = this.parseProjectionExpression();
+        let direction;
+        if (this.match(TokenType.Asc))
+            direction = 'ASC';
+        else if (this.match(TokenType.Desc))
+            direction = 'DESC';
         return {
-            kind: 'MergeStatement',
-            source,
-            target,
-            where,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'OrderItem',
+            expression,
+            direction,
+            range: { start, end: this.endPos() }
         };
     }
-    // ────────────────────────────────────────────────────────────────────
-    //  DELETE
-    // ────────────────────────────────────────────────────────────────────
-    parseDeleteStatement() {
+    parseLimitClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Delete);
-        let deleteType;
-        let keys;
-        let target;
-        let detach = false;
-        if (this.check(TokenType.Attributes)) {
-            deleteType = 'ATTRIBUTES';
-            this.advance();
-            keys = this.parseDeleteKeySet();
-            this.expect(TokenType.From);
-            target = this.expectVariable();
-        }
-        else if (this.check(TokenType.Metadata)) {
-            deleteType = 'METADATA';
-            this.advance();
-            keys = this.parseDeleteKeySet();
-            this.expect(TokenType.From);
-            target = this.expectVariable();
-        }
-        else if (this.check(TokenType.Propositions)) {
-            deleteType = 'PROPOSITIONS';
-            this.advance();
-            target = this.expectVariable();
-        }
-        else if (this.check(TokenType.Concept)) {
-            deleteType = 'CONCEPT';
-            this.advance();
-            target = this.expectVariable();
-            if (this.check(TokenType.Detach)) {
-                detach = true;
-                this.advance();
-            }
-            else {
-                this.error(`Expected DETACH after DELETE CONCEPT target '${target}'`, this.current());
-            }
-        }
-        else {
-            this.error(`Expected ATTRIBUTES, METADATA, PROPOSITIONS, or CONCEPT after DELETE`, this.current());
-            deleteType = 'ATTRIBUTES';
-            target = '?unknown';
-        }
-        const where = this.parseWhereClause();
+        this.expect(TokenType.Limit);
+        const value = this.parseScalarValue();
         return {
-            kind: 'DeleteStatement',
-            deleteType,
-            keys,
-            target,
-            detach: detach || undefined,
-            where,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'LimitClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    parseDeleteKeySet() {
-        this.expect(TokenType.LBrace);
-        const keys = [];
-        if (!this.check(TokenType.RBrace)) {
-            keys.push(this.expectString());
-            while (this.match(TokenType.Comma)) {
-                if (this.check(TokenType.RBrace))
-                    break;
-                keys.push(this.expectString());
-            }
-        }
-        this.expect(TokenType.RBrace);
-        return keys;
-    }
-    // ────────────────────────────────────────────────────────────────────
-    //  DESCRIBE
-    // ────────────────────────────────────────────────────────────────────
-    parseDescribeStatement() {
+    parseCursorClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Describe);
-        let describeType;
-        let typeName;
-        let typeNameValue;
-        let limit;
-        let cursor;
-        if (this.check(TokenType.Primer)) {
-            describeType = 'PRIMER';
-            this.advance();
-        }
-        else if (this.check(TokenType.Domains)) {
-            describeType = 'DOMAINS';
-            this.advance();
-        }
-        else if (this.check(TokenType.Concept)) {
-            const headTok = this.advance();
-            if (this.check(TokenType.Types)) {
-                describeType = 'CONCEPT_TYPES';
-                this.expectSecondWord(TokenType.Types, headTok);
-            }
-            else if (this.check(TokenType.Type)) {
-                describeType = 'CONCEPT_TYPE';
-                this.expectSecondWord(TokenType.Type, headTok);
-                typeNameValue = this.parseStringOrParameterValue('DESCRIBE CONCEPT TYPE');
-                typeName =
-                    typeNameValue.kind === 'StringLiteral'
-                        ? typeNameValue.parsed
-                        : typeNameValue.name;
-            }
-            else {
-                this.error(`Expected TYPE or TYPES after DESCRIBE CONCEPT`, this.current());
-                describeType = 'CONCEPT_TYPES';
-            }
-        }
-        else if (this.check(TokenType.Proposition)) {
-            const headTok = this.advance();
-            if (this.check(TokenType.Types)) {
-                describeType = 'PROPOSITION_TYPES';
-                this.expectSecondWord(TokenType.Types, headTok);
-            }
-            else if (this.check(TokenType.Type)) {
-                describeType = 'PROPOSITION_TYPE';
-                this.expectSecondWord(TokenType.Type, headTok);
-                typeNameValue = this.parseStringOrParameterValue('DESCRIBE PROPOSITION TYPE');
-                typeName =
-                    typeNameValue.kind === 'StringLiteral'
-                        ? typeNameValue.parsed
-                        : typeNameValue.name;
-            }
-            else {
-                this.error(`Expected TYPE or TYPES after DESCRIBE PROPOSITION`, this.current());
-                describeType = 'PROPOSITION_TYPES';
-            }
-        }
-        else {
-            this.error(`Expected PRIMER, DOMAINS, CONCEPT, or PROPOSITION after DESCRIBE`, this.current());
-            describeType = 'PRIMER';
-        }
-        // Only the plural `... TYPES` forms are paginated (§5.1.3 / §5.1.5).
-        const paginable = describeType === 'CONCEPT_TYPES' || describeType === 'PROPOSITION_TYPES';
-        if (this.check(TokenType.Limit)) {
-            if (!paginable) {
-                this.error(`LIMIT is only valid on DESCRIBE CONCEPT TYPES / PROPOSITION TYPES`, this.current());
-            }
-            limit = this.parseLimitClause();
-        }
-        if (this.check(TokenType.Cursor)) {
-            if (!paginable) {
-                this.error(`CURSOR is only valid on DESCRIBE CONCEPT TYPES / PROPOSITION TYPES`, this.current());
-            }
-            cursor = this.parseCursorClause();
-        }
+        this.expect(TokenType.Cursor);
+        const value = this.parseScalarValue();
         return {
-            kind: 'DescribeStatement',
-            describeType,
-            typeName,
-            typeNameValue,
-            limit,
-            cursor,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'CursorClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
     // ────────────────────────────────────────────────────────────────────
-    //  SEARCH
+    //  WHERE
     // ────────────────────────────────────────────────────────────────────
-    parseSearchStatement() {
+    parseWhereClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Search);
-        let searchTarget;
-        if (this.check(TokenType.Concept)) {
-            searchTarget = 'CONCEPT';
-            this.expectKeywordWithSpace(TokenType.Concept);
-        }
-        else if (this.check(TokenType.Proposition)) {
-            searchTarget = 'PROPOSITION';
-            this.expectKeywordWithSpace(TokenType.Proposition);
-        }
-        else {
-            this.error(`Expected CONCEPT or PROPOSITION after SEARCH`, this.current());
-            searchTarget = 'CONCEPT';
-        }
-        const termValue = this.parseStringOrParameterValue('SEARCH term');
-        const term = termValue.kind === 'StringLiteral' ? termValue.parsed : termValue.name;
-        let withType;
-        let withTypeValue;
-        let mode;
-        let modeValue;
-        let threshold;
-        let limit;
-        // Clauses may appear in any order but each at most once — a second
-        // `LIMIT` is trailing input, not an override.
-        while (!this.isAtEnd()) {
+        this.expect(TokenType.LBrace);
+        const patterns = this.parseWherePatterns();
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'WhereClause',
+            patterns,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseWherePatterns() {
+        const patterns = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
             const before = this.pos;
-            const clause = this.current();
-            if (this.check(TokenType.With)) {
-                this.rejectRepeat(withTypeValue, 'WITH TYPE', clause);
-                const withTok = this.advance();
-                this.expectSecondWord(TokenType.Type, withTok);
-                withTypeValue = this.parseStringOrParameterValue('SEARCH WITH TYPE');
-                withType =
-                    withTypeValue.kind === 'StringLiteral'
-                        ? withTypeValue.parsed
-                        : withTypeValue.name;
+            const pattern = this.parseWherePattern();
+            if (pattern)
+                patterns.push(pattern);
+            if (this.pos === before)
+                break;
+            // WHERE items are whitespace-delimited; a comma between them is not
+            // grammar, so report it rather than silently accepting both spellings.
+            if (this.check(TokenType.Comma)) {
+                this.error('WHERE items are separated by whitespace, not commas', this.current());
+                this.advance();
+            }
+        }
+        return patterns;
+    }
+    parseWherePattern() {
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Variable:
+                return this.parseVariableLeadingPattern();
+            case TokenType.LParen:
+            case TokenType.Proposition:
+                return this.parsePropositionPattern(undefined);
+            case TokenType.Structural:
+                return this.parseStructuralPattern(undefined);
+            case TokenType.Filter:
+                return this.parseFilterClause();
+            case TokenType.Not:
+                return this.parseNotClause();
+            case TokenType.Optional:
+                return this.parseOptionalClause();
+            case TokenType.Union:
+                return this.parseUnionClause();
+            default:
+                this.error(`Unexpected token '${tok.value}' in WHERE block`, tok);
+                this.advance();
+                return null;
+        }
+    }
+    /**
+     * Disambiguates the pattern families that all begin with a variable.
+     *
+     * `?x {`/`?x CONCEPT {` is a Concept, `?x (`/`?x PROPOSITION (` a raw
+     * Proposition, and the remaining families name their kind outright.
+     */
+    parseVariableLeadingPattern() {
+        const variable = this.parseVariableRef();
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.LBrace:
+            case TokenType.Concept:
+                return this.parseConceptPattern(variable);
+            case TokenType.LParen:
+            case TokenType.Proposition:
+                return this.parsePropositionPattern(variable);
+            case TokenType.Assertion:
+                return this.parseAssertionPattern(variable);
+            case TokenType.Evidence:
+                return this.parseEvidencePattern(variable);
+            case TokenType.Activity:
+                return this.parseActivityPattern(variable);
+            case TokenType.Structural:
+                return this.parseStructuralPattern(variable);
+            case TokenType.Belief:
+                return this.parseBeliefPattern(variable);
+            default:
+                this.error(`Expected a pattern body after ${variable.name} but got '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+    }
+    parseConceptPattern(variable) {
+        const explicit = this.match(TokenType.Concept);
+        const matcher = this.parseObjectPattern();
+        return {
+            kind: 'ConceptPattern',
+            variable,
+            explicit,
+            matcher,
+            range: { start: variable.range.start, end: this.endPos() }
+        };
+    }
+    parsePropositionPattern(variable) {
+        const start = variable ? variable.range.start : this.currentPos();
+        const explicit = this.match(TokenType.Proposition);
+        const tuple = this.parsePropositionTuple();
+        return {
+            kind: 'PropositionPattern',
+            variable,
+            explicit,
+            tuple,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseAssertionPattern(variable) {
+        this.expect(TokenType.Assertion);
+        const matcher = this.parseObjectPattern();
+        return {
+            kind: 'AssertionPattern',
+            variable,
+            matcher,
+            range: { start: variable.range.start, end: this.endPos() }
+        };
+    }
+    parseEvidencePattern(variable) {
+        this.expect(TokenType.Evidence);
+        const matcher = this.parseObjectPattern();
+        return {
+            kind: 'EvidencePattern',
+            variable,
+            matcher,
+            range: { start: variable.range.start, end: this.endPos() }
+        };
+    }
+    parseActivityPattern(variable) {
+        this.expect(TokenType.Activity);
+        const matcher = this.parseObjectPattern();
+        return {
+            kind: 'ActivityPattern',
+            variable,
+            matcher,
+            range: { start: variable.range.start, end: this.endPos() }
+        };
+    }
+    parseStructuralPattern(variable) {
+        const start = variable ? variable.range.start : this.currentPos();
+        this.expect(TokenType.Structural);
+        this.expect(TokenType.LParen);
+        const subject = this.parseTerm();
+        this.expect(TokenType.Comma);
+        const field = this.parseSchemaSymbol();
+        this.expect(TokenType.Comma);
+        const object = this.parseTerm();
+        this.expect(TokenType.RParen);
+        return {
+            kind: 'StructuralPattern',
+            variable,
+            subject,
+            field,
+            object,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseBeliefPattern(variable) {
+        const start = variable.range.start;
+        const beliefTok = this.expect(TokenType.Belief);
+        // `BELIEF SLOT (...)` — the whole functional slot, not one tuple.
+        if (this.check(TokenType.Slot)) {
+            this.expectSecondWord(TokenType.Slot, beliefTok);
+            this.expect(TokenType.LParen);
+            const subject = this.parseTerm();
+            this.expect(TokenType.Comma);
+            const predicate = this.parsePredicateAtom();
+            this.expect(TokenType.RParen);
+            this.rejectBeliefInRawDialect(start);
+            return {
+                kind: 'BeliefSlotPattern',
+                variable,
+                subject,
+                predicate,
+                range: { start, end: this.endPos() }
+            };
+        }
+        this.expect(TokenType.LParen);
+        // `BELIEF (?p)` projects an already-bound Proposition; `BELIEF (s, p, o)`
+        // projects a tuple. Only a lone variable followed by `)` is the former.
+        if (this.check(TokenType.Variable) && this.peekPast(1)?.type === TokenType.RParen) {
+            const proposition = this.parseVariableRef();
+            this.expect(TokenType.RParen);
+            this.rejectBeliefInRawDialect(start);
+            return {
+                kind: 'BeliefPattern',
+                variable,
+                proposition,
+                range: { start, end: this.endPos() }
+            };
+        }
+        // `BELIEF (id: ...)` — the operand is the Proposition expression slot, so
+        // the same id form that names a Proposition in a pattern names it here
+        // (Spec §43.2 / §46.1). Same recognition rule as parsePropositionTuple.
+        if (this.isPropositionIdStart()) {
+            this.advance(); // id
+            this.advance(); // :
+            const propositionId = this.parseScalarValue();
+            this.expect(TokenType.RParen);
+            this.rejectBeliefInRawDialect(start);
+            return {
+                kind: 'BeliefPattern',
+                variable,
+                propositionId,
+                range: { start, end: this.endPos() }
+            };
+        }
+        // `BELIEF (:p)` is the one spelling a reader might reach for that means
+        // nothing: a lone parameter is not a bound variable and not an id
+        // reference. Say what the reference form is instead of "expected ','",
+        // and recover as if the id form had been written so nothing cascades.
+        if (this.check(TokenType.Parameter) && this.peekPast(1)?.type === TokenType.RParen) {
+            const param = this.current();
+            this.error(`BELIEF (${param.value}) is not a form: name the Proposition by (id: ${param.value}), or bind it first and write BELIEF (?p)`, param);
+            const propositionId = this.parseParameterRef();
+            this.expect(TokenType.RParen);
+            this.rejectBeliefInRawDialect(start);
+            return {
+                kind: 'BeliefPattern',
+                variable,
+                propositionId,
+                range: { start, end: this.endPos() }
+            };
+        }
+        const subject = this.parseTerm();
+        this.expect(TokenType.Comma);
+        const predicate = this.parsePredicateAtom();
+        this.expect(TokenType.Comma);
+        const object = this.parseTerm();
+        this.expect(TokenType.RParen);
+        this.rejectBeliefInRawDialect(start);
+        return {
+            kind: 'BeliefPattern',
+            variable,
+            subject,
+            predicate,
+            object,
+            range: { start, end: this.endPos() }
+        };
+    }
+    /**
+     * BELIEF is an Epistemic Projection: virtual, read-only, and derived from a
+     * policy. KML excludes it because a Projection can never be a mutation
+     * target; EXPORT excludes it because a capsule carries records, not
+     * interpretations.
+     */
+    rejectBeliefInRawDialect(start) {
+        if (this.dialect === 'raw') {
+            this.diagnostics.push({
+                range: { start, end: this.endPos() },
+                severity: 'error',
+                message: 'BELIEF is a read-only Epistemic Projection and cannot appear in a mutation or export selection',
+                code: 'KIP_1001'
+            });
+        }
+    }
+    parseFilterClause() {
+        const start = this.currentPos();
+        this.expect(TokenType.Filter);
+        this.expect(TokenType.LParen);
+        const expression = this.parseExpression();
+        this.expect(TokenType.RParen);
+        return {
+            kind: 'FilterClause',
+            expression,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseNotClause() {
+        const start = this.currentPos();
+        this.expect(TokenType.Not);
+        this.expect(TokenType.LBrace);
+        const patterns = this.parseWherePatterns();
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'NotClause',
+            patterns,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseOptionalClause() {
+        const start = this.currentPos();
+        this.expect(TokenType.Optional);
+        this.expect(TokenType.LBrace);
+        const patterns = this.parseWherePatterns();
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'OptionalClause',
+            patterns,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseUnionClause() {
+        const start = this.currentPos();
+        this.expect(TokenType.Union);
+        this.expect(TokenType.LBrace);
+        const patterns = this.parseWherePatterns();
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'UnionClause',
+            patterns,
+            range: { start, end: this.endPos() }
+        };
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  Raw semantic tuples
+    // ────────────────────────────────────────────────────────────────────
+    parsePropositionTuple() {
+        const start = this.currentPos();
+        this.expect(TokenType.LParen);
+        // `(id: ...)` addresses the same slot by record identity. `id` is a field
+        // name, not a keyword, so it is matched on its exact lowercase text and
+        // only when a `:` follows — `(id, "p", ?o)` is still a triple whose
+        // subject happens to be a variable-free term.
+        if (this.isPropositionIdStart()) {
+            this.advance(); // id
+            this.advance(); // :
+            const id = this.parseScalarValue();
+            this.expect(TokenType.RParen);
+            return {
+                kind: 'PropositionTuple',
+                id,
+                range: { start, end: this.endPos() }
+            };
+        }
+        const subject = this.parseTerm();
+        this.expect(TokenType.Comma);
+        const predicate = this.parseRawPredicateExpression();
+        this.expect(TokenType.Comma);
+        const object = this.parseTerm();
+        this.expect(TokenType.RParen);
+        return {
+            kind: 'PropositionTuple',
+            subject,
+            predicate,
+            object,
+            range: { start, end: this.endPos() }
+        };
+    }
+    /**
+     * True when the cursor sits on the `id :` of a `(id: ...)` reference.
+     *
+     * Field names are case-sensitive, so only the exact spelling `id` counts;
+     * `ID` is an ordinary identifier and would not parse as a term anyway.
+     */
+    isPropositionIdStart() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Identifier || tok.value !== 'id')
+            return false;
+        const next = this.peekPast(1);
+        // `(id: :p)` lexes the separator as its own colon; `(id:"P")` likewise,
+        // because a parameter needs an identifier start after the colon.
+        return next?.type === TokenType.Colon;
+    }
+    parseTerm() {
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Variable:
+                return this.parseVariableRef();
+            case TokenType.Parameter:
+                return this.parseParameterRef();
+            case TokenType.LBrace:
+                return this.parseObjectPattern();
+            case TokenType.LParen:
+                return this.parsePropositionTuple();
+            case TokenType.String:
+            case TokenType.Number:
+            case TokenType.Boolean:
+            case TokenType.Null:
+                return this.parseLiteral();
+            default:
+                this.error(`Expected a term (variable, parameter, literal, {...} or a tuple) but got '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+    }
+    /** `predicate_atom = string_literal | parameter | variable` */
+    parsePredicateAtom() {
+        const tok = this.current();
+        if (tok.type === TokenType.String) {
+            return this.parseStringLiteral();
+        }
+        if (tok.type === TokenType.Parameter) {
+            return this.parseParameterRef();
+        }
+        if (tok.type === TokenType.Variable) {
+            return this.parseVariableRef();
+        }
+        this.error(`Expected a predicate (quoted symbol, :parameter or ?variable) but got '${tok.value}'`, tok);
+        throw new ParseAbort();
+    }
+    /**
+     * `raw_predicate_expression` — path atoms joined by `|`.
+     *
+     * Alternation and hop quantifiers are traversal syntax owned by KQL. KML
+     * and META spell the same slot as a bare `predicate_atom`, so in the raw
+     * dialect anything beyond one plain atom is reported here.
+     */
+    parseRawPredicateExpression() {
+        const start = this.currentPos();
+        const atoms = [this.parsePredicatePathAtom()];
+        while (this.check(TokenType.Pipe)) {
+            const pipe = this.current();
+            if (this.dialect === 'raw') {
+                this.error('Predicate alternation is a KQL traversal form and is not allowed here', pipe);
+            }
+            this.advance();
+            atoms.push(this.parsePredicatePathAtom());
+        }
+        return {
+            kind: 'RawPredicateExpression',
+            atoms,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parsePredicatePathAtom() {
+        const start = this.currentPos();
+        const atom = this.parsePredicateAtom();
+        let quantifier;
+        if (this.check(TokenType.LBrace)) {
+            const brace = this.current();
+            if (this.dialect === 'raw') {
+                this.error('Path quantifiers are a KQL traversal form and are not allowed here', brace);
             }
-            else if (this.check(TokenType.Mode)) {
-                this.rejectRepeat(modeValue, 'MODE', clause);
+            quantifier = this.parsePathQuantifier();
+        }
+        return {
+            kind: 'PredicatePathAtom',
+            atom,
+            quantifier,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parsePathQuantifier() {
+        const start = this.currentPos();
+        this.expect(TokenType.LBrace);
+        const min = this.expectHopCount();
+        let max;
+        let hasComma = false;
+        if (this.match(TokenType.Comma)) {
+            hasComma = true;
+            if (!this.check(TokenType.RBrace)) {
+                max = this.expectHopCount();
+            }
+        }
+        else {
+            max = min;
+        }
+        this.expect(TokenType.RBrace);
+        if (max !== undefined && max < min) {
+            this.error(`Hop range {${min},${max}} is empty: the maximum is below the minimum`, this.current());
+        }
+        return {
+            kind: 'PathQuantifier',
+            min,
+            max,
+            hasComma,
+            range: { start, end: this.endPos() }
+        };
+    }
+    /**
+     * A hop count is a plain unsigned integer.
+     *
+     * `{1.5}`, `{-1}` and `{1e3}` all lex as one number token, so the check is
+     * on the token text, not on the parsed value.
+     */
+    expectHopCount() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Number || !/^\d+$/.test(tok.value)) {
+            this.error(`Expected an unsigned integer hop count but got '${tok.value}'`, tok);
+            this.advance();
+            return 0;
+        }
+        const value = Number(tok.value);
+        if (value > 65535) {
+            this.error(`Hop count ${value} exceeds the 16-bit maximum 65535`, tok);
+        }
+        this.advance();
+        return value;
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  KML — MUTATE
+    // ────────────────────────────────────────────────────────────────────
+    parseMutateStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        this.expectKeywordWithSpace(TokenType.Mutate);
+        this.expect(TokenType.LBrace);
+        const clauses = [];
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
+            this.skipComments();
+            if (this.check(TokenType.RBrace) || this.isAtEnd())
+                break;
+            // A nested MUTATE is not a smaller transaction, it is a different
+            // statement; the grammar forbids it outright.
+            if (this.check(TokenType.Mutate)) {
+                this.error('MUTATE cannot contain another MUTATE', this.current());
                 this.advance();
-                modeValue = this.parseStringOrParameterValue('SEARCH MODE');
-                mode =
-                    modeValue.kind === 'StringLiteral' ? modeValue.parsed : modeValue.name;
+                continue;
             }
-            else if (this.check(TokenType.Threshold)) {
-                this.rejectRepeat(threshold, 'THRESHOLD', clause);
-                threshold = this.parseThresholdClause();
+            try {
+                clauses.push(this.parseMutationClause());
             }
-            else if (this.check(TokenType.Limit)) {
-                this.rejectRepeat(limit, 'LIMIT', clause);
-                limit = this.parseLimitClause();
+            catch {
+                this.recoverToMutationBoundary();
+            }
+            if (this.pos === before)
+                break;
+        }
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'MutateStatement',
+            clauses,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  KML — CREATE / UPSERT / ENSURE / ASSERT
+    // ────────────────────────────────────────────────────────────────────
+    parseCreateStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const create = this.expectKeywordWithSpace(TokenType.Create);
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Concept:
+                this.expectSecondWord(TokenType.Concept, create);
+                return this.parseCreateConceptBody(start, leadingComments);
+            case TokenType.Evidence:
+                this.expectSecondWord(TokenType.Evidence, create);
+                return this.parseRecordCreateBody('CreateEvidenceStatement', start, leadingComments);
+            case TokenType.Assertion:
+                this.expectSecondWord(TokenType.Assertion, create);
+                return this.parseRecordCreateBody('CreateAssertionStatement', start, leadingComments);
+            case TokenType.Activity:
+                this.expectSecondWord(TokenType.Activity, create);
+                return this.parseRecordCreateBody('CreateActivityStatement', start, leadingComments);
+            default:
+                this.error(`Expected CONCEPT, EVIDENCE, ASSERTION or ACTIVITY after CREATE but got '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+    }
+    parseCreateConceptBody(start, leadingComments) {
+        const handle = this.expectHandle();
+        this.expect(TokenType.LBrace);
+        const stmt = {
+            kind: 'CreateConceptStatement',
+            handle,
+            setFacets: [],
+            range: { start, end: start },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
+            this.skipComments();
+            if (this.check(TokenType.RBrace) || this.isAtEnd())
+                break;
+            const tok = this.current();
+            switch (tok.type) {
+                case TokenType.Type:
+                    this.rejectRepeat(stmt.type, 'TYPE', tok);
+                    stmt.type = this.parseTypeClause();
+                    break;
+                case TokenType.Client:
+                    this.rejectRepeat(stmt.clientKey, 'CLIENT KEY', tok);
+                    stmt.clientKey = this.parseClientKeyClause();
+                    break;
+                case TokenType.Name:
+                    this.rejectRepeat(stmt.name, 'NAME', tok);
+                    stmt.name = this.parseNameClause();
+                    break;
+                case TokenType.Set:
+                    this.applyCreateSetClause(stmt, tok);
+                    break;
+                default:
+                    this.error(`Unexpected token '${tok.value}' in CREATE CONCEPT`, tok);
+                    this.advance();
+            }
+            if (this.pos === before)
+                break;
+        }
+        this.expect(TokenType.RBrace);
+        stmt.range = { start, end: this.endPos() };
+        return stmt;
+    }
+    applyCreateSetClause(stmt, tok) {
+        const clause = this.parseSetClause();
+        switch (clause.kind) {
+            case 'SetFieldsClause':
+                this.rejectRepeat(stmt.setFields, 'SET FIELDS', tok);
+                stmt.setFields = clause;
+                break;
+            case 'SetAttributesClause':
+                this.rejectRepeat(stmt.setAttributes, 'SET ATTRIBUTES', tok);
+                stmt.setAttributes = clause;
+                break;
+            case 'SetFacetClause':
+                stmt.setFacets.push(clause);
+                break;
+            case 'SetStructuralClause':
+                this.rejectRepeat(stmt.setStructural, 'SET STRUCTURAL', tok);
+                stmt.setStructural = clause;
+                break;
+            default:
+                this.error(`'SET ${clause.kind}' is not allowed in CREATE CONCEPT`, tok);
+        }
+    }
+    /** CREATE EVIDENCE / ASSERTION / ACTIVITY share one clause vocabulary. */
+    parseRecordCreateBody(kind, start, leadingComments) {
+        const handle = this.expectHandle();
+        this.expect(TokenType.LBrace);
+        const stmt = {
+            kind,
+            handle,
+            setFacets: [],
+            clientKey: undefined,
+            setFields: undefined,
+            setStructural: undefined,
+            range: { start, end: start },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
+            this.skipComments();
+            if (this.check(TokenType.RBrace) || this.isAtEnd())
+                break;
+            const tok = this.current();
+            if (tok.type === TokenType.Client) {
+                this.rejectRepeat(stmt.clientKey, 'CLIENT KEY', tok);
+                stmt.clientKey = this.parseClientKeyClause();
+            }
+            else if (tok.type === TokenType.Set) {
+                const clause = this.parseSetClause();
+                if (clause.kind === 'SetFieldsClause') {
+                    this.rejectRepeat(stmt.setFields, 'SET FIELDS', tok);
+                    stmt.setFields = clause;
+                }
+                else if (clause.kind === 'SetFacetClause') {
+                    stmt.setFacets.push(clause);
+                }
+                else if (clause.kind === 'SetStructuralClause') {
+                    this.rejectRepeat(stmt.setStructural, 'SET STRUCTURAL', tok);
+                    stmt.setStructural = clause;
+                }
+                else {
+                    this.error(`'SET ${clause.kind}' is not allowed in ${kind.replace('Statement', '')}`, tok);
+                }
             }
             else {
+                this.error(`Unexpected token '${tok.value}' in ${kind}`, tok);
+                this.advance();
+            }
+            if (this.pos === before)
                 break;
+        }
+        this.expect(TokenType.RBrace);
+        stmt.range = { start, end: this.endPos() };
+        return stmt;
+    }
+    parseUpsertConcept() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const upsert = this.expectKeywordWithSpace(TokenType.Upsert);
+        this.expectSecondWord(TokenType.Concept, upsert);
+        const handle = this.expectHandle();
+        this.expect(TokenType.LBrace);
+        const stmt = {
+            kind: 'UpsertConceptStatement',
+            handle,
+            setFacets: [],
+            unsetFacets: [],
+            range: { start, end: start },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+            const before = this.pos;
+            this.skipComments();
+            if (this.check(TokenType.RBrace) || this.isAtEnd())
+                break;
+            const tok = this.current();
+            switch (tok.type) {
+                case TokenType.Match:
+                    this.rejectRepeat(stmt.match, 'MATCH', tok);
+                    stmt.match = this.parseMatchClause();
+                    break;
+                case TokenType.Expect:
+                    this.rejectRepeat(stmt.expectVersion, 'EXPECT VERSION', tok);
+                    stmt.expectVersion = this.parseExpectVersionClause();
+                    break;
+                case TokenType.Set: {
+                    const clause = this.parseSetClause();
+                    if (clause.kind === 'SetFieldsClause') {
+                        this.rejectRepeat(stmt.setFields, 'SET FIELDS', tok);
+                        stmt.setFields = clause;
+                    }
+                    else if (clause.kind === 'SetAttributesClause') {
+                        this.rejectRepeat(stmt.setAttributes, 'SET ATTRIBUTES', tok);
+                        stmt.setAttributes = clause;
+                    }
+                    else if (clause.kind === 'SetFacetClause') {
+                        stmt.setFacets.push(clause);
+                    }
+                    else if (clause.kind === 'SetStructuralClause') {
+                        this.rejectRepeat(stmt.setStructural, 'SET STRUCTURAL', tok);
+                        stmt.setStructural = clause;
+                    }
+                    else {
+                        this.error(`'SET RETENTION' is not a clause of UPSERT CONCEPT`, tok);
+                    }
+                    break;
+                }
+                case TokenType.Unset: {
+                    const clause = this.parseUnsetClause();
+                    if (clause.kind === 'UnsetAttributesClause') {
+                        this.rejectRepeat(stmt.unsetAttributes, 'UNSET ATTRIBUTES', tok);
+                        stmt.unsetAttributes = clause;
+                    }
+                    else if (clause.kind === 'UnsetStructuralClause') {
+                        this.rejectRepeat(stmt.unsetStructural, 'UNSET STRUCTURAL', tok);
+                        stmt.unsetStructural = clause;
+                    }
+                    else {
+                        stmt.unsetFacets.push(clause);
+                    }
+                    break;
+                }
+                default:
+                    this.error(`Unexpected token '${tok.value}' in UPSERT CONCEPT`, tok);
+                    this.advance();
             }
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
             if (this.pos === before)
                 break;
         }
+        this.expect(TokenType.RBrace);
+        stmt.range = { start, end: this.endPos() };
+        return stmt;
+    }
+    parseEnsureProposition() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const ensure = this.expectKeywordWithSpace(TokenType.Ensure);
+        this.expectSecondWord(TokenType.Proposition, ensure);
+        const handle = this.check(TokenType.Variable)
+            ? this.parseVariableRef()
+            : undefined;
+        this.dialect = 'raw';
+        const tuple = this.parsePropositionTuple();
+        const expectVersion = this.check(TokenType.Expect)
+            ? this.parseExpectVersionClause()
+            : undefined;
+        return {
+            kind: 'EnsurePropositionStatement',
+            handle,
+            tuple,
+            expectVersion,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+    }
+    parseAssertStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        this.expectKeywordWithSpace(TokenType.Assert);
+        const handle = this.check(TokenType.Variable)
+            ? this.parseVariableRef()
+            : undefined;
+        this.dialect = 'raw';
+        const tuple = this.parsePropositionTuple();
+        const assignments = this.parseAssignmentObject();
+        let superseding;
+        if (this.match(TokenType.Superseding)) {
+            superseding = this.parseTargetRef();
+        }
         return {
-            kind: 'SearchStatement',
-            searchTarget,
-            term,
-            termValue,
-            withType,
-            withTypeValue,
-            mode,
-            modeValue,
-            threshold,
-            limit,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'AssertStatement',
+            handle,
+            tuple,
+            assignments,
+            superseding,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
     // ────────────────────────────────────────────────────────────────────
-    //  EXPORT
+    //  KML — clause vocabulary
     // ────────────────────────────────────────────────────────────────────
-    parseExportStatement() {
+    parseTypeClause() {
         const start = this.currentPos();
-        const comments = this.collectLeadingComments();
-        this.expectKeywordWithSpace(TokenType.Export);
-        const target = this.expectVariable();
-        const where = this.parseWhereClause();
-        let limit;
-        let cursor;
-        if (this.check(TokenType.Limit)) {
-            limit = this.parseLimitClause();
-        }
-        if (this.check(TokenType.Cursor)) {
-            cursor = this.parseCursorClause();
-        }
+        this.expect(TokenType.Type);
+        const value = this.parseSchemaSymbol();
+        return { kind: 'TypeClause', value, range: { start, end: this.endPos() } };
+    }
+    parseClientKeyClause() {
+        const start = this.currentPos();
+        const client = this.expect(TokenType.Client);
+        this.expectSecondWord(TokenType.Key, client);
+        const value = this.parseScalarValue();
         return {
-            kind: 'ExportStatement',
-            target,
-            where,
-            limit,
-            cursor,
-            range: { start, end: this.currentPos() },
-            leadingComments: comments.length > 0 ? comments : undefined
+            kind: 'ClientKeyClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    // ────────────────────────────────────────────────────────────────────
-    //  WHERE clause and patterns
-    // ────────────────────────────────────────────────────────────────────
-    parseWhereClause() {
+    parseNameClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Where);
-        this.expect(TokenType.LBrace);
-        const patterns = this.parseWherePatterns();
-        this.expect(TokenType.RBrace);
+        this.expect(TokenType.Name);
+        const value = this.parseScalarValue();
+        return { kind: 'NameClause', value, range: { start, end: this.endPos() } };
+    }
+    parseMatchClause() {
+        const start = this.currentPos();
+        this.expect(TokenType.Match);
+        const pattern = this.parseObjectPattern();
         return {
-            kind: 'WhereClause',
-            patterns,
-            range: { start, end: this.currentPos() }
+            kind: 'MatchClause',
+            pattern,
+            range: { start, end: this.endPos() }
         };
     }
-    parseWherePatterns() {
-        const patterns = [];
-        this.skipComments();
+    /** Dispatches every `SET ...` form; callers reject the ones they disallow. */
+    parseSetClause() {
+        const start = this.currentPos();
+        const set = this.expect(TokenType.Set);
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Fields: {
+                this.expectSecondWord(TokenType.Fields, set);
+                const assignments = this.parseAssignmentObject();
+                return {
+                    kind: 'SetFieldsClause',
+                    assignments,
+                    range: { start, end: this.endPos() }
+                };
+            }
+            case TokenType.Attributes: {
+                this.expectSecondWord(TokenType.Attributes, set);
+                const assignments = this.parseAssignmentObject();
+                return {
+                    kind: 'SetAttributesClause',
+                    assignments,
+                    range: { start, end: this.endPos() }
+                };
+            }
+            case TokenType.Facet: {
+                this.expectSecondWord(TokenType.Facet, set);
+                const facet = this.parseSchemaSymbol();
+                const assignments = this.parseAssignmentObject();
+                return {
+                    kind: 'SetFacetClause',
+                    facet,
+                    assignments,
+                    range: { start, end: this.endPos() }
+                };
+            }
+            case TokenType.Structural: {
+                this.expectSecondWord(TokenType.Structural, set);
+                return this.parseSetStructuralBody(start);
+            }
+            case TokenType.Retention:
+                return { kind: 'SetRetentionMarker' };
+            default:
+                this.error(`Expected FIELDS, ATTRIBUTES, FACET, STRUCTURAL or RETENTION after SET but got '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+    }
+    parseSetStructuralBody(start) {
+        this.expect(TokenType.LBrace);
+        const assignments = [];
         while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
             const before = this.pos;
             this.skipComments();
-            if (this.check(TokenType.RBrace))
+            if (this.check(TokenType.RBrace) || this.isAtEnd())
                 break;
-            const pattern = this.parseWherePattern();
-            if (pattern)
-                patterns.push(pattern);
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
+            assignments.push(this.parseStructuralAssignment());
             if (this.pos === before)
                 break;
         }
-        return patterns;
-    }
-    parseWherePattern() {
-        this.skipComments();
-        const tok = this.current();
-        if (tok.type === TokenType.Filter) {
-            return this.parseFilterClause();
-        }
-        if (tok.type === TokenType.Not) {
-            return this.parseNotClause();
-        }
-        if (tok.type === TokenType.Optional) {
-            return this.parseOptionalClause();
-        }
-        if (tok.type === TokenType.Union) {
-            return this.parseUnionClause();
-        }
-        // Variable: could be concept pattern or proposition pattern
-        if (tok.type === TokenType.Variable) {
-            return this.parseVariableLeadingPattern();
-        }
-        // Opening ( = proposition pattern without variable binding
-        if (tok.type === TokenType.LParen) {
-            return this.parsePropositionPatternBody(undefined);
-        }
-        this.error(`Unexpected token '${tok.value}' in WHERE clause`, tok);
-        this.advance();
-        return null;
-    }
-    parseVariableLeadingPattern() {
-        // ?var could be followed by:
-        //  { ... }  => concept pattern
-        //  ( ... )  => proposition pattern
-        const start = this.currentPos();
-        const variable = this.expectVariable();
-        if (this.check(TokenType.LBrace)) {
-            return this.parseConceptPatternBody(variable, start);
-        }
-        if (this.check(TokenType.LParen)) {
-            return this.parsePropositionPatternBody(variable, start);
-        }
-        // Just a variable reference as a standalone concept pattern without matcher
-        // This occurs in WHERE like: ?drug {type: "Drug"}
-        this.error(`Expected '{' or '(' after variable '${variable}' in WHERE clause`, this.current());
-        return {
-            kind: 'ConceptPattern',
-            variable,
-            matcher: {
-                kind: 'ConceptMatcher',
-                entries: [],
-                range: { start, end: this.currentPos() }
-            },
-            range: { start, end: this.currentPos() }
-        };
-    }
-    parseConceptPatternBody(variable, start) {
-        const matcher = this.parseConceptMatcher();
-        return {
-            kind: 'ConceptPattern',
-            variable,
-            matcher,
-            range: { start, end: this.currentPos() }
-        };
-    }
-    parseConceptMatcher() {
-        const start = this.currentPos();
-        const brace = this.expect(TokenType.LBrace);
-        const seen = { trailingComma: false };
-        const entries = this.parseObjectEntries(seen);
-        if (seen.trailingComma) {
-            this.error(`A concept matcher takes no trailing comma`, brace);
-        }
         this.expect(TokenType.RBrace);
         return {
-            kind: 'ConceptMatcher',
-            entries,
-            range: { start, end: this.currentPos() }
+            kind: 'SetStructuralClause',
+            assignments,
+            range: { start, end: this.endPos() }
         };
     }
-    parsePropositionPatternBody(variable, start = this.currentPos()) {
+    parseStructuralAssignment() {
+        const start = this.currentPos();
         this.expect(TokenType.LParen);
-        if (this.isIdMatcherStart()) {
-            const id = this.parseIdMatcherValue();
-            this.expect(TokenType.RParen);
-            return {
-                kind: 'PropositionPattern',
-                variable,
-                id,
-                range: { start, end: this.currentPos() }
-            };
-        }
-        const subject = this.parsePropositionEndpoint();
-        this.expect(TokenType.Comma);
-        const predicate = this.parsePredicateExpr();
+        const field = this.parseSchemaSymbol();
         this.expect(TokenType.Comma);
-        const object = this.parsePropositionEndpoint();
+        const value = this.parseMutationValue();
         this.expect(TokenType.RParen);
+        const options = this.check(TokenType.LBrace)
+            ? this.parseObjectLiteral()
+            : undefined;
         return {
-            kind: 'PropositionPattern',
-            variable,
-            subject,
-            predicate,
-            object,
-            range: { start, end: this.currentPos() }
+            kind: 'StructuralAssignment',
+            field,
+            value,
+            options,
+            range: { start, end: this.endPos() }
         };
     }
-    parsePropositionEndpoint() {
-        // Could be: ?var, ?var {...}, ?var (...), {...}, or nested (...)
-        if (this.check(TokenType.Variable)) {
-            const start = this.currentPos();
-            const name = this.expectVariable();
-            if (this.check(TokenType.LBrace)) {
-                return this.parseConceptPatternBody(name, start);
-            }
-            if (this.check(TokenType.LParen)) {
-                return this.parsePropositionPatternBody(name, start);
-            }
-            return {
-                kind: 'VariableRef',
-                name,
-                range: { start, end: this.currentPos() }
-            };
-        }
-        if (this.check(TokenType.LBrace)) {
-            const start = this.currentPos();
-            const matcher = this.parseConceptMatcher();
+    parseUnsetClause() {
+        const start = this.currentPos();
+        const unset = this.expect(TokenType.Unset);
+        const tok = this.current();
+        if (tok.type === TokenType.Attributes) {
+            this.expectSecondWord(TokenType.Attributes, unset);
+            const fields = this.parseUnsetFieldSet();
             return {
-                kind: 'ConceptPattern',
-                matcher,
-                range: { start, end: this.currentPos() }
+                kind: 'UnsetAttributesClause',
+                fields,
+                range: { start, end: this.endPos() }
             };
         }
-        if (this.check(TokenType.LParen)) {
-            return this.parsePropositionPatternBody(undefined);
-        }
-        this.error(`Expected variable, concept pattern, or proposition pattern`, this.current());
-        const start = this.currentPos();
-        return {
-            kind: 'VariableRef',
-            name: '?unknown',
-            range: { start, end: start }
-        };
-    }
-    parsePredicateExpr() {
-        const start = this.currentPos();
-        if (this.check(TokenType.Variable)) {
-            const pred = this.parsePredicateVariable();
-            if (this.check(TokenType.LBrace)) {
-                this.error(`Predicate variables cannot use hop ranges; use a quoted predicate literal for path traversal`, this.current());
-                this.parseHopRange();
-            }
-            if (this.check(TokenType.Pipe)) {
-                this.error(`Predicate variables cannot be used in predicate alternations`, this.current());
-                while (this.match(TokenType.Pipe)) {
-                    if (this.check(TokenType.String)) {
-                        this.parsePredicateLiteral();
-                    }
-                    else if (this.check(TokenType.Variable)) {
-                        this.parsePredicateVariable();
-                    }
-                    else {
-                        break;
-                    }
-                }
-            }
+        if (tok.type === TokenType.Facet) {
+            this.expectSecondWord(TokenType.Facet, unset);
+            const facet = this.parseSchemaSymbol();
+            const fields = this.parseUnsetFieldSet();
             return {
-                ...pred,
-                range: { start, end: this.currentPos() }
+                kind: 'UnsetFacetClause',
+                facet,
+                fields,
+                range: { start, end: this.endPos() }
             };
         }
-        const first = this.parsePredicateLiteral();
-        // Check for alternation: "pred1" | "pred2"
-        if (this.check(TokenType.Pipe)) {
-            const predicates = [first];
-            while (this.match(TokenType.Pipe)) {
-                predicates.push(this.parsePredicateLiteral());
+        if (tok.type === TokenType.Structural) {
+            // Every SET has an UNSET: an entry is the SET STRUCTURAL entry without
+            // its options object (Spec §17.5).
+            this.expectSecondWord(TokenType.Structural, unset);
+            this.expect(TokenType.LBrace);
+            const removals = [];
+            while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
+                const before = this.pos;
+                this.skipComments();
+                if (this.check(TokenType.RBrace) || this.isAtEnd())
+                    break;
+                removals.push(this.parseStructuralRemoval());
+                if (this.pos === before)
+                    break;
             }
+            this.expect(TokenType.RBrace);
             return {
-                kind: 'PredicateAlternation',
-                predicates,
-                range: { start, end: this.currentPos() }
+                kind: 'UnsetStructuralClause',
+                removals,
+                range: { start, end: this.endPos() }
             };
         }
-        return first;
-    }
-    parsePredicateVariable() {
-        const start = this.currentPos();
-        const name = this.expectVariable();
-        return {
-            kind: 'PredicateVariable',
-            name,
-            range: { start, end: this.currentPos() }
-        };
+        this.error(`Expected ATTRIBUTES, FACET or STRUCTURAL after UNSET but got '${tok.value}'`, tok);
+        throw new ParseAbort();
     }
-    parsePredicateLiteral() {
+    parseStructuralRemoval() {
         const start = this.currentPos();
-        const value = this.expectStringValue();
-        // Check for hop range: {m,n} {m,} {m}
-        let hopRange;
+        this.expect(TokenType.LParen);
+        const field = this.parseSchemaSymbol();
+        this.expect(TokenType.Comma);
+        const value = this.parseMutationValue();
+        this.expect(TokenType.RParen);
         if (this.check(TokenType.LBrace)) {
-            hopRange = this.parseHopRange();
+            this.error('UNSET STRUCTURAL removes a reference by (field, target); it takes no options object', this.current());
         }
         return {
-            kind: 'PredicateLiteral',
+            kind: 'StructuralRemoval',
+            field,
             value,
-            hopRange,
-            range: { start, end: this.currentPos() }
+            range: { start, end: this.endPos() }
         };
     }
-    parseHopRange() {
-        const start = this.currentPos();
+    parseUnsetFieldSet() {
         this.expect(TokenType.LBrace);
-        const min = this.expectHopCount();
-        let max;
-        if (this.match(TokenType.Comma)) {
-            if (this.check(TokenType.Number)) {
-                max = this.expectHopCount();
-            }
-            // else: {m,} means unbounded
-        }
-        else {
-            max = min; // {m} means exactly m
+        const fields = [];
+        if (!this.check(TokenType.RBrace)) {
+            do {
+                if (this.check(TokenType.RBrace))
+                    break;
+                const start = this.currentPos();
+                const { key, isQuoted } = this.expectKeyWithQuoting();
+                fields.push({
+                    kind: 'UnsetField',
+                    name: key,
+                    isQuoted,
+                    range: { start, end: this.endPos() }
+                });
+            } while (this.match(TokenType.Comma));
         }
         this.expect(TokenType.RBrace);
-        return {
-            kind: 'HopRange',
-            min,
-            max,
-            range: { start, end: this.currentPos() }
-        };
-    }
-    /**
-     * Reads one bound of a `{m,n}` hop quantifier.
-     *
-     * A hop count is a plain 16-bit integer — no sign, no decimal point, no
-     * exponent. `"p"{1e9,}` is not an enormous traversal, it is a typo, and
-     * accepting it would hand the engine a bound it cannot honour.
-     */
-    expectHopCount() {
-        const tok = this.current();
-        if (tok.type !== TokenType.Number || !/^[0-9]+$/.test(tok.value)) {
-            this.error(`Expected a whole number in a hop range`, tok);
-            this.advance();
-            return 0;
-        }
-        const value = Number(tok.value);
-        if (value > 0xffff) {
-            this.error(`Hop count ${tok.value} exceeds the maximum of 65535`, tok);
-        }
-        this.advance();
-        return value;
-    }
-    parseFilterClause() {
-        const start = this.currentPos();
-        this.expect(TokenType.Filter);
-        this.expect(TokenType.LParen);
-        const expression = this.parseExpression();
-        this.expect(TokenType.RParen);
-        return {
-            kind: 'FilterClause',
-            expression,
-            range: { start, end: this.currentPos() }
-        };
+        return fields;
     }
-    parseNotClause() {
+    parseExpectVersionClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Not);
-        this.expect(TokenType.LBrace);
-        const patterns = this.parseWherePatterns();
-        this.expect(TokenType.RBrace);
+        const expect = this.expect(TokenType.Expect);
+        this.expectSecondWord(TokenType.Version, expect);
+        const value = this.parseScalarValue();
         return {
-            kind: 'NotClause',
-            patterns,
-            range: { start, end: this.currentPos() }
+            kind: 'ExpectVersionClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    parseOptionalClause() {
+    parseExpectStateClause() {
         const start = this.currentPos();
-        this.expect(TokenType.Optional);
-        this.expect(TokenType.LBrace);
-        const patterns = this.parseWherePatterns();
-        this.expect(TokenType.RBrace);
+        const expect = this.expect(TokenType.Expect);
+        this.expectSecondWord(TokenType.State, expect);
+        const value = this.parseScalarValue();
         return {
-            kind: 'OptionalClause',
-            patterns,
-            range: { start, end: this.currentPos() }
+            kind: 'ExpectStateClause',
+            value,
+            range: { start, end: this.endPos() }
         };
     }
-    parseUnionClause() {
+    // ────────────────────────────────────────────────────────────────────
+    //  KML — UPDATE
+    // ────────────────────────────────────────────────────────────────────
+    parseUpdateStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        this.expect(TokenType.Union);
-        this.expect(TokenType.LBrace);
-        const patterns = this.parseWherePatterns();
-        this.expect(TokenType.RBrace);
+        this.expectKeywordWithSpace(TokenType.Update);
+        const target = this.parseTargetRef();
+        const expectVersion = this.check(TokenType.Expect)
+            ? this.parseExpectVersionClause()
+            : undefined;
+        const actions = [];
+        for (;;) {
+            if (this.check(TokenType.Set)) {
+                const clause = this.parseSetClause();
+                if (clause.kind === 'SetRetentionMarker') {
+                    this.error('SET RETENTION is its own statement, not an UPDATE action', this.current());
+                    break;
+                }
+                actions.push(clause);
+            }
+            else if (this.check(TokenType.Unset)) {
+                actions.push(this.parseUnsetClause());
+            }
+            else {
+                break;
+            }
+        }
+        if (actions.length === 0) {
+            this.error('UPDATE requires at least one SET or UNSET action', this.current());
+        }
+        // WHERE binds a ?variable target; a direct :id / "id" target already names
+        // the element and may omit it, exactly as ARCHIVE / TOMBSTONE / PURGE /
+        // SET RETENTION / RETRACT ASSERTION do (Spec §58). Whether a bare
+        // ?variable is bound is semantic — inside MUTATE it may be a local handle.
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
+        }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
         return {
-            kind: 'UnionClause',
-            patterns,
-            range: { start, end: this.currentPos() }
+            kind: 'UpdateStatement',
+            target,
+            expectVersion,
+            actions,
+            where,
+            limit,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
     // ────────────────────────────────────────────────────────────────────
-    //  SET ATTRIBUTES / SET PROPOSITIONS / WITH METADATA
+    //  KML — lifecycle and correction
     // ────────────────────────────────────────────────────────────────────
-    parseSetAttributesBody(start) {
-        this.expect(TokenType.LBrace);
-        const entries = this.parseObjectEntries();
-        this.expect(TokenType.RBrace);
+    parseRetractAssertion() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const retract = this.expectKeywordWithSpace(TokenType.Retract);
+        this.expectSecondWord(TokenType.Assertion, retract);
+        const target = this.parseTargetRef();
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
+        }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const expectState = this.check(TokenType.Expect)
+            ? this.parseExpectStateClause()
+            : undefined;
         return {
-            kind: 'SetAttributes',
-            entries,
-            range: { start, end: this.currentPos() }
+            kind: 'RetractAssertionStatement',
+            target,
+            where,
+            limit,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseSetMetadataBody(start) {
-        this.expect(TokenType.LBrace);
-        const entries = this.parseObjectEntries();
-        this.expect(TokenType.RBrace);
+    parseSupersedeAssertion() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const supersede = this.expectKeywordWithSpace(TokenType.Supersede);
+        this.expectSecondWord(TokenType.Assertion, supersede);
+        const target = this.parseTargetRef();
+        this.expect(TokenType.By);
+        const by = this.parseTargetRef();
+        const expectState = this.check(TokenType.Expect)
+            ? this.parseExpectStateClause()
+            : undefined;
         return {
-            kind: 'SetMetadata',
-            entries,
-            range: { start, end: this.currentPos() }
+            kind: 'SupersedeAssertionStatement',
+            target,
+            by,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseSetPropositionsBody(start) {
-        this.expect(TokenType.LBrace);
-        const items = [];
-        this.skipComments();
-        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const before = this.pos;
-            this.skipComments();
-            if (this.check(TokenType.RBrace))
-                break;
-            items.push(this.parsePropositionItem());
-            this.skipComments();
-            // Items are juxtaposed, but a separating comma — including a trailing
-            // one — is tolerated. Generated KML reaches for it constantly, and the
-            // reference grammar accepts it.
-            this.match(TokenType.Comma);
-            this.skipComments();
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
+    parseCorrectEvidence() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const correct = this.expectKeywordWithSpace(TokenType.Correct);
+        this.expectSecondWord(TokenType.Evidence, correct);
+        const target = this.parseTargetRef();
+        this.expect(TokenType.By);
+        const by = this.parseTargetRef();
+        const expectState = this.check(TokenType.Expect)
+            ? this.parseExpectStateClause()
+            : undefined;
+        return {
+            kind: 'CorrectEvidenceStatement',
+            target,
+            by,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+    }
+    parseTransitionActivity() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const transition = this.expectKeywordWithSpace(TokenType.Transition);
+        this.expectSecondWord(TokenType.Activity, transition);
+        const target = this.parseTargetRef();
+        this.expect(TokenType.To);
+        const to = this.parseScalarValue();
+        // Terminal outputs and ended_at may be finalized in the same statement
+        // that moves the Activity to its terminal state.
+        const finalize = [];
+        while (this.check(TokenType.Set)) {
+            const clause = this.parseSetClause();
+            if (clause.kind === 'SetFieldsClause' || clause.kind === 'SetStructuralClause') {
+                finalize.push(clause);
+            }
+            else {
+                this.error('TRANSITION ACTIVITY accepts only SET FIELDS and SET STRUCTURAL', this.current());
                 break;
+            }
         }
-        this.expect(TokenType.RBrace);
+        const expectState = this.check(TokenType.Expect)
+            ? this.parseExpectStateClause()
+            : undefined;
         return {
-            kind: 'SetPropositions',
-            items,
-            range: { start, end: this.currentPos() }
+            kind: 'TransitionActivityStatement',
+            target,
+            to,
+            finalize,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parsePropositionItem() {
+    // ────────────────────────────────────────────────────────────────────
+    //  KML — retention and removal
+    // ────────────────────────────────────────────────────────────────────
+    parseSetRetention() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        this.expect(TokenType.LParen);
-        const predicate = this.expectStringValue();
-        this.expect(TokenType.Comma);
-        const target = this.parsePropositionEndpoint();
-        this.expect(TokenType.RParen);
-        let metadata;
-        if (this.check(TokenType.With)) {
-            metadata = this.parseWithMetadata();
+        const set = this.expectKeywordWithSpace(TokenType.Set);
+        this.expectSecondWord(TokenType.Retention, set);
+        const target = this.parseTargetRef();
+        const assignments = this.parseAssignmentObject();
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
         }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const expectVersion = this.check(TokenType.Expect)
+            ? this.parseExpectVersionClause()
+            : undefined;
         return {
-            kind: 'PropositionItem',
-            predicate,
+            kind: 'SetRetentionStatement',
             target,
-            metadata,
-            range: { start, end: this.currentPos() }
+            assignments,
+            where,
+            limit,
+            expectVersion,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    isIdMatcherStart() {
-        if (!this.isIdKeyToken(this.current()))
-            return false;
-        const next = this.peekPast(this.pos + 1);
-        // `(id: "...")` may be written with a comment between the key and the
-        // colon; comments are trivia everywhere else, so they are here too.
-        return (next?.type === TokenType.Colon ||
-            (next?.type === TokenType.Parameter && next.value.startsWith(':')));
+    parseArchiveStatement() {
+        const { start, target, where, limit, expectState, leadingComments } = this.parseRemovalBody(TokenType.Archive);
+        return {
+            kind: 'ArchiveStatement',
+            target,
+            where,
+            limit,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments
+        };
     }
-    /** The first non-comment token at or after `i`. */
-    peekPast(i) {
-        while (this.tokens[i]?.type === TokenType.Comment)
-            i++;
-        return this.tokens[i];
+    parseTombstoneStatement() {
+        const { start, target, where, limit, expectState, leadingComments } = this.parseRemovalBody(TokenType.Tombstone);
+        return {
+            kind: 'TombstoneStatement',
+            target,
+            where,
+            limit,
+            expectState,
+            range: { start, end: this.endPos() },
+            leadingComments
+        };
     }
-    parseIdMatcherValue() {
-        const keyTok = this.current();
-        if (!this.isIdKeyToken(keyTok)) {
-            this.error(`Expected id matcher key but got '${keyTok.value}'`, keyTok);
+    /** ARCHIVE and TOMBSTONE share one shape; PURGE adds its confirmation. */
+    parseRemovalBody(keyword) {
+        const comments = this.collectLeadingComments();
+        const start = this.currentPos();
+        this.expectKeywordWithSpace(keyword);
+        const target = this.parseTargetRef();
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
         }
-        this.advance();
-        this.expect(TokenType.Colon);
-        return this.parseStringOrParameterValue('proposition id');
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const expectState = this.check(TokenType.Expect)
+            ? this.parseExpectStateClause()
+            : undefined;
+        return {
+            start,
+            target,
+            where,
+            limit,
+            expectState,
+            leadingComments: comments.length ? comments : undefined
+        };
     }
-    parseStringOrParameterValue(context) {
-        const tok = this.current();
+    parsePurgeStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        if (tok.type === TokenType.String) {
-            this.advance();
-            return {
-                kind: 'StringLiteral',
-                value: tok.value,
-                parsed: this.unescapeString(tok.value, tok),
-                range: { start, end: this.currentPos() }
-            };
+        this.expectKeywordWithSpace(TokenType.Purge);
+        const target = this.parseTargetRef();
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
         }
-        if (tok.type === TokenType.Parameter) {
-            this.advance();
-            return {
-                kind: 'ParameterRef',
-                name: tok.value,
-                range: { start, end: this.currentPos() }
-            };
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        let referencePolicy;
+        if (this.check(TokenType.Reference)) {
+            const reference = this.expect(TokenType.Reference);
+            this.expectSecondWord(TokenType.Policy, reference);
+            referencePolicy = this.parseScalarValue();
+        }
+        // The grammar freezes the confirmation spelling. Physical erasure is
+        // exceptional, so the literal is required and checked here rather than
+        // left for the engine to discover.
+        this.expect(TokenType.Confirm);
+        const confirmTok = this.current();
+        const confirm = this.parseStringLiteral();
+        if (confirm.parsed !== 'PURGE') {
+            this.error(`PURGE must be confirmed with the exact literal "PURGE", got ${confirmTok.value}`, confirmTok);
         }
-        this.error(`Expected string or parameter for ${context}`, tok);
         return {
-            kind: 'StringLiteral',
-            value: '""',
-            parsed: '',
-            range: { start, end: start }
+            kind: 'PurgeStatement',
+            target,
+            where,
+            limit,
+            referencePolicy,
+            confirm,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    isIdKeyToken(tok) {
-        return ((tok.type === TokenType.Identifier && tok.value === 'id') ||
-            (tok.type === TokenType.String && this.unescapeString(tok.value) === 'id'));
-    }
-    parseWithMetadata() {
+    parseMergeConcept() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        const withTok = this.expect(TokenType.With);
-        this.expectSecondWord(TokenType.Metadata, withTok);
-        this.expect(TokenType.LBrace);
-        const entries = this.parseObjectEntries();
-        this.expect(TokenType.RBrace);
+        const merge = this.expectKeywordWithSpace(TokenType.Merge);
+        this.expectSecondWord(TokenType.Concept, merge);
+        const source = this.parseTargetRef();
+        this.expect(TokenType.Into);
+        const into = this.parseTargetRef();
+        let where;
+        if (this.check(TokenType.Where)) {
+            this.expectKeywordWithSpace(TokenType.Where);
+            this.dialect = 'raw';
+            where = this.parseWhereClause();
+        }
+        const expectVersion = this.check(TokenType.Expect)
+            ? this.parseExpectVersionClause()
+            : undefined;
         return {
-            kind: 'WithMetadata',
-            entries,
-            range: { start, end: this.currentPos() }
+            kind: 'MergeConceptStatement',
+            source,
+            into,
+            where,
+            expectVersion,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseExpectVersion() {
+    // ────────────────────────────────────────────────────────────────────
+    //  META — DESCRIBE
+    // ────────────────────────────────────────────────────────────────────
+    parseDescribeStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const describe = this.expectKeywordWithSpace(TokenType.Describe);
+        const tok = this.current();
+        const stmt = (target, extra = {}) => ({
+            kind: 'DescribeStatement',
+            target,
+            ...extra,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        });
+        switch (tok.type) {
+            case TokenType.Primer: {
+                this.expectSecondWord(TokenType.Primer, describe);
+                let mode;
+                if (this.match(TokenType.Mode))
+                    mode = this.parseScalarValue();
+                return stmt('PRIMER', { mode });
+            }
+            case TokenType.Protocol:
+                this.expectSecondWord(TokenType.Protocol, describe);
+                return stmt('PROTOCOL');
+            case TokenType.Execution: {
+                const exec = this.expectSecondWord(TokenType.Execution, describe);
+                this.expectSecondWord(TokenType.Context, exec);
+                return stmt('EXECUTION_CONTEXT');
+            }
+            case TokenType.Capabilities:
+                this.expectSecondWord(TokenType.Capabilities, describe);
+                return stmt('CAPABILITIES');
+            case TokenType.Space: {
+                this.expectSecondWord(TokenType.Space, describe);
+                const value = this.isMetaValueStart() ? this.parseScalarValue() : undefined;
+                return stmt('SPACE', { value });
+            }
+            case TokenType.Schema: {
+                const schema = this.expectSecondWord(TokenType.Schema, describe);
+                this.expectSecondWord(TokenType.Environment, schema);
+                const asOf = this.check(TokenType.As) ? this.parseAsOfClause() : undefined;
+                return stmt('SCHEMA_ENVIRONMENT', { asOf });
+            }
+            case TokenType.Package:
+                this.expectSecondWord(TokenType.Package, describe);
+                return stmt('PACKAGE', { value: this.parseScalarValue() });
+            case TokenType.Type:
+                this.expectSecondWord(TokenType.Type, describe);
+                return stmt('TYPE', { value: this.parseScalarValue() });
+            case TokenType.Predicate:
+                this.expectSecondWord(TokenType.Predicate, describe);
+                return stmt('PREDICATE', { value: this.parseScalarValue() });
+            case TokenType.Facet:
+                this.expectSecondWord(TokenType.Facet, describe);
+                return stmt('FACET', { value: this.parseScalarValue() });
+            case TokenType.Structural: {
+                const structural = this.expectSecondWord(TokenType.Structural, describe);
+                this.expectSecondWord(TokenType.Field, structural);
+                return stmt('STRUCTURAL_FIELD', { value: this.parseScalarValue() });
+            }
+            case TokenType.Compatibility: {
+                this.expectSecondWord(TokenType.Compatibility, describe);
+                this.expect(TokenType.From);
+                const from = this.parseScalarValue();
+                this.expect(TokenType.To);
+                const to = this.parseScalarValue();
+                return stmt('COMPATIBILITY', { from, to });
+            }
+            case TokenType.Error:
+                this.expectSecondWord(TokenType.Error, describe);
+                return stmt('ERROR', { value: this.parseScalarValue() });
+            case TokenType.Transaction: {
+                const transaction = this.expectSecondWord(TokenType.Transaction, describe);
+                if (this.check(TokenType.By)) {
+                    const by = this.expectSecondWord(TokenType.By, transaction);
+                    const idem = this.expectSecondWord(TokenType.Idempotency, by);
+                    this.expectSecondWord(TokenType.Key, idem);
+                    return stmt('TRANSACTION_BY_IDEMPOTENCY_KEY', {
+                        value: this.parseScalarValue()
+                    });
+                }
+                return stmt('TRANSACTION', { value: this.parseScalarValue() });
+            }
+            case TokenType.Snapshot: {
+                this.expectSecondWord(TokenType.Snapshot, describe);
+                const asOf = this.check(TokenType.As) ? this.parseAsOfClause() : undefined;
+                return stmt('SNAPSHOT', { asOf });
+            }
+            case TokenType.Capsule:
+                this.expectSecondWord(TokenType.Capsule, describe);
+                return stmt('CAPSULE', { value: this.parseScalarValue() });
+            case TokenType.Epistemic: {
+                const epistemic = this.expectSecondWord(TokenType.Epistemic, describe);
+                this.expectSecondWord(TokenType.Policy, epistemic);
+                const value = this.isMetaValueStart() ? this.parseScalarValue() : undefined;
+                return stmt('EPISTEMIC_POLICY', { value });
+            }
+            case TokenType.Projection: {
+                const projection = this.expectSecondWord(TokenType.Projection, describe);
+                this.expectSecondWord(TokenType.Capability, projection);
+                return stmt('PROJECTION_CAPABILITY');
+            }
+            case TokenType.Trust: {
+                this.expectSecondWord(TokenType.Trust, describe);
+                const value = this.isMetaValueStart() ? this.parseScalarValue() : undefined;
+                return stmt('TRUST', { value });
+            }
+            case TokenType.Access: {
+                this.expectSecondWord(TokenType.Access, describe);
+                const withOptions = this.match(TokenType.With)
+                    ? this.parseObjectLiteral()
+                    : undefined;
+                return stmt('ACCESS', { with: withOptions });
+            }
+            default:
+                this.error(`Unknown DESCRIBE target '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  META — LIST
+    // ────────────────────────────────────────────────────────────────────
+    parseListStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        const expectTok = this.expect(TokenType.Expect);
-        this.expectSecondWord(TokenType.Version, expectTok);
-        const value = this.parseNumberOrParameterValue('EXPECT VERSION');
+        const list = this.expectKeywordWithSpace(TokenType.List);
+        const tok = this.current();
+        let target;
+        let status;
+        switch (tok.type) {
+            case TokenType.Spaces:
+                this.expectSecondWord(TokenType.Spaces, list);
+                target = 'SPACES';
+                break;
+            case TokenType.Schema: {
+                const schema = this.expectSecondWord(TokenType.Schema, list);
+                this.expectSecondWord(TokenType.Packages, schema);
+                target = 'SCHEMA_PACKAGES';
+                if (this.match(TokenType.Status))
+                    status = this.parseScalarValue();
+                break;
+            }
+            case TokenType.Types:
+                this.expectSecondWord(TokenType.Types, list);
+                target = 'TYPES';
+                break;
+            case TokenType.Predicates:
+                this.expectSecondWord(TokenType.Predicates, list);
+                target = 'PREDICATES';
+                break;
+            case TokenType.Facets:
+                this.expectSecondWord(TokenType.Facets, list);
+                target = 'FACETS';
+                break;
+            case TokenType.Structural: {
+                const structural = this.expectSecondWord(TokenType.Structural, list);
+                this.expectSecondWord(TokenType.Fields, structural);
+                target = 'STRUCTURAL_FIELDS';
+                break;
+            }
+            case TokenType.Epistemic: {
+                const epistemic = this.expectSecondWord(TokenType.Epistemic, list);
+                this.expectSecondWord(TokenType.Policies, epistemic);
+                target = 'EPISTEMIC_POLICIES';
+                break;
+            }
+            default:
+                this.error(`Unknown LIST target '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const cursor = this.check(TokenType.Cursor)
+            ? this.parseCursorClause()
+            : undefined;
         return {
-            kind: 'ExpectVersion',
-            value,
-            range: { start, end: this.currentPos() }
+            kind: 'ListStatement',
+            target,
+            status,
+            limit,
+            cursor,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
     // ────────────────────────────────────────────────────────────────────
-    //  ORDER BY, LIMIT, CURSOR
+    //  META — SEARCH
     // ────────────────────────────────────────────────────────────────────
-    parseOrderBy() {
+    parseSearchStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        const orderTok = this.expect(TokenType.Order);
-        this.expectSecondWord(TokenType.By, orderTok);
-        const keys = [];
-        keys.push(this.parseOrderByKey());
-        while (this.match(TokenType.Comma)) {
-            keys.push(this.parseOrderByKey());
+        const search = this.expectKeywordWithSpace(TokenType.Search);
+        const kindTok = this.current();
+        let searchKind;
+        switch (kindTok.type) {
+            case TokenType.Concept:
+                searchKind = 'CONCEPT';
+                break;
+            case TokenType.Proposition:
+                searchKind = 'PROPOSITION';
+                break;
+            case TokenType.Assertion:
+                searchKind = 'ASSERTION';
+                break;
+            case TokenType.Evidence:
+                searchKind = 'EVIDENCE';
+                break;
+            case TokenType.Activity:
+                searchKind = 'ACTIVITY';
+                break;
+            case TokenType.Cognition:
+                searchKind = 'COGNITION';
+                break;
+            default:
+                this.error(`Expected CONCEPT, PROPOSITION, ASSERTION, EVIDENCE, ACTIVITY or COGNITION after SEARCH but got '${kindTok.value}'`, kindTok);
+                throw new ParseAbort();
+        }
+        this.expectSecondWord(kindTok.type, search);
+        const term = this.parseScalarValue();
+        let withType;
+        let withPredicate;
+        let mode;
+        let threshold;
+        let asOfSeq;
+        // The grammar fixes this order; each modifier is taken at most once.
+        while (this.check(TokenType.With)) {
+            const withTok = this.expect(TokenType.With);
+            if (this.check(TokenType.Type)) {
+                this.expectSecondWord(TokenType.Type, withTok);
+                this.rejectRepeat(withType, 'WITH TYPE', withTok);
+                withType = this.parseScalarValue();
+            }
+            else if (this.check(TokenType.Predicate)) {
+                this.expectSecondWord(TokenType.Predicate, withTok);
+                this.rejectRepeat(withPredicate, 'WITH PREDICATE', withTok);
+                withPredicate = this.parseScalarValue();
+            }
+            else {
+                this.error(`Expected TYPE or PREDICATE after WITH but got '${this.current().value}'`, this.current());
+                break;
+            }
         }
-        const first = keys[0];
+        if (this.match(TokenType.Mode))
+            mode = this.parseScalarValue();
+        if (this.match(TokenType.Threshold))
+            threshold = this.parseScalarValue();
+        if (this.check(TokenType.As)) {
+            const as = this.expect(TokenType.As);
+            const of = this.expectSecondWord(TokenType.Of, as);
+            this.expectSecondWord(TokenType.Seq, of);
+            asOfSeq = this.parseScalarValue();
+        }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const cursor = this.check(TokenType.Cursor)
+            ? this.parseCursorClause()
+            : undefined;
         return {
-            kind: 'OrderByClause',
-            keys,
-            expression: first.expression,
-            direction: first.direction,
-            range: { start, end: this.currentPos() }
+            kind: 'SearchStatement',
+            searchKind,
+            term,
+            withType,
+            withPredicate,
+            mode,
+            threshold,
+            asOfSeq,
+            limit,
+            cursor,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseOrderByKey() {
+    // ────────────────────────────────────────────────────────────────────
+    //  META — VERIFY / VALIDATE / PREVIEW
+    // ────────────────────────────────────────────────────────────────────
+    parseVerifyStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        const expression = this.parseExpression();
-        let direction = 'ASC';
-        if (this.check(TokenType.Asc)) {
-            this.advance();
-            direction = 'ASC';
-        }
-        else if (this.check(TokenType.Desc)) {
-            this.advance();
-            direction = 'DESC';
+        const verify = this.expectKeywordWithSpace(TokenType.Verify);
+        const tok = this.current();
+        let target;
+        switch (tok.type) {
+            case TokenType.Capsule:
+                this.expectSecondWord(TokenType.Capsule, verify);
+                target = 'CAPSULE';
+                break;
+            case TokenType.Schema: {
+                const schema = this.expectSecondWord(TokenType.Schema, verify);
+                this.expectSecondWord(TokenType.Package, schema);
+                target = 'SCHEMA_PACKAGE';
+                break;
+            }
+            case TokenType.Receipt:
+                this.expectSecondWord(TokenType.Receipt, verify);
+                target = 'RECEIPT';
+                break;
+            case TokenType.Blob:
+                this.expectSecondWord(TokenType.Blob, verify);
+                target = 'BLOB';
+                break;
+            case TokenType.Checkpoint:
+                this.expectSecondWord(TokenType.Checkpoint, verify);
+                target = 'CHECKPOINT';
+                break;
+            default:
+                this.error(`Unknown VERIFY target '${tok.value}'`, tok);
+                throw new ParseAbort();
         }
         return {
-            kind: 'OrderByKey',
-            expression,
-            direction,
-            range: { start, end: this.currentPos() }
+            kind: 'VerifyStatement',
+            target,
+            value: this.parseScalarValue(),
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseThresholdClause() {
+    parseValidateStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        this.expectKeywordWithSpace(TokenType.Threshold);
-        const value = this.parseNumberOrParameterValue('THRESHOLD');
+        const validate = this.expectKeywordWithSpace(TokenType.Validate);
+        const tok = this.current();
+        let target;
+        switch (tok.type) {
+            case TokenType.Kql:
+                this.expectSecondWord(TokenType.Kql, validate);
+                target = 'KQL';
+                break;
+            case TokenType.Kml:
+                this.expectSecondWord(TokenType.Kml, validate);
+                target = 'KML';
+                break;
+            case TokenType.Capsule:
+                this.expectSecondWord(TokenType.Capsule, validate);
+                target = 'CAPSULE';
+                break;
+            case TokenType.Schema: {
+                const schema = this.expectSecondWord(TokenType.Schema, validate);
+                this.expectSecondWord(TokenType.Package, schema);
+                target = 'SCHEMA_PACKAGE';
+                break;
+            }
+            case TokenType.Import: {
+                const importTok = this.expectSecondWord(TokenType.Import, validate);
+                this.expectSecondWord(TokenType.Plan, importTok);
+                target = 'IMPORT_PLAN';
+                break;
+            }
+            default:
+                this.error(`Unknown VALIDATE target '${tok.value}'`, tok);
+                throw new ParseAbort();
+        }
+        const value = this.parseScalarValue();
+        const options = this.match(TokenType.With)
+            ? this.parseObjectLiteral()
+            : undefined;
         return {
-            kind: 'ThresholdClause',
+            kind: 'ValidateStatement',
+            target,
             value,
-            range: { start, end: this.currentPos() }
+            options,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseNumberOrParameterValue(context) {
-        const tok = this.current();
+    parsePreviewStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        let value;
-        if (tok.type === TokenType.Number) {
-            value = {
-                kind: 'NumberLiteral',
-                value: Number(tok.value),
-                raw: tok.value,
-                range: { start, end: start }
+        const preview = this.expectKeywordWithSpace(TokenType.Preview);
+        const tok = this.current();
+        if (tok.type === TokenType.Kml) {
+            this.expectSecondWord(TokenType.Kml, preview);
+            return {
+                kind: 'PreviewStatement',
+                target: 'KML',
+                value: this.parseScalarValue(),
+                range: { start, end: this.endPos() },
+                leadingComments: leadingComments.length ? leadingComments : undefined
             };
-            this.advance();
-            value.range.end = this.currentPos();
-            return value;
         }
-        if (tok.type === TokenType.Parameter) {
-            value = {
-                kind: 'ParameterRef',
-                name: tok.value,
-                range: { start, end: start }
+        if (tok.type === TokenType.Import) {
+            const importTok = this.expectSecondWord(TokenType.Import, preview);
+            this.expectSecondWord(TokenType.Capsule, importTok);
+            const value = this.parseScalarValue();
+            this.expect(TokenType.Into);
+            const into = this.parseScalarValue();
+            return {
+                kind: 'PreviewStatement',
+                target: 'IMPORT_CAPSULE',
+                value,
+                into,
+                range: { start, end: this.endPos() },
+                leadingComments: leadingComments.length ? leadingComments : undefined
             };
-            this.advance();
-            value.range.end = this.currentPos();
-            return value;
         }
-        this.error(`Expected number or parameter after ${context}`, tok);
-        return {
-            kind: 'NumberLiteral',
-            value: 0,
-            raw: '0',
-            range: { start, end: start }
-        };
+        this.error(`Expected KML or IMPORT CAPSULE after PREVIEW but got '${tok.value}'`, tok);
+        throw new ParseAbort();
     }
-    parseLimitClause() {
+    // ────────────────────────────────────────────────────────────────────
+    //  META — HISTORY / CHANGES / SNAPSHOT
+    // ────────────────────────────────────────────────────────────────────
+    parseHistoryStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        this.expectKeywordWithSpace(TokenType.Limit);
-        const value = this.parseNumberOrParameterValue('LIMIT');
+        const history = this.expectKeywordWithSpace(TokenType.History);
+        const tok = this.current();
+        let target;
+        let value;
+        if (tok.type === TokenType.Element) {
+            this.expectSecondWord(TokenType.Element, history);
+            target = 'ELEMENT';
+            value = this.parseScalarValue();
+        }
+        else if (tok.type === TokenType.Space) {
+            this.expectSecondWord(TokenType.Space, history);
+            target = 'SPACE';
+        }
+        else {
+            this.error(`Expected ELEMENT or SPACE after HISTORY but got '${tok.value}'`, tok);
+            throw new ParseAbort();
+        }
+        let fromSeq;
+        let toSeq;
+        if (this.check(TokenType.From)) {
+            const from = this.expect(TokenType.From);
+            this.expectSecondWord(TokenType.Seq, from);
+            fromSeq = this.parseScalarValue();
+        }
+        if (this.check(TokenType.To)) {
+            const to = this.expect(TokenType.To);
+            this.expectSecondWord(TokenType.Seq, to);
+            toSeq = this.parseScalarValue();
+        }
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
+        const cursor = this.check(TokenType.Cursor)
+            ? this.parseCursorClause()
+            : undefined;
         return {
-            kind: 'LimitClause',
+            kind: 'HistoryStatement',
+            target,
             value,
-            range: { start, end: this.currentPos() }
+            fromSeq,
+            toSeq,
+            limit,
+            cursor,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
-    parseCursorClause() {
+    parseChangesStatement() {
+        const leadingComments = this.collectLeadingComments();
         const start = this.currentPos();
-        this.expectKeywordWithSpace(TokenType.Cursor);
-        const tok = this.current();
-        let value;
-        if (tok.type === TokenType.String) {
-            value = {
-                kind: 'StringLiteral',
-                value: tok.value,
-                parsed: this.unescapeString(tok.value, tok),
-                range: { start: this.currentPos(), end: this.currentPos() }
-            };
-            this.advance();
-            value.range.end = this.currentPos();
+        const changes = this.expectKeywordWithSpace(TokenType.Changes);
+        let mode;
+        if (this.check(TokenType.Since)) {
+            this.expectSecondWord(TokenType.Since, changes);
+            mode = 'SINCE';
         }
-        else if (tok.type === TokenType.Parameter) {
-            value = {
-                kind: 'ParameterRef',
-                name: tok.value,
-                range: { start: this.currentPos(), end: this.currentPos() }
-            };
-            this.advance();
-            value.range.end = this.currentPos();
+        else if (this.check(TokenType.After)) {
+            const after = this.expectSecondWord(TokenType.After, changes);
+            this.expectSecondWord(TokenType.Seq, after);
+            mode = 'AFTER_SEQ';
         }
         else {
-            this.error(`Expected string or parameter after CURSOR`, tok);
-            value = {
-                kind: 'StringLiteral',
-                value: '""',
-                parsed: '',
-                range: { start: this.currentPos(), end: this.currentPos() }
-            };
+            this.error(`Expected SINCE or AFTER SEQ after CHANGES but got '${this.current().value}'`, this.current());
+            throw new ParseAbort();
         }
+        const value = this.parseScalarValue();
+        const limit = this.check(TokenType.Limit) ? this.parseLimitClause() : undefined;
         return {
-            kind: 'CursorClause',
+            kind: 'ChangesStatement',
+            mode,
             value,
-            range: { start, end: this.currentPos() }
+            limit,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+    }
+    parseSnapshotStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        this.expect(TokenType.Snapshot);
+        const asOf = this.check(TokenType.As) ? this.parseAsOfClause() : undefined;
+        return {
+            kind: 'SnapshotStatement',
+            asOf,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
+        };
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  META — EXPORT CAPSULE
+    // ────────────────────────────────────────────────────────────────────
+    parseExportCapsuleStatement() {
+        const leadingComments = this.collectLeadingComments();
+        const start = this.currentPos();
+        const exportTok = this.expectKeywordWithSpace(TokenType.Export);
+        this.expectSecondWord(TokenType.Capsule, exportTok);
+        const target = this.parseTargetRef();
+        this.expectKeywordWithSpace(TokenType.Where);
+        // A capsule carries records, not interpretations: BELIEF is excluded.
+        this.dialect = 'raw';
+        const where = this.parseWhereClause();
+        const options = this.match(TokenType.With)
+            ? this.parseObjectLiteral()
+            : undefined;
+        const asOf = this.check(TokenType.As) ? this.parseAsOfClause() : undefined;
+        return {
+            kind: 'ExportCapsuleStatement',
+            target,
+            where,
+            options,
+            asOf,
+            range: { start, end: this.endPos() },
+            leadingComments: leadingComments.length ? leadingComments : undefined
         };
     }
     // ────────────────────────────────────────────────────────────────────
-    //  Expressions (for FILTER and FIND projections)
+    //  Expressions
     // ────────────────────────────────────────────────────────────────────
     parseExpression() {
         return this.parseOrExpression();
@@ -1283,317 +2165,540 @@ class Parser {
                 operator: '||',
                 left,
                 right,
-                range: { start, end: right.range.end }
+                range: { start, end: this.endPos() }
             };
         }
         return left;
     }
     parseAndExpression() {
-        let left = this.parseComparisonExpression();
+        let left = this.parseEqualityExpression();
         while (this.check(TokenType.And)) {
             const start = left.range.start;
             this.advance();
-            const right = this.parseComparisonExpression();
+            const right = this.parseEqualityExpression();
             left = {
                 kind: 'BinaryExpression',
                 operator: '&&',
                 left,
                 right,
-                range: { start, end: right.range.end }
+                range: { start, end: this.endPos() }
             };
         }
         return left;
     }
-    parseComparisonExpression() {
-        let left = this.parseUnaryExpression();
-        const compOps = [
-            TokenType.Eq,
-            TokenType.NotEq,
-            TokenType.Lt,
-            TokenType.Gt,
-            TokenType.LtEq,
-            TokenType.GtEq
-        ];
-        if (compOps.includes(this.current().type)) {
+    parseEqualityExpression() {
+        let left = this.parseRelationalExpression();
+        while (this.check(TokenType.Eq) || this.check(TokenType.NotEq)) {
             const start = left.range.start;
-            const op = this.current().value;
-            this.advance();
-            const right = this.parseUnaryExpression();
+            const op = this.advance().type;
+            const right = this.parseRelationalExpression();
             left = {
                 kind: 'BinaryExpression',
-                operator: op,
+                operator: op === TokenType.Eq ? '==' : '!=',
                 left,
                 right,
-                range: { start, end: right.range.end }
+                range: { start, end: this.endPos() }
             };
         }
-        return left;
+        return left;
+    }
+    /**
+     * `relational_expression` takes at most one comparison.
+     *
+     * `a < b < c` is not chained comparison in KIP, it is a grammar error, and
+     * accepting it here would give the parser a meaning the reference grammar
+     * does not define.
+     */
+    parseRelationalExpression() {
+        const left = this.parseUnaryExpression();
+        const tok = this.current();
+        let operator;
+        switch (tok.type) {
+            case TokenType.Lt:
+                operator = '<';
+                break;
+            case TokenType.Gt:
+                operator = '>';
+                break;
+            case TokenType.LtEq:
+                operator = '<=';
+                break;
+            case TokenType.GtEq:
+                operator = '>=';
+                break;
+            default:
+                return left;
+        }
+        this.advance();
+        const right = this.parseUnaryExpression();
+        const result = {
+            kind: 'BinaryExpression',
+            operator,
+            left,
+            right,
+            range: { start: left.range.start, end: this.endPos() }
+        };
+        const next = this.current();
+        if (next.type === TokenType.Lt ||
+            next.type === TokenType.Gt ||
+            next.type === TokenType.LtEq ||
+            next.type === TokenType.GtEq) {
+            this.error(`Chained comparison '${next.value}' is not allowed; use && between comparisons`, next);
+        }
+        return result;
     }
     parseUnaryExpression() {
-        if (this.check(TokenType.Bang)) {
+        const tok = this.current();
+        if (tok.type === TokenType.Bang || tok.type === TokenType.Minus) {
             const start = this.currentPos();
             this.advance();
-            const operand = this.parseUnaryExpression();
+            const operand = this.parsePrimaryExpression();
             return {
                 kind: 'UnaryExpression',
-                operator: '!',
+                operator: tok.type === TokenType.Bang ? '!' : '-',
                 operand,
-                range: { start, end: operand.range.end }
+                range: { start, end: this.endPos() }
             };
         }
         return this.parsePrimaryExpression();
     }
     parsePrimaryExpression() {
         const tok = this.current();
-        const start = this.currentPos();
-        // Function call: NAME(...)
-        if (this.isFunctionToken(tok.type)) {
-            return this.parseFunctionCall();
+        switch (tok.type) {
+            case TokenType.Variable:
+                return this.parseFieldAccessOrVariable();
+            case TokenType.Parameter:
+                return this.parseParameterRef();
+            case TokenType.String:
+            case TokenType.Number:
+            case TokenType.Boolean:
+            case TokenType.Null:
+                return this.parseLiteral();
+            case TokenType.LBracket:
+                return this.parseArrayLiteral();
+            case TokenType.LBrace:
+                return this.parseObjectLiteral();
+            case TokenType.LParen: {
+                this.advance();
+                const inner = this.parseExpression();
+                this.expect(TokenType.RParen);
+                return inner;
+            }
+            default:
+                // `function_call` is an open `identifier "("`, and KIP 2.0 keywords
+                // are contextual, so any identifier-like token may name a function.
+                if (isIdentifierLike(tok.type) && this.peekPast(1)?.type === TokenType.LParen) {
+                    return this.parseCallExpression();
+                }
+                this.error(`Unexpected token '${tok.value}' in expression`, tok);
+                this.advance();
+                return {
+                    kind: 'NullLiteral',
+                    range: { start: this.currentPos(), end: this.endPos() }
+                };
         }
-        // Variable (may have dot access)
-        if (tok.type === TokenType.Variable) {
-            const name = tok.value;
-            this.advance();
-            let expr = {
-                kind: 'VariableRef',
-                name,
-                range: { start, end: this.currentPos() }
+    }
+    /** `COUNT(DISTINCT ?x)` where the name is an aggregate, else a plain call. */
+    parseCallExpression() {
+        const start = this.currentPos();
+        const nameTok = this.advance();
+        const name = nameTok.value;
+        this.expect(TokenType.LParen);
+        if (isAggregate(name)) {
+            const distinct = this.match(TokenType.Distinct);
+            const argument = this.parseExpression();
+            this.expect(TokenType.RParen);
+            return {
+                kind: 'AggregateExpr',
+                name: name.toUpperCase(),
+                distinct,
+                argument,
+                range: { start, end: this.endPos() }
             };
-            // Dot access chain. A dot path is written with no whitespace anywhere
-            // inside it: `?x.name` is a path, but `?x. name` is a path followed by
-            // stray input, and reading them alike would let `ORDER BY ?x.name. ASC`
-            // silently sort by a field named `ASC` with no direction.
-            let prevEnd = tok.offset + tok.value.length;
-            while (this.check(TokenType.Dot)) {
-                const dotTok = this.current();
-                if (dotTok.offset !== prevEnd) {
-                    this.error(`Unexpected whitespace before '.' in a dot path`, dotTok);
-                    break;
-                }
+        }
+        const args = [];
+        if (!this.check(TokenType.RParen)) {
+            do {
+                args.push(this.parseExpression());
+            } while (this.match(TokenType.Comma));
+        }
+        this.expect(TokenType.RParen);
+        return {
+            kind: 'FunctionCallExpr',
+            name,
+            args,
+            range: { start, end: this.endPos() }
+        };
+    }
+    /**
+     * `field_access = variable, { field_step }`.
+     *
+     * A dot path carries no whitespace: `?x . name` is three tokens to a
+     * conformant engine, not one path, so the gap is checked here.
+     */
+    parseFieldAccessOrVariable() {
+        const base = this.parseVariableRef();
+        if (!this.isTightFieldStepStart())
+            return base;
+        const steps = [];
+        while (this.isTightFieldStepStart()) {
+            const start = this.currentPos();
+            if (this.check(TokenType.Dot)) {
                 this.advance();
-                const propTok = this.current();
-                if (propTok.offset !== dotTok.offset + 1) {
-                    this.error(`Expected property name after '.'`, propTok);
-                    break;
-                }
-                if (propTok.type === TokenType.Identifier ||
-                    this.isNonAmbiguousKeyword(propTok.type)) {
-                    const prop = propTok.value;
-                    prevEnd = propTok.offset + propTok.value.length;
-                    this.advance();
-                    expr = {
-                        kind: 'DotExpression',
-                        object: expr,
-                        property: prop,
-                        range: { start, end: this.currentPos() }
-                    };
-                }
-                else {
-                    this.error(`Expected property name after '.'`, propTok);
+                const nameTok = this.current();
+                if (!isIdentifierLike(nameTok.type)) {
+                    this.error(`Expected a field name after '.' but got '${nameTok.value}'`, nameTok);
                     break;
                 }
+                this.advance();
+                steps.push({
+                    kind: 'DotStep',
+                    name: nameTok.value,
+                    range: { start, end: this.endPos() }
+                });
+            }
+            else {
+                this.advance(); // [
+                const key = this.parseStringLiteral();
+                this.expect(TokenType.RBracket);
+                steps.push({
+                    kind: 'IndexStep',
+                    key,
+                    range: { start, end: this.endPos() }
+                });
             }
-            return expr;
-        }
-        // Parameter ref
-        if (tok.type === TokenType.Parameter) {
-            this.advance();
-            return {
-                kind: 'ParameterRef',
-                name: tok.value,
-                range: { start, end: this.currentPos() }
-            };
         }
-        // String literal
-        if (tok.type === TokenType.String) {
-            this.advance();
-            return {
-                kind: 'StringLiteral',
-                value: tok.value,
-                parsed: this.unescapeString(tok.value, tok),
-                range: { start, end: this.currentPos() }
-            };
+        return {
+            kind: 'FieldAccess',
+            base,
+            steps,
+            range: { start: base.range.start, end: this.endPos() }
+        };
+    }
+    /** True when a `.`/`[` follows with no gap, i.e. continues the path. */
+    isTightFieldStepStart() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Dot && tok.type !== TokenType.LBracket) {
+            return false;
         }
-        // Number literal
-        if (tok.type === TokenType.Number) {
-            this.advance();
+        const prev = this.tokens[this.pos - 1];
+        if (!prev)
+            return false;
+        return prev.offset + prev.value.length === tok.offset;
+    }
+    // ────────────────────────────────────────────────────────────────────
+    //  Values, objects, arrays
+    // ────────────────────────────────────────────────────────────────────
+    parseVariableRef() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Variable) {
+            this.error(`Expected a variable (e.g. ?name) but got '${tok.value}'`, tok);
             return {
-                kind: 'NumberLiteral',
-                value: Number(tok.value),
-                raw: tok.value,
-                range: { start, end: this.currentPos() }
+                kind: 'VariableRef',
+                name: '?unknown',
+                range: { start: this.currentPos(), end: this.endPos() }
             };
         }
-        // Boolean
-        if (tok.type === TokenType.Boolean) {
-            this.advance();
+        const start = this.currentPos();
+        this.advance();
+        return {
+            kind: 'VariableRef',
+            name: tok.value,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseParameterRef() {
+        const tok = this.current();
+        const start = this.currentPos();
+        this.advance();
+        return {
+            kind: 'ParameterRef',
+            name: tok.value,
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseStringLiteral() {
+        const tok = this.current();
+        if (tok.type !== TokenType.String) {
+            this.error(`Expected a quoted string but got '${tok.value}'`, tok);
             return {
-                kind: 'BooleanLiteral',
-                value: tok.value === 'true',
-                range: { start, end: this.currentPos() }
+                kind: 'StringLiteral',
+                value: '""',
+                parsed: '',
+                range: { start: this.currentPos(), end: this.endPos() }
             };
         }
-        // Null
-        if (tok.type === TokenType.Null) {
-            this.advance();
-            return { kind: 'NullLiteral', range: { start, end: this.currentPos() } };
+        const start = this.currentPos();
+        this.advance();
+        return {
+            kind: 'StringLiteral',
+            value: tok.value,
+            parsed: this.unescapeString(tok.value, tok),
+            range: { start, end: this.endPos() }
+        };
+    }
+    parseLiteral() {
+        const tok = this.current();
+        const start = this.currentPos();
+        switch (tok.type) {
+            case TokenType.String:
+                return this.parseStringLiteral();
+            case TokenType.Number: {
+                this.advance();
+                const value = Number(tok.value);
+                if (!Number.isFinite(value)) {
+                    this.error(`Only finite numbers are valid KIP literals, got '${tok.value}'`, tok);
+                }
+                return {
+                    kind: 'NumberLiteral',
+                    value,
+                    raw: tok.value,
+                    range: { start, end: this.endPos() }
+                };
+            }
+            case TokenType.Boolean:
+                this.advance();
+                return {
+                    kind: 'BooleanLiteral',
+                    value: tok.value === 'true',
+                    range: { start, end: this.endPos() }
+                };
+            case TokenType.Null:
+                this.advance();
+                return { kind: 'NullLiteral', range: { start, end: this.endPos() } };
+            default:
+                this.error(`Expected a literal but got '${tok.value}'`, tok);
+                this.advance();
+                return { kind: 'NullLiteral', range: { start, end: this.endPos() } };
         }
-        // Array
-        if (tok.type === TokenType.LBracket) {
-            return this.parseArrayLiteral();
+    }
+    /** `scalar_value` / `meta_value` = `parameter | literal` */
+    parseScalarValue() {
+        const tok = this.current();
+        if (tok.type === TokenType.Parameter) {
+            return this.parseParameterRef();
         }
-        // Object
-        if (tok.type === TokenType.LBrace) {
-            return this.parseObjectLiteral();
+        if (tok.type === TokenType.String ||
+            tok.type === TokenType.Number ||
+            tok.type === TokenType.Boolean ||
+            tok.type === TokenType.Null) {
+            return this.parseLiteral();
         }
-        // Parenthesized expression
-        if (tok.type === TokenType.LParen) {
-            this.advance();
-            const expr = this.parseExpression();
-            this.expect(TokenType.RParen);
-            return expr;
+        this.error(`Expected a literal or :parameter but got '${tok.value}'`, tok);
+        this.advance();
+        return {
+            kind: 'NullLiteral',
+            range: { start: this.currentPos(), end: this.endPos() }
+        };
+    }
+    /** True when the next token could begin a `meta_value`. */
+    isMetaValueStart() {
+        const t = this.current().type;
+        return (t === TokenType.Parameter ||
+            t === TokenType.String ||
+            t === TokenType.Number ||
+            t === TokenType.Boolean ||
+            t === TokenType.Null);
+    }
+    /** `schema_symbol = string_literal | parameter` */
+    parseSchemaSymbol() {
+        const tok = this.current();
+        if (tok.type === TokenType.Parameter) {
+            return this.parseParameterRef();
         }
-        // System identifier as literal
-        if (tok.type === TokenType.SystemIdent) {
-            this.error(`Unquoted value '${tok.value}': KIP values are JSON values, so write "${tok.value}"`, tok);
-            this.advance();
-            return {
-                kind: 'StringLiteral',
-                value: `"${tok.value}"`,
-                parsed: tok.value,
-                range: { start, end: this.currentPos() }
-            };
+        if (tok.type === TokenType.String) {
+            return this.parseStringLiteral();
         }
-        // A bare word is not a KIP value — only object *keys* may go unquoted, and
-        // those never reach here. Recover as a string so the tree stays usable in
-        // an editor, and report it: `lower` sees only the tree, so it is the
-        // caller's error-diagnostic check that keeps this reading off the wire.
-        if (tok.type === TokenType.Identifier) {
-            this.error(`Unquoted value '${tok.value}': KIP values are JSON values, so write "${tok.value}"`, tok);
-            this.advance();
+        this.error(`Expected a schema symbol (quoted name or :parameter) but got '${tok.value}'`, tok);
+        this.advance();
+        return {
+            kind: 'StringLiteral',
+            value: '""',
+            parsed: '',
+            range: { start: this.currentPos(), end: this.endPos() }
+        };
+    }
+    /** `target_ref = variable | parameter | string_literal` */
+    parseTargetRef() {
+        const tok = this.current();
+        if (tok.type === TokenType.Variable)
+            return this.parseVariableRef();
+        if (tok.type === TokenType.Parameter)
+            return this.parseParameterRef();
+        if (tok.type === TokenType.String)
+            return this.parseStringLiteral();
+        this.error(`Expected a target (?variable, :parameter or quoted id) but got '${tok.value}'`, tok);
+        this.advance();
+        return {
+            kind: 'StringLiteral',
+            value: '""',
+            parsed: '',
+            range: { start: this.currentPos(), end: this.endPos() }
+        };
+    }
+    expectHandle() {
+        const tok = this.current();
+        if (tok.type !== TokenType.Variable) {
+            this.error(`Expected a local handle (e.g. ?e) but got '${tok.value}'`, tok);
             return {
-                kind: 'StringLiteral',
-                value: `"${tok.value}"`,
-                parsed: tok.value,
-                range: { start, end: this.currentPos() }
+                kind: 'VariableRef',
+                name: '?unknown',
+                range: { start: this.currentPos(), end: this.endPos() }
             };
         }
-        this.error(`Unexpected token '${tok.value}' in expression`, tok);
-        this.advance();
-        return { kind: 'NullLiteral', range: { start, end: this.currentPos() } };
+        return this.parseVariableRef();
     }
-    parseFunctionCall() {
-        const start = this.currentPos();
-        const name = this.current().value;
-        this.advance();
-        this.expect(TokenType.LParen);
-        const args = [];
-        if (!this.check(TokenType.RParen)) {
-            // Handle DISTINCT keyword inside COUNT
-            if (this.current().type === TokenType.Distinct) {
-                const dStart = this.currentPos();
+    /** `mutation_value` — everything a KML assignment may hold. */
+    parseMutationValue() {
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Variable:
+                return this.parseFieldAccessOrVariable();
+            case TokenType.Parameter:
+                return this.parseParameterRef();
+            case TokenType.LBracket:
+                return this.parseArrayLiteral();
+            case TokenType.LBrace:
+                return this.parseObjectLiteral();
+            case TokenType.String:
+            case TokenType.Number:
+            case TokenType.Boolean:
+            case TokenType.Null:
+                return this.parseLiteral();
+            default:
+                if (isIdentifierLike(tok.type) && this.peekPast(1)?.type === TokenType.LParen) {
+                    return this.parseCallExpression();
+                }
+                this.error(`Unexpected token '${tok.value}' in assignment value`, tok);
                 this.advance();
-                const innerArg = this.parseExpression();
-                args.push({
-                    kind: 'FunctionCallExpr',
-                    name: 'DISTINCT',
-                    args: [innerArg],
-                    range: { start: dStart, end: this.currentPos() }
-                });
-            }
-            else {
-                args.push(this.parseExpression());
-            }
-            while (this.match(TokenType.Comma)) {
-                args.push(this.parseExpression());
-            }
+                return {
+                    kind: 'NullLiteral',
+                    range: { start: this.currentPos(), end: this.endPos() }
+                };
         }
-        this.expect(TokenType.RParen);
+    }
+    /** `assignment_object = "{" [assignment_member {"," assignment_member}] "}"` */
+    parseAssignmentObject() {
+        const start = this.currentPos();
+        this.expect(TokenType.LBrace);
+        const seen = { trailingComma: false };
+        const entries = this.parseEntries(seen, () => this.parseMutationValue());
+        this.expect(TokenType.RBrace);
         return {
-            kind: 'FunctionCallExpr',
-            name,
-            args,
-            range: { start, end: this.currentPos() }
+            kind: 'ObjectLiteral',
+            entries,
+            trailingComma: seen.trailingComma || undefined,
+            range: { start, end: this.endPos() }
+        };
+    }
+    /** `object_pattern` — `{...}` in matching position. */
+    parseObjectPattern() {
+        const start = this.currentPos();
+        this.expect(TokenType.LBrace);
+        const seen = { trailingComma: false };
+        const members = this.parseEntries(seen, () => this.parsePatternValue());
+        this.expect(TokenType.RBrace);
+        return {
+            kind: 'ObjectPattern',
+            members,
+            trailingComma: seen.trailingComma || undefined,
+            range: { start, end: this.endPos() }
         };
     }
+    parsePatternValue() {
+        const tok = this.current();
+        switch (tok.type) {
+            case TokenType.Variable:
+                return this.parseVariableRef();
+            case TokenType.Parameter:
+                return this.parseParameterRef();
+            case TokenType.LBracket:
+                return this.parseArrayPattern();
+            case TokenType.LBrace:
+                return this.parseObjectPattern();
+            case TokenType.LParen:
+                return this.parsePropositionTuple();
+            case TokenType.String:
+            case TokenType.Number:
+            case TokenType.Boolean:
+            case TokenType.Null:
+                return this.parseLiteral();
+            default:
+                this.error(`Unexpected token '${tok.value}' in match pattern`, tok);
+                this.advance();
+                return {
+                    kind: 'NullLiteral',
+                    range: { start: this.currentPos(), end: this.endPos() }
+                };
+        }
+    }
+    parseArrayPattern() {
+        return this.parseArrayWith(() => this.parsePatternValue());
+    }
     parseArrayLiteral() {
+        return this.parseArrayWith(() => this.parseExpression());
+    }
+    parseArrayWith(parseElement) {
         const start = this.currentPos();
         this.expect(TokenType.LBracket);
         const elements = [];
         let trailingComma = false;
-        this.skipComments();
         if (!this.check(TokenType.RBracket)) {
-            elements.push(this.parseExpression());
-            while (this.match(TokenType.Comma)) {
-                this.skipComments();
+            do {
                 if (this.check(TokenType.RBracket)) {
                     trailingComma = true;
                     break;
                 }
-                elements.push(this.parseExpression());
-            }
+                elements.push(parseElement());
+            } while (this.match(TokenType.Comma));
         }
-        this.skipComments();
         this.expect(TokenType.RBracket);
         return {
             kind: 'ArrayLiteral',
             elements,
-            trailingComma,
-            range: { start, end: this.currentPos() }
+            trailingComma: trailingComma || undefined,
+            range: { start, end: this.endPos() }
         };
     }
     parseObjectLiteral() {
         const start = this.currentPos();
         this.expect(TokenType.LBrace);
         const seen = { trailingComma: false };
-        const entries = this.parseObjectEntries(seen);
+        const entries = this.parseEntries(seen, () => this.parseExpression());
         this.expect(TokenType.RBrace);
         return {
             kind: 'ObjectLiteral',
             entries,
-            trailingComma: seen.trailingComma,
-            range: { start, end: this.currentPos() }
+            trailingComma: seen.trailingComma || undefined,
+            range: { start, end: this.endPos() }
         };
     }
-    parseObjectEntries(seen) {
+    parseEntries(seen, parseValue) {
         const entries = [];
-        this.skipComments();
-        while (!this.check(TokenType.RBrace) && !this.isAtEnd()) {
-            const before = this.pos;
+        if (this.check(TokenType.RBrace))
+            return entries;
+        do {
             this.skipComments();
-            if (this.check(TokenType.RBrace))
+            if (this.check(TokenType.RBrace)) {
+                seen.trailingComma = entries.length > 0;
                 break;
-            const entryStart = this.currentPos();
+            }
+            const start = this.currentPos();
             const { key, isQuoted } = this.expectKeyWithQuoting();
             this.expectObjectColon(key);
-            const value = this.parseExpression();
+            const value = parseValue();
             entries.push({
                 kind: 'ObjectEntry',
                 key,
                 isQuoted,
                 value,
-                range: { start: entryStart, end: this.currentPos() }
+                range: { start, end: this.endPos() }
             });
-            this.skipComments();
-            if (this.check(TokenType.RBrace))
-                break;
-            if (this.match(TokenType.Comma)) {
-                this.skipComments();
-                if (seen && this.check(TokenType.RBrace))
-                    seen.trailingComma = true;
-                continue;
-            }
-            this.error(`Expected ',' or '}' after object entry`, this.current());
-            // A sub-parser that rejects its first token reports and returns
-            // without consuming it, so a loop keyed on that token would spin
-            // forever building diagnostics. Stop as soon as nothing moved.
-            if (this.pos === before)
-                break;
-        }
+        } while (this.match(TokenType.Comma));
         return entries;
     }
     // ────────────────────────────────────────────────────────────────────
-    //  Helpers
+    //  Token helpers
     // ────────────────────────────────────────────────────────────────────
     current() {
         return (this.tokens[this.pos] ?? {
@@ -1608,6 +2713,24 @@ class Parser {
         const tok = this.current();
         return { line: tok.line, column: tok.column };
     }
+    /**
+     * The end of the most recently consumed token — where a node actually ends.
+     *
+     * `currentPos()` points at the *next* token, so using it as `range.end`
+     * stretches every node to the start of whatever follows. An editor folding
+     * on that range would hide the first line of the next clause, so the end is
+     * measured from the last token the node consumed. Comments are skipped
+     * because `advance()` steps over them without them belonging to the node.
+     */
+    endPos() {
+        let i = this.pos - 1;
+        while (i >= 0 && this.tokens[i].type === TokenType.Comment)
+            i--;
+        const tok = this.tokens[i];
+        if (!tok)
+            return this.currentPos();
+        return { line: tok.line, column: tok.column + tok.value.length };
+    }
     isAtEnd() {
         return (this.pos >= this.tokens.length || this.current().type === TokenType.EOF);
     }
@@ -1628,6 +2751,10 @@ class Parser {
         this.skipComments();
         return tok;
     }
+    /** The token `i` positions ahead, skipping nothing. */
+    peekPast(i) {
+        return this.tokens[this.pos + i];
+    }
     expect(type) {
         const tok = this.current();
         if (tok.type !== type) {
@@ -1642,7 +2769,7 @@ class Parser {
      * Most KIP keywords only need a word boundary, so `WHERE{...}` is legal.
      * A handful — the statement introducers and the clause keywords whose
      * operand may itself start with a brace or a quote — require real
-     * whitespace, which is what keeps `UPSERT{` from reading as a statement.
+     * whitespace, which is what keeps `MUTATE{` from reading as a statement.
      * The distinction is per-keyword-position, not per-keyword, so it lives at
      * the call site rather than in the lexer.
      */
@@ -1658,32 +2785,22 @@ class Parser {
         }
         return this.advance();
     }
-    expectVariable() {
-        const tok = this.current();
-        if (tok.type !== TokenType.Variable) {
-            this.error(`Expected variable (e.g., ?name) but got '${tok.value}'`, tok);
-            return '?unknown';
-        }
-        this.advance();
-        return tok.value;
-    }
-    expectString() {
-        const tok = this.current();
-        if (tok.type !== TokenType.String) {
-            this.error(`Expected string literal but got '${tok.value}'`, tok);
-            return '';
-        }
-        this.advance();
-        return this.unescapeString(tok.value, tok);
-    }
-    expectStringValue() {
+    /**
+     * Consumes the second word of a multi-word keyword (`SET FIELDS`,
+     * `AS OF`, `EXPECT VERSION`, `BELIEF SLOT`, ...).
+     *
+     * The grammar joins these with whitespace only. A comment between the words
+     * is not a smaller gap, it is a different token sequence, and reading
+     * `SET//c\nFIELDS` as `SET FIELDS` would accept text the reference grammar
+     * rejects.
+     */
+    expectSecondWord(type, first) {
         const tok = this.current();
-        if (tok.type !== TokenType.String) {
-            this.error(`Expected quoted string but got '${tok.value}'`, tok);
-            return '';
+        const gap = this.source.slice(first.offset + first.value.length, tok.offset);
+        if (tok.type === type && !/^\s+$/.test(gap)) {
+            this.error(`'${first.value} ${tok.value}' must be separated by whitespace only`, tok);
         }
-        this.advance();
-        return this.unescapeString(tok.value, tok);
+        return this.expect(type);
     }
     expectKeyWithQuoting() {
         const tok = this.current();
@@ -1691,8 +2808,10 @@ class Parser {
             this.advance();
             return { key: this.unescapeString(tok.value, tok), isQuoted: true };
         }
-        if (tok.type === TokenType.Identifier ||
-            this.isNonAmbiguousKeyword(tok.type)) {
+        // `field_name = identifier | string_literal`, and KIP 2.0 keywords are
+        // contextual: the Spec's own ASSERT sugar writes `by:`, `mode:`, `at:`
+        // and `key:` as object keys.
+        if (isIdentifierLike(tok.type)) {
             this.advance();
             return { key: tok.value, isQuoted: false };
         }
@@ -1706,6 +2825,13 @@ class Parser {
             this.error(`Duplicate ${name} clause`, tok);
         }
     }
+    /** Enforces the canonical statement-level order while still recovering. */
+    checkClauseOrder(order, previous, name, tok) {
+        if (order < previous) {
+            this.error(`${name} clause is out of order`, tok);
+        }
+        return Math.max(order, previous);
+    }
     skipComments() {
         while (this.pos < this.tokens.length &&
             this.current().type === TokenType.Comment) {
@@ -1725,26 +2851,8 @@ class Parser {
     /**
      * Consume the `:` separating an object key from its value. A colon written
      * with no space before an identifier value (e.g. `status:active`) is lexed as
-     * a single parameter placeholder token (`:active`), so surface a targeted hint
-     * instead of the generic "Expected ':'" message.
-     */
-    /**
-     * Consumes the second word of a two-word keyword (`SET ATTRIBUTES`,
-     * `ORDER BY`, `EXPECT VERSION`, ...).
-     *
-     * The grammar joins these with whitespace only. A comment between the words
-     * is not a smaller gap, it is a different token sequence, and reading
-     * `SET//c\nMETADATA` as `SET METADATA` would accept text the reference
-     * grammar rejects.
+     * a single parameter placeholder token (`:active`), so split it back apart.
      */
-    expectSecondWord(type, first) {
-        const tok = this.current();
-        const gap = this.source.slice(first.offset + first.value.length, tok.offset);
-        if (tok.type === type && !/^\s+$/.test(gap)) {
-            this.error(`'${first.value} ${tok.value}' must be separated by whitespace only`, tok);
-        }
-        return this.expect(type);
-    }
     expectObjectColon(_key) {
         if (this.check(TokenType.Colon)) {
             this.advance();
@@ -1778,48 +2886,6 @@ class Parser {
         }));
         this.tokens.splice(this.pos, 1, ...retoken);
     }
-    isFunctionToken(type) {
-        return (type === TokenType.Count ||
-            type === TokenType.Sum ||
-            type === TokenType.Avg ||
-            type === TokenType.Min ||
-            type === TokenType.Max ||
-            type === TokenType.Contains ||
-            type === TokenType.StartsWith ||
-            type === TokenType.EndsWith ||
-            type === TokenType.Regex ||
-            type === TokenType.In ||
-            type === TokenType.IsNull ||
-            type === TokenType.IsNotNull ||
-            type === TokenType.Add ||
-            type === TokenType.Mul ||
-            type === TokenType.Clamp ||
-            type === TokenType.Coalesce);
-    }
-    /** Keywords that can also serve as property names in dot notation or object keys */
-    isNonAmbiguousKeyword(type) {
-        return (type === TokenType.Type ||
-            type === TokenType.Types ||
-            type === TokenType.Attributes ||
-            type === TokenType.Metadata ||
-            type === TokenType.Propositions ||
-            type === TokenType.Identifier ||
-            // Allow most keywords as property names since KIP uses snake_case for attrs
-            type === TokenType.Asc ||
-            type === TokenType.Desc ||
-            type === TokenType.Primer ||
-            type === TokenType.Domains ||
-            type === TokenType.From ||
-            type === TokenType.By ||
-            type === TokenType.Order ||
-            type === TokenType.Set ||
-            type === TokenType.With ||
-            type === TokenType.Into ||
-            type === TokenType.Expect ||
-            type === TokenType.Version ||
-            type === TokenType.Mode ||
-            type === TokenType.Threshold);
-    }
     /**
      * Reads the value of a string token.
      *
@@ -1875,21 +2941,65 @@ class Parser {
             code
         });
     }
+    static STATEMENT_STARTERS = new Set([
+        TokenType.Find,
+        TokenType.Mutate,
+        TokenType.Create,
+        TokenType.Upsert,
+        TokenType.Ensure,
+        TokenType.Assert,
+        TokenType.Update,
+        TokenType.Retract,
+        TokenType.Supersede,
+        TokenType.Correct,
+        TokenType.Transition,
+        TokenType.Set,
+        TokenType.Archive,
+        TokenType.Tombstone,
+        TokenType.Purge,
+        TokenType.Merge,
+        TokenType.Describe,
+        TokenType.List,
+        TokenType.Search,
+        TokenType.Verify,
+        TokenType.Validate,
+        TokenType.Preview,
+        TokenType.History,
+        TokenType.Changes,
+        TokenType.Snapshot,
+        TokenType.Export,
+        TokenType.EOF
+    ]);
     recoverToNextStatement() {
-        const stmtStarters = new Set([
-            TokenType.Find,
-            TokenType.Upsert,
-            TokenType.Update,
-            TokenType.Merge,
-            TokenType.Delete,
-            TokenType.Describe,
-            TokenType.Search,
-            TokenType.Export,
-            TokenType.EOF
-        ]);
-        while (!this.isAtEnd() && !stmtStarters.has(this.current().type)) {
+        while (!this.isAtEnd() &&
+            !Parser.STATEMENT_STARTERS.has(this.current().type)) {
             this.pos++;
         }
     }
+    /** Inside MUTATE, recovery stops at the next clause or the closing brace. */
+    recoverToMutationBoundary() {
+        let depth = 0;
+        while (!this.isAtEnd()) {
+            const type = this.current().type;
+            if (type === TokenType.LBrace)
+                depth++;
+            else if (type === TokenType.RBrace) {
+                if (depth === 0)
+                    return;
+                depth--;
+            }
+            else if (depth === 0 && Parser.STATEMENT_STARTERS.has(type)) {
+                return;
+            }
+            this.pos++;
+        }
+    }
+}
+/** Unwinds a sub-parser that cannot produce a node; `parse` recovers. */
+class ParseAbort extends Error {
+    constructor() {
+        super('parse aborted');
+        this.name = 'ParseAbort';
+    }
 }
 //# sourceMappingURL=parser.js.map