@tellaro/tql 2.0.0 → 3.0.0

package/dist/index.js

@@ -1,73 +1,78 @@
-import { AGGREGATION_FUNCTIONS as r, BOOLEAN_PREDICATE_MUTATORS as i, BOOLEAN_PREDICATE_MUTATOR_SET as o, COLLECTION_OPERATORS as T, COMPARISON_OPERATORS as a, KEYWORDS as l, LOGICAL_OPERATORS as n, MUTATORS as g, NEGATION_SYMBOL_OPERATORS as s, SYMBOL_OPERATORS as O, TYPE_HINTS as m, TqlTokenizer as A, VISUALIZATION_TYPES as c, findPreviousToken as E, findTokenAtPosition as S, findTokenBefore as p, findTokensInRange as C, tokenizeTql as d, tokenizeTqlNoWhitespace as f } from "./src/tokenizer.js";
-import { TqlParser as h, formatParseError as P, getTqlErrors as _, isValidTql as N, parseTql as x } from "./src/parser.js";
-import { MAX_REGEX_PATTERN_LENGTH as I, TqlValidator as y, formatValidationResult as q, getTqlIssues as M, isValidTqlSyntax as u, validateTql as z } from "./src/validator.js";
-import { getCompletionTriggerCharacters as F, getCompletions as G, getWordAtPosition as U, shouldTriggerCompletion as V } from "./src/completionProvider.js";
-import { findClosestMatch as B, fuzzyFilter as D, fuzzyMatch as Y, highlightMatch as H, levenshteinDistance as W } from "./src/fuzzyMatcher.js";
-import { SchemaCache as X, createSchemaCache as b, getCachedField as K, getCachedFieldNames as Q, getCachedFieldType as Z, getSchemaCache as j } from "./src/schemaCache.js";
-import { ComplexityAnalyzer as $, analyzeComplexity as ee, getComplexityMetrics as te, getComplexityWarnings as re, isHighComplexity as ie } from "./src/complexityAnalyzer.js";
-import { SemanticPreview as Te, flattenLogicTree as ae, formatLogicTreeAscii as le, formatLogicTreeNode as ne, generatePreview as ge, getFieldUsage as se, getLogicTree as Oe, getLogicTreeDepth as me, getOperatorSummary as Ae, getUniqueFields as ce } from "./src/semanticPreview.js";
-import { buildStatsQuery as Se, parseVizHintString as pe } from "./src/builder.js";
+import { AGGREGATION_FUNCTIONS as r, BOOLEAN_PREDICATE_MUTATORS as i, BOOLEAN_PREDICATE_MUTATOR_SET as o, COLLECTION_OPERATORS as T, COMPARISON_OPERATORS as a, KEYWORDS as E, LOGICAL_OPERATORS as l, MUTATORS as S, NEGATION_SYMBOL_OPERATORS as O, SYMBOL_OPERATORS as n, TYPE_HINTS as s, TqlTokenizer as g, VISUALIZATION_TYPES as A, findPreviousToken as m, findTokenAtPosition as R, findTokenBefore as c, findTokensInRange as C, tokenizeTql as _, tokenizeTqlNoWhitespace as p } from "./src/tokenizer.js";
+import { TqlParser as d, formatParseError as f, getTqlErrors as h, isValidTql as I, parseTql as N } from "./src/parser.js";
+import { CASE_SENSITIVE_MEMBERSHIP_OPERATORS as x, CASE_SENSITIVE_OPERATORS as y, CASE_SENSITIVE_WHOLE_VALUE_OPERATORS as M, MAX_REGEX_PATTERN_LENGTH as q, TqlValidator as u, casePreservingForm as z, caseSensitiveSupport as V, formatValidationResult as F, getTqlIssues as U, isValidTqlSyntax as k, validateTql as v } from "./src/validator.js";
+import { getCompletionTriggerCharacters as B, getCompletions as H, getWordAtPosition as D, shouldTriggerCompletion as W } from "./src/completionProvider.js";
+import { findClosestMatch as w, fuzzyFilter as X, fuzzyMatch as b, highlightMatch as K, levenshteinDistance as Q } from "./src/fuzzyMatcher.js";
+import { SchemaCache as j, createSchemaCache as J, getCachedField as $, getCachedFieldNames as ee, getCachedFieldType as te, getSchemaCache as re } from "./src/schemaCache.js";
+import { ComplexityAnalyzer as oe, analyzeComplexity as Te, getComplexityMetrics as ae, getComplexityWarnings as Ee, isHighComplexity as le } from "./src/complexityAnalyzer.js";
+import { SemanticPreview as Oe, flattenLogicTree as ne, formatLogicTreeAscii as se, formatLogicTreeNode as ge, generatePreview as Ae, getFieldUsage as me, getLogicTree as Re, getLogicTreeDepth as ce, getOperatorSummary as Ce, getUniqueFields as _e } from "./src/semanticPreview.js";
+import { buildStatsQuery as Pe, parseVizHintString as de } from "./src/builder.js";
 export {
   r as AGGREGATION_FUNCTIONS,
   i as BOOLEAN_PREDICATE_MUTATORS,
   o as BOOLEAN_PREDICATE_MUTATOR_SET,
+  x as CASE_SENSITIVE_MEMBERSHIP_OPERATORS,
+  y as CASE_SENSITIVE_OPERATORS,
+  M as CASE_SENSITIVE_WHOLE_VALUE_OPERATORS,
   T as COLLECTION_OPERATORS,
   a as COMPARISON_OPERATORS,
-  $ as ComplexityAnalyzer,
-  l as KEYWORDS,
-  n as LOGICAL_OPERATORS,
-  I as MAX_REGEX_PATTERN_LENGTH,
-  g as MUTATORS,
-  s as NEGATION_SYMBOL_OPERATORS,
-  O as SYMBOL_OPERATORS,
-  X as SchemaCache,
-  Te as SemanticPreview,
-  m as TYPE_HINTS,
-  h as TqlParser,
-  A as TqlTokenizer,
-  y as TqlValidator,
-  c as VISUALIZATION_TYPES,
-  ee as analyzeComplexity,
-  Se as buildStatsQuery,
-  b as createSchemaCache,
-  B as findClosestMatch,
-  E as findPreviousToken,
-  S as findTokenAtPosition,
-  p as findTokenBefore,
+  oe as ComplexityAnalyzer,
+  E as KEYWORDS,
+  l as LOGICAL_OPERATORS,
+  q as MAX_REGEX_PATTERN_LENGTH,
+  S as MUTATORS,
+  O as NEGATION_SYMBOL_OPERATORS,
+  n as SYMBOL_OPERATORS,
+  j as SchemaCache,
+  Oe as SemanticPreview,
+  s as TYPE_HINTS,
+  d as TqlParser,
+  g as TqlTokenizer,
+  u as TqlValidator,
+  A as VISUALIZATION_TYPES,
+  Te as analyzeComplexity,
+  Pe as buildStatsQuery,
+  z as casePreservingForm,
+  V as caseSensitiveSupport,
+  J as createSchemaCache,
+  w as findClosestMatch,
+  m as findPreviousToken,
+  R as findTokenAtPosition,
+  c as findTokenBefore,
   C as findTokensInRange,
-  ae as flattenLogicTree,
-  le as formatLogicTreeAscii,
-  ne as formatLogicTreeNode,
-  P as formatParseError,
-  q as formatValidationResult,
-  D as fuzzyFilter,
-  Y as fuzzyMatch,
-  ge as generatePreview,
-  K as getCachedField,
-  Q as getCachedFieldNames,
-  Z as getCachedFieldType,
-  F as getCompletionTriggerCharacters,
-  G as getCompletions,
-  te as getComplexityMetrics,
-  re as getComplexityWarnings,
-  se as getFieldUsage,
-  Oe as getLogicTree,
-  me as getLogicTreeDepth,
-  Ae as getOperatorSummary,
-  j as getSchemaCache,
-  _ as getTqlErrors,
-  M as getTqlIssues,
-  ce as getUniqueFields,
-  U as getWordAtPosition,
-  H as highlightMatch,
-  ie as isHighComplexity,
-  N as isValidTql,
-  u as isValidTqlSyntax,
-  W as levenshteinDistance,
-  x as parseTql,
-  pe as parseVizHintString,
-  V as shouldTriggerCompletion,
-  d as tokenizeTql,
-  f as tokenizeTqlNoWhitespace,
-  z as validateTql
+  ne as flattenLogicTree,
+  se as formatLogicTreeAscii,
+  ge as formatLogicTreeNode,
+  f as formatParseError,
+  F as formatValidationResult,
+  X as fuzzyFilter,
+  b as fuzzyMatch,
+  Ae as generatePreview,
+  $ as getCachedField,
+  ee as getCachedFieldNames,
+  te as getCachedFieldType,
+  B as getCompletionTriggerCharacters,
+  H as getCompletions,
+  ae as getComplexityMetrics,
+  Ee as getComplexityWarnings,
+  me as getFieldUsage,
+  Re as getLogicTree,
+  ce as getLogicTreeDepth,
+  Ce as getOperatorSummary,
+  re as getSchemaCache,
+  h as getTqlErrors,
+  U as getTqlIssues,
+  _e as getUniqueFields,
+  D as getWordAtPosition,
+  K as highlightMatch,
+  le as isHighComplexity,
+  I as isValidTql,
+  k as isValidTqlSyntax,
+  Q as levenshteinDistance,
+  N as parseTql,
+  de as parseVizHintString,
+  W as shouldTriggerCompletion,
+  _ as tokenizeTql,
+  p as tokenizeTqlNoWhitespace,
+  v as validateTql
 };

