@minnowdb/core 0.6.5 → 0.6.6

package/dist/engine/query.js

@@ -9,7 +9,7 @@ import { stringArgument } from "./sql-semantics.js";
 import { jsonArrowStep, jsonAtPath, jsonConstructor, jsonIsValid, parseJsonPath, } from "./sql-json.js";
 import { optimizePlan } from "./optimizer.js";
 import { compareSqlValues as compareValues, compileLikePattern, compileSimilarPattern, encodeSqlEqualityValue, roundSqlNumber, } from "./sql-semantics.js";
-import { arrayDomainValue, boundedJsonText, collatedDomainValue, dateDomainValue, exactNumericBinary, exactNumericValue, externalSqlDomainColumnValue, externalSqlDomainValue, intervalDomainValue, isDateDomainValue, isExactNumeric, isSqlDomainValue, jsonDomainValue, normalizeSqlDomainValue, preservedJsonDomainValue, protectedSqlTextValue, timeDomainValue, uuidDomainValue, } from "./sql-domains.js";
+import { arrayDomainValue, boundedJsonText, collatedDomainValue, concatenatedSqlValue, dateDomainValue, exactNumericAsNumber, exactNumericBinary, exactNumericLiteral, exactNumericValue, externalSqlDomainColumnValue, externalSqlDomainValue, intervalDomainValue, isDateDomainValue, isExactNumeric, isSqlDomainValue, jsonDomainValue, normalizeSqlDomainValue, preservedJsonDomainValue, protectedSqlTextValue, timeDomainValue, uuidDomainValue, } from "./sql-domains.js";
 import { columnarTableFromRows, prepareVectorQuery, } from "./vector.js";
 /** Domain metadata for an execution path that has no catalog-backed type information. */
 export function unknownColumnDomains(columns) {
@@ -81,7 +81,7 @@ export const volatileScalarFunctionNames = new Set([
  * reading, so they are resolved once per execution rather than evaluated per row: every row of
  * one statement sees one instant, both executors agree, and constant folding leaves them alone.
  */
-export const statementDatetimeNames = new Set([
+const statementDatetimeNames = new Set([
     "CURRENT_DATE",
     "CURRENT_TIMESTAMP",
     "LOCALTIME",
@@ -607,7 +607,7 @@ function assertReplacementResultLength(source, search, replacement) {
         throw new RangeError(`REPLACE result exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
     }
 }
-export const dateTruncUnits = new Set([
+const dateTruncUnits = new Set([
     "year",
     "quarter",
     "month",
@@ -637,7 +637,7 @@ const intervalUnits = new Map([
  * rather than converted, because a month is not a fixed number of them: adding one to January 31
  * has to land on the end of February, which only calendar arithmetic can do.
  */
-export function intervalLiteral(text) {
+function intervalLiteral(text) {
     let months = 0;
     let milliseconds = 0;
     let matched = 0;
@@ -663,7 +663,7 @@ export function intervalLiteral(text) {
  * does not exist in the target month clamps to that month's last day, which is what both SQLite
  * and PostgreSQL do with 31 January plus a month.
  */
-export function dateAddValue(value, months, milliseconds) {
+function dateAddValue(value, months, milliseconds) {
     if (value === null || value === undefined)
         return null;
     const calendarDate = isDateDomainValue(value);
@@ -690,7 +690,7 @@ export function dateAddValue(value, months, milliseconds) {
         ? dateDomainValue(dateIsoString(result).slice(0, 10))
         : result;
 }
-export function dateTruncValue(unit, value) {
+function dateTruncValue(unit, value) {
     if (typeof unit !== "string" || !dateTruncUnits.has(unit.toLowerCase())) {
         throw new TypeError("DATE_TRUNC requires a unit of year, quarter, month, week, day, hour, minute, or second");
     }
@@ -888,6 +888,7 @@ export function compileQuery(sql, options = {}) {
     }
     let compiled;
     try {
+        resolvePlanExactNumericConstants(plan);
         compiled = options.optimize === false ? plan : optimizePlan(plan);
     }
     catch (error) {
@@ -995,7 +996,7 @@ export function compileCheckExpression(sql, name) {
     if (hasAggregate(expression) || containsWindow(expression) || containsParameter(expression)) {
         throw new TypeError(`CHECK ${name} takes a row condition over this table's own columns`);
     }
-    return expression;
+    return resolveExactNumericConstants(expression);
 }
 /**
  * Parses and type-checks one catalog default. PostgreSQL defaults are variable-free scalar
@@ -1529,7 +1530,7 @@ export function blockHasSubqueries(plan) {
     return blockHas(plan);
 }
 /** True when any `?`/`$n` placeholder remains anywhere in the expression tree. */
-export function containsParameter(expression) {
+function containsParameter(expression) {
     if (expression.kind === "parameter")
         return true;
     if (expression.kind === "subquery" || expression.kind === "exists") {
@@ -1537,7 +1538,7 @@ export function containsParameter(expression) {
     }
     return childExpressions(expression).some(containsParameter);
 }
-export function blockHasParameters(block) {
+function blockHasParameters(block) {
     if (block.limitParameter !== undefined ||
         block.offsetParameter !== undefined ||
         (block.limitValidationParameters?.length ?? 0) > 0 ||
@@ -2991,12 +2992,188 @@ export function expandFtsColumns(plan, searchableColumnsFor) {
     expandBlock(plan);
     return plan;
 }
+/**
+ * Annotates every `AVG(column)` in this block's expression positions with the argument column's
+ * declared NUMERIC scale, resolved against the given schemas. PostgreSQL floors an AVG's
+ * internal division scale at the summed values' display scale; the canonical NUMERIC encoding
+ * strips trailing fractional zeros, so without the annotation the divide cannot know the digits
+ * a declared scale above its own selection would render, and the display padding would fabricate
+ * zeros where PostgreSQL computes real digits. Runs where the catalog is known, per block —
+ * nested blocks execute through their own schema-aware entry. Copy-on-write: plans without an
+ * AVG pass through untouched, and the input is often the compile cache's own object.
+ */
+export function annotateAvgArgumentScales(plan, schemas) {
+    const containsAvg = (expression) => (expression.kind === "call" && expression.name === "AVG") ||
+        childExpressions(expression).some(containsAvg);
+    const roots = [];
+    forEachBlockExpression(plan, (expression) => roots.push(expression));
+    if (!roots.some(containsAvg))
+        return plan;
+    plan = clonePlanTree(plan);
+    const sources = [plan.base, ...plan.joins];
+    const declaredScale = (reference) => {
+        const parts = reference.split(".");
+        const matches = parts.length === 2
+            ? sources
+                .filter(({ alias }) => alias === parts[0])
+                .flatMap((source) => (schemas.get(source.table) ?? []).filter(({ name }) => name === parts[1]))
+            : sources.flatMap((source) => (schemas.get(source.table) ?? []).filter(({ name }) => name === parts[0]));
+        const domain = matches.length === 1 ? matches[0]?.sqlDomain : undefined;
+        return domain?.kind === "numeric" ? domain.scale : undefined;
+    };
+    const annotate = (expression) => {
+        if (expression.kind === "call" && expression.name === "AVG") {
+            const argument = expression.arguments[0];
+            if (argument?.kind === "column") {
+                const scale = declaredScale(argument.reference);
+                if (scale !== undefined && scale > 0)
+                    expression.avgArgumentScale = scale;
+            }
+        }
+        for (const child of childExpressions(expression))
+            annotate(child);
+    };
+    forEachBlockExpression(plan, annotate);
+    return plan;
+}
+/**
+ * The exact fold of a constant arithmetic subtree, or undefined where none applies. PostgreSQL
+ * types every decimal constant — and every integer constant too large for its integer types —
+ * as NUMERIC, so arithmetic among constants happens in exact decimal space before any float8
+ * context sees the result: `0.1 + 0.2` is exactly 0.3. A subtree folds only when it is
+ * "seeded" by such a constant (one carrying exact digits); pure safe-integer arithmetic keeps
+ * its historical Float64 evaluation, including non-truncating division.
+ */
+function exactConstantFold(expression) {
+    if (expression.kind === "literal") {
+        if (expression.exactText !== undefined) {
+            return { value: exactNumericLiteral(expression.exactText), seeded: true };
+        }
+        const value = expression.value;
+        if (typeof value === "string" && expression.sqlDomain?.kind === "numeric") {
+            return isExactNumeric(value) ? { value, seeded: true } : undefined;
+        }
+        if (typeof value === "number" && Number.isFinite(value))
+            return { value, seeded: false };
+        if (value === null)
+            return { value: null, seeded: false };
+        return undefined;
+    }
+    if (expression.kind !== "binary" || expression.operator === "||")
+        return undefined;
+    const left = exactConstantFold(expression.left);
+    if (left === undefined)
+        return undefined;
+    const right = exactConstantFold(expression.right);
+    if (right === undefined)
+        return undefined;
+    const seeded = left.seeded || right.seeded;
+    if (left.value === null || right.value === null)
+        return { value: null, seeded };
+    const folded = exactNumericBinary(expression.operator, left.value, right.value, 0, false);
+    return folded === undefined ? undefined : { value: folded, seeded };
+}
+/**
+ * Rewrites every seeded constant arithmetic subtree of this expression to its exact fold. A
+ * folded value demotes back to an ordinary number literal when it reads back identically from
+ * a Float64 — PostgreSQL's own cast when a numeric constant meets a float8 operand, and it
+ * keeps every number-typed fast path — and stays a tagged exact-NUMERIC literal when the
+ * number boundary would visibly round it. A fold that overflows its bounds is left unfolded
+ * for execution to report.
+ */
+function resolveExactNumericConstants(expression) {
+    let folded;
+    try {
+        folded = exactConstantFold(expression);
+    }
+    catch {
+        folded = undefined;
+    }
+    if (folded?.seeded === true) {
+        const value = folded.value;
+        if (value === null || typeof value === "number")
+            return { kind: "literal", value };
+        const fits = exactNumericAsNumber(value);
+        if (fits !== undefined)
+            return { kind: "literal", value: fits };
+        return { kind: "literal", value, internalSqlValue: true, sqlDomain: { kind: "numeric" } };
+    }
+    if (expression.kind === "subquery" || expression.kind === "exists") {
+        resolvePlanExactNumericConstants(expression.block);
+        return expression;
+    }
+    if (expression.kind === "window") {
+        return {
+            ...expression,
+            partitionBy: expression.partitionBy.map(resolveExactNumericConstants),
+            orderBy: expression.orderBy.map((order) => ({
+                ...order,
+                expression: resolveExactNumericConstants(order.expression),
+            })),
+            ...(expression.argument === undefined
+                ? {}
+                : { argument: resolveExactNumericConstants(expression.argument) }),
+        };
+    }
+    return mapChildExpressions(expression, resolveExactNumericConstants);
+}
+/** Applies `resolveExactNumericConstants` to every expression of a plan, nested blocks included. */
+function resolvePlanExactNumericConstants(plan) {
+    mapBlockExpressions(plan, resolveExactNumericConstants);
+    forEachNestedBlock(plan, resolvePlanExactNumericConstants);
+}
+/**
+ * The statement counterpart of `resolvePlanExactNumericConstants`: every expression slot a
+ * mutation evaluates later. INSERT VALUES cells are absent because the parser evaluates them
+ * to values on the spot, resolving each expression first.
+ */
+function resolveStatementExactNumericConstants(statement) {
+    const resolve = resolveExactNumericConstants;
+    if (statement.kind === "insert") {
+        const conflict = statement.onConflict;
+        if (conflict?.assignments !== undefined) {
+            for (const assignment of conflict.assignments) {
+                assignment.expression = resolve(assignment.expression);
+            }
+        }
+        if (conflict?.where !== undefined)
+            conflict.where = resolve(conflict.where);
+        return;
+    }
+    if (statement.kind === "update" || statement.kind === "delete") {
+        if (statement.kind === "update") {
+            for (const assignment of statement.assignments) {
+                assignment.expression = resolve(assignment.expression);
+            }
+        }
+        for (const predicate of statement.predicates) {
+            predicate.left = resolve(predicate.left);
+            predicate.right = resolve(predicate.right);
+        }
+        return;
+    }
+    if (statement.kind === "merge") {
+        statement.on = resolve(statement.on);
+        for (const branch of statement.branches) {
+            if (branch.condition !== undefined)
+                branch.condition = resolve(branch.condition);
+            if (branch.action.kind === "update") {
+                for (const assignment of branch.action.assignments) {
+                    assignment.expression = resolve(assignment.expression);
+                }
+            }
+            if (branch.action.kind === "insert") {
+                branch.action.values = branch.action.values.map(resolve);
+            }
+        }
+    }
+}
 /**
  * Aggregates the frame members named by position, for the frames whose rows are not contiguous.
  * EXCLUDE puts a hole in the middle of a frame, which the prefix sums the common path uses
  * cannot represent, so those positions walk their members instead.
  */
-function aggregateWindowMembers(window, values, members) {
+function aggregateWindowMembers(window, values, members, avgScale) {
     const present = members.filter((member) => {
         const value = values[member];
         return value !== null && value !== undefined;
@@ -3026,7 +3203,9 @@ function aggregateWindowMembers(window, values, members) {
                     throw new Error("Exact NUMERIC sum disappeared");
                 total = next;
             }
-            return window.name === "SUM" ? total : exactNumericBinary("/", total, present.length);
+            return window.name === "SUM"
+                ? total
+                : exactNumericBinary("/", total, present.length, avgScale);
         }
         const total = present.reduce((sum, member) => sum + numeric(values[member]), 0);
         return window.name === "SUM" ? total : total / present.length;
@@ -3051,7 +3230,7 @@ function aggregateWindowMembers(window, values, members) {
  * RANGE frames take only UNBOUNDED and CURRENT ROW bounds, where CURRENT ROW spans the peer
  * group. COUNT of an empty frame is 0 and every other aggregate NULL.
  */
-function applyAggregateWindow(rows, indexes, window, samePartition, sameOrderKeys) {
+function applyAggregateWindow(rows, indexes, window, samePartition, sameOrderKeys, avgScale) {
     const frame = window.frame ?? {
         unit: "range",
         start: { kind: "unbounded-preceding" },
@@ -3063,11 +3242,11 @@ function applyAggregateWindow(rows, indexes, window, samePartition, sameOrderKey
         while (end < indexes.length && samePartition(indexes[start] ?? 0, indexes[end] ?? 0)) {
             end += 1;
         }
-        applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKeys, start, end);
+        applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKeys, start, end, avgScale);
         start = end;
     }
 }
-function applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKeys, start, end) {
+function applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKeys, start, end, avgScale) {
     const size = end - start;
     // Peer-group bounds per position; with no OVER ordering the whole partition is one peer group.
     const peerStart = new Array(size).fill(0);
@@ -3198,7 +3377,7 @@ function applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKe
                 if (!dropped)
                     members.push(member);
             }
-            value = aggregateWindowMembers(window, values, members);
+            value = aggregateWindowMembers(window, values, members, avgScale);
             const row = rows[indexes[start + position] ?? -1];
             if (row !== undefined)
                 row[window.alias] = asQueryValue(value);
@@ -3230,7 +3409,7 @@ function applyAggregateWindowPartition(rows, indexes, window, frame, sameOrderKe
             }
             else if (prefixExact !== undefined) {
                 const total = exactNumericBinary("-", prefixExact[high] ?? exactZero, prefixExact[low] ?? exactZero);
-                value = window.name === "SUM" ? total : exactNumericBinary("/", total, nonNull);
+                value = window.name === "SUM" ? total : exactNumericBinary("/", total, nonNull, avgScale);
             }
             else {
                 const total = (prefixSum?.[high] ?? 0) - (prefixSum?.[low] ?? 0);
@@ -3407,7 +3586,13 @@ export function applyWindowFunctions(result, windows, options = {}) {
             continue;
         }
         if (window.name !== "ROW_NUMBER" && window.name !== "RANK" && window.name !== "DENSE_RANK") {
-            applyAggregateWindow(rows, indexes, window, samePartition, sameOrderKeys);
+            // PostgreSQL computes a window AVG's quotient to at least the summed values' display
+            // scale; canonical NUMERIC values no longer carry it, so read the argument column's
+            // declared scale from the inner result the way the summed dscale would have carried it.
+            const argumentDomain = window.name === "AVG" && window.argumentAlias !== undefined
+                ? result.columnDomains[result.columns.indexOf(window.argumentAlias)]
+                : undefined;
+            applyAggregateWindow(rows, indexes, window, samePartition, sameOrderKeys, argumentDomain?.kind === "numeric" ? argumentDomain.scale : undefined);
             continue;
         }
         let rowNumber = 0;
@@ -3819,7 +4004,7 @@ function evaluate(expression, context, group) {
                 if (typeof left !== "string" || typeof right !== "string") {
                     throw new TypeError("|| requires string operands");
                 }
-                return protectedSqlTextValue(String(externalSqlDomainValue(left)) + String(externalSqlDomainValue(right)));
+                return concatenatedSqlValue(left, right);
             }
             const exact = exactNumericBinary(expression.operator, left, right);
             if (exact !== undefined)
@@ -3963,7 +4148,8 @@ function evaluate(expression, context, group) {
                         ? null
                         : (() => {
                             const sum = sumNumericValues(values);
-                            return exactNumericBinary("/", sum, values.length) ?? numeric(sum) / values.length;
+                            return (exactNumericBinary("/", sum, values.length, expression.avgArgumentScale) ??
+                                numeric(sum) / values.length);
                         })();
                 if (expression.name === "MIN")
                     return values.reduce((best, value) => (best === undefined || compareValues(value, best) < 0 ? value : best), undefined);
@@ -4416,6 +4602,11 @@ export function hasAggregate(expression) {
     }
     return childExpressions(expression).some(hasAggregate);
 }
+function hasWindow(expression) {
+    if (expression.kind === "window")
+        return true;
+    return childExpressions(expression).some(hasWindow);
+}
 /** 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);
@@ -5308,6 +5499,14 @@ class Parser {
             },
         };
     }
+    /** A type name's precision, scale, or width: plain digits, as PostgreSQL requires there. */
+    #typeWidth() {
+        const token = this.#take("number");
+        if (!/^\d+$/.test(token.text)) {
+            throw new SqlCompileError(`A type width must be an integer: ${token.text}`, token.start, token.end - token.start);
+        }
+        return Number(token.text);
+    }
     /** A CAST target: the SqlColumnType, or "number-integer" for the truncating integer names. */
     #castTarget() {
         const word = this.#identifier().toUpperCase();
@@ -5315,9 +5514,9 @@ class Parser {
             let precision;
             let scale;
             if (this.#punctuation("(")) {
-                precision = Number(this.#take("number").text);
+                precision = this.#typeWidth();
                 if (this.#punctuation(","))
-                    scale = Number(this.#take("number").text);
+                    scale = this.#typeWidth();
                 else
                     scale = 0;
                 this.#expectPunctuation(")");
@@ -5335,9 +5534,9 @@ class Parser {
         if (mapped === undefined)
             throw new TypeError(`Unsupported CAST target: ${word}`);
         if (this.#punctuation("(")) {
-            this.#take("number");
+            this.#typeWidth();
             if (this.#punctuation(","))
-                this.#take("number");
+                this.#typeWidth();
             this.#expectPunctuation(")");
         }
         const integer = word === "INTEGER" || word === "INT" || word === "BIGINT" || word === "SMALLINT";
@@ -5350,8 +5549,8 @@ class Parser {
             let precision;
             let scale;
             if (this.#punctuation("(")) {
-                precision = Number(this.#take("number").text);
-                scale = this.#punctuation(",") ? Number(this.#take("number").text) : 0;
+                precision = this.#typeWidth();
+                scale = this.#punctuation(",") ? this.#typeWidth() : 0;
                 this.#expectPunctuation(")");
             }
             return {
@@ -5376,7 +5575,7 @@ class Parser {
         }
         // Character widths document intent and do not truncate values.
         if (this.#punctuation("(")) {
-            this.#take("number");
+            this.#typeWidth();
             if (this.#punctuation(",")) {
                 throw new TypeError(`${word} takes one width`);
             }
@@ -5396,6 +5595,7 @@ class Parser {
                 ? this.#updateStatement()
                 : this.#deleteStatement();
         this.#take("eof");
+        resolveStatementExactNumericConstants(statement);
         return statement;
     }
     #insertStatement() {
@@ -5428,7 +5628,9 @@ class Parser {
             };
         }
         if (this.#isKeyword("SELECT")) {
-            const query = optimizePlan(this.#selectBlock("(insert select)"));
+            const insertSource = this.#selectBlock("(insert select)");
+            resolvePlanExactNumericConstants(insertSource);
+            const query = optimizePlan(insertSource);
             if (query.select.some((item) => item.expression.kind === "wildcard")) {
                 throw new TypeError("INSERT ... SELECT requires an explicit select list");
             }
@@ -5691,7 +5893,9 @@ class Parser {
             throw new TypeError("MERGE does not support RETURNING; read the rows back with a SELECT");
         }
         this.#take("eof");
-        return { kind: "merge", table, alias, source, on, branches };
+        const statement = { kind: "merge", table, alias, source, on, branches };
+        resolveStatementExactNumericConstants(statement);
+        return statement;
     }
     #updateStatement() {
         this.#keyword("UPDATE");
@@ -5751,7 +5955,7 @@ class Parser {
         if (hasAggregate(expression) || expressionColumns(expression).length > 0) {
             throw new TypeError(`${label} must be constant expressions`);
         }
-        return asQueryValue(evaluate(expression, {}));
+        return asQueryValue(evaluate(resolveExactNumericConstants(expression), {}));
     }
     #unionMember(sql) {
         if (this.#punctuation("(")) {
@@ -6932,6 +7136,11 @@ class Parser {
                 continue;
             }
             const operator = this.#peek().text;
+            // A bracket after a complete expression is PostgreSQL's array subscript, which has no
+            // other reading in this grammar — name the missing feature instead of "Expected eof".
+            if (operator === "[") {
+                throw new TypeError("Array subscripts are not supported");
+            }
             // || and the JSON arrows share PostgreSQL's loosest "any other operator" level, applying
             // left-to-right to whole arithmetic terms: `'a' || d ->> 'k'` is `('a' || d) ->> 'k'`.
             const precedence = operator === "*" || operator === "/" || operator === "%"
@@ -7021,10 +7230,29 @@ class Parser {
         if (token.kind === "number") {
             this.#index += 1;
             const value = Number(token.text);
-            if (!token.text.includes(".") && !Number.isSafeInteger(value)) {
-                throw new SqlCompileError(`Integer literal is outside the exact safe range: ${token.text}`, token.start, token.end - token.start);
+            // A safe integer spelled as one is exactly itself; every other spelling — a decimal
+            // point, an exponent, or digits beyond 2^53 — is a numeric constant PostgreSQL would
+            // type NUMERIC. Keep its exact digits: as an annotation when the value reads back
+            // identically from a number, or as a tagged exact-NUMERIC literal when it would not.
+            if (!/[.eE]/.test(token.text) && Number.isSafeInteger(value)) {
+                return { kind: "literal", value };
+            }
+            let tagged;
+            try {
+                tagged = exactNumericLiteral(token.text);
             }
-            return { kind: "literal", value };
+            catch (error) {
+                throw new SqlCompileError(error instanceof Error ? error.message : `Invalid number: ${token.text}`, token.start, token.end - token.start);
+            }
+            const fits = exactNumericAsNumber(tagged);
+            if (fits !== undefined)
+                return { kind: "literal", value: fits, exactText: token.text };
+            return {
+                kind: "literal",
+                value: tagged,
+                internalSqlValue: true,
+                sqlDomain: { kind: "numeric" },
+            };
         }
         if (token.kind === "string") {
             this.#index += 1;
@@ -8115,6 +8343,8 @@ export function assembleSelectBlock(parts, nextSequence) {
     if (distinct) {
         if (select.some((item) => hasAggregate(item.expression)))
             throw new TypeError("SELECT DISTINCT cannot be combined with aggregate functions");
+        if (select.some((item) => hasWindow(item.expression)))
+            throw new TypeError("SELECT DISTINCT cannot be combined with window functions");
         if (groupBy.length > 0)
             throw new TypeError("SELECT DISTINCT cannot be combined with GROUP BY");
         if (having.length > 0)
@@ -8193,7 +8423,7 @@ export function assembleSelectBlock(parts, nextSequence) {
  * over those same columns provides the deduplication through the grouped executor. Runs
  * exactly once per execution entry, like MATCH(*) expansion.
  */
-export function expandDistinctWildcard(plan, columnsOf) {
+function expandDistinctWildcard(plan, columnsOf) {
     if (plan.distinctWildcard !== true)
         return plan;
     const shaped = [plan.base, ...plan.joins].map((source) => ({
@@ -8285,7 +8515,7 @@ export function planHasSourceColumnAliases(plan) {
  * scan cannot know whether the next row ties — and the ordered result is trimmed here: rows up
  * to the limit, plus every following row equal to the last one on all ORDER BY columns.
  */
-export function withTiesPlan(plan) {
+function withTiesPlan(plan) {
     // Ordering by an expression or an unselected column wraps the real block in a projection that
     // hides the sort column. The tie test needs that column, so the inner block runs and the
     // projection is applied after trimming instead of before.
@@ -8472,7 +8702,7 @@ export function expandSourceColumnAliases(plan, columnsOf) {
  * one source, and `alias.column` when it reads several, so two sources cannot collide.
  * Runs once per execution entry, like MATCH(*) and DISTINCT * expansion.
  */
-export function expandQualifiedWildcards(plan, columnsOf) {
+function expandQualifiedWildcards(plan, columnsOf) {
     const qualified = (block) => {
         if (block.select.some((item) => item.expression.kind === "wildcard" && item.expression.table))
             return true;
@@ -8748,7 +8978,7 @@ function jsonTableColumnValue(column, value) {
     }
     return date;
 }
-export function timestampLiteral(text) {
+function timestampLiteral(text) {
     const trimmed = text.trim();
     const match = /^(\d{4}-\d{2}-\d{2})(?:[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?))?(Z|[+-]\d{2}:?\d{2})?$/.exec(trimmed);
     if (match === null)
@@ -8922,13 +9152,14 @@ function defaultAlias(expression) {
     return "expression";
 }
 /**
- * Whether a numeric literal's digits are well formed: at most one decimal point (radix 10 only)
- * and underscores only between digits, never leading, trailing, or doubled (T662).
+ * Whether a numeric literal's digits are well formed: at most one decimal point and an optional
+ * exponent (radix 10 only), and underscores only between digits, never leading, trailing, or
+ * doubled (T662). Exponent digits are plain, as in PostgreSQL.
  */
 function validNumericLiteral(text, radix) {
     const digits = radix === 16 ? "0-9a-fA-F" : radix === 8 ? "0-7" : radix === 2 ? "01" : "0-9";
     const group = `[${digits}]+(?:_[${digits}]+)*`;
-    const pattern = radix === 10 ? `^${group}(?:\\.${group})?$` : `^${group}$`;
+    const pattern = radix === 10 ? `^${group}(?:\\.${group})?(?:[eE][+-]?\\d+)?$` : `^${group}$`;
     return new RegExp(pattern).test(text);
 }
 function tokenize(sql) {
@@ -8986,6 +9217,16 @@ function tokenize(sql) {
             // T662: underscores may separate digits.
             while (index < sql.length && /[\d._]/.test(sql[index] ?? ""))
                 index += 1;
+            // Scientific notation: an exponent marker joins the token only when digits follow, so
+            // `1e2` is the numeric constant 100 while `SELECT 1 e` still reads `e` as an alias.
+            if (/[eE]/.test(sql[index] ?? "")) {
+                const signed = /[+-]/.test(sql[index + 1] ?? "") ? 1 : 0;
+                if (/\d/.test(sql[index + 1 + signed] ?? "")) {
+                    index += 2 + signed;
+                    while (index < sql.length && /\d/.test(sql[index] ?? ""))
+                        index += 1;
+                }
+            }
             const text = sql.slice(start, index);
             if (!validNumericLiteral(text, 10))
                 throw new SqlCompileError(`Invalid number: ${text}`, start, index - start);

package/dist/engine/result-wire.d.ts

@@ -13,7 +13,7 @@ import type { QueryResult, QueryRow, QueryValue } from "./query.js";
  * a byte mask, and a column name like `__proto__` comes back as the own property the engine
  * defined — never as a prototype assignment.
  */
-export type WireResultColumn = {
+type WireResultColumn = {
     kind: "number";
     values: Float64Array;
     nulls?: Uint8Array;
@@ -67,3 +67,4 @@ export declare function encodeQueryResult(result: QueryResult): EncodedQueryResu
 export declare function encodeQueryRows(rows: readonly QueryRow[]): EncodedQueryResult;
 export declare function decodeQueryResult(payload: unknown): QueryResult;
 export declare function isWireQueryResult(value: unknown): value is WireQueryResult;
+export {};

package/dist/engine/schema.d.ts

@@ -55,6 +55,17 @@ export declare function foreignKeyName(tableName: string, columnName: string): s
 export type HasDefault<TValue> = TValue & {
     readonly __minnowHasDefault?: true;
 };
+/**
+ * A JSON column's select value carrying a declared document shape. The value is still JSON
+ * text — the brand is an optional phantom property, so plain strings stay assignable in both
+ * directions — and adapters read the shape to offer typed traversal. The tuple wrapper keeps
+ * `never` and union shapes intact through inference.
+ */
+export type JsonShape<TShape> = string & {
+    readonly __minnowJsonShape?: readonly [TShape];
+};
+/** A JSON column without a declared shape selects as exactly `string`, with no brand. */
+type JsonColumnValue<TShape> = [TShape] extends [never] ? string : JsonShape<TShape>;
 export interface ColumnBuilder<TValue extends SchemaValue, TNullable extends boolean, TUnique extends boolean = false, THasDefault extends boolean = false, TInput extends SchemaValue = TValue, TDomain extends SqlDomain["kind"] | undefined = undefined, TGenerated extends boolean = false> {
     readonly kind: "column";
     readonly type: SchemaColumnType;
@@ -179,8 +190,13 @@ export declare const column: {
         precision?: number;
         scale?: number;
     }) => ColumnBuilder<string, false, false, false, string | number, "numeric", false>;
-    json: () => ColumnBuilder<string, false, false, false, string, "json", false>;
-    jsonb: () => ColumnBuilder<string, false, false, false, string, "jsonb", false>;
+    /**
+     * JSON text at the JavaScript boundary. Optionally declare the document's shape —
+     * `column.json<{ name: string }>()` — for adapters to type `->`/`->>` traversal; the runtime
+     * value stays JSON text either way.
+     */
+    json: <TShape = never>() => ColumnBuilder<JsonColumnValue<TShape>, false, false, false, string, "json", false>;
+    jsonb: <TShape = never>() => ColumnBuilder<JsonColumnValue<TShape>, false, false, false, string, "jsonb", false>;
     uuid: () => ColumnBuilder<string, false, false, false, string, "uuid", false>;
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
     date: () => ColumnBuilder<string, false, false, false, string, "date", false>;

package/dist/engine/schema.js

@@ -228,8 +228,17 @@ export const column = {
         const sqlDomain = validateSqlDomain({ kind: "numeric", ...options }, "numeric column");
         return createColumn("string", { sqlDomain });
     },
-    json: () => createColumn("string", { sqlDomain: { kind: "json" } }),
-    jsonb: () => createColumn("string", { sqlDomain: { kind: "jsonb" } }),
+    /**
+     * JSON text at the JavaScript boundary. Optionally declare the document's shape —
+     * `column.json<{ name: string }>()` — for adapters to type `->`/`->>` traversal; the runtime
+     * value stays JSON text either way.
+     */
+    json: () => createColumn("string", {
+        sqlDomain: { kind: "json" },
+    }),
+    jsonb: () => createColumn("string", {
+        sqlDomain: { kind: "jsonb" },
+    }),
     uuid: () => createColumn("string", { sqlDomain: { kind: "uuid" } }),
     /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
     date: () => createColumn("string", { sqlDomain: { kind: "date" } }),