@minnowdb/core 0.6.0 → 0.6.2

package/dist/engine/point-read.d.ts

@@ -0,0 +1,57 @@
+import type { CompiledQuery, QueryValue } from "../plan/model.js";
+export type PointReadValue = boolean | number | string | Date;
+export interface PointReadEquality {
+    column: string;
+    value: PointReadValue;
+}
+export interface PointReadShape {
+    table: string;
+    /** Conjunctive equalities, in predicate order; may repeat a column. */
+    equalities: PointReadEquality[];
+    /** Plain column projections, in select order. */
+    select: Array<{
+        column: string;
+        alias: string;
+    }>;
+}
+/** The statement-shaped half of the analysis, computed once per cached plan. */
+interface PointReadTemplate {
+    table: string;
+    equalities: Array<{
+        column: string;
+        value: PointReadValue;
+    } | {
+        column: string;
+        parameter: number;
+    }>;
+    select: Array<{
+        column: string;
+        alias: string;
+    }>;
+}
+/**
+ * Test-only escape hatch and counters. Not exported from any public entry point: in-repo
+ * differential suites import this module directly to force the ordinary executor and to
+ * assert the fast path actually served eligible statements.
+ */
+export declare const pointReadTestHooks: {
+    disabled: boolean;
+    attempted: number;
+    served: number;
+};
+/** The template for a cached compiled plan, analyzed once per statement. */
+export declare function cachedPointReadTemplate(plan: CompiledQuery): PointReadTemplate | null;
+/**
+ * Substitutes this call's parameters into the statement template. Undefined means a parameter
+ * carries a value the fast path cannot compare exactly (NULL, a non-finite number, an invalid
+ * Date, or a non-storage value), and the ordinary executor must decide what it means.
+ */
+export declare function resolvePointReadShape(template: PointReadTemplate, params: readonly QueryValue[]): PointReadShape | undefined;
+/** Whether the array is non-strictly ascending; memoized per immutable decoded array. */
+export declare function valuesAreAscending(values: Float64Array): boolean;
+/** The [begin, end) run of slots equal to `target` over an ascending array. */
+export declare function equalRunRange(values: Float64Array, target: number): {
+    begin: number;
+    end: number;
+};
+export {};

package/dist/engine/point-read.js

