@kuindji/typed-sql 0.3.0 → 0.4.0

package/src/expressions.ts

@@ -3,9 +3,9 @@ import type {
     ColumnRef,
     ColumnRefValidLooseWith,
     ParseColumnRef,
-    QualifiedColumnRefs,
+    QualifiedRefScan,
     ResolveTableKey,
-    UnqualifiedColumnRefs,
+    UnqualifiedRefScan,
     UnqualifiedColumnValid
 } from "./columns.js";
 import type { AliasesInQuery, TablesInQuery } from "./tables.js";
@@ -23,7 +23,6 @@ import type {
     SqlConstantType,
     SplitBalancedParen,
     SplitTopLevel,
-    TokenizeLoose,
     Trim
 } from "./parsing.js";
 import type { AllTrue } from "./utils.js";
@@ -144,7 +143,95 @@ export type ApplyProjectionNull<
         ? CoalesceAllArgsNullable<SplitTopLevel<Args>, Tables, Aliases, S, Nullable> extends true
             ? T | null
             : T
-        : ApplyJoinNull<T, E, Nullable>;
+        : [Nullable] extends [never]
+            ? T
+            : [T] extends [never]
+                ? ApplyJoinNull<T, E, Nullable>
+                : [T] extends [number | null]
+                    ? E extends `${string}${"+" | "-" | "*" | "/" | "%"}${string}`
+                        ? ArithRefJoinNullable<E, Tables, Aliases, S, Nullable> extends true
+                            ? T | null
+                            : ApplyJoinNull<T, E, Nullable>
+                        : ApplyJoinNull<T, E, Nullable>
+                    : ApplyJoinNull<T, E, Nullable>;
+
+// Outer-join nullability for a TOP-LEVEL ARITHMETIC projection (`A op B`).
+// SQL NULL arithmetic is NULL, so the result is nullable when ANY operand is
+// sourced from the nullable side of an outer join. `RefQualifier` cannot see
+// operand refs (an arithmetic expression is not a plain column ref — or worse,
+// its leftmost dot fakes one: `u.id + o.total` "qualifies" as `u`), so this
+// walks the operands the same way the arithmetic TYPING did: split at the
+// top-level operator and recurse each side. Only consulted when the projection
+// already typed `number`/`number | null` (the arithmetic result types), under
+// a non-empty `Nullable` set, with an operator char present — join-free
+// queries and plain projections pay nothing. A `false` verdict falls back to
+// `ApplyJoinNull`, so a non-arithmetic expression that slips past the op-char
+// gate (e.g. a quoted-punct ref like `"u-1".id`) keeps its plain-ref handling.
+type ArithRefJoinNullable<
+    E extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Nullable extends string,
+    Steps extends any[] = []
+> =
+    Steps["length"] extends 8
+        ? false
+        : UnwrapRedundantParens<Trim<E>> extends infer SC extends string
+            ? SC extends `${string}${"+" | "-" | "*" | "/" | "%"}${string}`
+                ? SplitTopLevelOp<SC> extends infer SR
+                    ? [SR] extends [never]
+                        ? ArithOperandJoinNullable<SC, Tables, Aliases, S, Nullable>
+                        : SR extends { __op: [infer L extends string, infer Op extends string, infer R extends string] }
+                            ? Op extends "||"
+                                ? false
+                                : ArithRefJoinNullable<Trim<L>, Tables, Aliases, S, Nullable, [any, ...Steps]> extends true
+                                    ? true
+                                    : ArithRefJoinNullable<Trim<R>, Tables, Aliases, S, Nullable, [any, ...Steps]>
+                            : ArithOperandJoinNullable<SC, Tables, Aliases, S, Nullable>
+                    : false
+                : ArithOperandJoinNullable<SC, Tables, Aliases, S, Nullable>
+            : false;
+
+// A LEAF arithmetic operand (no top-level operator left). A whole-operand
+// `coalesce(...)` keeps its all-args-nullable semantics (`coalesce(o.x, 0)`
+// stays non-null even on the nullable side). A function-call operand
+// (`sum(o.total)`) is conservatively nullable when any nullable-side
+// qualified ref appears inside it — an all-NULL group aggregates to NULL.
+// A plain ref consults its qualifier; literals and params stay non-null.
+type ArithOperandJoinNullable<
+    SC extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Nullable extends string
+> =
+    CleanExpr<StripOuterCast<SC>> extends `coalesce(${infer Args})`
+        ? CoalesceAllArgsNullable<SplitTopLevel<Args>, Tables, Aliases, S, Nullable>
+        : SC extends `${string}(${string}`
+            ? NullableQualRefIn<SC, Nullable>
+            : RefQualifier<SC> extends infer Q extends string
+                ? [Q] extends [never]
+                    ? false
+                    : Q extends Nullable
+                        ? true
+                        : false
+                : false;
+
+// True when a `<Q>.`-qualified ref appears in `E` for any nullable qualifier
+// `Q` — at the start, or after a boundary char that cannot be part of an
+// identifier (so alias-suffix lookalikes like `po.x` never match `o`).
+type NullableQualRefIn<E extends string, Nullable extends string> =
+    true extends (Nullable extends string ? QualRefIn<E, Nullable> : never)
+        ? true
+        : false;
+
+type QualRefIn<E extends string, Q extends string> =
+    E extends `${Q}.${string}`
+        ? true
+        : E extends `${string}${" " | "(" | "," | "+" | "-" | "*" | "/" | "%"}${Q}.${string}`
+            ? true
+            : false;
 
 // True only when every coalesce argument is nullable. An empty/exhausted list is
 // vacuously `true`, but the wrapper above only reaches this for a real coalesce call