package/dist/src/index.d.ts

@@ -6,10 +6,10 @@
  *
  * @packageDocumentation
  */
-export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, TqlGroupExpression, TqlLiteral, TqlFieldReference, TqlComparisonOperator, TqlLogicalOperator, TqlCollectionOperator, TqlMutator, TqlAggregationFunction, TqlTypeHint, TqlVisualizationType, TqlVizParams, TqlVizHint, TqlParseResult, TqlParseError, TqlParseWarning, TqlErrorCode, TqlWarningCode, TqlValidationResult, TqlValidationOptions, TqlFieldType, TqlCompletionItem, TqlCompletionKind, TqlCompletionContext, TqlCompletionOptions, TqlFieldSchema, TqlSnippet, TqlInputProps, TqlInputEmits, TqlInputExpose } from './types';
+export type { TqlToken, TqlTokenType, TqlExpression, TqlBinaryExpression, TqlUnaryExpression, TqlComparisonExpression, TqlCollectionExpression, TqlMutatorExpression, TqlAggregationExpression, TqlStatsExpression, TqlGroupExpression, TqlLiteral, TqlFieldReference, TqlComparisonOperator, TqlLogicalOperator, TqlCollectionOperator, TqlMutator, TqlAggregationFunction, TqlTypeHint, TqlVisualizationType, TqlVizParams, TqlVizHint, TqlParseResult, TqlParseError, TqlParseWarning, TqlErrorCode, TqlWarningCode, TqlValidationResult, TqlValidationOptions, TqlFieldType, CaseSensitiveSupport, TqlCompletionItem, TqlCompletionKind, TqlCompletionContext, TqlCompletionOptions, TqlFieldSchema, TqlSnippet, TqlInputProps, TqlInputEmits, TqlInputExpose } from './types';
 export { TqlTokenizer, tokenizeTql, tokenizeTqlNoWhitespace, findTokenAtPosition, findTokensInRange, findTokenBefore, findPreviousToken, COMPARISON_OPERATORS, SYMBOL_OPERATORS, NEGATION_SYMBOL_OPERATORS, LOGICAL_OPERATORS, COLLECTION_OPERATORS, MUTATORS, BOOLEAN_PREDICATE_MUTATORS, BOOLEAN_PREDICATE_MUTATOR_SET, AGGREGATION_FUNCTIONS, TYPE_HINTS, VISUALIZATION_TYPES, KEYWORDS } from './tokenizer';
 export { TqlParser, parseTql, isValidTql, getTqlErrors, formatParseError } from './parser';
