@adaptabletools/adaptable 23.1.0 → 24.0.0-canary.0

package/vendor/aql/validation/validateAqlExpression.js

@@ -0,0 +1,746 @@
+import { isAST_Function } from '../types.js';
+import { migrateExpressionNode, normalizeAst, } from '../normalize/normalizeAst.js';
+import { printExpression } from '../normalize/print.js';
+import { AGGREGATION_ONLY_NAMES, DUAL_AGGREGATION_NAMES, LEGACY_OBSERVABLE_MARKER_NAMES, LEGACY_OBSERVABLE_SOURCE_NAMES, OPERAND_CLAUSE_NAMES, OBSERVABLE_SOURCE_NAMES, RETIRED_CLAUSE_RENAMES, } from '../normalize/names.js';
+import { classifyExpression, getRootExpression, } from './classifyExpression.js';
+import { ANY_COL_SOURCE_NAMES, BASELINE_CUSTOM_AGGREGATION_SPEC, CLAUSE_OPERAND_KINDS, CUSTOM_OBSERVABLE_FALLBACK_SPEC, SORT_DIRECTION_LITERALS, TRIGGER_LITERALS, getObservableCallSpec, toSortDirection, } from './functionMetadata.js';
+import { SYSTEM_AGGREGATION_CATALOGUE } from '../plan/catalogue.js';
+import { KEYWORD_OPERATORS } from '../functions/operatorFunctions.js';
+import { inferStaticExpressionType, validateExpressionTypes, } from './validateExpressionTypes.js';
+const DEFAULT_MAX_WITHIN_MS = 24 * 3600 * 1000;
+const DEFAULT_MAX_HISTORY_PER_CELL = 1000;
+/** Names that are never scalar-pool lookups (refs, literals, internals). */
+const NON_POOL_FUNCTION_NAMES = new Set([
+    'COL',
+    'FIELD',
+    'VAR',
+    'QUERY',
+    '$SCOPE',
+    'SCOPE',
+    'TO_ARRAY',
+    'DURATION',
+    'CASE',
+    'NULL',
+]);
+/**
+ * Paren-callable names that runtime normalize does not rewrite (sugar
+ * wrappers and operand/marker tags). Never "unknown functions".
+ */
+const EVALUATION_SUGAR_AND_OPERAND_NAMES = new Set([
+    'CUMUL',
+    'PERCENTAGE',
+    'ABSOLUTE_DIFF',
+    'PERCENT_DIFF',
+    'TIMEFRAME',
+    'WHERE',
+    'GROUP_BY',
+    'OVER',
+    'WEIGHT',
+]);
+const kindOf = (fn) => fn.kind ?? fn.metaInfo;
+const isClauseNode = (value) => isAST_Function(value) && kindOf(value) === 'CLAUSE';
+const isRefNode = (value) => isAST_Function(value) && (value.type === 'COL' || value.type === 'FIELD');
+const formatDurationMs = (ms) => {
+    const units = [
+        [86400000, 'd'],
+        [3600000, 'h'],
+        [60000, 'm'],
+        [1000, 's'],
+    ];
+    for (const [factor, unit] of units) {
+        if (ms >= factor && ms % factor === 0) {
+            return `${ms / factor}${unit}`;
+        }
+    }
+    return `${ms}ms`;
+};
+const pushIssue = (state, code, message, node, extras) => {
+    state.issues.push({
+        code,
+        message,
+        severity: 'error',
+        range: node?.range,
+        functionName: node?.type,
+        ...extras,
+    });
+};
+// ---------------------------------------------------------------------------
+// Raw-surface rails (run on the authored AST, before normalization)
+// ---------------------------------------------------------------------------
+const braceQuickFix = (state, call) => {
+    const normalized = migrateExpressionNode(call, {
+        ...state.normalizeOptions,
+        // the fix IS the aggregation reading — force dual names through
+        aggregatedContext: true,
+    });
+    if (!isAST_Function(normalized) || kindOf(normalized) === 'FUNCTION') {
+        return undefined;
+    }
+    return {
+        label: `Rewrite as ${normalized.type}{…}`,
+        replacement: printExpression(normalized),
+        range: call.range,
+    };
+};
+/**
+ * Quick-fix for a legacy observable source (either spelling, optionally
+ * with its trailing root `WHERE`): the observable comparison `migrateAst`
+ * produces for it. `undefined` when the call cannot be mapped.
+ */
+const legacyObservableQuickFix = (state, expression) => {
+    const migrated = migrateExpressionNode(expression, {
+        ...state.normalizeOptions,
+        rewriteLegacyObservables: true,
+    });
+    if (!isAST_Function(migrated) || LEGACY_OBSERVABLE_SOURCE_NAMES.has(migrated.type)) {
+        return undefined;
+    }
+    const replacement = printExpression(migrated);
+    return { label: `Rewrite as ${replacement}`, replacement, range: expression.range };
+};
+const isLegacyObservableCall = (value) => isAST_Function(value) &&
+    LEGACY_OBSERVABLE_SOURCE_NAMES.has(value.type) &&
+    kindOf(value) !== 'CLAUSE';
+const reportLegacyObservable = (state, call, fixTarget) => {
+    const spelling = kindOf(call) === 'FUNCTION' ? '(…)' : '{…}';
+    pushIssue(state, 'AQL_LEGACY_SPELLING', `${call.type}${spelling} legacy observable sources have been replaced by live functions (CHANGE_COUNT{…}, HIGHEST{…}, ROWS_ADDED{…}, …) — rewrite the rule, or let the state upgrade migrate it`, call, { quickFix: legacyObservableQuickFix(state, fixTarget) });
+};
+const checkRawSpellingRails = (state, call, context) => {
+    if (context.inCumul) {
+        return;
+    }
+    if (context.inLegacyObservableArgs &&
+        (LEGACY_OBSERVABLE_MARKER_NAMES.has(call.type) || call.type === 'TIMEFRAME')) {
+        return; // pattern markers inside a retired source (already flagged with a quick-fix)
+    }
+    if (call.type === 'CUMUL') {
+        pushIssue(state, 'AQL_LEGACY_SPELLING', 'CUMUL(...) is not supported — use a CUMULATIVE(...) clause, or expressionApi.migratePreV24Expression', call);
+        return;
+    }
+    if (call.type === 'TIMEFRAME') {
+        pushIssue(state, 'AQL_LEGACY_SPELLING', 'TIMEFRAME(...) is not supported — use WITHIN(<duration>), or expressionApi.migratePreV24Expression', call);
+        return;
+    }
+    if (call.type === 'NULL' && call.args.length === 0) {
+        pushIssue(state, 'AQL_LEGACY_SPELLING', 'NULL() is not supported — use the NULL literal, or expressionApi.migratePreV24Expression', call);
+        return;
+    }
+    if (call.type === '$SCOPE' && call.args.length === 0) {
+        pushIssue(state, 'AQL_LEGACY_SPELLING', '$SCOPE() is not supported — use $SCOPE, or expressionApi.migratePreV24Expression', call);
+        return;
+    }
+    if (call.type === 'COL' && call.args.length === 1 && typeof call.args[0] === 'string') {
+        pushIssue(state, 'AQL_LEGACY_SPELLING', `COL('${call.args[0]}') is not supported — use [${call.args[0]}], or expressionApi.migratePreV24Expression`, call);
+        return;
+    }
+    if (LEGACY_OBSERVABLE_SOURCE_NAMES.has(call.type)) {
+        return; // reported by the legacy-observable pass (walkRaw)
+    }
+    if (context.inBraceBody && isRetiredClauseCall(call)) {
+        const renamed = RETIRED_CLAUSE_RENAMES[call.type];
+        pushIssue(state, 'AQL_LEGACY_SPELLING', `${call.type}() has been renamed ${renamed}() — same meaning: one shared history across all rows`, call, { quickFix: { label: `Rename to ${renamed}()`, replacement: `${renamed}()`, range: call.range } });
+        return;
+    }
+    // Named operands in a brace body parse as FUNCTION (`COUNT(3)`, `MIN()`,
+    // `CUMULATIVE([d])`) — they are not leftover paren aggregations.
+    if (context.inBraceBody && isNamedOperandCall(call)) {
+        return;
+    }
+    // Rail 1 — aggregation-only name with parens.
+    if (state.aggregationOnlyNames.has(call.type)) {
+        pushIssue(state, 'AQL_AGG_PAREN_CALL', `${call.type} aggregates a column — use ${call.type}{…}, or expressionApi.migratePreV24Expression`, call, { quickFix: braceQuickFix(state, call) });
+        return;
+    }
+    // Dual name with an operand-tag argument is a leftover paren aggregation
+    // (`SUM([p], GROUP_BY([m]))`) — not the row-wise scalar.
+    if (state.dualNames.has(call.type) &&
+        call.args.some((arg) => isAST_Function(arg) && OPERAND_CLAUSE_NAMES.has(arg.type))) {
+        pushIssue(state, 'AQL_AGG_PAREN_CALL', `${call.type} aggregates a column — use ${call.type}{…}, or expressionApi.migratePreV24Expression`, call, { quickFix: braceQuickFix(state, call) });
+        return;
+    }
+    // Rail 2 — dual name with ONE scalar-typed paren argument. One-arg calls
+    // over array-typed values stay legal (array flattening).
+    if (state.dualNames.has(call.type) && call.args.length === 1) {
+        const arg = call.args[0];
+        const argIsArrayLike = Array.isArray(arg) ||
+            (isAST_Function(arg) &&
+                (arg.type === 'TO_ARRAY' ||
+                    (state.scalarFunctions?.[arg.type]?.returnType ?? '').endsWith('[]')));
+        if (!argIsArrayLike) {
+            pushIssue(state, 'AQL_DUAL_PAREN_AGG', `${call.type} with a single value aggregates a column — use ${call.type}{…} (scalar ${call.type} needs two or more values), or expressionApi.migratePreV24Expression`, call, { quickFix: braceQuickFix(state, call) });
+        }
+    }
+};
+const checkRawCallBodyRails = (state, call) => {
+    // Rails 4 (duplicate authored filter) and 5 (missing-comma quirk) look at
+    // authored filter positions, which the normalizer would silently repair
+    // (AND-merge) — validation still tells the author to clean the text up.
+    let filterPositions = 0;
+    for (const arg of call.args) {
+        if (isAST_Function(arg) && kindOf(arg) === 'INFIX' && arg.type === 'WHERE') {
+            filterPositions += 1;
+            const lhs = arg.args[0];
+            // `ANY_COL(…)` is the subject, so `ANY_COL() WHERE p` is an inline filter
+            if (isAST_Function(lhs) &&
+                lhs.type !== 'ANY_COL' &&
+                (OPERAND_CLAUSE_NAMES.has(lhs.type) || kindOf(lhs) === 'CLAUSE')) {
+                pushIssue(state, 'AQL_MISSING_COMMA_BEFORE_WHERE', `WHERE is filtering the ${lhs.type} clause — add a comma before WHERE, or move the filter next to the input`, arg);
+            }
+        }
+        else if (isClauseNode(arg) && arg.type === 'WHERE') {
+            filterPositions += 1;
+        }
+    }
+    if (filterPositions > 1) {
+        pushIssue(state, 'AQL_DUPLICATE_FILTER', `${call.type} has ${filterPositions} WHERE filters — a call takes one filter (combine predicates with AND)`, call);
+    }
+};
+const walkRaw = (state, expression, context) => {
+    if (expression == null || typeof expression !== 'object') {
+        return;
+    }
+    if (Array.isArray(expression)) {
+        for (const item of expression) {
+            walkRaw(state, item, context);
+        }
+        return;
+    }
+    if (!isAST_Function(expression)) {
+        for (const value of Object.values(expression)) {
+            walkRaw(state, value, context);
+        }
+        return;
+    }
+    const kind = kindOf(expression);
+    // Legacy observable sources: one error per call (either spelling), with
+    // the observable rewrite as quick-fix. A root `… WHERE p` over the call is
+    // fixed as a whole so the filter lands inside the observable call.
+    if (context.isRoot &&
+        kind === 'INFIX' &&
+        expression.type === 'WHERE' &&
+        isLegacyObservableCall(expression.args[0])) {
+        reportLegacyObservable(state, expression.args[0], expression);
+        walkRaw(state, expression.args[0].args, { inLegacyObservableArgs: true });
+        walkRaw(state, expression.args[1], {});
+        return;
+    }
+    const isLegacyObservable = isLegacyObservableCall(expression);
+    if (isLegacyObservable) {
+        reportLegacyObservable(state, expression, expression);
+    }
+    else if (kind === 'FUNCTION') {
+        checkRawSpellingRails(state, expression, context);
+    }
+    const isBraceCall = kind === 'AGG_CALL' || kind === 'OBSERVABLE_CALL';
+    const isLegacyAggCall = kind === 'FUNCTION' &&
+        (state.aggregationOnlyNames.has(expression.type) || state.dualNames.has(expression.type));
+    if (!isLegacyObservable && (isBraceCall || isLegacyAggCall)) {
+        checkRawCallBodyRails(state, expression);
+    }
+    const childContext = {
+        inLegacyObservableArgs: isLegacyObservable,
+        inCumul: context.inCumul || expression.type === 'CUMUL',
+        inBraceBody: isBraceCall,
+    };
+    walkRaw(state, expression.args, childContext);
+};
+const isNamedOperandCall = (call) => OPERAND_CLAUSE_NAMES.has(call.type);
+/** A retired clause spelling left in a brace body (`GRID()`); reported on the raw tree. */
+const isRetiredClauseCall = (value) => isAST_Function(value) &&
+    RETIRED_CLAUSE_RENAMES[value.type] !== undefined &&
+    value.args.length === 0 &&
+    kindOf(value) === 'FUNCTION';
+// ---------------------------------------------------------------------------
+// Normalized-tree rails (structure, clauses, operand types)
+// ---------------------------------------------------------------------------
+const resolveCallSpec = (state, call, callKind) => {
+    if (callKind === 'OBSERVABLE_CALL') {
+        return (getObservableCallSpec(call.type) ??
+            (state.customObservableNames.has(call.type) ? CUSTOM_OBSERVABLE_FALLBACK_SPEC : undefined));
+    }
+    return (state.catalogue.getBraceCallSpec(call.type) ??
+        // A host-known name with no operator in the catalogue: accept the
+        // baseline shape (input + GROUP_BY / WHERE) so the rest of the
+        // expression still validates.
+        (state.customAggregatedNames.has(call.type) ? BASELINE_CUSTOM_AGGREGATION_SPEC : undefined));
+};
+/** Bracket-aware unknown-name diagnostics for brace calls. */
+const reportUnknownBraceCall = (state, call) => {
+    const scalarHomonym = state.scalarFunctions?.[call.type];
+    pushIssue(state, 'AQL_UNKNOWN_BRACE_CALL', scalarHomonym
+        ? `${call.type}{…} is not a known aggregation or live function — ${call.type}(…) exists as a scalar function; did you mean parentheses?`
+        : `${call.type}{…} is not a known aggregation or live function`, call);
+};
+const isPositiveIntLiteral = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1;
+/**
+ * WITHIN may be omitted when the call allows a cumulative (since-load) window
+ * and the WITHIN clause is not marked required on the callable spec.
+ */
+const isWithinClauseOptional = (call, state) => {
+    const spec = getObservableCallSpec(call.type) ??
+        (state.customObservableNames.has(call.type) ? CUSTOM_OBSERVABLE_FALLBACK_SPEC : undefined);
+    if (!spec) {
+        return true;
+    }
+    const withinClause = spec.clauses.find((entry) => entry.clause === 'WITHIN');
+    if (!withinClause) {
+        return true;
+    }
+    if (withinClause.required) {
+        return false;
+    }
+    return spec.windows.includes('cumulative');
+};
+const SORT_DIRECTION_HINT = SORT_DIRECTION_LITERALS.map((literal) => `'${literal}'`).join(' or ');
+/** `OVER([col], 'DESC')` / `CUMULATIVE([col], 'DESC')`: at most one direction literal. */
+const checkSortDirectionArgs = (state, clause, extraArgs) => {
+    const [direction, ...rest] = extraArgs;
+    if (direction === undefined) {
+        return;
+    }
+    if (!toSortDirection(direction)) {
+        pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} sort direction must be ${SORT_DIRECTION_HINT} — got ${printExpression(direction)}`, clause);
+        return;
+    }
+    if (rest.length > 0) {
+        pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} takes a column and an optional direction — remove ${printExpression(rest[0])}`, clause);
+    }
+};
+/**
+ * Self-sorting windows (`QUANT{[v], 4, 'DESC'}`, `QUARTILE{[v], 'DESC'}`):
+ * any text item after the input must be a single direction literal.
+ */
+const checkSelfSortDirection = (state, call) => {
+    const [, ...paramItems] = call.args.filter((arg) => !isClauseNode(arg));
+    let directionCount = 0;
+    for (const item of paramItems) {
+        if (typeof item !== 'string') {
+            continue;
+        }
+        if (!toSortDirection(item)) {
+            pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${call.type} sort direction must be ${SORT_DIRECTION_HINT} — got ${printExpression(item)}`, call);
+            continue;
+        }
+        directionCount += 1;
+        if (directionCount > 1) {
+            pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${call.type} takes one sort direction — remove ${printExpression(item)}`, call);
+        }
+    }
+};
+const checkClauseOperand = (state, call, clause) => {
+    const operandKind = CLAUSE_OPERAND_KINDS[clause.type];
+    const rawOperand = clause.args[0];
+    // Flatten leftover `CUMULATIVE(OVER([d]))` from pre-amendment ASTs.
+    const orderArgs = clause.type === 'CUMULATIVE' && isAST_Function(rawOperand) && rawOperand.type === 'OVER'
+        ? rawOperand.args
+        : clause.args;
+    const operand = orderArgs[0];
+    if (clause.type === 'OVER' || clause.type === 'CUMULATIVE') {
+        checkSortDirectionArgs(state, clause, orderArgs.slice(1));
+    }
+    switch (operandKind) {
+        case 'ref':
+        case 'numeric-ref': {
+            if (!isRefNode(operand)) {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} expects a column reference like [tradeDate]`, clause);
+                return;
+            }
+            if (operandKind === 'numeric-ref' && state.getColumnType) {
+                const columnId = operand.args[0];
+                const columnType = typeof columnId === 'string' ? state.getColumnType(columnId) : undefined;
+                if (columnType && columnType !== 'number') {
+                    pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} expects a numeric column — [${columnId}] is ${columnType}`, clause);
+                }
+            }
+            return;
+        }
+        case 'duration': {
+            if (isAST_Function(operand) && operand.type === 'DURATION_PLACEHOLDER') {
+                const withinOptional = isWithinClauseOptional(call, state);
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', withinOptional
+                    ? 'Replace duration-here with a duration (e.g. 5m, 2h, 1d) or remove the WITHIN clause if its not required'
+                    : 'Replace duration-here with a duration (e.g. 5m, 2h, 1d)', clause, { severity: 'warning', range: operand.range });
+                return;
+            }
+            if (!isAST_Function(operand) || operand.type !== 'DURATION') {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} expects a duration literal like 250ms, 20s, 5m, 1h or 3d`, clause);
+                return;
+            }
+            // Rail 9 — max-window clamp.
+            const ms = operand.args[0];
+            if (typeof ms === 'number' && ms > state.maxWithinMs) {
+                pushIssue(state, 'AQL_WITHIN_EXCEEDS_MAX', `WITHIN(${formatDurationMs(ms)}) exceeds the maximum window of ${formatDurationMs(state.maxWithinMs)}`, clause);
+            }
+            return;
+        }
+        case 'positive-int': {
+            if (!isPositiveIntLiteral(operand)) {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} expects a whole number of at least 1, like ${clause.type}(20)`, clause);
+                return;
+            }
+            if (clause.type === 'LAST_N' && operand > state.maxHistoryPerCell) {
+                pushIssue(state, 'AQL_LAST_N_EXCEEDS_MAX', `LAST_N(${operand}) exceeds the maximum history of ${state.maxHistoryPerCell} changes per cell`, clause);
+            }
+            return;
+        }
+        case 'trigger-list': {
+            if (clause.args.length === 0) {
+                pushIssue(state, 'AQL_TRIGGER_KIND', `TRIGGER needs at least one origin: ${[...TRIGGER_LITERALS].map((t) => `'${t}'`).join(', ')}`, clause);
+                return;
+            }
+            for (const arg of clause.args) {
+                if (typeof arg !== 'string' || !TRIGGER_LITERALS.has(arg)) {
+                    pushIssue(state, 'AQL_TRIGGER_KIND', `TRIGGER accepts ${[...TRIGGER_LITERALS].map((t) => `'${t}'`).join(', ')} — got ${typeof arg === 'string' ? `'${arg}'` : printExpression(arg)}`, clause);
+                }
+            }
+            return;
+        }
+        case 'column-list': {
+            for (const arg of clause.args) {
+                if (!isAST_Function(arg) || arg.type !== 'COL') {
+                    pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type} takes column references — ${clause.type}() for every column, or ${clause.type}([bid], [ask])`, clause);
+                    return;
+                }
+            }
+            return;
+        }
+        case 'none': {
+            if (clause.args.length > 0) {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${clause.type}() takes no operand`, clause);
+            }
+            return;
+        }
+        default:
+            return;
+    }
+};
+/**
+ * Observable-specific rails, run after the generic clause loop (which already
+ * handled duplicates, disallowed clauses and operand shapes).
+ */
+const checkObservableCall = (state, call, spec, seen) => {
+    const callDisplay = `${call.type}{…}`;
+    if (seen.has('WITHIN') && seen.has('LAST_N')) {
+        pushIssue(state, 'AQL_CLAUSE_CONFLICT', `${callDisplay} cannot have both WITHIN and LAST_N — pick a time window or a count window`, call.args.find((arg) => isClauseNode(arg) && arg.type === 'LAST_N'));
+    }
+    const positional = call.args.filter((arg) => !isClauseNode(arg) && !isRetiredClauseCall(arg));
+    const input = positional[0];
+    if (spec.input === 'column-or-any') {
+        const anyCol = call.args.find((arg) => isClauseNode(arg) && arg.type === 'ANY_COL');
+        if (anyCol) {
+            if (input !== undefined) {
+                pushIssue(state, 'AQL_OBSERVABLE_INPUT', `${call.type} watches either one column or ANY_COL(…), not both — remove ${printExpression(input)} or ANY_COL(…)`, call);
+            }
+            const trigger = call.args.find((arg) => isClauseNode(arg) && arg.type === 'TRIGGER');
+            if (trigger?.args.includes('calculated')) {
+                pushIssue(state, 'AQL_TRIGGER_KIND', `ANY_COL() never sees Calculated Column recomputations — watch the Calculated Column itself: ${call.type}{[column], TRIGGER('calculated')}`, trigger);
+            }
+            return;
+        }
+        if (input === undefined) {
+            pushIssue(state, 'AQL_OBSERVABLE_INPUT', `${call.type}{} needs something to watch: ${call.type}{[price], …} for one column, or ${call.type}{ANY_COL(), …} for every column`, call);
+            return;
+        }
+    }
+    if (spec.input === 'required' || spec.input === 'column-or-any') {
+        if (input === undefined) {
+            pushIssue(state, 'AQL_OBSERVABLE_INPUT', `${call.type}{} needs a column to watch: ${call.type}{[price], …}`, call);
+        }
+        else if (!isAST_Function(input) || input.type !== 'COL') {
+            pushIssue(state, 'AQL_OBSERVABLE_INPUT', `${call.type} watches a column — write ${call.type}{[price], …}, not an expression`, call);
+        }
+        else if (spec.inputTypes && state.getColumnType && typeof input.args[0] === 'string') {
+            const columnType = state.getColumnType(input.args[0]);
+            if (columnType !== undefined && !spec.inputTypes.includes(columnType)) {
+                pushIssue(state, 'AQL_OBSERVABLE_NUMERIC_INPUT', `${call.type} needs a ${spec.inputTypes.join(' or ')} column — [${input.args[0]}] is ${columnType}`, call);
+            }
+        }
+        // Extra positional params (`PREVIOUS{[c], n}`).
+        const params = spec.positional ?? [];
+        for (let index = 1; index < positional.length; index += 1) {
+            const param = params[index - 1];
+            const value = positional[index];
+            if (!param) {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${callDisplay} takes ${params.length + 1} item${params.length ? 's' : ''} — remove ${printExpression(value)}`, call);
+                break;
+            }
+            if (!isPositiveIntLiteral(value)) {
+                pushIssue(state, 'AQL_CLAUSE_OPERAND_TYPE', `${call.type} ${param.name} must be a whole number of at least 1, like ${call.type}{[price], 2}`, call);
+            }
+        }
+    }
+    else if (spec.input === 'forbidden' && positional.length > 0) {
+        pushIssue(state, 'AQL_OBSERVABLE_INPUT', `${call.type}{} takes no input — it ${spec.scopes.length === 1 && spec.scopes[0] === 'grid' ? 'counts row events' : 'reads the row itself'}`, call);
+    }
+};
+const OBSERVABLE_CLAUSES = new Set([
+    'ANY_COL',
+    'WITHIN',
+    'LAST_N',
+    'ALL_ROWS',
+    'TRIGGER',
+]);
+const checkCallClauses = (state, call, callKind, spec) => {
+    const clauses = call.args.filter(isClauseNode);
+    const allowed = new Set(spec.clauses.map((usage) => usage.clause));
+    const seen = new Set();
+    const callDisplay = `${call.type}{…}`;
+    for (const clause of clauses) {
+        // Rail 4 — duplicate clause per call (duplicate filters are caught on the
+        // authored text; the normalizer AND-merges them).
+        if (seen.has(clause.type)) {
+            pushIssue(state, 'AQL_DUPLICATE_CLAUSE', `${callDisplay} has more than one ${clause.type} clause`, clause);
+            continue;
+        }
+        seen.add(clause.type);
+        if (!allowed.has(clause.type)) {
+            // Rail 11 — cumulation capability.
+            if (clause.type === 'CUMULATIVE' && callKind === 'AGG_CALL') {
+                pushIssue(state, 'AQL_CUMULATIVE_UNSUPPORTED', `${call.type} does not support CUMULATIVE (supported: ${state.catalogue
+                    .cumulativeNames()
+                    .join(', ')})`, clause);
+                continue;
+            }
+            // Rail 10 — clause/context mismatch.
+            let message = `${callDisplay} does not accept a ${clause.type} clause`;
+            if (callKind === 'AGG_CALL' && OBSERVABLE_CLAUSES.has(clause.type)) {
+                message =
+                    clause.type === 'WITHIN'
+                        ? `WITHIN is a live-function (window) clause — it cannot appear in the aggregation ${callDisplay}`
+                        : `${clause.type} is a live-function clause — it cannot appear in the aggregation ${callDisplay}`;
+            }
+            else if (callKind === 'OBSERVABLE_CALL' && clause.type === 'ALL_ROWS') {
+                message =
+                    call.type === 'ROW_AGE' || call.type === 'ADDED_AT'
+                        ? `${call.type} is per row — ALL_ROWS() does not apply here`
+                        : `${call.type} already counts across all rows — remove ALL_ROWS()`;
+            }
+            else if (callKind === 'OBSERVABLE_CALL' && clause.type === 'ANY_COL') {
+                message = `${call.type} reads one column's values — ANY_COL() only works with ${ANY_COL_SOURCE_NAMES.join(', ')}`;
+            }
+            else if (callKind === 'OBSERVABLE_CALL' && (clause.type === 'WITHIN' || clause.type === 'LAST_N')) {
+                const observableSpec = spec;
+                if (call.type === 'PREVIOUS') {
+                    message = `PREVIOUS reads the n-th last change — use PREVIOUS{[col], n} instead of a ${clause.type} window`;
+                }
+                else if (clause.type === 'LAST_N' && observableSpec.windows?.includes('WITHIN')) {
+                    message = `${call.type} takes a time window, not a count window — use WITHIN(<duration>) instead of LAST_N`;
+                }
+                else {
+                    message = `${call.type} has no window — remove ${clause.type}`;
+                }
+            }
+            else if (callKind === 'OBSERVABLE_CALL' && clause.type === 'GROUP_BY') {
+                message = `${call.type} is per row (or ALL_ROWS()) — GROUP_BY does not apply to live functions`;
+            }
+            pushIssue(state, 'AQL_CLAUSE_NOT_ALLOWED', message, clause);
+            continue;
+        }
+        checkClauseOperand(state, call, clause);
+    }
+    for (const usage of spec.clauses) {
+        if (usage.required && !seen.has(usage.clause)) {
+            pushIssue(state, 'AQL_MISSING_REQUIRED_CLAUSE', `${call.type} requires an ${usage.clause} clause (e.g. ${call.type}{${usage.clause}([column])})`, call);
+        }
+    }
+    if (callKind === 'OBSERVABLE_CALL') {
+        // Observable input rails replace rail 8 (they carry column-specific text).
+        checkObservableCall(state, call, spec, seen);
+        return;
+    }
+    // Rail 8 — every aggregation needs an input (RANK is the
+    // metadata-declared exception).
+    const positionalItems = call.args.filter((arg) => !isClauseNode(arg));
+    if (spec.requiresInput && positionalItems.length === 0) {
+        pushIssue(state, 'AQL_MISSING_INPUT', `${call.type}{} needs an input expression`, call);
+    }
+    if (spec.acceptsSortDirection) {
+        checkSelfSortDirection(state, call);
+    }
+};
+const walkNormalized = (state, expression, context) => {
+    if (expression == null || typeof expression !== 'object') {
+        return;
+    }
+    if (Array.isArray(expression)) {
+        for (const item of expression) {
+            walkNormalized(state, item, context);
+        }
+        return;
+    }
+    if (!isAST_Function(expression)) {
+        for (const value of Object.values(expression)) {
+            walkNormalized(state, value, { ...context, isRoot: false });
+        }
+        return;
+    }
+    const kind = kindOf(expression);
+    const childContext = { ...context, isRoot: false };
+    if (LEGACY_OBSERVABLE_SOURCE_NAMES.has(expression.type) && kind !== 'CLAUSE') {
+        // Already reported as AQL_LEGACY_SPELLING on the authored tree; the
+        // brace body would only produce follow-on noise.
+        return;
+    }
+    if (kind === 'AGG_CALL') {
+        // Rail 3 — aggregation braces do not nest.
+        if (context.insideAggCall) {
+            pushIssue(state, 'AQL_NESTED_AGG', `${context.insideAggCall}{…} cannot contain ${expression.type}{…} — compose aggregations with scalar math outside the braces`, expression);
+        }
+        const spec = resolveCallSpec(state, expression, 'AGG_CALL');
+        if (!spec) {
+            reportUnknownBraceCall(state, expression);
+        }
+        else {
+            checkCallClauses(state, expression, 'AGG_CALL', spec);
+        }
+        childContext.insideAggCall = expression.type;
+    }
+    else if (kind === 'OBSERVABLE_CALL') {
+        if (context.insideObservableCall) {
+            pushIssue(state, 'AQL_OBSERVABLE_IN_OBSERVABLE', `${context.insideObservableCall}{…} cannot contain ${expression.type}{…} — live functions do not nest; combine them with scalar math outside the braces`, expression);
+        }
+        if (context.insideAggCall) {
+            pushIssue(state, 'AQL_OBSERVABLE_IN_AGGREGATION', `${context.insideAggCall}{…} cannot contain ${expression.type}{…} — aggregate the column, then compare with the live function outside the braces`, expression);
+        }
+        const spec = resolveCallSpec(state, expression, 'OBSERVABLE_CALL');
+        if (!spec) {
+            reportUnknownBraceCall(state, expression);
+        }
+        else {
+            checkCallClauses(state, expression, 'OBSERVABLE_CALL', spec);
+        }
+        childContext.insideObservableCall = expression.type;
+    }
+    else if (kind === 'FUNCTION') {
+        // Bracket-aware unknown paren name. Sugar / leftover operand tags are
+        // never "unknown functions"; leftover aggregations are separate rails.
+        if (state.scalarFunctions &&
+            !state.scalarFunctions[expression.type] &&
+            !NON_POOL_FUNCTION_NAMES.has(expression.type) &&
+            !EVALUATION_SUGAR_AND_OPERAND_NAMES.has(expression.type) &&
+            !(context.insideObservableCall && isRetiredClauseCall(expression))) {
+            const braceHomonym = state.aggregationOnlyNames.has(expression.type) ||
+                state.observableNames.has(expression.type);
+            pushIssue(state, 'AQL_UNKNOWN_FUNCTION', braceHomonym
+                ? `${expression.type}(…) is not a scalar function — did you mean ${expression.type}{…}?`
+                : `${expression.type}(…) is not a known function`, expression);
+        }
+    }
+    else if ((kind === 'INFIX' || kind === 'CONDITIONAL') &&
+        state.scalarFunctions &&
+        KEYWORD_OPERATORS.has(expression.type) &&
+        !state.scalarFunctions[expression.type]) {
+        pushIssue(state, 'AQL_UNKNOWN_FUNCTION', `${expression.type} is not available here`, expression);
+    }
+    walkNormalized(state, expression.args, childContext);
+};
+// ---------------------------------------------------------------------------
+// Host request checks (structural kind, return type, capabilities)
+// ---------------------------------------------------------------------------
+const checkRequest = (state, request, classification, normalizedAst) => {
+    const root = getRootExpression(normalizedAst);
+    const rootFn = isAST_Function(root) ? root : undefined;
+    if (request.allowsAggCalls === false && classification.aggCallCount > 0) {
+        pushIssue(state, 'AQL_AGG_NOT_ALLOWED', `aggregations are not available in this context — it is evaluated per row`, rootFn);
+    }
+    if (request.requiresAggCalls && classification.aggCallCount === 0) {
+        pushIssue(state, 'AQL_AGG_REQUIRED', `this context requires an aggregation (e.g. SUM{[column]})`, rootFn);
+    }
+    if (request.allowsObservableCalls === false && classification.observableCallCount > 0) {
+        pushIssue(state, 'AQL_OBSERVABLE_NOT_ALLOWED', `live functions (CHANGE_COUNT{…}, HIGHEST{…}, …) are not available in this context`, rootFn);
+    }
+    if (request.returnType === 'boolean' && state.scalarFunctions) {
+        const rootType = inferStaticExpressionType(normalizedAst, state.scalarFunctions, {
+            getColumnType: state.getColumnType,
+            getBraceCallSpec: state.catalogue.getBraceCallSpec,
+        });
+        if (rootType !== 'boolean' && rootType !== 'unknown') {
+            pushIssue(state, 'AQL_ROOT_NOT_BOOLEAN', `this context expects a condition (boolean), but the expression returns ${rootType}`, rootFn);
+        }
+    }
+};
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export const validateAqlExpression = (ast, options = {}) => {
+    const catalogue = options.catalogue ?? SYSTEM_AGGREGATION_CATALOGUE;
+    const customAggregatedNames = new Set([
+        ...catalogue.customNames(),
+        ...(options.customAggregatedNames ?? []),
+    ]);
+    const customObservableNames = new Set(options.customObservableNames ?? []);
+    const scalarNameSet = new Set(Object.keys(options.scalarFunctions ?? {}));
+    // A name in both the scalar pool and a custom aggregation pool is a dual
+    // name (paren = row-wise, brace = agg).
+    const dynamicDualNames = [...customAggregatedNames].filter((name) => scalarNameSet.has(name));
+    const dualNames = dynamicDualNames.length > 0
+        ? new Set([...DUAL_AGGREGATION_NAMES, ...dynamicDualNames])
+        : DUAL_AGGREGATION_NAMES;
+    const aggregationOnlyExtras = [...customAggregatedNames].filter((name) => !dualNames.has(name));
+    const normalizeOptions = {
+        customAggregatedNames,
+        customObservableNames,
+    };
+    const state = {
+        issues: [],
+        aggregationOnlyNames: aggregationOnlyExtras.length
+            ? new Set([...AGGREGATION_ONLY_NAMES, ...aggregationOnlyExtras])
+            : AGGREGATION_ONLY_NAMES,
+        dualNames,
+        observableNames: customObservableNames.size
+            ? new Set([...OBSERVABLE_SOURCE_NAMES, ...customObservableNames])
+            : OBSERVABLE_SOURCE_NAMES,
+        scalarFunctions: options.scalarFunctions,
+        catalogue,
+        customAggregatedNames,
+        customObservableNames,
+        maxWithinMs: options.maxWithinMs ?? DEFAULT_MAX_WITHIN_MS,
+        maxHistoryPerCell: options.maxHistoryPerCell ?? DEFAULT_MAX_HISTORY_PER_CELL,
+        getColumnType: options.getColumnType,
+        normalizeOptions,
+    };
+    // Phase A — authored-spelling rails on the raw tree.
+    ast.forEach((statement, index) => {
+        walkRaw(state, statement, { isRoot: index === ast.length - 1 });
+    });
+    // Phase B — normalize onto the contract-v3 shape.
+    const normalizedAst = normalizeAst(ast, normalizeOptions);
+    // Phase C — structural classification + host request.
+    const classification = classifyExpression(normalizedAst, {
+        scalarFunctions: options.scalarFunctions,
+    });
+    const request = options.request;
+    if (request) {
+        checkRequest(state, request, classification, normalizedAst);
+    }
+    // Phase D — structure / clause / operand rails on the normalized tree.
+    normalizedAst.forEach((statement, index) => {
+        walkNormalized(state, statement, { isRoot: index === normalizedAst.length - 1 });
+    });
+    // Phase E — scalar type walk (brace-aware).
+    if (options.scalarFunctions) {
+        const typeCheck = validateExpressionTypes(normalizedAst, options.scalarFunctions, {
+            getColumnType: options.getColumnType,
+            getBraceCallSpec: catalogue.getBraceCallSpec,
+        });
+        for (const issue of typeCheck.issues) {
+            state.issues.push({
+                code: issue.code ?? 'AQL_TYPE_MISMATCH',
+                message: issue.message,
+                severity: issue.severity,
+                range: issue.range,
+                functionName: issue.functionName,
+                // Literal-level fixes carry no range (literals have no source span);
+                // the editor applies them by text.
+                quickFix: issue.quickFix,
+            });
+        }
+    }
+    return {
+        isValid: state.issues.every((issue) => issue.severity !== 'error'),
+        issues: state.issues,
+        classification,
+        normalizedAst,
+    };
+};
+//# sourceMappingURL=validateAqlExpression.js.map