@@ -243,57 +330,452 @@ export type IsBoolExpr<CE extends string> =
             : false;
 
 // Scans for a comparison operator outside parens and outside `'…'`/`"…"` quotes.
-// `->>`, `#>>` and `::` are consumed as units so their `>`/`:` are not mistaken
-// for comparisons. Modelled on the char-walker in `SplitTopLevel` (parsing.ts).
-export type HasTopLevelCompare<
+// `->>`, `#>>` etc. are consumed as units so their `>` is not mistaken for a
+// comparison.
+//
+// Struct-jump, not per-char (the old walk minted the tail PER CHARACTER over
+// every compare-bearing expression, including whole casted subquery bodies).
+// Each step advances to the leftmost of `'` `"` `(` `)` (pairwise narrowing);
+// the RUN before it — structural-char-free by construction — is tested at
+// depth 0 with `HtcRunCheck`: a run containing `=` or `!` is a comparison
+// outright (no non-comparison unit contains either), and a run with only
+// `<`/`>` is scanned unit-to-unit (`->`, `->>`, `#>`, `#>>`, `@>`, `<@`,
+// `<<`, `>>` consumed by 1-char context; the old `::` consume was a no-op —
+// `:` never matched the compare set). Quote spans are jumped quote-to-quote
+// (the other quote kind inside a span is data, the old InQ/InDQ suppression);
+// an unterminated quote swallows the rest (old walk-to-EOF → `false`). The
+// cap counts jumps, `false` on overflow as before.
+export type HasTopLevelCompare<S extends string> = HtcJump<S, [], []>;
+
+type HtcJump<
     S extends string,
-    Depth extends any[] = [],
-    Steps extends any[] = [],
-    InQ extends boolean = false,
-    InDQ extends boolean = false
+    Depth extends any[],
+    Steps extends any[]
 > = Steps["length"] extends 400
     ? false
