@quereus/quereus 4.8.0 → 4.10.0

package/dist/src/runtime/emit/binary.js

@@ -6,10 +6,25 @@ import { hasRelationalDescendant } from "../../planner/analysis/scalar-subquerie
 import { emitPlanNode, emitCallFromPlan } from "../emitters.js";
 import { compareSqlValuesFast, createTypedComparator, hasSemanticOrdering, isTruthy } from "../../util/comparison.js";
 import { coerceToNumberForArithmetic } from "../../util/coercion.js";
+import { canonicalizeInteger } from "../../util/numeric-canonical.js";
+import { valueToText } from "../../util/value-text.js";
 import { simpleLike, compileLikeMatcher } from "../../util/patterns.js";
 import { tryTemporalArithmetic, tryTemporalComparison } from "./temporal-arithmetic.js";
+import { runTemporalCase, temporalOpCaseForTypes, unsupportedTemporalOp } from "../../types/temporal-ops.js";
 import { effectiveComparisonCollation } from "../../planner/analysis/comparison-collation.js";
-export function emitBinaryOp(plan, ctx) {
+import { emitScalarOp } from "./scalar-op.js";
+/**
+ * Operator dispatch for a binary node — the single entry point both consumers share, so
+ * neither has to restate which operator routes to which body. `undefined` means the node
+ * has no {@link ScalarOpSpec}: today that is exactly the AND/OR short-circuit form, whose
+ * right operand is a deferred sub-program rather than a value (see
+ * {@link buildLogicalOpSpec}). A fusion consumer treats `undefined` as "do not fuse";
+ * {@link emitBinaryOp} falls back to {@link emitShortCircuitLogicalOp}.
+ *
+ * An unsupported operator throws here rather than returning `undefined` — that is an
+ * unimplemented operator, not a node that declines to fuse.
+ */
+export function buildBinaryOpSpec(plan, ctx) {
     // Normalize operator to uppercase for case-insensitive matching of keywords
     const operator = plan.expression.operator.toUpperCase();
     switch (operator) {
@@ -18,7 +33,7 @@ export function emitBinaryOp(plan, ctx) {
         case '*':
         case '/':
         case '%':
-            return emitNumericOp(plan, ctx);
+            return buildNumericOpSpec(plan);
         case '=':
         case '==':
         case '!=':
@@ -27,20 +42,24 @@ export function emitBinaryOp(plan, ctx) {
         case '<=':
         case '>':
         case '>=':
-            return emitComparisonOp(plan, ctx);
+            return buildComparisonOpSpec(plan, ctx);
         case '||':
-            return emitConcatOp(plan, ctx);
+            return buildConcatOpSpec(plan);
         case 'AND':
         case 'OR':
         case 'XOR':
-            return emitLogicalOp(plan, ctx);
+            return buildLogicalOpSpec(plan);
         case 'LIKE':
-            return emitLikeOp(plan, ctx);
-        // TODO: emitBitwise
+            return buildLikeOpSpec(plan);
+        // TODO: bitwise operators
         default:
             quereusError(`Unsupported binary operator: ${plan.expression.operator}`, StatusCode.UNSUPPORTED, undefined, plan.expression);
     }
 }
+export function emitBinaryOp(plan, ctx) {
+    const spec = buildBinaryOpSpec(plan, ctx);
+    return spec ? emitScalarOp(spec, ctx) : emitShortCircuitLogicalOp(plan, ctx);
+}
 /** Handle arithmetic when at least one operand is bigint.
  *  Both bigint → use bigint arithmetic directly.
  *  Mixed (one bigint, one non-bigint):
@@ -50,7 +69,11 @@ export function emitBinaryOp(plan, ctx) {
 function mixedBigIntArithmetic(v1, v2, inner, innerBigInt) {
     if (typeof v1 === 'bigint' && typeof v2 === 'bigint') {
         try {
-            return innerBigInt(v1, v2);
+            // Narrow a result that lands inside the safe-integer range back to number
+            // (R1, util/numeric-canonical.ts) — on the success path only; the catch
+            // arms (division by zero, RangeError) still return null. Narrowing itself
+            // cannot throw.
+            return canonicalizeInteger(innerBigInt(v1, v2));
         }
         catch {
             return null;
@@ -64,7 +87,8 @@ function mixedBigIntArithmetic(v1, v2, inner, innerBigInt) {
     const num = typeof v1n === 'bigint' ? v2n : v1n;
     if (Number.isInteger(num)) {
         try {
-            return innerBigInt(typeof v1n === 'bigint' ? v1n : BigInt(v1n), typeof v2n === 'bigint' ? v2n : BigInt(v2n));
+            // Same success-path narrowing as the both-bigint arm above.
+            return canonicalizeInteger(innerBigInt(typeof v1n === 'bigint' ? v1n : BigInt(v1n), typeof v2n === 'bigint' ? v2n : BigInt(v2n)));
         }
         catch {
             // Fall through to float path (e.g., division by zero)
@@ -78,7 +102,43 @@ function mixedBigIntArithmetic(v1, v2, inner, innerBigInt) {
         return null;
     return result;
 }
-export function emitNumericOp(plan, ctx) {
+/**
+ * The general arithmetic body: sniff the values for a temporal shape first, then fall back
+ * to coercing numeric arithmetic.
+ *
+ * Two branches of {@link buildNumericOpSpec} share it — the temporal arm whose declared
+ * types settle nothing, and the non-temporal generic path — because value sniffing is the
+ * defined semantics for both. They differ only in the note they carry; keeping one body
+ * means they cannot come to differ in behavior.
+ */
+function buildCoercingArithmeticRun(operator, inner, innerBigInt) {
+    return function runCoercingArithmetic(_ctx, v1, v2) {
+        const temporalResult = tryTemporalArithmetic(operator, v1, v2);
+        if (temporalResult !== undefined) {
+            return temporalResult;
+        }
+        if (v1 !== null && v2 !== null) {
+            if (typeof v1 === 'bigint' || typeof v2 === 'bigint') {
+                return mixedBigIntArithmetic(v1, v2, inner, innerBigInt);
+            }
+            else {
+                const n1 = coerceToNumberForArithmetic(v1);
+                const n2 = coerceToNumberForArithmetic(v2);
+                try {
+                    const result = inner(n1, n2);
+                    if (!Number.isFinite(result))
+                        return null;
+                    return result;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+        return null;
+    };
+}
+export function buildNumericOpSpec(plan) {
     let inner;
     let innerBigInt;
     switch (plan.expression.operator) {
@@ -111,51 +171,79 @@ export function emitNumericOp(plan, ctx) {
     let run;
     let note;
     if (leftLogical.isTemporal || rightLogical.isTemporal) {
-        // Temporal path: must check temporal arithmetic first
-        run = function runTemporalArithmetic(ctx, v1, v2) {
-            const temporalResult = tryTemporalArithmetic(plan.expression.operator, v1, v2);
-            if (temporalResult !== undefined) {
-                return temporalResult;
-            }
-            if (v1 !== null && v2 !== null) {
-                if (typeof v1 === 'bigint' || typeof v2 === 'bigint') {
-                    return mixedBigIntArithmetic(v1, v2, inner, innerBigInt);
-                }
-                else {
-                    const n1 = coerceToNumberForArithmetic(v1);
-                    const n2 = coerceToNumberForArithmetic(v2);
-                    try {
-                        const result = inner(n1, n2);
-                        if (!Number.isFinite(result))
-                            return null;
-                        return result;
-                    }
-                    catch {
-                        return null;
-                    }
-                }
-            }
-            return null;
-        };
-        note = `${plan.expression.operator}(temporal)`;
+        // Temporal path. Both operands' declared logical types are already in hand — that
+        // is *why* this branch was selected — so the (operator, left kind, right kind)
+        // lookup into the operation table (types/temporal-ops.ts) happens once here rather
+        // than once per row. Same lookup `BinaryOpNode.generateType` used to announce the
+        // result type, through the same function, so the two cannot select different cases.
+        // Three arms, chosen at emit:
+        const { kinds, entry } = temporalOpCaseForTypes(plan.expression.operator, leftLogical, rightLogical);
+        if (kinds && entry) {
+            // (1) Specialized: the case is fixed, so the per-row path is one call into the
+            // shared envelope — no value sniffing at all.
+            //
+            // This arm TRUSTS the declared types. A DATE-declared operand actually holding
+            // `'garbage'` returns null here (runTemporalCase's catch), where the sniffing
+            // path below would have raised `Unsupported temporal operation`. That is the
+            // intended trade: write-side coercion enforces declared logical types on every
+            // normal path, so only a misbehaving virtual table can produce such a value.
+            run = function runTemporalCased(_ctx, v1, v2) {
+                return runTemporalCase(entry, v1, v2);
+            };
+            note = `${plan.expression.operator}(temporal-${kinds[0]}-${kinds[1]})`;
+        }
+        else if (kinds) {
+            // (2) Statically unsupported: both kinds are known and the table has no case
+            // for them (DATE + DATE, DATE * NUMBER, TIME − DATE, anything with `%`), so no
+            // combination of runtime values can succeed.
+            //
+            // The throw deliberately stays at RUNTIME rather than moving to emit/plan time.
+            // Today the error is raised only when a row is actually evaluated, so
+            // `select case when 0 then date_a + date_b else 1 end`, the same expression
+            // under `where 1 = 0`, and the same expression over an empty table all succeed.
+            // Hoisting the throw would turn each into a hard failure for no gain — a
+            // constant-throw closure costs nothing per row on the paths that never run it.
+            //
+            // The null check is load-bearing: `date_a + date_b` with a NULL operand returns
+            // null today rather than erroring, and must keep doing so.
+            run = function runTemporalUnsupported(_ctx, v1, v2) {
+                if (v1 === null || v2 === null)
+                    return null;
+                unsupportedTemporalOp();
+            };
+            note = `${plan.expression.operator}(temporal-unsupported)`;
+        }
+        else {
+            // (3) Fallback: at least one operand is TEXT / ANY / NULL / TIMESTAMP / a
+            // plugin-registered temporal type, so the declared types cannot settle the
+            // case. Runtime sniffing IS the defined semantics there (a TEXT column holding
+            // a duration string is a supported shape), so this arm is the generic body
+            // below under a different note — same function, so they cannot drift.
+            run = buildCoercingArithmeticRun(plan.expression.operator, inner, innerBigInt);
+            note = `${plan.expression.operator}(temporal)`;
+        }
     }
     else if (leftLogical.isNumeric && rightLogical.isNumeric) {
         // Numeric-only path: skip temporal check and coercion entirely
+        //
+        // NOTE: accepted tradeoff — the two null checks plus two `typeof === 'bigint'`
+        // checks below are NOT collapsed into one `typeof === 'number'` pair with the
+        // null/bigint handling behind a fallback. Measured at 1.19 ns vs 1.22 ns per
+        // operation (isolated microbench, see `compareSqlValuesFast` in
+        // util/comparison.ts) — no difference at all, so the guard would be pure noise.
         run = function runNumericOnly(ctx, v1, v2) {
             if (v1 !== null && v2 !== null) {
                 if (typeof v1 === 'bigint' || typeof v2 === 'bigint') {
                     return mixedBigIntArithmetic(v1, v2, inner, innerBigInt);
                 }
                 else {
-                    try {
-                        const result = inner(v1, v2);
-                        if (!Number.isFinite(result))
-                            return null;
-                        return result;
-                    }
-                    catch {
+                    // No try/catch: `inner` over plain numbers cannot throw (division by
+                    // zero yields Infinity/NaN, caught by the finite check below); only
+                    // the bigint arm above can throw (handled inside mixedBigIntArithmetic).
+                    const result = inner(v1, v2);
+                    if (!Number.isFinite(result))
                         return null;
-                    }
+                    return result;
                 }
             }
             return null;
@@ -164,42 +252,16 @@ export function emitNumericOp(plan, ctx) {
     }
     else {
         // Generic path: temporal check + coercion (for TEXT or mixed types)
-        run = function runGenericArithmetic(ctx, v1, v2) {
-            const temporalResult = tryTemporalArithmetic(plan.expression.operator, v1, v2);
-            if (temporalResult !== undefined) {
-                return temporalResult;
-            }
-            if (v1 !== null && v2 !== null) {
-                if (typeof v1 === 'bigint' || typeof v2 === 'bigint') {
-                    return mixedBigIntArithmetic(v1, v2, inner, innerBigInt);
-                }
-                else {
-                    const n1 = coerceToNumberForArithmetic(v1);
-                    const n2 = coerceToNumberForArithmetic(v2);
-                    try {
-                        const result = inner(n1, n2);
-                        if (!Number.isFinite(result))
-                            return null;
-                        return result;
-                    }
-                    catch {
-                        return null;
-                    }
-                }
-            }
-            return null;
-        };
+        run = buildCoercingArithmeticRun(plan.expression.operator, inner, innerBigInt);
         note = `${plan.expression.operator}(numeric)`;
     }
-    const leftExpr = emitPlanNode(plan.left, ctx);
-    const rightExpr = emitPlanNode(plan.right, ctx);
     return {
-        params: [leftExpr, rightExpr],
-        run: asRun(run),
+        operands: [plan.left, plan.right],
+        run,
         note
     };
 }
-export function emitComparisonOp(plan, ctx) {
+export function buildComparisonOpSpec(plan, ctx) {
     const leftType = plan.left.getType();
     const rightType = plan.right.getType();
     // One shared, symmetric resolution for plan-time facts and runtime behavior
@@ -241,6 +303,11 @@ export function emitComparisonOp(plan, ctx) {
     else if (!needsTemporalCheck && bothSameCategory) {
         // Fast same-category comparison: no temporal check, no coercion needed
         // Use compareSqlValuesFast which handles runtime type mismatches gracefully
+        //
+        // NOTE: accepted tradeoff — this does NOT further specialize on the known category
+        // (both-TEXT → guarded `typeof` pair → collation call, both-numeric → guarded
+        // inline three-way). Measured and declined; the numbers and the revisit condition
+        // are on `compareSqlValuesFast` in util/comparison.ts.
         const cmpToResult = buildCmpToResult(operator, plan);
         run = function runSameCategoryCompare(ctx, v1, v2) {
             if (v1 === null || v2 === null)
@@ -254,11 +321,9 @@ export function emitComparisonOp(plan, ctx) {
         run = buildGenericComparisonRun(operator, plan, collationFunc);
         noteTag = 'compare';
     }
-    const leftExpr = emitPlanNode(plan.left, ctx);
-    const rightExpr = emitPlanNode(plan.right, ctx);
     return {
-        params: [leftExpr, rightExpr],
-        run: asRun(run),
+        operands: [plan.left, plan.right],
+        run,
         note: `${plan.expression.operator}(${noteTag}${collationName !== 'BINARY' ? ` ${collationName}` : ''})`
     };
 }
@@ -297,121 +362,146 @@ function buildGenericComparisonRun(operator, plan, collationFunc) {
         return cmpToResult(compareSqlValuesFast(v1, v2, collationFunc));
     };
 }
-export function emitConcatOp(plan, ctx) {
+export function buildConcatOpSpec(plan) {
     function run(ctx, v1, v2) {
         // SQL concatenation: NULL || anything -> NULL
         if (v1 === null || v2 === null)
             return null;
-        // Convert both operands to strings
-        const s1 = String(v1);
-        const s2 = String(v2);
-        return s1 + s2;
+        // Convert both operands through the shared value-to-text rule, so `b || ''`
+        // spells a blob or a JSON document exactly as `cast(b as text)` does.
+        return valueToText(v1) + valueToText(v2);
     }
-    const leftExpr = emitPlanNode(plan.left, ctx);
-    const rightExpr = emitPlanNode(plan.right, ctx);
     return {
-        params: [leftExpr, rightExpr],
-        run: asRun(run),
+        operands: [plan.left, plan.right],
+        run,
         note: '||(concat)'
     };
 }
-export function emitLogicalOp(plan, ctx) {
-    // Normalize operator to uppercase for case-insensitive matching
-    const operator = plan.expression.operator.toUpperCase();
-    // SQL three-valued-logic combine — single source of truth shared by the eager
-    // `run` and the deferred `runShortCircuit` path, so the two cannot diverge (the
-    // parity tests in test/and-or-short-circuit.spec.ts guard exactly this). Coerce
-    // non-NULL operands to a boolean using SQL truthiness (isTruthy) rather than JS
-    // truthiness so that values like blobs and non-numeric strings agree with how
-    // FilterNode/CASE/NOT treat them — otherwise `<blob> AND true` and a bare
-    // `<blob>` predicate diverge.
-    function combineLogical(v1, v2) {
+/** false dominates; else NULL if any operand is NULL; else true. */
+const combineAnd = (b1, b2) => {
+    if (b1 === false || b2 === false)
+        return false;
+    if (b1 === null || b2 === null)
+        return null;
+    return true;
+};
+/** true dominates; else NULL if any operand is NULL; else false. */
+const combineOr = (b1, b2) => {
+    if (b1 === true || b2 === true)
+        return true;
+    if (b1 === null || b2 === null)
+        return null;
+    return false;
+};
+/** NULL with anything -> NULL; else logical inequality. */
+const combineXor = (b1, b2) => {
+    if (b1 === null || b2 === null)
+        return null;
+    return b1 !== b2;
+};
+function selectLogicalCombine(operator, plan) {
+    switch (operator) {
+        case 'AND': return combineAnd;
+        case 'OR': return combineOr;
+        case 'XOR': return combineXor;
+        default:
+            quereusError(`Unsupported logical operator: ${plan.expression.operator}`, StatusCode.UNSUPPORTED, undefined, plan.expression);
+    }
+}
+/**
+ * The 3VL combine over raw operand values, resolved once at emit time (not per row) —
+ * single source of truth shared by the eager spec body and the deferred short-circuit
+ * path below, so the two cannot diverge (the parity tests in
+ * test/and-or-short-circuit.spec.ts guard exactly this).
+ *
+ * Coerces non-NULL operands to a boolean using SQL truthiness (isTruthy) rather than
+ * JS truthiness so that values like blobs and non-numeric strings agree with how
+ * FilterNode/CASE/NOT treat them — otherwise `<blob> AND true` and a bare `<blob>`
+ * predicate diverge.
+ */
+function buildCombineLogical(operator, plan) {
+    const combine = selectLogicalCombine(operator, plan);
+    return function combineLogical(v1, v2) {
         const b1 = v1 === null ? null : isTruthy(v1);
         const b2 = v2 === null ? null : isTruthy(v2);
-        switch (operator) {
-            case 'AND': {
-                // false dominates; else NULL if any operand is NULL; else true.
-                if (b1 === false || b2 === false)
-                    return false;
-                if (b1 === null || b2 === null)
-                    return null;
-                return true;
-            }
-            case 'OR': {
-                // true dominates; else NULL if any operand is NULL; else false.
-                if (b1 === true || b2 === true)
-                    return true;
-                if (b1 === null || b2 === null)
-                    return null;
-                return false;
-            }
-            case 'XOR': {
-                // NULL with anything -> NULL; else logical inequality.
-                if (b1 === null || b2 === null)
-                    return null;
-                return b1 !== b2;
-            }
-            default:
-                quereusError(`Unsupported logical operator: ${plan.expression.operator}`, StatusCode.UNSUPPORTED, undefined, plan.expression);
-        }
-    }
-    // Eager two-param combine. Used for XOR (both operands always required) and for
-    // AND/OR whose right operand is cheap (no subquery) — the zero-overhead path.
+        return combine(b1, b2);
+    };
+}
+/**
+ * Short-circuit deferral gate: AND/OR whose right operand contains a subquery
+ * (a scalar/IN/EXISTS subquery — a relational descendant). Such an operand is emitted
+ * as an on-demand callback and evaluated lazily, only when the left operand does not
+ * already decide the result (`false AND x` → false; `true OR x` → true). This stops an
+ * expensive/side-effecting subquery from running on every row for nothing. Left stays
+ * eager — it is always needed and always evaluated first, so operand order is unchanged.
+ *
+ * NOTE: only a *subquery* right operand defers. A non-subquery expensive scalar operand
+ * (deeply nested arithmetic, or a volatile/slow UDF called directly rather than inside a
+ * subquery) is still evaluated eagerly. Such operands are rare and the dominant expensive
+ * case in SQL is the subquery; if a non-subquery volatile/expensive scalar operand ever
+ * shows up hot, extend this gate with a cost or volatility check.
+ */
+function usesShortCircuit(plan, operator) {
+    return (operator === 'AND' || operator === 'OR') && hasRelationalDescendant(plan.right);
+}
+/**
+ * Eager two-operand combine. Used for XOR (both operands always required) and for
+ * AND/OR whose right operand is cheap (no subquery) — the zero-overhead path.
+ *
+ * `undefined` for the short-circuit form, whose right operand is a `SubProgram` param
+ * rather than a value and whose body returns `MaybePromise` — not a {@link ScalarOpSpec}
+ * body. Consumers fall back: the emitter below builds that Instruction itself, and a
+ * fusion consumer must decline to fuse.
+ */
+export function buildLogicalOpSpec(plan) {
+    // Normalize operator to uppercase for case-insensitive matching
+    const operator = plan.expression.operator.toUpperCase();
+    if (usesShortCircuit(plan, operator))
+        return undefined;
+    const combineLogical = buildCombineLogical(operator, plan);
     function run(_ctx, v1, v2) {
         return combineLogical(v1, v2);
     }
+    return {
+        operands: [plan.left, plan.right],
+        run,
+        note: `${plan.expression.operator}(logical)`
+    };
+}
+function emitShortCircuitLogicalOp(plan, ctx) {
+    const operator = plan.expression.operator.toUpperCase();
+    const combineLogical = buildCombineLogical(operator, plan);
     const leftExpr = emitPlanNode(plan.left, ctx);
-    // Short-circuit deferral: for AND/OR whose right operand contains a subquery
-    // (a scalar/IN/EXISTS subquery — a relational descendant), emit the right
-    // operand as an on-demand callback and evaluate it lazily, only when the left
-    // operand does not already decide the result (`false AND x` → false;
-    // `true OR x` → true). This stops an expensive/side-effecting subquery from
-    // running on every row for nothing. Left stays eager — it is always needed
-    // and always evaluated first, so operand order is unchanged.
-    //
-    // NOTE: only a *subquery* right operand defers. A non-subquery expensive
-    // scalar operand (deeply nested arithmetic, or a volatile/slow UDF called
-    // directly rather than inside a subquery) is still evaluated eagerly. Such
-    // operands are rare and the dominant expensive case in SQL is the subquery;
-    // if a non-subquery volatile/expensive scalar operand ever shows up hot,
-    // extend this gate with a cost or volatility check.
-    if ((operator === 'AND' || operator === 'OR') && hasRelationalDescendant(plan.right)) {
-        const rightCall = emitCallFromPlan(plan.right, ctx);
-        function runShortCircuit(ctx, v1, rightFn) {
-            // Left decides — the right operand is never fetched (`false AND x` → false;
-            // `true OR x` → true). Same SQL truthiness as the eager path.
-            const b1 = v1 === null ? null : isTruthy(v1);
-            if (operator === 'AND' && b1 === false)
-                return false;
-            if (operator === 'OR' && b1 === true)
-                return true;
-            // Otherwise fetch the deferred right and combine with the shared 3VL
-            // (combineLogical) — byte-identical to the eager path. Stay synchronous
-            // when the right sub-program resolves synchronously; only take the
-            // microtask hop on a genuinely async subquery (see docs/runtime.md
-            // "Avoid a per-row microtask hop on the synchronous fast path"). A
-            // left-decides row returned above, so it never pays an async tick.
-            const raw = rightFn(ctx);
-            return raw instanceof Promise
-                ? raw.then(v2 => combineLogical(v1, v2))
-                : combineLogical(v1, raw);
-        }
-        return {
-            params: [leftExpr, rightCall],
-            run: asRun(runShortCircuit),
-            note: `${plan.expression.operator}(logical short-circuit)`
-        };
+    const rightCall = emitCallFromPlan(plan.right, ctx);
+    // The left-operand value that decides the result on its own, resolved once at
+    // emit time: `false AND x` → false, `true OR x` → true. Also the result itself.
+    const decidingValue = operator === 'AND' ? false : true;
+    function runShortCircuit(ctx, v1, rightFn) {
+        // Left decides — the right operand is never fetched (`false AND x` → false;
+        // `true OR x` → true). Same SQL truthiness as the eager path.
+        const b1 = v1 === null ? null : isTruthy(v1);
+        if (b1 === decidingValue)
+            return decidingValue;
+        // Otherwise fetch the deferred right and combine with the shared 3VL
+        // (combineLogical) — byte-identical to the eager path. Stay synchronous
+        // when the right sub-program resolves synchronously; only take the
+        // microtask hop on a genuinely async subquery (see docs/runtime.md
+        // "Avoid a per-row microtask hop on the synchronous fast path"). A
+        // left-decides row returned above, so it never pays an async tick.
+        const raw = rightFn(ctx);
+        return raw instanceof Promise
+            ? raw.then(v2 => combineLogical(v1, v2))
+            : combineLogical(v1, raw);
     }
-    const rightExpr = emitPlanNode(plan.right, ctx);
     return {
-        params: [leftExpr, rightExpr],
-        run: asRun(run),
-        note: `${plan.expression.operator}(logical)`
+        params: [leftExpr, rightCall],
+        run: asRun(runShortCircuit),
+        note: `${plan.expression.operator}(logical short-circuit)`
     };
 }
 /**
  * If `node` is a literal-constant, non-NULL pattern, return the exact string the
- * per-row path would derive from it (`String(value)`), otherwise undefined.
+ * per-row path would derive from it ({@link valueToText}), otherwise undefined.
  * A NULL literal, a not-yet-resolved Promise value, or any non-literal node
  * falls through to the dynamic (memoized) per-row path so semantics are
  * unchanged. Cast/collate-wrapped literals are intentionally NOT unwrapped —
@@ -423,14 +513,14 @@ function constLikePattern(node) {
     const value = node.expression.value;
     if (value === null || value === undefined || value instanceof Promise)
         return undefined;
-    return String(value);
+    return valueToText(value);
 }
-export function emitLikeOp(plan, ctx) {
-    const leftExpr = emitPlanNode(plan.left, ctx);
+export function buildLikeOpSpec(plan) {
     // Fast path: the pattern operand is a literal constant. Compile the matcher
     // once here at emit time and capture it in the closure, so no per-row compile
-    // or cache lookup happens at all. The literal operand is not emitted as a
-    // param since its value is already baked into `matcher`.
+    // or cache lookup happens at all. The literal operand is NOT declared as an
+    // operand since its value is already baked into `matcher` — this spec's arity
+    // is one, while the plan node still has two children.
     const constPattern = constLikePattern(plan.right);
     if (constPattern !== undefined) {
         const matcher = compileLikeMatcher(constPattern);
@@ -438,11 +528,11 @@ export function emitLikeOp(plan, ctx) {
             // text LIKE <const>: NULL text → NULL, else run the pre-compiled matcher.
             if (text === null)
                 return null;
-            return matcher(String(text));
+            return matcher(valueToText(text));
         }
         return {
-            params: [leftExpr],
-            run: asRun(runConstPattern),
+            operands: [plan.left],
+            run: runConstPattern,
             note: 'LIKE(like-const)'
         };
     }
@@ -452,15 +542,16 @@ export function emitLikeOp(plan, ctx) {
         if (text === null || pattern === null) {
             return null;
         }
-        // Convert both operands to strings and perform LIKE matching (memoized compile).
-        const textStr = String(text);
-        const patternStr = String(pattern);
+        // Convert both operands through the shared value-to-text rule and perform LIKE
+        // matching (memoized compile). Must agree with `constLikePattern` above, or the
+        // constant-pattern fast path starts answering differently from this one.
+        const textStr = valueToText(text);
+        const patternStr = valueToText(pattern);
         return simpleLike(patternStr, textStr);
     }
-    const rightExpr = emitPlanNode(plan.right, ctx);
     return {
-        params: [leftExpr, rightExpr],
-        run: asRun(run),
+        operands: [plan.left, plan.right],
+        run,
         note: 'LIKE(like)'
     };
 }