@tellaro/tql 1.5.0 → 3.0.0

package/dist/src/types.d.ts

@@ -38,9 +38,25 @@ export interface TqlComparisonExpression {
     start: number;
     end: number;
 }
+/**
+ * `field ANY value` and its relatives — a comparison applied across the ELEMENTS of an
+ * array-valued field rather than to the field as a whole.
+ *
+ * This type shipped for a long time with no parse path that could produce it: the tokenizer
+ * emitted `collectionOp` for `any` / `all` / `none`, the parser had no arm for that token
+ * type, and every collection query in the editor came back as
+ * "Expected operator after field". The type and `COLLECTION_OPERATORS` were exported the
+ * whole time, so the surface looked supported. `tests/collectionParity.spec.ts` now pins the
+ * accepted forms against both engine grammars.
+ *
+ * `negated` carries the `not any` / `!any` / `not_any` spellings, which both engines accept
+ * and which are otherwise indistinguishable from the positive form once `operator` has been
+ * normalised to its canonical upper-case name.
+ */
 export interface TqlCollectionExpression {
     type: "collection";
     operator: "ANY" | "ALL" | "NONE";
+    negated: boolean;
     field: TqlFieldReference;
     condition: TqlExpression;
     start: number;
@@ -88,21 +104,52 @@ export interface TqlLiteral {
     start: number;
     end: number;
 }
+/**
+ * One argument inside a parameterised mutator call: `split(delimiter=",")`.
+ *
+ * Both engines accept named (`delimiter=","`), positional (`","`) and bare-identifier
+ * (`old=a`) arguments; neither accepts a list literal. See `mutator_arg` in
+ * tql/src/parser/grammar.pest and `_setup_mutators` in
+ * src/tql/parser_components/grammar.py.
+ */
+export interface TqlMutatorArgument {
+    /** Present for `name=value` form; absent for a positional argument. */
+    name?: string;
+    valueType: "string" | "number" | "boolean" | "null" | "identifier";
+    value: string | number | boolean | null;
+    start: number;
+    end: number;
+}
+/**
+ * One link in a mutator chain, with the arguments it was called with.
+ *
+ * `TqlFieldReference.mutators` remains the flat list of names (unchanged for existing
+ * consumers); `mutatorCalls` carries the same chain with argument detail attached.
+ */
+export interface TqlMutatorCall {
+    name: string;
+    args: TqlMutatorArgument[];
+    /** True when the call carried an explicit `(...)` list, even an empty one. */
+    parenthesized: boolean;
+    start: number;
+    end: number;
+}
 export interface TqlFieldReference {
     type: "field";
     name: string;
     path: string[];
     mutators?: string[];
+    mutatorCalls?: TqlMutatorCall[];
     typeHint?: TqlTypeHint;
     start: number;
     end: number;
 }
-export type TqlComparisonOperator = "eq" | "ne" | "=" | "!=" | "==" | "eq_ci" | "gt" | "gte" | "lt" | "lte" | ">" | ">=" | "<" | "<=" | "contains" | "not_contains" | "!contains" | "startswith" | "not_startswith" | "!startswith" | "endswith" | "not_endswith" | "!endswith" | "contains_cs" | "not_contains_cs" | "!contains_cs" | "startswith_cs" | "not_startswith_cs" | "!startswith_cs" | "endswith_cs" | "not_endswith_cs" | "!endswith_cs" | "regexp" | "regex" | "not_regexp" | "not_regex" | "!regexp" | "!regex" | "matches" | "not_matches" | "!matches" | "between" | "not_between" | "!between" | "in" | "not_in" | "!in" | "in_cs" | "not_in_cs" | "!in_cs" | "exists" | "not_exists" | "!exists" | "is" | "is_not" | "!is" | "cidr" | "not_cidr" | "!cidr" | "any" | "all" | "none" | "not_any" | "not_all" | "not_none" | "!any" | "!all" | "!none";
+export type TqlComparisonOperator = "eq" | "ne" | "=" | "!=" | "eq_ci" | "gt" | "gte" | "lt" | "lte" | ">" | ">=" | "<" | "<=" | "contains" | "not_contains" | "!contains" | "startswith" | "not_startswith" | "!startswith" | "endswith" | "not_endswith" | "!endswith" | "contains_cs" | "not_contains_cs" | "!contains_cs" | "startswith_cs" | "not_startswith_cs" | "!startswith_cs" | "endswith_cs" | "not_endswith_cs" | "!endswith_cs" | "regexp" | "regex" | "not_regexp" | "not_regex" | "!regexp" | "!regex" | "matches" | "not_matches" | "!matches" | "between" | "not_between" | "!between" | "in" | "not_in" | "!in" | "in_cs" | "not_in_cs" | "!in_cs" | "exists" | "not_exists" | "!exists" | "is" | "is_not" | "!is" | "cidr" | "not_cidr" | "!cidr" | "any" | "all" | "none" | "not_any" | "not_all" | "not_none" | "!any" | "!all" | "!none";
 export type TqlLogicalOperator = "AND" | "OR" | "NOT";
 export type TqlCollectionOperator = "ANY" | "ALL" | "NONE";
 export type TqlMutator = "lowercase" | "uppercase" | "trim" | "split" | "length" | "replace" | "b64encode" | "b64decode" | "urldecode" | "hexencode" | "hexdecode" | "md5" | "sha256" | "refang" | "defang" | "is_private" | "is_global" | "is_multicast" | "is_loopback" | "is_link_local" | "nslookup" | "geoip_lookup" | "geoip" | "geo" | "any" | "all" | "avg" | "average" | "sum" | "min" | "max";
 export type TqlAggregationFunction = "count" | "sum" | "avg" | "average" | "mean" | "median" | "med" | "min" | "max" | "percentile" | "percentiles" | "p" | "pct" | "percentile_rank" | "percentile_ranks" | "pct_rank" | "pct_ranks" | "std" | "standard_deviation" | "unique_count" | "cardinality" | "values" | "unique" | "distinct";
-export type TqlTypeHint = "string" | "str" | "number" | "int" | "integer" | "float" | "double" | "decimal" | "date" | "bool" | "boolean" | "array" | "list" | "object" | "geo";
+export type TqlTypeHint = "string" | "str" | "number" | "int" | "integer" | "float" | "double" | "decimal" | "date" | "bool" | "boolean" | "array" | "list" | "object" | "geo" | "ip";
 export type TqlVisualizationType = "bar" | "barchart" | "horizontal_bar" | "line" | "area" | "stacked_area" | "pie" | "donut" | "scatter" | "heatmap" | "treemap" | "sunburst" | "table" | "number" | "gauge" | "map" | "grouped_bar" | "stacked_bar" | "nested_pie" | "nested_donut" | "chord" | "auto";
 /**
  * Visualization parameters (e.g., title="Events", stacked=true).
@@ -153,8 +200,75 @@ export interface TqlParseWarning {
     code: TqlWarningCode;
     suggestion?: string;
 }
-export type TqlErrorCode = "UNEXPECTED_TOKEN" | "UNEXPECTED_END" | "UNBALANCED_PARENS" | "UNBALANCED_BRACKETS" | "UNTERMINATED_STRING" | "INVALID_OPERATOR" | "INVALID_MUTATOR" | "INVALID_VALUE" | "MISSING_OPERAND" | "MISSING_OPERATOR" | "MISSING_VALUE" | "MISSING_FIELD" | "MISSING_MUTATOR" | "INVALID_SYNTAX" | "MAX_DEPTH_EXCEEDED" | "TYPE_MISMATCH";
-export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPERATOR" | "REDUNDANT_PARENS";
+export type TqlErrorCode = "UNEXPECTED_TOKEN" | "UNEXPECTED_END" | "UNBALANCED_PARENS" | "UNBALANCED_BRACKETS" | "UNTERMINATED_STRING" | "INVALID_OPERATOR" | "INVALID_MUTATOR" | "INVALID_VALUE" | "MISSING_OPERAND" | "MISSING_OPERATOR" | "MISSING_VALUE" | "MISSING_FIELD" | "MISSING_MUTATOR" | "INVALID_SYNTAX" | "MAX_DEPTH_EXCEEDED" | "TYPE_MISMATCH"
+/**
+ * `f::int | trim::str` — a type hint on BOTH sides of the mutator chain.
+ *
+ * Both engines accept the hint in either position and refuse it in both, structurally: each
+ * grammar is an ordered choice whose first alternative consumes `f::int | trim` and strands
+ * `::str`. There is no defensible answer for which hint would win.
+ */
+ | "DUPLICATE_TYPE_HINT"
+/**
+ * `::` with a token after it that can never be a type name (`f::| trim`, `f:: eq 'a'`,
+ * `f | trim:: eq 'a'`, `f::lowercase`). All four are parse errors in both engines.
+ *
+ * `f::` at END of input is NOT this — that is a hint being typed, and stays a warning.
+ */
+ | "MISSING_TYPE_HINT"
+/**
+ * A malformed `top N` / `bottom N` modifier on a stats aggregation.
+ *
+ * Reserved for the shapes BOTH engines refuse: the modifier given twice on one aggregation
+ * (`sum(x, top 10) top 5`), a modifier with no count (`sum(x) top by y`), and the in-parens
+ * form on `count(*)` / `count()` (`count(*, top 2)`). A spelling only one engine refuses is
+ * an ENGINE_DIVERGENCE warning instead — never this.
+ */
+ | "INVALID_STATS_MODIFIER";
+export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPERATOR" | "REDUNDANT_PARENS"
+/**
+ * The query parses, but only ONE of the two engines accepts it.
+ *
+ * Reserved for measured, currently-live divergences between `tql/src/parser/grammar.pest`
+ * and `src/tql/parser_components/grammar.py` — not for anything this package merely
+ * dislikes. The editor stays permissive (a red squiggle over syntax an engine accepts is
+ * the defect this parser keeps being fixed for) while still naming the engine that will
+ * refuse the query, because silently accepting it is the worse half of the same failure:
+ * the user finds out at execution instead of at the keystroke.
+ */
+ | "ENGINE_DIVERGENCE"
+/**
+ * The query parses, but the field cannot answer the operator and the query engine refuses
+ * it at execution.
+ *
+ * Raised for the `_cs` (case-sensitive) operators, under TWO rules rather than one --
+ * they do not share a predicate, and describing only the first is how this docstring was
+ * wrong on 90 of its own 98 firing cells before review:
+ *
+ *   * the WHOLE-VALUE six (`contains_cs`, `startswith_cs`, `endswith_cs` + negations)
+ *     whenever the field has no case-preserving form at all. That includes analyzed `text`
+ *     with no `keyword` subfield AND every non-string type -- a `long`, `ip`, `date`,
+ *     `boolean`, `geo_point`, `nested` or `object` field has no un-analyzed STRING form,
+ *     and a substring match against one is not imprecise, it is unanswerable.
+ *   * the MEMBERSHIP two (`in_cs`, `not_in_cs`) only when the base field is analyzed
+ *     `text`. Case-sensitivity is vacuous for a number or an instant, and the query engine
+ *     answers `in_cs` on those perfectly well.
+ *
+ * See `caseSensitiveSupport` in `src/validator.ts` for the predicate and for what the
+ * schema has to carry for this to fire at all.
+ *
+ * A WARNING and never an error, deliberately. The verdict is only as good as the schema
+ * the host supplied: a converter that flattens field names but drops multifields makes a
+ * perfectly translatable query look unanswerable, and a red squiggle over a query the
+ * cluster serves is the worse failure.
+ *
+ * Distinct from `TYPE_MISMATCH` because the objection is to the MAPPING, not the type --
+ * `text` is an accepted type for every `_cs` operator. The two can coincide on a
+ * non-string field, where the type is also wrong; the validator suppresses the softer
+ * `TYPE_MISMATCH` there rather than reporting both, so a consumer filtering by code sees
+ * one diagnostic per clause and the more accurate one.
+ */
+ | "UNANSWERABLE_MAPPING";
 export interface TqlValidationResult {
     valid: boolean;
     errors: TqlParseError[];
@@ -168,6 +282,16 @@ export interface TqlValidationOptions {
     allowMutators?: boolean;
     maxDepth?: number;
 }
+/**
+ * Whether a field can answer a case-SENSITIVE (`_cs`) operator, as far as a supplied schema shows.
+ *
+ * Three-valued because the engines' rule keys on the index MAPPING while this package is
+ * handed a flat name→type map: `"unknown"` is a real and common answer, distinct from
+ * `"supported"`, and conflating the two is what let the editor green-light a query the
+ * engines refuse (tql#206). Produced by `caseSensitiveSupport` in `src/validator.ts`, which
+ * documents the predicate and its two blind spots.
+ */
+export type CaseSensitiveSupport = "supported" | "unsupported" | "unknown";
 export type TqlFieldType = "text" | "keyword" | "long" | "integer" | "short" | "byte" | "double" | "float" | "half_float" | "scaled_float" | "unsigned_long" | "date" | "boolean" | "ip" | "nested" | "object" | "geo_point";
 export interface TqlCompletionItem {
     label: string;
@@ -264,6 +388,10 @@ export interface TqlInputEmits {
  * Reactive reference type for Vue computed properties.
  * This is a simplified type that matches Vue's ComputedRef interface
  * without requiring Vue as a direct dependency.
+ *
+ * @deprecated No longer used by `TqlInputExpose`: Vue unwraps refs on a
+ * component's exposed instance, so a template ref never saw a `.value` here.
+ * Kept exported so existing imports keep compiling.
  */
 export interface ReactiveRef<T> {
     readonly value: T;
@@ -277,12 +405,12 @@ export interface TqlInputExpose {
     getTokenAtPosition(pos: number): TqlToken | null;
     getCursorPosition(): number;
     setCursorPosition(pos: number): void;
-    /** Whether the current query is valid (no syntax errors). Access via .value */
-    isValid: ReactiveRef<boolean>;
-    /** Whether the current query has validation errors. Access via .value */
-    hasErrors: ReactiveRef<boolean>;
-    /** Array of current validation errors. Access via .value */
-    errors: ReactiveRef<TqlParseError[]>;
+    /** Whether the current query is valid (no syntax errors). */
+    readonly isValid: boolean;
+    /** Whether the current query has validation errors. */
+    readonly hasErrors: boolean;
+    /** Array of current validation errors. */
+    readonly errors: TqlParseError[];
 }
 export type ComplexityScore = "low" | "medium" | "high";
 export interface ComplexityWarning {

package/dist/src/validator.d.ts

@@ -1,4 +1,186 @@
-import { TqlParseError, TqlParseWarning, TqlValidationOptions, TqlValidationResult } from './types';
+import { CaseSensitiveSupport, TqlComparisonOperator, TqlFieldType, TqlParseError, TqlParseWarning, TqlValidationOptions, TqlValidationResult } from './types';
+/**
+ * Maximum regex pattern length TQL will compile, in characters (code points).
+ *
+ * A pattern longer than this is refused by every TQL runtime. It is flagged here
+ * -- in the editor, as the user types -- because the alternative is discovering
+ * it after the rule has been saved and deployed: before tql#185 the Python
+ * evaluator answered "no match" for an over-long pattern while the query parsed
+ * cleanly and reported health green, so a detection rule carrying one never
+ * fired and nothing anywhere said so.
+ *
+ * Mirrored by `MAX_REGEX_PATTERN_LENGTH` in `src/tql/regex_guard.py` and
+ * `tql/src/comparator.rs`. Changing it in one place only re-creates the
+ * divergence.
+ */
+export declare const MAX_REGEX_PATTERN_LENGTH = 1000;
+/**
+ * Every field type in the `TqlFieldType` union.
+ *
+ * Declared once so an operator that genuinely applies to everything says so by NAME rather
+ * than by a transcribed twelve-element list — and so a new field type cannot be added to the
+ * union while silently falling out of the operators it belongs to.
+ * `tests/collectionOperatorTypes.spec.ts` reads the union out of `src/types.ts` and asserts
+ * this array is exactly it, so a divergence is a red rather than a quiet narrowing.
+ */
+export declare const ALL_FIELD_TYPES: TqlFieldType[];
+/**
+ * Every numeric field type in the union — all nine widths, not the five that get typed out.
+ */
+export declare const NUMERIC_FIELD_TYPES: TqlFieldType[];
+/**
+ * The types an ORDERED comparison (`gt`/`gte`/`lt`/`lte`) is defined over.
+ *
+ * Numeric and date, plus `keyword`: both evaluators fall back to a lexicographic string
+ * comparison when neither side reads as a number, and Python's own validator lists all four
+ * operators in its `keyword_ops`. `text` is excluded on that same source's reasoning — a
+ * range over an analyzed field compares tokens, not the value the user typed.
+ */
+export declare const ORDERED_FIELD_TYPES: TqlFieldType[];
+/**
+ * The types `between` / `not_between` are defined over.
+ *
+ * `ORDERED_FIELD_TYPES` minus `keyword`. The four ordered operators and `between` are NOT
+ * the same set, and the difference is Python's, not this package's: `keyword_ops` in
+ * `_validate_simple_type_compatibility` lists `gt`/`gte`/`lt`/`lte` and excludes `between`.
+ * `tests/collectionAndNullSemantics.spec.ts` pins that exclusion against the Python source,
+ * so this constant self-retires if Python ever adds it.
+ */
+export declare const BETWEEN_FIELD_TYPES: TqlFieldType[];
+/**
+ * The case-SENSITIVE WHOLE-VALUE operators: every spelling the `TqlComparisonOperator` type
+ * admits.
+ *
+ * TWELVE spellings across both families, EIGHT operators. The engines' constants — same two
+ * names, in `tql/src/opensearch/field_mappings.rs` and
+ * `src/tql/opensearch_components/field_mapping.py` — carry eight, because the engines only
+ * ever see `not_contains_cs`.
+ *
+ * The four `!` members are unreachable from `validate()`: `normalizeOperator` in
+ * `src/parser.ts` maps every `!x` through `NEGATION_SYMBOL_OPERATORS` before an AST exists,
+ * and `TqlValidator` takes a query string and nothing else. They are kept because this array
+ * is exported public API and a host may match raw user-typed text against it — pinned by "the
+ * `!` spellings reach the validator normalised", which also goes red if normalisation is ever
+ * removed and the `!` forms become live.
+ *
+ * `tests/caseSensitiveOperatorMapping.spec.ts` reads both engine constants and asserts these
+ * arrays cover exactly them, family by family, once the `!` forms are normalised — so the two
+ * cannot drift in either direction, and neither can the SPLIT between the families, which is
+ * the part that actually changes the predicate.
+ */
+export declare const CASE_SENSITIVE_WHOLE_VALUE_OPERATORS: TqlComparisonOperator[];
+/**
+ * The case-SENSITIVE MEMBERSHIP operators, kept separate for the reason the engines keep them
+ * separate: their refusal predicate is NARROWER.
+ *
+ * `in_cs` is a keyword operator (an exact-match `terms` query), so it routes through a
+ * different branch of `get_field_for_operator` (Python) / `get_query_field` (Rust), and that branch refuses
+ * only when the base field is analyzed `text`. The whole-value six refuse whenever there is
+ * no un-analyzed form at all. Folding the two lists into one is what made
+ * `caseSensitiveSupport` wrong for six operators in this PR's first round.
+ */
+export declare const CASE_SENSITIVE_MEMBERSHIP_OPERATORS: TqlComparisonOperator[];
+/** Every spelling of every case-SENSITIVE operator — the union of the two families above. */
+export declare const CASE_SENSITIVE_OPERATORS: TqlComparisonOperator[];
+/**
+ * Whether a field offers a CASE-PRESERVING form, as far as the supplied schema shows.
+ *
+ * This is the field half of the engines' rule, on its own because the two `_cs` operator
+ * families consume it differently (see `caseSensitiveSupport`, which is the function you
+ * probably want).
+ *
+ *   * `"present"` — the field itself is `keyword`, or it has a `keyword` subfield. One whole
+ *     value, one indexed term, case intact.
+ *   * `"absent"` — no such form. That covers analyzed `text` with no `keyword` sibling AND
+ *     every non-string type: a `long`, `ip`, `date` or `boolean` field has no un-analyzed
+ *     STRING form either. Whether that matters depends on the operator, which is why this
+ *     function does not decide it.
+ *   * `"unknown"` — no `fieldTypes` was supplied, or this field is not in it.
+ *
+ * Mirrors `FieldMappings::unanalyzed_form` (Rust) and `FieldMapping.unanalyzed_field`
+ * (Python) as closely as a flat name→type map allows. Two documented divergences, both of
+ * which fail quiet — see `caseSensitiveSupport`.
+ *
+ * ## The sibling test is on TYPE, not on the name `.keyword`
+ *
+ * Both engines scan a field's declared subfields for one whose TYPE is `keyword` (Rust:
+ * `subfield_of(field, |t| *t == FieldType::Keyword)`; Python: `keyword_field`, set for any
+ * subfield with `"type": "keyword"`). A multifield named `.raw` or `.kw` answers exactly as
+ * well as one named `.keyword`, and hard-coding the name would report `"absent"` on a working
+ * mapping. So this walks the map for `${field}.` prefixed entries and looks at their type.
+ *
+ * ## One level down, matching the engines
+ *
+ * A subfield is a DIRECT child: both engines read a declared `subfields` map, so
+ * `f.sub.deep` is not a subfield of `f` to either of them. Scanning descendants at any depth
+ * would report `"present"` for a mapping the engines refuse.
+ */
+export declare function casePreservingForm(field: string, fieldTypes?: Record<string, TqlFieldType>): "present" | "absent" | "unknown";
+/**
+ * Whether a field can answer a case-SENSITIVE operator, as far as the supplied schema shows.
+ *
+ * Three-valued on purpose. The engines' rule keys on the MAPPING and this package is handed a
+ * flat name→type map, so there are genuinely three answers and collapsing them to two is how
+ * this ended up unimplemented for a release (tql#206):
+ *
+ *   * `"unsupported"` — both engines raise (`TQLTypeError` / `OpenSearchError::TypeError`)
+ *     for this field-and-operator pair. That is now true of every type, which it was not
+ *     when this check was written: Rust's `parse_field_type` had no arm for `geo_point` or
+ *     `unsigned_long`, dropped such a field from its mappings, and permitted the query —
+ *     emitting a `wildcard` that could never match. Fixed in tql#210, in this same PR, and
+ *     `no_field_type_is_silently_dropped` in
+ *     `tql/tests/opensearch_case_sensitive_unanswerable.rs` holds the property for type
+ *     names neither engine lists, not just for the two that were noticed.
+ *   * `"supported"` — the schema shows nothing that would stop the engines translating it.
+ *   * `"unknown"` — no `fieldTypes` was supplied, or this field is not in it. Nothing is
+ *     claimed and no diagnostic should be produced.
+ *
+ * ## Why the OPERATOR is a parameter and not an afterthought
+ *
+ * The two `_cs` families do NOT share a predicate, and a field-only version of this function
+ * got it wrong for six of the eight operators before review caught it:
+ *
+ *   * **Whole-value** (`contains_cs`, `startswith_cs`, `endswith_cs` + negations) refuse
+ *     whenever there is no un-analyzed form at all — `field_mapping.py`'s
+ *     `if self.unanalyzed_field is None and operator in CASE_SENSITIVE_WHOLE_VALUE_OPERATORS`,
+ *     and the unconditional `if CASE_SENSITIVE_WHOLE_VALUE_OPERATORS.contains(&operator)` in
+ *     `field_mappings.rs`. Neither is gated on the base type. Measured against the Python
+ *     engine at `{"f": {"type": t}}`: `contains_cs`, `startswith_cs` and `endswith_cs` all
+ *     raise for `long`, `ip`, `date` and `boolean`.
+ *   * **Membership** (`in_cs`, `not_in_cs`) refuse only when the base field is analyzed
+ *     `text` — `operator in CASE_SENSITIVE_MEMBERSHIP_OPERATORS and
+ *     self.field_types.get(self.base_field_name) == "text"`, and its Rust twin. The same
+ *     measurement: `f in_cs ['a']` translates to `{"terms": …}` for all four of those types,
+ *     because case-sensitivity is vacuous for a number, an address, an instant or a flag.
+ *
+ * So "no case-preserving form" is the whole answer for six operators and half of it for two.
+ * `test_a_non_text_field_without_a_keyword_form_is_not_caught` pins the membership half only;
+ * reading its NAME as covering all eight is exactly how the field-only version passed review
+ * of its own tests.
+ *
+ * ## Two blind spots, both of which fail SILENT rather than loud
+ *
+ * 1. **A `wildcard` sibling reads as absent.** The engines accept `wildcard` as a
+ *    case-preserving form (`FieldType::is_unanalyzed_string`), but `wildcard` is not a member
+ *    of `TqlFieldType`, so a host cannot express it and this cannot see it.
+ * 2. **An object CHILD is indistinguishable from a multifield.** `os` (`text`) beside
+ *    `os.name` (`keyword`) is read as case-preserving though `os.name` is a sibling field,
+ *    not a subfield of `os`. A flat map carries no way to tell them apart.
+ *
+ * Blind spot 2 under-reports (a real refusal goes unwarned — no worse than before this
+ * existed), and blind spot 1 over-reports, which is the whole reason the caller emits a
+ * WARNING and not an error. Neither justifies staying silent in the ordinary ECS case, which
+ * is the case this answers.
+ *
+ * @param field - the field name as written in the query
+ * @param operator - the `_cs` operator being applied. A non-`_cs` operator always returns
+ *   `"supported"`: this function answers one rule and does not stand in for the type tables.
+ * @param fieldTypes - the flat schema, exactly as passed in `TqlValidationOptions.fieldTypes`.
+ *   For this to return anything but `"unknown"` it must contain the field; for it to
+ *   distinguish the two `text` shapes it must ALSO contain the multifield entries
+ *   (`message.keyword`), which is what an index-mapping flattener naturally produces.
+ */
+export declare function caseSensitiveSupport(field: string, operator: TqlComparisonOperator, fieldTypes?: Record<string, TqlFieldType>): CaseSensitiveSupport;
 export declare class TqlValidator {
     private options;
     private errors;
@@ -12,6 +194,58 @@ export declare class TqlValidator {
      * Validate an expression recursively
      */
     private validateExpression;
+    /**
+     * `f any ['a','b']` is ill-typed. Say so, and name `in`.
+     *
+     * ## The rule, as both engines implement it
+     *
+     * `any` / `none` apply a comparison to each ELEMENT of an array-valued field. The operand
+     * is therefore a SCALAR: `f any 'admin'` asks whether some element equals `'admin'`. A
+     * LIST operand asks whether some single element equals the whole two-element list, which
+     * no scalar element can. `in` is already the membership operator, and is what the author
+     * meant.
+     *
+     * Both engines now refuse it -- `ab55587` in `tql/src/opensearch/query_builder.rs`
+     * (`build_collection_op`) and `_refuse_list_operand` in
+     * `src/tql/opensearch_components/query_converter.py` -- raising a type error whose
+     * `valid_operators` are `in` / `not in`. Before that it emitted `{"term": {"f": [..]}}`,
+     * which OpenSearch answers with HTTP 400 `[term] query does not support array of values`,
+     * failing the WHOLE search including every unrelated clause; the intermediate fix emitted
+     * `match_none`, which executed cleanly and excluded nothing, silently.
+     *
+     * ## Three arities, and only the middle one is new
+     *
+     * The engines do NOT test `is_array`. They unwrap a single-element list FIRST
+     * (`unwrap_single` in Rust, `len(value) == 1` in Python) and refuse only what is still a
+     * list. Measured against the live Python translator at `ab55587`:
+     *
+     * | Query              | Python translator                                    |
+     * |--------------------|------------------------------------------------------|
+     * | `f any 'admin'`    | `{"term": {"f": "admin"}}`                            |
+     * | `f any ['a']`      | `{"term": {"f": "a"}}` -- unwrapped, NOT refused      |
+     * | `f any ['a','b']`  | `TQLTypeError`, valid operators `in`, `not in`        |
+     *
+     * A naive `Array.isArray(value)` check would flag `f any ['a']`, which both engines
+     * translate perfectly well -- a red squiggle over a working query, which is the defect
+     * this parser keeps being fixed for. Hence `length >= 2`, and hence the two arities are
+     * tested separately in `tests/collectionListOperand.spec.ts`.
+     *
+     * The empty list is not handled here: `f any []` is already an `INVALID_VALUE` error from
+     * the parser (`tests/emptyValueList.spec.ts`), and Python does not even parse it
+     * (`TQLSyntaxError`). Reporting it twice would be noise.
+     *
+     * ## Why `ALL` is excluded, and why that is not an oversight
+     *
+     * `all` / `not_all` are answered by a Painless script that compares each element to
+     * `params.value`. A list operand there emits valid DSL that matches nothing -- which is
+     * what both in-memory evaluators also answer -- so both engines dispatch `all` BEFORE the
+     * refusal and leave it untouched. `f all ['a','b']` translating cleanly is a pinned
+     * negative case here, not a gap.
+     *
+     * Negation is irrelevant: in both engines the array check precedes the quantifier wrapper,
+     * so `not any` / `not none` refuse on the same footing as the positive spellings.
+     */
+    private validateCollectionOperand;
     /**
      * Validate a comparison expression
      */