-    : S extends `${infer C}${infer Rest}`
-        ? InQ extends true
-            ? HasTopLevelCompare<Rest, Depth, [any, ...Steps], C extends "'" ? false : true, InDQ>
-        : InDQ extends true
-            ? HasTopLevelCompare<Rest, Depth, [any, ...Steps], InQ, C extends `"` ? false : true>
-        : C extends "'"
-            ? HasTopLevelCompare<Rest, Depth, [any, ...Steps], true, InDQ>
-        : C extends `"`
-            ? HasTopLevelCompare<Rest, Depth, [any, ...Steps], InQ, true>
-        : C extends "("
-            ? HasTopLevelCompare<Rest, [any, ...Depth], [any, ...Steps], InQ, InDQ>
-        : C extends ")"
-            ? HasTopLevelCompare<Rest, Depth extends [any, ...infer D] ? D : [], [any, ...Steps], InQ, InDQ>
-        : Depth["length"] extends 0
-            // Consume multi-char operators whose `<`/`>`/`:` are NOT comparisons:
-            // JSON access (`->`, `->>`, `#>`, `#>>`), containment (`@>`, `<@`),
-            // cast (`::`), and bit-shift (`<<`, `>>`). Longer forms first.
-            ? S extends `->>${infer R}`
-                ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `->${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `#>>${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `#>${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `@>${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `<@${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `::${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `<<${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : S extends `>>${infer R}`
-                    ? HasTopLevelCompare<R, Depth, [any, ...Steps], InQ, InDQ>
-                : C extends "<" | ">" | "=" | "!"
-                    ? true
-                    : HasTopLevelCompare<Rest, Depth, [any, ...Steps], InQ, InDQ>
-            : HasTopLevelCompare<Rest, Depth, [any, ...Steps], InQ, InDQ>
+    : S extends `${infer P}'${infer R}`
+        ? P extends `${string}"${string}` | `${string}(${string}` | `${string})${string}`
+            ? HtcJump2<S, Depth, Steps>
+            : HtcRunCheck<P, Depth> extends true
+                ? true
+                : R extends `${string}'${infer R2}`
+                    ? HtcJump<R2, Depth, [any, ...Steps]>
+                    : false
+        : HtcJump2<S, Depth, Steps>;
+
+type HtcJump2<
+    S extends string,
+    Depth extends any[],
+    Steps extends any[]
+> = S extends `${infer P}"${infer R}`
+    ? P extends `${string}(${string}` | `${string})${string}`
+        ? HtcJump3<S, Depth, Steps>
+        : HtcRunCheck<P, Depth> extends true
+            ? true
+            : R extends `${string}"${infer R2}`
+                ? HtcJump<R2, Depth, [any, ...Steps]>
+                : false
+    : HtcJump3<S, Depth, Steps>;
+
+type HtcJump3<
+    S extends string,
+    Depth extends any[],
+    Steps extends any[]
+> = S extends `${infer P}(${infer R}`
+    ? P extends `${string})${string}`
+        ? HtcJump4<S, Depth, Steps>
+        : HtcRunCheck<P, Depth> extends true
+            ? true
+            : HtcJump<R, [any, ...Depth], [any, ...Steps]>
+    : HtcJump4<S, Depth, Steps>;
+
+type HtcJump4<
+    S extends string,
+    Depth extends any[],
+    Steps extends any[]
+> = S extends `${infer P})${infer R}`
+    ? HtcRunCheck<P, Depth> extends true
+        ? true
+        : HtcJump<R, Depth extends [any, ...infer D] ? D : [], [any, ...Steps]>
+    : HtcRunCheck<S, Depth>;
+
+// A structural-char-free run is only inspected at depth 0. `=`/`!` never occur
+// in a non-comparison unit, so their presence alone is a comparison; `<`/`>`
+// need the unit scan.
+type HtcRunCheck<P extends string, Depth extends any[]> =
+    Depth["length"] extends 0
+        ? P extends `${string}${"=" | "!"}${string}`
+            ? true
+            : P extends `${string}${"<" | ">"}${string}`
+                ? HtcRunScan<P>
+                : false
+        : false;
+
+// Unit-to-unit scan of a `<`/`>`-bearing run (no `=`/`!`, no structural chars):
+// jump to the leftmost `<` or `>` and judge it by 1-char context — part of
+// `<@`/`<<` (next char) or `->`/`->>`/`#>`/`#>>`/`@>`/`>>` (previous/next
+// char) is consumed as a unit; anything else is a bare comparison.
+type HtcRunScan<R extends string, Steps extends any[] = []> =
+    Steps["length"] extends 50
+        ? false
+        : R extends `${infer A}<${infer B}`
+            ? A extends `${string}>${string}`
+                ? HtcRunGt<R, Steps>
+                : B extends `@${infer B2}`
+                    ? HtcRunScan<B2, [any, ...Steps]>
+                    : B extends `<${infer B2}`
+                        ? HtcRunScan<B2, [any, ...Steps]>
+                        : true
+            : HtcRunGt<R, Steps>;
+
+type HtcRunGt<R extends string, Steps extends any[]> =
+    R extends `${infer A}>${infer B}`
+        ? A extends `${string}${"-" | "#" | "@"}`
+            ? B extends `>${infer B2}`
+                ? HtcRunScan<B2, [any, ...Steps]>
+                : HtcRunScan<B, [any, ...Steps]>
+            : B extends `>${infer B2}`
+                ? HtcRunScan<B2, [any, ...Steps]>
+                : true
         : false;
 