@@ -0,0 +1,189 @@
+/**
+ * Shape analysis for the keyed point-read fast path: a single-table conjunction of
+ * column-equals-literal predicates that covers the table's unique key, projecting plain
+ * columns. Such a statement addresses at most one row, so execution can skip parameter
+ * binding, plan cloning, streamed-view construction, and the vector pipeline entirely and
+ * answer from cached decoded blocks. Anything this module cannot prove eligible falls back to
+ * the ordinary executor, which stays the authority on errors and semantics.
+ */
+import { dateMilliseconds } from "../date-value.js";
+/**
+ * Test-only escape hatch and counters. Not exported from any public entry point: in-repo
+ * differential suites import this module directly to force the ordinary executor and to
+ * assert the fast path actually served eligible statements.
+ */
+export const pointReadTestHooks = {
+    disabled: false,
+    attempted: 0,
+    served: 0,
+};
+const DUAL_TABLE = "(dual)";
+/** A base-table column reference: bare, or qualified by the base source's alias. */
+function baseColumnReference(expression, alias) {
+    if (expression.kind !== "column")
+        return undefined;
+    const reference = expression.reference;
+    const dot = reference.indexOf(".");
+    if (dot < 0)
+        return reference;
+    if (reference.slice(0, dot) !== alias)
+        return undefined;
+    const column = reference.slice(dot + 1);
+    // A nested qualifier ("a.b.c") is not a base-table column.
+    return column.includes(".") ? undefined : column;
+}
+/** A usable equality operand: a plain non-null literal of a storage type, verified exactly. */
+function equalityValue(value) {
+    if (value === null)
+        return undefined;
+    if (typeof value === "number" && !Number.isFinite(value))
+        return undefined;
+    // Strings in the engine's protected NUL namespace are wrapped at the write boundary, so a
+    // raw comparison against stored bytes would not reproduce the ordinary path's answer.
+    if (typeof value === "string" && value.startsWith("\u0000"))
+        return undefined;
+    // The internal-slot read never invokes caller-controlled Date methods.
+    if (value instanceof Date && Number.isNaN(dateMilliseconds(value)))
+        return undefined;
+    return value;
+}
+function templateEquality(expression) {
+    if (expression.kind === "parameter")
+        return { parameter: expression.index };
+    if (expression.kind !== "literal")
+        return undefined;
+    // Tagged internal values and logical-domain literals compare under domain rules the fast
+    // path does not implement; a NULL literal never equals anything.
+    if (expression.internalSqlValue === true || expression.sqlDomain !== undefined)
+        return undefined;
+    const value = equalityValue(expression.value);
+    return value === undefined ? undefined : { value };
+}
+/**
+ * Recognizes the eligible statement shape. Purely syntactic: catalog checks (column existence,
+ * types, key coverage, view expansion, physical history) belong to the caller, which falls
+ * back to the ordinary executor whenever they cannot be proven.
+ */
+function pointReadTemplate(plan) {
+    const base = plan.base;
+    if (base.table === DUAL_TABLE ||
+        base.derived !== undefined ||
+        base.union !== undefined ||
+        base.recursive !== undefined ||
+        base.windowed !== undefined ||
+        base.lateral === true ||
+        base.columnAliases !== undefined ||
+        plan.joins.length > 0 ||
+        plan.groupBy.length > 0 ||
+        plan.having.length > 0 ||
+        plan.orderBy.length > 0 ||
+        plan.select.length === 0 ||
+        plan.predicates.length === 0 ||
+        plan.limit !== undefined ||
+        plan.offset !== undefined ||
+        plan.limitParameter !== undefined ||
+        plan.offsetParameter !== undefined ||
+        (plan.limitValidationParameters?.length ?? 0) > 0 ||
+        (plan.offsetValidationParameters?.length ?? 0) > 0 ||
+        plan.limitWithTies === true ||
+        plan.distinctWildcard === true ||
+        plan.usesStatementDatetime === true ||
+        plan.usesSequenceCalls === true ||
+        plan.usesVolatileFunctions === true) {
+        return undefined;
+    }
+    const select = [];
+    for (const item of plan.select) {
+        const column = baseColumnReference(item.expression, base.alias);
+        if (column === undefined)
+            return undefined;
+        select.push({ column, alias: item.alias });
+    }
+    const equalities = [];
+    for (const predicate of plan.predicates) {
+        if (predicate.operator !== "=" || predicate.escape !== undefined)
+            return undefined;
+        const leftColumn = baseColumnReference(predicate.left, base.alias);
+        const rightColumn = baseColumnReference(predicate.right, base.alias);
+        const operand = leftColumn !== undefined && rightColumn === undefined
+            ? templateEquality(predicate.right)
+            : rightColumn !== undefined && leftColumn === undefined
+                ? templateEquality(predicate.left)
+                : undefined;
+        const column = leftColumn ?? rightColumn;
+        if (operand === undefined || column === undefined)
+            return undefined;
+        equalities.push({ column, ...operand });
+    }
+    return { table: base.table, equalities, select };
+}
+const templates = new WeakMap();
+/** The template for a cached compiled plan, analyzed once per statement. */
+export function cachedPointReadTemplate(plan) {
+    const cached = templates.get(plan);
+    if (cached !== undefined)
+        return cached;
+    const template = pointReadTemplate(plan) ?? null;
+    templates.set(plan, template);
+    return template;
+}
+/**
+ * Substitutes this call's parameters into the statement template. Undefined means a parameter
+ * carries a value the fast path cannot compare exactly (NULL, a non-finite number, an invalid
+ * Date, or a non-storage value), and the ordinary executor must decide what it means.
+ */
+export function resolvePointReadShape(template, params) {
+    const equalities = [];
+    for (const entry of template.equalities) {
+        if ("value" in entry) {
+            equalities.push(entry);
+            continue;
+        }
+        const raw = params[entry.parameter];
+        if (raw === undefined)
+            return undefined;
+        const value = equalityValue(raw);
+        if (value === undefined)
+            return undefined;
+        equalities.push({ column: entry.column, value });
+    }
+    return { table: template.table, equalities, select: template.select };
+}
+const ascendingRuns = new WeakMap();
+/** Whether the array is non-strictly ascending; memoized per immutable decoded array. */
+export function valuesAreAscending(values) {
+    const cached = ascendingRuns.get(values);
+    if (cached !== undefined)
+        return cached;
+    let ascending = true;
+    for (let index = 1; index < values.length; index += 1) {
+        if ((values[index] ?? 0) < (values[index - 1] ?? 0)) {
+            ascending = false;
+            break;
+        }
+    }
+    ascendingRuns.set(values, ascending);
+    return ascending;
+}
+/** The [begin, end) run of slots equal to `target` over an ascending array. */
+export function equalRunRange(values, target) {
+    let low = 0;
+    let high = values.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if ((values[middle] ?? 0) < target)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    const begin = low;
+    high = values.length;
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+        if ((values[middle] ?? 0) <= target)
+            low = middle + 1;
+        else
+            high = middle;
+    }
+    return { begin, end: low };
+}

