@rippling/rippling-sdk 0.2.0-alpha.85 → 0.2.0-alpha.87

package/src/core/platform/custom-objects/typed-rql.ts

@@ -0,0 +1,1273 @@
+import type { AnyCustomObjectDefinition, FieldNames } from './types';
+
+const STANDARD_TYPED_RQL_FIELDS = [
+  'id',
+  'name',
+  'created_at',
+  'updated_at',
+  'system_updated_at',
+  'external_id',
+  'owner_role',
+  'created_by',
+  'last_modified_by',
+] as const;
+
+const STANDARD_LOOKUP_FIELDS = new Set(['owner_role', 'created_by', 'last_modified_by']);
+
+/**
+ * Standard field-name strings accepted by the parsed RQL helper.
+ *
+ * @typeParam TDefinition - Object definition whose standard record fields should be exposed.
+ */
+export type ParsedRqlStandardFieldName<TDefinition extends AnyCustomObjectDefinition> =
+  (typeof STANDARD_TYPED_RQL_FIELDS)[number];
+
+/**
+ * Field-name strings accepted by the parsed RQL helper.
+ *
+ * @typeParam TDefinition - Object definition whose field-name union should be exposed.
+ */
+export type ParsedRqlFieldName<TDefinition extends AnyCustomObjectDefinition> =
+  | ParsedRqlStandardFieldName<TDefinition>
+  | FieldNames<TDefinition>;
+
+/** Whitespace characters trimmed by the type-level parsed RQL validator. */
+type RqlWhitespace = ' ' | '\n' | '\t' | '\r';
+
+/** Removes leading and trailing whitespace from a string literal. */
+type TrimRql<T extends string> =
+  T extends `${RqlWhitespace}${infer Rest}` ? TrimRql<Rest>
+  : T extends `${infer Rest}${RqlWhitespace}` ? TrimRql<Rest>
+  : T;
+
+/** Appends one value to a tuple used as a depth counter. */
+type PushDepth<TDepth extends readonly unknown[]> = [...TDepth, 1];
+
+/** Removes one value from a tuple used as a depth counter. */
+type PopDepth<TDepth extends readonly unknown[]> = TDepth extends [...infer Rest, unknown] ? Rest : [];
+
+/**
+ * Returns true when the outermost `(` and `)` pair actually wraps the full expression.
+ *
+ * This is stricter than a raw open/close count. For example, `(a) AND (b)` has
+ * balanced parentheses but is not globally wrapped by its first `(` and last `)`.
+ */
+type OuterParensWrapExpression<
+  TSource extends string,
+  TParenDepth extends readonly unknown[] = [1],
+  TBracketDepth extends readonly unknown[] = [],
+  TInString extends boolean = false,
+> = TSource extends '' ?
+  TParenDepth['length'] extends 1 ?
+    true
+  : false
+: TInString extends true ?
+  TSource extends `\\${infer _Escaped}${infer Rest}` ?
+    OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, true>
+  : TSource extends `'${infer Rest}` ? OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, false>
+  : TSource extends `${infer _Char}${infer Rest}` ?
+    OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, true>
+  : false
+: TSource extends `'${infer Rest}` ? OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, true>
+: TSource extends `[${infer Rest}` ?
+  OuterParensWrapExpression<Rest, TParenDepth, PushDepth<TBracketDepth>, false>
+: TSource extends `]${infer Rest}` ?
+  OuterParensWrapExpression<Rest, TParenDepth, PopDepth<TBracketDepth>, false>
+: TBracketDepth['length'] extends 0 ?
+  TSource extends `(${infer Rest}` ?
+    OuterParensWrapExpression<Rest, PushDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `)${infer Rest}` ?
+    TParenDepth['length'] extends 1 ?
+      false
+    : OuterParensWrapExpression<Rest, PopDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `${infer _Char}${infer Rest}` ?
+    OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, false>
+  : false
+: TSource extends `(${infer Rest}` ? OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, false>
+: TSource extends `)${infer Rest}` ? OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, false>
+: TSource extends `${infer _Char}${infer Rest}` ?
+  OuterParensWrapExpression<Rest, TParenDepth, TBracketDepth, false>
+: false;
+
+/** Removes one pair of outer parentheses when they wrap the full expression. */
+type StripOuterParens<T extends string> =
+  T extends `(${infer Inner})` ?
+    OuterParensWrapExpression<Inner> extends true ?
+      StripOuterParens<TrimRql<Inner>>
+    : T
+  : T;
+
+/** Utility for splitting an expression by a top-level delimiter while respecting strings, brackets, and parentheses. */
+type SplitTopLevel<
+  TSource extends string,
+  TDelimiter extends string,
+  TCurrent extends string = '',
+  TParts extends readonly string[] = [],
+  TParenDepth extends readonly unknown[] = [],
+  TBracketDepth extends readonly unknown[] = [],
+  TInString extends boolean = false,
+> = TSource extends '' ? [...TParts, TrimRql<TCurrent>]
+: TInString extends true ?
+  TSource extends `\\${infer Escaped}${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}\\${Escaped}`, TParts, TParenDepth, TBracketDepth, true>
+  : TSource extends `'${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, false>
+  : TSource extends `${infer Char}${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, true>
+  : [...TParts, TrimRql<TCurrent>]
+: TParenDepth['length'] extends 0 ?
+  TBracketDepth['length'] extends 0 ?
+    TSource extends `${TDelimiter}${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, '', [...TParts, TrimRql<TCurrent>], TParenDepth, TBracketDepth, false>
+    : TSource extends `'${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+    : TSource extends `(${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+    : TSource extends `)${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+    : TSource extends `[${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+    : TSource extends `]${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+    : TSource extends `${infer Char}${infer Rest}` ?
+      SplitTopLevel<Rest, TDelimiter, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+    : [...TParts, TrimRql<TCurrent>]
+  : TSource extends `'${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+  : TSource extends `(${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `)${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `[${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+  : TSource extends `]${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+  : TSource extends `${infer Char}${infer Rest}` ?
+    SplitTopLevel<Rest, TDelimiter, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+  : [...TParts, TrimRql<TCurrent>]
+: TSource extends `'${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+: TSource extends `(${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+: TSource extends `)${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+: TSource extends `[${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+: TSource extends `]${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+: TSource extends `${infer Char}${infer Rest}` ?
+  SplitTopLevel<Rest, TDelimiter, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+: [...TParts, TrimRql<TCurrent>];
+
+/** Joins string parts using one delimiter. */
+type JoinWithDelimiter<TParts extends readonly string[], TDelimiter extends string> = TParts extends [] ? ''
+: TParts extends [infer TOnly extends string] ? TOnly
+: TParts extends [infer THead extends string, ...infer TRest extends string[]] ?
+  `${THead}${TDelimiter}${JoinWithDelimiter<TRest, TDelimiter>}`
+: string;
+
+/** Parsed logical operator tokens recognized by the type-level validator. */
+type ParsedRqlLogicalOperator = 'AND' | 'OR';
+
+/** Parsed logical-expression pieces after one top-level scan. */
+type ParsedLogicalMatch<
+  TOperator extends ParsedRqlLogicalOperator = ParsedRqlLogicalOperator,
+  TParts extends readonly string[] = readonly string[],
+> = readonly [operator: TOperator, parts: TParts];
+
+/** Attempts to parse one logical expression in a single top-level scan while preserving OR-before-AND splitting semantics. */
+type ParseLogicalMatch<
+  TSource extends string,
+  TMode extends ParsedRqlLogicalOperator | 'none' = 'none',
+  TCurrent extends string = '',
+  TParts extends readonly string[] = [],
+  TParenDepth extends readonly unknown[] = [],
+  TBracketDepth extends readonly unknown[] = [],
+  TInString extends boolean = false,
+> = TSource extends '' ?
+  TMode extends ParsedRqlLogicalOperator ?
+    ParsedLogicalMatch<TMode, [...TParts, TrimRql<TCurrent>]>
+  : never
+: TInString extends true ?
+  TSource extends `\\${infer Escaped}${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}\\${Escaped}`, TParts, TParenDepth, TBracketDepth, true>
+  : TSource extends `'${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, false>
+  : TSource extends `${infer Char}${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, true>
+  : never
+: TParenDepth['length'] extends 0 ?
+  TBracketDepth['length'] extends 0 ?
+    TSource extends ` OR ${infer Rest}` ?
+      TMode extends 'OR' ?
+        ParseLogicalMatch<Rest, 'OR', '', [...TParts, TrimRql<TCurrent>], TParenDepth, TBracketDepth, false>
+      : TMode extends 'AND' ?
+        ParseLogicalMatch<
+          Rest,
+          'OR',
+          '',
+          [JoinWithDelimiter<[...TParts, TrimRql<TCurrent>], ' AND '>],
+          TParenDepth,
+          TBracketDepth,
+          false
+        >
+      : ParseLogicalMatch<Rest, 'OR', '', [TrimRql<TCurrent>], TParenDepth, TBracketDepth, false>
+    : TSource extends ` AND ${infer Rest}` ?
+      TMode extends 'OR' ?
+        ParseLogicalMatch<Rest, 'OR', `${TCurrent} AND `, TParts, TParenDepth, TBracketDepth, false>
+      : TMode extends 'AND' ?
+        ParseLogicalMatch<Rest, 'AND', '', [...TParts, TrimRql<TCurrent>], TParenDepth, TBracketDepth, false>
+      : ParseLogicalMatch<Rest, 'AND', '', [TrimRql<TCurrent>], TParenDepth, TBracketDepth, false>
+    : TSource extends `'${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+    : TSource extends `(${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+    : TSource extends `)${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+    : TSource extends `[${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+    : TSource extends `]${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+    : TSource extends `${infer Char}${infer Rest}` ?
+      ParseLogicalMatch<Rest, TMode, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+    : never
+  : TSource extends `'${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+  : TSource extends `(${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `)${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+  : TSource extends `[${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+  : TSource extends `]${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+  : TSource extends `${infer Char}${infer Rest}` ?
+    ParseLogicalMatch<Rest, TMode, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+  : never
+: TSource extends `'${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent}'`, TParts, TParenDepth, TBracketDepth, true>
+: TSource extends `(${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent}(`, TParts, PushDepth<TParenDepth>, TBracketDepth, false>
+: TSource extends `)${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent})`, TParts, PopDepth<TParenDepth>, TBracketDepth, false>
+: TSource extends `[${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent}[`, TParts, TParenDepth, PushDepth<TBracketDepth>, false>
+: TSource extends `]${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent}]`, TParts, TParenDepth, PopDepth<TBracketDepth>, false>
+: TSource extends `${infer Char}${infer Rest}` ?
+  ParseLogicalMatch<Rest, TMode, `${TCurrent}${Char}`, TParts, TParenDepth, TBracketDepth, false>
+: never;
+
+/** Normalizes one candidate parsed-RQL expression before boolean/comparison validation. */
+type NormalizeParsedRqlExpression<TExpression extends string> = StripOuterParens<TrimRql<TExpression>>;
+
+/** Returns the first validation error from the provided expression parts. */
+type ValidateEveryExpression<
+  TDefinition extends AnyCustomObjectDefinition,
+  TParts extends readonly string[],
+> = TParts extends [infer Next extends string, ...infer Rest extends string[]] ?
+  ValidateParsedRqlExpression<TDefinition, Next> extends infer TResult ?
+    TResult extends true ?
+      ValidateEveryExpression<TDefinition, Rest>
+    : TResult
+  : never
+: true;
+
+/** Standard parsed-RQL field category. */
+type StandardFieldCategory<TFieldName extends string> =
+  TFieldName extends 'owner_role' | 'created_by' | 'last_modified_by' ? 'lookup' : 'string';
+
+/** Category lookup for one custom-field kind. */
+type ParsedRqlCategoryByKind<TKind extends string> =
+  TKind extends (
+    | 'text'
+    | 'long-text'
+    | 'email'
+    | 'url'
+    | 'phone'
+    | 'date'
+    | 'datetime'
+    | 'time'
+    | 'radio'
+    | 'formula-text'
+    | 'formula-date'
+    | 'formula-url'
+  ) ?
+    'string'
+  : TKind extends (
+    'number' | 'currency' | 'percentage' | 'formula-number' | 'formula-currency' | 'formula-percentage'
+  ) ?
+    'number'
+  : TKind extends 'boolean' | 'formula-boolean' ? 'boolean'
+  : TKind extends 'lookup' | 'parent-child' ? 'lookup'
+  : 'unsupported';
+
+/** Cached custom-field category map for one object definition. */
+type ParsedRqlCustomFieldCategoryMap<TDefinition extends AnyCustomObjectDefinition> = {
+  readonly [K in FieldNames<TDefinition>]: TDefinition['fields'][K] extends (
+    { kind: infer TKind extends string }
+  ) ?
+    ParsedRqlCategoryByKind<TKind>
+  : 'unsupported';
+};
+
+/** Cached full field-category map for one object definition. */
+type ParsedRqlFieldCategoryMap<TDefinition extends AnyCustomObjectDefinition> = {
+  readonly [K in ParsedRqlStandardFieldName<TDefinition>]: StandardFieldCategory<K>;
+} & ParsedRqlCustomFieldCategoryMap<TDefinition>;
+
+/** Field category used for operator and literal validation. */
+type ParsedRqlFieldCategory<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends string,
+> = TFieldName extends keyof ParsedRqlFieldCategoryMap<TDefinition> ?
+  ParsedRqlFieldCategoryMap<TDefinition>[TFieldName]
+: 'missing';
+
+/** Human-readable field-category names used in compile-time diagnostics. */
+type ParsedRqlFieldCategoryLabel<TCategory extends string> =
+  TCategory extends 'string' ? "a quoted string literal such as 'Ada'"
+  : TCategory extends 'number' ? 'a numeric literal such as 14'
+  : TCategory extends 'boolean' ? 'a boolean literal: True or False'
+  : TCategory extends 'lookup' ? "a quoted record-id string such as 'rec_123'"
+  : 'a supported literal value';
+
+/** Formats a consistent compile-time error for one field/operator/literal mismatch. */
+type ParsedRqlLiteralError<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+> = `RQL field "${TFieldName}" with operator "${TOperator}" expects ${ParsedRqlFieldCategoryLabel<TCategory>}; received ${TLiteral}.`;
+
+/** Formats a compile-time error for unsupported field categories. */
+type ParsedRqlUnsupportedFieldError<
+  TFieldName extends string,
+  TCategory extends string,
+> = `RQL field "${TFieldName}" uses an unsupported field category (${TCategory}) in typedRql(...).`;
+
+/** Validates a quoted string literal. */
+type ValidateStringLiteral<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+> = TLiteral extends `'${string}'` ? true : ParsedRqlLiteralError<TFieldName, TOperator, TCategory, TLiteral>;
+
+/** Validates a numeric literal. */
+type ValidateNumberLiteral<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+> = TLiteral extends `${number}` ? true : ParsedRqlLiteralError<TFieldName, TOperator, TCategory, TLiteral>;
+
+/** Validates a boolean literal. */
+type ValidateBooleanLiteral<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+> = Lowercase<TLiteral> extends 'true' | 'false' ? true
+: ParsedRqlLiteralError<TFieldName, TOperator, TCategory, TLiteral>;
+
+/** Validates a null literal. */
+type ValidateNullLiteral<TLiteral extends string> = Lowercase<TLiteral> extends 'null' ? true : false;
+
+/** Validates one scalar literal against the target field category. */
+type ValidateScalarLiteral<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+  TAllowNull extends boolean = true,
+> = TAllowNull extends true ?
+  ValidateNullLiteral<TLiteral> extends true ?
+    true
+  : ValidateScalarLiteral<TFieldName, TOperator, TCategory, TLiteral, false>
+: TCategory extends 'string' ? ValidateStringLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: TCategory extends 'number' ? ValidateNumberLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: TCategory extends 'boolean' ? ValidateBooleanLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: TCategory extends 'lookup' ? ValidateStringLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: ParsedRqlUnsupportedFieldError<TFieldName, TCategory>;
+
+/** Validates one array literal against the target field category. */
+type ValidateArrayLiteral<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TLiteral extends string,
+> = TLiteral extends `[${infer Inner}]` ?
+  SplitTopLevel<TrimRql<Inner>, ', '> extends infer TParts extends string[] ?
+    TParts['length'] extends 0 ?
+      `RQL field "${TFieldName}" with operator "${TOperator}" requires a non-empty array literal such as ['value'].`
+    : ValidateEveryArrayElement<TFieldName, TOperator, TCategory, TParts>
+  : `RQL field "${TFieldName}" with operator "${TOperator}" has an array literal that could not be parsed.`
+: `RQL field "${TFieldName}" with operator "${TOperator}" requires an array literal such as ['value']; received ${TLiteral}.`;
+
+/** Returns the first invalid array element, if any. */
+type ValidateEveryArrayElement<
+  TFieldName extends string,
+  TOperator extends string,
+  TCategory extends string,
+  TParts extends readonly string[],
+> = TParts extends [infer Next extends string, ...infer Rest extends string[]] ?
+  ValidateScalarLiteral<TFieldName, TOperator, TCategory, Next, false> extends infer TResult ?
+    TResult extends true ?
+      ValidateEveryArrayElement<TFieldName, TOperator, TCategory, Rest>
+    : TResult
+  : never
+: true;
+
+/** Validates the operator/literal pairing for one field category. */
+type ValidateComparisonLiteral<
+  TFieldName extends string,
+  TCategory extends string,
+  TOperator extends string,
+  TLiteral extends string,
+> = TCategory extends 'unsupported' ? ParsedRqlUnsupportedFieldError<TFieldName, TCategory>
+: TOperator extends '==' | '!=' ? ValidateScalarLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: TOperator extends '<' | '<=' | '>' | '>=' ?
+  TCategory extends 'string' | 'number' ?
+    ValidateScalarLiteral<TFieldName, TOperator, TCategory, TLiteral, false>
+  : `RQL field "${TFieldName}" uses operator "${TOperator}", which is only valid for string or number fields; this field expects ${ParsedRqlFieldCategoryLabel<TCategory>}.`
+: TOperator extends 'IN' | 'NOT_IN' ? ValidateArrayLiteral<TFieldName, TOperator, TCategory, TLiteral>
+: `RQL field "${TFieldName}" uses unsupported operator "${TOperator}".`;
+
+/** Validates one comparison clause once the field and operator have been identified. */
+type ValidateParsedComparison<
+  TDefinition extends AnyCustomObjectDefinition,
+  TFieldName extends string,
+  TOperator extends string,
+  TLiteral extends string,
+> = ParsedRqlFieldCategory<TDefinition, TFieldName> extends infer TCategory extends string ?
+  TCategory extends 'missing' ?
+    `Unknown RQL field "${TFieldName}". Use a logical field name from the object definition.`
+  : ValidateComparisonLiteral<TFieldName, TCategory, TOperator, TrimRql<TLiteral>>
+: never;
+
+/** Parsed comparison operator tokens recognized by the type-level validator. */
+type ParsedRqlComparisonOperator = 'NOT_IN' | 'IN' | '==' | '!=' | '<=' | '>=' | '<' | '>';
+
+/** Parsed comparison pieces once one operator match has been identified. */
+type ParsedComparisonMatch<
+  TLeft extends string = string,
+  TOperator extends ParsedRqlComparisonOperator = ParsedRqlComparisonOperator,
+  TRight extends string = string,
+> = readonly [left: TLeft, operator: TOperator, right: TRight];
+
+/** Space-tokenized comparison tuple for one expression, respecting nested strings/brackets/parens. */
+type ParsedComparisonTokens<TExpression extends string> = SplitTopLevel<TExpression, ' '>;
+
+/** Attempts to parse one comparison expression from a token tuple. */
+type ParseComparisonMatch<TExpression extends string> =
+  ParsedComparisonTokens<TExpression> extends (
+    [
+      infer TLeft extends string,
+      infer TOperator extends ParsedRqlComparisonOperator,
+      infer TRight extends string,
+    ]
+  ) ?
+    ParsedComparisonMatch<TrimRql<TLeft>, TOperator, TRight>
+  : never;
+
+/** Tries operators in longest-first order so `NOT_IN` wins before `IN`. */
+type ValidateParsedComparisonExpression<
+  TDefinition extends AnyCustomObjectDefinition,
+  TExpression extends string,
+> = [ParseComparisonMatch<TExpression>] extends [never] ?
+  `Could not parse RQL comparison "${TExpression}". Use a supported form such as "field == 'value'", "field <= 14", or "field IN ['value']" with spaces around the operator.`
+: ParseComparisonMatch<TExpression> extends (
+  ParsedComparisonMatch<
+    infer TFieldName extends string,
+    infer TOperator extends ParsedRqlComparisonOperator,
+    infer TLiteral extends string
+  >
+) ?
+  ValidateParsedComparison<TDefinition, TFieldName, TOperator, TLiteral>
+: `Could not parse RQL comparison "${TExpression}". Use a supported form such as "field == 'value'", "field <= 14", or "field IN ['value']" with spaces around the operator.`;
+
+/**
+ * Validates one parsed-RQL expression string against the object definition.
+ *
+ * The supported subset matches the SDK's documented parsed-string custom-object
+ * RQL contract:
+ * - comparisons over standard fields and local custom-object fields
+ * - `==`, `!=`, `<`, `<=`, `>`, `>=`, `IN`, and `NOT_IN`
+ * - boolean composition via `AND`, `OR`, and `NOT`
+ * - parentheses / grouping
+ * - string / number / boolean / null / array literals
+ * - lookup equality against quoted ids such as `'role_123'`
+ *
+ * @typeParam TDefinition - Object definition whose field names and value types should be enforced.
+ * @typeParam TExpression - Candidate RQL expression string.
+ */
+type ValidateNormalizedParsedRqlExpression<
+  TDefinition extends AnyCustomObjectDefinition,
+  TNormalizedExpression extends string,
+> = [ParseLogicalMatch<TNormalizedExpression>] extends [never] ?
+  TNormalizedExpression extends `NOT ${infer TInner}` ?
+    ValidateParsedRqlExpression<TDefinition, TInner>
+  : ValidateParsedComparisonExpression<TDefinition, TNormalizedExpression>
+: ParseLogicalMatch<TNormalizedExpression> extends (
+  ParsedLogicalMatch<
+    infer _TOperator extends ParsedRqlLogicalOperator,
+    infer TParts extends readonly string[]
+  >
+) ?
+  ValidateEveryExpression<TDefinition, TParts>
+: TNormalizedExpression extends `NOT ${infer TInner}` ? ValidateParsedRqlExpression<TDefinition, TInner>
+: ValidateParsedComparisonExpression<TDefinition, TNormalizedExpression>;
+
+/**
+ * Validates one parsed-RQL expression string against the object definition.
+ *
+ * @typeParam TDefinition - Object definition whose field names and value types should be enforced.
+ * @typeParam TExpression - Candidate RQL expression string.
+ */
+export type ValidateParsedRqlExpression<
+  TDefinition extends AnyCustomObjectDefinition,
+  TExpression extends string,
+> = NormalizeParsedRqlExpression<TExpression> extends infer TNormalizedExpression extends string ?
+  ValidateNormalizedParsedRqlExpression<TDefinition, TNormalizedExpression>
+: never;
+
+/**
+ * Type-level gate used by {@link typedRql} to reject invalid parsed-RQL strings.
+ *
+ * @typeParam TDefinition - Object definition whose field names and value types should be enforced.
+ * @typeParam TExpression - Candidate RQL expression string.
+ */
+export type CheckedParsedRql<
+  TDefinition extends AnyCustomObjectDefinition,
+  TExpression extends string,
+> = ValidateParsedRqlExpression<TDefinition, TExpression> extends true ? TExpression
+: TExpression & {
+    readonly __parsedRqlError__: ValidateParsedRqlExpression<TDefinition, TExpression>;
+  };
+
+/** Parsed scalar literal used by the runtime parser. */
+interface ParsedRqlLiteralString {
+  readonly kind: 'string';
+  readonly value: string;
+}
+
+/** Parsed numeric literal used by the runtime parser. */
+interface ParsedRqlLiteralNumber {
+  readonly kind: 'number';
+  readonly value: number;
+}
+
+/** Parsed boolean literal used by the runtime parser. */
+interface ParsedRqlLiteralBoolean {
+  readonly kind: 'boolean';
+  readonly value: boolean;
+}
+
+/** Parsed null literal used by the runtime parser. */
+interface ParsedRqlLiteralNull {
+  readonly kind: 'null';
+  readonly value: null;
+}
+
+/** Parsed array literal used by the runtime parser. */
+interface ParsedRqlLiteralArray {
+  readonly kind: 'array';
+  readonly value: readonly ParsedRqlScalarLiteral[];
+}
+
+/** Parsed scalar literal used by the runtime parser. */
+type ParsedRqlScalarLiteral =
+  | ParsedRqlLiteralString
+  | ParsedRqlLiteralNumber
+  | ParsedRqlLiteralBoolean
+  | ParsedRqlLiteralNull;
+
+/** Parsed literal used by the runtime parser. */
+type ParsedRqlLiteral = ParsedRqlScalarLiteral | ParsedRqlLiteralArray;
+
+/** Parsed comparison node in the runtime AST. */
+interface ParsedRqlComparisonNode {
+  readonly kind: 'comparison';
+  readonly field: string;
+  readonly operator: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT_IN';
+  readonly value: ParsedRqlLiteral;
+}
+
+/** Parsed boolean-composition node in the runtime AST. */
+interface ParsedRqlLogicalNode {
+  readonly kind: 'logical';
+  readonly operator: 'AND' | 'OR';
+  readonly operands: readonly ParsedRqlExpressionNode[];
+}
+
+/** Parsed negation node in the runtime AST. */
+interface ParsedRqlNotNode {
+  readonly kind: 'not';
+  readonly operand: ParsedRqlExpressionNode;
+}
+
+/** Runtime AST node used by {@link typedRql}. */
+type ParsedRqlExpressionNode = ParsedRqlComparisonNode | ParsedRqlLogicalNode | ParsedRqlNotNode;
+
+/** Runtime field category used by parsed-RQL validation. */
+type RuntimeFieldCategory = 'string' | 'number' | 'boolean' | 'lookup' | 'unsupported';
+
+/** Runtime metadata needed to validate and render one parsed RQL field. */
+interface RuntimeFieldMetadata {
+  /** Wire-level field API name used in rendered backend RQL. */
+  readonly apiName: string;
+
+  /** Runtime literal category used to validate operator and literal compatibility. */
+  readonly category: RuntimeFieldCategory;
+}
+
+/** Mutable parser cursor used by the runtime parsed-RQL scanner. */
+interface RuntimeParsedRqlState {
+  /** Full source text being parsed. */
+  readonly text: string;
+
+  /** Zero-based cursor into {@link text}. */
+  index: number;
+}
+
+/**
+ * Returns whether one character should be treated as parser whitespace.
+ *
+ * @param char - Candidate source character.
+ * @returns Whether the parser should skip this character outside literals.
+ */
+function isWhitespace(char: string): boolean {
+  return char === ' ' || char === '\n' || char === '\t' || char === '\r';
+}
+
+/**
+ * Advances the parser cursor past any contiguous whitespace.
+ *
+ * @param state - Mutable parser cursor to advance in place.
+ */
+function skipWhitespace(state: RuntimeParsedRqlState): void {
+  while (state.index < state.text.length && isWhitespace(state.text[state.index] as string)) {
+    state.index += 1;
+  }
+}
+
+/**
+ * Checks whether the parser cursor is currently positioned at one complete RQL keyword token.
+ *
+ * @param state - Mutable parser cursor whose current position should be checked.
+ * @param keyword - Uppercase keyword token to match, such as `AND`, `OR`, or `NULL`.
+ * @returns Whether the cursor is positioned at that complete keyword token.
+ */
+function startsWithKeyword(state: RuntimeParsedRqlState, keyword: string): boolean {
+  const source = state.text.slice(state.index, state.index + keyword.length);
+  if (source.toUpperCase() !== keyword) return false;
+  const next = state.text[state.index + keyword.length];
+  if (next == null) return true;
+  return isWhitespace(next) || next === ')' || next === ']' || next === ',';
+}
+
+/**
+ * Consumes one keyword token when it is present at the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to update in place.
+ * @param keyword - Uppercase keyword token to consume.
+ * @returns Whether the keyword was present and therefore consumed.
+ */
+function consumeKeyword(state: RuntimeParsedRqlState, keyword: string): boolean {
+  skipWhitespace(state);
+  if (!startsWithKeyword(state, keyword)) return false;
+  state.index += keyword.length;
+  return true;
+}
+
+/**
+ * Consumes one specific punctuation character when it is present at the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to update in place.
+ * @param char - Expected punctuation character, such as `(`, `)`, `[`, `]`, or `,`.
+ * @returns Whether the character was present and therefore consumed.
+ */
+function consumeCharacter(state: RuntimeParsedRqlState, char: string): boolean {
+  skipWhitespace(state);
+  if (state.text[state.index] !== char) return false;
+  state.index += 1;
+  return true;
+}
+
+/**
+ * Requires one specific punctuation character at the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to validate and update in place.
+ * @param char - Required punctuation character.
+ * @throws Error when the required character is not present.
+ */
+function expectCharacter(state: RuntimeParsedRqlState, char: string): void {
+  if (!consumeCharacter(state, char)) {
+    throw new Error(`Expected "${char}" at index ${state.index} while parsing RQL.`);
+  }
+}
+
+/**
+ * Parses one field identifier token from the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to read and update in place.
+ * @returns The parsed logical field name.
+ * @throws Error when no identifier is present at the current cursor.
+ */
+function parseIdentifier(state: RuntimeParsedRqlState): string {
+  skipWhitespace(state);
+  const start = state.index;
+  while (state.index < state.text.length) {
+    const char = state.text[state.index] as string;
+    if (!/[A-Za-z0-9_]/.test(char)) break;
+    state.index += 1;
+  }
+  if (state.index === start) {
+    throw new Error(`Expected a field name at index ${state.index} while parsing RQL.`);
+  }
+  return state.text.slice(start, state.index);
+}
+
+/**
+ * Parses one quoted string literal, including backslash escapes.
+ *
+ * @param state - Mutable parser cursor positioned at the opening single quote.
+ * @returns Parsed runtime string-literal node.
+ * @throws Error when the string literal is unterminated or contains an unterminated escape.
+ */
+function parseStringLiteral(state: RuntimeParsedRqlState): ParsedRqlLiteralString {
+  expectCharacter(state, "'");
+  let value = '';
+  while (state.index < state.text.length) {
+    const char = state.text[state.index] as string;
+    state.index += 1;
+    if (char === '\\') {
+      const next = state.text[state.index];
+      if (next == null) {
+        throw new Error('Unterminated escape sequence in RQL string literal.');
+      }
+      value += next;
+      state.index += 1;
+      continue;
+    }
+    if (char === "'") {
+      return { kind: 'string', value };
+    }
+    value += char;
+  }
+  throw new Error('Unterminated RQL string literal.');
+}
+
+/**
+ * Parses one numeric literal from the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to read and update in place.
+ * @returns Parsed runtime numeric-literal node.
+ * @throws Error when no supported numeric literal is present.
+ */
+function parseNumberLiteral(state: RuntimeParsedRqlState): ParsedRqlLiteralNumber {
+  skipWhitespace(state);
+  const remainder = state.text.slice(state.index);
+  const match = remainder.match(/^-?(?:\d*\.\d+|\d+)(?:[Ee][+-]?\d+)?/);
+  if (match == null) {
+    throw new Error(`Expected a numeric literal at index ${state.index} while parsing RQL.`);
+  }
+  state.index += match[0].length;
+  return { kind: 'number', value: Number(match[0]) };
+}
+
+/**
+ * Parses one scalar literal: string, number, boolean, or null.
+ *
+ * @param state - Mutable parser cursor to read and update in place.
+ * @returns Parsed runtime scalar-literal node.
+ */
+function parseScalarLiteral(state: RuntimeParsedRqlState): ParsedRqlScalarLiteral {
+  skipWhitespace(state);
+  const next = state.text[state.index];
+  if (next === "'") return parseStringLiteral(state);
+  if (startsWithKeyword(state, 'TRUE')) {
+    state.index += 4;
+    return { kind: 'boolean', value: true };
+  }
+  if (startsWithKeyword(state, 'FALSE')) {
+    state.index += 5;
+    return { kind: 'boolean', value: false };
+  }
+  if (startsWithKeyword(state, 'NULL')) {
+    state.index += 4;
+    return { kind: 'null', value: null };
+  }
+  return parseNumberLiteral(state);
+}
+
+/**
+ * Parses one array literal containing zero or more scalar literal elements.
+ *
+ * @param state - Mutable parser cursor positioned at the opening `[`.
+ * @returns Parsed runtime array-literal node.
+ */
+function parseArrayLiteral(state: RuntimeParsedRqlState): ParsedRqlLiteralArray {
+  expectCharacter(state, '[');
+  const values: ParsedRqlScalarLiteral[] = [];
+  skipWhitespace(state);
+  if (consumeCharacter(state, ']')) {
+    return { kind: 'array', value: values };
+  }
+  while (true) {
+    values.push(parseScalarLiteral(state));
+    skipWhitespace(state);
+    if (consumeCharacter(state, ']')) {
+      return { kind: 'array', value: values };
+    }
+    expectCharacter(state, ',');
+  }
+}
+
+/**
+ * Parses either one scalar literal or one array literal at the current parser cursor.
+ *
+ * @param state - Mutable parser cursor to read and update in place.
+ * @returns Parsed runtime literal node.
+ */
+function parseLiteral(state: RuntimeParsedRqlState): ParsedRqlLiteral {
+  skipWhitespace(state);
+  if (state.text[state.index] === '[') {
+    return parseArrayLiteral(state);
+  }
+  return parseScalarLiteral(state);
+}
+
+/**
+ * Parses one supported comparison operator token in longest-first order.
+ *
+ * @param state - Mutable parser cursor to read and update in place.
+ * @returns Parsed comparison operator token.
+ * @throws Error when no supported operator is present.
+ */
+function parseOperator(state: RuntimeParsedRqlState): ParsedRqlComparisonNode['operator'] {
+  skipWhitespace(state);
+  for (const operator of ['NOT_IN', 'IN', '==', '!=', '<=', '>=', '<', '>'] as const) {
+    if (state.text.slice(state.index, state.index + operator.length).toUpperCase() === operator) {
+      state.index += operator.length;
+      return operator;
+    }
+  }
+  throw new Error(`Expected an RQL operator at index ${state.index}.`);
+}
+
+/**
+ * Parses one full comparison clause.
+ *
+ * @param state - Mutable parser cursor positioned at the start of one comparison expression.
+ * @returns Parsed runtime comparison node.
+ */
+function parseComparison(state: RuntimeParsedRqlState): ParsedRqlComparisonNode {
+  const field = parseIdentifier(state);
+  const operator = parseOperator(state);
+  const value = parseLiteral(state);
+  return { kind: 'comparison', field, operator, value };
+}
+
+/**
+ * Parses one parenthesized subexpression or leaf comparison expression.
+ *
+ * @param state - Mutable parser cursor positioned at the next primary expression.
+ * @returns Parsed runtime expression node.
+ */
+function parsePrimary(state: RuntimeParsedRqlState): ParsedRqlExpressionNode {
+  skipWhitespace(state);
+  if (consumeCharacter(state, '(')) {
+    const expression = parseOrExpression(state);
+    expectCharacter(state, ')');
+    return expression;
+  }
+  return parseComparison(state);
+}
+
+/**
+ * Parses one NOT-prefixed expression, recursing to preserve unary precedence.
+ *
+ * @param state - Mutable parser cursor positioned at the next unary expression.
+ * @returns Parsed runtime expression node.
+ */
+function parseNotExpression(state: RuntimeParsedRqlState): ParsedRqlExpressionNode {
+  skipWhitespace(state);
+  if (consumeKeyword(state, 'NOT')) {
+    return { kind: 'not', operand: parseNotExpression(state) };
+  }
+  return parsePrimary(state);
+}
+
+/**
+ * Parses one AND-composed expression group.
+ *
+ * @param state - Mutable parser cursor positioned at the next AND-precedence expression.
+ * @returns Parsed runtime expression node, collapsed when only one operand is present.
+ */
+function parseAndExpression(state: RuntimeParsedRqlState): ParsedRqlExpressionNode {
+  const operands: ParsedRqlExpressionNode[] = [parseNotExpression(state)];
+  while (true) {
+    const checkpoint = state.index;
+    if (!consumeKeyword(state, 'AND')) {
+      state.index = checkpoint;
+      break;
+    }
+    operands.push(parseNotExpression(state));
+  }
+  return operands.length === 1 ?
+      (operands[0] as ParsedRqlExpressionNode)
+    : { kind: 'logical', operator: 'AND', operands };
+}
+
+/**
+ * Parses one OR-composed expression group, the lowest-precedence logical form.
+ *
+ * @param state - Mutable parser cursor positioned at the next OR-precedence expression.
+ * @returns Parsed runtime expression node, collapsed when only one operand is present.
+ */
+function parseOrExpression(state: RuntimeParsedRqlState): ParsedRqlExpressionNode {
+  const operands: ParsedRqlExpressionNode[] = [parseAndExpression(state)];
+  while (true) {
+    const checkpoint = state.index;
+    if (!consumeKeyword(state, 'OR')) {
+      state.index = checkpoint;
+      break;
+    }
+    operands.push(parseAndExpression(state));
+  }
+  return operands.length === 1 ?
+      (operands[0] as ParsedRqlExpressionNode)
+    : { kind: 'logical', operator: 'OR', operands };
+}
+
+/**
+ * Parses one complete parsed-string RQL expression into the runtime AST.
+ *
+ * @param text - Logical-name RQL source string to parse.
+ * @returns Parsed runtime expression tree.
+ * @throws Error when the expression is malformed or contains trailing content.
+ */
+function parseTypedRqlExpression(text: string): ParsedRqlExpressionNode {
+  const state: RuntimeParsedRqlState = { text, index: 0 };
+  const expression = parseOrExpression(state);
+  skipWhitespace(state);
+  if (state.index !== state.text.length) {
+    throw new Error(
+      `Unexpected trailing RQL content starting at index ${state.index}: ${state.text.slice(state.index)}.`,
+    );
+  }
+  return expression;
+}
+
+/**
+ * Resolves the runtime validation/rendering metadata for one logical field name.
+ *
+ * @param definition - Object definition that owns the valid field set.
+ * @param fieldName - Logical field name referenced by the parsed expression.
+ * @returns Runtime metadata used to validate literals and render wire-level field names.
+ * @throws Error when the field name is unknown for the supplied definition.
+ */
+function resolveRuntimeFieldMetadata(
+  definition: AnyCustomObjectDefinition,
+  fieldName: string,
+): RuntimeFieldMetadata {
+  if ((STANDARD_TYPED_RQL_FIELDS as readonly string[]).includes(fieldName)) {
+    return {
+      apiName: fieldName,
+      category: STANDARD_LOOKUP_FIELDS.has(fieldName) ? 'lookup' : 'string',
+    };
+  }
+
+  const field = definition.fields[fieldName as FieldNames<typeof definition>];
+  if (field == null) {
+    throw new Error(
+      `Unknown field "${fieldName}" for "${definition.apiName}". Valid fields: ${[
+        ...STANDARD_TYPED_RQL_FIELDS,
+        ...Object.keys(definition.fields).sort(),
+      ].join(', ')}.`,
+    );
+  }
+
+  switch (field.kind) {
+    case 'text':
+    case 'long-text':
+    case 'email':
+    case 'url':
+    case 'phone':
+    case 'date':
+    case 'datetime':
+    case 'time':
+    case 'radio':
+    case 'formula-text':
+    case 'formula-date':
+    case 'formula-url':
+      return { apiName: field.apiName, category: 'string' };
+    case 'number':
+    case 'currency':
+    case 'percentage':
+    case 'formula-number':
+    case 'formula-currency':
+    case 'formula-percentage':
+      return { apiName: field.apiName, category: 'number' };
+    case 'boolean':
+    case 'formula-boolean':
+      return { apiName: field.apiName, category: 'boolean' };
+    case 'lookup':
+    case 'parent-child':
+      return { apiName: field.apiName, category: 'lookup' };
+    default:
+      return { apiName: field.apiName, category: 'unsupported' };
+  }
+}
+
+/**
+ * Describes the literal form a runtime field category accepts in human-readable errors.
+ *
+ * @param category - Runtime field category being validated.
+ * @returns Human-readable description of the expected literal form.
+ */
+function describeRuntimeExpectedLiteral(category: RuntimeFieldCategory): string {
+  switch (category) {
+    case 'string':
+      return "a quoted string literal such as 'Ada'";
+    case 'number':
+      return 'a numeric literal such as 14';
+    case 'boolean':
+      return 'a boolean literal: True or False';
+    case 'lookup':
+      return "a quoted record-id string such as 'rec_123'";
+    default:
+      return 'a supported literal value';
+  }
+}
+
+/**
+ * Describes one parsed literal value in human-readable runtime errors.
+ *
+ * @param literal - Parsed literal value to describe.
+ * @returns Human-readable description of the provided literal.
+ */
+function describeRuntimeLiteral(literal: ParsedRqlLiteral): string {
+  switch (literal.kind) {
+    case 'string':
+      return `quoted string ${encodeTypedRqlString(literal.value)}`;
+    case 'number':
+      return `number ${String(literal.value)}`;
+    case 'boolean':
+      return `boolean ${literal.value ? 'True' : 'False'}`;
+    case 'null':
+      return 'null';
+    case 'array':
+      return `array ${renderTypedRqlLiteral(literal)}`;
+  }
+}
+
+/**
+ * Enforces that one parsed literal/operator pairing is valid for the field category.
+ *
+ * @param fieldName - Logical field name used in user-facing error messages.
+ * @param category - Runtime category inferred for that field.
+ * @param operator - Comparison operator applied to the field.
+ * @param literal - Parsed literal value supplied on the right-hand side.
+ * @throws Error when the operator/literal combination is invalid for the field category.
+ */
+function assertLiteralMatchesCategory(
+  fieldName: string,
+  category: RuntimeFieldCategory,
+  operator: ParsedRqlComparisonNode['operator'],
+  literal: ParsedRqlLiteral,
+): void {
+  if (category === 'unsupported') {
+    throw new Error('typedRql(...) does not yet support this field kind in parsed-string mode.');
+  }
+
+  if (operator === 'IN' || operator === 'NOT_IN') {
+    if (literal.kind !== 'array') {
+      throw new Error(
+        `RQL field "${fieldName}" with operator "${operator}" requires an array literal such as ['value']; received ${describeRuntimeLiteral(
+          literal,
+        )}.`,
+      );
+    }
+    if (literal.value.length === 0) {
+      throw new Error(
+        `RQL field "${fieldName}" with operator "${operator}" requires a non-empty array literal such as ['value'].`,
+      );
+    }
+    for (const value of literal.value) {
+      assertLiteralMatchesCategory(fieldName, category, '==', value);
+    }
+    return;
+  }
+
+  if (literal.kind === 'null') {
+    if (operator === '<' || operator === '<=' || operator === '>' || operator === '>=') {
+      throw new Error(
+        `RQL field "${fieldName}" with operator "${operator}" does not allow null. Use a concrete ${describeRuntimeExpectedLiteral(
+          category,
+        )}.`,
+      );
+    }
+    return;
+  }
+
+  if (
+    (operator === '<' || operator === '<=' || operator === '>' || operator === '>=') &&
+    !(category === 'string' || category === 'number')
+  ) {
+    throw new Error(
+      `RQL field "${fieldName}" uses operator "${operator}", which is only valid for string or number fields; this field expects ${describeRuntimeExpectedLiteral(
+        category,
+      )}.`,
+    );
+  }
+
+  switch (category) {
+    case 'string':
+      if (literal.kind !== 'string') {
+        throw new Error(
+          `RQL field "${fieldName}" with operator "${operator}" expects ${describeRuntimeExpectedLiteral(
+            category,
+          )}; received ${describeRuntimeLiteral(literal)}.`,
+        );
+      }
+      return;
+    case 'number':
+      if (literal.kind !== 'number') {
+        throw new Error(
+          `RQL field "${fieldName}" with operator "${operator}" expects ${describeRuntimeExpectedLiteral(
+            category,
+          )}; received ${describeRuntimeLiteral(literal)}.`,
+        );
+      }
+      return;
+    case 'boolean':
+      if (literal.kind !== 'boolean') {
+        throw new Error(
+          `RQL field "${fieldName}" with operator "${operator}" expects ${describeRuntimeExpectedLiteral(
+            category,
+          )}; received ${describeRuntimeLiteral(literal)}.`,
+        );
+      }
+      return;
+    case 'lookup':
+      if (literal.kind !== 'string') {
+        throw new Error(
+          `RQL field "${fieldName}" with operator "${operator}" expects ${describeRuntimeExpectedLiteral(
+            category,
+          )}; received ${describeRuntimeLiteral(literal)}.`,
+        );
+      }
+      return;
+    default:
+      return;
+  }
+}
+
+/**
+ * Walks the runtime AST and validates each comparison against the object definition.
+ *
+ * @param definition - Object definition that owns the valid field set and field categories.
+ * @param node - Parsed runtime AST node to validate.
+ * @throws Error when any referenced field or literal/operator combination is invalid.
+ */
+function validateTypedRqlAst(definition: AnyCustomObjectDefinition, node: ParsedRqlExpressionNode): void {
+  switch (node.kind) {
+    case 'logical':
+      for (const operand of node.operands) validateTypedRqlAst(definition, operand);
+      return;
+    case 'not':
+      validateTypedRqlAst(definition, node.operand);
+      return;
+    case 'comparison': {
+      const metadata = resolveRuntimeFieldMetadata(definition, node.field);
+      assertLiteralMatchesCategory(node.field, metadata.category, node.operator, node.value);
+      return;
+    }
+  }
+}
+
+/**
+ * Escapes one string value back into backend-ready single-quoted RQL syntax.
+ *
+ * @param value - Raw string value to encode.
+ * @returns Escaped single-quoted RQL literal text.
+ */
+function encodeTypedRqlString(value: string): string {
+  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+
+/**
+ * Renders one parsed literal value back into backend-ready RQL text.
+ *
+ * @param literal - Parsed literal node to render.
+ * @returns Backend-ready RQL literal text.
+ */
+function renderTypedRqlLiteral(literal: ParsedRqlLiteral): string {
+  switch (literal.kind) {
+    case 'string':
+      return encodeTypedRqlString(literal.value);
+    case 'number':
+      return String(literal.value);
+    case 'boolean':
+      return literal.value ? 'True' : 'False';
+    case 'null':
+      return 'null';
+    case 'array':
+      return `[${literal.value.map((value) => renderTypedRqlLiteral(value)).join(', ')}]`;
+  }
+}
+
+/**
+ * Renders the validated runtime AST back into backend-ready wire-level RQL.
+ *
+ * @param definition - Object definition that supplies wire-level field API names.
+ * @param node - Parsed and validated runtime AST node to render.
+ * @returns Backend-ready RQL expression string.
+ */
+function renderTypedRqlAst(definition: AnyCustomObjectDefinition, node: ParsedRqlExpressionNode): string {
+  switch (node.kind) {
+    case 'logical':
+      return `(${node.operands
+        .map((operand) => renderTypedRqlAst(definition, operand))
+        .join(` ${node.operator} `)})`;
+    case 'not':
+      return `(NOT ${renderTypedRqlAst(definition, node.operand)})`;
+    case 'comparison': {
+      const metadata = resolveRuntimeFieldMetadata(definition, node.field);
+      return `(${metadata.apiName} ${node.operator} ${renderTypedRqlLiteral(node.value)})`;
+    }
+  }
+}
+
+/**
+ * Parses a constrained logical-name RQL string, validates it against the typed custom-object definition,
+ * and renders a backend-ready RQL string that uses wire-level field api names.
+ *
+ * Supported parsed-string custom-object RQL contract:
+ * - standard record fields and local custom-object fields
+ * - `==`, `!=`, `<`, `<=`, `>`, `>=`, `IN`, `NOT_IN`
+ * - `AND`, `OR`, `NOT`
+ * - parentheses / grouping
+ * - string / number / boolean / null / array literals
+ * - lookup equality against quoted ids such as `owner_role == 'role_123'`
+ *
+ * This helper intentionally targets the SDK's documented custom-object subset
+ * rather than the full universe of backend RQL features.
+ *
+ * @param definition - Object definition whose logical field names and value categories should be enforced.
+ * @param expression - Constrained logical-name RQL source string to parse and render.
+ * @returns Backend-ready RQL string that uses wire-level field API names.
+ * @typeParam TDefinition - Object definition whose field names and value types should be enforced.
+ * @typeParam TExpression - Candidate RQL expression string.
+ */
+export function typedRql<TDefinition extends AnyCustomObjectDefinition, TExpression extends string>(
+  definition: TDefinition,
+  expression: CheckedParsedRql<TDefinition, TExpression>,
+): string {
+  const ast = parseTypedRqlExpression(expression as string);
+  validateTypedRqlAst(definition, ast);
+  return renderTypedRqlAst(definition, ast);
+}