+// ---------------------------------------------------------------------------
+// Tier-2 arithmetic: top-level operator split.
+//
+// Finds the LEFTMOST operator in {`||`, `+`, `-`, `*`, `/`, `%`} that sits at
+// paren depth 0 outside `'…'`/`"…"` quotes, and splits the expression around
+// it: `{ __op: [left, op, right] }`. A top-level UNMODELED operator char
+// (single `|` bitwise-or, or the `||/` cube-root prefix) yields the abort
+// marker `{ __ab: true }` (consumer: `unknown`); `never` means no top-level
+// modeled operator exists. `->` / `->>` JSON arrows are consumed as units so
+// their `-` is not mistaken for subtraction.
+//
+// Structure mirrors `HasTopLevelCompare` (struct-jump to the leftmost of
+// `'` `"` `(` `)`, pairwise narrowing) but ACCUMULATES the consumed prefix so
+// the split can be returned, and is worker/driver CHUNKED like
+// `SplitTopLevel` (split.ts): each jump costs ~4 structural helpers plus a
+// ≤6-level run scan at depth 0, so 80 jumps/chunk stays well under TS's
+// ~1000 tail-count budget (round-11 lesson: budget chunks in tail counts,
+// not jumps). Quote spans are jumped quote-to-quote (`''` escapes alternate
+// close/re-open across jumps, so escaped content stays "inside"); an
+// unterminated quote means no trustworthy split -> `never`.
+type SplitTopLevelOp<S extends string> = StoDrive<StoWorker<S>>;
+
+// `[R] extends [never]` MUST be guarded first — `never` distributes through
+// the `extends {…}` test and would otherwise fall into the infer arm
+// (round-10 lesson).
+type StoDrive<R> =
+    [R] extends [never]
+        ? never
+        : R extends { __c: [infer S2 extends string, infer D extends any[], infer A extends string] }
+            ? StoDrive<StoWorker<S2, D, A, []>>
+            : R;
+
+type StoWorker<
+    S extends string,
+    Depth extends any[] = [],
+    Acc extends string = "",
+    Steps extends any[] = []
+> = Steps["length"] extends 80
+    ? { __c: [S, Depth, Acc] }
+    : StoJump1<S, Depth, Acc, Steps>;
+
+// Run-gate: a structural-char-free run is only operator-scanned at depth 0.
+// At depth > 0 every char is data (`sum(x | y) + 1` must not abort on the
+// nested `|`).
+type StoRunGate<P extends string, Depth extends any[], Acc extends string, Tail extends string> =
+    Depth["length"] extends 0
+        ? StoRunScan<P, Acc, Tail>
+        : never;
+
+type StoJump1<
+    S extends string,
+    Depth extends any[],
+    Acc extends string,
+    Steps extends any[]
+> = S extends `${infer P}'${infer R}`
+    ? P extends `${string}"${string}` | `${string}(${string}` | `${string})${string}`
+        ? StoJump2<S, Depth, Acc, Steps>
+        : StoRunGate<P, Depth, Acc, `'${R}`> extends infer RR
+            ? [RR] extends [never]
+                ? R extends `${infer Span}'${infer R2}`
+                    ? StoWorker<R2, Depth, `${Acc}${P}'${Span}'`, [any, ...Steps]>
+                    : never
+                : RR
+            : never
+    : StoJump2<S, Depth, Acc, Steps>;
+
+type StoJump2<
+    S extends string,
+    Depth extends any[],
+    Acc extends string,
+    Steps extends any[]
+> = S extends `${infer P}"${infer R}`
+    ? P extends `${string}(${string}` | `${string})${string}`
+        ? StoJump3<S, Depth, Acc, Steps>
+        : StoRunGate<P, Depth, Acc, `"${R}`> extends infer RR
+            ? [RR] extends [never]
+                ? R extends `${infer Span}"${infer R2}`
+                    ? StoWorker<R2, Depth, `${Acc}${P}"${Span}"`, [any, ...Steps]>
+                    : never
+                : RR
+            : never
+    : StoJump3<S, Depth, Acc, Steps>;
+
+type StoJump3<
+    S extends string,
+    Depth extends any[],
+    Acc extends string,
+    Steps extends any[]
+> = S extends `${infer P}(${infer R}`
+    ? P extends `${string})${string}`
+        ? StoJump4<S, Depth, Acc, Steps>
+        : StoRunGate<P, Depth, Acc, `(${R}`> extends infer RR
+            ? [RR] extends [never]
+                ? StoWorker<R, [any, ...Depth], `${Acc}${P}(`, [any, ...Steps]>
+                : RR
+            : never
+    : StoJump4<S, Depth, Acc, Steps>;
+
+type StoJump4<
+    S extends string,
+    Depth extends any[],
+    Acc extends string,
+    Steps extends any[]
+> = S extends `${infer P})${infer R}`
+    ? StoRunGate<P, Depth, Acc, `)${R}`> extends infer RR
+        ? [RR] extends [never]
+            // an unmatched `)` at depth 0 stays at depth 0 (pop of empty = empty)
+            ? StoWorker<R, Depth extends [any, ...infer D] ? D : [], `${Acc}${P})`, [any, ...Steps]>
+            : RR
+        : never
+    : StoRunGate<S, Depth, Acc, "">;
+
+// Leftmost modeled operator within a structural-free run `P` (no quotes or
+// parens by construction). Pairwise narrowing, same invariant as
+// `StlStructJump`: each level checks the matched prefix for every LATER
+// class, so the level that fires is genuinely the leftmost. `Tail` is the
+// untouched remainder of the whole expression after the run; the returned
+// `right` re-attaches it.
+type StoRunScan<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}+${infer B}`
+        ? A extends `${string}${"-" | "*" | "/" | "%" | "|"}${string}`
+            ? StoRunScan2<P, Acc, Tail>
+            : { __op: [`${Acc}${A}`, "+", `${B}${Tail}`] }
+        : StoRunScan2<P, Acc, Tail>;
+
+type StoRunScan2<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}-${infer B}`
+        ? A extends `${string}${"*" | "/" | "%" | "|"}${string}`
+            ? StoRunScan3<P, Acc, Tail>
+            : B extends `>${infer B2}`
+                // `->` / `->>` JSON arrow: a unit, not subtraction — keep
+                // scanning the rest of the run (a leading `>` from `->>` is
+                // not an operator char and is skipped naturally). Non-tail
+                // recursion, but bounded by arrows-per-run (tiny in practice).
+                ? StoRunScan<B2, `${Acc}${A}->`, Tail>
+                : { __op: [`${Acc}${A}`, "-", `${B}${Tail}`] }
+        : StoRunScan3<P, Acc, Tail>;
+
+type StoRunScan3<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}*${infer B}`
+        ? A extends `${string}${"/" | "%" | "|"}${string}`
+            ? StoRunScan4<P, Acc, Tail>
+            : { __op: [`${Acc}${A}`, "*", `${B}${Tail}`] }
+        : StoRunScan4<P, Acc, Tail>;
+
+type StoRunScan4<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}/${infer B}`
+        ? A extends `${string}${"%" | "|"}${string}`
+            ? StoRunScan5<P, Acc, Tail>
+            : { __op: [`${Acc}${A}`, "/", `${B}${Tail}`] }
+        : StoRunScan5<P, Acc, Tail>;
+
+type StoRunScan5<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}%${infer B}`
+        ? A extends `${string}|${string}`
+            ? StoRunScan6<P, Acc, Tail>
+            : { __op: [`${Acc}${A}`, "%", `${B}${Tail}`] }
+        : StoRunScan6<P, Acc, Tail>;
+
+type StoRunScan6<P extends string, Acc extends string, Tail extends string> =
+    P extends `${infer A}|${infer B}`
+        ? B extends `|${infer B2}`
+            ? B2 extends `/${string}`
+                // `||/` cube root — numeric prefix operator, NOT concat
+                ? { __ab: true }
+                : Trim<`${Acc}${A}`> extends ""
+                    // leading `||` with no left operand — unmodeled prefix op
+                    ? { __ab: true }
+                    : { __op: [`${Acc}${A}`, "||", `${B2}${Tail}`] }
+            // single `|` (bitwise) at top level — unmodeled, conservative stop
+            : { __ab: true }
+        : never;
+
+// `A op B` for op in {+, -, *, /, %} types `number` when BOTH operands type
+// `number` (`| null` propagating from either side — SQL NULL arithmetic is
+// NULL). number op number is numeric in Postgres; the interval/date hazards
+// all require a non-number operand, which the schema types as non-number, so
+// the both-number case is unambiguous and contract-legal. Any other operand
+// type — including `never` — degrades to `unknown`: an operand the core path
+// cannot resolve (a ref qualified by a joined-derived alias, a mis-split
+// like `1e+5` -> `1e`) must NOT reject, or `ExprValid`'s never-gate would
+// flip `ValidateSQL` to `false` on valid SQL; genuinely bogus columns are
+// still rejected by the token-scan validators independently.
+type ArithCombineType<
+    L extends string,
+    R extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[]
+> =
+    Trim<L> extends ""
+        ? unknown
+        : ArithCombineTypes<ExprType<Trim<L>, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>;
+
+// Same, with the LEFT operand's type already computed (the Func-branch
+// dispatcher gets it from `FunctionReturn` without re-parsing the call).
+type ArithCombineTypes<
+    LT,
+    R extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[]
+> =
+    Trim<R> extends ""
+        ? unknown
+        : ArithNumClass<LT> extends infer LN
+            ? LN extends false
+                ? unknown
+                : ArithNumClass<ExprType<Trim<R>, Tables, Aliases, S, [any, ...Steps]>> extends infer RN
+                    ? RN extends false
+                        ? unknown
+                        : "nullable" extends LN | RN
+                            ? number | null
+                            : number
+                    : unknown
+            : unknown;
+
+// `never` guarded FIRST — `[never]` matches the later arms too. A bare
+// `null` operand classes as nullable (`price + null` -> number | null).
+type ArithNumClass<T> =
+    [T] extends [never]
+        ? false
+        : [T] extends [number]
+            ? "num"
+            : [T] extends [number | null]
+                ? "nullable"
+                : false;
+
+// Scan-and-combine used where no cheaper dispatch is possible: the
+// fallback-slot path and the op-char-in-Func-prefix path. `NoOp` is the
+// result when the scan finds no top-level modeled operator (today's
+// behavior at the call site); the abort marker is conservative `unknown`.
+type ArithViaScan<
+    CE extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[],
+    NoOp
+> =
+    SplitTopLevelOp<CE> extends infer SR
+        ? [SR] extends [never]
+            ? NoOp
+            : SR extends { __op: [infer L extends string, infer Op extends string, infer R extends string] }
+                ? Op extends "||"
+                    ? string
+                    : ArithCombineType<L, R, Tables, Aliases, S, Steps>
+                : unknown
+        : never;
+
+// Final-fallback-slot arithmetic (replaces Tier 1's DivByNumericLiteralType,
+// which it subsumes: a numeric-literal divisor is just a `${number}` right
+// operand). Sits after the column-ref branch fails, so common paths pay
+// nothing; the char pre-gate skips the scan for operator-free expressions.
+// `||` is unreachable here (the naive `${string}||${string}` branch runs
+// earlier in the cascade), so the gate set is the five arithmetic chars.
+type TopLevelArithType<
+    CE extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[]
+> =
+    CE extends `${string}${"+" | "-" | "*" | "/" | "%"}${string}`
+        ? ArithViaScan<CE, Tables, Aliases, S, Steps, unknown>
+        : unknown;
+
+// Func-branch dispatcher. The greedy `${Func}(${Args})` match anchors on the
+// LAST `)`, so `sum(price) / count(id)` lands here with Func="sum",
+// Args="price) / count(id" — a function call is only the WHOLE expression
+// when its first paren group is also its last. Dispatch:
+// - Func clean + no `)` in Args (the overwhelmingly common projection:
+//   `count(*)`, `sum(price)`, `upper(name)`, ops hidden inside quoted args)
+//   -> FunctionReturn directly, zero new cost.
+// - Func clean + `)` in Args -> `SplitBalancedParen` (already-paid chunked
+//   primitive) resolves the first call's true extent WITHOUT a scan:
+//   rest "" means the call spans the whole expression (nested calls like
+//   `coalesce(min(x), 0)`); an operator-leading rest is arithmetic with the
+//   call as left operand; anything else (window `over (...)`, `filter`)
+//   keeps today's greedy FunctionReturn.
+// - Operator char in Func (`price + count(id)`, `name || upper(b)`) -> the
+//   operator precedes the first paren; full top-level scan.
+type FuncOrArithType<
+    CE extends string,
+    Func extends string,
+    Args extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[]
+> =
+    Func extends `${string}${"+" | "-" | "*" | "/" | "%" | "|"}${string}`
+        ? ArithViaScan<CE, Tables, Aliases, S, Steps, FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>>
+        : Args extends `${string})${string}`
+            ? CE extends `${string}(${infer AfterOpen}`
+                ? SplitBalancedParen<`(${AfterOpen}`> extends { inner: infer Inner extends string; rest: infer Rest extends string }
+                    ? Trim<Rest> extends ""
+                        ? FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>
+                        : FuncRestDispatch<Trim<Rest>, Func, Args, Inner, Tables, Aliases, S, Steps>
+                    : FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>
+                : FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>
+            : FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>;
+
+// `RestT` (trimmed) is what follows the first balanced call. An arithmetic
+// operator -> the call (typed via FunctionReturn on its TRUE arg list) is
+// the left operand. `||` -> string (guarding the `||/` cube root). A `->`
+// JSON arrow or any other shape (window clauses, …) -> today's greedy path.
+type FuncRestDispatch<
+    RestT extends string,
+    Func extends string,
+    Args extends string,
+    Inner extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[]
+> =
+    RestT extends `||${infer R}`
+        ? R extends `/${string}`
+            ? unknown
+            : string
+        : RestT extends `+${infer R}`
+            ? ArithCombineTypes<FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>
+            : RestT extends `-${infer R}`
+                ? R extends `>${string}`
+                    ? FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>
+                    : ArithCombineTypes<FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>
+                : RestT extends `*${infer R}`
+                    ? ArithCombineTypes<FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>
+                    : RestT extends `/${infer R}`
+                        ? ArithCombineTypes<FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>
+                        : RestT extends `%${infer R}`
+                            ? ArithCombineTypes<FunctionReturn<CleanIdent<Func>, Inner, Tables, Aliases, S, [any, ...Steps]>, R, Tables, Aliases, S, Steps>
+                            : FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>;
+
 // Strip a redundant fully-wrapping paren pair, repeatedly: `((expr))` and
 // `((case ...)::text)` -> the inner expression whose parens wrap the WHOLE
 // thing. Without this an outer operator hidden by a redundant wrap (e.g. the
@@ -363,9 +845,9 @@ export type ExprType<
                                         ? never
                                         : SqlTypeToTs<CastTypeName>
                                 : CE extends `${infer Func}(${infer Args})`
-                                    ? FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>
+                                    ? FuncOrArithType<CE, Func, Args, Tables, Aliases, S, Steps>
                                 : CE extends `${infer Func} (${infer Args})`
-                                    ? FunctionReturn<CleanIdent<Func>, Args, Tables, Aliases, S, [any, ...Steps]>
+                                    ? FuncOrArithType<CE, Func, Args, Tables, Aliases, S, Steps>
                                     : CE extends `${string}||${string}`
                                         ? string
                                     : CE extends `${infer JBase}->>${string}`
@@ -394,12 +876,12 @@ export type ExprType<
                                                                     ? [Ref] extends [never]
                                                                         ? IsIdentifier<CE> extends true
                                                                             ? never
-                                                                            : unknown
+                                                                            : TopLevelArithType<CE, Tables, Aliases, S, Steps>
                                                                         : Ref extends ColumnRef<infer TableKey extends string, infer Column extends string>
                                                                             ? ColumnTypeFromTableKey<TableKey, Column, S>
                                                                             : IsIdentifier<CE> extends true
                                                                                 ? never
-                                                                                : unknown
+                                                                                : TopLevelArithType<CE, Tables, Aliases, S, Steps>
                                                                     : unknown
                             // A genuine TOP-LEVEL `::T` cast. As with the JSON-text
                             // operators, a `->>` / `#>>` to the right of the cast type
@@ -480,7 +962,18 @@ export type FunctionReturn<
                             ? string
                             : Func extends "coalesce"
                                 ? UnionArgTypes<Args, Tables, Aliases, S, Steps>
-                                : unknown;
+                                // Postgres EXTRACT always returns a numeric
+                                // value regardless of field/source, so typing
+                                // it is unambiguous; it is NULL iff its source
+                                // is NULL, so propagate the argument's
+                                // nullability. An unmodeled argument types
+                                // `unknown` (which may include null) → the
+                                // conservative answer is `number | null`.
+                                : Func extends "extract"
+                                    ? null extends FirstArgType<Args, Tables, Aliases, S, Steps>
+                                        ? number | null
+                                        : number
+                                    : unknown;
 
 // Expression validation
 
@@ -608,7 +1101,7 @@ export type ExprQualifiedRefsValid<
     Tables extends string,
     Aliases extends string,
     S extends DatabaseSchema
-> = QualifiedColumnRefs<TokenizeLoose<E>, S, Tables, Aliases> extends infer Cols
+> = QualifiedRefScan<E> extends infer Cols
     ? AllTrue<Cols extends string ? ColumnRefValidLooseWith<Cols, Tables, Aliases, S> : true>
     : true;
 
@@ -617,7 +1110,7 @@ export type ExprUnqualifiedRefsValid<
     Tables extends string,
     Aliases extends string,
     S extends DatabaseSchema
-> = UnqualifiedColumnRefs<TokenizeLoose<E>, S, Tables, Aliases> extends infer Cols
+> = UnqualifiedRefScan<E, S, Tables, Aliases> extends infer Cols
     ? AllTrue<Cols extends string ? UnqualifiedColumnValid<Cols, Tables, Aliases, S> : true>
     : true;