@dbsp/nql 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1055 @@
+import { QueryIntent, CteQueryIntent, MutationIntent, SetOperationIntent } from '@dbsp/types';
+export { DeleteIntent, ExpressionIntent, IncludeIntent, InsertIntent, MutationIntent, OrderByIntent, QueryIntent, SelectAllIntent, SelectFieldsIntent, SelectIntent, SelectWithExpressionsIntent, UpdateIntent, UpsertIntent, WhereAndIntent, WhereComparisonIntent, WhereInIntent, WhereIntent, WhereLikeIntent, WhereNotIntent, WhereNullIntent, WhereOrIntent, WhereRangeIntent } from '@dbsp/types';
+import * as chevrotain from 'chevrotain';
+import { Lexer, CstParser, CstNode, IToken } from 'chevrotain';
+
+/**
+ * NQL Abstract Syntax Tree Types
+ *
+ * These types represent the parsed structure of NQL queries,
+ * independent of the underlying database schema.
+ */
+/**
+ * A complete NQL program with let bindings and statements
+ * Supports multiple statements for mutation chaining
+ */
+interface NqlProgram {
+    type: 'program';
+    statements: NqlStatement[];
+}
+type NqlStatement = NqlQuery | NqlMutationPipeline | NqlWithQuery;
+interface NqlCteItem {
+    type: 'cteItem';
+    name: string;
+    query: NqlQuery;
+}
+interface NqlWithQuery {
+    type: 'withQuery';
+    ctes: NqlCteItem[];
+    query: NqlQuery;
+}
+interface NqlQuery {
+    type: 'query';
+    table: string;
+    clauses: NqlClause[];
+}
+interface NqlMutationPipeline {
+    type: 'mutationPipeline';
+    mutation: NqlMutation;
+    clauses: NqlMutationClause[];
+}
+type NqlMutation = NqlInsert | NqlInsertFrom | NqlUpdate | NqlDelete | NqlUpsert | NqlUpsertFrom;
+type NqlMutationClause = NqlSelectClause | NqlBindClause;
+type NqlClause = NqlWhereClause | NqlSelectClause | NqlFlatClause | NqlGroupByClause | NqlOrderByClause | NqlLimitClause | NqlOffsetClause | NqlBindClause | NqlSetClause | NqlLockClause;
+/**
+ * Where clause - position determines compilation:
+ * - Before `group by` → SQL WHERE (aggregates forbidden)
+ * - After `group by` → SQL HAVING (aggregates allowed)
+ */
+interface NqlWhereClause {
+    type: 'where';
+    condition: NqlExpression;
+}
+interface NqlSelectClause {
+    type: 'select';
+    distinct: boolean;
+    items: NqlSelectItem[];
+}
+/**
+ * NQL v2.1: Forces JOIN strategy instead of json_agg for relation includes
+ */
+interface NqlFlatClause {
+    type: 'flat';
+}
+interface NqlGroupByClause {
+    type: 'groupBy';
+    expressions: NqlExpression[];
+}
+interface NqlOrderByClause {
+    type: 'orderBy';
+    items: NqlOrderItem[];
+}
+interface NqlLimitClause {
+    type: 'limit';
+    count: number;
+    relation?: string;
+}
+interface NqlOffsetClause {
+    type: 'offset';
+    count: number;
+}
+/**
+ * Capture mutation result into a variable (for chained mutations)
+ * Used with `bind` keyword: `insert ... | bind result | ...`
+ */
+interface NqlBindClause {
+    type: 'bind';
+    name: string;
+}
+/**
+ * Set operation clause: UNION, INTERSECT, EXCEPT
+ * The right operand is either an inline query or a bound name reference.
+ */
+interface NqlSetClause {
+    type: 'setOperation';
+    op: 'union' | 'intersect' | 'except';
+    all: boolean;
+    /** Inline sub-query (parenthesized) */
+    right?: NqlQuery;
+    /** Bound name reference (via | bind) */
+    boundName?: string;
+}
+/**
+ * Lock clause (E15): FOR UPDATE | FOR SHARE | FOR NO KEY UPDATE | FOR KEY SHARE
+ * with optional wait policy: SKIP LOCKED | NOWAIT
+ */
+interface NqlLockClause {
+    type: 'lock';
+    strength: 'forUpdate' | 'forShare' | 'forNoKeyUpdate' | 'forKeyShare';
+    waitPolicy: 'block' | 'skipLocked' | 'noWait';
+}
+type NqlSelectItem = NqlSelectStar | NqlSelectRelationStar | NqlSelectExpression;
+interface NqlSelectStar {
+    type: 'star';
+}
+interface NqlSelectRelationStar {
+    type: 'relationStar';
+    relation: string[];
+}
+interface NqlSelectExpression {
+    type: 'expression';
+    expression: NqlExpression;
+    alias?: string;
+}
+interface NqlJoinSpec {
+    relation: string;
+    params?: NqlJoinParam[] | undefined;
+    via?: string | undefined;
+    condition?: NqlExpression | undefined;
+}
+interface NqlJoinParam {
+    name: string;
+    value: NqlLiteral;
+}
+interface NqlOrderItem {
+    expression: NqlExpression;
+    direction: 'asc' | 'desc';
+}
+type NqlExpression = NqlBinaryExpression | NqlUnaryExpression | NqlComparisonExpression | NqlRangeOpExpression | NqlInExpression | NqlAnyExpression | NqlBetweenExpression | NqlIsNullExpression | NqlExistsExpression | NqlRelationFilterExpression | NqlFunctionCall | NqlWindowExpression | NqlCaseExpression | NqlPathExpression | NqlJsonAccessExpression | NqlJsonComparisonExpression | NqlLiteral | NqlSubquery | NqlVariableRef;
+interface NqlBinaryExpression {
+    type: 'binary';
+    operator: 'and' | 'or' | '+' | '-' | '*' | '/' | '%';
+    left: NqlExpression;
+    right: NqlExpression;
+}
+interface NqlUnaryExpression {
+    type: 'unary';
+    operator: 'not' | '-';
+    operand: NqlExpression;
+}
+interface NqlComparisonExpression {
+    type: 'comparison';
+    operator: '=' | '!=' | '<' | '>' | '<=' | '>=' | 'like';
+    left: NqlExpression;
+    right: NqlExpression;
+}
+/**
+ * PostgreSQL range operator expression: column RANGE_OP range_literal
+ * Examples: dateRange overlaps [2024-01-01,2024-12-31)
+ */
+interface NqlRangeOpExpression {
+    type: 'rangeOp';
+    operator: 'overlaps' | 'contains' | 'containedBy';
+    left: NqlExpression;
+    range?: NqlRangeLiteral;
+    scalar?: NqlLiteral;
+}
+interface NqlInExpression {
+    type: 'in';
+    negated: boolean;
+    expression: NqlExpression;
+    values: NqlExpression[] | NqlSubquery | NqlDateRangeLiteral;
+}
+/**
+ * BATCH-001: ANY expression — col = ANY(:paramName)
+ * Compiles to WhereAnyIntent with values resolved from named parameters.
+ */
+interface NqlAnyExpression {
+    type: 'any';
+    column: NqlExpression;
+    paramName: string;
+}
+/**
+ * BETWEEN is a ternary operator: expr BETWEEN low AND high
+ */
+interface NqlBetweenExpression {
+    type: 'between';
+    expression: NqlExpression;
+    low: NqlExpression;
+    high: NqlExpression;
+}
+/**
+ * IS NULL / IS NOT NULL check
+ */
+interface NqlIsNullExpression {
+    type: 'isNull';
+    expression: NqlExpression;
+    negated: boolean;
+}
+interface NqlExistsExpression {
+    type: 'exists';
+    negated: boolean;
+    subquery: NqlSubquery;
+}
+/**
+ * SPEC-002: Relation filter expression for cross-table pseudo-columns
+ *
+ * Quantifier modes:
+ * - 'some' (default): EXISTS - at least one related record matches
+ * - 'none': NOT EXISTS - no related record matches
+ * - 'every': ALL - every related record matches (vacuous truth if empty)
+ *
+ * Syntax forms:
+ * - Implicit: `posts.featured = true` (some), `not posts.featured = true` (none), `all posts.featured = true` (every)
+ * - Explicit: `some(posts).featured = true`, `none(posts).featured = true`, `every(posts).featured = true`
+ * - With alias: `posts as p, p.featured = true and p.published = true`
+ */
+interface NqlRelationFilterExpression {
+    type: 'relationFilter';
+    /** Relation path (can be multi-hop, e.g., ['author', 'company']) */
+    relation: string[];
+    /** The filter condition applied to the relation */
+    condition: NqlExpression;
+    /** Quantifier mode */
+    mode: 'some' | 'none' | 'every';
+    /** Optional alias for the relation (for complex conditions) */
+    alias?: string;
+}
+interface NqlFunctionCall {
+    type: 'function';
+    name: string;
+    args: NqlExpression[];
+    /** Whether DISTINCT modifier was used: count(distinct col) */
+    distinct?: boolean;
+}
+/**
+ * Window expression: function OVER (PARTITION BY ... ORDER BY ...)
+ */
+interface NqlWindowExpression {
+    type: 'window';
+    function: string;
+    args: NqlExpression[];
+    partitionBy: NqlExpression[];
+    orderBy: NqlOrderItem[];
+}
+/**
+ * CASE expression: CASE WHEN cond THEN result [WHEN ...] [ELSE default] END
+ */
+interface NqlCaseExpression {
+    type: 'case';
+    /** Subject expression for simple CASE (CASE expr WHEN val ...) */
+    subject?: NqlExpression;
+    whenClauses: Array<{
+        condition: NqlExpression;
+        result: NqlExpression;
+    }>;
+    elseClause?: NqlExpression;
+}
+/**
+ * JSON access expression: col->'a'->'b'->>'c'
+ * Chained path extraction with final mode determined by last operator.
+ */
+interface NqlJsonAccessExpression {
+    type: 'jsonAccess';
+    /** Base expression (typically a path/column reference) */
+    base: NqlExpression;
+    /** Keys to extract in order */
+    path: string[];
+    /** 'json' = ->, 'text' = ->> (determined by LAST operator) */
+    mode: 'json' | 'text';
+}
+/**
+ * JSON comparison expression: col @> val, col <@ val, col ? key
+ */
+interface NqlJsonComparisonExpression {
+    type: 'jsonComparison';
+    /** Left expression (column/field) */
+    left: NqlExpression;
+    /** Operator: @> (contains), <@ (containedBy), ? (exists) */
+    operator: '@>' | '<@' | '?';
+    /** Right expression (value/key) */
+    right: NqlExpression;
+}
+interface NqlPathExpression {
+    type: 'path';
+    segments: string[];
+    /** Optional depth hint for scoped traversal: ascendant[3].column */
+    depthHint?: number;
+}
+interface NqlSubquery {
+    type: 'subquery';
+    query: NqlQuery;
+}
+/**
+ * Reference to a let-bound variable
+ */
+interface NqlVariableRef {
+    type: 'variable';
+    name: string;
+}
+type NqlLiteral = NqlStringLiteral | NqlNumberLiteral | NqlBooleanLiteral | NqlNullLiteral | NqlDateRangeLiteral | NqlRangeLiteral;
+interface NqlStringLiteral {
+    type: 'string';
+    value: string;
+}
+interface NqlNumberLiteral {
+    type: 'number';
+    value: number;
+}
+interface NqlBooleanLiteral {
+    type: 'boolean';
+    value: boolean;
+}
+interface NqlNullLiteral {
+    type: 'null';
+}
+/**
+ * Natural language date range (e.g., 'last 7 days', 'this month')
+ * Semantic layer validates and converts to actual dates
+ */
+interface NqlDateRangeLiteral {
+    type: 'dateRange';
+    value: string;
+}
+/**
+ * PostgreSQL range literal (e.g., '[2024-01-01,2024-12-31)')
+ * Used with range operators: overlaps, contains, containedBy
+ */
+interface NqlRangeLiteral {
+    type: 'rangeLiteral';
+    value: string;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+    lower: string;
+    upper: string;
+}
+interface NqlInsert {
+    type: 'insert';
+    table: string;
+    /** Multi-row support: each element is a row's assignments */
+    rows: NqlAssignment[][];
+}
+/**
+ * INSERT INTO target FROM source query.
+ * @example `insert into archived_users from users | where active = false`
+ */
+interface NqlInsertFrom {
+    type: 'insert_from';
+    /** Target table to insert into */
+    table: string;
+    /** Source table to select from */
+    source: string;
+    /** Optional column mapping (default: same columns) */
+    columns?: string[] | undefined;
+    /** WHERE clause to filter source rows */
+    where?: NqlExpression | undefined;
+    /** LIMIT clause to restrict rows */
+    limit?: number | undefined;
+}
+interface NqlUpdate {
+    type: 'update';
+    table: string;
+    assignments: NqlAssignment[];
+    where?: NqlExpression;
+}
+interface NqlDelete {
+    type: 'delete';
+    table: string;
+    where?: NqlExpression;
+}
+interface NqlUpsert {
+    type: 'upsert';
+    table: string;
+    conflictColumns: string[];
+    assignments: NqlAssignment[];
+    where?: NqlExpression;
+}
+/**
+ * UPSERT INTO target ON conflictColumns FROM source [WHERE ...] [LIMIT ...]
+ * Bulk upsert by selecting from another table or bound CTE
+ */
+interface NqlUpsertFrom {
+    type: 'upsert_from';
+    table: string;
+    conflictColumns: string[];
+    source: string;
+    columns?: string[] | undefined;
+    where?: NqlExpression | undefined;
+    limit?: number | undefined;
+}
+interface NqlAssignment {
+    column: string;
+    value: NqlExpression;
+}
+
+interface CompileResult {
+    readonly query?: QueryIntent;
+    /** CTE query (WITH clause): wraps outer QueryIntent in CteQueryIntent */
+    readonly cteQuery?: CteQueryIntent;
+    readonly mutation?: MutationIntent;
+    readonly returning?: readonly string[];
+    /** Named bindings from `| bind X` clauses (CTE source queries) */
+    readonly bindings?: ReadonlyMap<string, QueryIntent>;
+    /**
+     * Named mutation bindings from `mutation | select cols | bind X` clauses.
+     * When a mutation has RETURNING and is bound, the original MutationIntent is stored here
+     * so the adapter can compile it as a CTE: `WITH X AS (INSERT ... RETURNING cols) ...`
+     * The corresponding synthetic QueryIntent is also stored in `bindings` for reference resolution.
+     */
+    readonly mutationBindings?: ReadonlyMap<string, MutationIntent>;
+    /** Set operation (UNION/INTERSECT/EXCEPT) wrapping two queries */
+    readonly setOperation?: SetOperationIntent;
+}
+/**
+ * Duck-type interface for schema-based column validation.
+ * Loose coupling: ModelIR from @dbsp/core satisfies this shape without direct import.
+ */
+interface ColumnValidatorSchema {
+    getTable(name: string): {
+        readonly columns: readonly {
+            readonly name: string;
+        }[];
+        readonly pseudoColumns?: readonly {
+            readonly parentRole: string;
+            readonly childRole: string;
+        }[];
+    } | undefined;
+    getRelationsFrom(sourceTable: string): readonly {
+        readonly name: string;
+        readonly target: string;
+    }[];
+}
+/**
+ * Options for the NQL compiler.
+ * Allows dynamic pseudo-column keywords from schema configuration.
+ */
+interface NqlCompilerOptions {
+    readonly pseudoColumnKeywords?: readonly string[];
+    readonly recursiveKeywords?: readonly string[];
+    /** BATCH-001: Named parameters for ANY(:param) expressions */
+    readonly params?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * NQL Compiler
+ *
+ * Transforms NQL AST to IntentAST.
+ * Thin coordinator: delegates to domain modules for actual compilation.
+ *
+ * @since ARCH-007: IntentAST types centralized in @dbsp/types to avoid circular dependencies.
+ */
+
+/**
+ * Compiler that transforms NQL AST to IntentAST.
+ * Thin coordinator: holds context, wires domain modules via CompilerFns.
+ */
+declare class NqlCompiler {
+    private readonly ctx;
+    private readonly fns;
+    constructor(options?: NqlCompilerOptions, schema?: ColumnValidatorSchema);
+    /**
+     * Compile an NQL program to IntentAST.
+     */
+    compile(program: NqlProgram): CompileResult;
+    private compileSingleStatement;
+}
+/**
+ * Create a compiler instance.
+ */
+declare function createCompiler(options?: NqlCompilerOptions, schema?: ColumnValidatorSchema): NqlCompiler;
+
+/**
+ * NQL Error Types
+ *
+ * Structured error types for lexer, parser, and semantic errors.
+ */
+/** Source location for error reporting */
+interface SourceLocation {
+    line: number;
+    column: number;
+    offset: number;
+}
+/** Base error interface for all NQL errors */
+interface NqlError {
+    code: string;
+    message: string;
+    location?: SourceLocation | undefined;
+    suggestion?: string | undefined;
+}
+/** Parser errors (syntax errors) */
+interface NqlParseError extends NqlError {
+    code: `ERR-PARSE-${string}`;
+    expected?: string[] | undefined;
+    found?: string | undefined;
+}
+/** Semantic errors (validation failures) */
+interface NqlSemanticError extends NqlError {
+    code: `ERR-SEM-${string}`;
+    relatedSymbol?: string | undefined;
+}
+/** Warning (non-fatal issues) */
+interface NqlWarning {
+    code: string;
+    message: string;
+    location?: SourceLocation | undefined;
+    suggestion?: string | undefined;
+}
+
+declare const allTokens: chevrotain.TokenType[];
+declare const NqlLexer: Lexer;
+
+/**
+ * NQL Parser using Chevrotain CstParser
+ */
+declare class NqlParser extends CstParser {
+    constructor();
+    /**
+     * Check if a token type can appear as an identifier segment.
+     * This includes regular identifiers, quoted identifiers, and pseudo-column keywords
+     * (parent, child, ascendant, descendant) which can be used in paths.
+     */
+    private isIdentifierLike;
+    /**
+     * program = { statement } ;
+     * Supports multiple statements (queries or mutations)
+     */
+    program: chevrotain.ParserMethod<[], CstNode>;
+    /**
+     * statement = withQuery | query | mutation_pipeline ;
+     * withQuery is tried first via GATE to avoid ambiguity with 'with' as identifier.
+     */
+    private statement;
+    /**
+     * withQuery = "with" cteList query ;
+     */
+    withQuery: chevrotain.ParserMethod<[], CstNode>;
+    /**
+     * cteList = cteItem { "," cteItem } ;
+     */
+    private cteList;
+    /**
+     * cteItem = identSegment "as" "(" query ")" ;
+     */
+    private cteItem;
+    /**
+     * query = table_ref { "|" query_clause } ;
+     */
+    query: chevrotain.ParserMethod<[], CstNode>;
+    /**
+     * table_ref = ident_segment ;
+     */
+    private tableRef;
+    /**
+     * query_clause = where_clause | select_clause | flat_clause
+     *              | group_clause | order_clause | limit_clause | offset_clause | bind_clause ;
+     */
+    private queryClause;
+    /**
+     * where_clause = "where" boolean_expr ;
+     */
+    private whereClause;
+    /**
+     * select_clause = "select" [ "distinct" ] select_list ;
+     */
+    private selectClause;
+    /**
+     * flat_clause = "flat" ;
+     * NQL v2.1: Forces JOIN strategy instead of json_agg for relation includes
+     */
+    private flatClause;
+    /**
+     * group_clause = "group" "by" expr_list ;
+     */
+    private groupClause;
+    /**
+     * order_clause = "order" "by" order_list ;
+     */
+    private orderClause;
+    /**
+     * limit_clause = "limit" [ident_segment ("." ident_segment)*] NUMBER ;
+     */
+    private limitClause;
+    /**
+     * offset_clause = "offset" NUMBER ;
+     */
+    private offsetClause;
+    /**
+     * lock_clause = lock_strength [ lock_wait_policy ] ;
+     * lock_strength = "for update" | "for share" | "for no key update" | "for key share" ;
+     * lock_wait_policy = "skip locked" | "nowait" ;
+     */
+    private lockClause;
+    /**
+     * select_list = select_item { "," select_item } ;
+     */
+    private selectList;
+    /**
+     * select_item = "*" | path_star | expr [ "as" ident_segment ] ;
+     * where path_star = ident { "." ident } "." "*"
+     */
+    private selectItem;
+    /**
+     * relation_star_expr = ident { "." ident } "." "*"
+     * Parses `relation.*` or `a.b.c.*` patterns
+     */
+    private relationStarExpr;
+    /**
+     * Check if current position looks like `path.*`
+     */
+    private isRelationStar;
+    /**
+     * order_list = order_item { "," order_item } ;
+     */
+    private orderList;
+    /**
+     * order_item = expr [ "asc" | "desc" ] ;
+     */
+    private orderItem;
+    /**
+     * boolean_expr = or_expr ;
+     */
+    private booleanExpr;
+    /**
+     * or_expr = and_expr { "or" and_expr } ;
+     */
+    private orExpr;
+    /**
+     * and_expr = not_expr { "and" not_expr } ;
+     */
+    private andExpr;
+    /**
+     * not_expr = [ "not" ] primary_cond ;
+     */
+    private notExpr;
+    /**
+     * primary_cond = "(" boolean_expr ")"
+     *              | quantified_relation_filter   -- SPEC-002: some()/none()/every()
+     *              | all_relation_filter          -- SPEC-002: all relation.col = val
+     *              | exists_check
+     *              | comparison / between / in / is_null ;
+     */
+    private primaryCond;
+    /**
+     * comparison_suffix = comp_op expr ;
+     */
+    private comparisonSuffix;
+    /**
+     * json_comparison_suffix = ("@>" | "<@" | "?") expression ;
+     * JSONB containment and key-existence operators.
+     */
+    private jsonComparisonSuffix;
+    /**
+     * comp_op = "=" | "!=" | "<" | ">" | "<=" | ">=" | "like" ;
+     * Note: Range operators (overlaps, contains, containedBy) are handled
+     * separately in rangeOpSuffix to allow (value,value) range syntax.
+     */
+    private compOp;
+    /**
+     * range_op = "overlaps" | "contains" | "containedBy" ;
+     * PostgreSQL range operators - handled separately to support (value,value) syntax.
+     */
+    private rangeOp;
+    /**
+     * range_op_suffix = range_op (range_literal | literal) ;
+     * Example: overlaps [1,10) or contains (0,100) or contains 25
+     * Note: contains can take a scalar value (e.g., contains 25 checks if range contains the value)
+     */
+    private rangeOpSuffix;
+    /**
+     * between_suffix = "between" expr "and" expr ;
+     */
+    private betweenSuffix;
+    /**
+     * exists_check = [ "not" ] "exists" "(" scalar_subquery ")" ;
+     */
+    private existsCheck;
+    /**
+     * SPEC-002: Explicit quantifier function
+     * quantified_relation_filter = quantifier "(" path_expr ")" "." ident_segment comp_op expr
+     *                            | quantifier "(" path_expr [ "as" IDENT ] "," boolean_expr ")" ;
+     * quantifier = "some" | "none" | "every" ;
+     *
+     * Examples:
+     *   some(posts).featured = true
+     *   none(posts).published = true
+     *   every(posts).status = 'approved'
+     *   some(posts as p, p.featured = true and p.published = true)
+     */
+    private quantifiedRelationFilter;
+    /**
+     * SPEC-002: ALL quantifier prefix for implicit relation filter
+     * all_relation_filter = "all" path_expr comp_op expr ;
+     *
+     * The path_expr contains both the relation and column, e.g., posts.featured
+     * The visitor will split it: relation = all but last segment, column = last segment
+     *
+     * Examples:
+     *   all posts.featured = true   (relation: posts, column: featured)
+     *   all author.posts.published = true  (relation: author.posts, column: published)
+     */
+    private allRelationFilter;
+    /**
+     * in_suffix = [ "not" ] "in" ( "(" value_list ")" | "(" scalar_subquery ")" | date_range_literal ) ;
+     */
+    /**
+     * any_suffix = '=' 'ANY' '(' ':' identifier ')' ;
+     * BATCH-001: Parses the ANY(:paramName) suffix after a column expression.
+     * Example: id = ANY(:ids)
+     */
+    private anySuffix;
+    private inSuffix;
+    /**
+     * is_null_suffix = "is" [ "not" ] "null" ;
+     */
+    private isNullSuffix;
+    /**
+     * Check if inside parentheses we have a scalar subquery
+     * A scalar subquery MUST have at least one pipe
+     */
+    private isScalarSubqueryInParen;
+    /**
+     * Check if we're looking at a scalar subquery (for expression context)
+     */
+    private isScalarSubquery;
+    /**
+     * expr = add_expr ;
+     */
+    private expression;
+    /**
+     * add_expr = mul_expr { ("+" | "-") mul_expr } ;
+     */
+    private addExpr;
+    /**
+     * mul_expr = unary_expr { ("*" | "/" | "%") unary_expr } ;
+     */
+    private mulExpr;
+    /**
+     * unary_expr = [ "-" ] json_access_expr ;
+     */
+    private unaryExpr;
+    /**
+     * json_access_expr = primary_expr { ("->" | "->>") string_literal } ;
+     * Chained JSON path access: col->'a'->'b'->>'c'
+     */
+    private jsonAccessExpr;
+    /**
+     * primary_expr = literal | case_expr | path_expr | func_call | "(" expr ")" | "(" scalar_subquery ")" ;
+     */
+    private primaryExpr;
+    /**
+     * Check if at start of scalar subquery (ident | ...)
+     */
+    private isScalarSubqueryStart;
+    /**
+     * scalar_subquery = query ;
+     * Delegates to the `query` rule (gate already ensures at least one pipe).
+     */
+    private scalarSubquery;
+    /**
+     * path_expr = ident_segment { "." ident_segment } ;
+     */
+    private pathExpr;
+    /**
+     * case_expr = "CASE" ( searched_case_body | simple_case_body ) [ else_clause ] "END" ;
+     * searched_case_body = "WHEN" boolean_expr "THEN" expression { "WHEN" boolean_expr "THEN" expression } ;
+     * simple_case_body = expression "WHEN" expression "THEN" expression { "WHEN" expression "THEN" expression } ;
+     * else_clause = "ELSE" expression ;
+     */
+    private caseExpr;
+    /**
+     * searched_case_body = "WHEN" boolean_expr "THEN" expression { ... } ;
+     */
+    private searchedCaseBody;
+    /**
+     * simple_case_body = expression "WHEN" expression "THEN" expression { ... } ;
+     */
+    private simpleCaseBody;
+    /**
+     * func_call = ( window_func | IDENT ) "(" [ func_arg_list ] ")" [ window_clause ] ;
+     * window_func = "row_number" | "rank" | "dense_rank" | "lag" | "lead" ;
+     * Regular functions can also have OVER (e.g., sum(x) OVER (...))
+     */
+    private funcCall;
+    /**
+     * window_clause = "over" "(" [ partition_clause ] [ order_clause_in_window ] ")" ;
+     */
+    private windowClause;
+    /**
+     * partition_clause = "partition" "by" expr_list ;
+     */
+    private partitionClause;
+    /**
+     * order_clause_in_window = "order" "by" order_list ;
+     * Same as orderClause but separate rule for clarity
+     */
+    private orderClauseInWindow;
+    /**
+     * Function argument list - handles count(*) and DISTINCT specially
+     * func_arg_list = "*" | [ "distinct" ] expr_list ;
+     */
+    private funcArgList;
+    /**
+     * expr_list = expr { "," expr } ;
+     */
+    private exprList;
+    /**
+     * value_list = expr { "," expr } ;
+     */
+    private valueList;
+    /**
+     * literal = STRING | NUMBER | "true" | "false" | "null" ;
+     */
+    private literal;
+    /**
+     * range_literal = ( "[" | "(" ) range_value "," range_value ( "]" | ")" ) ;
+     * range_value = RANGE_VALUE | NUMBER | "-" NUMBER ;
+     *
+     * PostgreSQL-style range bounds (full support):
+     * - Opening: [ (inclusive) or ( (exclusive)
+     * - Closing: ] (inclusive) or ) (exclusive)
+     * Examples: [1,10], (0,100), [1,10), (0,10]
+     *
+     * Note: This is only called from rangeOpSuffix (after overlaps/contains/containedBy),
+     * so there's no ambiguity with grouped expressions like (a + b).
+     */
+    private rangeLiteral;
+    /**
+     * range_value = RANGE_VALUE | NUMBER | "-" NUMBER ;
+     * RANGE_VALUE matches date/time patterns (2024-01-01, 08:00)
+     * NUMBER matches plain integers
+     */
+    private rangeValue;
+    /**
+     * ident_segment = IDENT | QUOTED_IDENT ;
+     */
+    private identSegment;
+    /**
+     * mutation_pipeline = mutation { "|" mutation_clause } ;
+     */
+    private mutationPipeline;
+    /**
+     * mutation_clause = select_clause | bind_clause ;
+     */
+    private mutationClause;
+    /**
+     * bind_clause = "bind" IDENT ;
+     */
+    private bindClause;
+    /**
+     * set_clause = set_op [ "all" ] set_operand ;
+     * set_op     = "union" | "intersect" | "except" ;
+     * set_operand = "(" query ")" | ident_segment ;
+     */
+    private setClause;
+    /**
+     * mutation = insert_from_stmt | insert_stmt | update_stmt | delete_stmt | upsert_stmt ;
+     * Note: insert_from_stmt must come before insert_stmt because both start with "insert into".
+     * We use BACKTRACK to resolve the ambiguity.
+     */
+    private mutation;
+    /**
+     * insert_stmt = "insert" "into" ident_segment "set" assignment_list ;
+     */
+    private insertStmt;
+    /**
+     * insert_from_stmt = "insert" "into" ident_segment "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+     * @example insert into archived_users from users where active = false limit 100
+     */
+    private insertFromStmt;
+    /**
+     * update_stmt = "update" ident_segment "set" assignment_list [ "where" boolean_expr ] ;
+     */
+    private updateStmt;
+    /**
+     * delete_stmt = "delete" "from" ident_segment [ "where" boolean_expr ] ;
+     * Note: WHERE is checked at semantic layer (to allow proper error messages)
+     */
+    private deleteStmt;
+    /**
+     * upsert_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "set" assignment_list [ "where" boolean_expr ] ;
+     * Allows both `on (id1, id2)` and `on id` syntax
+     */
+    private upsertStmt;
+    /**
+     * upsert_from_stmt = "upsert" "into" ident_segment "on" ( "(" ident_list ")" | ident_segment ) "from" ident_segment [ "where" boolean_expr ] [ "limit" number ] ;
+     * @example upsert into authors on id from counts
+     * @example upsert into authors on (id, email) from counts where active = true
+     */
+    private upsertFromStmt;
+    /**
+     * assignment_list = assignment { "," assignment } ;
+     */
+    private assignmentList;
+    /**
+     * SQL-style values tuple: (col1=val1, col2=val2)
+     */
+    private valuesTuple;
+    /**
+     * assignment = ident_segment "=" expr ;
+     */
+    private assignment;
+    /**
+     * ident_list = ident_segment { "," ident_segment } ;
+     */
+    private identList;
+}
+/**
+ * Parse NQL input and return CST
+ */
+declare function parseCst(input: string): {
+    cst: CstNode | undefined;
+    errors: Array<{
+        message: string;
+        token?: IToken;
+    }>;
+};
+
+/**
+ * @module semantic/helpers
+ * Shared types and utility functions for NQL CST-to-AST visitor.
+ */
+
+/** CST context type — values are arrays of CstNode or IToken */
+type CstContext = Record<string, (CstNode | IToken)[] | undefined>;
+/**
+ * Window specification returned by windowClause visitor
+ */
+interface WindowSpec {
+    partitionBy: NqlExpression[];
+    orderBy: NqlOrderItem[];
+}
+
+declare const BaseCstVisitor: new (...args: any[]) => chevrotain.ICstVisitor<any, any>;
+/**
+ * CST Visitor that transforms Chevrotain CST to NQL AST.
+ * All logic lives in domain modules; this class is a thin dispatcher.
+ */
+declare class NqlCstVisitor extends BaseCstVisitor {
+    private readonly v;
+    readonly warnings: NqlWarning[];
+    constructor();
+    /** Clear warnings before each parse run (singleton reuse). */
+    resetWarnings(): void;
+    program(ctx: CstContext): NqlProgram;
+    statement(ctx: CstContext): NqlStatement;
+    query(ctx: CstContext): NqlQuery;
+    tableRef(ctx: CstContext): string;
+    queryClause(ctx: CstContext): NqlClause;
+    whereClause(ctx: CstContext): NqlClause;
+    selectClause(ctx: CstContext): NqlClause;
+    flatClause(_ctx: CstContext): NqlClause;
+    groupClause(ctx: CstContext): NqlClause;
+    orderClause(ctx: CstContext): NqlClause;
+    limitClause(ctx: CstContext): NqlClause;
+    offsetClause(ctx: CstContext): NqlClause;
+    selectList(ctx: CstContext): NqlSelectItem[];
+    selectItem(ctx: CstContext): NqlSelectItem;
+    relationStarExpr(ctx: CstContext): NqlSelectItem;
+    orderList(ctx: CstContext): NqlOrderItem[];
+    orderItem(ctx: CstContext): NqlOrderItem;
+    lockClause(ctx: CstContext): NqlLockClause;
+    booleanExpr(ctx: CstContext): NqlExpression;
+    orExpr(ctx: CstContext): NqlExpression;
+    andExpr(ctx: CstContext): NqlExpression;
+    notExpr(ctx: CstContext): NqlExpression;
+    primaryCond(ctx: CstContext): NqlExpression;
+    comparisonSuffix(_ctx: CstContext): NqlExpression;
+    betweenSuffix(_ctx: CstContext): NqlExpression;
+    rangeOpSuffix(_ctx: CstContext): NqlExpression;
+    jsonComparisonSuffix(_ctx: CstContext): NqlExpression;
+    inSuffix(_ctx: CstContext): NqlExpression;
+    anySuffix(_ctx: CstContext): undefined;
+    isNullSuffix(_ctx: CstContext): NqlExpression;
+    compOp(ctx: CstContext): string;
+    rangeOp(ctx: CstContext): "overlaps" | "contains" | "containedBy";
+    expression(ctx: CstContext): NqlExpression;
+    addExpr(ctx: CstContext): NqlExpression;
+    mulExpr(ctx: CstContext): NqlExpression;
+    unaryExpr(ctx: CstContext): NqlExpression;
+    jsonAccessExpr(ctx: CstContext): NqlExpression;
+    primaryExpr(ctx: CstContext): NqlExpression;
+    caseExpr(ctx: CstContext): NqlCaseExpression;
+    searchedCaseBody(_ctx: CstContext): void;
+    simpleCaseBody(_ctx: CstContext): void;
+    scalarSubquery(ctx: CstContext): NqlSubquery;
+    pathExpr(ctx: CstContext): NqlExpression;
+    exprList(ctx: CstContext): NqlExpression[];
+    existsCheck(ctx: CstContext): NqlExistsExpression;
+    quantifiedRelationFilter(ctx: CstContext): NqlRelationFilterExpression;
+    allRelationFilter(ctx: CstContext): NqlRelationFilterExpression;
+    funcCall(ctx: CstContext): NqlFunctionCall | NqlWindowExpression;
+    windowClause(ctx: CstContext): WindowSpec;
+    partitionClause(ctx: CstContext): NqlExpression[];
+    orderClauseInWindow(ctx: CstContext): NqlOrderItem[];
+    funcArgList(ctx: CstContext): NqlExpression[];
+    literal(ctx: CstContext): NqlLiteral;
+    rangeLiteral(ctx: CstContext): NqlRangeLiteral;
+    rangeValue(ctx: CstContext): string;
+    identSegment(ctx: CstContext): string;
+    identList(ctx: CstContext): string[];
+    valueList(ctx: CstContext): NqlExpression[];
+    mutationPipeline(ctx: CstContext): NqlMutationPipeline;
+    mutationClause(ctx: CstContext): NqlMutationClause;
+    bindClause(ctx: CstContext): NqlMutationClause;
+    setClause(ctx: CstContext): NqlSetClause;
+    mutation(ctx: CstContext): NqlMutation;
+    insertStmt(ctx: CstContext): NqlMutation;
+    insertFromStmt(ctx: CstContext): NqlMutation;
+    updateStmt(ctx: CstContext): NqlMutation;
+    deleteStmt(ctx: CstContext): NqlMutation;
+    upsertStmt(ctx: CstContext): NqlMutation;
+    upsertFromStmt(ctx: CstContext): NqlMutation;
+    assignmentList(ctx: CstContext): NqlAssignment[];
+    valuesTuple(ctx: CstContext): NqlAssignment[];
+    assignment(ctx: CstContext): NqlAssignment;
+    withQuery(ctx: CstContext): NqlWithQuery;
+    cteList(ctx: CstContext): NqlCteItem[];
+    cteItem(ctx: CstContext): NqlCteItem;
+}
+declare const nqlVisitor: NqlCstVisitor;
+/**
+ * Transform CST to AST, collecting any warnings emitted during traversal.
+ */
+declare function cstToAst(cst: CstNode): {
+    ast: NqlProgram;
+    warnings: NqlWarning[];
+};
+
+interface ParseOptions {
+    /** Reject keyword aliases (default: true) */
+    strictMode?: boolean;
+    /** Maximum subquery nesting depth (default: 10) */
+    maxSubqueryDepth?: number;
+    /** Maximum clauses per query (default: 20) */
+    maxClauses?: number;
+    /** Maximum joins per query (default: 10) */
+    maxJoins?: number;
+}
+interface ParseResult<T> {
+    success: boolean;
+    ast?: T;
+    errors: NqlError[];
+    warnings: NqlWarning[];
+}
+
+/**
+ * Parse NQL input without schema validation
+ */
+declare function parse(input: string, _options?: ParseOptions): ParseResult<NqlProgram>;
+/**
+ * Parse, validate, and compile NQL to IntentAST
+ */
+declare function compile(input: string, schema: unknown, // ModelIR from @dbsp/core — satisfies ColumnValidatorSchema
+options?: ParseOptions, compilerOptions?: NqlCompilerOptions): ParseResult<CompileResult>;
+
+export { type ColumnValidatorSchema, type CompileResult, type NqlAnyExpression, type NqlAssignment, type NqlBetweenExpression, type NqlBinaryExpression, type NqlBindClause, type NqlBooleanLiteral, type NqlCaseExpression, type NqlClause, type NqlComparisonExpression, NqlCompiler, type NqlCompilerOptions, NqlCstVisitor, type NqlCteItem, type NqlDateRangeLiteral, type NqlDelete, type NqlError, type NqlExistsExpression, type NqlExpression, type NqlFlatClause, type NqlFunctionCall, type NqlGroupByClause, type NqlInExpression, type NqlInsert, type NqlInsertFrom, type NqlIsNullExpression, type NqlJoinParam, type NqlJoinSpec, type NqlJsonAccessExpression, type NqlJsonComparisonExpression, NqlLexer, type NqlLimitClause, type NqlLiteral, type NqlLockClause, type NqlMutation, type NqlMutationClause, type NqlMutationPipeline, type NqlNullLiteral, type NqlNumberLiteral, type NqlOffsetClause, type NqlOrderByClause, type NqlOrderItem, type NqlParseError, NqlParser, type NqlPathExpression, type NqlProgram, type NqlQuery, type NqlRangeLiteral, type NqlRangeOpExpression, type NqlRelationFilterExpression, type NqlSelectClause, type NqlSelectExpression, type NqlSelectItem, type NqlSelectRelationStar, type NqlSelectStar, type NqlSemanticError, type NqlSetClause, type NqlStatement, type NqlStringLiteral, type NqlSubquery, type NqlUnaryExpression, type NqlUpdate, type NqlUpsert, type NqlUpsertFrom, type NqlVariableRef, type NqlWarning, type NqlWhereClause, type NqlWindowExpression, type NqlWithQuery, type ParseOptions, type ParseResult, allTokens, compile, createCompiler, cstToAst, nqlVisitor, parse, parseCst };