package/dist/engine/query.d.ts

@@ -583,6 +583,12 @@ export declare function distinctFromComparison(left: unknown, right: unknown): b
 export declare function evaluateBooleanExpression(expression: Expression, evaluateValue: (expression: Expression) => unknown): boolean | null;
 export declare function comparisonHolds(operator: PredicateOperator, leftValue: unknown, rightValue: unknown): boolean;
 export declare function hasAggregate(expression: Expression): boolean;
+/** One root aggregate call, using the same canonical set as parsing and execution. */
+export declare function isAggregateCall(expression: Expression): expression is Extract<Expression, {
+    kind: "call";
+}> & {
+    name: AggregateName;
+};
 /** The column references inside one expression; a subquery contributes none (its own scope). */
 export declare function expressionColumnNames(expression: Expression): string[];
 export declare function expressionColumns(expression: Expression): string[];

package/dist/engine/query.js

@@ -800,6 +800,7 @@ const aggregateNames = new Set([
     "MAX",
     "JSON_ARRAYAGG",
     "STRING_AGG",
+    "MINNOW_SINGLE_VALUE",
 ]);
 /** Set functions the parser builds from COUNT/SUM rather than from their own accumulator. */
 const statisticalAggregates = new Set([
@@ -1502,8 +1503,12 @@ export function containsParameter(expression) {
     return childExpressions(expression).some(containsParameter);
 }
 export function blockHasParameters(block) {
-    if (block.limitParameter !== undefined || block.offsetParameter !== undefined)
+    if (block.limitParameter !== undefined ||
+        block.offsetParameter !== undefined ||
+        (block.limitValidationParameters?.length ?? 0) > 0 ||
+        (block.offsetValidationParameters?.length ?? 0) > 0) {
         return true;
+    }
     const expressions = [];
     forEachBlockExpression(block, (expression) => expressions.push(expression));
     return (expressions.some(containsParameter) ||
@@ -1608,6 +1613,14 @@ function bindBlock(block, values) {
         block.offset = validateOffset(numeric(values[block.offsetParameter] ?? null));
         delete block.offsetParameter;
     }
+    for (const index of block.limitValidationParameters ?? []) {
+        validateLimit(numeric(values[index] ?? null));
+    }
+    for (const index of block.offsetValidationParameters ?? []) {
+        validateOffset(numeric(values[index] ?? null));
+    }
+    delete block.limitValidationParameters;
+    delete block.offsetValidationParameters;
     for (const item of block.select)
         item.expression = bindExpression(item.expression, values);
     for (const predicate of [...block.predicates, ...block.having]) {
@@ -1892,6 +1905,7 @@ export function inferBlockSchema(plan, schemas) {
             expression.name === "AVG" ||
             expression.name === "MIN" ||
             expression.name === "MAX" ||
+            expression.name === "MINNOW_SINGLE_VALUE" ||
             expression.name === "COALESCE" ||
             expression.name === "NULLIF" ||
             expression.name === "GREATEST" ||
@@ -3790,6 +3804,13 @@ function evaluate(expression, context, group) {
                 if (group === undefined)
                     throw new TypeError(`${expression.name} requires grouped execution`);
                 const argument = expression.arguments[0] ?? { kind: "wildcard" };
+                if (expression.name === "MINNOW_SINGLE_VALUE") {
+                    if (group.length > 1) {
+                        throw new TypeError(`A scalar subquery returned ${String(group.length)} rows`);
+                    }
+                    const row = group[0];
+                    return row === undefined ? null : evaluate(argument, row);
+                }
                 if (expression.name === "STRING_AGG") {
                     const delimiter = expression.arguments[1];
                     if (delimiter === undefined)
@@ -3847,12 +3868,44 @@ function evaluate(expression, context, group) {
                             String(externalSqlDomainValue(member.value)))
                         .join(""));
                 }
+                if (expression.name === "JSON_ARRAYAGG") {
+                    let members = group.map((row) => ({
+                        value: argument.kind === "wildcard" ? 1 : evaluate(argument, row),
+                        order: (expression.aggregateOrderBy ?? []).map((item) => evaluate(item.expression, row)),
+                    }));
+                    if (expression.distinct === true) {
+                        const seen = new Set();
+                        members = members.filter(({ value }) => {
+                            const key = value instanceof Date ? ` d${String(dateMilliseconds(value))}` : value;
+                            if (seen.has(key))
+                                return false;
+                            seen.add(key);
+                            return true;
+                        });
+                    }
+                    if ((expression.aggregateOrderBy?.length ?? 0) > 0) {
+                        members.sort((left, right) => {
+                            for (const [index, order] of (expression.aggregateOrderBy ?? []).entries()) {
+                                const a = left.order[index];
+                                const b = right.order[index];
+                                const placed = nullOrder(a, b, order.nulls, order.direction);
+                                if (placed !== undefined && placed !== 0)
+                                    return placed;
+                                const compared = compareValues(a, b);
+                                if (compared !== 0)
+                                    return order.direction === "desc" ? -compared : compared;
+                            }
+                            return 0;
+                        });
+                    }
+                    return members.length === 0
+                        ? null
+                        : preservedJsonDomainValue(jsonConstructor("JSON_ARRAY", members.map(({ value }) => value)));
+                }
                 let values = argument.kind === "wildcard"
                     ? group.map(() => 1)
                     : group.map((row) => evaluate(argument, row));
-                if (expression.name !== "JSON_ARRAYAGG") {
-                    values = values.filter((value) => value !== null && value !== undefined);
-                }
+                values = values.filter((value) => value !== null && value !== undefined);
                 if (expression.distinct === true) {
                     const seen = new Set();
                     values = values.filter((value) => {
@@ -3874,11 +3927,6 @@ function evaluate(expression, context, group) {
                             const sum = sumNumericValues(values);
                             return exactNumericBinary("/", sum, values.length) ?? numeric(sum) / values.length;
                         })();
-                if (expression.name === "JSON_ARRAYAGG") {
-                    return values.length === 0
-                        ? null
-                        : preservedJsonDomainValue(jsonConstructor("JSON_ARRAY", values));
-                }
                 if (expression.name === "MIN")
                     return values.reduce((best, value) => (best === undefined || compareValues(value, best) < 0 ? value : best), undefined);
                 return values.reduce((best, value) => (best === undefined || compareValues(value, best) > 0 ? value : best), undefined);
@@ -4330,6 +4378,10 @@ export function hasAggregate(expression) {
     }
     return childExpressions(expression).some(hasAggregate);
 }
+/** One root aggregate call, using the same canonical set as parsing and execution. */
+export function isAggregateCall(expression) {
+    return expression.kind === "call" && aggregateNames.has(expression.name);
+}
 function validateGrouping(plan) {
     const grouped = plan.groupBy.length > 0 || plan.select.some((item) => hasAggregate(item.expression));
     if (!grouped)
@@ -5336,7 +5388,7 @@ class Parser {
                 rows: [[]],
                 defaultValues: true,
                 ...this.#onConflictClause(table),
-                ...this.#returningClause(),
+                ...this.#returningClause(table),
             };
         }
         if (this.#isKeyword("SELECT")) {
@@ -5353,7 +5405,7 @@ class Parser {
                 columns,
                 rows: [],
                 query,
-                ...this.#returningClause(),
+                ...this.#returningClause(table),
             };
         }
         this.#keyword("VALUES");
@@ -5380,7 +5432,7 @@ class Parser {
             columns,
             rows,
             ...this.#onConflictClause(table),
-            ...this.#returningClause(),
+            ...this.#returningClause(table),
         };
     }
     #onConflictClause(table) {
@@ -5447,8 +5499,8 @@ class Parser {
             },
         };
     }
-    /** RETURNING * or RETURNING col, ... — the engine's runStatement implements the semantics. */
-    #returningClause() {
+    /** RETURNING *, target.*, or [target.]col, ... — execution owns the row semantics. */
+    #returningClause(table) {
         if (!this.#isKeyword("RETURNING"))
             return {};
         this.#keyword("RETURNING");
@@ -5458,7 +5510,23 @@ class Parser {
         }
         const columns = [];
         for (;;) {
-            columns.push(this.#identifier());
+            const first = this.#identifier();
+            if (this.#punctuation(".")) {
+                if (first !== table) {
+                    throw new TypeError(`RETURNING qualifier must name the target table: ${table}`);
+                }
+                if (this.#peek().text === "*") {
+                    this.#index += 1;
+                    if (columns.length > 0 || this.#peek().text === ",") {
+                        throw new TypeError("RETURNING target.* must be the only returned item");
+                    }
+                    return { returning: "*" };
+                }
+                columns.push(this.#identifier());
+            }
+            else {
+                columns.push(first);
+            }
             if (!this.#punctuation(","))
                 break;
         }
@@ -5609,14 +5677,14 @@ class Parser {
             throw new TypeError("UPDATE assignments must set each column once");
         }
         const predicates = this.#mutationPredicates();
-        return { kind: "update", table, assignments, predicates, ...this.#returningClause() };
+        return { kind: "update", table, assignments, predicates, ...this.#returningClause(table) };
     }
     #deleteStatement() {
         this.#keyword("DELETE");
         this.#keyword("FROM");
         const table = this.#identifier();
         const predicates = this.#mutationPredicates();
-        return { kind: "delete", table, predicates, ...this.#returningClause() };
+        return { kind: "delete", table, predicates, ...this.#returningClause(table) };
     }
     #mutationPredicates() {
         const predicates = [];
@@ -6791,10 +6859,18 @@ class Parser {
                 const all = this.#isKeyword("ALL");
                 this.#keyword(this.#isKeyword("ANY") ? "ANY" : all ? "ALL" : "SOME");
                 this.#expectPunctuation("(");
+                // Kysely's fn.any(subquery) emits PostgreSQL's valid ANY((SELECT ...)) spelling.
+                let wrapped = 0;
+                while (this.#punctuation("("))
+                    wrapped += 1;
                 if (!this.#isKeyword("SELECT")) {
                     throw new TypeError("ANY/ALL take a subquery");
                 }
                 const block = this.#selectBlock("(quantified subquery)");
+                while (wrapped > 0) {
+                    this.#expectPunctuation(")");
+                    wrapped -= 1;
+                }
                 this.#expectPunctuation(")");
                 return {
                     kind: "condition",
@@ -7296,7 +7372,9 @@ class Parser {
             // canonical plan names. ANY_VALUE picks an implementation-dependent row of the group
             // (T626); MIN is one such choice and reuses its accumulator exactly.
             const name = (upper === "ANY_VALUE" ? "MIN" : (functionSpellings.get(upper) ?? upper));
-            if (name === "MINNOW_TUPLE_KEY" || name === "MINNOW_COLLATE") {
+            if (name === "MINNOW_TUPLE_KEY" ||
+                name === "MINNOW_COLLATE" ||
+                name === "MINNOW_SINGLE_VALUE") {
                 throw new TypeError(`Unsupported function: ${identifier}`);
             }
             if (!aggregateNames.has(name) && !scalarFunctionNames.has(name))
@@ -7327,6 +7405,11 @@ class Parser {
                     if (this.#isKeyword("ORDER"))
                         aggregateOrderBy = this.#orderByClause();
                 }
+                else if (name === "JSON_ARRAYAGG") {
+                    args.push(this.#expression());
+                    if (this.#isKeyword("ORDER"))
+                        aggregateOrderBy = this.#orderByClause();
+                }
                 else {
                     args.push(...this.#expressionList());
                 }

package/dist/engine/vector.js

@@ -864,8 +864,11 @@ function bindExpression(expression, sources, aggregateSpecs, aggregateIndexes, m
             argument.vector.kind === "datetime"
             ? { source: argument.source, vector: argument.vector }
             : undefined;
-        const rawNumber = expression.name !== "JSON_ARRAYAGG" &&
-            expression.name !== "STRING_AGG" &&
+        const rawNumber = (expression.name === "COUNT" ||
+            expression.name === "SUM" ||
+            expression.name === "AVG" ||
+            expression.name === "MIN" ||
+            expression.name === "MAX") &&
             argument.kind === "column" &&
             argument.vector.kind === "number"
             ? { source: argument.source, vector: argument.vector }
@@ -1536,6 +1539,12 @@ async function executeBoundPlanWithHashSpill(plan, memory, options) {
                                     (spec.orderBy ?? []).map((order) => encodeSpillValue(asQueryValue(evaluateBatchExpression(plan, order.expression, batch, row)))),
                                 ]);
                             }
+                            else if (spec.name === "JSON_ARRAYAGG" && (spec.orderBy?.length ?? 0) > 0) {
+                                spillRow[`a${String(index)}`] = JSON.stringify([
+                                    encodeSpillValue(asQueryValue(raw ?? null)),
+                                    (spec.orderBy ?? []).map((order) => encodeSpillValue(asQueryValue(evaluateBatchExpression(plan, order.expression, batch, row)))),
+                                ]);
+                            }
                             else {
                                 spillRow[`a${String(index)}`] =
                                     raw === null || raw === undefined ? null : asQueryValue(raw);
@@ -3763,12 +3772,30 @@ function updateAggregatesFromValues(plan, state, values, memory) {
                 throw new Error("Spilled STRING_AGG order is invalid");
             applyAggregateValue(spec, state, index, decoded[0], memory, decoded[1], encodedOrder.map(decodeSpillValue));
         }
+        else if (spec.name === "JSON_ARRAYAGG" &&
+            (spec.orderBy?.length ?? 0) > 0 &&
+            typeof value === "string") {
+            const decoded = JSON.parse(value);
+            if (!Array.isArray(decoded) || decoded.length !== 2 || !Array.isArray(decoded[1])) {
+                throw new Error("Spilled JSON_ARRAYAGG input is invalid");
+            }
+            applyAggregateValue(spec, state, index, decodeSpillValue(decoded[0]), memory, undefined, decoded[1].map(decodeSpillValue));
+        }
         else {
             applyAggregateValue(spec, state, index, value, memory);
         }
     }
 }
 function applyAggregateValue(spec, state, index, value, memory, delimiter, orderValues = []) {
+    if (spec.name === "MINNOW_SINGLE_VALUE") {
+        const count = (state.counts[index] ?? 0) + 1;
+        state.counts[index] = count;
+        if (count > 1) {
+            throw new TypeError(`A scalar subquery returned ${String(count)} rows`);
+        }
+        replaceAggregateValue(state, index, asQueryValue(value ?? null), "Scalar subquery value", memory);
+        return;
+    }
     if (spec.name === "JSON_ARRAYAGG") {
         const member = asQueryValue(value ?? null);
         if (spec.distinct === true && !firstOfItsKind(state, index, member, memory))
@@ -3780,8 +3807,14 @@ function applyAggregateValue(spec, state, index, value, memory, delimiter, order
             list = [];
             lists[index] = list;
         }
-        list.push(member);
-        memory.tally(safeMemorySum(QUERY_REFERENCE_BYTES, queryValuePayloadBytes(member), "JSON_ARRAYAGG member"), "JSON_ARRAYAGG member");
+        const retained = (spec.orderBy?.length ?? 0) === 0
+            ? member
+            : JSON.stringify([
+                encodeSpillValue(member),
+                orderValues.map((orderValue) => encodeSpillValue(orderValue)),
+            ]);
+        list.push(retained);
+        memory.tally(safeMemorySum(QUERY_REFERENCE_BYTES, queryValuePayloadBytes(retained), "JSON_ARRAYAGG member"), "JSON_ARRAYAGG member");
         return;
     }
     if (spec.name === "STRING_AGG") {
@@ -3921,7 +3954,38 @@ function evaluateFinalExpression(plan, expression, group) {
     if (count === 0)
         return null;
     if (expression.name === "JSON_ARRAYAGG") {
-        return preservedJsonDomainValue(jsonConstructor("JSON_ARRAY", required(group.lists, "JSON aggregate list state is missing")[aggregateIndex] ?? []));
+        const retained = required(group.lists, "JSON aggregate list state is missing")[aggregateIndex] ?? [];
+        const orderBy = plan.aggregates[aggregateIndex]?.orderBy ?? [];
+        const members = retained.map((encoded) => {
+            if (orderBy.length === 0)
+                return { value: encoded, order: [] };
+            if (typeof encoded !== "string")
+                throw new Error("JSON_ARRAYAGG member is invalid");
+            const pair = JSON.parse(encoded);
+            if (!Array.isArray(pair) || pair.length !== 2 || !Array.isArray(pair[1])) {
+                throw new Error("JSON_ARRAYAGG member is invalid");
+            }
+            return {
+                value: decodeSpillValue(pair[0]),
+                order: pair[1].map(decodeSpillValue),
+            };
+        });
+        if (orderBy.length > 0) {
+            members.sort((left, right) => {
+                for (const [index, order] of orderBy.entries()) {
+                    const a = left.order[index];
+                    const b = right.order[index];
+                    const placed = nullOrder(a, b, order.nulls, order.direction);
+                    if (placed !== undefined && placed !== 0)
+                        return placed;
+                    const compared = compareValues(a, b);
+                    if (compared !== 0)
+                        return order.direction === "desc" ? -compared : compared;
+                }
+                return 0;
+            });
+        }
+        return preservedJsonDomainValue(jsonConstructor("JSON_ARRAY", members.map(({ value }) => value)));
     }
     if (expression.name === "STRING_AGG") {
         const members = required(group.lists, "STRING_AGG list state is missing")[aggregateIndex] ?? [];

package/dist/plan/model.d.ts

@@ -14,7 +14,9 @@ export interface QueryResult {
 }
 export type BinaryOperator = "+" | "-" | "*" | "/" | "%" | "||";
 export type ComparisonOperator = "=" | "!=" | "<>" | ">" | ">=" | "<" | "<=";
-export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX" | "JSON_ARRAYAGG" | "STRING_AGG";
+export type AggregateName = "COUNT" | "SUM" | "AVG" | "MIN" | "MAX" | "JSON_ARRAYAGG" | "STRING_AGG"
+/** Optimizer-only aggregate that enforces scalar-subquery cardinality. */
+ | "MINNOW_SINGLE_VALUE";
 export type ScalarFunctionName = "ROUND" | "COALESCE" | "DATE_TRUNC" | "DATE_ADD" | "UPPER" | "LOWER" | "LENGTH" | "ABS" | "TRIM" | "LTRIM" | "RTRIM" | "SUBSTR" | "REPLACE" | "INSTR" | "NULLIF" | "GREATEST" | "LEAST" | "FLOOR" | "CEIL" | "MOD" | "POWER" | "SQRT" | "EXTRACT" | "CAST" | "OCTET_LENGTH" | "LPAD" | "RPAD" | "OVERLAY" | "CURRENT_DATE" | "CURRENT_TIMESTAMP" | "LOCALTIME" | "GROUPING" | "JSON_VALUE" | "JSON_QUERY" | "JSON_EXISTS" | "JSON_OBJECT" | "JSON_ARRAY" | "IS_JSON" | "ARRAY"
 /** Optimizer-only, prefix-free equality key for hashable multi-column decorrelation. */
  | "MINNOW_TUPLE_KEY"
@@ -201,6 +203,10 @@ export interface CompiledQuery {
     distinctWildcard?: boolean;
     limitParameter?: number;
     offsetParameter?: number;
+    /** Optimizer-relocated LIMIT placeholders that still need bind-time numeric/range validation. */
+    limitValidationParameters?: number[];
+    /** Optimizer-relocated OFFSET placeholders that still need bind-time numeric/range validation. */
+    offsetValidationParameters?: number[];
     limitWithTies?: boolean;
     parameterCount?: number;
     usesStatementDatetime?: boolean;