-export { TqlValidator, validateTql, isValidTqlSyntax, getTqlIssues, formatValidationResult, MAX_REGEX_PATTERN_LENGTH } from './validator';
+export { TqlValidator, validateTql, isValidTqlSyntax, getTqlIssues, formatValidationResult, caseSensitiveSupport, casePreservingForm, CASE_SENSITIVE_OPERATORS, CASE_SENSITIVE_WHOLE_VALUE_OPERATORS, CASE_SENSITIVE_MEMBERSHIP_OPERATORS, MAX_REGEX_PATTERN_LENGTH } from './validator';
 export { getCompletions, getWordAtPosition, getCompletionTriggerCharacters, shouldTriggerCompletion } from './completionProvider';
 export { fuzzyMatch, levenshteinDistance, findClosestMatch, fuzzyFilter, highlightMatch, type FuzzyMatchResult, type FuzzyMatchOptions } from './fuzzyMatcher';
 export { SchemaCache, getSchemaCache, createSchemaCache, getCachedFieldNames, getCachedFieldType, getCachedField, type CachedSchema } from './schemaCache';

package/dist/src/types.d.ts

@@ -236,7 +236,39 @@ export type TqlWarningCode = "UNKNOWN_FIELD" | "TYPE_MISMATCH" | "DEPRECATED_OPE
  * 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";
+ | "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[];
@@ -250,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;
@@ -346,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;
@@ -359,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,4 @@
-import { TqlFieldType, 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).
  *
@@ -47,6 +47,140 @@ export declare const ORDERED_FIELD_TYPES: TqlFieldType[];
  * 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;